AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Date Difference Agent Guide

Agent guide for order-independent calendar date differences plus total UTC day counts.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Date Difference in the alexandrai-tools project.

Project overview

This guide covers src/tools/date-difference/index.ts. The tool parses YYYY-MM-DD text, calculates total days from UTC epoch-day values, sorts inputs internally, then computes non-negative years, months, and days with a month-borrow algorithm.

Primary source files

  • src/tools/date-difference/index.ts defines meta, DateDiffResult, isoToEpochDay, parseISO, and dateDiff.
  • src/tools/date-difference/index.test.ts covers same date, leap years, month and day differences, month borrow, input order independence, invalid format, and year-crossing borrow.
  • src/tools/date-difference/Body.astro owns browser controls.
  • src/tools/date-difference/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

  • Return structured errors for non-matching YYYY-MM-DD input.
  • Compute totalDays from UTC epoch days.
  • Sort inputs internally so output is order-independent.
  • Return non-negative years, months, and days.
  • When days are negative, borrow from the previous calendar month of the later date.
  • When months are negative, borrow from years and add twelve months.
  • If signed differences are added, expose them as a separate option rather than changing the default.

Testing

Test identical dates, simple year spans, leap-year February, non-leap February, month borrow, year-boundary borrow, swapped inputs, invalid format, totalDays consistency, and any future signed-difference option.

PR checklist

  • npm test passes for date-difference.
  • 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.