AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Event Time Zone Converter Agent Guide

Agent guide for converting an event wall-clock time from one IANA zone into another.

AGENTS.md

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

Project overview

This guide covers src/tools/event-time-zone-converter/index.ts. The tool defines major city zones, parses event date and HH:MM time in a source IANA zone, converts that wall-clock time to a UTC epoch with a two-pass Intl loop, then formats the target zone date, time, and normalized offset.

Primary source files

  • src/tools/event-time-zone-converter/index.ts defines meta, MAJOR_CITIES, EventConvertResult, convertInstant, wallClockToEpoch, normaliseOffset, and convertEventTime.
  • src/tools/event-time-zone-converter/index.test.ts covers New York to London, New York to Tokyo, summer DST, invalid target zone, and invalid date format.
  • src/tools/event-time-zone-converter/Body.astro owns browser controls.
  • src/tools/event-time-zone-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 zone identifiers for source and target zones.
  • Accept date as YYYY-MM-DD and time as HH:MM.
  • Return an invalid date or time error when source wall-clock parsing fails.
  • Return unknown-zone errors from target conversion when Intl rejects the target zone.
  • Keep the two-pass wall-clock correction for DST-aware conversion.
  • Normalize offsets from GMT format to UTC, +HH:MM, or -HH:MM style.
  • If source-zone errors need distinct messages, separate them without changing valid conversion output.

Testing

Test winter and summer conversions, same-zone conversion, cross-date conversions, invalid date, invalid time, invalid source zone, invalid target zone, offset labels, major city list consistency, and DST transition edge cases.

PR checklist

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