craftar 0.23.0 → 0.25.0

package/dist/cli.js

@@ -22,7 +22,8 @@ import { preferredLine, renderImportReport } from "./core/import-report.js";
 import { driftList, unmanaged } from "./core/drift.js";
 import { diffIngredients, listVariants, profileOf } from "./core/variants.js";
 import { hashNormalized, toLf, stripBom } from "./core/text.js";
-import { exists, gitDirty, gitIsRepo, gitUnheld, loadForge } from "./core/forge.js";
+import { exists, gitDirty, gitIgnored, gitIsRepo, gitUnheld, loadForge } from "./core/forge.js";
+import { applyBasePromotion, planBasePromotion, proveBasePromotion } from "./core/promote.js";
 import { fingerprintDir } from "./core/fingerprint.js";
 import { hunkAt, planFrom, applyPlan, writeUnified, checkRecipeCascade, rewriteRecipes, pruneCandidates, pruneRecipes, note, } from "./core/unify.js";
 import { checkParamWrites, writeParamFile } from "./core/param-writes.js";
@@ -34,6 +35,8 @@ import { localKeys, readLocalFile } from "./core/workspace-yaml.js";
 import { HUNK_CLASSES, INGREDIENT_TYPES, UnifyPlanSchema } from "./schema/index.js";
 import { EXAMPLE_SETTINGS } from "./emitters/shared.js";
 import { YamlSyntaxError, parseYamlText } from "./core/yaml-read.js";
+import { spawn } from "node:child_process";
+import { recordedServices, pendingLine, upRefusal, composeArgv, downArgv, readPs, dockerVersion, dockerFault, dockerRunner, projectName, statusReport } from "./core/services.js";
 import { errorText } from "./core/schema-fault.js";
 process.stdout.on("error", (e) => { if (e.code === "EPIPE")
     process.exit(0); });
@@ -44,7 +47,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.23.0");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.25.0");
 const SAVE_PLAN_GATE = { what: "plan", who: "unify", outside: "save plans outside the Forge", never: "unify never overwrites" };
 const REPORT_GATE = { what: "report", who: "import", outside: "write the report outside the Forge", never: "import never overwrites" };
 program
@@ -1142,7 +1145,7 @@ program
         for (const ing of result.ingredients) {
             const col1 = ing.outputName !== ing.name ? `${ing.name} → ${ing.outputName}` : ing.name;
             allCol1.push(col1);
-            allCol2.push(`targets ${ing.targets === "*" ? "*" : ing.targets.join(", ")}`);
+            allCol2.push(`targets ${ing.targets === "*" ? "*" : (ing.targets.join(", ") || "none")}`);
             allCol3.push(`in ${ing.recipes.length ? ing.recipes.join(", ") : "no recipe"}`);
         }
         for (const m of result.missing) {
@@ -1164,7 +1167,7 @@ program
             console.log(type);
             for (const ing of ings) {
                 const col1 = ing.outputName !== ing.name ? `${ing.name} → ${ing.outputName}` : ing.name;
-                const col2 = `targets ${ing.targets === "*" ? "*" : ing.targets.join(", ")}`;
+                const col2 = `targets ${ing.targets === "*" ? "*" : (ing.targets.join(", ") || "none")}`;
                 const col3 = `in ${ing.recipes.length ? ing.recipes.join(", ") : "no recipe"}`;
                 const desc = ing.description ? `— ${ing.description}` : "";
                 const disabled = ing.disabled ? "(disabled by this workspace)" : "";
@@ -1299,6 +1302,9 @@ program
     for (const line of pathLines) {
         console.log(`  ${line.label.padEnd(maxLabelLen)}  ${line.content}`);
     }
+    console.log();
+    // Service line — text mode only (spec 31 §4.7: no JSON key, one line in the paths block)
+    console.log("  service: written by sync under .craftar/ for no target; see craftar services");
     for (const w of warnings)
         console.log(`  ${pc.yellow("warn")} ${w}`);
 });
@@ -1955,24 +1961,7 @@ forge
         console.log(`  ${pc.yellow("warn")} ${w}`);
     // 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}`);
+        console.log(`  ${impactLine(impactEntries[i], impactResults[i])}`);
     }
     // 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)
@@ -1981,6 +1970,269 @@ forge
         console.log(`  next: run \`craftar status --workspace <dir>\` in a workspace on profile ${o.profile} to see what moved`);
     }
 });
+forge
+    .command("promote")
+    .description("Make a profile's variant the base: the base takes the variant's files, every other profile that resolves the old base gets it back as its own variant through a recipe it owns, and every profile is proved to resolve the same ingredients before anything is written. Writes to the Forge")
+    .argument("<type/name>", "base ingredient (rule/workflow)")
+    .requiredOption("--profile <p>", "the profile whose variant becomes the base")
+    .option("--forge <dir>", "Forge directory (instead of --workspace)")
+    .option("--workspace <dir>", "workspace whose craftar.yaml names the Forge (default: .)")
+    .option("--no-impact", "skip planning the registered workspaces of this Forge before and after the writes")
+    .option("--dry-run", "run every check and the first impact pass, print what would be written, and write nothing", false)
+    .option("--json", "machine-readable output", false)
+    .action(async (ref, o) => {
+    // Never through the cache, as `forge unify` (spec 13 §4.4).
+    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>`,
+    });
+    // P2 (spec 29 §4.4): git is the undo, so it must be there, hold a commit and be clean — before anything is planned.
+    if (f.commit === null) {
+        if (await gitIsRepo(f.root))
+            fail(`${f.root} has no commits yet — forge promote writes to the Forge and needs git as the undo`);
+        fail(`${f.root} is not a git repository — forge promote writes to the Forge and needs git as the undo`);
+    }
+    if (await gitDirty(f.root))
+        fail(`${f.root} is not a clean git checkout — commit or stash your changes first`);
+    const promotion = await planBasePromotion(f, ref, o.profile);
+    const forgeRel = (abs) => path.relative(f.root, abs).split(path.sep).join("/");
+    // Every path overwritten or deleted must be held by git; a path created must not be one git ignores, or `git clean` would not undo it.
+    const unheld = await gitUnheld(f.root, promotion.mustHold);
+    for (const w of promotion.writes) {
+        if (w.created && (await gitIgnored(f.root, forgeRel(w.abs))))
+            unheld.push({ path: forgeRel(w.abs), reason: "ignored" });
+    }
+    if (unheld.length)
+        fail(unheldMessage("forge promote", f.root, unheld));
+    await proveBasePromotion(f, promotion);
+    let impactState = "skipped";
+    let impactEntries = [];
+    let impactBefore = [];
+    const warnings = [...promotion.warnings];
+    if (o.impact) {
+        try {
+            const fw = await forgeWorkspaces(craftarHome(), f.root);
+            impactEntries = fw.workspaces;
+            warnings.push(...fw.warnings);
+            impactBefore = await planAll(fw.workspaces, f);
+            impactState = refineRegistryState(fw.state, impactBefore);
+        }
+        catch (e) {
+            impactState = "unreadable";
+            warnings.push(`the registry could not be read (${e instanceof Error ? e.message : String(e)}) — no workspace was checked`);
+        }
+        if (impactState === "off")
+            warnings.push("the registry is off — no workspace was checked");
+    }
+    // The references the Forge cannot see (spec 29 §4.4): a workspace adding a shared recipe that names the base, removing
+    // one this run copies for its profile, or disabling the base or the variant by name, follows the Forge at its next sync, not this promotion.
+    const shared = [...f.recipes.values()].filter((r) => r.ingredients.includes(promotion.base) && !promotion.recipes.edited.includes(r.name)).map((r) => r.name);
+    const split = promotion.recipes.created.map((r) => r.from);
+    const byName = (doc) => {
+        const d = (typeof doc === "object" && doc !== null ? doc : {});
+        const add = Array.isArray(d.recipes?.add) ? d.recipes.add : [];
+        const remove = Array.isArray(d.recipes?.remove) ? d.recipes.remove : [];
+        const disable = Array.isArray(d.overrides?.ingredients?.disable) ? d.overrides.ingredients.disable : [];
+        // A removed recipe the profile no longer names (it names the copy) stops removing anything.
+        return add.some((r) => shared.includes(r)) || remove.some((r) => split.includes(r)) || disable.some((r) => r === promotion.base || r === promotion.removed);
+    };
+    for (const c of concerned(impactBefore, impactEntries, byName).concerned) {
+        warnings.push(`${c.path} (${c.file}) adds or removes a recipe that names ${promotion.base}, or disables ${promotion.base} or ${promotion.removed}, by name — its next sync follows the Forge, not this promotion`);
+    }
+    const journal = [];
+    if (!o.dryRun) {
+        try {
+            await applyBasePromotion(promotion, journal);
+        }
+        catch (e) {
+            // After writing began: name what was touched and how git undoes it, and still exit 1.
+            fail(lateFailure(e, f.root, journal, "forge promote"));
+        }
+    }
+    const checked = impactState !== "skipped" && impactState !== "unreadable" && impactState !== "off";
+    let impactResults = [];
+    if (!o.dryRun && checked && impactEntries.length > 0) {
+        let impactAfter;
+        try {
+            impactAfter = await planAll(impactEntries, await loadForge(f.root));
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            impactAfter = impactEntries.map(() => ({ kind: "error", stage: "plan", message }));
+        }
+        impactResults = impactEntries.map((_, i) => impactOf(impactBefore[i], impactAfter[i]));
+    }
+    if (o.json) {
+        return console.log(JSON.stringify({
+            base: promotion.base,
+            profile: promotion.profile,
+            dryRun: o.dryRun,
+            removed: promotion.removed,
+            // Every key is always present, `[]` when empty.
+            created: promotion.created,
+            recipes: promotion.recipes,
+            profiles: promotion.profiles,
+            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,
+            })),
+            warnings,
+        }, null, 2));
+    }
+    const n = (count) => `${count} workspace(s)`;
+    console.log(pc.bold(`craftar forge promote ${promotion.base} ← ${promotion.profile}${o.dryRun ? " (dry run — nothing written)" : ""}`));
+    console.log(`  base     ${promotion.base} ${o.dryRun ? "would hold" : "now holds"} ${promotion.profile}'s text (was ${promotion.removed})`);
+    for (const c of promotion.created)
+        console.log(`  variant  ${c} ${o.dryRun ? "would be created" : "created"} (the old base)`);
+    if (promotion.discarded)
+        console.log(`  the old base is resolved by no profile — discarded (git holds it)`);
+    const recipeLines = [...promotion.detail.recipes.filter((r) => r.from === null), ...promotion.detail.recipes.filter((r) => r.from !== null)];
+    for (const r of recipeLines)
+        console.log(`  recipe   ${r.name}${r.from === null ? "" : ` ${o.dryRun ? "would be created" : "created"} from ${r.from}`}: ${r.old} → ${r.new}`);
+    for (const p of promotion.detail.profiles)
+        console.log(`  profile  ${p.file}: ${p.swaps.map((s) => `${s.old} → ${s.new}`).join(", ")}`);
+    for (const w of warnings)
+        console.log(`  ${pc.yellow("warn")} ${w}`);
+    if (checked) {
+        if (impactEntries.length === 0)
+            console.log(`  impact   no workspace of this Forge is registered on this machine`);
+        else if (o.dryRun)
+            console.log(`  impact   ${n(impactEntries.length)} planned: not written, not compared`);
+        else if (impactResults.every((r) => r.state === "no-effect"))
+            console.log(`  impact   ${n(impactResults.length)} planned before and after: no effect`);
+        else
+            for (let i = 0; i < impactResults.length; i++)
+                console.log(`  ${impactLine(impactEntries[i], impactResults[i])}`);
+    }
+    if (promotion.created.length)
+        console.log(`  next     craftar forge variants — the old base now shows as ${promotion.created.length} variant(s) to unify`);
+});
+/* ---------------------------------------------------------------- services ---------------------------------------------------------------- */
+const services = program.command("services").description("Local services of this workspace: run Docker Compose on what craftar.lock records under .craftar/");
+/** The workspace's lock, read without the Forge: these commands need no plan and no network (spec 31 §4.2). */
+async function servicesContext(dir) {
+    const { root, real } = await servicesBase(dir);
+    return { root, real, recorded: await recordedServices(root, await readLock(root)) };
+}
+/** The base workspace info without the lock read — `down` catches the lock read separately. */
+async function servicesBase(dir) {
+    const root = path.resolve(dir);
+    if (!(await exists(path.join(root, WORKSPACE_FILE))))
+        fail(`no ${WORKSPACE_FILE} in ${root} — run craftar services inside a workspace, or pass --workspace <dir>`);
+    return { root, real: await fs.realpath(root) };
+}
+/** Helper to get the .env file path if it exists, or null. */
+async function envFileOrNull(root) {
+    const env = path.join(root, ".env");
+    return (await exists(env)) ? env : null;
+}
+/** Runs `docker compose` with the terminal's own streams and resolves with its exit code. No shell. */
+function runCompose(argv, real) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("docker", argv, { stdio: "inherit", env: { ...process.env, CRAFTAR_WORKSPACE: real } });
+        child.on("error", reject);
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+}
+services
+    .command("up")
+    .description("Start the services (docker compose up -d) — refused when a recorded file is missing or edited")
+    .argument("[service...]", "Compose service names to start (default: all)")
+    .option("--wait", "wait until the services are running or healthy", false)
+    .option("--workspace <dir>", "workspace root", ".")
+    .action(async (names, o) => {
+    try {
+        const { root, real, recorded } = await servicesContext(o.workspace);
+        const refusal = upRefusal(recorded, names);
+        if (refusal.length)
+            fail(refusal.join("\n"));
+        const fault = dockerFault(await dockerVersion(dockerRunner), true);
+        if (fault !== null)
+            fail(fault);
+        const argv = composeArgv("up", { project: projectName(real), stack: path.join(root, ".craftar", "compose.yaml"), envFile: await envFileOrNull(root), wait: o.wait, services: names });
+        process.exitCode = await runCompose(argv, real);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e));
+    }
+});
+services
+    .command("down")
+    .description("Stop the services (docker compose down) — never refused on the files")
+    .option("--volumes", "also remove the volumes the stack declares", false)
+    .option("--workspace <dir>", "workspace root", ".")
+    .action(async (o) => {
+    try {
+        const { root, real } = await servicesBase(o.workspace);
+        // Try to read the lock — if it fails, warn and stop by name only
+        let recorded = null;
+        try {
+            recorded = await recordedServices(root, await readLock(root));
+        }
+        catch (e) {
+            console.error(`${pc.yellow("warn")} ${errorText(e)}`);
+        }
+        const docker = await dockerVersion(dockerRunner);
+        const fault = dockerFault(docker, false);
+        if (fault !== null)
+            fail(fault);
+        // Use downArgv for the full decision — `-f` and `--env-file` only when lock was read and stack is usable
+        const argv = downArgv(projectName(real), recorded, docker, path.join(root, ".craftar", "compose.yaml"), await envFileOrNull(root), o.volumes);
+        process.exitCode = await runCompose(argv, real);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e));
+    }
+});
+services
+    .command("status")
+    .description("The declared services and their containers — reports, never refused on the files")
+    .option("--json", "machine-readable output", false)
+    .option("--workspace <dir>", "workspace root", ".")
+    .action(async (o) => {
+    try {
+        const { real, recorded } = await servicesContext(o.workspace);
+        const docker = await dockerVersion(dockerRunner);
+        let ps = null;
+        let psFault = dockerFault(docker, false);
+        if (psFault === null) {
+            const r = await dockerRunner("docker", composeArgv("ps", { project: projectName(real), stack: null, envFile: null }));
+            if (r.code === 0)
+                ps = readPs(r.stdout);
+            else
+                psFault = `docker compose ps failed — ${r.stderr.trim().split("\n")[0] || `exit ${r.code}`}`;
+        }
+        const report = statusReport(real, recorded, docker, ps, psFault);
+        if (o.json)
+            console.log(JSON.stringify(report, null, 2));
+        else {
+            console.log(pc.bold(`craftar services — project ${report.project}`));
+            if (report.services.length === 0)
+                console.log("  no service declared");
+            const w = Math.max(0, ...report.services.map((s) => s.name.length));
+            for (const s of report.services) {
+                const ports = s.ports.map((p) => `${p.host}:${p.container}/${p.protocol}`).join(", ");
+                console.log(`  ${s.name.padEnd(w)}  ${s.ingredient ?? "(not declared)"}  ${s.state}${s.health ? ` (${s.health})` : ""}${ports ? `  ${ports}` : ""}`);
+            }
+            for (const p of report.pending)
+                console.log(`  ${pc.yellow(pendingLine(p))}`);
+            for (const x of report.warnings)
+                console.error(`${pc.yellow("warn")} ${x}`);
+        }
+        if (psFault !== null)
+            process.exitCode = 1;
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e));
+    }
+});
 /* ---------------------------------------------------------------- cache ---------------------------------------------------------------- */
 const cache = program.command("cache").description("The per-machine Forge cache in $CRAFTAR_HOME/forges/");
 cache
@@ -2146,6 +2398,19 @@ function warnStderr(warnings) {
     for (const w of warnings)
         console.error(`${pc.yellow("warn")} ${w}`);
 }
+/** One workspace's line after a Forge write was planned before and after (spec 25 §4.2) — `forge unify` and `forge promote` print the same. */
+function impactLine(ws, r) {
+    let state;
+    if (r.state === "no-effect")
+        state = "no effect";
+    else if (r.state === "changed")
+        state = r.files.length === 1 ? `1 file changes — ${r.files[0]}` : `${r.files.length} files change — ${r.files.join(", ")}`;
+    else if (r.state === "missing")
+        state = "missing";
+    else
+        state = `error: ${r.error}`;
+    return `impact: ${ws.entry.path} (${ws.entry.profile}) ${state}${matchSuffix(ws)}`;
+}
 /**
  * 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.