AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools World Clock Agent Guide

Agent guide for formatting current time and UTC offset labels for default world clock zones.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools World Clock in the alexandrai-tools project.

Project overview

This guide covers src/tools/world-clock/index.ts. The tool defines default city and IANA zone entries, formats a fixed epoch in any zone as HH:MM:SS using Intl.DateTimeFormat, and derives a normalized UTC offset label from shortOffset parts.

Primary source files

  • src/tools/world-clock/index.ts defines meta, ZoneEntry, DEFAULT_ZONES, formatInZone, and utcOffsetLabel.
  • src/tools/world-clock/index.test.ts covers UTC, New York DST, Tokyo, Kolkata, two-digit hour formatting, UTC labels, positive offsets, and negative offsets.
  • src/tools/world-clock/Body.astro owns live ticking and display.
  • src/tools/world-clock/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

  • Keep DEFAULT_ZONES as explicit label and IANA pairs.
  • Use Intl.DateTimeFormat rather than manual offset math.
  • Format time with en-GB, two-digit hour, minute, second, and hour12 false.
  • Normalize GMT prefixes to UTC in offset labels.
  • Pad one-digit signed offset hours when a minute component is present.
  • Let Intl throw for invalid zones unless UI validation wraps it.
  • If date display is added, keep time-only formatting tests stable.

Testing

Test fixed epochs in UTC, New York, Tokyo, Kolkata, London, and Sydney, midnight formatting, DST offsets, UTC offset labels, invalid zone behavior, default zone order, and live UI updates separately from pure helpers.

PR checklist

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