@intentius/chant 0.124.12 → 0.124.14

package/dist/workspace/lineage-upgrade.js

@@ -0,0 +1,889 @@
+/**
+ * `chant workspace upgrade <scope>`: bring one lineage scope to a newer
+ * version of its template (#2550, D9, ws-005, ws-032).
+ *
+ * The upgrade is a core command, never an Op the template ships, so the
+ * template cannot change the rules that judge its own upgrade. It works in the
+ * six steps of D9:
+ *
+ * 1. Fetch the target version of the template. For a git source that is one
+ *    `git fetch` of the target ref, plus the commit the scope was made from.
+ *    This is the command's only network step, catalogued in
+ *    `test/egress-catalogue.ts`. A local repository reaches nothing, and
+ *    neither does a directory source (#2647), which reads `--to <dir>`.
+ * 2. Rebuild the merge base offline: each recorded file's content at the base
+ *    commit, kept only when it has the hash the lock recorded. A file the
+ *    project never edited is its own merge base. Vendor sources keep no
+ *    history, so only unedited vendored files have a base.
+ * 3. Migrate in a separate git worktree, checked out at HEAD under
+ *    `.chant/upgrade/`. The chain is planned from the template's
+ *    `.chant/migrations/`, and a gap refuses the upgrade.
+ * 4. Merge per file (ws-005): an edited file takes the new version only when
+ *    every hunk merges cleanly. Otherwise it stays as it was, with one manual
+ *    step. The worktree never holds conflict markers.
+ *    Then rebuild each CI workflow a chant member's package.json builds with
+ *    `chant build ... -o <workflow>` (#3244), with the chant doing the
+ *    upgrade, so the committed workflow follows that chant's composites.
+ * 5. Check the worktree: `chant build` and `chant lint` when the project is a
+ *    chant project, and the lineage checks of `chant workspace check`.
+ * 6. Bind the gate to the digest of the resulting patch: the pending fact and
+ *    the approval name it, so an approval covers exactly this patch.
+ *
+ * The project's own tree changes only once the gate is approved, when the
+ * patch is applied to it. A patch that changes governance files (Op files,
+ * `chant.config`, CI workflows, CODEOWNERS) needs human approvals, as many as
+ * the strictest gate in the Op files it changes asks for at HEAD. The
+ * upgraded Op files never decide their own gate.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { computePlanDigest } from "../lifecycle/plan-digest.js";
+import { checkLineage, findingKey } from "./lineage-check.js";
+import { dirLabel, git, parseDirSpec, parseTemplateSource, portableUrl, readTemplateDir, readTemplateTree, recordedDirPath } from "./lineage-init.js";
+import { LOCK_FILE, LockError, contentDigest, fileHash, readLock, renderLock, scopeKey, writeLock, } from "./lineage-lock.js";
+import { mergeFile } from "./lineage-merge.js";
+import { reportPlan, runChantMigrations } from "./chant-migrations.js";
+import { readDeclaration, readerVersion, WorkspaceReadError } from "./declaration.js";
+import { assertCodeAllowed, planMigrations, runMigration, splitMigrations } from "./lineage-migrations.js";
+import { applyUpstream } from "./lineage-update.js";
+import { pathsInsideNested } from "./nesting.js";
+import { carryParameters, readManifest, substituteParameters } from "./template-manifest.js";
+import { repinSubstituted } from "./template-pins.js";
+import { workingTree } from "./tree.js";
+import { splitCommandLine } from "./checks/generated.js";
+/** The kind the patch digest is taken under, so it never collides with another kind of plan. */
+export const UPGRADE_PLAN_KIND = "workspace-upgrade";
+/** Where staging worktrees live, relative to the project root. */
+export const UPGRADE_DIR = ".chant/upgrade";
+export class UpgradeError extends LockError {
+    constructor() {
+        super(...arguments);
+        this.name = "UpgradeError";
+    }
+}
+/**
+ * The default runner: this same chant, in a child process. The child sees the
+ * worktree's sources and resolves packages the way the project does, since the
+ * worktree sits inside the project.
+ */
+export const spawnChant = (command, cwd, args = []) => new Promise((resolvePromise, reject) => {
+    const entry = process.argv[1];
+    if (!entry) {
+        reject(new UpgradeError("cannot find the chant entry point to run build and lint in the worktree"));
+        return;
+    }
+    const child = spawn(process.execPath, [...process.execArgv, entry, command, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    const out = [];
+    child.stdout.on("data", (c) => out.push(c));
+    child.stderr.on("data", (c) => out.push(c));
+    child.on("error", reject);
+    child.on("close", (code) => resolvePromise({ exitCode: code ?? 1, output: Buffer.concat(out).toString("utf-8") }));
+});
+/** A CI workflow path a forge reads, relative to the repository root. The governance list's pipeline entries. */
+const CI_WORKFLOW = [/(^|\/)\.github\/workflows\/[^/]+\.ya?ml$/, /(^|\/)\.forgejo\/workflows\/[^/]+\.ya?ml$/, /(^|\/)\.gitea\/workflows\/[^/]+\.ya?ml$/, /(^|\/)\.gitlab-ci\.ya?ml$/];
+/**
+ * The CI workflows the chant members under `worktreeProject` build: each
+ * package.json script that is one `chant build ... -o <file>` command (no
+ * shell, no `&&`), whose output is a committed CI workflow inside the scope.
+ * The studio kit's template has `"ci:build": "chant build ci --lexicon github
+ * -o ../.github/workflows/ci.yml"` in delivery/, and its CI fails when the
+ * committed workflow differs from what ci/ci.ts builds.
+ */
+function workflowBuilds(worktree, worktreeProject, scopeRepoPath) {
+    const out = [];
+    for (const member of chantMemberDirs(worktreeProject)) {
+        const dir = member === "." ? worktreeProject : join(worktreeProject, member);
+        let scripts;
+        try {
+            scripts = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")).scripts ?? {};
+        }
+        catch {
+            continue;
+        }
+        for (const [script, line] of Object.entries(scripts)) {
+            if (typeof line !== "string")
+                continue;
+            const words = splitCommandLine(line);
+            if (!words || words[0] !== "chant" || words[1] !== "build")
+                continue;
+            const flag = words.findIndex((w) => w === "-o" || w === "--output");
+            const target = flag >= 0 ? words[flag + 1] : words.find((w) => w.startsWith("--output="))?.slice("--output=".length);
+            if (!target)
+                continue;
+            const abs = resolve(dir, target);
+            const path = relative(worktree, abs).split(sep).join("/");
+            if (path.startsWith("../") || !CI_WORKFLOW.some((re) => re.test(path)))
+                continue;
+            if (scopeRepoPath !== "." && !path.startsWith(`${scopeRepoPath}/`))
+                continue;
+            if (!existsSync(abs))
+                continue;
+            out.push({ member, script, command: line, args: words.slice(2), abs, path });
+        }
+    }
+    return out;
+}
+/**
+ * Rebuild the CI workflows {@link workflowBuilds} finds (#3244), each in its
+ * member's directory of the staging worktree with that member's node_modules
+ * linked in from the project. A workflow is built from the member's sources
+ * through the lexicon's composites, so upgrading chant can change it with no
+ * change to the sources (#2621 moved Checkout and SetupNode from v4 to v7),
+ * and a committed copy then fails the project's own ci:check. Rebuilding it
+ * here puts the new workflow in the patch the gate approves. The links are
+ * removed before the patch is taken. A build that fails leaves the file as
+ * the merge left it.
+ */
+async function rebuildWorkflows(root, worktree, worktreeProject, scopeRepoPath, run) {
+    const builds = workflowBuilds(worktree, worktreeProject, scopeRepoPath);
+    if (builds.length === 0)
+        return [];
+    const linked = [];
+    const results = [];
+    try {
+        for (const member of new Set(builds.map((b) => b.member))) {
+            if (member === ".")
+                continue;
+            const from = join(root, member, "node_modules");
+            const to = join(worktreeProject, member, "node_modules");
+            if (existsSync(from) && !existsSync(to) && existsSync(dirname(to))) {
+                symlinkSync(from, to, "dir");
+                linked.push(to);
+            }
+        }
+        for (const b of builds) {
+            const before = readFileSync(b.abs);
+            const r = await run("build", b.member === "." ? worktreeProject : join(worktreeProject, b.member), b.args);
+            const base = { member: b.member, script: b.script, path: b.path, command: b.command };
+            if (r.exitCode !== 0) {
+                writeFileSync(b.abs, before);
+                results.push({ ...base, status: "failed", detail: tail(r.output) });
+                continue;
+            }
+            const after = existsSync(b.abs) ? readFileSync(b.abs) : null;
+            if (after === null) {
+                writeFileSync(b.abs, before);
+                results.push({ ...base, status: "failed", detail: `\`${b.command}\` exited 0 and wrote no ${b.path}` });
+                continue;
+            }
+            results.push({ ...base, status: after.equals(before) ? "unchanged" : "rebuilt" });
+        }
+    }
+    finally {
+        for (const l of linked) {
+            try {
+                if (lstatSync(l).isSymbolicLink())
+                    unlinkSync(l);
+            }
+            catch {
+                // Already gone.
+            }
+        }
+    }
+    return results;
+}
+/**
+ * The template's files as the project would have them (#2627): the manifest
+ * removed and the parameters substituted, with the recorded values and the
+ * defaults of parameters this version adds. Records that pin a substituted
+ * file are re-pinned as init re-pinned them (#2549), for the base and the
+ * target alike, so an unedited record compares equal to its base.
+ */
+function instantiate(raw, recorded, label) {
+    try {
+        const manifest = readManifest(raw);
+        const parameters = carryParameters(manifest, recorded);
+        const { files, repinned } = repinSubstituted(raw, substituteParameters(raw, manifest, parameters), manifest?.files ?? []);
+        return { files, parameters, repinned };
+    }
+    catch (err) {
+        throw new UpgradeError(`${label}: ${err.message.replace(/; pass --param .*$/, "")}`);
+    }
+}
+/**
+ * Fetch the target ref, and the commit the scope was made from, of a git
+ * source into a scratch repository, and read both trees. The base fetch may
+ * fail (a server that refuses fetches by commit); the base is then left empty,
+ * and every edited file the template changed becomes a manual step.
+ */
+function fetchGit(root, lineage, ref, onto) {
+    const source = lineage.source;
+    if (source.type !== "git")
+        throw new UpgradeError("not a git source");
+    const baseUrl = source.url.startsWith(".") ? resolve(root, source.url) : source.url;
+    // With --source (#2551) the target comes from the other template; the base always from the scope's own.
+    const url = onto ? onto.url : baseUrl;
+    const label = `${onto ? onto.repo : source.repo}@${ref}`;
+    const scratch = mkdtempSync(join(tmpdir(), "chant-upgrade-"));
+    try {
+        git(scratch, ["init", "-q"]);
+        try {
+            // The network step of `chant workspace upgrade`, catalogued in test/egress-catalogue.ts.
+            git(scratch, ["fetch", "-q", "--depth", "1", url, ref]);
+        }
+        catch (err) {
+            const stderr = err.stderr?.toString().trim();
+            throw new UpgradeError(`could not fetch ${label}${stderr ? `: ${stderr}` : ""}`);
+        }
+        const commit = git(scratch, ["rev-parse", "FETCH_HEAD^{commit}"]);
+        const target = readTemplateTree(scratch, commit, onto ? onto.path : source.path, label);
+        const raw = new Map();
+        const executable = new Set();
+        for (const [path, f] of target.files) {
+            raw.set(path, f.data);
+            if (f.executable)
+                executable.add(path);
+        }
+        // The target with the scope's parameters substituted (#2627), so an
+        // unedited file that carries a value compares equal to its base.
+        const instantiated = instantiate(raw, lineage.parameters, label);
+        let base = new Map();
+        const baseCommit = lineage.address?.commit;
+        if (baseCommit && baseCommit !== commit) {
+            try {
+                git(scratch, ["fetch", "-q", "--depth", "1", baseUrl, baseCommit]);
+                const oldLabel = `${source.repo}@${baseCommit.slice(0, 12)}`;
+                const old = readTemplateTree(scratch, baseCommit, source.path, oldLabel);
+                // The base is rebuilt the way init wrote it: the old version's
+                // manifest, with the values the lock recorded.
+                base = instantiate(new Map([...old.files].map(([path, f]) => [path, f.data])), lineage.parameters, oldLabel).files;
+            }
+            catch {
+                // No base from the source; the tree still supplies it for unedited files.
+            }
+        }
+        else if (baseCommit) {
+            base = new Map(instantiated.files);
+        }
+        const split = splitMigrations(instantiated.files);
+        return {
+            files: split.files,
+            executable,
+            base,
+            migrations: split.migrations,
+            modules: split.modules,
+            commit,
+            tree: target.tree,
+            parameters: instantiated.parameters,
+            repinned: instantiated.repinned,
+        };
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/**
+ * Why a directory scope cannot be upgraded, with the way out. A directory
+ * has no history, so the merge base exists only while the files the scope
+ * was made from are still on disk.
+ */
+function dirRefusal(lineage, why) {
+    const source = lineage.source;
+    return new UpgradeError(`${why}. The scope was made from the directory ${dirLabel(source.path, source.member)}, which has no git history to rebuild a merge base from. ` +
+        `Upgrade with --to <dir> while ${source.path} still holds the files the scope was made from, or move the scope onto the git repository the directory was copied from with \`chant workspace adopt-lineage --from <repo>[#<member>]\`.`);
+}
+/**
+ * The upstream of a directory source (#2647): the new version from the
+ * directory `to` names, and the merge base from the recorded directory, used
+ * only when its files, instantiated with the recorded parameters, still have
+ * the recorded digest. Anything else is refused: a base that is not the one
+ * the scope was made from would turn the project's edits into upstream
+ * changes. Reaches no network.
+ */
+function readDir(root, lineage, to) {
+    const source = lineage.source;
+    if (source.type !== "dir")
+        throw new UpgradeError("not a directory source");
+    if (!to)
+        throw dirRefusal(lineage, "no --to directory");
+    let target;
+    try {
+        target = parseDirSpec(to);
+    }
+    catch {
+        target = null;
+    }
+    if (!target)
+        throw new UpgradeError(`--to ${to}: a scope made from a directory upgrades from a directory, and ${to} is not one`);
+    const member = to.includes("#") ? target.member : source.member;
+    const label = dirLabel(target.path, member);
+    const read = readTemplateDir(target.abs, member, label);
+    const raw = new Map();
+    const executable = new Set();
+    for (const [path, f] of read.files) {
+        raw.set(path, f.data);
+        if (f.executable)
+            executable.add(path);
+    }
+    const instantiated = instantiate(raw, lineage.parameters, label);
+    // The merge base: the recorded directory, only while it holds exactly what the scope was made from.
+    const original = resolve(root, source.path);
+    const originalLabel = dirLabel(source.path, source.member);
+    let base;
+    try {
+        const old = readTemplateDir(original, source.member, originalLabel);
+        base = splitMigrations(instantiate(new Map([...old.files].map(([path, f]) => [path, f.data])), lineage.parameters, originalLabel).files).files;
+    }
+    catch {
+        throw dirRefusal(lineage, `${originalLabel} is gone`);
+    }
+    if (!lineage.address || contentDigest(base) !== lineage.address.digest) {
+        throw dirRefusal(lineage, `${originalLabel} no longer holds the files the scope was made from (its digest is not ${lineage.address?.digest ?? "recorded"})`);
+    }
+    const split = splitMigrations(instantiated.files);
+    return {
+        files: split.files,
+        executable,
+        base,
+        migrations: split.migrations,
+        modules: split.modules,
+        parameters: instantiated.parameters,
+        repinned: instantiated.repinned,
+        source: { type: "dir", path: recordedDirPath(target.path, target.abs, root), ...(member ? { member } : {}) },
+    };
+}
+async function fetchUpstream(root, lineage, ref, onto) {
+    const source = lineage.source;
+    if (source.type === "git") {
+        if (!ref)
+            throw new UpgradeError("the scope records no ref; pass --to <ref>");
+        return fetchGit(root, lineage, ref, onto);
+    }
+    if (source.type === "local" || source.type === "archive") {
+        const { resolveVendorSource } = await import("../cli/commands/vendor.js");
+        const files = await resolveVendorSource(source, root);
+        return { files, executable: new Set(), base: new Map(), migrations: [], modules: new Map() };
+    }
+    if (source.type === "dir")
+        return readDir(root, lineage, ref);
+    throw new UpgradeError(`scope made by \`chant init --template\` (${lineage.template}) is refused: it came from a lexicon's built-in template, which has no versioned source to fetch, and the merge base would be the render of the chant version that wrote it, which chant cannot rebuild offline. Scopes made by \`chant init --from\` (a git repository or a directory) and \`chant vendor\` scopes upgrade.`);
+}
+/** The merge base per recorded file: from the source's old version, or from an unedited file in the tree. */
+function rebuildBase(scopeDir, lineage, fromSource) {
+    const base = new Map();
+    for (const [path, entry] of Object.entries(lineage.files)) {
+        const old = fromSource.get(path);
+        if (old && fileHash(old) === entry.sha256) {
+            base.set(path, old);
+            continue;
+        }
+        const abs = join(scopeDir, path);
+        if (existsSync(abs)) {
+            const data = readFileSync(abs);
+            if (fileHash(data) === entry.sha256)
+                base.set(path, data);
+        }
+    }
+    return base;
+}
+// ── Governance ───────────────────────────────────────────────────────────────
+const GOVERNANCE = [
+    /(^|\/)[^/]+\.op\.[cm]?[jt]s$/,
+    /(^|\/)chant\.config\.(ts|js|mjs|cjs|json)$/,
+    /(^|\/)chant\.workspace\.jsonc?$/,
+    /(^|\/)\.github\/workflows\//,
+    /(^|\/)\.forgejo\/workflows\//,
+    /(^|\/)\.gitea\/workflows\//,
+    /(^|\/)\.gitlab-ci\.ya?ml$/,
+    /(^|\/)CODEOWNERS$/,
+];
+/** Whether a repository path is a governance file: one that decides gates, pipelines or review. */
+export function isGovernancePath(path) {
+    return GOVERNANCE.some((re) => re.test(path));
+}
+/**
+ * The approval an upgrade gate asks for when the patch changes governance
+ * files. Only human approvals count, and the gate needs as many as the
+ * strictest gate declared at HEAD in any Op file the patch changes, at least
+ * one. The Op files are read from the project's tree, which the upgrade
+ * requires to match HEAD for every path the patch touches.
+ */
+async function rulesAtHead(root, repo, paths) {
+    const opFiles = new Set(paths.filter((p) => GOVERNANCE[0].test(p)));
+    let count = 1;
+    let roles;
+    if (opFiles.size > 0) {
+        const { discoverOps } = await import("../op/discover.js");
+        const { ops } = await discoverOps({ cwd: root });
+        for (const { config, filePath } of ops.values()) {
+            const rel = relative(repo, filePath).split(sep).join("/");
+            if (!opFiles.has(rel))
+                continue;
+            for (const approval of gateApprovals(config)) {
+                const need = approval.quorum?.count ?? 1;
+                if (need > count) {
+                    count = need;
+                    roles = approval.quorum?.roles;
+                }
+            }
+        }
+    }
+    return { mode: "log-only", quorum: { count, ...(roles && roles.length > 0 ? { roles } : {}) } };
+}
+function gateApprovals(config) {
+    const out = [];
+    const visit = (step) => {
+        if (step.kind === "gate")
+            out.push(step.approval ?? {});
+        if (step.kind === "effect")
+            (step.steps ?? []).forEach(visit);
+    };
+    for (const p of [...(config.phases ?? []), ...(config.onFailure ?? [])])
+        p.steps.forEach(visit);
+    return out;
+}
+// ── Stage ────────────────────────────────────────────────────────────────────
+function gitOut(cwd, args) {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+}
+function isChantProject(dir) {
+    return ["chant.config.ts", "chant.config.json", "chant.config.js", "chant.config.mjs"].some((f) => existsSync(join(dir, f)));
+}
+function tail(text, lines = 30) {
+    return text.trimEnd().split("\n").slice(-lines).join("\n");
+}
+/**
+ * The `chant` members `chant.workspace.json` declares in `dir` (#2804): a
+ * template built as a workspace, such as the studio kit's, keeps its chant
+ * project in a member (`delivery`), not at the scope's root, and the root
+ * itself never has a `chant.config`. Empty when `dir` declares no workspace,
+ * or the declaration cannot be read: the caller then falls back to `dir`
+ * itself.
+ */
+function chantMemberDirs(dir) {
+    try {
+        return readDeclaration(workingTree(dir))
+            .members.filter((m) => m.kind === "chant")
+            .map((m) => m.dir);
+    }
+    catch (err) {
+        if (err instanceof WorkspaceReadError)
+            return [];
+        throw err;
+    }
+}
+/**
+ * Resolve the scope argument against `root` (#2550). A scope the lock at
+ * `root` holds is used as it is. Otherwise a member the workspace
+ * declaration names (by name or directory) that keeps a lock of its own is
+ * upgraded from its directory, as the project it is, so its patch, gate and
+ * build stay inside it. A member without a lock was not made from a template.
+ */
+export function resolveUpgradeTarget(root, scopeArg) {
+    const scope = scopeKey(scopeArg ?? ".");
+    const lock = readLock(root);
+    if (lock?.scopes[scope])
+        return { root, scope };
+    if (scope !== ".") {
+        let declared = [];
+        try {
+            declared = readDeclaration(workingTree(root)).members;
+        }
+        catch (err) {
+            if (!(err instanceof WorkspaceReadError))
+                throw err;
+        }
+        const hit = declared.find((m) => m.dir !== "." && (m.name === scopeArg || scopeKey(m.dir) === scope));
+        if (hit?.kind === "workspace") {
+            // A nested workspace upgrades itself; the outer one never writes inside it (D2, #2551).
+            throw new UpgradeError(`member "${hit.name}" is a nested workspace, which upgrades itself: run chant workspace upgrade in ${hit.dir}`);
+        }
+        if (hit) {
+            const memberRoot = join(root, hit.dir);
+            if (readLock(memberRoot))
+                return { root: memberRoot, scope: ".", member: hit.name };
+            throw new UpgradeError(`member "${hit.name}" (${hit.dir}) has no ${LOCK_FILE}, so it was not made from a template and has nothing to upgrade. \`chant init --from <template> ${hit.dir}\` writes one; \`chant workspace adopt-lineage\` is for an older member.`);
+        }
+    }
+    return { root, scope };
+}
+/**
+ * Stage an upgrade: steps 1 to 5 and the digest of step 6. Nothing in the
+ * project's tree changes. The caller decides the gate, then applies the patch
+ * with {@link applyStagedUpgrade} or commits it with {@link commitStagedUpgrade},
+ * and always calls `dispose()`.
+ */
+export async function stageUpgrade(options) {
+    const { root, scope, member } = resolveUpgradeTarget(resolve(options.root), options.scope);
+    const lock = readLock(root);
+    if (!lock)
+        throw new UpgradeError(`no ${LOCK_FILE} in ${root}`);
+    const lineage = lock.scopes[scope];
+    if (!lineage) {
+        throw new UpgradeError(`${LOCK_FILE} has no scope "${scope}" (scopes: ${Object.keys(lock.scopes).join(", ") || "none"})`);
+    }
+    if (lineage.manualSteps.length > 0) {
+        throw new UpgradeError(`scope "${scope}" has ${lineage.manualSteps.length} open manual step(s) from its last update (${lineage.manualSteps.map((s) => s.path).join(", ")}). Merge them and run \`chant workspace lineage resolve <path>\` first.`);
+    }
+    let repo;
+    let head;
+    try {
+        repo = gitOut(root, ["rev-parse", "--show-toplevel"]).trim();
+        head = gitOut(root, ["rev-parse", "HEAD"]).trim();
+    }
+    catch {
+        throw new UpgradeError("chant workspace upgrade stages its change in a git worktree, so the project must be in a git repository with at least one commit");
+    }
+    const projectRel = relative(repo, root).split(sep).join("/");
+    const scopeRepoPath = [projectRel, scope === "." ? "" : scope].filter(Boolean).join("/") || ".";
+    const lockRepoPath = [projectRel, LOCK_FILE].filter(Boolean).join("/");
+    let lockTracked = true;
+    try {
+        gitOut(repo, ["ls-files", "--error-unmatch", "--", lockRepoPath]);
+    }
+    catch {
+        lockTracked = false;
+    }
+    const dirty = gitOut(repo, ["status", "--porcelain", "--untracked-files=all", "--", scopeRepoPath, lockRepoPath])
+        .split("\n")
+        .filter(Boolean)
+        .filter((line) => !line.slice(3).startsWith(`${[projectRel, UPGRADE_DIR].filter(Boolean).join("/")}/`));
+    if (dirty.length > 0) {
+        throw new UpgradeError(`the scope has uncommitted changes (${dirty.slice(0, 5).map((l) => l.slice(3)).join(", ")}${dirty.length > 5 ? ", …" : ""}). Commit or stash them: the upgrade stages from HEAD and applies its patch to the tree.`);
+    }
+    // A move to another template (#2551): a git scope only, and to a named ref.
+    let onto;
+    if (options.source !== undefined) {
+        const spec = parseTemplateSource(options.source, root, "--source");
+        if (spec.ref !== undefined)
+            throw new UpgradeError(`--source ${options.source}: name the version with --to, not "@${spec.ref}"`);
+        if (options.to === undefined)
+            throw new UpgradeError("--source moves the scope to another template, so it needs --to <ref>: a version of that template");
+        if (lineage.source.type !== "git") {
+            throw new UpgradeError(`scope "${scope}" has a ${lineage.source.type} source; only a git scope moves to another template. A directory scope moves onto git with chant workspace adopt-lineage first.`);
+        }
+        onto = { url: spec.url, repo: spec.repo, ...(spec.member ? { path: spec.member } : {}), id: spec.id };
+    }
+    const switching = onto !== undefined && onto.id !== lineage.template;
+    // 1. Fetch. A directory source has no ref: `--to` names the directory.
+    const fromDir = lineage.source.type === "dir";
+    const ref = fromDir ? undefined : options.to ?? lineage.ref;
+    const upstream = await fetchUpstream(root, lineage, fromDir ? options.to : ref, onto);
+    // 2. The merge base, offline from here on.
+    const base = rebuildBase(join(root, scope), lineage, upstream.base);
+    // Plan the chain before anything is staged, so a gap refuses early.
+    const plan = lineage.kind === "template" ? planMigrations(lineage, ref, upstream.migrations, onto?.id) : { chain: [] };
+    assertCodeAllowed(plan.chain, !!options.allowCode);
+    // 3. The worktree, inside the project so the project's packages resolve.
+    const holder = join(root, UPGRADE_DIR);
+    mkdirSync(holder, { recursive: true });
+    const worktree = mkdtempSync(join(holder, `${scope === "." ? "root" : basename(scope)}-`));
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        try {
+            gitOut(repo, ["worktree", "remove", "--force", worktree]);
+        }
+        catch {
+            // Fall through to the directory removal and a prune.
+        }
+        rmSync(worktree, { recursive: true, force: true });
+        try {
+            gitOut(repo, ["worktree", "prune"]);
+        }
+        catch {
+            // Nothing to prune.
+        }
+        if (existsSync(holder) && readdirSync(holder).length === 0)
+            rmSync(holder, { recursive: true, force: true });
+    };
+    try {
+        gitOut(repo, ["worktree", "add", "-q", "--detach", worktree, head]);
+        const worktreeProject = projectRel ? join(worktree, projectRel) : worktree;
+        const scopeDir = join(worktreeProject, scope);
+        const next = structuredClone(lock);
+        const staged = next.scopes[scope];
+        const scratch = mkdtempSync(join(tmpdir(), "chant-upgrade-code-"));
+        try {
+            for (const m of plan.chain) {
+                await runMigration(m, {
+                    dir: scopeDir,
+                    lineage: staged,
+                    modules: upstream.modules,
+                    allowCode: !!options.allowCode,
+                    scratch,
+                    onMove: (from, to) => {
+                        const data = base.get(from);
+                        base.delete(from);
+                        if (data)
+                            base.set(to, data);
+                    },
+                });
+            }
+        }
+        finally {
+            rmSync(scratch, { recursive: true, force: true });
+        }
+        // chant's own migrations (#2737): planned from what the scope holds, and
+        // applied only when the plan has no conflict. A conflict fails the checks.
+        // Each is planned from the tree the ones before it left.
+        const chantRuns = lineage.kind === "template" ? runChantMigrations({ dir: scopeDir, lineage: staged, chantVersion: readerVersion() }) : [];
+        const chantMigrations = chantRuns.map((r) => reportPlan(r.plan, r.applied));
+        // 4. Merge per file.
+        const result = applyUpstream(scopeDir, staged, upstream.files, { base, merge: mergeFile });
+        for (const path of result.written)
+            if (upstream.executable.has(path))
+                chmodSync(join(scopeDir, path), 0o755);
+        if (ref !== undefined)
+            staged.ref = ref;
+        if (upstream.parameters)
+            staged.parameters = upstream.parameters;
+        if (upstream.repinned) {
+            // The records this version re-pins, among the files the scope keeps (#2549).
+            const kept = upstream.repinned.filter((r) => staged.files[r.record] !== undefined || existsSync(join(scopeDir, r.record)));
+            if (kept.length > 0)
+                staged.repinned = kept;
+            else
+                delete staged.repinned;
+        }
+        if (upstream.commit)
+            staged.address = { ...staged.address, commit: upstream.commit, tree: upstream.tree };
+        if (upstream.source)
+            staged.source = upstream.source;
+        if (onto) {
+            staged.template = onto.id;
+            staged.source = { type: "git", repo: onto.repo, url: portableUrl(onto.url, root), ...(onto.path ? { path: onto.path } : {}) };
+        }
+        writeLock(worktreeProject, next);
+        const lockText = renderLock(next);
+        // The CI workflows a chant member builds, rebuilt with this chant (#3244),
+        // before the patch is taken so the gate approves them with the rest.
+        const workflows = lineage.kind === "template" ? await rebuildWorkflows(root, worktree, worktreeProject, scopeRepoPath, options.runChant ?? spawnChant) : [];
+        // The patch, taken before anything else runs in the worktree.
+        gitOut(worktree, ["add", "-A"]);
+        if (!lockTracked)
+            gitOut(worktree, ["rm", "--cached", "-q", "--ignore-unmatch", "--", lockRepoPath]);
+        const patch = gitOut(worktree, ["diff", "--cached", "--binary", "--full-index", "--no-color", "--no-ext-diff", head]);
+        const changedPaths = gitOut(worktree, ["diff", "--cached", "--name-only", "-z", head]).split("\0").filter(Boolean).sort();
+        // An upgrade writes inside its scope and the lock that records it, and nowhere else.
+        const outside = changedPaths.filter((p) => scopeRepoPath !== "." && p !== lockRepoPath && p !== scopeRepoPath && !p.startsWith(`${scopeRepoPath}/`));
+        if (outside.length > 0) {
+            throw new UpgradeError(`the upgrade would change ${outside.slice(0, 5).join(", ")}${outside.length > 5 ? ", ..." : ""}, outside the scope "${scopeRepoPath}". An upgrade writes only inside its own scope.`);
+        }
+        const lockChanged = !lockTracked && lockText !== readFileSync(join(root, LOCK_FILE), "utf-8");
+        const changed = patch.length > 0 || lockChanged;
+        const digest = computePlanDigest(UPGRADE_PLAN_KIND, lockTracked ? { scope, patch } : { scope, patch, lock: lockText });
+        // The outer workspace never writes inside a nested one (D2, #2551): that one upgrades itself.
+        const inNested = pathsInsideNested(worktreeProject, projectRel, changedPaths);
+        if (inNested.length > 0) {
+            throw new UpgradeError(`the upgrade would change files inside the nested workspace ${inNested[0].member} (${inNested.slice(0, 5).map((p) => p.path).join(", ")}). A nested workspace upgrades itself with its own chant workspace upgrade, and the outer one never writes inside it.`);
+        }
+        // Governance: decided by the rules at HEAD, never by the upgraded files.
+        const governed = changedPaths.filter(isGovernancePath);
+        let governance = null;
+        if (governed.length > 0) {
+            const existing = governed.filter((p) => existsSync(join(repo, p)));
+            const touched = existing.length === 0 ? [] : gitOut(repo, ["status", "--porcelain", "--", ...existing]).split("\n").filter(Boolean);
+            if (touched.length > 0) {
+                throw new UpgradeError(`the upgrade changes governance files that have uncommitted edits (${touched.map((l) => l.slice(3)).join(", ")}). Commit them first: their gates are read at HEAD.`);
+            }
+            governance = { paths: governed, approval: await rulesAtHead(root, repo, governed), rules: head };
+        }
+        // 5. Checks.
+        const checks = [];
+        for (const w of workflows.filter((w) => w.status === "failed")) {
+            checks.push({
+                name: "build",
+                status: "failed",
+                member: w.member,
+                detail: `${w.path} could not be rebuilt with \`${w.command}\` (the ${w.script} script), so it may differ from what this chant builds:\n${w.detail ?? ""}`,
+            });
+        }
+        for (const m of chantMigrations.filter((m) => !m.applied)) {
+            checks.push({
+                name: "migration",
+                status: "failed",
+                detail: `${m.id} was not applied: ${m.conflicts.map((c) => `${c.path}: ${c.reason}`).join("\n")}`,
+            });
+        }
+        if (changed) {
+            // Every `chant` member chant.workspace.json declares, so a template
+            // whose chant project sits in a member (the studio kit's `delivery/`)
+            // is built and linted there, not skipped for having no chant.config at
+            // the scope's root (#2804). A scope with no workspace declaration falls
+            // back to the root, as before.
+            const members = chantMemberDirs(worktreeProject);
+            const targets = members.length > 0 ? members : isChantProject(worktreeProject) ? ["."] : [];
+            if (targets.length > 0) {
+                const run = options.runChant ?? spawnChant;
+                const namedMember = targets.length > 1 || targets[0] !== ".";
+                // A member that installs its packages in its own directory resolves them from its node_modules, which is not
+                // an ancestor of the staging worktree: link it in from the project (#2847). The patch and its digest are
+                // computed above, so the links never reach them, and dispose() removes them with the worktree.
+                for (const member of targets) {
+                    if (member === ".")
+                        continue;
+                    const from = join(root, member, "node_modules");
+                    const to = join(worktreeProject, member, "node_modules");
+                    if (existsSync(from) && !existsSync(to) && existsSync(dirname(to)))
+                        symlinkSync(from, to, "dir");
+                }
+                for (const member of targets) {
+                    const dir = member === "." ? worktreeProject : join(worktreeProject, member);
+                    const at = namedMember ? { member } : {};
+                    for (const command of ["build", "lint"]) {
+                        const r = await run(command, dir);
+                        checks.push(r.exitCode === 0 ? { name: command, status: "passed", ...at } : { name: command, status: "failed", detail: tail(r.output), ...at });
+                    }
+                }
+            }
+            else {
+                for (const name of ["build", "lint"])
+                    checks.push({ name, status: "skipped", detail: "not a chant project (no chant.config)" });
+            }
+            checks.push(lineageCheck(root, worktreeProject, result.manualSteps, scope));
+        }
+        return {
+            scope,
+            ...(member !== undefined ? { member } : {}),
+            gate: member ?? scope,
+            template: lineage.template,
+            ...(switching ? { switchedTo: onto.id } : {}),
+            kind: lineage.kind,
+            from: fromDir ? sourcePin(lineage.source) : lineage.ref ?? null,
+            to: fromDir ? sourcePin(staged.source) : staged.ref ?? null,
+            ...(upstream.commit ? { commit: { ...(lineage.address?.commit ? { from: lineage.address.commit } : {}), to: upstream.commit } } : {}),
+            migrations: [...plan.chain.map((m) => m.migration.id), ...chantMigrations.filter((m) => m.applied).map((m) => m.id)],
+            chantMigrations,
+            workflows,
+            written: result.written,
+            merged: result.merged,
+            removed: result.removed,
+            kept: result.kept,
+            skipped: result.skipped,
+            manualSteps: result.manualSteps,
+            changedPaths,
+            patch,
+            lock: { path: lockRepoPath, tracked: lockTracked, text: lockText },
+            changed,
+            digest,
+            governance,
+            checks,
+            checksOk: checks.every((c) => c.status !== "failed"),
+            repo,
+            head,
+            worktree,
+            worktreeProject,
+            dispose,
+        };
+    }
+    catch (err) {
+        dispose();
+        throw err;
+    }
+}
+/** A directory source's pin, for the summary: the directory it reads. */
+function sourcePin(source) {
+    return source.type === "dir" ? dirLabel(source.path, source.member) : null;
+}
+/**
+ * `chant workspace check` in the worktree. A finding already present at HEAD
+ * is not the upgrade's doing, and the upgrade's own manual steps are what the
+ * gate approves; any other finding fails the check.
+ */
+function lineageCheck(root, worktreeProject, ownSteps, scope) {
+    const before = new Set(checkLineage(root).findings.map(findingKey));
+    const own = new Set(ownSteps.map((s) => (scope === "." ? s.path : `${scope}/${s.path}`)));
+    const report = checkLineage(worktreeProject);
+    const fresh = report.findings.filter((f) => !before.has(findingKey(f)) && !(f.code === "manual-step-open" && f.path !== undefined && own.has(f.path)));
+    if (fresh.length === 0)
+        return { name: "workspace check", status: "passed" };
+    return { name: "workspace check", status: "failed", detail: fresh.map((f) => `${f.path ?? f.scope ?? ""}: ${f.message}`).join("\n") };
+}
+// ── Apply or propose ─────────────────────────────────────────────────────────
+/** Apply the staged patch to the project's tree. Leaves it uncommitted. */
+export function applyStagedUpgrade(staged) {
+    if (!staged.lock.tracked)
+        writeFileSync(join(staged.repo, staged.lock.path), staged.lock.text);
+    if (!staged.patch)
+        return;
+    const file = join(mkdtempSync(join(tmpdir(), "chant-upgrade-patch-")), "upgrade.patch");
+    try {
+        writeFileSync(file, staged.patch);
+        execFileSync("git", ["apply", "--binary", "--whitespace=nowarn", file], { cwd: staged.repo, stdio: ["ignore", "pipe", "pipe"] });
+    }
+    catch (err) {
+        const stderr = err.stderr?.toString().trim();
+        throw new UpgradeError(`the approved patch no longer applies to the tree${stderr ? `: ${stderr}` : ""}`);
+    }
+    finally {
+        rmSync(join(file, ".."), { recursive: true, force: true });
+    }
+}
+/**
+ * Commit the staged patch in the worktree and point `branch` at it. Returns
+ * the commit. The caller has already refused the default branch.
+ */
+export function commitStagedUpgrade(staged, branch, message) {
+    const identity = [];
+    const has = (key) => {
+        try {
+            return gitOut(staged.worktree, ["config", key]).trim().length > 0;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!has("user.name"))
+        identity.push("-c", "user.name=chant");
+    if (!has("user.email"))
+        identity.push("-c", "user.email=chant@localhost");
+    // An ignored lock is still part of the proposal: the branch starts tracking it.
+    if (!staged.lock.tracked)
+        gitOut(staged.worktree, ["add", "-f", "--", staged.lock.path]);
+    gitOut(staged.worktree, [...identity, "commit", "-q", "--no-verify", "-m", message]);
+    const commit = gitOut(staged.worktree, ["rev-parse", "HEAD"]).trim();
+    gitOut(staged.repo, ["branch", "-f", branch, commit]);
+    return commit;
+}
+/** One line per staged change, for the terminal and for a PR body. */
+export function describeStaged(staged) {
+    const lines = [];
+    const at = (p) => (staged.scope === "." ? p : `${staged.scope}/${p}`);
+    lines.push(`${staged.gate}  ${staged.template}  ${staged.from ?? "(no ref)"} -> ${staged.to ?? "(no ref)"}`);
+    if (staged.switchedTo)
+        lines.push(`  template: ${staged.template} -> ${staged.switchedTo}`);
+    const chantIds = new Set(staged.chantMigrations.map((m) => m.id));
+    for (const id of staged.migrations)
+        if (!chantIds.has(id))
+            lines.push(`  migration: ${id}`);
+    for (const m of staged.chantMigrations) {
+        lines.push(`  chant migration: ${m.id} (${m.applied ? "applied" : "not applied: it has conflicts"}), to ${m.description}`);
+        for (const c of m.changes)
+            lines.push(`    ${c.action === "delete" ? "delete" : "write"}: ${at(c.path)} (${c.why}${c.edited ? "; it was edited since the template, and the edit stays in git history" : ""})`);
+        for (const n of m.notMoved)
+            lines.push(`    not moved: ${n.what} -> ${n.where}`);
+        for (const c of m.conflicts)
+            lines.push(`    conflict: ${at(c.path)}: ${c.reason}`);
+    }
+    for (const w of staged.workflows) {
+        if (w.status !== "unchanged")
+            lines.push(`  workflow ${w.status === "rebuilt" ? "rebuilt" : "not rebuilt"}: ${w.path} (${w.script}: ${w.command})`);
+    }
+    for (const p of staged.written)
+        lines.push(`  updated: ${at(p)}`);
+    for (const p of staged.merged)
+        lines.push(`  merged: ${at(p)}`);
+    for (const p of staged.removed)
+        lines.push(`  removed: ${at(p)}`);
+    for (const s of staged.skipped) {
+        if (s.class === "generated")
+            lines.push(`  generated, not merged: ${at(s.path)}${s.command ? ` (rebuild with ${s.command})` : ""}`);
+    }
+    for (const s of staged.manualSteps)
+        lines.push(`  manual step: ${at(s.path)} (${s.reason})`);
+    if (staged.governance) {
+        const q = staged.governance.approval.quorum;
+        lines.push(`  governance: ${staged.governance.paths.join(", ")}; needs ${q.count} human approval(s)${q.roles ? ` with a role in ${q.roles.join(", ")}` : ""}, from the rules at ${staged.governance.rules.slice(0, 12)}`);
+    }
+    for (const c of staged.checks) {
+        const label = c.member !== undefined ? `${c.name} (${c.member})` : c.name;
+        lines.push(`  ${label}: ${c.status}${c.status === "skipped" && c.detail ? ` (${c.detail})` : ""}`);
+    }
+    lines.push(`  patch: ${staged.changedPaths.length} file(s)${staged.lock.tracked ? "" : ` and the untracked ${LOCK_FILE}`}, ${staged.digest}`);
+    return lines;
+}