AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Days Until in the alexandrai-tools project.

Project overview

This guide covers src/tools/days-until/index.ts. The tool converts two YYYY-MM-DD strings to UTC epoch days and returns target minus start as a signed whole-day count. Positive values mean the target is after the start and negative values mean it is before the start.

Primary source files

• src/tools/days-until/index.ts defines meta, DaysUntilResult, isoToEpochDay, and daysBetween.
• src/tools/days-until/index.test.ts covers same date, future targets, past targets, month boundaries, leap years, non-leap years, year boundaries, invalid formats, and full-year spans.
• src/tools/days-until/Body.astro owns browser controls.
• src/tools/days-until/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 UTC epoch-day arithmetic to avoid local timezone drift.
• Return a signed day count as target minus start.
• Return structured errors for non-matching date formats.
• Do not silently use the current date inside pure daysBetween.
• Preserve whole-day semantics rather than millisecond countdown semantics.
• Document that regex-only parsing may allow overflow dates unless stricter validation is added.
• If strict date validity is added, cover month and day overflow in tests.

Testing

Test zero days, positive days, negative days, leap-year February, non-leap February, month and year boundaries, full non-leap year, full leap year, invalid formats, overflow date policy, and UI defaults for start date.

PR checklist

• npm test passes for days-until.
• Timezone, UTC, and rounding behavior remain documented.
• Invalid-input behavior is covered by tests.
• UI labels, metadata, and pure date or time logic stay in sync.