AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Cron Expression Agent Guide

Agent guide for the Cron Expression Explainer parser, description builder, and next-run preview.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Cron Expression in the alexandrai-tools project.

Project overview

This guide covers src/tools/cron-expression/index.ts. The tool parses standard five-field cron expressions, describes allowed sets for minute, hour, day of month, month, and day of week, and computes bounded future UTC run timestamps by scanning minute by minute from a starting time.

Primary source files

  • src/tools/cron-expression/index.ts defines meta, CronResult, field parsing, explainCron, and nextRuns.
  • src/tools/cron-expression/index.test.ts covers common descriptions, invalid field count, out-of-range values, empty expressions, and nextRuns.
  • src/tools/cron-expression/Body.astro owns the browser form and display.
  • src/tools/cron-expression/i18n.ts owns localized copy.
  • src/lib/tools.ts auto-discovers metadata for routing and hub grouping.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Keep support scoped to five-field cron syntax unless parser, copy, and tests are expanded together.
  • Reject empty input, wrong field counts, invalid ranges, invalid steps, and out-of-range values with useful errors.
  • Preserve numeric ranges: minutes 0 through 59, hours 0 through 23, day of month 1 through 31, month 1 through 12, day of week 0 through 6.
  • Keep nextRuns UTC-based and bounded by the existing one-year scan cap to avoid infinite work.
  • Prevent description regressions for step expressions, exact hour and minute expressions, month names, and day names.
  • Do not add server-side schedule execution; this is an explainer and preview utility.
  • If adding named cron aliases, normalize them before field parsing and test each alias.

Testing

Test wildcard, step, list, range, exact time, invalid step, invalid range, impossible field count, next-run count, UTC rollover, and no-match bounded scans. Include day-of-week and month-name display tests when copy changes.

PR checklist

  • npm test passes for cron-expression.
  • Invalid expressions return ok false instead of throwing.
  • nextRuns never loops without a cap.
  • UI copy still states the five-field scope.