AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Password Generator Agent Guide

Agent guide for cryptographic password generation, ambiguous-character filtering, and entropy estimation.

AGENTS.md

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

Project overview

This guide covers src/tools/password-generator/index.ts. The tool builds a character pool from selected lowercase, uppercase, digit, and symbol sets, can remove ambiguous characters, clamps output length, uses crypto.getRandomValues, applies rejection sampling to avoid modulo bias, and estimates password strength from observed character classes.

Primary source files

  • src/tools/password-generator/index.ts defines meta, PwOptions, generatePassword, StrengthResult, and estimateStrength.
  • src/tools/password-generator/index.test.ts covers length, selected sets, fallback pool, clamping, ambiguous-character removal, uppercase exclusion, and strength labels.
  • src/tools/password-generator/Body.astro owns browser controls and generated output.
  • src/tools/password-generator/i18n.ts owns localized page copy.
  • src/lib/tools.ts auto-discovers metadata.

Setup commands

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

Change rules

  • Use crypto.getRandomValues and keep rejection sampling to avoid modulo bias.
  • Clamp requested length to the established minimum and maximum bounds.
  • Fall back to lowercase when no character set is selected.
  • After ambiguous-character filtering, keep a non-empty fallback pool.
  • Keep symbol set changes synchronized with estimateStrength and tests.
  • Do not store, transmit, log, or reuse generated passwords.
  • Do not present entropy estimates as a substitute for unique-password and password-manager guidance.

Testing

Test all character sets, each single-set mode, no-set fallback, lower and upper length clamps, ambiguous filtering, excluded uppercase and symbols, rejection-sampling output shape, entropy ordering, labels, and empty strength input.

PR checklist

  • npm test passes for password-generator.
  • Generated output respects selected character sets.
  • No Math.random is introduced.
  • Generated passwords are not persisted or sent anywhere.