craftar 0.32.1 → 0.34.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import pc from "picocolors";
 import path from "node:path";
-import { promises as fs } from "node:fs";
+import { promises as fs, statSync } from "node:fs";
 import YAML from "yaml";
 import { importClaudeCode } from "./importers/claude-code.js";
 import { parsePreferKiro } from "./importers/prefer-kiro.js";
@@ -16,7 +16,7 @@ import { launchRefusal, pinOf } from "./core/mcp-protocol.js";
 import { serve } from "./mcp.js";
 import { pruneCache } from "./core/cache.js";
 import { resolveHome } from "./core/home-lock.js";
-import { loadWorkspace, readWorkspaceConfig, plan, readLock, status, apply, unsetDeclared, unsetRefusal, unsetRefused, agentsMdOverBudget, agentsMdRefusal, resolveForge, resolveForgeSource, WORKSPACE_FILE, LOCAL_FILE } from "./core/sync.js";
+import { loadWorkspace, loadForgeSource, readWorkspaceConfig, plan, readLock, status, apply, unsetDeclared, unsetRefusal, unsetRefused, agentsMdOverBudget, agentsMdRefusal, resolveForge, resolveForgeSource, WORKSPACE_FILE, LOCAL_FILE } from "./core/sync.js";
 import { sectionKey } from "./core/resolve.js";
 import { catalogueContext, listRecipes, listIngredients, checkType, withLoadWarnings } from "./core/catalogue.js";
 import { canonicalValue } from "./core/sections.js";
@@ -25,13 +25,18 @@ import { preferredLine, renderImportReport } from "./core/import-report.js";
 import { driftList, unmanaged } from "./core/drift.js";
 import { EXAMPLE_CONTENT_HIDDEN, diffReport, explainFile, explainSkip, notProduced, readText, statusPath, statusReport, targetsReport } from "./core/report.js";
 import { diffIngredients, listVariants, profileOf } from "./core/variants.js";
-import { exists, gitDirty, gitIgnored, gitIsRepo, gitUnheld, loadForge } from "./core/forge.js";
+import { exists, gitDirty, gitIgnored, gitIsRepo, gitUnheld, loadForge, realpathOfNearest } 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";
-import { checkInitFlags, initLine, planInit } from "./core/init.js";
-import { askInit, confirmInit, againLine } from "./core/init-flow.js";
+import { checkInitFlags, checkLocalKeys, initLine, planInit, forgeSource } from "./core/init.js";
+import { profileName } from "./core/new-profile.js";
+import { newProfileGate } from "./core/new-profile-gate.js";
+import { writeNewProfile, reproveFromDisk, NewProfileRaceLost, NewProfileLateFailure } from "./core/new-profile-write.js";
+import { askInit, askClone, confirmInit, againLine, NOT_CLONED_REFUSED } from "./core/init-flow.js";
+import { findGit, cloneRepos, listRepos, planClone } from "./core/clone.js";
+import { byHand, profileRepos } from "./core/repos.js";
 import { readlineIo } from "./prompt.js";
 import { editRecipesText, planRecipeEdit, recipeDiffLine } from "./core/recipe-edit.js";
 import { localKeys, readLocalFile } from "./core/workspace-yaml.js";
@@ -52,7 +57,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.32.1");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.34.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
@@ -220,24 +225,98 @@ async function applyAndReport(ws, p, st, lock, opts = {}) {
         console.log(`  ${pc.yellow("warn")} ${registryWarning}`);
     return r;
 }
+/**
+ * Shared clone report for `craftar init --clone` and `craftar repos clone`.
+ * Prints the header, the present rows first, then the clone rows (cloned/failed), each group
+ * in the profile's order. Returns whether any clone failed.
+ *
+ * @param header The bold header line (without the leading text, which is added here)
+ * @param results The clone results (cloned or failed)
+ * @param skipped The entries that were skipped (present state)
+ * @param root The workspace root, used for the by-hand message
+ * @param opts.reposCloneLine Whether to print the "or, from the workspace: craftar repos clone ..." line
+ */
+function printCloneReport(header, results, skipped, root, opts) {
+    console.log(pc.bold(header));
+    const rows = [];
+    for (const e of skipped) {
+        rows.push({ state: "present", name: e.name, path: e.path });
+    }
+    for (const r of results) {
+        if (r.outcome === "cloned") {
+            rows.push({ state: "cloned", name: r.entry.name, path: r.entry.path });
+        }
+        else {
+            rows.push({ state: "failed", name: r.entry.name, path: r.entry.path, reason: r.reason });
+        }
+    }
+    // Compute column widths: sw = longest state, nw = longest name
+    const sw = Math.max(...rows.map((r) => r.state.length));
+    const nw = Math.max(...rows.map((r) => r.name.length));
+    // Print rows
+    for (const r of rows) {
+        let line = `  ${r.state.padEnd(sw)}  ${r.name.padEnd(nw)}  → ${r.path}`;
+        if (r.state === "present") {
+            line += "  (not cloned)";
+        }
+        else if (r.state === "failed" && r.reason) {
+            line += `  (${r.reason})`;
+        }
+        console.log(line);
+    }
+    // Failure report
+    const failed = results.filter((r) => r.outcome === "failed");
+    if (failed.length > 0) {
+        const ok = results.length - failed.length;
+        const n = results.length;
+        console.log(`  ${ok} of ${n} cloned — clone the rest by hand, in ${root}:`);
+        for (const f of failed) {
+            console.log(`    ${byHand(f.entry)}`);
+        }
+        if (opts.reposCloneLine) {
+            const failedNames = failed.map((f) => f.entry.name);
+            console.log(`  or, from the workspace: craftar repos clone ${failedNames.join(" ")}`);
+        }
+    }
+    return failed.length > 0;
+}
+/**
+ * The clone step for `craftar init --clone`: clones the entries, prints the report, sets exitCode on failures.
+ * Calls `again()` at the end.
+ */
+async function runCloneStep(root, profile, entries, git, again) {
+    const n = entries.length;
+    const repoWord = n === 1 ? "repository" : "repositories";
+    const results = await cloneRepos(root, entries, { git, env: process.env, stdinIsTty: process.stdin.isTTY === true });
+    const header = `craftar init — cloning ${n} ${repoWord} of ${profile}`;
+    const anyFailed = printCloneReport(header, results, [], root, { reposCloneLine: true });
+    if (anyFailed)
+        process.exitCode = 1;
+    again();
+}
 /* ---------------------------------------------------------------- init */
 program
     .command("init")
-    .description("Start a workspace from a Forge and a profile: write a craftar.yaml proved to resolve and plan, then run the first sync; in a terminal, asks for the Forge and the profile not given as flags; refused when craftar.yaml already exists")
+    .description("Start a workspace from a Forge and a profile: write a craftar.yaml proved to resolve and plan, then run the first sync; with --new-profile, create the profile in the Forge directory first (recipes and targets from --like and the recipe/target flags), then start the workspace on it — nothing is committed; with --clone, clone the profile's repositories into the workspace (after the first sync, or with --no-sync after writing craftar.yaml); in a terminal, asks for the Forge and the profile not given as flags; refused when craftar.yaml already exists")
     .option("--forge <dir|url>", "the Forge: a directory (written relative to the workspace) or a git URL; asked for in a terminal when omitted")
     .option("--profile <name>", "the client profile in the Forge; asked for in a terminal when omitted")
+    .option("--new-profile <name>", "create this profile in the Forge directory (recipes and targets from --like and the recipe flags), then start the workspace on it; nothing is committed")
+    .option("--like <profile>", "with --new-profile: start the new profile's recipes and targets from this profile's — nothing else of it is copied")
     .option("--ref <ref>", "branch, tag or full SHA of a remote Forge")
-    .option("--targets <a,b>", "targets to write in craftar.yaml (claude-code, kiro, agents-md); omitted, the workspace follows the profile's")
-    .option("--add-recipe <name>", "add a recipe to the profile's (repeatable)", collect, [])
-    .option("--remove-recipe <name>", "remove a recipe of the profile's (repeatable)", collect, [])
+    .option("--targets <a,b>", "targets to write in craftar.yaml, or of the new profile with --new-profile (claude-code, kiro, agents-md); omitted, the workspace follows the profile's")
+    .option("--add-recipe <name>", "add a recipe to the profile's, or to the new profile's with --new-profile (repeatable)", collect, [])
+    .option("--remove-recipe <name>", "remove a recipe from the profile's, or from the new profile's with --new-profile (repeatable)", collect, [])
     .option("--replace", "let --add-recipe take a slot another recipe holds", false)
     .option("--no-sync", "write craftar.yaml only, and say what the first sync would do")
+    .option("--clone", "after the first sync, clone the profile's repositories (its repos list) into the workspace")
+    .option("--no-clone", "do not clone, and do not ask")
     .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
     .option("--workspace <dir>", "workspace root, created when missing", ".")
     .action(async (o, cmd) => {
     const root = path.resolve(o.workspace);
     // N1: craftar.yaml already exists
-    const n1 = () => fail(`${WORKSPACE_FILE} already exists in ${root} — change recipes with craftar add recipe / remove recipe, or edit it`);
+    const n1Text = `${WORKSPACE_FILE} already exists in ${root} — change recipes with craftar add recipe / remove recipe, or edit it`;
+    const n1 = () => fail(n1Text);
     const file = path.join(root, WORKSPACE_FILE);
     if (await exists(file))
         n1();
@@ -265,15 +344,42 @@ program
         addRecipes: o.addRecipe,
         removeRecipes: o.removeRecipe,
     });
+    // C1: --clone and --no-clone cannot be given together
+    if (process.argv.includes("--clone") && process.argv.includes("--no-clone")) {
+        fail("pass --clone or --no-clone, not both");
+    }
+    // C2: --clone with --offline
+    if (o.clone === true && o.offline) {
+        fail("--clone needs the network — drop --offline, or clone later with git");
+    }
+    // C6: --clone with no git on PATH
+    const git = await findGit(process.env);
+    if (o.clone === true && git === null) {
+        fail("cloning needs git — install it, or leave the clone out");
+    }
+    // P1–P4: --new-profile checks (before anything is read)
+    if (o.newProfile !== undefined && o.profile !== undefined) {
+        fail("pass --profile or --new-profile, not both");
+    }
+    if (o.like !== undefined && o.newProfile === undefined) {
+        fail("--like goes with --new-profile");
+    }
+    if (o.newProfile !== undefined) {
+        profileName(o.newProfile);
+    }
+    if (o.newProfile !== undefined && o.forge !== undefined && classifyForge(o.forge) === "url") {
+        fail("a new profile is written into a Forge directory — clone the Forge, pass that directory as --forge, then commit and push the profile");
+    }
     // Mode: flags when both given; else interactive when both streams are TTYs; else N2
-    const bothGiven = o.forge !== undefined && o.profile !== undefined;
+    // --new-profile counts as --profile for bothGiven and N2
+    const bothGiven = o.forge !== undefined && (o.profile !== undefined || o.newProfile !== undefined);
     const isTTY = process.stdin.isTTY && process.stdout.isTTY;
     if (!bothGiven && !isTTY) {
         // N2: refuse with our message
-        if (o.forge === undefined && o.profile === undefined) {
+        if (o.forge === undefined && o.profile === undefined && o.newProfile === undefined) {
             fail("--forge and --profile are required when craftar init does not run in a terminal — pass them, or run craftar init in a terminal to be asked");
         }
-        else if (o.profile === undefined) {
+        else if (o.profile === undefined && o.newProfile === undefined) {
             fail("--profile is required when craftar init does not run in a terminal — pass it, or run craftar init in a terminal to be asked");
         }
         else {
@@ -289,17 +395,46 @@ program
         const result = await askInit(root, {
             forge: o.forge,
             profile: o.profile,
+            newProfile: o.newProfile,
+            like: o.like,
             ref: o.ref,
             targets: o.targets === undefined ? undefined : o.targets.split(",").map((t) => t.trim()),
             addRecipes: o.addRecipe,
             removeRecipes: o.removeRecipe,
             replace: o.replace,
+            clone: o.clone,
         }, local, io, { ...load(o, "sync"), registryOff: registryOff() });
         if (result.kind === "cancelled")
             fail("init cancelled — nothing written");
         input = result.input;
         answers = result.answers;
     }
+    else if (o.newProfile !== undefined) {
+        // --forge and --new-profile given (flags mode with new profile)
+        // N10 (spec 38 §4.2): the one check, before the load — --new-profile counts as --profile there
+        checkLocalKeys(local.keys, {
+            ref: o.ref !== undefined,
+            recipes: o.addRecipe.length > 0 || o.removeRecipe.length > 0,
+            targets: o.targets !== undefined,
+        });
+        // Load the Forge
+        const loaded = await loadForgeSource(root, forgeSource(root, o.forge), o.ref ?? null, { ...load(o, "sync") });
+        // Gate: P5-P8
+        await newProfileGate(loaded.forge, resolveHome(process.env.CRAFTAR_HOME || undefined), o.newProfile);
+        // Build input
+        input = {
+            forge: o.forge,
+            profile: o.newProfile,
+            newProfile: { name: o.newProfile, like: o.like },
+            ref: o.ref,
+            targets: o.targets === undefined ? undefined : o.targets.split(",").map((t) => t.trim()),
+            addRecipes: o.addRecipe,
+            removeRecipes: o.removeRecipe,
+            replace: o.replace,
+            clone: o.clone === true,
+            loaded,
+        };
+    }
     else {
         input = {
             forge: o.forge,
@@ -309,41 +444,126 @@ program
             addRecipes: o.addRecipe,
             removeRecipes: o.removeRecipe,
             replace: o.replace,
+            clone: o.clone === true,
         };
     }
-    const init = await planInit(root, input, { ...load(o, "sync"), local });
+    let init = await planInit(root, input, { ...load(o, "sync"), local });
+    // Interactive mode: when o.clone is undefined, ask about cloning between planInit and confirmInit
+    // --clone typed: planInit has checked C3–C5 and returned the entries, in either mode
+    let cloneEntries = o.clone === true ? init.repos : [];
+    let cloneRefused = false;
     if (answers !== null) {
+        if (o.clone === undefined) {
+            const io = readlineIo(process.stdin, process.stdout, { terminal: true });
+            const cloneResult = await askClone(io, init, { root, offline: o.offline, git });
+            if (cloneResult === "cancelled")
+                fail("init cancelled — nothing written");
+            cloneEntries = cloneResult.entries;
+            cloneRefused = cloneResult.refused === true;
+        }
         const io = readlineIo(process.stdin, process.stdout, { terminal: true });
-        const confirm = await confirmInit(init, root, io, { sync: o.sync });
+        const confirm = await confirmInit(init, root, io, {
+            sync: o.sync,
+            clone: cloneEntries.length || undefined,
+            cloneRefused: o.clone === true || cloneRefused,
+        });
         if (confirm === "cancelled")
             fail("init cancelled — nothing written");
     }
-    const { ws, plan: p } = init;
+    let { ws, plan: p } = init;
+    const forgeRoot = ws.forge.root;
     const workspaceGiven = cmd.getOptionValueSource("workspace") === "cli";
     const again = () => {
         if (answers !== null) {
-            console.log(againLine(answers, { workspace: workspaceGiven ? o.workspace : undefined, sync: o.sync, offline: o.offline }));
+            console.log(againLine(answers, { workspace: workspaceGiven ? o.workspace : undefined, sync: o.sync, offline: o.offline, clone: cloneEntries.length > 0 }));
         }
     };
+    // When init.newProfile: write the profile, then reprove from disk
+    let journal = [];
+    // Step 1's notes are printed after the initLine line (spec 38), so keep them before reprove
+    const step1Notes = init.notes;
+    if (init.newProfile) {
+        try {
+            journal = await writeNewProfile(forgeRoot, init);
+        }
+        catch (e) {
+            if (e instanceof NewProfileRaceLost) {
+                // P7's first message, no recover lines
+                fail(e.message);
+            }
+            if (e instanceof NewProfileLateFailure) {
+                fail(lateFailure(e, forgeRoot, e.journal, "init"));
+            }
+            throw e;
+        }
+        // Reprove from disk (step 4)
+        try {
+            init = await reproveFromDisk(root, input.forge, init, { ...load(o, "sync") }, journal, input.ref);
+        }
+        catch (e) {
+            if (e instanceof NewProfileLateFailure) {
+                fail(lateFailure(e, forgeRoot, e.journal, "init"));
+            }
+            throw e;
+        }
+        // Update ws and p from the second init
+        ws = init.ws;
+        p = init.plan;
+        // Print the profile creation lines
+        console.log(pc.bold(`craftar init — created profile ${ws.config.profile} in ${forgeRoot}`));
+        console.log(`  + profiles/${ws.config.profile}/profile.yaml   (not committed — commit it in the Forge, on a branch, before anyone else syncs)`);
+    }
     // Every refusal is above: only now does the directory, and craftar.yaml, come to exist
-    await fs.mkdir(root, { recursive: true });
-    try {
-        await fs.writeFile(file, init.text, { flag: "wx" });
+    // When journal is not empty: mkdir inside the try, with late failure handling
+    if (journal.length > 0) {
+        try {
+            await fs.mkdir(root, { recursive: true });
+        }
+        catch (e) {
+            fail(lateFailure(e, forgeRoot, journal, "init"));
+        }
+        try {
+            await fs.writeFile(file, init.text, { flag: "wx" });
+        }
+        catch (e) {
+            if (e.code === "EEXIST") {
+                // N1's text, then lateFailure
+                fail(`${n1Text}\n${lateFailure(e, forgeRoot, journal, "init")}`);
+            }
+            fail(lateFailure(e, forgeRoot, journal, "init"));
+        }
     }
-    catch (e) {
-        if (e.code === "EEXIST")
-            n1();
-        throw e;
+    else {
+        // No journal: existing behaviour unchanged
+        await fs.mkdir(root, { recursive: true });
+        try {
+            await fs.writeFile(file, init.text, { flag: "wx" });
+        }
+        catch (e) {
+            if (e.code === "EEXIST")
+                n1();
+            throw e;
+        }
     }
     console.log(pc.bold(`craftar init — wrote ${WORKSPACE_FILE} in ${root}`));
     console.log(`  ${initLine(init)}`);
-    for (const n of init.notes)
+    for (const n of step1Notes)
         console.log(`  note ${n}`);
     const unset = unsetDeclared(p);
+    const cloning = cloneEntries.length > 0;
+    const refused = unset.length > 0;
     if (!o.sync) {
         console.log(nextSyncLine(init.statuses, unset));
         for (const w of p.warnings)
             console.log(`  ${pc.yellow("warn")} ${w}`);
+        if (cloning && refused && answers === null) {
+            console.log(NOT_CLONED_REFUSED);
+        }
+        else if (cloning && !refused) {
+            // Clone even without sync
+            await runCloneStep(root, ws.config.profile, cloneEntries, git, again);
+            return;
+        }
         again();
         return;
     }
@@ -352,6 +572,9 @@ program
     if (unset.length) {
         for (const w of p.warnings)
             console.log(`  ${pc.yellow("warn")} ${w}`);
+        if (cloning && answers === null) {
+            console.log(NOT_CLONED_REFUSED);
+        }
         refusalBlock(unset, { thenSync: true });
         again();
         process.exitCode = 1;
@@ -361,8 +584,152 @@ program
     const collisions = r.skipped.filter((s) => s.state === "collision").length;
     if (collisions)
         console.log(`  ${pc.yellow("warn")} ${collisions} file(s) already in the workspace differ from the Forge and were left as they are — to bring them into the Forge, run craftar import`);
+    if (cloning) {
+        await runCloneStep(root, ws.config.profile, cloneEntries, git, again);
+        return;
+    }
     again();
 });
+/* ---------------------------------------------------------------- repos */
+// `craftar repos` lists (the command's own action); `craftar repos clone` clones. No `repos list` (spec 37 §13.3 item 29).
+const reposCmd = program
+    .command("repos")
+    .description("List the profile's repositories (its repos list) with their state in this workspace: present, missing or blocked; starts no program but the Forge load, writes nothing")
+    .option("--workspace <dir>", "workspace root", ".")
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
+    .option("--json", "machine-readable output", false)
+    .action(async (o) => {
+    const ws = await loadWorkspace(o.workspace, load(o, "read"));
+    const p = await plan(ws);
+    const lock = await readLock(ws.root);
+    const profile = ws.forge.profiles.get(ws.config.profile);
+    // C4: profileRepos throws for a block that does not read
+    const entries = profileRepos(profile);
+    // No entry → one line, exit 0
+    if (entries.length === 0) {
+        if (o.json) {
+            const out = {
+                workspace: await fs.realpath(ws.root),
+                profile: ws.config.profile,
+                repos: [],
+                warnings: p.warnings,
+            };
+            console.log(JSON.stringify(out, null, 2));
+        }
+        else {
+            console.log(`profile ${ws.config.profile} lists no repositories`);
+            for (const w of p.warnings)
+                console.log(`  ${pc.yellow("warn")} ${w}`);
+        }
+        return;
+    }
+    // Build the destination context: planned paths and lock paths
+    const ctx = {
+        planned: p.files.map((f) => f.path),
+        lockPaths: lock?.files.map((f) => f.path) ?? [],
+        forgeDir: ws.forge.root,
+    };
+    const list = await listRepos(ws.root, entries, ctx);
+    const missing = list.filter((e) => e.state === "missing").length;
+    if (o.json) {
+        const repos = list.map((e) => ({
+            name: e.name,
+            url: e.url,
+            path: e.path,
+            ref: e.ref,
+            state: e.state,
+            reason: e.reason,
+        }));
+        const out = {
+            workspace: await fs.realpath(ws.root),
+            profile: ws.config.profile,
+            repos,
+            warnings: p.warnings,
+        };
+        console.log(JSON.stringify(out, null, 2));
+        return;
+    }
+    // Text output
+    console.log(`repositories of ${ws.config.profile} — ${list.length} in the profile, ${missing} missing`);
+    const sw = 7; // "present" is longest, always
+    const nw = Math.max(...list.map((e) => e.name.length));
+    const pw = Math.max(...list.map((e) => e.path.length));
+    for (const e of list) {
+        let line = `  ${e.state.padEnd(sw)}  ${e.name.padEnd(nw)}  → ${e.path.padEnd(pw)}   ${e.url}`;
+        if (e.ref)
+            line += `  @ ${e.ref}`;
+        if (e.reason)
+            line += `  (${e.reason})`;
+        console.log(line);
+    }
+    for (const w of p.warnings)
+        console.log(`  ${pc.yellow("warn")} ${w}`);
+});
+reposCmd
+    .command("clone")
+    .description("Clone the profile's repositories that are missing in this workspace (all, or the names given); typing the command is the consent; needs a fresh copy of a remote Forge")
+    .argument("[names...]", "repository names to clone (default: all missing)")
+    // No default here: `repos` holds `--workspace` too, and commander gives the value to the parent when both declare it.
+    .option("--workspace <dir>", 'workspace root (default: ".")')
+    .action(async (names, o) => {
+    const workspace = o.workspace ?? reposCmd.opts().workspace ?? ".";
+    // C6: git is needed before any load
+    const git = await findGit(process.env);
+    if (git === null) {
+        fail("cloning needs git — install it, or leave the clone out");
+    }
+    // R4: fetchHint: "fresh-copy" — repos clone refuses a stale cached copy
+    const ws = await loadWorkspace(workspace, { ...load({ offline: false }, "sync"), fetchHint: "fresh-copy" });
+    const p = await plan(ws);
+    const lock = await readLock(ws.root);
+    const profile = ws.forge.profiles.get(ws.config.profile);
+    // Build the destination context
+    const ctx = {
+        planned: p.files.map((f) => f.path),
+        lockPaths: lock?.files.map((f) => f.path) ?? [],
+        forgeDir: ws.forge.root,
+    };
+    // planClone: C3, C4, C5, R1, R2, R3 come out of it
+    const clonePlan = await planClone(ws.root, profile, ctx, {
+        present: "skip",
+        noEntries: "nothing to clone",
+        names: names.length ? names : undefined,
+    });
+    // Nothing to clone and no names given: all are present
+    if (clonePlan.entries.length === 0) {
+        const all = profileRepos(profile);
+        const n = all.length;
+        const repoWord = n === 1 ? "repository" : "repositories";
+        console.log(`all ${n} ${repoWord} of ${ws.config.profile} are present — nothing to clone`);
+        return;
+    }
+    // Clone the entries
+    const results = await cloneRepos(ws.root, clonePlan.entries, { git, env: process.env, stdinIsTty: process.stdin.isTTY === true });
+    // Combine skipped and results in profile order for the report
+    // skipped entries come from planClone, results are in the same order as entries
+    // To merge them in profile order: iterate through all entries and match
+    const allEntries = profileRepos(profile);
+    const skippedNames = new Set(clonePlan.skipped.map((e) => e.name.toLowerCase()));
+    const resultMap = new Map(results.map((r) => [r.entry.name.toLowerCase(), r]));
+    const orderedSkipped = [];
+    const orderedResults = [];
+    for (const e of allEntries) {
+        const lower = e.name.toLowerCase();
+        if (skippedNames.has(lower)) {
+            orderedSkipped.push(clonePlan.skipped.find((s) => s.name.toLowerCase() === lower));
+        }
+        else if (resultMap.has(lower)) {
+            orderedResults.push(resultMap.get(lower));
+        }
+    }
+    // Report
+    const n = clonePlan.entries.length;
+    const repoWord = n === 1 ? "repository" : "repositories";
+    const header = `craftar repos clone — cloning ${n} ${repoWord} of ${ws.config.profile}`;
+    const anyFailed = printCloneReport(header, orderedResults, orderedSkipped, ws.root, { reposCloneLine: false });
+    if (anyFailed)
+        process.exitCode = 1;
+});
 /* ---------------------------------------------------------------- sync */
 program
     .command("sync")
@@ -2691,54 +3058,6 @@ function color(state) {
             return pc.dim;
     }
 }
-/**
- * The real path of `abs`, resolved through its nearest existing ancestor: `fs.realpath` needs the
- * path to exist, and a plan target usually does not yet — so the part that exists is resolved
- * (symlinks and all) and the part that does not is appended as written.
- *
- * It walks up only past a component that truly does not exist (`lstat` says ENOENT/ENOTDIR). Any
- * other outcome throws instead. A component `lstat` cannot inspect (a symlink loop or a permission
- * error on Linux) "cannot be inspected"; one it can inspect but `realpath` cannot follow (a
- * dangling symlink or junction, a loop on Windows) "exists but cannot be resolved". Resolving the
- * rest lexically would let a link that points into the Forge pass the containment check, so the gate
- * fails closed rather than guess where the target lands.
- */
-async function realpathOfNearest(abs) {
-    let head = abs;
-    const tail = [];
-    for (;;) {
-        try {
-            return path.join(await fs.realpath(head), ...tail);
-        }
-        catch (realpathError) {
-            try {
-                await fs.lstat(head);
-            }
-            catch (lstatError) {
-                const code = lstatError.code;
-                if (code === "ENOENT" || code === "ENOTDIR") {
-                    const parent = path.dirname(head);
-                    if (parent === head)
-                        return abs;
-                    tail.unshift(path.basename(head));
-                    head = parent;
-                    continue;
-                }
-                throw cannotResolve(head, lstatError, "cannot be inspected");
-            }
-            throw cannotResolve(head, realpathError, "exists but cannot be resolved");
-        }
-    }
-}
-/**
- * The refusal for a target that cannot be resolved; the caller adds which command cannot prove it. `what` is
- * "cannot be inspected" when `lstat` itself failed, so the path is not known to exist, and "exists but cannot be
- * resolved" when `lstat` succeeded and `realpath` did not.
- */
-function cannotResolve(p, e, what) {
-    const code = e?.code ?? (e instanceof Error ? e.message : String(e));
-    return new Error(`${p} ${what} (${code})`);
-}
 /**
  * The gate of a user-supplied output path (Ruling 30 of spec 06; spec 29 §4.2): the file a command writes where the
  * user says must lie outside the Forge and must not exist. Both sides are compared as real paths, so neither a `..`
@@ -2788,6 +3107,7 @@ function unheldMessage(command, root, unheld) {
  * The message for a `forge unify` failure after writing began (Ruling 33): the original error, the
  * Forge-relative paths already touched, and the git commands that undo them — `checkout` for what
  * git tracks, `clean` for files unify created (checkout refuses a path git does not know).
+ * For created paths, directories get `clean -fd`, files (or missing paths) get `clean -f`.
  */
 function lateFailure(e, root, journal, command = "unify") {
     const msg = errorText(e);
@@ -2796,15 +3116,35 @@ function lateFailure(e, root, journal, command = "unify") {
     const rel = (abs) => path.relative(root, abs).split(path.sep).join("/");
     const quote = (p) => (/^[\w./-]+$/.test(p) ? p : `"${p}"`);
     const restore = [...new Set(journal.filter((j) => !j.created).map((j) => rel(j.abs)))];
-    const created = [...new Set(journal.filter((j) => j.created).map((j) => rel(j.abs)))];
+    const created = [...new Set(journal.filter((j) => j.created).map((j) => j.abs))];
+    // For created paths, check if they are directories
+    const createdDirs = [];
+    const createdFiles = [];
+    for (const abs of created) {
+        try {
+            const st = statSync(abs);
+            if (st.isDirectory()) {
+                createdDirs.push(rel(abs));
+            }
+            else {
+                createdFiles.push(rel(abs));
+            }
+        }
+        catch {
+            // Path doesn't exist, treat as file
+            createdFiles.push(rel(abs));
+        }
+    }
     const lines = [msg, `${command} had already started changing the Forge (${root}) when this failed:`];
-    for (const p of [...restore, ...created])
+    for (const p of [...restore, ...createdDirs, ...createdFiles])
         lines.push(`  ${p}`);
     lines.push("recover with:");
     if (restore.length)
         lines.push(`  git -C ${quote(root)} checkout -- ${restore.map(quote).join(" ")}`);
-    if (created.length)
-        lines.push(`  git -C ${quote(root)} clean -f -- ${created.map(quote).join(" ")}`);
+    if (createdDirs.length)
+        lines.push(`  git -C ${quote(root)} clean -fd -- ${createdDirs.map(quote).join(" ")}`);
+    if (createdFiles.length)
+        lines.push(`  git -C ${quote(root)} clean -f -- ${createdFiles.map(quote).join(" ")}`);
     return lines.join("\n");
 }
 /** ` [1 evolution · 2 block]` in the fixed class order, zero counts omitted; empty for a variant without hunks (spec 08 §4.2). */