craftar 0.15.0 → 0.17.0

package/dist/cli.js

@@ -6,7 +6,9 @@ import YAML from "yaml";
 import { importClaudeCode } from "./importers/claude-code.js";
 import { classifyForge } from "./core/remote.js";
 import { forget, listWorkspaces, prune, register, registryFile } from "./core/registry.js";
+import { forgeWorkspaces, planAll, nextSync, impactOf, concerned, refineRegistryState } from "./core/impact.js";
 import { runDoctor } from "./core/doctor.js";
+import { pruneCache } from "./core/cache.js";
 import { resolveHome } from "./core/home-lock.js";
 import { loadWorkspace, plan, readLock, status, apply, resolveForge, resolveForgeSource, WORKSPACE_FILE, LOCAL_FILE } from "./core/sync.js";
 import { resolve, sectionKey } from "./core/resolve.js";
@@ -16,9 +18,9 @@ import { canonicalValue } from "./core/sections.js";
 import { renderDiff, NO_EOF_NEWLINE_MARKER } from "./core/diff.js";
 import { diffIngredients, listVariants, profileOf } from "./core/variants.js";
 import { hashNormalized, toLf, stripBom } from "./core/text.js";
-import { exists, gitDirty, gitIsRepo, gitUnheld } from "./core/forge.js";
+import { exists, gitDirty, gitIsRepo, gitUnheld, loadForge } from "./core/forge.js";
 import { fingerprintDir } from "./core/fingerprint.js";
-import { hunkAt, planFrom, applyPlan, writeUnified, checkRecipeCascade, rewriteRecipes, } from "./core/unify.js";
+import { hunkAt, planFrom, applyPlan, writeUnified, checkRecipeCascade, rewriteRecipes, pruneCandidates, pruneRecipes, note, } from "./core/unify.js";
 import { checkParamWrites, writeParamFile } from "./core/param-writes.js";
 import { planInit } from "./core/init.js";
 import { editRecipesText, planRecipeEdit, recipeDiffLine } from "./core/recipe-edit.js";
@@ -33,7 +35,7 @@ process.stdout.on("error", (e) => { if (e.code === "EPIPE")
  */
 const DIFF_EXIT_CODE_FETCH_MODE = "sync";
 const program = new Command();
-program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.15.0");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.17.0");
 /* ---------------------------------------------------------------- import */
 program
     .command("import")
@@ -869,6 +871,94 @@ forge
     const orphanNote = orphans.length ? `, ${orphans.length} orphan${orphans.length === 1 ? "" : "s"}` : "";
     console.log(`\n  ${groups.length} base${groups.length === 1 ? "" : "s"} with variants, ${total} variant${total === 1 ? "" : "s"} total${orphanNote}`);
 });
+forge
+    .command("impact")
+    .description("List every workspace registered on this machine that reads this Forge — by its path, by a git remote of this clone, or through another clone of the same remote — with what its next sync would do against the Forge as it is now. Read-only; no fetch")
+    .option("--forge <dir>", "Forge directory (instead of --workspace)")
+    .option("--workspace <dir>", "workspace whose craftar.yaml names the Forge (default: .)")
+    .option("--json", "machine-readable output", false)
+    .action(async (o) => {
+    const f = await resolveForge({
+        forge: o.forge,
+        workspace: o.workspace,
+        refuseRemote: (url) => `the Forge of this workspace is remote (${url}) — clone it and pass --forge <dir>`,
+    });
+    let fw;
+    try {
+        fw = await forgeWorkspaces(craftarHome(), f.root);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e));
+    }
+    warnStderr(fw.warnings);
+    const planned = await planAll(fw.workspaces, f);
+    const results = await Promise.all(planned.map((p) => nextSync(p)));
+    // Refine the registry state: "partial" when any entry is missing or stage-config error (spec 25 §3)
+    const registryState = refineRegistryState(fw.state, planned);
+    if (o.json) {
+        const workspaces = fw.workspaces.map((ws, i) => {
+            const r = results[i];
+            return {
+                path: ws.entry.path,
+                profile: ws.entry.profile,
+                match: ws.match,
+                via: ws.via,
+                ref: ws.ref,
+                state: r.state,
+                counts: r.counts,
+                error: r.error,
+            };
+        });
+        console.log(JSON.stringify({ forge: fw.realForge, registry: registryState, workspaces }, null, 2));
+        return;
+    }
+    // Text output
+    const parts = [];
+    const byMatch = {};
+    for (const ws of fw.workspaces)
+        byMatch[ws.match] = (byMatch[ws.match] ?? 0) + 1;
+    if (byMatch.path)
+        parts.push(`${byMatch.path} by path`);
+    if (byMatch.remote)
+        parts.push(`${byMatch.remote} by remote`);
+    if (byMatch.clone)
+        parts.push(`${byMatch.clone} by clone`);
+    if (fw.state === "none") {
+        console.log(`craftar forge impact — ${fw.realForge}`);
+        console.log(`  no registered workspace reads this Forge on this machine`);
+        return;
+    }
+    if (fw.state === "off") {
+        console.log(`craftar forge impact — ${fw.realForge}`);
+        console.log(`  the registry is off (CRAFTAR_NO_REGISTRY)`);
+        return;
+    }
+    const n = fw.workspaces.length;
+    console.log(`craftar forge impact — ${fw.realForge} · ${n} registered workspace${n === 1 ? "" : "s"} (${parts.join(", ")})`);
+    const maxPath = Math.max(...fw.workspaces.map((ws) => ws.entry.path.length));
+    const maxProfile = Math.max(...fw.workspaces.map((ws) => ws.entry.profile.length));
+    for (let i = 0; i < fw.workspaces.length; i++) {
+        const ws = fw.workspaces[i];
+        const r = results[i];
+        let stateStr;
+        if (r.state === "unchanged") {
+            stateStr = "unchanged";
+        }
+        else if (r.state === "changed") {
+            // Counts in NEXT_SYNC order
+            const countParts = NEXT_SYNC_STATES.map((k) => (r.counts[k] ? `${r.counts[k]} ${k}` : "")).filter(Boolean);
+            stateStr = countParts.join(", ");
+        }
+        else if (r.state === "missing") {
+            stateStr = "missing";
+        }
+        else {
+            stateStr = `error: ${r.error}`;
+        }
+        const suffix = matchSuffix(ws);
+        console.log(`  ${ws.entry.path.padEnd(maxPath)}  ${ws.entry.profile.padEnd(maxProfile)}  ${stateStr}${suffix}`);
+    }
+});
 forge
     .command("diff")
     .description("Show the distance and the differences between a base ingredient and each of its variants, each hunk with a suggested class (evolution, value, block) that never decides anything. Read-only")
@@ -930,10 +1020,16 @@ forge
     .option("--take <side>", "resolve every decision to base or variant")
     .option("--plan <file>", "apply the decisions in this plan file (a hunk may be take: param with its params list, or take: section with its section name)")
     .option("--save-plan <file>", "write a plan with every decision deferred, each hunk annotated with its suggested class (which --plan ignores), value hunks pre-filled with params, block hunks pre-filled with a section name, and hunks touching an existing section with its name, to a new file outside the Forge, and stop")
+    .option("--no-impact", "skip planning the registered workspaces of this Forge before and after the writes (the warnings then keep their previous text)")
+    .option("--prune-recipes", "delete each suffixed recipe the cascade leaves identical to its sibling and repoint the profiles that name it — only when every workspace registered on this machine plans byte for byte the same; needs the impact passes")
     .option("--forge <dir>", "Forge directory (instead of --workspace)")
     .option("--workspace <dir>", "workspace whose craftar.yaml names the Forge (default: .)")
     .option("--json", "machine-readable output", false)
     .action(async (ref, o) => {
+    // Spec 25 §4.4: --prune-recipes with --no-impact is refused before anything is read
+    if (o.pruneRecipes && !o.impact) {
+        fail("--prune-recipes needs the impact passes — drop --no-impact");
+    }
     const frontEnds = [o.take, o.plan, o.savePlan].filter((v) => v !== undefined);
     if (frontEnds.length !== 1)
         fail("pass exactly one of --take, --plan or --save-plan");
@@ -1048,6 +1144,10 @@ forge
     // Ruling 33, dry pass: every recipe `ingredients` rewrite the cascade will make is checked before
     // the first byte is written, so a refusal (an aliased reference) leaves the Forge untouched.
     const cascadeFiles = result.resolved ? await checkRecipeCascade(f, base.ref, variant.ref) : [];
+    // Spec 25 §4.4: prune candidates, computed in the dry pass
+    const candidates = o.pruneRecipes && result.resolved
+        ? await pruneCandidates(f, base.ref, variant.ref, o.profile)
+        : [];
     // Spec 09 & 12: the Forge-level rows and YAML edits for parameter and section extractions, rendered before any write.
     const paramWrites = result.params.length || result.sections.length
         ? await checkParamWrites(f, base, variant, o.profile, result.params, result.sections)
@@ -1056,7 +1156,9 @@ forge
     // check above cannot see ignored files (a Forge its enclosing repo ignores, an ignored file in
     // a variant) nor untracked ones under `status.showUntrackedFiles=no` — so every path this run
     // will overwrite or delete is checked on its own, before the first write.
-    const mustHold = [base.dir, ...(result.resolved ? [variant.dir, ...cascadeFiles] : []), ...(paramWrites?.mustHold ?? [])];
+    // Spec 25 §4.4: prune candidates' profile files join mustHold
+    const candidateProfiles = candidates.flatMap((c) => c.profiles.map((p) => p.abs));
+    const mustHold = [base.dir, ...(result.resolved ? [variant.dir, ...cascadeFiles] : []), ...(paramWrites?.mustHold ?? []), ...candidateProfiles];
     const unheld = await gitUnheld(f.root, mustHold);
     if (unheld.length) {
         // Name every such path (the first few, then a count), so one run shows the whole problem.
@@ -1066,6 +1168,25 @@ forge
             lines.push(`  … and ${unheld.length - SHOWN} more`);
         fail(`unify can only change files git can restore — ${unheld.length} path(s) under ${f.root} are not:\n${lines.join("\n")}`);
     }
+    let impactState = "skipped";
+    let impactEntries = [];
+    let impactBefore = [];
+    let impactWarnings = [];
+    let impactUnreadableReason = null;
+    if (o.impact) {
+        try {
+            const fw = await forgeWorkspaces(craftarHome(), f.root);
+            impactEntries = fw.workspaces;
+            impactWarnings = fw.warnings;
+            impactBefore = await planAll(fw.workspaces, f);
+            // Refine the state: "partial" when any before entry is missing or stage-config error
+            impactState = refineRegistryState(fw.state, impactBefore);
+        }
+        catch (e) {
+            impactState = "unreadable";
+            impactUnreadableReason = e instanceof Error ? e.message : String(e);
+        }
+    }
     // Order: merged files, then the recipe cascade, then removal of the variant directory
     // (Ruling 21) — a late failure leaves the variant in place, never a recipe naming a removed ingredient.
     // Spec 12 §6.7: the manifest is first when it moves to schema: 2; each prefix is emission-neutral.
@@ -1097,8 +1218,72 @@ forge
         // writing began: name what was touched and how git undoes it, and still exit 1.
         throw new Error(lateFailure(e, f.root, journal), { cause: e });
     }
+    // Spec 25 §4.2: after pass — planAll against the Forge as unify left it, then impactOf per entry
+    let impactAfter = [];
+    let impactResults = [];
+    if (o.impact && impactState !== "skipped" && impactState !== "unreadable" && impactEntries.length > 0) {
+        let afterForge = f;
+        try {
+            afterForge = await loadForge(f.root);
+        }
+        catch (e) {
+            // If loadForge fails, treat every entry as error with the actual message
+            const msg = e instanceof Error ? e.message : String(e);
+            for (let i = 0; i < impactEntries.length; i++) {
+                impactAfter.push({ kind: "error", stage: "plan", message: msg });
+            }
+        }
+        if (impactAfter.length === 0) {
+            impactAfter = await planAll(impactEntries, afterForge);
+        }
+        for (let i = 0; i < impactEntries.length; i++) {
+            impactResults.push(impactOf(impactBefore[i], impactAfter[i]));
+        }
+    }
+    // Spec 25 §4.4: prune step — after unify's writes and the after pass, prove and apply prunes
+    let pruneResult = { pruned: [], kept: [] };
+    if (o.pruneRecipes && candidates.length > 0) {
+        // Map the state: "skipped" cannot happen here (--prune-recipes requires --impact)
+        const pruneState = impactState === "unreadable" ? "unreadable" : impactState;
+        try {
+            pruneResult = await pruneRecipes(f.root, candidates, {
+                state: pruneState,
+                entries: impactEntries,
+                after: impactAfter,
+            });
+        }
+        catch (e) {
+            // A throw in pruneRecipes (e.g. loadForge fails) after unify's writes: name what was touched.
+            throw new Error(lateFailure(e, f.root, journal), { cause: e });
+        }
+        // Apply the prune writes
+        for (const p of pruneResult.pruned) {
+            try {
+                // Write profile files first, then delete the recipe file
+                for (const w of p.writes) {
+                    if (w.content !== null) {
+                        await note(journal, w.abs);
+                        await fs.writeFile(w.abs, w.content);
+                    }
+                    else {
+                        journal.push({ abs: w.abs, created: false });
+                        await fs.rm(w.abs, { force: true });
+                    }
+                }
+            }
+            catch (e) {
+                throw new Error(lateFailure(e, f.root, journal), { cause: e });
+            }
+        }
+    }
     // Ruling 28: a metadata difference leaves the variant in place; say which fields and why.
     const warnings = [];
+    // Spec 25 §4.2: warning for unreadable registry
+    if (impactUnreadableReason !== null) {
+        warnings.push(`the registry could not be read (${impactUnreadableReason}) — no workspace was checked`);
+    }
+    // Spec 25 §4.2: push warnings from forgeWorkspaces (credential lines)
+    warnings.push(...impactWarnings);
     if (result.metaDiffers.length) {
         warnings.push(`ingredient.yaml differs in ${result.metaDiffers.join(", ")} — unify cannot merge ingredient.yaml, so ${variant.ref} stays; ` +
             `resolve it by hand, or use --take base to discard the variant`);
@@ -1106,30 +1291,142 @@ forge
     // Ruling 42: a suffixed recipe left identical to its sibling is reported, never deleted — a
     // workspace's recipes.add or an extends chain may name the sibling, and removing the suffixed
     // one would shift recipe order or param precedence there.
+    // Spec 25 §4.4: only printed for candidates NOT pruned; without --prune-recipes, ends with a hint
     const suffix = `--${o.profile}`;
+    const prunedRecipes = new Set(pruneResult.pruned.map((p) => p.recipe));
     for (const rn of cascade.identicalToSibling) {
+        // Skip if this was pruned
+        if (prunedRecipes.has(rn))
+            continue;
         const sibling = rn.slice(0, -suffix.length);
-        warnings.push(`recipe ${rn} is now identical to ${sibling} — it can be removed by hand after repointing the profiles, extends and ` +
+        const baseText = `recipe ${rn} is now identical to ${sibling} — it can be removed by hand after repointing the profiles, extends and ` +
             `workspace recipes lists that name it; unify does not, because a workspace or an extends chain may also name ` +
-            `${sibling} and the recipe order or param precedence would change`);
+            `${sibling} and the recipe order or param precedence would change`;
+        // Without --prune-recipes: add the hint to rerun with it
+        const warning = o.pruneRecipes
+            ? baseText
+            : `${baseText} — or restore the Forge with git and rerun this unify with --prune-recipes`;
+        warnings.push(warning);
     }
-    // Ruling 38: `resolve()` matches overrides.ingredients.disable by ref, so once the variant ref
-    // is gone a workspace that disabled it gets the base back, enabled, with no error.
-    // Spec 09 W1: what a parameter extraction cannot check from inside the Forge (W2 went with spec 10).
+    // Spec 25 §4.3: helper to build conditional warnings based on registry state and concerned workspaces
+    const unchecked = impactBefore.filter((p) => p.kind === "missing" || (p.kind === "error" && p.stage === "config")).length;
+    const reach = (text, test) => {
+        // --no-impact → today's text
+        if (!o.impact)
+            return `${text}; unify cannot reach workspaces`;
+        const c = concerned(impactBefore, impactEntries, test);
+        // concerned non-empty → name them
+        if (c.concerned.length > 0) {
+            const names = c.concerned.map((w) => `${w.path} (${w.file})`).join(", ");
+            const uncheckedNote = c.unchecked > 0 ? ` (the registry could not check ${c.unchecked} workspace${c.unchecked > 1 ? "s" : ""})` : "";
+            return `${text} — concerned: ${names}${uncheckedNote}`;
+        }
+        // none concerned and registry state read → no warning
+        if (impactState === "read")
+            return null;
+        // otherwise → today's text plus suffix by state
+        let stateSuffix;
+        switch (impactState) {
+            case "partial":
+                stateSuffix = ` (the registry could not check ${unchecked} workspace${unchecked > 1 ? "s" : ""})`;
+                break;
+            case "none":
+                stateSuffix = " (no workspace of this Forge is registered on this machine)";
+                break;
+            case "off":
+                stateSuffix = " (the registry is off)";
+                break;
+            case "unreadable":
+                stateSuffix = " (the registry could not be read)";
+                break;
+            default:
+                stateSuffix = "";
+        }
+        return `${text}; unify cannot reach workspaces${stateSuffix}`;
+    };
+    // Spec 09 W1: a new parameter may override a workspace's overrides.params
     for (const e of result.params.filter((p) => !p.reused)) {
-        warnings.push(`${e.key} is now a parameter of ${base.ref} — a workspace that sets overrides.params.${e.key} (craftar.yaml or ` +
-            `craftar.local.yaml) now overrides ${base.ref} too; unify cannot reach workspaces`);
+        const text = `${e.key} is now a parameter of ${base.ref} — a workspace that sets overrides.params.${e.key} (craftar.yaml or ` +
+            `craftar.local.yaml) now overrides ${base.ref} too`;
+        const testW1 = (doc) => {
+            if (typeof doc !== "object" || doc === null)
+                return false;
+            const d = doc;
+            if (typeof d.overrides !== "object" || d.overrides === null)
+                return false;
+            const ov = d.overrides;
+            if (typeof ov.params !== "object" || ov.params === null)
+                return false;
+            return Object.hasOwn(ov.params, e.key);
+        };
+        const warn = reach(text, testW1);
+        if (warn !== null)
+            warnings.push(warn);
     }
-    // Spec 12 W3: a new section's name may be cited by a workspace's overrides.sections that was inert until now.
+    // Spec 12 W3: a new section may be filled by a workspace's overrides.sections
     for (const s of result.sections.filter((sec) => !sec.existing)) {
-        warnings.push(`${s.name} is now a section of ${base.ref} — a workspace that sets overrides.sections.${s.key}.${s.name} (craftar.yaml or ` +
-            `craftar.local.yaml) now applies there; unify cannot reach workspaces`);
+        const text = `${s.name} is now a section of ${base.ref} — a workspace that sets overrides.sections.${s.key}.${s.name} (craftar.yaml or ` +
+            `craftar.local.yaml) now applies there`;
+        const testW3 = (doc) => {
+            if (typeof doc !== "object" || doc === null)
+                return false;
+            const d = doc;
+            if (typeof d.overrides !== "object" || d.overrides === null)
+                return false;
+            const ov = d.overrides;
+            if (typeof ov.sections !== "object" || ov.sections === null)
+                return false;
+            const sec = ov.sections;
+            if (!Object.hasOwn(sec, s.key))
+                return false;
+            const keyObj = sec[s.key];
+            if (typeof keyObj !== "object" || keyObj === null)
+                return false;
+            return Object.hasOwn(keyObj, s.name);
+        };
+        const warn = reach(text, testW3);
+        if (warn !== null)
+            warnings.push(warn);
     }
+    // Ruling 38: a removed variant may be disabled by a workspace's overrides.ingredients.disable
     if (variantRemoved) {
-        warnings.push(`${variant.ref} was removed — a workspace that disables it in overrides.ingredients.disable (craftar.yaml or craftar.local.yaml) ` +
-            `must now name ${base.ref}, or the base comes back enabled; unify cannot reach workspaces`);
+        const text = `${variant.ref} was removed — a workspace that disables it in overrides.ingredients.disable (craftar.yaml or craftar.local.yaml) ` +
+            `must now name ${base.ref}, or the base comes back enabled`;
+        const testDisable = (doc) => {
+            if (typeof doc !== "object" || doc === null)
+                return false;
+            const d = doc;
+            if (typeof d.overrides !== "object" || d.overrides === null)
+                return false;
+            const ov = d.overrides;
+            if (typeof ov.ingredients !== "object" || ov.ingredients === null)
+                return false;
+            const ing = ov.ingredients;
+            if (!Array.isArray(ing.disable))
+                return false;
+            return ing.disable.includes(variant.ref);
+        };
+        const warn = reach(text, testDisable);
+        if (warn !== null)
+            warnings.push(warn);
+    }
+    // Spec 25 §4.4: when at least one recipe was pruned, add coverage warning
+    if (pruneResult.pruned.length > 0) {
+        const n = impactEntries.length;
+        warnings.push(`pruned against the ${n} workspace${n === 1 ? "" : "s"} registered on this machine — a workspace synced elsewhere (CI, another machine, CRAFTAR_NO_REGISTRY) is not covered`);
     }
     if (o.json) {
+        // Spec 25 §4.2: impact array in JSON output
+        const impact = impactResults.map((r, i) => ({
+            path: impactEntries[i].entry.path,
+            profile: impactEntries[i].entry.profile,
+            match: impactEntries[i].match,
+            via: impactEntries[i].via,
+            ref: impactEntries[i].ref,
+            state: r.state,
+            files: r.files,
+            error: r.error,
+        }));
         return console.log(JSON.stringify({
             base: base.ref,
             profile: o.profile,
@@ -1143,6 +1440,8 @@ forge
             recipes: {
                 rewritten: cascade.rewritten,
                 identicalToSibling: cascade.identicalToSibling,
+                pruned: pruneResult.pruned.map((p) => ({ recipe: p.recipe, sibling: p.sibling, profiles: p.profiles })),
+                kept: pruneResult.kept,
             },
             metaDiffers: result.metaDiffers,
             // Spec 09 §4.5: only what this run wrote — [] when every key was already declared and valued.
@@ -1160,6 +1459,8 @@ forge
             manifestEdited: paramWrites?.manifest !== null && paramWrites?.manifest !== undefined,
             profileEdited: paramWrites?.profile ? path.relative(f.root, paramWrites.profile.abs).split(path.sep).join("/") : null,
             warnings,
+            // Spec 25 §4.2: always present, [] when no workspace was checked
+            impact,
         }, null, 2));
     }
     console.log(pc.bold(`craftar forge unify ${ref} ↔ ${o.profile}`));
@@ -1190,9 +1491,70 @@ forge
     if (cascade.identicalToSibling.length) {
         console.log(`  recipes now identical to a sibling: ${cascade.identicalToSibling.join(", ")}`);
     }
+    // Spec 25 §4.4: pruned and kept recipes, after the identical-to-sibling line
+    for (const p of pruneResult.pruned) {
+        console.log(`  pruned recipe ${p.recipe} → ${p.sibling} (${p.profiles.join(", ")})`);
+    }
+    for (const k of pruneResult.kept) {
+        console.log(`  kept recipe ${k.recipe} — ${k.reason}`);
+    }
     for (const w of warnings)
         console.log(`  ${pc.yellow("warn")} ${w}`);
-    console.log(`  next: run \`craftar status --workspace <dir>\` in a workspace on profile ${o.profile} to see what moved`);
+    // Spec 25 §4.2: impact lines, one per workspace, with suffix format
+    for (let i = 0; i < impactResults.length; i++) {
+        const ws = impactEntries[i];
+        const r = impactResults[i];
+        let stateStr;
+        if (r.state === "no-effect") {
+            stateStr = "no effect";
+        }
+        else if (r.state === "changed") {
+            const n = r.files.length;
+            stateStr = n === 1 ? `1 file changes — ${r.files[0]}` : `${n} files change — ${r.files.join(", ")}`;
+        }
+        else if (r.state === "missing") {
+            stateStr = "missing";
+        }
+        else {
+            stateStr = `error: ${r.error}`;
+        }
+        const impactSuffix = matchSuffix(ws);
+        console.log(`  impact: ${ws.entry.path} (${ws.entry.profile}) ${stateStr}${impactSuffix}`);
+    }
+    // Spec 25 §4.2: the next: hint is printed only when no workspace was checked
+    // (every entry missing/stage-config error, or no entries, or --no-impact, or unreadable)
+    const someChecked = impactBefore.some((p) => p.kind !== "missing" && !(p.kind === "error" && p.stage === "config"));
+    if (!someChecked) {
+        console.log(`  next: run \`craftar status --workspace <dir>\` in a workspace on profile ${o.profile} to see what moved`);
+    }
+});
+/* ---------------------------------------------------------------- cache ---------------------------------------------------------------- */
+const cache = program.command("cache").description("The per-machine Forge cache in $CRAFTAR_HOME/forges/");
+cache
+    .command("prune")
+    .description("Remove the Forge cache entries nothing uses — no registered workspace and not this one — the entries whose first fetch never completed, and trees unused for 14 days; --dry-run only shows. Never touches a workspace, a lock or the registry; no network")
+    // No commander default: an explicit --workspace without craftar.yaml exits 1, the current directory without one runs (spec 26 §4.1).
+    .option("--dry-run", "show what would be removed; remove nothing", false)
+    .option("--workspace <dir>", "the workspace whose Forge counts as used besides the registry (default: the current directory, when it holds craftar.yaml)")
+    .option("--json", "machine-readable output", false)
+    .action(async (o) => {
+    let workspace = null;
+    if (o.workspace !== undefined) {
+        if (!(await exists(path.join(o.workspace, WORKSPACE_FILE))))
+            fail(`no ${WORKSPACE_FILE} in ${path.resolve(o.workspace)} — run cache prune inside a workspace, or without --workspace`);
+        workspace = o.workspace;
+    }
+    else if (await exists(path.join(process.cwd(), WORKSPACE_FILE)))
+        workspace = process.cwd();
+    const result = await pruneCache(craftarHome(), {
+        dryRun: o.dryRun,
+        workspace,
+        registryOff: registryOff(),
+    });
+    if (o.json)
+        console.log(JSON.stringify(result.report, null, 2));
+    else
+        printPrune(result);
 });
 program.parseAsync().catch((e) => fail(e instanceof Error ? e.message : String(e)));
 /* ---------------------------------------------------------------- helpers */
@@ -1224,6 +1586,65 @@ function printDoctor(r) {
         console.log(`  ${paint(c.level)} ${c.id.padEnd(13)} ${c.message}${suffix(c)}`);
     console.log(`summary: ${r.summary.ok} ok, ${r.summary.warn} warn, ${r.summary.error} error`);
 }
+/** The text report of `craftar cache prune` (spec 26 §4.4) — presentation, not contract. */
+function printPrune(result) {
+    const mb = (b) => `${(b / (1024 * 1024)).toFixed(1)} MB`;
+    if (result.header === null) {
+        console.log("nothing to prune");
+        for (const w of result.report.warnings)
+            console.log(`  ${pc.yellow("warn")} ${w}`);
+        return;
+    }
+    const { forges, entries, bytes } = result.header;
+    console.log(pc.bold(`craftar cache prune — ${forges} (${entries} ${entries === 1 ? "entry" : "entries"}, ${mb(bytes)})`));
+    // Compute label width: for entries/leftovers, just the key; for trees, `<key>/trees/<first 10 of commit>…`.
+    const labelOf = (r) => {
+        const p = r.path;
+        if ("kind" in r && r.kind === "tree") {
+            // forges/<key>/trees/<commit> → <key>/trees/<commit10>…
+            const parts = p.split("/");
+            return `${parts[1]}/trees/${parts[3].slice(0, 10)}…`;
+        }
+        // forges/<key> or forges/~removing-<...> → last segment
+        return p.split("/").pop();
+    };
+    const whyRemoved = (r) => {
+        if (r.reason === "orphan")
+            return "orphan: nothing names it";
+        if (r.reason === "incomplete")
+            return "incomplete: a fetch never completed";
+        if (r.reason === "unused")
+            return "unused for 14 days or more";
+        return "leftover of an interrupted prune";
+    };
+    const whyKept = (k) => {
+        if (k.reason === "named")
+            return `named by ${k.namedBy.join(", ")}`;
+        if (k.reason === "busy")
+            return "in use";
+        if (k.reason === "held-open")
+            return "held open";
+        return "not checked";
+    };
+    // Compute column widths W (label) and V (why) across removed and kept rows.
+    const allLabels = [...result.report.removed, ...result.report.kept].map(labelOf);
+    const removedWhys = result.report.removed.map(whyRemoved);
+    const keptWhys = result.report.kept.map(whyKept);
+    const W = Math.max(1, ...allLabels.map((l) => l.length));
+    const V = Math.max(1, ...removedWhys.map((w) => w.length), ...keptWhys.map((w) => w.length));
+    const verb = result.report.dryRun ? "would remove" : "removed";
+    for (const r of result.report.removed) {
+        console.log(`  ${verb.padEnd(12)} ${labelOf(r).padEnd(W)} ${whyRemoved(r).padEnd(V)} ${mb(r.bytes)}`);
+    }
+    for (const k of result.report.kept) {
+        console.log(`  ${"kept".padEnd(12)} ${labelOf(k).padEnd(W)} ${whyKept(k)}`);
+    }
+    for (const w of result.report.warnings) {
+        console.log(`  ${pc.yellow("warn")} ${w}`);
+    }
+    const freedVerb = result.report.dryRun ? "would free" : "freed";
+    console.log(`${freedVerb} ${mb(result.report.freedBytes)}`);
+}
 /** `CRAFTAR_NO_REGISTRY` — "no registry", read like NO_COLOR: any non-empty value turns it off (spec 21 §4.1). */
 function registryOff() {
     return Boolean(process.env.CRAFTAR_NO_REGISTRY);
@@ -1272,6 +1693,20 @@ function warnStderr(warnings) {
     for (const w of warnings)
         console.error(`${pc.yellow("warn")} ${w}`);
 }
+/**
+ * Spec 25 §4.1–§4.2: the suffix format for a workspace that is not a path match.
+ * Used by both `forge impact` and `forge unify` so the format is shared.
+ */
+function matchSuffix(ws) {
+    let suffix = "";
+    if (ws.match === "remote")
+        suffix = ` · after push (${ws.via})`;
+    if (ws.match === "clone")
+        suffix = ` · after push and pull (${ws.via})`;
+    if (ws.ref)
+        suffix += `, pins ${ws.ref}`;
+    return suffix;
+}
 /** The header line naming a remote Forge (spec 13 §4.1); null for a path Forge, whose headers keep their shape. */
 function forgeLine(ws, lock) {
     const o = ws.origin;