AGENTS.md

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

Project overview

This guide covers src/tools/date-add/index.ts. The tool parses YYYY-MM-DD text, validates finite amounts, uses UTC epoch arithmetic for days and weeks, uses calendar arithmetic for months and years, and clamps overflowing days to the last day of the target month.

Primary source files

• src/tools/date-add/index.ts defines meta, DateUnit, DateAddResult, parseISO, pad2, and addToDate.
• src/tools/date-add/index.test.ts covers days, weeks, months, years, leap days, month-end clamps, year boundaries, invalid date format, and non-finite amount errors.
• src/tools/date-add/Body.astro owns browser controls.
• src/tools/date-add/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

• Accept only YYYY-MM-DD format in pure parsing.
• Return structured errors for bad date format and non-finite amounts.
• Use UTC arithmetic for day and week offsets.
• Treat weeks as seven days.
• Normalize month overflow and underflow before clamping the day.
• Clamp month and year results to the last valid day of the target month.
• If stricter date validation is added, test invalid month and day overflow explicitly.

Testing

Test positive and negative days, zero offset, week offsets, leap-year and non-leap-year February, Jan 31 month additions, month subtraction across years, year addition and subtraction, Feb 29 to non-leap year, invalid format, non-finite amount, and invalid calendar dates if validation changes.

PR checklist

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