AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools UUID Generator Agent Guide

Agent guide for Web Crypto UUID v4 generation, count clamping, and UUID validation.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools UUID Generator in the alexandrai-tools project.

Project overview

This guide covers src/tools/uuid-generator/index.ts. The tool uses globalThis.crypto.randomUUID for one UUID v4, generates batches through generateMany with a clamp from one to one thousand, and validates standard UUID strings with a case-insensitive regular expression.

Primary source files

  • src/tools/uuid-generator/index.ts defines meta, generateUuidV4, generateMany, and isValidUuid.
  • src/tools/uuid-generator/index.test.ts covers v4 format, uniqueness across a small sample, count clamping, and validation.
  • src/tools/uuid-generator/Body.astro owns the browser count controls and output.
  • src/tools/uuid-generator/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

  • Keep UUID generation on Web Crypto instead of Math.random.
  • Preserve generateMany clamping to avoid oversized browser work.
  • Keep isValidUuid version-agnostic unless a new explicit v4 validator is added.
  • Do not guarantee global uniqueness beyond standard UUID probability semantics.
  • Do not add server-side UUID generation for this browser utility.
  • If fallback generation is needed for unsupported browsers, use crypto.getRandomValues and test version and variant bits.
  • Avoid publishing generated UUID batches as meaningful identifiers.

Testing

Test v4 format, variant bits, uniqueness across a bounded sample, lower clamp, upper clamp, validation true for generated output, validation false for malformed strings, and any fallback implementation.

PR checklist

  • npm test passes for uuid-generator.
  • Generation uses Web Crypto APIs.
  • Batch count stays clamped.
  • Validation and generation semantics are not conflated.