simt-dev 0.6.2 → 0.7.0

package/src/commands/plugin.mjs

@@ -1,4 +1,4 @@
-// simt plugin <claude|gemini|cursor> --out <dir> [--yes]
+// simt plugin <claude|gemini|cursor|opencode> --out <dir> [--yes]
 //
 // Build one harness package from the same tables `agent-hooks install` writes into a
 // repository, so a package and a repository install cannot drift apart. A dry run prints
@@ -9,6 +9,7 @@
 import { EXIT, emit, emitJson, fail, isJson, writeMode } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
 import { buildPackage, PLUGIN_KINDS } from '../plugins.mjs';
+import { diffField, emitDiffs } from '../diff.mjs';
 
 export async function pluginCommand(args, flags) {
   const kind = args[0];
@@ -29,6 +30,17 @@ export async function pluginCommand(args, flags) {
   const root = flags.root ?? process.cwd();
   const plan = await buildPackage(kind, { root, out, apply });
 
+  // The `--diff` pairs: the generated files, created or refreshed (R50). The
+  // before-sides ride on the plan from `buildPackage`, read before anything was
+  // written, so the diff is true in preview and in apply alike.
+  const diffs =
+    flags.diff === true
+      ? plan.files.map((f) => ({ path: f.path, before: f.before ?? null, after: f.text }))
+      : [];
+  // The file bytes travel in `diff`, not in the file list: a payload that
+  // carried every generated file twice would be a document nobody diffs.
+  const publicFiles = plan.files.map(({ text, before, ...rest }) => rest);
+
   if (isJson(flags)) {
     emitJson({
       ok: true,
@@ -36,8 +48,9 @@ export async function pluginCommand(args, flags) {
       out,
       dryRun: !apply,
       runtime: plan.runtime,
-      files: plan.files,
+      files: publicFiles,
       notes: plan.notes,
+      ...diffField(diffs, flags),
     });
     return EXIT.OK;
   }
@@ -57,5 +70,7 @@ export async function pluginCommand(args, flags) {
     ].join('\n'),
     { maxBytes: flags.maxBytes ?? 0 },
   );
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   return EXIT.OK;
 }

package/src/commands/prbody.mjs

@@ -0,0 +1,45 @@
+// `simt pr-body [--base <ref>]` (plan 0003 R55).
+//
+// The report layer over `src/prbody.mjs`: a markdown PR body on stdout, one
+// JSON document under `--json`. Read-only like `evidence` and `review` — it
+// names the tree, reads the ledger and the check cache, and writes nothing,
+// so there is no `--yes`, no `--diff` and no journal entry to record.
+//
+// The exit code never carries the verdict. A report that failed when the body
+// said BLOCK would be a gate by another name (the same reason `review`
+// exits 0 on an unverified reply), and a gate this command never asked to be.
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { buildPrBody, renderPrBody } from '../prbody.mjs';
+
+export async function prBodyCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+  if (args.length > 0) {
+    return fail(`pr-body takes no positional arguments`, EXIT.USAGE, `run: ${CLI} pr-body [--base <ref>]`);
+  }
+  const report = await buildPrBody(root, { base: flags.base ?? null });
+  if (report.error !== null) {
+    return fail(report.error, EXIT.USAGE, `run: ${CLI} pr-body --base <ref> with a ref git knows`);
+  }
+  if (isJson(flags)) {
+    emitJson(
+      {
+        ok: true,
+        command: 'pr-body',
+        base: report.base,
+        tree: report.tree,
+        evidence: report.evidence,
+        decisions: report.decisions,
+        paths: report.paths,
+        gates: report.gates,
+        verdict: report.verdict,
+        unreviewed: report.unreviewed,
+      },
+      { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 },
+    );
+    return EXIT.OK;
+  }
+  emit(renderPrBody(report), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/commands/repoindex.mjs

@@ -18,6 +18,9 @@ export async function indexCommand(args, flags) {
       allowRemote: flags.allowRemote === true,
     });
   } catch (error) {
+    if (error?.code === 'INDEX_BUSY') {
+      return fail(`could not index this repository (${error.message})`, EXIT.FAIL, 'wait a moment and run the index again');
+    }
     return fail(
       `could not index this repository (${error.message})`,
       EXIT.UNSUPPORTED,
@@ -36,6 +39,7 @@ export async function indexCommand(args, flags) {
     `files    ${result.files}`,
     `updated  ${result.updated}`,
     `removed  ${result.removed}`,
+    `skipped  ${result.skipped ?? 0}`,
     `symbols  ${result.symbols}`,
     `edges    ${result.edges}`,
     `ms       ${result.ms}`,

package/src/commands/rules.mjs

@@ -20,7 +20,9 @@ import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { loadRules, select } from '../projection/project.mjs';
 import { loadMdcRules } from '../projection/mdc.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
-import { byId, citations, loadDecisions, redactEstate } from '../decisions/index.mjs';
+import { byId, citations, loadDecisionsCached, redactEstate } from '../decisions/index.mjs';
+import { DECISIONS_DIR } from '../decisions/index.mjs';
+import { decisionsDir } from '../decisions/dir.mjs';
 import { nearMatches } from '../resolve/near.mjs';
 import { CLI } from '../name.mjs';
 
@@ -87,11 +89,10 @@ async function loadPerSurfaceRules() {
 
 export async function listCommand(args, flags) {
   const root = flags.root ?? null;
-  const { rules, broken } = await load(root);
-
   // With --root the question becomes "which of these apply to me", which is a
   // different answer from the catalogue and the one an agent usually wants.
-  const selection = root ? await selectionFor(rules, root) : null;
+  const { rules, broken, notes } = await rulesCatalogue(root, { selectFor: root });
+  const selection = root ? new Set(rules.filter((r) => r.selected).map((r) => r.id)) : null;
 
   if (isJson(flags)) {
     emitJson(
@@ -99,19 +100,8 @@ export async function listCommand(args, flags) {
                 ok: broken.length === 0,
                 command: 'rules list',
                 root,
-                rules: sorted(rules).map((r) => ({
-                  id: r.id,
-                  title: r.title,
-                  origin: r.origin,
-                  source: r.source,
-                  applies: r.applies,
-                  fallback: r.fallback,
-                  bytes: r.bytes,
-                  error: r.error,
-                  adrs: citations(r.body),
-                  selected: selection ? selection.selected.has(r.id) : null,
-                })),
-                notes: selection?.notes ?? [],
+                rules,
+                notes,
               },
     );
     return broken.length === 0 ? EXIT.OK : EXIT.FAIL;
@@ -145,7 +135,7 @@ export async function listCommand(args, flags) {
   ];
 
   for (const rule of rows) {
-    const mark = selection && selection.selected.has(rule.id) ? '*' : ' ';
+    const mark = selection && selection.has(rule.id) ? '*' : ' ';
     lines.push(
       render(mark, rule.id, kb(rule.bytes), rule.origin, appliesLabel(rule), rule.title ?? '(no title)'),
     );
@@ -156,7 +146,7 @@ export async function listCommand(args, flags) {
   }
   if (selection) {
     lines.push('', `* selected for ${root}`);
-    for (const note of selection.notes) lines.push(`  note ${note}`);
+    for (const note of notes) lines.push(`  note ${note}`);
   }
   if (root) {
     const locals = rules.filter((r) => r.origin === 'local');
@@ -173,15 +163,152 @@ async function selectionFor(rules, root) {
   return { selected: new Set(selected.map((r) => r.id)), notes };
 }
 
+// --- cores: one computation for the CLI and the MCP tools (Q15) ----------------
+//
+// `rules_list` and `rules_why` in the MCP surface rebuilt this catalogue from the
+// same modules with narrower loads: the MCP list missed the per-surface rules and
+// the MCP why failed on them, because neither shared the catalogue below. The
+// commands render these facts for terminals; the tools return them as JSON. The
+// CLI keeps its field names; the tools adopt them.
+//
+// A core throws when it cannot answer: the message names the problem, `remedy`
+// names the next command, and `exitCode` is the exit the CLI leaves with.
+function rulesFailure(message, remedy, exitCode) {
+  throw Object.assign(new Error(message), { remedy, exitCode });
+}
+
+/**
+ * The merged decision index: the package's shipped records underlay the
+ * repository's own, which win on an id collision (review 0003 Q34).
+ *
+ * Before this, a consumer with its own ADR-001/002 read `rules why core` as
+ * settled by *their* ADR-001 while the package's ADR-003…009 — the ones the
+ * shipped rules actually cite — reported MISSING. The overlay keeps both
+ * visible: every decision carries which layer it came from, so a same-number
+ * collision reads as two records, never as one answer wearing the wrong title.
+ *
+ * @returns {{ok: boolean, decisions: object[], errors: string[], origins: Record<string,'repo'|'package'>}}
+ */
+async function loadDecisionsFor(root, all) {
+  // Q55: one resolution (manifest key, then detection) and the shared cache,
+  // so `rules why` answers from the repository's own records without re-parsing
+  // every record on every call. No root means the package's own records.
+  const pkg = await loadDecisionsCached({ root, dir: DECISIONS_DIR, all });
+  if (!root) return { ...pkg, origins: Object.fromEntries(pkg.decisions.map((d) => [d.id, 'package'])) };
+  const relDir = await decisionsDir(root);
+  const absDir = join(root, relDir);
+  const hasLocal = (await readdir(absDir).catch(() => [])).some((n) => /^ADR-\d{3,}-.*\.md$/i.test(n));
+  if (!hasLocal) return { ...pkg, origins: Object.fromEntries(pkg.decisions.map((d) => [d.id, 'package'])) };
+  const local = await loadDecisionsCached({ root, dir: absDir, all });
+  const merged = new Map(pkg.decisions.map((d) => [d.id, d]));
+  const origins = Object.fromEntries(pkg.decisions.map((d) => [d.id, 'package']));
+  for (const d of local.decisions) {
+    merged.set(d.id, d);
+    origins[d.id] = 'repo';
+  }
+  return { ok: pkg.ok && local.ok, decisions: [...merged.values()], errors: [...pkg.errors, ...local.errors], origins };
+}
+
+/** The catalogue both surfaces answer from: every rule, its decisions, and the selection. */
+export async function rulesCatalogue(root, { selectFor = null } = {}) {
+  const { rules, broken } = await load(root);
+  const selection = selectFor ? await selectionFor(rules, selectFor) : null;
+  return {
+    rules: sorted(rules).map((r) => ({
+      id: r.id,
+      title: r.title,
+      origin: r.origin,
+      source: r.source,
+      applies: r.applies,
+      optIn: r.optIn ?? false,
+      fallback: r.fallback,
+      bytes: r.bytes,
+      error: r.error,
+      adrs: citations(r.body),
+      selected: selection ? selection.selected.has(r.id) : null,
+    })),
+    broken,
+    notes: selection?.notes ?? [],
+  };
+}
+
+/**
+ * The provenance facts for one rule or one decision record, in the shape the
+ * JSON documents carry. Text renders from the same facts; nothing re-derives.
+ */
+export async function rulesWhyFacts(root, what, { all = false } = {}) {
+  const { rules } = await load(root);
+  if (/^ADR-\d{3,}$/i.test(what)) {
+    const id = what.toUpperCase();
+    const { ok, decisions, errors, origins } = await loadDecisionsFor(root, all);
+    if (!ok) {
+      rulesFailure(errors[0], 'the decision records must be readable for provenance to work', EXIT.CONFIG);
+    }
+    const record = decisions.find((x) => x.id === id) ?? null;
+    // Was 'list them with: ls docs/decisions/' - a path relative to simt-dev's own
+    // tree, which resolves to nothing in the repo the reader is standing in. The
+    // remedy must be a command they can run (Q34: the decisions list, not the
+    // rules list - the reader asked about a decision, not a rule).
+    if (!record) rulesFailure(`no decision record ${id}`, `list the known decisions with: ${CLI} rules decisions`, EXIT.USAGE);
+    const replacement = record.supersededBy ? decisions.find((x) => x.id === record.supersededBy) : null;
+    return {
+      direction: 'decision',
+      id,
+      adr: { ...record, origin: origins[id] ?? 'package' },
+      origins,
+      supersededBy: replacement ? { id: replacement.id, title: replacement.title } : null,
+      inForce: replacement
+        ? { id: replacement.id, status: replacement.status, summary: replacement.summary }
+        : { id: record.id, status: record.status, summary: record.summary },
+      rules: rules.filter((r) => citations(r.body).includes(id)).map((r) => r.id),
+    };
+  }
+  const rule = rules.find((r) => r.id === what);
+  if (!rule) {
+    const near = nearMatches(what, rules.map((r) => r.id));
+    rulesFailure(
+      `no rule with id "${what}"${near.length > 0 ? ` (did you mean ${near.join(', ')}?)` : ''}`,
+      `run: ${CLI} rules list`,
+      EXIT.USAGE,
+    );
+  }
+  const { ok, decisions, errors, origins } = await loadDecisionsFor(root, all);
+  if (!ok) {
+    rulesFailure(errors[0], 'the decision records must be readable for provenance to work', EXIT.CONFIG);
+  }
+  const index = byId(decisions);
+  const cited = citations(rule.body);
+  const others = rules.filter((r) => r.id !== rule.id && citations(r.body).some((c) => cited.includes(c)));
+  return {
+    direction: 'rule',
+    id: rule.id,
+    rule: rule.id,
+    title: rule.title ?? null,
+    source: rule.source,
+    origin: rule.origin,
+    adrs: cited.map((c) => (index.has(c) ? { ...index.get(c), origin: origins[c] ?? 'package' } : { id: c, missing: true })),
+    uncited: cited.length === 0,
+    others: others.map((r) => r.id),
+    origins,
+  };
+}
+
 // --- show ---------------------------------------------------------------------
 
 export async function showCommand(args, flags) {
   const id = args[0];
   if (!id) return fail('rules show needs a rule id', EXIT.USAGE, `usage: ${CLI} rules show <id>`);
 
-  const { rules, broken } = await load(flags.root ?? null);
+  const { rules } = await load(flags.root ?? null);
   const rule = rules.find((r) => r.id === id);
-  if (!rule) return unknown(id, rules);
+  if (!rule) {
+    const near = nearMatches(id, rules.map((r) => r.id));
+    return fail(
+      `no rule with id "${id}"${near.length > 0 ? ` (did you mean ${near.join(', ')}?)` : ''}`,
+      EXIT.USAGE,
+      `run: ${CLI} rules list`,
+    );
+  }
 
   const adrs = citations(rule.body);
   if (isJson(flags)) {
@@ -218,47 +345,25 @@ export async function whyCommand(args, flags) {
   const what = args[0];
   if (!what) return fail('rules why needs a rule id or an ADR id', EXIT.USAGE, `usage: ${CLI} rules why <rule-id|ADR-NNN>`);
 
-  const { rules, broken } = await load(flags.root ?? null);
-  const localDir = flags.root ? join(flags.root, 'docs', 'decisions') : null;
-  const hasLocal = localDir
-    ? (await readdir(localDir).catch(() => [])).some((n) => /^ADR-\d{3,}-.*\.md$/i.test(n))
-    : false;
-  const { ok, decisions, errors } = await loadDecisions({
-    all: flags.all === true,
-    ...(hasLocal ? { dir: localDir } : {}),
-  });
-  if (!ok) return fail(errors[0], EXIT.CONFIG, 'the decision records must be readable for provenance to work');
-
-  return what.match(/^ADR-\d{3,}$/i)
-    ? adrDirection(what.toUpperCase(), rules, decisions, flags)
-    : ruleDirection(what, rules, decisions, flags, broken);
-}
-
-async function ruleDirection(id, rules, decisions, flags, broken) {
-  const rule = rules.find((r) => r.id === id);
-  if (!rule) return unknown(id, rules);
-
-  const cited = citations(rule.body);
-  const index = byId(decisions);
+  let facts;
+  try {
+    facts = await rulesWhyFacts(flags.root ?? null, what, { all: flags.all === true });
+  } catch (error) {
+    return fail(error.message, error.exitCode ?? EXIT.FAIL, error.remedy);
+  }
 
   if (isJson(flags)) {
-    emitJson(
-      {
-                ok: true,
-                command: 'rules why',
-                rule: rule.id,
-                source: rule.source,
-                origin: rule.origin,
-                adrs: cited.map((c) => index.get(c) ?? { id: c, missing: true }),
-                uncited: cited.length === 0,
-              },
-    );
+    emitJson({ ok: true, command: 'rules why', ...facts });
     return EXIT.OK;
   }
 
-  const lines = [`${rule.id} - ${rule.title ?? '(no title)'}`, '', `source  ${rule.source} (${rule.origin})`];
+  return facts.direction === 'decision' ? adrDirection(facts, flags) : ruleDirection(facts, flags);
+}
+
+function ruleDirection(facts, flags) {
+  const lines = [`${facts.rule} - ${facts.title ?? '(no title)'}`, '', `source  ${facts.source} (${facts.origin})`];
 
-  if (cited.length === 0) {
+  if (facts.uncited) {
     lines.push(
       '',
       'provenance  NONE',
@@ -269,14 +374,14 @@ async function ruleDirection(id, rules, decisions, flags, broken) {
     return EXIT.OK;
   }
 
-  lines.push('', `settled by ${cited.length} decision${cited.length === 1 ? '' : 's'}`);
-  for (const adr of cited) {
-    const d = index.get(adr);
-    if (!d) {
-      lines.push(`  ${adr}  MISSING - the rule cites it, but this installation has no record of it`);
+  lines.push('', `settled by ${facts.adrs.length} decision${facts.adrs.length === 1 ? '' : 's'}`);
+  for (const d of facts.adrs) {
+    if (d.missing) {
+      lines.push(`  ${d.id}  MISSING - the rule cites it, but neither this repo nor this installation has a record of it`);
+      lines.push(`          remedy: list the known decisions with: ${CLI} rules decisions`);
       continue;
     }
-    lines.push(`  ${d.id}  ${d.title}`);
+    lines.push(`  ${d.id}  [${d.origin ?? 'package'}]  ${d.title}`);
     lines.push(`          ${d.status}`);
     if (d.supersededBy) {
       // Never print a reversed ruling as if it were current.
@@ -286,52 +391,24 @@ async function ruleDirection(id, rules, decisions, flags, broken) {
 
   // The reverse edge is what makes this useful for maintaining the set: which
   // rules would a change to one decision touch?
-  const others = rules.filter((r) => r.id !== rule.id && citations(r.body).some((c) => cited.includes(c)));
-  if (others.length > 0) {
-    lines.push('', `shares a decision with ${others.map((r) => r.id).join(', ')}`);
+  if (facts.others.length > 0) {
+    lines.push('', `shares a decision with ${facts.others.join(', ')}`);
   }
 
   emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
   return EXIT.OK;
 }
 
-async function adrDirection(adr, rules, decisions, flags) {
-  const d = decisions.find((x) => x.id === adr);
-  if (!d) {
-    // Was 'list them with: ls docs/decisions/' - a path relative to simt-dev's own
-    // tree, which resolves to nothing in the repo the reader is standing in. The
-    // remedy must be a command they can run.
-    return fail(`no decision record ${adr}`, EXIT.USAGE, `list the known decisions with: ${CLI} rules list`);
-  }
-
-  const restates = rules.filter((r) => citations(r.body).includes(d.id));
-
-  if (isJson(flags)) {
-    // The machine payload answers the same question as the text one. A caller reading
-    // `adr.summary.ruled` off a superseded record would get the reversal, so the
-    // effective ruling is carried alongside rather than instead: the record asked about
-    // is still named, and what is in force is named separately.
-    const replacement = d.supersededBy ? decisions.find((x) => x.id === d.supersededBy) : null;
-    emitJson(
-      {
-                ok: true,
-                command: 'rules why',
-                adr: d,
-                supersededBy: replacement ? { id: replacement.id, title: replacement.title } : null,
-                inForce: replacement
-                  ? { id: replacement.id, status: replacement.status, summary: replacement.summary }
-                  : { id: d.id, status: d.status, summary: d.summary },
-                rules: restates.map((r) => r.id),
-              },
-    );
-    return EXIT.OK;
-  }
+function adrDirection(facts, flags) {
+  const d = facts.adr;
+  const restates = facts.rules;
 
   const lines = [
     `${d.id} - ${d.title}`,
     '',
+    `origin    ${d.origin ?? 'package'}${d.origin === 'repo' ? ' (this repository overlays the shipped record of the same number)' : ''}`,
     `status    ${d.status}`,
-    `restates  ${restates.length > 0 ? restates.map((r) => r.id).join(', ') : '(no rule cites it)'}`,
+    `restates  ${restates.length > 0 ? restates.join(', ') : '(no rule cites it)'}`,
   ];
   if (d.supersededBy) lines.push(`SUPERSEDED by ${d.supersededBy} - this record is retained as evidence, not as policy.`);
   if (d.supersedes.length > 0) lines.push(`supersedes  ${d.supersedes.join(', ')}`);
@@ -360,7 +437,7 @@ async function adrDirection(adr, rules, decisions, flags) {
   // attached, and an agent that skims the ruling and not the banner acts on the
   // reversal. This is the failure the decision index's own header names: a provenance
   // feature that proves provenance but not currency.
-  const replacement = d.supersededBy ? decisions.find((x) => x.id === d.supersededBy) : null;
+  const replacement = facts.replacement;
   const effective = replacement ?? d;
 
   if (replacement) {
@@ -415,11 +492,48 @@ async function adrDirection(adr, rules, decisions, flags) {
   return EXIT.OK;
 }
 
-function unknown(id, rules) {
-  const near = nearMatches(id, rules.map((r) => r.id));
-  return fail(
-    `no rule with id "${id}"${near.length > 0 ? ` (did you mean ${near.join(', ')}?)` : ''}`,
-    EXIT.USAGE,
-    `run: ${CLI} rules list`,
-  );
+// --- decisions ------------------------------------------------------------------
+
+/**
+ * `simt rules decisions`: every known decision record, both layers.
+ *
+ * The shipped records underlay the repository's own, which win on a number
+ * collision (review 0003 Q34). The column that matters is `origin`: a reader in
+ * a consumer repository must be able to tell the package's ADR-001 from their
+ * own, because they are two records that happen to share a number.
+ */
+export async function decisionsCommand(args, flags) {
+  const root = flags.root ?? null;
+  const { ok, decisions, errors, origins } = await loadDecisionsFor(root, flags.all === true);
+  if (!ok) {
+    return fail(errors[0], EXIT.CONFIG, 'the decision records must be readable to list them');
+  }
+  const rows = [...decisions]
+    .sort((a, b) => Number(a.id.replace(/^ADR-/i, '')) - Number(b.id.replace(/^ADR-/i, '')))
+    .map((d) => ({
+      id: d.id,
+      title: d.title,
+      status: d.status,
+      origin: origins[d.id] ?? 'package',
+      supersededBy: d.supersededBy ?? null,
+      file: d.file,
+    }));
+
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'rules decisions', root, decisions: rows });
+    return EXIT.OK;
+  }
+
+  const repo = rows.filter((r) => r.origin === 'repo').length;
+  const lines = [
+    `${rows.length} decisions${root && repo > 0 ? ` (${repo} from this repo overlay the shipped set)` : ''}`,
+    '',
+    'id       origin   title',
+  ];
+  for (const r of rows) {
+    const head = r.status.length > 80 ? `${r.status.slice(0, 80)}...` : r.status;
+    lines.push(`${r.id.padEnd(8)}  ${r.origin.padEnd(7)}  ${r.title} — ${head}`);
+  }
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
 }

package/src/commands/shared.mjs

@@ -11,10 +11,12 @@
 // is `doctor`'s job rather than a third subcommand: a question asked about a repository is
 // answered by the command that already reports on a repository (ADR-084).
 
-import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson, writeMode } from '../output/index.mjs';
 import { CLI, MANIFEST_FILE } from '../name.mjs';
 import { targetRoot } from '../workspace.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import {
+  injectShared,
   intersect,
   sharedBody,
   sharedCandidates,
@@ -25,7 +27,7 @@ import {
   sharedTargets,
   writeSharedFile,
 } from '../projection/shared.mjs';
-import { buildManifest, declaredShared, readManifest, writeManifest } from '../projection/manifest.mjs';
+import { buildManifest, declaredShared, manifestPath, manifestText, readManifest, writeManifest } from '../projection/manifest.mjs';
 import { desiredRegion } from '../projection/rules.mjs';
 
 /**
@@ -241,7 +243,31 @@ export async function sharedInstallCommand(_args, flags) {
     manifests.push({ root, action: 'declared', manifest: built });
   }
 
-  if (flags.yes !== true) {
+  // The `--diff` pairs, read before anything is written so the before side is
+  // true in preview and in apply alike (R50). Home-directory copies through the
+  // same `injectShared` the write applies, manifest declarations through
+  // `manifestText`; paste targets carry no file and are printed in full below.
+  let diffs = [];
+  if (flags.diff === true) {
+    for (const t of targets) {
+      if (t.path === null) continue;
+      const before = await readBefore(t.path);
+      diffs.push({ path: t.path, before, after: injectShared(before ?? '', shared, meta).text });
+    }
+    for (const row of manifests) {
+      if (row.action !== 'declared') continue;
+      diffs.push({
+        path: `${basename(row.root)}/${MANIFEST_FILE}`,
+        before: await readBefore(await manifestPath(row.root)),
+        after: manifestText(row.manifest),
+      });
+    }
+  }
+
+  // `--yes --dry-run` is a rehearsal, not consent: only writeMode decides, so the
+  // `--dry-run` promise holds for the one command that writes into `$HOME` (Q09).
+  const { dryRun, apply } = writeMode(flags);
+  if (!apply) {
     // Nothing above this line writes, and nothing below it runs without the reader's
     // consent — because one of the two writes lands in their home directory and the other
     // edits repositories other people may be reviewing. The states printed here come from
@@ -259,12 +285,13 @@ export async function sharedInstallCommand(_args, flags) {
       emitJson({
         ok: false,
         command: 'shared install',
-        mode: 'preview',
+        mode: dryRun ? 'dry-run' : 'preview',
         roots,
         shared,
         divergent,
         targets: states,
         manifests: manifests.map(({ root: r, action, detail }) => ({ root: r, action, detail: detail ?? null })),
+        ...diffField(diffs, flags),
       });
       return EXIT.FAIL;
     }
@@ -277,10 +304,12 @@ export async function sharedInstallCommand(_args, flags) {
             : `  ${s.state.padEnd(9)}${s.path}`,
         ),
         `manifest ${manifests.map((m) => `${m.action}:${basename(m.root)}`).join(' ')}`,
-        `nothing written; re-run with: ${CLI} shared install --yes`,
+        dryRun ? 'dry-run  nothing written' : `nothing written; re-run with: ${CLI} shared install --yes`,
       ].join('\n'),
       { maxBytes: flags.maxBytes ?? 0 },
     );
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
     return EXIT.FAIL;
   }
 
@@ -326,6 +355,8 @@ export async function sharedInstallCommand(_args, flags) {
   }
   lines.push(`verify   ${CLI} doctor  reports the copy as current, and ${CLI} tokens --repos --root . reports what is left`);
   emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   return EXIT.OK;
 }