AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Countdown To Date Agent Guide

Agent guide for breaking an absolute millisecond difference into days, hours, minutes, seconds, and past state.

AGENTS.md

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

Project overview

This guide covers src/tools/countdown-to-date/index.ts. The tool compares targetEpochMs and nowEpochMs, records whether the target is in the past, uses the absolute difference floored to whole seconds, and decomposes it into days, hours, minutes, and seconds.

Primary source files

  • src/tools/countdown-to-date/index.ts defines meta, CountdownResult, and diffToTarget.
  • src/tools/countdown-to-date/index.test.ts covers future and past countdowns, exactly one day, same instant, and hour-minute-second decomposition.
  • src/tools/countdown-to-date/Body.astro owns browser controls.
  • src/tools/countdown-to-date/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

  • Compute diff as targetEpochMs minus nowEpochMs.
  • Set past to true only when diff is less than zero.
  • Use absolute difference for displayed duration components.
  • Floor milliseconds to whole seconds.
  • Use 86400 seconds per day.
  • Return zero components and past false for the same instant.
  • Keep timezone and date input parsing in the UI layer unless pure logic is expanded deliberately.

Testing

Test future targets, past targets, same instant, exact day boundaries, hour-minute-second decomposition, sub-second flooring, negative differences, and UI date parsing around local timezone boundaries.

PR checklist

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