AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Random PIN Generator Agent Guide

Agent guide for unbiased crypto-backed numeric PIN generation.

AGENTS.md

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

Project overview

This guide covers src/tools/random-pin-generator/index.ts. The tool generates random digits with Uint8Array crypto bytes, rejects byte values outside the largest multiple of ten below 256, and builds a requested number of fixed-length numeric PIN strings.

Primary source files

  • src/tools/random-pin-generator/index.ts defines meta, private randomDigit, and randomPin.
  • src/tools/random-pin-generator/index.test.ts covers count, digit length, numeric-only output, zero count, fixed-length strings, and all digits appearing in a large sample.
  • src/tools/random-pin-generator/Body.astro owns browser controls.
  • src/tools/random-pin-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 rejection sampling in randomDigit to avoid modulo bias.
  • Return numeric strings only.
  • Respect requested digits and count as currently implemented.
  • Return an empty array when count is zero.
  • Do not store or transmit generated PINs.
  • If length or count clamps are added, update tests and copy together.
  • Do not reuse generated PINs across requests.

Testing

Test count, fixed digit length, numeric-only output, zero count, one-digit large sample coverage, long PINs, negative or zero digit behavior if constrained, and future clamps.

PR checklist

  • npm test passes for random-pin-generator.
  • Web Crypto remains the random source.
  • Input lists or generated values stay browser-local.
  • Current clamping and empty-input semantics remain documented.