AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Timestamp Converter Agent Guide

Agent guide for Unix timestamp unit detection, from-Unix conversion, and date-string to Unix conversion.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Timestamp Converter in the alexandrai-tools project.

Project overview

This guide covers src/tools/timestamp-converter/index.ts. The tool detects seconds versus milliseconds by absolute magnitude, converts Unix values to ISO and UTC strings, returns both seconds and milliseconds, and parses trimmed date strings through the JavaScript Date constructor.

Primary source files

  • src/tools/timestamp-converter/index.ts defines meta, TimestampUnit, FromUnixResult, ToUnixResult, detectUnit, fromUnix, and toUnix.
  • src/tools/timestamp-converter/index.test.ts covers unit detection, epoch zero, known seconds and milliseconds values, auto detection, UTC output, NaN input, ISO parsing, invalid input, empty input, and ISO echoing.
  • src/tools/timestamp-converter/Body.astro owns browser controls.
  • src/tools/timestamp-converter/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

  • Treat absolute values greater than or equal to 1e12 as milliseconds.
  • Treat smaller absolute values as seconds.
  • Use explicit unit when provided instead of auto detection.
  • Return ok false for invalid Date results.
  • Use Math.trunc for unixSeconds.
  • Return ok false for empty date-string input.
  • If date parsing becomes stricter, prefer ISO-first validation and update copy.

Testing

Test detectUnit thresholds, negative timestamps, epoch zero, known seconds and milliseconds values, auto mode, invalid numeric input, ISO string parsing, invalid strings, empty strings, timezone-bearing strings, truncation of milliseconds, and local date-string ambiguity if UI accepts it.

PR checklist

  • npm test passes for timestamp-converter.
  • Timezone, date, and cycle assumptions remain documented.
  • Invalid-input behavior is covered by tests.
  • UI labels, metadata, and pure logic stay in sync.