AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Secret Santa in the alexandrai-tools project.

Project overview

This guide covers src/tools/secret-santa. assign requires at least two unique names, uses crypto.getRandomValues inside a Sattolo-style shuffle where the swap index excludes the current index, and maps each original giver to the shuffled receiver at the same position so no participant receives themselves.

Primary source files

• src/tools/secret-santa/index.ts defines meta, Assignment, cryptoShuffle, and assign.
• src/tools/secret-santa/index.test.ts covers every giver once, every receiver once, no self-assignment, too-few names, repeated random runs, and duplicate-name errors.
• src/tools/secret-santa/Body.astro owns name input and assignment display.
• src/tools/secret-santa/i18n.ts owns localized labels.
• src/lib/tools.ts registers the tool metadata.

Setup commands

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

Change rules

• Throw when fewer than two names are supplied.
• Throw when duplicate names are supplied.
• Use crypto.getRandomValues for shuffle entropy.
• Keep the Sattolo swap index below the current index.
• Return one assignment per input name.
• Ensure each name appears exactly once as giver and once as receiver.
• Do not persist or upload participant names.

Testing

Test too-few names, duplicates, giver coverage, receiver coverage, no self-assignment across repeated runs, deterministic test seams if added, whitespace normalization, and privacy copy.

PR checklist

• npm test passes for secret-santa.
• Date, random, or hash behavior is documented exactly as implemented.
• Health outputs remain framed as estimates, not medical decisions.
• UI labels, validation, and pure helper tests stay aligned.