@rungs/cli 0.3.0 → 0.4.0

package/src/cli.ts

@@ -3,16 +3,18 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 import { auditModules, loadAllModules } from './manifest.ts';
 import { detect, scanRepo } from './detect.ts';
-import { addModule, adoptableGates, blockedByParadigm, registerGates, resolveInstallOrder, writeInstallRecord } from './add.ts';
-import { render, writeReport, type Harness } from './render.ts';
+import { addModule, adoptableGates, blockedByConflict, blockedByParadigm, moduleEmissionCandidates, preflightModuleEmissions, prospectiveRuleEmissions, type ConflictBlock, registerGates, resolveInstallOrder, writeInstallRecord } from './add.ts';
+import { preflightRender, render, writeReport, type Harness } from './render.ts';
 import { resolveParams } from './substitute.ts';
 import { appendLedger, type GateRun, ledgerQuestions, loadRegistry, runGates, UnknownTierError } from './check.ts';
 import { applyUpgrade, eject, planUpgrade, PROFILES, readRecord, setupGit } from './lifecycle.ts';
 import { explain, IN_SCOPE as EXPLAINABLE } from './explain.ts';
-import { applyArchive, planArchive } from './backlog.ts';
+import { applyArchive, planArchive, resolveArchiveTree } from './backlog.ts';
 import { land, preflight, sessionStart, worktrees } from './concurrency.ts';
 import { existsSync } from 'node:fs';
 import type { DetectResult, Manifest } from './types.ts';
+import { UnsafeEmittedPathError } from './emitted-path.ts';
+import { COMMANDS, FLAGS } from './help.ts';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const MODULES = join(HERE, '..', 'modules');
@@ -26,6 +28,12 @@ const c = {
   cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
 };
 
+function pathRefusal(error: unknown): number {
+  if (!(error instanceof UnsafeEmittedPathError)) throw error;
+  console.log(c.red(`\n  refused: ${error.message}\n`) + c.dim('  Nothing was written. Fix the named path or repository alias and retry.\n'));
+  return 1;
+}
+
 const STATE_LABEL: Record<DetectResult['state'], string> = {
   absent: c.dim('absent'),
   'ours-current': c.green('ours'),
@@ -40,8 +48,17 @@ function cmdModules(showParams = false) {
   console.log(c.bold(`\n${mods.length} modules\n`));
   for (const m of mods) {
     const deps = m.requires.length ? c.dim(` ← ${m.requires.join(', ')}`) : '';
-    console.log(`  ${c.bold(m.name.padEnd(14))} rung ${m.rung}${deps}`);
+    // A `designed` module is marked wherever a module is named, because a
+    // distinction the manifest declares and no surface prints is the field
+    // being unread all over again (F-038, and F-037 nearly repeated it). The
+    // extracted case is unmarked: it is what every bundled module is, and a
+    // badge on all fifteen would carry no information.
+    const designed = m.provenance.kind === 'designed' ? c.yellow('  designed') : '';
+    console.log(`  ${c.bold(m.name.padEnd(14))} rung ${m.rung}${deps}${designed}`);
     console.log(`  ${' '.repeat(14)} ${c.dim(m.summary)}`);
+    if (designed) {
+      console.log(`  ${' '.repeat(14)} ${c.dim(`not extracted — ${firstSentence(m.provenance.rationale ?? '')}`)}`);
+    }
     // Rendered from the manifest at the moment it is asked for, never written down. A committed
     // parameter table would be correct the day it was generated and silently wrong the day a
     // default moved — which is the failure this flag exists to answer (WI-006).
@@ -84,7 +101,12 @@ function cmdDoctor(target: string, doExplain = false) {
   console.log(c.bold(`\nrungs doctor — ${root}\n`));
 
   const files = scanRepo(root);
-  const record = readRecord(root);
+  let record;
+  try {
+    record = readRecord(root);
+  } catch (error) {
+    return pathRefusal(error);
+  }
   console.log(
     c.dim(`  scanned ${files.length} files`) +
       (record ? c.dim(` · installed ${Object.keys(record.modules).length} module(s)`) : c.dim(' · not a rungs repo')) +
@@ -95,10 +117,15 @@ function cmdDoctor(target: string, doExplain = false) {
     Object.entries(record?.modules ?? {}).flatMap(([n, e]) => (e.params ? [[n, e.params]] : [])),
   ), root);
   const skillsDir = record?.harnesses.includes('claude') === false ? '.agents/skills' : '.claude/skills';
-  const results = mods.map((m) => {
-    const installed = record?.modules[m.name];
-    return detect(m, root, files, installed ? { ...installed, skillsDir, params_all: params } : undefined);
-  });
+  let results;
+  try {
+    results = mods.map((m) => {
+      const installed = record?.modules[m.name];
+      return detect(m, root, files, installed ? { ...installed, skillsDir, params_all: params } : undefined);
+    });
+  } catch (error) {
+    return pathRefusal(error);
+  }
   const byState = (s: DetectResult['state']) => results.filter((r) => r.state === s);
 
   for (const r of results) {
@@ -386,6 +413,41 @@ function cmdAdd(names: string[], root: string, dryRun: boolean, harnesses: Harne
     console.log(c.dim('      You will have two systems for one job. That is a choice, not a merge.\n'));
   }
 
+  // F-038: a module's `[conflicts]` was parsed and read by nothing, so a
+  // declared incompatibility installed in silence. It refuses the same way a
+  // paradigm does — state it and stop — but it is computed separately, because
+  // a paradigm is *inferred from files* and a conflict is *declared by an
+  // author*, and a refusal should say which of the two it is.
+  //
+  // What counts as present: what the repo already has, plus everything else in
+  // this install set. Two modules that cannot coexist cannot arrive together
+  // either.
+  let record;
+  try {
+    record = readRecord(root);
+  } catch (error) {
+    return pathRefusal(error);
+  }
+  const present = new Set([...Object.keys(record?.modules ?? {}), ...order.map((m) => m.name)]);
+  const declared = blockedByConflict(order, present, mods);
+  const conflictOverride = flags.has('--confirm-conflict');
+
+  // Computed even when overridden, and printed — for the reason the paradigm
+  // override just above says: an override that prints nothing is
+  // indistinguishable from finding nothing, and the two want opposite
+  // follow-ups.
+  if (conflictOverride && declared.size) {
+    for (const [name, clash] of declared) {
+      if (clash.cause !== name) continue;
+      console.log(
+        c.yellow(`  ${name}: installing alongside ${clash.with}, which it declares a conflict with`) +
+          c.dim(' — --confirm-conflict'),
+      );
+    }
+    console.log(c.dim('      The author said these two do not coexist. You are overruling them, not merging them.\n'));
+  }
+  const conflicts = conflictOverride ? new Map<string, ConflictBlock>() : declared;
+
   // Re-resolve from what survives rather than filtering `order` in place. A
   // dependency is only ever pulled in *for* something; `add backlog` on an
   // issue-tracker repo was still writing `instructions` and `gates`, which
@@ -393,7 +455,7 @@ function cmdAdd(names: string[], root: string, dryRun: boolean, harnesses: Harne
   // refused. Recomputing the closure drops them, and keeps anything a *surviving*
   // request still needs.
   let toInstall = order;
-  if (blocked.size) {
+  if (blocked.size || conflicts.size) {
     for (const mod of order) {
       const cause = blocked.get(mod.name);
       if (!cause) continue;
@@ -407,18 +469,68 @@ function cmdAdd(names: string[], root: string, dryRun: boolean, harnesses: Harne
         console.log(c.yellow(`  ${mod.name}: not installed — it requires ${cause}.`));
       }
     }
-    toInstall = resolveInstallOrder(names.filter((n) => !blocked.has(n)), mods).order;
-    const dropped = order.filter((m) => !toInstall.includes(m) && !blocked.has(m.name));
+    for (const mod of order) {
+      const clash = conflicts.get(mod.name);
+      // A module refused by both is reported once, under the paradigm, which
+      // carries the more specific evidence — a matched path.
+      if (!clash || blocked.has(mod.name)) continue;
+      if (clash.cause === mod.name) {
+        const declarer = mod.conflicts.includes(clash.with) ? mod.name : clash.with;
+        console.log(c.yellow(`  ${mod.name}: conflicts with ${clash.with}`));
+        console.log(
+          c.dim(`      declared by ${declarer}`) +
+            c.dim(present.has(clash.with) && !order.some((m) => m.name === clash.with) ? ', which this repo already has' : ', and both were requested'),
+        );
+      } else {
+        console.log(c.yellow(`  ${mod.name}: not installed — it requires ${clash.cause}.`));
+      }
+    }
+    const refused = new Set([...blocked.keys(), ...conflicts.keys()]);
+    toInstall = resolveInstallOrder(names.filter((n) => !refused.has(n)), mods).order;
+    const dropped = order.filter((m) => !toInstall.includes(m) && !refused.has(m.name));
     if (dropped.length) {
       console.log(c.dim(`      ${dropped.map((m) => m.name).join(', ')} not written — pulled in only for the above`));
     }
+    const escapes = [blocked.size ? '--confirm-paradigm' : '', conflicts.size ? '--confirm-conflict' : ''].filter(Boolean);
     console.log(
-      c.dim(`\n  Pass --confirm-paradigm to install anyway.`) +
+      c.dim(`\n  Pass ${escapes.join(' / ')} to install anyway.`) +
         (toInstall.length ? c.dim(' Continuing with the rest.\n') : c.dim(' Nothing was written.\n')),
     );
     if (!toInstall.length) return 1;
   }
 
+  // A module nobody paid for is a different thing to install than one extracted
+  // from a repo that did, and the person typing `add` is who should be told
+  // (F-037). One line, at the only moment it changes a decision.
+  for (const mod of toInstall.filter((m) => m.provenance.kind === 'designed')) {
+    console.log(
+      c.yellow(`  ${mod.name}: designed, not extracted`) +
+        c.dim(` — ${firstSentence(mod.provenance.rationale ?? '')}`),
+    );
+  }
+
+  // This is one operation, even though files, gates, the install record and
+  // harness renderings are applied in phases.  Validate every selected module
+  // and every post-phase output before the first module can write.
+  const actualInstall = toInstall.filter(
+    (mod) => !(mod.threshold?.confirm && !dryRun && !flags.has('--confirm-threshold')),
+  );
+  try {
+    preflightModuleEmissions(actualInstall, root, params, skillsDir);
+    preflightRender(
+      root,
+      harnesses,
+      prospectiveRuleEmissions(actualInstall, params, skillsDir),
+      [
+        ...moduleEmissionCandidates(actualInstall, params, skillsDir),
+        { moduleName: 'rungs', target: '.ai/gates.toml', shared: true, writeExisting: true },
+        { moduleName: 'rungs', target: '.ai/rungs.toml', writeExisting: true },
+      ],
+    );
+  } catch (error) {
+    return pathRefusal(error);
+  }
+
   const installed: Manifest[] = [];
   const wrote = new Map<string, Set<string>>();
   for (const mod of toInstall) {
@@ -463,7 +575,7 @@ function cmdAdd(names: string[], root: string, dryRun: boolean, harnesses: Harne
   }
 
   if (!dryRun) {
-    writeInstallRecord(root, order, params, harnesses, stamp, skillsDir, wrote);
+    writeInstallRecord(root, installed, params, harnesses, stamp, skillsDir, wrote);
     const entries = render(root, harnesses);
     writeReport(root, entries, harnesses, stamp);
     console.log(
@@ -477,6 +589,11 @@ function cmdAdd(names: string[], root: string, dryRun: boolean, harnesses: Harne
 }
 
 function cmdRender(root: string, harnesses: Harness[], stamp: string) {
+  try {
+    preflightRender(root, harnesses);
+  } catch (error) {
+    return pathRefusal(error);
+  }
   const entries = render(root, harnesses);
   writeReport(root, entries, harnesses, stamp);
   console.log(c.bold(`\nrungs render — ${root}\n`));
@@ -514,11 +631,18 @@ function landRunner(dir: string, only?: ReadonlySet<string>) {
   const failing = runs.filter((r) => r.status === 'fail' || r.status === 'error');
   return {
     pass: runs.filter((r) => r.status === 'pass').length,
-    // `file: message`, so the same broken link in the same file is the same
-    // finding across two runs, and a *new* one is visibly not.
+    // Keep a stable comparison identity separate from the operator-facing
+    // diagnostic. `file: identity` makes the same broken link in the same file
+    // the same finding across runs, while command diagnostics can stay complete.
     failing: failing.map((r) => ({
       id: r.id,
-      findings: r.findings.map((f) => `${f.file ? `${f.file}: ` : ''}${f.message}`),
+      findings: r.findings.map((f) => {
+        const prefix = f.file ? `${f.file}: ` : '';
+        return {
+          identity: `${prefix}${f.identity ?? f.message}`,
+          diagnostic: `${prefix}${f.message}`,
+        };
+      }),
     })),
   };
 }
@@ -588,7 +712,7 @@ function cmdCheck(root: string, tier: string | undefined, stamp: string) {
         (r.examined ? c.dim(`  ${r.examined} examined`) : ''),
     );
     for (const f of r.findings.slice(0, 4)) {
-      console.log(`         ${c.dim(f.file ? `${f.file}: ` : '')}${f.message}`);
+      console.log(`         ${c.dim(f.file ? `${f.file}: ` : '')}${f.message.replace(/\n/g, '\n         ')}`);
     }
     if (r.findings.length > 4) console.log(c.dim(`         …and ${r.findings.length - 4} more`));
   }
@@ -640,16 +764,29 @@ function reportLedger(root: string) {
 }
 
 function cmdBacklogArchive(root: string, dryRun: boolean) {
-  const record = readRecord(root);
+  let record;
+  try {
+    record = readRecord(root);
+  } catch (error) {
+    return pathRefusal(error);
+  }
   const configured = record?.modules['backlog']?.params?.root;
   const backlogRoot = `docs/${configured ?? 'backlog'}`;
 
-  if (!existsSync(join(root, ...backlogRoot.split('/'), 'items'))) {
+  let tree;
+  let plan;
+  try {
+    tree = resolveArchiveTree(root, backlogRoot);
+    plan = planArchive(root, backlogRoot);
+  } catch (error) {
+    return pathRefusal(error);
+  }
+
+  if (!tree.itemsExists) {
     console.log(c.red(`\n  no backlog at ${backlogRoot}/items\n`));
     return 1;
   }
 
-  const plan = planArchive(root, backlogRoot);
   console.log(c.bold(`\nrungs backlog archive → ${root}${dryRun ? c.yellow('  (dry run)') : ''}\n`));
 
   for (const h of plan.held) console.log(c.yellow(`  held  ${h.file}`) + c.dim(` — ${h.reason}`));
@@ -679,14 +816,24 @@ function cmdBacklogArchive(root: string, dryRun: boolean) {
     return 0;
   }
 
-  applyArchive(root, plan);
+  try {
+    applyArchive(root, plan);
+  } catch (error) {
+    return pathRefusal(error);
+  }
   console.log(c.green(`\n  archived ${plan.moves.length} item(s)`) + c.dim(' — ids stay spent and every citation still resolves.'));
   console.log(c.dim('  Run `rungs check` to confirm.\n'));
   return 0;
 }
 
 function cmdInit(root: string, profile: string, dryRun: boolean, harnesses: Harness[], stamp: string) {
-  if (readRecord(root)) {
+  let existing;
+  try {
+    existing = readRecord(root);
+  } catch (error) {
+    return pathRefusal(error);
+  }
+  if (existing) {
     console.log(
       c.yellow('\n  this repo is already initialised.') +
         c.dim(' Use `rungs add <module>` to install more, or `rungs upgrade`.\n'),
@@ -703,13 +850,23 @@ function cmdInit(root: string, profile: string, dryRun: boolean, harnesses: Harn
 }
 
 function cmdUpgrade(root: string, apply: boolean) {
-  const record = readRecord(root);
+  let record;
+  try {
+    record = readRecord(root);
+  } catch (error) {
+    return pathRefusal(error);
+  }
   if (!record) {
     console.log(c.yellow('\n  not a rungs repo — nothing to upgrade.\n'));
     return 1;
   }
   const mods = loadAllModules(MODULES);
-  const plan = planUpgrade(root, mods, record);
+  let plan;
+  try {
+    plan = planUpgrade(root, mods, record);
+  } catch (error) {
+    return pathRefusal(error);
+  }
   console.log(c.bold(`\nrungs upgrade — ${root}${apply ? '' : c.yellow('  (preview)')}\n`));
 
   let stale = 0;
@@ -730,7 +887,13 @@ function cmdUpgrade(root: string, apply: boolean) {
   // old block — F-016, measured on a scratch consumer where `session` 1.1.0 →
   // 1.2.0 added a gate and `rungs check` went on running the previous twenty.
   if (apply) {
-    const { written, gates, recorded } = applyUpgrade(root, mods, record, plan);
+    let result;
+    try {
+      result = applyUpgrade(root, mods, record, plan);
+    } catch (error) {
+      return pathRefusal(error);
+    }
+    const { written, gates, recorded } = result;
     const parts = [
       written ? `${written} file(s)` : '',
       gates ? `${gates} gate registration(s)` : '',
@@ -747,7 +910,13 @@ function cmdUpgrade(root: string, apply: boolean) {
 }
 
 function cmdEject(root: string, dryRun: boolean) {
-  if (!readRecord(root)) {
+  let record;
+  try {
+    record = readRecord(root);
+  } catch (error) {
+    return pathRefusal(error);
+  }
+  if (!record) {
     console.log(c.yellow('\n  not a rungs repo — nothing to eject.\n'));
     return 1;
   }
@@ -775,48 +944,6 @@ function cmdEject(root: string, dryRun: boolean) {
  */
 const VALUE_FLAGS = new Set(['--set']);
 
-/**
- * The command surface, defined once and rendered into `--help`.
- *
- * It was a template literal listing eight of the nine commands — `setup git` was missing entirely —
- * beside a README table listing all nine, which is two hand-kept inventories of one fact. They had
- * already drifted, in both directions: help omitted a real command, and three real flags appeared
- * in neither. Keep this table beside the switch it describes, and add a row when you add a `case`.
- *
- * The README's table is still hand-kept and still a second inventory. That is a known cost, not an
- * oversight — see WI-004.
- */
-const COMMANDS: [usage: string, blurb: string][] = [
-  ['init [path] [profile]', 'scaffold a repo — minimal · tracked · disciplined · hardened · fleet'],
-  ['doctor [path]', 'detect what a repo already has, installed or not'],
-  ['add <module…> [--into p]', 'install modules, resolving dependencies and adopting what exists'],
-  ['check [path] [tier]', 'run the registered gates and record the ledger'],
-  ['render [path]', 're-emit path-scoped rules per harness'],
-  ['upgrade [path]', 'move to newer module versions, never touching what you edited'],
-  ['eject [path]', 'materialise the engines; stop depending on rungs'],
-  ['setup git [path]', 'install the merge drivers .gitattributes names'],
-  ['modules', 'list the module set and audit the manifests'],
-  ['backlog archive [path]', 'move finished items to archive/, repointing every link'],
-  ['session start <branch>', 'cut a branch and worktree from the last verified merge'],
-  ['preflight [path]', 'did the integration branch change files you changed?'],
-  ['land <branch>', 'merge → verify the merged tree → advance, or refuse and park it'],
-  ['worktrees [path]', 'which worktrees are merged, prunable, or merged and still dirty'],
-];
-
-/** Every flag the parser honours. A flag absent here is a flag nobody can find. */
-const FLAGS: [flag: string, blurb: string][] = [
-  ['--dry-run', 'report what would happen, write nothing'],
-  ['--explain', "doctor: also run the detectors over what this repo already has"],
-  ['--confirm-paradigm', 'add: install a module this repo already solves another way'],
-  ['--into <path>', 'add: install into this repo instead of the working directory'],
-  ['--set m.param=value', 'add/init: override a module parameter. Repeatable'],
-  ['--confirm-threshold', 'add: install a module whose rung is above this repo'],
-  ['--apply', 'upgrade: write the changes, rather than preview them'],
-  ['--fast, --full', 'check: pick the gate tier, as the positional also does'],
-  ['--params', 'modules: show every module parameter, its default and its allowed values'],
-  ['--copilot', 'also emit Copilot instruction files'],
-];
-
 function renderHelp(): string {
   const pad = Math.max(...COMMANDS.map(([u]) => u.length)) + 2;
   const fpad = Math.max(...FLAGS.map(([f]) => f.length)) + 2;