@sylad/cadence 0.7.0 → 0.9.0

package/dist/deliver.js

@@ -1,11 +1,16 @@
-import { execFileSync, spawnSync } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
+import { constants } from 'node:os';
 import { parse } from 'yaml';
+import { onTermination, readProcs, SIGNAL_GRACE_MS, TreeTracker } from './proc.js';
+import { isPlanOnly } from './audit.js';
 import { headSha, isAncestor, onRemote, readCommits, repoStatus, resolveCommit } from './git.js';
+import { citedRefs } from './link.js';
 import { RafError } from './plan.js';
 import { appendDelivery, lastDelivery, lockAlive, lockPath, readLock, releaseLock, removeStaleLock, writeLock } from './state.js';
 const POLL_CI = 15_000;
 const CI_APPEAR = 300_000;
-const POLL_VERIFY = 10_000;
+/** Intervalle de réessai d'une vérification : celui de deliver ET de `cadence verify --retry`. */
+export const POLL_VERIFY = 10_000;
 const CI_OK = new Set(['success', 'skipped', 'neutral']);
 const GH_TIMEOUT = 60_000;
 export const TIMED_OUT = 124;
@@ -90,8 +95,8 @@ export function parseDeliverConfig(text, file) {
         deployTimeout: seconds('deployTimeout', 1800),
     };
 }
-/** Dépendances réelles : sh, gh, fetch, horloge. */
-export function realDeps(root) {
+/** Dépendances réelles : sh, gh, fetch, horloge. `read` : le relevé des processus du suivi (injectable pour les tests). */
+export function realDeps(root, read = readProcs) {
     const gh = (args) => {
         try {
             return execFileSync('gh', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: GH_TIMEOUT });
@@ -106,18 +111,51 @@ export function realDeps(root) {
         }
     };
     return {
-        exec: (cmd, env, timeoutMs) => {
-            const r = spawnSync('sh', ['-c', cmd], {
+        exec: (cmd, env, timeoutMs) => new Promise((resolve) => {
+            const child = spawn('sh', ['-c', cmd], {
                 cwd: root,
                 env: { ...process.env, ...env },
                 stdio: ['ignore', 'inherit', 'inherit'],
-                timeout: Math.max(1_000, timeoutMs),
-                killSignal: 'SIGKILL',
+                // PAS de groupe détaché : la commande reste dans le groupe de premier plan et la session de cadence.
+                // Ctrl-C et le raccrochage l'atteignent avec cadence, et /dev/tty reste là pour ssh, sudo, pinentry.
             });
-            if (r.error?.code === 'ETIMEDOUT' || r.signal)
-                return TIMED_OUT;
-            return r.status ?? 1;
-        },
+            const pid = child.pid;
+            if (pid === undefined) {
+                child.once('error', () => resolve(127));
+                return;
+            }
+            // L'arbre de la commande est suivi pendant toute son exécution (relevé périodique, pid + heure de
+            // démarrage) : un enfant dont le parent meurt reste connu. Au délai, ou si cadence est tué (Ctrl-C,
+            // SIGTERM, raccrochage), TOUS les processus suivis encore vivants meurent avant que cadence ne rende la
+            // main ou ne meure — sh fait un fork par commande, et un descendant survivant livrerait encore pendant
+            // qu'une seconde livraison prend le verrou libéré ou périmé. Ctrl-C et raccrochage : l'arbre a déjà
+            // reçu le signal du terminal, un court délai de grâce laisse finir ses trap (et git son index.lock)
+            // avant le kill ; SIGTERM (à cadence seul) et le délai : kill immédiat.
+            const tree = new TreeTracker(pid, read, () => process.stderr.write('deliver : relevé des processus indisponible — le kill n\'est dégradé que tant que le relevé échoue : seule la commande racine sera tuée, ses descendants survivront\n'), () => process.stderr.write('deliver : kill replié sur la commande racine faute de relevé des processus — des descendants ont pu survivre\n'));
+            // Terminaison en cours : exec ne rend pas la main avant qu'elle ne soit finie — sinon deliver libère
+            // le verrou pendant la grâce, alors que des descendants tournent encore.
+            let ending = null;
+            const forget = onTermination((sig) => (ending = sig === 'SIGTERM' ? Promise.resolve(tree.kill()) : tree.end(SIGNAL_GRACE_MS)));
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                tree.kill();
+            }, Math.max(1_000, timeoutMs));
+            child.once('exit', (code, signal) => {
+                clearTimeout(timer);
+                tree.rootExited(); // son pid peut être repris : plus d'adoption tardive de la racine pendant la grâce
+                const result = timedOut ? TIMED_OUT : signal ? 128 + (constants.signals[signal] ?? 0) : (code ?? 1);
+                const settle = () => {
+                    tree.stop();
+                    forget();
+                    resolve(result);
+                };
+                if (ending)
+                    void ending.then(settle);
+                else
+                    settle();
+            });
+        }),
         gh: (sha) => JSON.parse(gh(['run', 'list', '--commit', sha, '--json', 'name,status,conclusion'])),
         ghReady: () => {
             try {
@@ -128,8 +166,8 @@ export function realDeps(root) {
                 return e.message;
             }
         },
-        fetch: async (url) => {
-            const res = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(20_000) });
+        fetch: async (url, timeoutMs = 20_000) => {
+            const res = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(Math.max(1_000, Math.min(20_000, timeoutMs))) });
             return { status: res.status, text: await res.text() };
         },
         sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
@@ -143,7 +181,7 @@ function substitute(text, sha) {
 function shellQuote(arg) {
     return /^[A-Za-z0-9_@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
 }
-function describeCheck(c, sha) {
+export function describeCheck(c, sha) {
     if (c.command !== undefined)
         return c.command;
     return `GET ${substitute(c.url, sha)} → ${c.status ?? 200}${c.contains === undefined ? '' : `, contient « ${substitute(c.contains, sha)} »`}`;
@@ -217,7 +255,7 @@ export async function deliver(ctx, deps) {
         out(`Livraison de ${env.CADENCE_SHORT} (${branch})`);
         if (script !== null) {
             out(`→ script du projet : ${script}`);
-            const code = deps.exec(script, env, config.deployTimeout * 1000);
+            const code = await deps.exec(script, env, config.deployTimeout * 1000);
             if (code !== 0)
                 return fail(`script de livraison en échec (${codeText(code)}) : ${script}`);
         }
@@ -227,7 +265,7 @@ export async function deliver(ctx, deps) {
                 return fail(ci);
             for (const [i, cmd] of config.deploy.entries()) {
                 out(`→ déploiement ${i + 1}/${config.deploy.length} : ${cmd}`);
-                const code = deps.exec(cmd, env, config.deployTimeout * 1000);
+                const code = await deps.exec(cmd, env, config.deployTimeout * 1000);
                 if (code !== 0)
                     return fail(`déploiement en échec (${codeText(code)}) : ${cmd}`);
             }
@@ -261,7 +299,7 @@ async function waitCi(ctx, deps, sha, env) {
         return null;
     if (typeof ci === 'object') {
         ctx.out(`→ CI : ${ci.command}`);
-        const code = deps.exec(ci.command, env, ciTimeout * 1000);
+        const code = await deps.exec(ci.command, env, ciTimeout * 1000);
         return code === 0 ? null : `CI en échec (${codeText(code)}) : ${ci.command}`;
     }
     ctx.out(`→ CI : attente des runs GitHub de ${sha.slice(0, 7)}`);
@@ -306,13 +344,14 @@ async function waitCi(ctx, deps, sha, env) {
         await deps.sleep(POLL_CI);
     }
 }
-async function tryCheck(c, deps, sha, env, budgetMs) {
+/** Un essai d'une vérification : cause de l'échec, ou null. Partagé par deliver et `cadence verify`. */
+export async function tryCheck(c, deps, sha, env, budgetMs) {
     if (c.command !== undefined) {
-        const code = deps.exec(c.command, env, budgetMs);
+        const code = await deps.exec(c.command, env, budgetMs);
         return code === 0 ? null : codeText(code);
     }
     try {
-        const res = await deps.fetch(substitute(c.url, sha));
+        const res = await deps.fetch(substitute(c.url, sha), budgetMs);
         const want = c.status ?? 200;
         if (res.status !== want)
             return `statut ${res.status} (attendu ${want})`;
@@ -324,22 +363,32 @@ async function tryCheck(c, deps, sha, env, budgetMs) {
         return `erreur réseau : ${e.message}`;
     }
 }
+/**
+ * UNE boucle de réessai, pour deliver et pour `cadence verify` : essaie, puis réessaie toutes les POLL_VERIFY
+ * tant que `until` n'est pas atteint. `attemptMs()` donne le délai de chaque essai. Rend la dernière cause
+ * d'échec, ou null dès que l'effet est celui attendu.
+ */
+export async function retryCheck(c, deps, sha, env, until, attemptMs) {
+    for (;;) {
+        const reason = await tryCheck(c, deps, sha, env, attemptMs());
+        if (reason === null)
+            return null;
+        const left = until - deps.now();
+        if (left <= 0)
+            return reason;
+        // jamais au-delà du délai : une commande tuée « à l'échéance » peut rendre la main un rien avant elle
+        await deps.sleep(Math.min(POLL_VERIFY, left));
+    }
+}
 /** Chaque vérification est réessayée jusqu'au délai commun ; message d'échec ou null. */
 async function verifyAll(ctx, deps, sha, env) {
     const deadline = deps.now() + ctx.config.verifyTimeout * 1000;
     for (const [i, c] of ctx.config.verify.entries()) {
         const label = describeCheck(c, sha);
         ctx.out(`→ vérification ${i + 1}/${ctx.config.verify.length} : ${label}`);
-        for (;;) {
-            const reason = await tryCheck(c, deps, sha, env, deadline - deps.now());
-            if (reason === null)
-                break;
-            const left = deadline - deps.now();
-            if (left <= 0)
-                return `vérification en échec après ${ctx.config.verifyTimeout} s : ${label} — ${reason}`;
-            // jamais au-delà du délai : une commande tuée « à l'échéance » peut rendre la main un rien avant elle
-            await deps.sleep(Math.min(POLL_VERIFY, left));
-        }
+        const reason = await retryCheck(c, deps, sha, env, deadline, () => deadline - deps.now());
+        if (reason !== null)
+            return `vérification en échec après ${ctx.config.verifyTimeout} s : ${label} — ${reason}`;
     }
     return null;
 }
@@ -361,7 +410,9 @@ function deliveredLots(ctx, prev, sha) {
     const known = new Set((ctx.plan.readonly ? lots.filter((l) => l.status === 'doing') : lots).map((l) => l.id));
     const ids = new Set();
     for (const c of readCommits(ctx.root, { range: `${prev}..${sha}` })) {
-        for (const r of ctx.plan.refs(`${c.subject}\n${c.body}`))
+        if (isPlanOnly(c.sha, ctx.plan, ctx.root))
+            continue; // entretien du plan : ne livre rien, même s'il cite des lots
+        for (const r of citedRefs(c, ctx.plan.refs))
             if (known.has(r.lot))
                 ids.add(r.lot);
     }

package/dist/git.js

@@ -45,9 +45,19 @@ export function hooksDir(cwd) {
     const dir = resolve(cwd, git(cwd, ['rev-parse', '--git-path', 'hooks']).trim());
     return basename(dir) === '_' && basename(dirname(dir)) === '.husky' ? dirname(dir) : dir;
 }
-/** Fichiers modifiés par un commit, relatifs à la racine du dépôt. */
+/** Fichiers modifiés par un commit, relatifs à la racine du dépôt (noms accentués ou à espaces compris). */
 export function changedFiles(cwd, sha) {
-    return git(cwd, ['diff-tree', '--root', '--no-commit-id', '--name-only', '-r', sha]).split('\n').filter(Boolean);
+    // -z : noms séparés par NUL, jamais échappés ; quotepath=off en plus pour les sorties qui citeraient quand même.
+    return git(cwd, ['-c', 'core.quotepath=off', 'diff-tree', '--root', '--no-commit-id', '--name-only', '-r', '-z', sha]).split('\0').filter(Boolean);
+}
+/** Contenu d'un fichier à un commit (`<sha>^` pour l'état d'avant) ; null s'il n'existe pas à ce commit. */
+export function fileAt(cwd, rev, file) {
+    try {
+        return git(cwd, ['show', `${rev}:${file}`]);
+    }
+    catch {
+        return null;
+    }
 }
 function tryGit(cwd, args) {
     try {

package/dist/link.js

@@ -1,6 +1,20 @@
 export function isMerge(c) {
     return /^Merge\b/.test(c.subject);
 }
+/** Portée d'un sujet « type(L24,L25)! : … » ; null sans parenthèses. */
+function scopeOf(subject) {
+    return /^[\w-]+\(([^)]*)\)!?\s*:/.exec(subject)?.[1] ?? null;
+}
+/**
+ * Références qui décident à quels lots appartient un commit : celles de la portée « type(L24) » quand elle
+ * en cite ; sinon, celles du message entier. Les mentions en passage (« page équipe (L27) »), les plages
+ * (« L28–L31 ») et le corps du message ne comptent donc pas dès que la portée désigne les lots.
+ */
+export function citedRefs(c, refsOf) {
+    const scope = scopeOf(c.subject);
+    const scoped = scope === null ? [] : refsOf(scope);
+    return scoped.length > 0 ? scoped : refsOf(`${c.subject}\n${c.body}`);
+}
 /** `refs` lit les références d'un message : `plan.refs`. */
 export function linkCommits(lots, commits, refsOf) {
     const ids = new Set(lots.map((l) => l.id));
@@ -9,7 +23,7 @@ export function linkCommits(lots, commits, refsOf) {
     const orphans = [];
     const unknown = [];
     for (const c of commits) {
-        const refs = refsOf(`${c.subject}\n${c.body}`);
+        const refs = citedRefs(c, refsOf);
         if (refs.length === 0) {
             if (!isMerge(c))
                 orphans.push(c);

package/dist/orchestrate/briefs.js

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RafError } from '../plan.js';
+/** Gabarits livrés avec le paquet (à la racine, à côté de dist/ et src/). */
+export const TEMPLATES_DIR = fileURLToPath(new URL('../../templates/orchestrate', import.meta.url));
+const FILES = {
+    implement: 'implement.md',
+    fix: 'fix.md',
+    'fix-minors': 'fix-minors.md',
+    review: 'review.md',
+    ux: 'ux.md',
+    'review-small': 'review-small.md',
+    'review-recheck': 'review-recheck.md',
+};
+/** Lit tous les gabarits du dossier. Un gabarit absent est une erreur, avant que quoi que ce soit ne parte. */
+export function loadTemplates(dir = TEMPLATES_DIR) {
+    const out = {};
+    for (const [name, file] of Object.entries(FILES)) {
+        try {
+            out[name] = readFileSync(join(dir, file), 'utf8');
+        }
+        catch (e) {
+            throw new RafError(`gabarit ${file} illisible dans ${dir} : ${e.message}`);
+        }
+    }
+    return out;
+}
+/**
+ * Rend le gabarit d'une étape par substitution de `{{nom}}`. Un nom sans valeur est une erreur.
+ * `source` : un instantané (`loadTemplates`, ce que fait une vague) ou un dossier lu à l'appel.
+ */
+export function renderBrief(kind, vars, source = TEMPLATES_DIR) {
+    const text = typeof source === 'string' ? loadTemplates(source)[kind] : source[kind];
+    const out = text.replace(/\{\{(\w+)\}\}/g, (_m, name) => {
+        const v = vars[name];
+        if (v === undefined)
+            throw new RafError(`gabarit ${FILES[kind]} : valeur manquante pour {{${name}}}`);
+        return v;
+    });
+    // Un marqueur vide ne laisse pas de trou : lignes vides en double ramenées à une.
+    return `${out.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim()}\n`;
+}
+/** `{{objectif}}` : le titre du lot, ses notes et ses sous-tâches — Sylvain n'écrit rien d'autre. */
+export function objective(lot) {
+    const lines = [`${lot.title}`];
+    if (lot.notes.length)
+        lines.push('', 'Notes of the lot (decisions included):', ...lot.notes.map((n) => `- ${n.date}: ${n.text}`));
+    if (lot.tasks.length)
+        lines.push('', 'Sub-tasks:', ...lot.tasks.map((t) => `- ${t.id} [${t.status}] ${t.title}`));
+    return lines.join('\n');
+}