AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Countdown Timer Agent Guide

Agent guide for formatting seconds as HH:MM:SS and parsing seconds, M:S, or H:M:S timer input.

AGENTS.md

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

Project overview

This guide covers src/tools/countdown-timer/index.ts. The tool formats non-negative floored seconds as HH:MM:SS, parses plain integer seconds, parses M:S and H:M:S colon formats, and returns NaN for empty or malformed input.

Primary source files

  • src/tools/countdown-timer/index.ts defines meta, formatDuration, and parseDuration.
  • src/tools/countdown-timer/index.test.ts covers formatting zero, seconds, minutes, hours, negative clamp, padding, plain seconds parsing, M:S parsing, H:M:S parsing, zero parts, empty input, non-numeric parts, and too many colons.
  • src/tools/countdown-timer/Body.astro owns timer state and alerts.
  • src/tools/countdown-timer/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

  • Clamp negative formatted durations to zero.
  • Floor fractional total seconds before formatting.
  • Pad hours, minutes, and seconds to two digits.
  • Parse plain digits as seconds.
  • Parse two colon-separated parts as M:S.
  • Parse three colon-separated parts as H:M:S.
  • Return NaN for empty, malformed, non-numeric, or overlong colon input.

Testing

Test formatting zero, negative, fractional, seconds-only, minutes, hours, large hour counts, parsing plain seconds, M:S, H:M:S, zero parts, whitespace, empty input, bad tokens, and too many separators.

PR checklist

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