AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Time Duration Calculator Agent Guide

Agent guide for HH:MM parsing, duration formatting, and midnight-crossing time-of-day differences.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Time Duration Calculator in the alexandrai-tools project.

Project overview

This guide covers src/tools/time-duration-calculator/index.ts. The tool parses H:MM or HH:MM into minutes since midnight, formats minute durations as hours and minutes, and calculates elapsed time between start and end. When end is less than or equal to start, it treats the result as crossing midnight and adds twenty-four hours.

Primary source files

  • src/tools/time-duration-calculator/index.ts defines meta, DurationResult, parseHHMM, formatResult, and calcDuration.
  • src/tools/time-duration-calculator/index.test.ts covers parsing, invalid times, formatting, same-day duration, crossing midnight, equal times, invalid start and end, and exact day boundaries.
  • src/tools/time-duration-calculator/Body.astro owns browser controls.
  • src/tools/time-duration-calculator/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 H:MM and HH:MM only.
  • Reject hours greater than twenty-three and minutes greater than fifty-nine.
  • Format zero minutes as 0 min.
  • Use hours-only output when minutes are zero.
  • Use minutes-only output when hours are zero.
  • Treat end less than or equal to start as crossing midnight.
  • Document that equal start and end currently returns twenty-four hours, not zero.

Testing

Test standard parsing, single-digit hours, invalid formats, invalid ranges, minutes-only formatting, hours-only formatting, mixed formatting, same-day duration, midnight crossing, equal times as twenty-four hours, invalid start, invalid end, and exact end-of-day values.

PR checklist

  • npm test passes for time-duration-calculator.
  • 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.