@roomi-fields/grillhouse 0.0.0-stage → 0.23.0

package/scripts/index-interfaces.mjs

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+// The index of the interfaces: one line per component, then one line per element it provides,
+// generated from the components' `docs/INTERFACE.md`. An agent loads it at start and opens an
+// interface, then one of its sections, only when the index names it.
+//
+//   npx grillhouse index-interfaces            writes docs/agents/index-des-interfaces.md
+//   npx grillhouse index-interfaces --verifier refuses (exit 1) when that file is out of date,
+//                                                its finding in SARIF too (scripts/resultats.mjs)
+//   npx grillhouse index-interfaces --publie <composant>
+//                                                prints what the providers of <composant> publish
+//
+// The providers of a component are the components whose `## Consommateurs` section names it: the
+// frame's one written and checked record of who uses whom (scripts/consommateurs.mjs). `--publie`
+// is the first level of a progressive disclosure, as the skills of Claude Code, llms.txt or
+// Aider's repository map: for each provider, its line, the names of the elements declared for the
+// component (the only ones the check of the consumers lets it use) and the address of the rubric
+// « Rend » of its `docs/CADRE.md`; the index of the interfaces is the second level, every element
+// with its sentence; the interface is the third, the section of each element. The launcher
+// (scripts/enveloppe/lancer.sh) writes the section `--publie` prints after the instruction of a role
+// agent; the relecteur prints it by the same command.
+//
+// An interface is found at `packages/<x>/docs/INTERFACE.md` and `src/<x>/docs/INTERFACE.md` for
+// each component of `composants` (a package out of the frame has none), and at
+// `docs/INTERFACE.md`. Its title and first sentence give the component's line, headed by the title
+// alone when the title already begins with the component's folder name (exact case, followed by a
+// blank or ending the title), else by `<component> — <title>`; the root interface is always
+// headed `(racine) — <title>`. Each `##` and `###` heading of the generated part (between the
+// marks `<!-- généré: début -->` and `<!-- généré: fin -->`, written by `npm run api`), with the
+// first sentence of its summary (the paragraph under it, before its signature and its rubrics
+// `**Paramètres**`, `**Retour**`, `**Fautes**`, `**Membres**`, which the index never carries),
+// gives an element's line; a heading outside the generated part gives
+// none, and an interface without marks (the root one) gives no element line. Code blocks (``` or
+// ~~~, indented or not) are skipped whole. The `## Consommateurs` section gives one line that
+// names each consumer with the elements it uses.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { composants, declares } from './consommateurs.mjs';
+import { DEBUT, FIN, marques } from './interfaces-contre-code.mjs';
+import { ecrireSarif } from './resultats.mjs';
+
+export const SORTIE = 'docs/agents/index-des-interfaces.md';
+
+// The interface files of the repository at <racine>, as paths relative to it, in a stable order:
+// the interface of each component that `composants` gives, and the root interface.
+export function interfaces(racine) {
+  const found = composants(racine)
+    .map(c => path.relative(racine, path.join(c.dir, 'docs', 'INTERFACE.md')))
+    .filter(rel => existsSync(path.join(racine, rel)));
+  if (existsSync(path.join(racine, 'docs', 'INTERFACE.md'))) found.push('docs/INTERFACE.md');
+  return found.sort();
+}
+
+// The heading of a component's line: the title as it is when it already begins with the component's
+// name, exact case, followed by a blank or ending the title; else the name, a dash, the title.
+const tetiere = (composant, titre) =>
+  composant !== '(racine)' &&
+  titre.startsWith(composant) &&
+  (titre.length === composant.length || /\s/.test(titre[composant.length]))
+    ? titre
+    : `${composant} — ${titre}`;
+
+const firstSentence = lines => {
+  const text = lines.join(' ').replace(/\s+/g, ' ').trim();
+  const m = /^(.+?[.!?])(\s|$)/.exec(text);
+  return m ? m[1] : text;
+};
+
+// One interface read once: its component, its heading, its first sentence, and its parts in their
+// order, each an element of its generated part `{ titre, phrase }` or its declared consumers
+// `{ consommateurs }` (Map consumer → Set of element names).
+export function lire(rel, contenu) {
+  const lignes = contenu.split('\n');
+  const composant = rel === 'docs/INTERFACE.md' ? '(racine)' : rel.split('/')[1];
+  const titre = (lignes.find(l => l.startsWith('# ')) ?? `# ${composant}`).slice(2).trim();
+  const sections = [];
+  let courante = { niveau: 1, titre, corps: [] };
+  const fermer = () => sections.push(courante);
+  let cloture = null;
+  // The generated part is read where the check finds its marks; invalid marks give none.
+  const m0 = marques(contenu);
+  let generee = false;
+  for (const [i, l] of lignes.entries()) {
+    // A code block is skipped whole: a `## …` written inside it is code, not a heading.
+    const f = /^\s*(```|~~~)/.exec(l);
+    if (cloture) {
+      if (f && f[1] === cloture) cloture = null;
+      continue;
+    }
+    if (f) {
+      cloture = f[1];
+      continue;
+    }
+    if (l.trim() === DEBUT || l.trim() === FIN) {
+      fermer();
+      generee = m0.etat === 'ok' && i === m0.debut;
+      courante = { niveau: 2, titre: '', corps: [], generee, ignoree: true };
+      continue;
+    }
+    const m = /^(#{1,3}) (.+)$/.exec(l);
+    if (m) {
+      if (m[1].length === 1) continue;
+      fermer();
+      courante = { niveau: m[1].length, titre: m[2].trim(), corps: [], generee };
+    } else if (courante.generee && (courante.fermee || /^\*\*[^*]+\*\*/.test(l))) {
+      // An element of the generated part gives its summary only: its rubrics (`**Membres**`,
+      // `**Paramètres**`…) are read at its address.
+      courante.fermee = true;
+    } else if (!l.trim()) {
+      if (courante.generee && courante.corps.length) courante.fermee = true;
+    } else if (!l.startsWith('|')) {
+      if (courante.corps.length < 6 || courante.titre === 'Consommateurs')
+        courante.corps.push(l.replace(/^[-*]\s+/, ''));
+    }
+  }
+  fermer();
+  const [tete, ...reste] = sections;
+  const parties = [];
+  for (const s of reste) {
+    if (s.ignoree) continue;
+    if (s.niveau === 2 && s.titre === 'Consommateurs') {
+      parties.push({
+        consommateurs: declares(`## Consommateurs\n${s.corps.map(l => `- ${l}`).join('\n')}`),
+      });
+    } else if (s.generee) {
+      parties.push({ titre: s.titre, phrase: firstSentence(s.corps) });
+    }
+  }
+  return {
+    rel,
+    composant,
+    tetiere: tetiere(composant, tete.titre),
+    phrase: firstSentence(tete.corps),
+    parties,
+  };
+}
+
+// The index lines of one interface: its component line, then one line per heading.
+export function entrees(rel, contenu) {
+  const { tetiere: t, phrase, parties } = lire(rel, contenu);
+  const out = [`## ${t}`, '', `${phrase} (\`${rel}\`)`, ''];
+  for (const p of parties) {
+    if (p.consommateurs) {
+      const liste = [...p.consommateurs]
+        .map(([qui, noms]) => `${qui} (${[...noms].join(', ')})`)
+        .join(' ; ');
+      out.push(`- **Consommateurs** — ${liste || 'aucun'}`);
+    } else {
+      out.push(`- **${p.titre}**${p.phrase ? ` — ${p.phrase}` : ''}`);
+    }
+  }
+  out.push('');
+  return out;
+}
+
+const TITRE_PUBLIE = "## Ce que les composants d'avant publient";
+
+// The rubric « Rend » of a component's frame (`docs/CADRE.md`, next to its interface), read once:
+// `{ titre }`, its `## Rend` heading, numbered or not (`## 3. Rend`), outside a code block;
+// `{ absent: true }` without the file, null without the rubric.
+function rend(racine, rel) {
+  const fichier = path.join(racine, rel);
+  if (!existsSync(fichier)) return { absent: true };
+  let cloture = null;
+  for (const l of readFileSync(fichier, 'utf8').split('\n')) {
+    const f = /^\s*(```|~~~)/.exec(l);
+    if (cloture) {
+      if (f && f[1] === cloture) cloture = null;
+    } else if (f) {
+      cloture = f[1];
+    } else {
+      const m = /^## ((?:\d+\.\s*)?Rend)\s*$/.exec(l);
+      if (m) return { titre: m[1] };
+    }
+  }
+  return null;
+}
+
+// What the components before <composant> publish, as the section the launcher writes after the
+// instruction of a role agent (scripts/enveloppe/lancer.sh). <composant> is the component's path
+// in the repository at <racine> (`packages/a`, `src/parser`), or `.` for a copy of the whole
+// repository, which the section points to the index of the interfaces. Its providers are the
+// components whose `## Consommateurs` section names it; for each, its line in the index of the
+// interfaces (its heading, its first sentence, its interface), the names of the elements its
+// `## Consommateurs` line declares for the component, never their sentence, which the index of the
+// interfaces holds, and the address of the rubric « Rend » of its frame (`<cadre> § <heading>`),
+// or one line saying the frame or the rubric is missing. A declaration of `*`, an import of the
+// whole component, names no element: its line says the elements are in the index. Each interface
+// and each frame is read once.
+export function publie(racine, composant) {
+  if (composant === '.') {
+    return [
+      TITRE_PUBLIE,
+      '',
+      `Ta copie montre tout le dépôt : \`${SORTIE}\` porte ce que publie chaque composant.`,
+    ].join('\n');
+  }
+  const nom = path.basename(composant);
+  const fournisseurs = interfaces(racine)
+    .map(rel => lire(rel, readFileSync(path.join(racine, rel), 'utf8')))
+    .flatMap(i => {
+      const declare = i.parties.find(p => p.consommateurs?.has(nom));
+      return declare && i.composant !== nom
+        ? [{ ...i, declare: declare.consommateurs.get(nom) }]
+        : [];
+    });
+  if (fournisseurs.length === 0) {
+    return [
+      TITRE_PUBLIE,
+      '',
+      `\`${nom}\` ne dépend d’aucun composant : aucune section « Consommateurs » ne le nomme.`,
+    ].join('\n');
+  }
+  const out = [
+    TITRE_PUBLIE,
+    '',
+    `\`${nom}\` dépend de ces composants, et n’utilise d’eux que les éléments déclarés pour lui. ` +
+      `Tous les éléments d’un composant, chacun avec sa phrase, sont dans \`${SORTIE}\` ; ` +
+      'un élément se lit en entier dans l’interface de son composant, à `<interface> § <son nom>`.',
+  ];
+  const dansIndex = `ses éléments sont dans \`${SORTIE}\``;
+  for (const f of fournisseurs) {
+    const noms = [...f.declare].filter(n => n !== '*').join(', ');
+    let declare = `${noms}.`;
+    if (f.declare.has('*')) {
+      declare = noms
+        ? `${noms}, et \`*\`, un import de tout le composant : ${dansIndex}.`
+        : `\`*\`, un import de tout le composant, sans élément nommé : ${dansIndex}.`;
+    }
+    out.push('', `### ${f.tetiere}`, '', `${f.phrase} (\`${f.rel}\`)`);
+    out.push(`Déclaré pour \`${nom}\` : ${declare}`);
+    if (!f.parties.some(p => !p.consommateurs)) {
+      out.push('Son interface n’a pas de part générée : elle dit elle-même ce qu’elle publie.');
+    }
+    const cadre = path.join(path.dirname(f.rel), 'CADRE.md');
+    const r = rend(racine, cadre);
+    if (r?.absent) out.push(`Son cadre manque : \`${cadre}\` n’existe pas.`);
+    else if (!r) out.push(`Son cadre n’a pas de rubrique « Rend » (\`${cadre}\`).`);
+    else out.push(`Son cadre rend : \`${cadre}\` § ${r.titre}.`);
+  }
+  return out.join('\n');
+}
+
+export function index(racine) {
+  const corps = interfaces(racine).flatMap(rel =>
+    entrees(rel, readFileSync(path.join(racine, rel), 'utf8'))
+  );
+  return [
+    '# Index des interfaces',
+    '',
+    'Généré par `npx grillhouse index-interfaces` depuis les `INTERFACE.md` ; ne pas éditer.',
+    "Une ligne par composant, puis une par élément qu'il fournit ; l'interface donne le détail.",
+    '',
+    ...corps,
+  ].join('\n');
+}
+
+// The command: its exit code. Its output is written before it returns, and Node drains it.
+function commande(racine, args) {
+  const i = args.indexOf('--publie');
+  if (i >= 0) {
+    const composant = args[i + 1];
+    if (!composant) {
+      process.stderr.write('usage: npx grillhouse index-interfaces --publie <composant>\n');
+      return 2;
+    }
+    process.stdout.write(`${publie(racine, composant)}\n`);
+    return 0;
+  }
+  const attendu = index(racine);
+  const cible = path.join(racine, SORTIE);
+  if (!args.includes('--verifier')) {
+    writeFileSync(cible, attendu);
+    return 0;
+  }
+  const present = existsSync(cible) ? readFileSync(cible, 'utf8') : '';
+  const refus =
+    present === attendu
+      ? []
+      : [
+          {
+            fichier: SORTIE,
+            message: `${SORTIE} n'est pas à jour avec les interfaces : npx grillhouse index-interfaces le régénère.`,
+          },
+        ];
+  for (const r of refus) process.stderr.write(`⛔ ${r.message}\n`);
+  ecrireSarif({ garde: 'index-interfaces', racine, constats: refus });
+  return refus.length ? 1 : 0;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  process.exitCode = commande(process.cwd(), process.argv.slice(2));
+}

package/scripts/init.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// A new project, created from the frame's template of a project, as create-turbo creates one from
+// its example. The first Claude session opened in it proposes the initialisation grill.
+//
+//   npx @roomi-fields/grillhouse init <dossier> [<préfixe des tickets>]
+//
+// - The directory is created, or must be empty: a directory that holds a file is refused (exit 1)
+//   and nothing is written in it.
+// - The project receives each file of the template (`templates/projet/` of the frame's files,
+//   scripts/cadre.mjs) at its own path; `_gitignore` and `_npmignore` become `.gitignore` and
+//   `.npmignore`, the names npm neither publishes nor reads in a package, as create-vite names its
+//   templates' files.
+// - Its package.json declares the frame's package, `@roomi-fields/grillhouse` at `^<version>` of
+//   this package, in its devDependencies.
+// - The preparation (scripts/preparation.mjs): git, Beads and its ticket store under the prefix
+//   given, else the directory's name, CodeGraph and its index, the frame's git hooks, `npm install`,
+//   then the plugins its settings declare: the template's declare the frame's,
+//   `grillhouse@roomi-fields`, whose marketplace names the package npm.
+// - Then what the frame writes in a project, as `grillhouse maj` writes it (scripts/grillhouse-maj.mjs):
+//   its turbo.json, the status line of its settings, the version of the frame; and the generated
+//   files (the boundaries' configuration, the interfaces index, run by the project's command). A
+//   plugin or a generator that fails has its line, and the exit code is non-zero once the project
+//   is created.
+// - The project ends on one commit, « chore: initial commit from Roomi's Grillhouse ».
+import { execFileSync } from 'node:child_process';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { CADRE, VERSION } from './cadre.mjs';
+import { mettreAJour, regenerer } from './grillhouse-maj.mjs';
+import { preparer } from './preparation.mjs';
+
+/** The frame's package, as a project declares it. */
+export const PAQUET_DU_CADRE = '@roomi-fields/grillhouse';
+// The template's files whose name the project receives changed.
+const RENOMMES = { _gitignore: '.gitignore', _npmignore: '.npmignore' };
+
+// Runs <commande> in <projet>, its output this process's; throws on a failure.
+const lancer = (projet, commande, args) =>
+  execFileSync(commande, args, { cwd: projet, stdio: 'inherit' });
+
+// Copies the template of a project into <projet>, its files renamed (RENOMMES).
+function copierLeGabarit(projet) {
+  const gabarit = path.join(CADRE, 'templates', 'projet');
+  cpSync(gabarit, projet, { recursive: true });
+  const renommer = dossier => {
+    for (const e of readdirSync(dossier, { withFileTypes: true })) {
+      const f = path.join(dossier, e.name);
+      if (e.isDirectory()) renommer(f);
+      else if (Object.hasOwn(RENOMMES, e.name)) renameSync(f, path.join(dossier, RENOMMES[e.name]));
+    }
+  };
+  renommer(projet);
+  const fichier = path.join(projet, 'package.json');
+  const p = JSON.parse(readFileSync(fichier, 'utf8'));
+  p.devDependencies = Object.fromEntries(
+    Object.entries({ ...(p.devDependencies ?? {}), [PAQUET_DU_CADRE]: `^${VERSION}` }).sort(
+      ([a], [b]) => a.localeCompare(b, 'en')
+    )
+  );
+  writeFileSync(fichier, `${JSON.stringify(p, null, 2)}\n`);
+}
+
+/** Creates the project at <dossier>; returns the lines of failure once it is created. */
+export function initialiser(dossier, prefixe) {
+  const projet = path.resolve(dossier);
+  if (existsSync(projet) && readdirSync(projet).length > 0) {
+    throw new Error(
+      `${dossier} n'est pas vide : grillhouse init crée un projet neuf. Un projet existant adopte le cadre par npm install -D ${PAQUET_DU_CADRE}, puis npx grillhouse maj.`
+    );
+  }
+  mkdirSync(projet, { recursive: true });
+  copierLeGabarit(projet);
+  const greffons = preparer(projet, prefixe);
+  mettreAJour(projet, CADRE);
+  const lignes = [...greffons, ...regenerer(projet, { tous: true })];
+  lancer(projet, 'git', ['add', '-A']);
+  // The initial commit carries no ticket: the frame's commit-msg hook has nothing to judge.
+  lancer(projet, 'git', [
+    'commit',
+    '-q',
+    '--no-verify',
+    '-m',
+    "chore: initial commit from Roomi's Grillhouse",
+  ]);
+  return lignes;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const [dossier, prefixe, ...reste] = process.argv.slice(2);
+  if (!dossier || dossier.startsWith('-') || reste.length > 0) {
+    process.stderr.write(
+      'Usage : npx @roomi-fields/grillhouse init <dossier> [<préfixe des tickets>]\n'
+    );
+    process.exitCode = 2;
+  } else {
+    try {
+      const lignes = initialiser(dossier, prefixe);
+      for (const l of lignes) process.stderr.write(`${l}\n`);
+      process.stdout.write(
+        `Projet créé dans ${dossier}. Ouvre Claude Code dans ce dossier : la première séance propose le grill d'initialisation.\n`
+      );
+      if (lignes.length > 0) process.exitCode = 1;
+    } catch (e) {
+      process.stderr.write(`⛔ ${e.message}\n`);
+      process.exitCode = 1;
+    }
+  }
+}

package/scripts/integration/file-attente.mjs

@@ -0,0 +1,61 @@
+// The waiting side of the integration, kept in git's common directory: the queue's entries, and
+// the git directory the integration's locks live in (taken through scripts/verrou-de-fichier.mjs).
+// The integration writes an entry when it commits a ticket on its branch; the queue
+// (scripts/integration/file.mjs) reads them in their order of arrival.
+//
+// - An entry is one JSON file `<arrival>-<process>.json` under `file-integration/` holding the
+//   branch and its one ticket; the name sorts in the order of arrival. One branch has one
+//   entry: writing it again replaces the earlier one.
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+// The git common directory of the repository at <racine>, absolute.
+export function dossierCommun(racine) {
+  return spawnSync(
+    'git',
+    ['-C', racine, 'rev-parse', '--path-format=absolute', '--git-common-dir'],
+    { encoding: 'utf8' }
+  ).stdout.trim();
+}
+
+const dossierEntrees = racine => path.join(dossierCommun(racine), 'file-integration');
+
+// The entries waiting, in their order of arrival: { fichier, branche, ticket }.
+export function lireEntrees(racine) {
+  const dossier = dossierEntrees(racine);
+  let noms = [];
+  try {
+    noms = readdirSync(dossier)
+      .filter(n => n.endsWith('.json'))
+      .sort();
+  } catch {
+    return [];
+  }
+  const entrees = [];
+  for (const n of noms) {
+    try {
+      const e = JSON.parse(readFileSync(path.join(dossier, n), 'utf8'));
+      entrees.push({ fichier: path.join(dossier, n), branche: e.branche, ticket: e.ticket });
+    } catch {
+      // an entry being written is read at the next turn
+    }
+  }
+  return entrees;
+}
+
+// Puts the branch at the end of the queue, replacing its earlier entry.
+export function inscrireEntree(racine, branche, ticket) {
+  for (const e of lireEntrees(racine)) {
+    if (e.branche === branche) rmSync(e.fichier, { force: true });
+  }
+  const dossier = dossierEntrees(racine);
+  mkdirSync(dossier, { recursive: true });
+  const arrivee = String(Date.now()).padStart(15, '0');
+  const fichier = path.join(dossier, `${arrivee}-${String(process.pid).padStart(8, '0')}.json`);
+  writeFileSync(fichier, JSON.stringify({ branche, ticket }), { flag: 'wx' });
+}
+
+export function retirerEntree(entree) {
+  rmSync(entree.fichier, { force: true });
+}