AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Timezone Converter Agent Guide

Agent guide for IANA time zone conversion using Intl formatting and wall-clock to epoch correction.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Timezone Converter in the alexandrai-tools project.

Project overview

This guide covers src/tools/timezone-converter/index.ts. The tool keeps a curated IANA zone list, converts UTC epoch milliseconds into date, time, and normalized offset strings with Intl.DateTimeFormat, and maps wall-clock date plus HH:MM input in a source zone to a UTC epoch value through a two-pass Intl correction loop.

Primary source files

  • src/tools/timezone-converter/index.ts defines meta, COMMON_ZONES, ConvertedTime, convertInstant, wallClockToEpoch, and normaliseOffset.
  • src/tools/timezone-converter/index.test.ts covers UTC, New York, London, Kolkata, Tokyo, Los Angeles, date output, unknown zones, non-finite epochs, and wall-clock round trips.
  • src/tools/timezone-converter/Body.astro owns browser controls.
  • src/tools/timezone-converter/i18n.ts owns localized copy.
  • src/lib/tools.ts registers metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Use IANA time zone identifiers.
  • Use Intl.DateTimeFormat for timezone-aware formatting.
  • Return structured errors for non-finite epoch values.
  • Return structured errors for unknown target zones.
  • Accept YYYY-MM-DD and HH:MM formats in wallClockToEpoch.
  • Keep the two-pass offset correction loop for common DST cases.
  • If ambiguous or nonexistent DST wall-clock times are handled explicitly, document the resolution policy and add tests.

Testing

Test fixed UTC instants across UTC, America/New_York, Europe/London, Asia/Kolkata, Asia/Tokyo, America/Los_Angeles, invalid zones, non-finite epochs, invalid date and time formats, DST summer and winter offsets, and wall-clock round trips.

PR checklist

  • npm test passes for timezone-converter.
  • Timezone, date, and cycle assumptions remain documented.
  • Invalid-input behavior is covered by tests.
  • UI labels, metadata, and pure logic stay in sync.