hook-author

Hook Author — Hookstack

Mission

Créer ou modifier un hook du catalogue. Un hook est un script Node .mjs branché sur le cycle de vie de l'agent (PreToolUse, PostToolUse, SessionStart, Stop…). Portable multi-agent (Claude Code / Codex / Copilot) — le code .mjs est identique, seul le format de config diffère.

Source de vérité (à retenir)

Le .mjs sur disque est la source de vérité du code. registry/registry.json est la source des métadonnées ; son champ code_snippet est dérivé du .mjs par le sync — jamais édité à la main.

Pattern OBLIGATOIRE — run() + garde + injection de dépendances

Tout hook expose une fonction pure qui contient la logique et retourne son résultat, sans toucher à stdin/stdout/process.exit. Les effets de bord (execSync, fs, fetch, process.platform, horloge) passent par des dépendances injectées avec valeurs par défaut réelles.

#!/usr/bin/env node
// @hookstack <slug>   // injected automatiquement par le sync — ne pas éditer à la main

export function run(input, { exec = defaultExec } = {}) { /* logique pure, retourne un résultat */ }

/* v8 ignore next 5 */
if (process.argv[1] === fileURLToPath(import.meta.url)) {
  const input = JSON.parse(readFileSync(0, 'utf8'));
  const result = run(input);
  if (result) process.stdout.write(JSON.stringify(result));
}

Règles d'écriture

• Langue : Node .mjs, OS-agnostique, dépendances builtins uniquement (fs, child_process, path). Pas de npm.
• Un fichier = une responsabilité.
• PostToolUse sont non bloquants : erreurs d'outils absents (--no-install) silencieuses.
• PreToolUse bloquants : reason actionnable, pas juste « interdit ».
• Timeout explicite sur tout execSync. Filtrer par extension avant un outil lourd (/\.tsx?$/.test(p)).
• Hooks Python : .mjs qui appelle uv run <tool> (ruff/pytest/pyright) — uv run résout le venv. Filtrer .endsWith('.py').

Workflow d'ajout / modif d'un hook

1. Écrire/modifier .claude/hooks/<slug>.mjs (pattern ci-dessus).
2. Ajouter/maj le test tests/hooks/<slug>.test.mjs (importe run, injecte des fakes vi.fn()). pnpm test.
3. Métadonnées dans registry/registry.json (type Hook) : name, benefit (≤ ~60 car., orienté résultat), description, use_cases (anglais, champs racine, pas d'overlay i18n), implementation.config (fragment { hooks: { [Event]: [...] } } fusionnable), implementation.script_path → le .mjs. Laisser code_snippet vide : rempli par le sync. Annoter stack seulement si le code filtre par extension ou appelle un outil non universel — ne jamais déduire le stack depuis les tags seuls, lire le code.
4. node .claude/sync-hooks.mjs — injecte // @hookstack <slug> en ligne 2, recopie dans code_snippet, reconstruit settings.json.
5. Outil externe requis (jscpd, gh, uv…) → ajouter une entrée dans PREREQ_HINTS (packages/cli/bin/core.mjs).
6. Après commit du .mjs : pnpm timeline (régénère registry/hooks-timeline.json, public/hooks-timeline.svg, bloc README).