@roomi-fields/grillhouse 0.0.0-stage → 0.23.0

package/scripts/consommateurs-arbitres.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// A line of a `## Consommateurs` section that a lot changes enters with its settled arbitrage at the
+// ticket: each dependency between components is decided before it is written, as a code owner
+// approves a change to the files it owns.
+//
+//   npx grillhouse consommateurs-arbitres   run from the repository root (a guard of grillhouse:gardes)
+//
+// - It judges the copy it runs in, on the branch `agent/<ticket>`: for each component the guards
+//   judge (`aVerifier` of scripts/interfaces-contre-code.mjs; in the envelope of a component,
+//   `GRILLHOUSE_ENVELOPPE`, that component alone), each list line (`- …`) of the `## Consommateurs`
+//   section of its `docs/INTERFACE.md` in the working tree that the section of HEAD does not hold
+//   is a changed line (an interface absent from HEAD: all its lines). Out of a branch `agent/…`
+//   (main, the detached copy of the integration, the CI, the night), there is no lot: nothing is
+//   judged.
+// - With a changed line, the comments of the ticket are read (`bd comments <ticket> --json`, run
+//   from the main tree, the parent of git's common directory). A changed line passes when an
+//   arbitrage that is settled (`arbitrageTranche`: a « ## Arbitrage… » comment, or the regulator's,
+//   that the circuit writes from its sheet, `estArbitrage`) names its consumer, the first
+//   name between backquotes of the line, found as it is in the comment's text. Without a changed
+//   line, bd is not called.
+// - A changed line no arbitrage settles passes too when the section « Architecture » of the
+//   ticket's description (`bd show <ticket> --json`, from its heading `## Architecture` to the
+//   next heading of its level or above) names its consumer and each name the line declares, word
+//   for word (`nommeParLArchitecture`): the ticket fixed them before the lot. The description is
+//   read only for such a line; a description that cannot be read refuses, as the comments do.
+// - A refusal names `<INTERFACE.md> § Consommateurs` and the line; a refusal inscribed in the
+//   project's debt (`grillhouse-dette.json`, see `dette.mjs`) passes, keyed by the interface and
+//   `consommateur-sans-arbitrage`. Comments that cannot be read refuse, never inscribed.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { trancher } from './dette.mjs';
+import { aVerifier } from './interfaces-contre-code.mjs';
+
+const REGLE = 'consommateur-sans-arbitrage';
+
+// The regulator's arbitrage as the circuit writes it at the ticket, from the `arbitrage` of its
+// sheet (scripts/circuit.mjs): `Circuit · <composant> · regulateur : arbitrage — <texte>`.
+const DU_REGULATEUR = /^Circuit · [^\n]* · regulateur : arbitrage — /;
+
+// True when the text <text> of a comment is an arbitrage: a « ## Arbitrage… » comment, or the
+// regulator's, as the circuit writes it.
+export const estArbitrage = text =>
+  /^\s*## Arbitrage\b/.test(String(text ?? '')) || DU_REGULATEUR.test(String(text ?? ''));
+
+// True when the arbitrage <a> of <comments> (Beads' JSON, in their order) is settled: the
+// regulator's (it settles only what the letter of a criterion, a written precedent or a rule of
+// the frame settles), a line `### Verdict — tranché`, or a « ## Réponse du responsable » comment
+// after it.
+export function arbitrageTranche(comments, a) {
+  const tranche = DU_REGULATEUR.test(a.text) || /^### Verdict\s*—\s*tranché/m.test(a.text);
+  return (
+    tranche ||
+    comments
+      .slice(comments.indexOf(a) + 1)
+      .some(c => /^\s*## Réponse du responsable\b/.test(c.text))
+  );
+}
+
+// The list lines of the section `## Consommateurs` of <texte>, trimmed.
+function lignesConsommateurs(texte) {
+  const out = [];
+  let dedans = false;
+  for (const l of texte.split('\n')) {
+    if (/^##\s/.test(l)) dedans = /^##\s+Consommateurs\s*$/.test(l);
+    else if (dedans && /^\s*-\s+\S/.test(l)) out.push(l.trim());
+  }
+  return out;
+}
+
+// The section « Architecture » of the ticket's description <description>: its lines from its
+// heading (`## Architecture`) to the next heading of its level or above, or '' without one.
+function sectionArchitecture(description) {
+  const out = [];
+  let niveau = 0;
+  for (const l of String(description ?? '').split('\n')) {
+    const titre = /^(#{1,6})\s+(.*)$/.exec(l);
+    if (niveau && titre && titre[1].length <= niveau) break;
+    if (niveau) out.push(l);
+    else if (titre && /^Architecture\b/.test(titre[2].trim())) niveau = titre[1].length;
+  }
+  return out.join('\n');
+}
+
+// Whether the text <texte> names the consumer and each name of the `## Consommateurs` line
+// <ligne> (``- `<consommateur>` : <nom>, <nom>``), word for word: each one whole, with no
+// character of a name (a letter, a digit, `_`, `$`, `-`) beside it; `*`, a namespace, between
+// backquotes.
+function nommeParLArchitecture(texte, ligne) {
+  const m = /^[-*]\s+`?([^`:\s]+)`?\s*:\s*(.+)$/.exec(ligne);
+  if (!m) return false;
+  const noms = m[2]
+    .split(',')
+    .map(s => s.replace(/`/g, '').trim())
+    .filter(Boolean);
+  const echappe = s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const nomme = nom =>
+    nom === '*'
+      ? texte.includes('`*`')
+      : new RegExp(`(?<![\\w$-])${echappe(nom)}(?![\\w$-])`).test(texte);
+  return [m[1], ...noms].every(nomme);
+}
+
+const git = (racine, ...a) => spawnSync('git', ['-C', racine, ...a], { encoding: 'utf8' });
+
+// The ticket of the copy at <racine>: <ticket> of its branch `agent/<ticket>`, or null.
+function ticketDeLaCopie(racine) {
+  const r = git(racine, 'rev-parse', '--abbrev-ref', 'HEAD');
+  const m = r.status === 0 ? /^agent\/(.+)$/.exec(r.stdout.trim()) : null;
+  return m ? m[1] : null;
+}
+
+// The findings of the copy <racine> under <env>, in the debt's form (`dette.mjs`).
+export function verifier(racine, env = process.env) {
+  const ticket = ticketDeLaCopie(racine);
+  if (!ticket) return [];
+  const changees = [];
+  for (const c of aVerifier(racine, env)) {
+    const iface = path.join(c.dir, 'docs', 'INTERFACE.md');
+    if (!existsSync(iface)) continue;
+    const rel = path.relative(racine, iface);
+    const head = git(racine, 'show', `HEAD:${rel}`);
+    const avant = new Set(head.status === 0 ? lignesConsommateurs(head.stdout) : []);
+    for (const ligne of lignesConsommateurs(readFileSync(iface, 'utf8'))) {
+      if (!avant.has(ligne)) changees.push({ rel, ligne });
+    }
+  }
+  if (changees.length === 0) return [];
+  const commun = git(racine, 'rev-parse', '--path-format=absolute', '--git-common-dir');
+  const principal = path.dirname(commun.stdout.trim());
+  const r = spawnSync('bd', ['comments', ticket, '--json'], {
+    cwd: principal,
+    encoding: 'utf8',
+    maxBuffer: 256 * 1024 * 1024,
+  });
+  let comments;
+  try {
+    if (r.status !== 0) throw new Error(r.stderr || r.error?.message || `code ${r.status}`);
+    comments = (JSON.parse(r.stdout || '[]') ?? []).map(x => ({ text: String(x.text ?? '') }));
+  } catch (e) {
+    return [
+      {
+        message: `Les commentaires du ticket ${ticket} ne se lisent pas (bd comments ${ticket} --json) : ${String(e.message ?? e).trim()} ; les lignes Consommateurs changées ne se jugent pas.`,
+      },
+    ];
+  }
+  const arbitrages = comments.filter(a => estArbitrage(a.text) && arbitrageTranche(comments, a));
+  const consommateurDe = ligne => /`([^`]+)`/.exec(ligne)?.[1] ?? ligne.replace(/^-\s+/, '');
+  const restantes = changees.filter(
+    ({ ligne }) => !arbitrages.some(a => a.text.includes(consommateurDe(ligne)))
+  );
+  if (restantes.length === 0) return [];
+  // The lines no arbitrage settles: the section « Architecture » of the ticket.
+  const show = spawnSync('bd', ['show', ticket, '--json'], {
+    cwd: principal,
+    encoding: 'utf8',
+    maxBuffer: 256 * 1024 * 1024,
+  });
+  let architecture;
+  try {
+    if (show.status !== 0) {
+      throw new Error(show.stderr || show.error?.message || `code ${show.status}`);
+    }
+    architecture = sectionArchitecture(JSON.parse(show.stdout || '[]')?.[0]?.description);
+  } catch (e) {
+    return [
+      {
+        message: `Le ticket ${ticket} ne se lit pas (bd show ${ticket} --json) : ${String(e.message ?? e).trim()} ; les lignes Consommateurs changées ne se jugent pas.`,
+      },
+    ];
+  }
+  const constats = [];
+  for (const { rel, ligne } of restantes) {
+    if (nommeParLArchitecture(architecture, ligne)) continue;
+    const consommateur = consommateurDe(ligne);
+    constats.push({
+      fichier: rel,
+      regle: REGLE,
+      message: `${rel} § Consommateurs : la ligne « ${ligne} » change sans arbitrage tranché au ticket ${ticket} qui nomme \`${consommateur}\`, ni section « Architecture » du ticket qui nomme ce consommateur et chaque nom de la ligne ; une dépendance entre composants se décide avant de s'écrire : un commentaire « ## Arbitrage » tranché au ticket qui nomme ce consommateur, ou l'Architecture du ticket qui la fixe.`,
+    });
+  }
+  return constats;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const racine = process.cwd();
+  const { refus, lignes } = trancher(racine, 'consommateurs-arbitres', verifier(racine));
+  for (const r of refus) process.stderr.write(`⛔ ${r.message}\n`);
+  for (const l of lignes) process.stderr.write(`${l}\n`);
+  process.exitCode = refus.length ? 1 : 0;
+}

package/scripts/consommateurs.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+// The consumers of the interfaces: each component's `docs/INTERFACE.md` declares, in its
+// `## Consommateurs` section, which components use which of its elements:
+//
+//   ## Consommateurs
+//
+//   - `a` : duree, tempo
+//   - `c` : *
+//
+// This check reads what the production code of every component imports from every other, and
+// refuses (exit 1) a use that the provider's interface does not declare. A declared use that no
+// code makes is reported, without refusing. `*` stands for a namespace, default, re-export-all or
+// side-effect import. A refusal inscribed in the project's debt (`grillhouse-dette.json`, see
+// `dette.mjs`) passes, keyed by the provider's interface and `usage-non-declare` (`homonyme` for
+// two components of one name, keyed by the first path).
+//
+//   npx grillhouse consommateurs        run from the repository root
+//
+// Components are the directories under `packages/` (reached by their package name or a relative
+// path) and under `src/` (reached by a relative path), except those listed out of the frame in
+// `docs/agents/hors-cadre.txt`: neither read nor checked, as provider or as consumer. Every check
+// of the frame enumerates the components through `composants`. In a repository of packages, such a
+// package stays a workspace, and Turborepo plays none of its tasks (scripts/turbo-des-paquets.mjs
+// writes its configuration). For the check of the uses, test files,
+// `dist/`, `docs/` and `node_modules/` are not production code and are not read; nor are Vite's
+// temporary files, and a file gone between the walk and its read is passed over (`parcourir`).
+// The identity of a component is its name: two directories of the same name, one under `packages/`
+// and one under `src/`, are refused, both paths named (the way npm workspaces, Nx and Cargo refuse
+// two projects of one name). Names differing by case are two names.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { trancher } from './dette.mjs';
+import { horsCadre } from './paquets.mjs';
+
+const SOURCE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|svelte|vue)$/;
+const TEST_DIR = new Set(['test', 'tests', '__tests__']);
+// The name of a test file: `x.test.ts`, `x.spec.mjs`…
+export const NOM_DE_TEST = /\.(test|spec)\.[cm]?[jt]sx?$/;
+const isTest = name => NOM_DE_TEST.test(name);
+const SKIP = new Set(['node_modules', 'dist', 'docs']);
+
+// Every directory under `packages/` and `src/` of the repository at <racine>: [{ nom, dir }].
+function tousDossiers(racine) {
+  const found = [];
+  for (const parent of ['packages', 'src']) {
+    const base = path.join(racine, parent);
+    if (!existsSync(base)) continue;
+    for (const e of readdirSync(base, { withFileTypes: true })) {
+      if (e.isDirectory()) found.push({ nom: e.name, dir: path.join(base, e.name) });
+    }
+  }
+  return found;
+}
+
+// The component directories of the repository at <racine>: [{ nom, dir }], each directory under
+// `packages/` and `src/` that `docs/agents/hors-cadre.txt` does not list.
+function dossiers(racine) {
+  const hors = horsCadre(racine);
+  return tousDossiers(racine).filter(d => !hors.has(d.nom));
+}
+
+// The names of `docs/agents/hors-cadre.txt` that no directory under `packages/` or `src/` bears,
+// in the order of the list.
+export function horsCadreInconnus(racine) {
+  const presents = new Set(tousDossiers(racine).map(d => d.nom));
+  return [...horsCadre(racine)].filter(nom => !presents.has(nom));
+}
+
+// The components of the repository at <racine>: [{ nom, dir, paquet }], `paquet` its package name.
+// Throws when a package.json is unreadable.
+export function composants(racine) {
+  return dossiers(racine).map(({ nom, dir }) => {
+    const pj = path.join(dir, 'package.json');
+    const paquet = existsSync(pj) ? (JSON.parse(readFileSync(pj, 'utf8')).name ?? null) : null;
+    return { nom, dir, paquet };
+  });
+}
+
+// The subpath export by which a component publishes the shared test material.
+const EXPORT_MATIERE = './test-fixtures';
+
+// The components of <racine> whose `package.json` exports `./test-fixtures`, in any form of its
+// value, a package out of the frame never one: the packages of the shared test material,
+// [{ nom, dir, paquet }] as `composants` gives.
+// A component whose `package.json` is unreadable is not a package of the material.
+export function matieres(racine) {
+  const found = [];
+  for (const { nom, dir } of dossiers(racine)) {
+    const pj = path.join(dir, 'package.json');
+    if (!existsSync(pj)) continue;
+    let paquet;
+    try {
+      paquet = JSON.parse(readFileSync(pj, 'utf8'));
+    } catch {
+      continue;
+    }
+    const { exports } = paquet ?? {};
+    if (exports !== null && typeof exports === 'object' && EXPORT_MATIERE in exports) {
+      found.push({ nom, dir, paquet: paquet.name ?? null });
+    }
+  }
+  return found;
+}
+
+// The declared consumers of an interface text: Map consumer → Set of element names.
+export function declares(texte) {
+  const out = new Map();
+  let dedans = false;
+  for (const l of texte.split('\n')) {
+    if (/^#{1,6} /.test(l)) {
+      dedans = /^## Consommateurs\s*$/.test(l);
+      continue;
+    }
+    const m = dedans && /^[-*]\s+`?([^`:\s]+)`?\s*:\s*(.+)$/.exec(l.trim());
+    if (!m) continue;
+    const noms = m[2]
+      .split(',')
+      .map(s => s.replace(/`/g, '').trim())
+      .filter(Boolean);
+    out.set(m[1], new Set(noms));
+  }
+  return out;
+}
+
+// The imports of a source text: [{ spec, noms }].
+export function imports(source) {
+  const out = [];
+  // A static clause holds only names, braces, commas, `*`, `as` and `type`: it never crosses a
+  // `;`, a quote, a parenthesis or an `=`, so it never runs from one statement into the next.
+  const re =
+    /^\s*(?:import|export)\s+(?:type\s+)?([^;'"()=]*?)\s*from\s*['"]([^'"]+)['"]|^\s*import\s*['"]([^'"]+)['"]|\b(?:require|import)\(\s*['"]([^'"]+)['"]\s*\)/gm;
+  for (const m of source.matchAll(re)) {
+    if (m[3] || m[4]) {
+      out.push({ spec: m[3] ?? m[4], noms: ['*'] });
+      continue;
+    }
+    const clause = m[1];
+    const noms = [];
+    const braces = /\{([^}]*)\}/.exec(clause);
+    if (braces) {
+      for (const part of braces[1].split(',')) {
+        const nom = part
+          .replace(/^\s*type\s+/, '')
+          .split(/\s+as\s+/)[0]
+          .trim();
+        if (nom) noms.push(nom);
+      }
+    }
+    if (
+      clause
+        .replace(/\{[^}]*\}/, '')
+        .replace(/,/g, '')
+        .trim()
+    )
+      noms.push('*');
+    out.push({ spec: m[2], noms });
+  }
+  return out;
+}
+
+// The temporary file Vite writes beside a configuration it bundles, then removes
+// (`vitest.config.ts.timestamp-<n>-<hash>.mjs`).
+const TEMPORAIRE_DE_VITE = /\.timestamp-[^/\\]*\.mjs$/;
+
+// <f> read by <lire>, or <absent> when it no longer exists (ENOENT).
+function siPresent(lire, f, absent) {
+  try {
+    return lire(f);
+  } catch (e) {
+    if (e?.code === 'ENOENT') return absent;
+    throw e;
+  }
+}
+
+// The files under <chemin> (a directory, or a file), each its absolute path: an entry below it
+// whose path <sauter> keeps out is neither entered nor listed, and Vite's temporary files are
+// never listed. The guards of the frame walk the repository while other processes write in it
+// (`npm run verifier` plays them beside the tests): a file or a directory gone before the walk
+// reaches it is passed over. The walk of every guard of the frame.
+export function parcourir(chemin, sauter = () => false) {
+  const out = [];
+  const walk = (p, dossier) => {
+    if (!dossier) {
+      if (!TEMPORAIRE_DE_VITE.test(p)) out.push(p);
+      return;
+    }
+    for (const e of siPresent(d => readdirSync(d, { withFileTypes: true }), p, [])) {
+      const q = path.join(p, e.name);
+      if (!sauter(q)) walk(q, e.isDirectory());
+    }
+  };
+  const racine = siPresent(statSync, chemin, null);
+  if (racine) walk(chemin, racine.isDirectory());
+  return out;
+}
+
+// The text of the file <f> a walk listed, or null when it is gone since.
+export const lireSiPresent = f => siPresent(x => readFileSync(x, 'utf8'), f, null);
+
+// The production source files under <dir>: test folders and test files left out.
+function fichiers(dir) {
+  const nom = p => path.basename(p);
+  return parcourir(
+    dir,
+    p => SKIP.has(nom(p)) || nom(p).startsWith('.') || TEST_DIR.has(nom(p))
+  ).filter(p => SOURCE.test(nom(p)) && !isTest(nom(p)));
+}
+
+// The component an import specifier reaches from <fichier>, other than <soi>, or null.
+function fournisseur(spec, fichier, tous, soi) {
+  if (spec.startsWith('.')) {
+    const cible = path.resolve(path.dirname(fichier), spec);
+    return (
+      tous.find(c => c !== soi && (cible === c.dir || cible.startsWith(c.dir + path.sep))) ?? null
+    );
+  }
+  return (
+    tous.find(
+      c => c !== soi && c.paquet && (spec === c.paquet || spec.startsWith(c.paquet + '/'))
+    ) ?? null
+  );
+}
+
+// What each component really uses of the others: Map provider → Map consumer → Set of names.
+export function utilise(racine, tous = composants(racine)) {
+  const out = new Map();
+  for (const c of tous) {
+    for (const f of fichiers(c.dir)) {
+      for (const { spec, noms } of imports(lireSiPresent(f) ?? '')) {
+        const p = fournisseur(spec, f, tous, c);
+        if (!p) continue;
+        if (!out.has(p.nom)) out.set(p.nom, new Map());
+        const parConsommateur = out.get(p.nom);
+        if (!parConsommateur.has(c.nom)) parConsommateur.set(c.nom, new Set());
+        for (const n of noms) parConsommateur.get(c.nom).add(n);
+      }
+    }
+  }
+  return out;
+}
+
+// The refusals of the components that share a name: one finding per name, both paths.
+function homonymes(racine) {
+  const parNom = new Map();
+  for (const { nom, dir } of dossiers(racine)) {
+    parNom.set(nom, [...(parNom.get(nom) ?? []), path.relative(racine, dir)]);
+  }
+  return [...parNom]
+    .filter(([, dirs]) => dirs.length > 1)
+    .map(([nom, dirs]) => ({
+      fichier: dirs[0],
+      regle: 'homonyme',
+      message: `${nom} : ${dirs.join(' et ')} portent le même nom de composant.`,
+    }));
+}
+
+// The refusals (uses no interface declares), as findings `{ fichier, regle, message }` the debt
+// (`dette.mjs`) judges, and the reports (declared uses no code makes). A declared consumer out of
+// the frame is passed over: its code is not read.
+export function verifier(racine) {
+  const tous = composants(racine);
+  const hors = horsCadre(racine);
+  const reel = utilise(racine, tous);
+  const refus = homonymes(racine);
+  const signaux = [];
+  for (const p of tous) {
+    const iface = path.join(p.dir, 'docs', 'INTERFACE.md');
+    const rel = path.relative(racine, iface);
+    const declare = existsSync(iface) ? declares(readFileSync(iface, 'utf8')) : new Map();
+    const utilises = reel.get(p.nom) ?? new Map();
+    for (const [consommateur, noms] of utilises) {
+      const permis = declare.get(consommateur) ?? new Set();
+      for (const n of noms) {
+        if (!permis.has(n))
+          refus.push({
+            fichier: rel,
+            regle: 'usage-non-declare',
+            message: `${consommateur} utilise « ${n} » de ${p.nom}, que ${rel} ne déclare pas.`,
+          });
+      }
+    }
+    for (const [consommateur, noms] of declare) {
+      if (hors.has(consommateur)) continue;
+      const faits = utilises.get(consommateur) ?? new Set();
+      for (const n of noms) {
+        if (!faits.has(n))
+          signaux.push(
+            `${rel} déclare « ${n} » pour ${consommateur}, qu'aucun code de ${consommateur} n'utilise.`
+          );
+      }
+    }
+  }
+  return { refus, signaux };
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const racine = process.cwd();
+  const verdict = verifier(racine);
+  const { refus, lignes } = trancher(racine, 'consommateurs', verdict.refus);
+  for (const s of verdict.signaux) process.stderr.write(`⚠️  ${s}\n`);
+  for (const r of refus) process.stderr.write(`⛔ ${r.message}\n`);
+  for (const l of lignes) process.stderr.write(`${l}\n`);
+  if (refus.length) {
+    process.stderr.write(
+      "Une consommation nouvelle se décide (la section « Architecture » du ticket qui la nomme, sinon le référent technique), puis entre dans la section « Consommateurs » de l'interface du fournisseur.\n"
+    );
+    process.exitCode = 1;
+  }
+}

package/scripts/crochet.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// One git hook of the frame at work: the guard of the hook <nom> (`CROCHETS` of
+// scripts/crochets.mjs), run with git's arguments and standard input, its exit code the hook's.
+//
+//   npx grillhouse hook <nom> [git's arguments…]
+//
+// - The guard runs in this process, as if Node had been given its path, as `grillhouse` runs a
+//   subcommand (bin/grillhouse.mjs).
+// - A name that is not a hook of the frame is refused, named on the error stream; exit code 2.
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { CROCHETS } from './crochets.mjs';
+
+const [nom, ...args] = process.argv.slice(2);
+if (nom === undefined || !Object.hasOwn(CROCHETS, nom)) {
+  process.stderr.write(
+    `⛔ crochet inconnu : ${nom ?? '(aucun)'} ; crochets du cadre : ${Object.keys(CROCHETS).join(', ')}\n`
+  );
+  process.exitCode = 2;
+} else {
+  const garde = path.join(path.dirname(fileURLToPath(import.meta.url)), CROCHETS[nom].garde);
+  process.argv = [process.argv[0], garde, ...args];
+  await import(pathToFileURL(garde).href);
+}

package/scripts/crochets.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// The frame's git hooks, on Husky's model: the project's `prepare`, which npm runs at its install,
+// places them, and each calls the project's command, `grillhouse hook <nom>`.
+//
+//   npx grillhouse hooks [<project>]            places both hooks (the current directory by default)
+//   npx grillhouse hooks --absents [<project>]  prints the name of each absent hook, one per line
+//
+// - commit-msg: « un ticket fermé garde sa livraison ; un ticket rouvert reçoit ses corrections » (scripts/un-commit-par-ticket.mjs).
+// - pre-push: the night branch guard (scripts/branche-de-nuit.mjs).
+// - A hook lives in the folder git reads for the project (`git rev-parse --git-path hooks`, which
+//   follows `core.hooksPath`, Beads' `.beads/hooks` included); the configuration is never changed
+//   here. The update of the frame (scripts/grillhouse-maj.mjs) places them by the same function.
+// - The frame's lines run `node_modules/.bin/grillhouse` of the project, the package installed;
+//   without it they do nothing and let the hook go on, as Husky's lines do without Husky.
+// - A hook that does not exist is created (shebang, the frame's lines), executable. In one that
+//   exists, the frame's lines of any version (a comment « … (Grillhouse): », a line that names a
+//   guard's script or the frame's shell variables `_gh_…`) give way to the current ones, written
+//   where the first stood, else right after the shebang; the project's lines and Beads' sections
+//   stay as they are. The frame's lines never end the hook early (no `exec` of a command), so the
+//   lines that follow still run.
+// - A hook is absent when it is missing from that folder or lacks the current lines of the frame.
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// The project's command, which the frame's lines run.
+const COMMANDE = '_gh_commande="$(git rev-parse --show-toplevel)/node_modules/.bin/grillhouse"';
+
+// The frame's hooks: name, guard (the script `grillhouse hook <nom>` runs) and lines. The pre-push
+// guard reads git's standard input, which is kept in a file and given back to the lines that
+// follow (Beads' section).
+export const CROCHETS = {
+  'commit-msg': {
+    garde: 'un-commit-par-ticket.mjs',
+    lignes: [
+      '# A closed ticket keeps its one delivery (Grillhouse): a second commit for a closed ticket whose delivery stands is refused, a commit for an open (reopened) ticket is a correction and passes; a revert (Revert "…", Reapply "…") passes and withdraws the delivery it names. Without the package @roomi-fields/grillhouse installed, nothing.',
+      COMMANDE,
+      'if [ -x "$_gh_commande" ]; then "$_gh_commande" hook commit-msg "$@" || exit 1; fi',
+    ],
+  },
+  'pre-push': {
+    garde: 'branche-de-nuit.mjs',
+    lignes: [
+      '# Night branch guard (Grillhouse): only the night pushes the branch of grillhouse.poussee.nuit, after its green. Without the package @roomi-fields/grillhouse installed, nothing.',
+      COMMANDE,
+      'if [ -x "$_gh_commande" ]; then _gh_entree=$(mktemp) && cat > "$_gh_entree" && "$_gh_commande" hook pre-push "$@" < "$_gh_entree" || { rm -f "$_gh_entree"; exit 1; }; exec < "$_gh_entree"; rm -f "$_gh_entree"; fi',
+    ],
+  },
+};
+
+// A line of the frame, of this version or of a former one (see the header).
+const ligneDuCadre = ligne =>
+  /^# .*\(Grillhouse\):/.test(ligne) ||
+  ligne.includes('_gh_') ||
+  Object.values(CROCHETS).some(({ garde }) => ligne.includes(garde));
+
+// The folder git reads the hooks of `projet` from, or null when it is not a git repository.
+function dossierDesCrochets(projet) {
+  try {
+    return path.resolve(
+      projet,
+      execFileSync('git', ['-C', projet, 'rev-parse', '--git-path', 'hooks'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim()
+    );
+  } catch {
+    return null;
+  }
+}
+
+// The text of the hook `nom` once the frame's current lines are placed in `actuel` (null: none).
+function texteDuCrochet(nom, actuel) {
+  const { lignes } = CROCHETS[nom];
+  if (actuel === null) {
+    return `#!/usr/bin/env sh\n${lignes.join('\n')}\n`;
+  }
+  const avant = actuel.split('\n');
+  const premiere = avant.findIndex(ligneDuCadre);
+  const reste = avant.filter(l => !ligneDuCadre(l));
+  const ou = premiere >= 0 ? premiere : avant[0]?.startsWith('#!') ? 1 : 0;
+  reste.splice(ou, 0, ...lignes);
+  return reste.join('\n');
+}
+
+// Places the frame's hook `nom` in the project (see the header). Returns its path when written.
+function poserCrochet(projet, nom) {
+  const dossier = dossierDesCrochets(projet);
+  if (!dossier) {
+    return null;
+  }
+  const f = path.join(dossier, nom);
+  const actuel = existsSync(f) ? readFileSync(f, 'utf8') : null;
+  const texte = texteDuCrochet(nom, actuel);
+  const ecrit = texte !== actuel;
+  if (ecrit) {
+    mkdirSync(dossier, { recursive: true });
+    writeFileSync(f, texte);
+  }
+  chmodSync(f, statSync(f).mode | 0o111);
+  return ecrit ? f : null;
+}
+
+/** Places both frame hooks in the project; returns the paths written. */
+export function poserCrochets(projet) {
+  return Object.keys(CROCHETS)
+    .map(nom => poserCrochet(projet, nom))
+    .filter(Boolean);
+}
+
+/** Names the frame hooks absent from the folder git reads for the project. */
+export function crochetsAbsents(projet) {
+  const dossier = dossierDesCrochets(projet);
+  return Object.entries(CROCHETS)
+    .filter(([nom, { lignes }]) => {
+      const f = dossier && path.join(dossier, nom);
+      return !f || !existsSync(f) || !readFileSync(f, 'utf8').includes(`${lignes.join('\n')}\n`);
+    })
+    .map(([nom]) => nom);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const args = process.argv.slice(2);
+  const absents = args[0] === '--absents';
+  const projet = path.resolve((absents ? args[1] : args[0]) ?? '.');
+  if (absents) {
+    const noms = crochetsAbsents(projet);
+    if (noms.length > 0) {
+      process.stdout.write(`${noms.join('\n')}\n`);
+    }
+  } else {
+    poserCrochets(projet);
+  }
+}