AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Username Generator Agent Guide

Agent guide for crypto-backed random and word-style username generation with uniqueness attempts.

AGENTS.md

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

Project overview

This guide covers src/tools/username-generator/index.ts. The tool uses crypto-backed unbiased random indexes, supports word and random styles, combines adjective, noun, and two or three digits for word usernames, generates alphanumeric random usernames, enforces maxLen by slicing or length caps, and attempts to keep outputs unique with a seen set.

Primary source files

  • src/tools/username-generator/index.ts defines meta, UsernameOptions, word lists, CHARS, randomIndex, randomChar, randomWord, randomNumber, makeWordUsername, makeRandomUsername, and generateUsernames.
  • src/tools/username-generator/index.test.ts covers requested counts, default style, no spaces, maxLen, alphanumeric output, and reasonable-count uniqueness.
  • src/tools/username-generator/Body.astro owns browser controls.
  • src/tools/username-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

  • Use crypto.getRandomValues for random indexes.
  • Keep randomIndex rejection sampling to avoid modulo bias.
  • Default style is word.
  • Default maxLen is twenty.
  • Word style concatenates adjective, noun, and two or three digits.
  • Random style uses lowercase letters and digits.
  • Stop uniqueness attempts after count times twenty attempts.

Testing

Test word style, random style, default style, maxLen, small maxLen boundaries, count zero if UI allows it, uniqueness attempts, alphanumeric output, no spaces, and randomIndex behavior.

PR checklist

  • npm test passes for username-generator.
  • Generated output shape, escaping, and invalid-input behavior remain documented.
  • Browser-local generation stays free of hidden network calls.
  • UI labels, metadata, and tests update together for behavior changes.