@intentius/chant 0.124.12 → 0.124.14

package/dist/workspace/lineage-migrations.js

@@ -0,0 +1,329 @@
+/**
+ * Template migrations (#2550, D9).
+ *
+ * A template ships its migrations beside its files, under
+ * `.chant/migrations/`, one JSON file each. The metadata is data: an id, the
+ * template versions it applies `from` (a template id and a version range), the
+ * version it brings the scope `to`, a body, and a post-condition. The body is
+ * either a closed list of declarative steps or a module, marked
+ * `"type": "code"`, which runs only when the caller allows code.
+ *
+ * `chant workspace upgrade` plans a chain from the scope's version to the
+ * target: every migration whose `to` lies in between, ordered by `to`. Each
+ * must accept the version the scope has reached when its turn comes. When one
+ * does not, a migration is missing from the chain, and the upgrade is refused
+ * rather than applied in part.
+ *
+ * Migrations run inside the upgrade's staging worktree, before the per-file
+ * merge. A `move` or `delete` updates the lineage too, so the merge that
+ * follows compares the right merge base with the new version.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, posix } from "node:path";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+import { LockError } from "./lineage-lock.js";
+import { compareVersions, formatVersion, parseVersion, satisfies, validateRange, VersionRangeError } from "./lineage-version.js";
+import { ensureTypeScriptLoader } from "../ts-loader.js";
+/** Where a template keeps its migrations, relative to the template's directory. */
+export const MIGRATIONS_DIR = ".chant/migrations";
+const RelPath = z
+    .string()
+    .min(1)
+    .refine((p) => {
+    const n = posix.normalize(p);
+    return !n.startsWith("/") && n !== ".." && !n.startsWith("../") && !p.includes("\\");
+}, "must be a relative path inside the scope");
+/** The declarative steps. Closed: a step chant does not know is refused. */
+const StepSchema = z.discriminatedUnion("op", [
+    /** Move a file. The lineage entry moves with it, merge base included. */
+    z.strictObject({ op: z.literal("move"), from: RelPath, to: RelPath }),
+    /** Delete a file and drop it from the lineage. */
+    z.strictObject({ op: z.literal("delete"), path: RelPath }),
+    /** Replace every occurrence of a literal string in a file. */
+    z.strictObject({ op: z.literal("replace"), path: RelPath, find: z.string().min(1), with: z.string() }),
+    /** Set a value in a JSON file at a JSON Pointer, creating objects on the way. */
+    z.strictObject({ op: z.literal("json-set"), path: RelPath, pointer: z.string().startsWith("/"), value: z.unknown() }),
+    /** Remove a key from a JSON file at a JSON Pointer. */
+    z.strictObject({ op: z.literal("json-delete"), path: RelPath, pointer: z.string().startsWith("/") }),
+]);
+/** What must hold after a migration ran. Every check must pass. */
+const PostSchema = z.discriminatedUnion("check", [
+    z.strictObject({ check: z.literal("exists"), path: RelPath }),
+    z.strictObject({ check: z.literal("absent"), path: RelPath }),
+    z.strictObject({ check: z.literal("contains"), path: RelPath, text: z.string().min(1) }),
+    z.strictObject({ check: z.literal("not-contains"), path: RelPath, text: z.string().min(1) }),
+]);
+const Range = z.string().min(1).superRefine((r, ctx) => {
+    try {
+        validateRange(r);
+    }
+    catch (err) {
+        ctx.addIssue({ code: "custom", message: err instanceof VersionRangeError ? err.message : String(err) });
+    }
+});
+const MigrationSchema = z.strictObject({
+    $schema: z.string().optional(),
+    /** Unique within the template. Recorded in the lock once applied. */
+    id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "letters, digits, '.', '_' and '-'"),
+    description: z.string().optional(),
+    from: z.strictObject({
+        /** The template id the migration applies to. Omitted, it applies to the template it ships in. */
+        template: z.string().min(1).optional(),
+        /** The versions it can be applied to. */
+        versions: Range,
+    }),
+    /** The version the scope is at once the migration ran. */
+    to: z.string().refine((v) => parseVersion(v) !== null, "must be a version, such as 2.0.0"),
+    body: z.discriminatedUnion("type", [
+        z.strictObject({ type: z.literal("declarative"), steps: z.array(StepSchema).min(1) }),
+        /**
+         * Code: a module in the migrations directory whose default export is
+         * `async ({ dir }) => void`, run with the scope directory as `dir`.
+         */
+        z.strictObject({ type: z.literal("code"), module: RelPath }),
+    ]),
+    post: z.array(PostSchema).default([]),
+});
+export class MigrationError extends LockError {
+    constructor() {
+        super(...arguments);
+        this.name = "MigrationError";
+    }
+}
+/**
+ * Read the migrations out of a template's files (relative path to bytes).
+ * Returns them and the files that remain once `.chant/migrations/` is taken
+ * out: migrations are the template's, never copied into a project.
+ */
+export function splitMigrations(files) {
+    const rest = new Map();
+    const migrations = [];
+    const modules = new Map();
+    const prefix = `${MIGRATIONS_DIR}/`;
+    for (const [path, data] of files) {
+        if (!path.startsWith(prefix)) {
+            rest.set(path, data);
+            continue;
+        }
+        const rel = path.slice(prefix.length);
+        if (!rel.endsWith(".json")) {
+            modules.set(rel, data);
+            continue;
+        }
+        let raw;
+        try {
+            raw = JSON.parse(data.toString("utf-8"));
+        }
+        catch (err) {
+            throw new MigrationError(`${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const parsed = MigrationSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new MigrationError(`invalid migration ${path}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+        }
+        migrations.push({ migration: parsed.data, file: path });
+    }
+    const ids = new Set();
+    for (const { migration, file } of migrations) {
+        if (ids.has(migration.id))
+            throw new MigrationError(`migration id "${migration.id}" is used twice (${file})`);
+        ids.add(migration.id);
+        if (migration.body.type === "code" && !modules.has(migration.body.module)) {
+            throw new MigrationError(`${file}: its code module ${MIGRATIONS_DIR}/${migration.body.module} is not in the template`);
+        }
+    }
+    return { migrations, modules, files: rest };
+}
+/**
+ * The migrations that take `lineage` from its version to `targetRef`, in order.
+ *
+ * With `switchTo`, the upgrade also moves the scope to another template, the
+ * one with that id (#2551). The chain then starts with a bridge migration: one
+ * the new template ships whose `from.template` names the scope's current
+ * template and whose `from.versions` accepts the scope's version. Its `to` is a
+ * version of the new template, and the new template's own migrations carry on
+ * from there. This is how a fork-born scope, adopted against the fork, comes
+ * forward onto the template the fork came from.
+ *
+ * Refused, with a {@link MigrationError}:
+ * - a target below the scope's version (without a switch: versions of two
+ *   templates do not compare);
+ * - a pending migration when either end of the upgrade is not a version, so
+ *   no chain can be computed;
+ * - a gap: a migration in range whose `from` does not accept the version the
+ *   scope has reached by then;
+ * - a switch with no bridge from the scope's version, when the new template
+ *   has migrations of its own, since the scope's place in its history is
+ *   then unknown.
+ */
+export function planMigrations(lineage, targetRef, available, switchTo) {
+    const from = parseVersion(lineage.ref);
+    const to = parseVersion(targetRef);
+    const applied = new Set(lineage.migrations);
+    const switching = switchTo !== undefined && switchTo !== lineage.template;
+    if (!switching && from && to && compareVersions(to, from) < 0) {
+        throw new MigrationError(`the target ${targetRef} (${formatVersion(to)}) is older than the scope's ${lineage.ref} (${formatVersion(from)}); an upgrade only goes forward`);
+    }
+    const target = switching ? switchTo : lineage.template;
+    const own = available.filter(({ migration: m }) => (m.from.template === undefined || m.from.template === target) && !applied.has(m.id));
+    const bridges = switching ? available.filter(({ migration: m }) => m.from.template === lineage.template && !applied.has(m.id)) : [];
+    if (own.length === 0 && bridges.length === 0)
+        return { chain: [], from, to };
+    if (!from || !to) {
+        const pending = [...bridges, ...own];
+        const which = !from ? `the scope's ref ${lineage.ref ?? "(none)"}` : `the target ${targetRef ?? "(none)"}`;
+        throw new MigrationError(`the template has ${pending.length} migration(s) not yet applied (${pending.map((m) => m.migration.id).join(", ")}), but ${which} is not a version, so no chain can be planned. Pin tagged versions, such as v1.2.0.`);
+    }
+    let at = from;
+    const chain = [];
+    if (switching) {
+        // The bridge: the one that accepts the scope's version and lands furthest without passing the target.
+        const fits = bridges
+            .map((m) => ({ ...m, target: parseVersion(m.migration.to) }))
+            .filter((m) => satisfies(from, m.migration.from.versions) && compareVersions(m.target, to) <= 0)
+            .sort((a, b) => compareVersions(b.target, a.target) || a.migration.id.localeCompare(b.migration.id));
+        if (fits.length === 0) {
+            if (own.length === 0)
+                return { chain: [], from, to };
+            throw new MigrationError(`moving scope from ${lineage.template} to ${switchTo} needs a bridge migration: one in ${switchTo} with from.template "${lineage.template}" whose from.versions accepts ${formatVersion(from)}${bridges.length > 0 ? ` (found ${bridges.map((m) => `${m.migration.id}: ${m.migration.from.versions}`).join(", ")})` : ""}. Without it the scope's place in ${switchTo}'s history is unknown, so the upgrade is refused.`);
+        }
+        chain.push({ migration: fits[0].migration, file: fits[0].file });
+        at = fits[0].target;
+    }
+    const inRange = own
+        .map((m) => ({ ...m, target: parseVersion(m.migration.to) }))
+        .filter((m) => compareVersions(m.target, at) > 0 && compareVersions(m.target, to) <= 0)
+        .sort((a, b) => compareVersions(a.target, b.target) || a.migration.id.localeCompare(b.migration.id));
+    let i = 0;
+    while (i < inRange.length) {
+        const step = inRange[i].target;
+        const group = inRange.filter((m) => compareVersions(m.target, step) === 0);
+        for (const m of group) {
+            if (!satisfies(at, m.migration.from.versions)) {
+                throw new MigrationError(`gap in the migration chain: ${m.migration.id} (${m.file}) upgrades ${m.migration.from.versions} to ${m.migration.to}, but the scope is at ${formatVersion(at)} when it would run. A migration that brings ${formatVersion(at)} into ${m.migration.from.versions} is missing, so the upgrade is refused.`);
+            }
+            chain.push({ migration: m.migration, file: m.file });
+        }
+        at = step;
+        i += group.length;
+    }
+    return { chain, from, to };
+}
+/** Refuse a chain holding code when code is not allowed, before anything runs. */
+export function assertCodeAllowed(chain, allowCode) {
+    const code = chain.filter((m) => m.migration.body.type === "code");
+    if (code.length > 0 && !allowCode) {
+        throw new MigrationError(`the chain includes ${code.length} code migration(s) (${code.map((m) => m.migration.id).join(", ")}), which run the template's own code. Read them, then pass --allow-code to run them.`);
+    }
+}
+/** Run one migration in the worktree, then its post-condition. Updates `lineage`. */
+export async function runMigration(m, opts) {
+    const { migration } = m;
+    const body = migration.body;
+    if (body.type === "code") {
+        if (!opts.allowCode)
+            throw new MigrationError(`${migration.id} is a code migration; pass --allow-code to run it`);
+        const file = join(opts.scratch, "migrations", body.module);
+        mkdirSync(dirname(file), { recursive: true });
+        for (const [rel, data] of opts.modules) {
+            const abs = join(opts.scratch, "migrations", rel);
+            mkdirSync(dirname(abs), { recursive: true });
+            writeFileSync(abs, data);
+        }
+        ensureTypeScriptLoader();
+        const mod = (await import(pathToFileURL(file).href));
+        if (typeof mod.default !== "function")
+            throw new MigrationError(`${migration.id}: ${body.module} has no default export function`);
+        await mod.default({ dir: opts.dir });
+    }
+    else {
+        for (const step of body.steps) {
+            applyStep(step, opts.dir, opts.lineage, migration.id);
+            if (step.op === "move")
+                opts.onMove?.(step.from, step.to);
+        }
+    }
+    const failed = migration.post.filter((c) => !holds(c, opts.dir));
+    if (failed.length > 0) {
+        throw new MigrationError(`migration ${migration.id} ran, but its post-condition does not hold: ${failed.map(describeCheck).join("; ")}. The upgrade is refused.`);
+    }
+    opts.lineage.migrations.push(migration.id);
+}
+function applyStep(step, dir, lineage, id) {
+    const abs = (p) => join(dir, p);
+    const need = (p) => {
+        if (!existsSync(abs(p)))
+            throw new MigrationError(`migration ${id}: ${step.op} needs ${p}, which is not in the scope`);
+    };
+    switch (step.op) {
+        case "move": {
+            need(step.from);
+            if (existsSync(abs(step.to)))
+                throw new MigrationError(`migration ${id}: cannot move ${step.from} to ${step.to}, which exists`);
+            mkdirSync(dirname(abs(step.to)), { recursive: true });
+            renameSync(abs(step.from), abs(step.to));
+            const entry = lineage.files[step.from];
+            if (entry) {
+                delete lineage.files[step.from];
+                lineage.files[step.to] = entry;
+            }
+            return;
+        }
+        case "delete":
+            if (existsSync(abs(step.path)))
+                rmSync(abs(step.path));
+            delete lineage.files[step.path];
+            return;
+        case "replace": {
+            need(step.path);
+            const text = readFileSync(abs(step.path), "utf-8");
+            writeFileSync(abs(step.path), text.split(step.find).join(step.with));
+            return;
+        }
+        case "json-set":
+        case "json-delete": {
+            need(step.path);
+            let doc;
+            try {
+                doc = JSON.parse(readFileSync(abs(step.path), "utf-8"));
+            }
+            catch {
+                throw new MigrationError(`migration ${id}: ${step.path} is not valid JSON`);
+            }
+            const keys = step.pointer.slice(1).split("/").map((k) => k.replace(/~1/g, "/").replace(/~0/g, "~"));
+            const last = keys.pop();
+            let node = doc;
+            for (const k of keys) {
+                if (typeof node[k] !== "object" || node[k] === null) {
+                    if (step.op === "json-delete")
+                        return;
+                    node[k] = {};
+                }
+                node = node[k];
+            }
+            if (step.op === "json-set")
+                node[last] = step.value;
+            else
+                delete node[last];
+            writeFileSync(abs(step.path), JSON.stringify(doc, null, 2) + "\n");
+            return;
+        }
+    }
+}
+function holds(c, dir) {
+    const abs = join(dir, c.path);
+    switch (c.check) {
+        case "exists":
+            return existsSync(abs);
+        case "absent":
+            return !existsSync(abs);
+        case "contains":
+            return existsSync(abs) && readFileSync(abs, "utf-8").includes(c.text);
+        case "not-contains":
+            return !existsSync(abs) || !readFileSync(abs, "utf-8").includes(c.text);
+    }
+}
+function describeCheck(c) {
+    return "text" in c ? `${c.check} ${JSON.stringify(c.text)} in ${c.path}` : `${c.path} ${c.check}`;
+}

package/dist/workspace/lineage-provenance.js

@@ -0,0 +1,36 @@
+/**
+ * The provenance of an adopted lineage (#2551, D5, requirement P7).
+ *
+ * `chant workspace adopt-lineage` records the commit it adopted at, and adds
+ * the range ending there to `.chant/trust.json`. That file is policy, always
+ * read at the base revision (./trust/policy.ts), so an adoption counts only
+ * once its range is in the policy at base, which takes a protected write by
+ * an admin. Until then the scope reads as `unattested`, like any lineage
+ * chant wrote itself.
+ */
+import { execFileSync } from "node:child_process";
+import { isAdopted, policyAtBase, resolveBase } from "./trust/provenance.js";
+/** Null for a lineage that makes no adoption claim: one chant wrote at init, vendor or upgrade, or a directory lineage moved onto git. */
+export function lineageProvenance(root, lineage) {
+    const adoption = lineage.adoption;
+    if (!adoption || adoption.by !== "files")
+        return null;
+    const to = adoption.commits.to;
+    let repo;
+    try {
+        repo = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    }
+    catch {
+        return { level: "unattested", reason: "not in a git repository, so the adopted range cannot be checked" };
+    }
+    const base = resolveBase(repo);
+    if (!base.commit)
+        return { level: "unattested", reason: base.problem ?? "no base revision" };
+    const policy = policyAtBase(repo, base);
+    if (isAdopted(repo, policy, to))
+        return { level: "adopted", reason: `the policy at ${base.commit.slice(0, 12)} adopts the range up to ${to.slice(0, 12)}` };
+    return {
+        level: "unattested",
+        reason: `the range up to ${to.slice(0, 12)} is not in .chant/trust.json at ${base.commit.slice(0, 12)} (${base.from}); it counts once that change is merged`,
+    };
+}

package/dist/workspace/lineage-update.js

@@ -0,0 +1,138 @@
+/**
+ * Bring one lineage scope to a new version of its source, file by file,
+ * without deleting the project's edits (#2540, ws-038).
+ *
+ * For each path, three hashes decide what happens: the merge base recorded in
+ * the lock, the source's new version, and the file in the tree.
+ *
+ * | tree            | source                   | result                                  |
+ * |-----------------|--------------------------|-----------------------------------------|
+ * | equals base     | anything                 | replaced (or removed) by the source     |
+ * | equals source   | anything                 | kept; base moves to the source          |
+ * | edited          | unchanged from base      | kept; base stays                        |
+ * | edited          | changed, merges cleanly  | merged; base moves to the source (*)    |
+ * | edited          | changed or removed       | kept; a manual step                     |
+ * | deleted         | unchanged from base      | stays deleted                           |
+ * | deleted         | changed                  | stays deleted; a manual step            |
+ * | untracked file  | adds the same path       | kept; a manual step                     |
+ *
+ * The table is for `owned` files. A `seed` file is never touched again, and a
+ * `generated` file is left for its command to rebuild (D9, D14). Files in the
+ * scope directory that the lineage does not list are never touched. This is
+ * the per-file rule of ws-005.
+ *
+ * (*) Only when the caller passes {@link MergeOptions}: the merge base's
+ * content, rebuilt by `chant workspace upgrade` (#2550), and a merge function.
+ * A file merges only when every hunk is clean; otherwise it is kept as it was
+ * and becomes one manual step. `chant vendor pull` passes no base, since a
+ * vendor source keeps no history to rebuild it from, so every conflicting
+ * path there is a manual step.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { contentDigest, declaredFilesAt, defaultFileClass, fileHash } from "./lineage-lock.js";
+/**
+ * Apply `upstream` (relative path to bytes) to the scope directory `dir`,
+ * updating `lineage` in place: its files, digest and manual steps. Open manual
+ * steps for paths this update touches again are replaced, others are kept.
+ */
+export function applyUpstream(dir, lineage, upstream, merging) {
+    const result = { written: [], merged: [], skipped: [], removed: [], kept: [], manualSteps: [] };
+    const steps = new Map(lineage.manualSteps.map((s) => [s.path, s]));
+    const paths = new Set([...Object.keys(lineage.files), ...upstream.keys()]);
+    // The declaration's generated list is read again on every update, so a
+    // file the member lists after the lock was written is rebuilt, not merged,
+    // and a file it marks hand-written is merged like any other (#2541).
+    const declared = declaredFilesAt(dir);
+    for (const path of [...paths].sort()) {
+        const abs = join(dir, path);
+        const recorded = lineage.files[path];
+        if (recorded && declared.has(path))
+            lineage.files[path] = { ...defaultFileClass(path, declared), sha256: recorded.sha256 };
+        const entry = lineage.files[path];
+        if (entry && entry.class !== "owned") {
+            // D9: a seed is written once, and a generated file is rebuilt by its
+            // command rather than merged. Neither is written here.
+            result.skipped.push({ path, class: entry.class, ...(entry.command ? { command: entry.command } : {}) });
+            continue;
+        }
+        const base = lineage.files[path]?.sha256;
+        const incoming = upstream.get(path);
+        const theirs = incoming ? fileHash(incoming) : undefined;
+        const local = existsSync(abs) ? fileHash(readFileSync(abs)) : undefined;
+        const step = (reason) => {
+            const s = { path, reason, upstream: theirs ?? null };
+            steps.set(path, s);
+            result.manualSteps.push(s);
+        };
+        const record = (sha) => {
+            lineage.files[path] = { ...(lineage.files[path] ?? defaultFileClass(path, declared)), sha256: sha };
+            steps.delete(path);
+        };
+        if (theirs === undefined) {
+            // The source no longer has the file.
+            if (local === undefined || local === base) {
+                if (local !== undefined) {
+                    rmSync(abs);
+                    result.removed.push(path);
+                }
+                delete lineage.files[path];
+                steps.delete(path);
+            }
+            else {
+                step("removed-upstream");
+                result.kept.push(path);
+            }
+            continue;
+        }
+        if (local === theirs) {
+            record(theirs);
+            continue;
+        }
+        if (local === undefined) {
+            if (base === undefined) {
+                write(abs, incoming);
+                result.written.push(path);
+                record(theirs);
+            }
+            else if (base === theirs) {
+                steps.delete(path);
+            }
+            else {
+                step("deleted-locally");
+            }
+            continue;
+        }
+        if (base !== undefined && local === base) {
+            write(abs, incoming);
+            result.written.push(path);
+            record(theirs);
+            continue;
+        }
+        // The tree has its own version of the file.
+        if (base !== undefined && base === theirs) {
+            result.kept.push(path);
+            steps.delete(path);
+            continue;
+        }
+        const baseData = merging?.base.get(path);
+        if (merging && baseData && fileHash(baseData) === base) {
+            const merged = merging.merge(baseData, readFileSync(abs), incoming);
+            if (merged) {
+                writeFileSync(abs, merged);
+                result.merged.push(path);
+                record(theirs);
+                continue;
+            }
+        }
+        result.kept.push(path);
+        step(base === undefined ? "exists-locally" : "changed-locally");
+    }
+    lineage.manualSteps = [...steps.values()].sort((a, b) => a.path.localeCompare(b.path));
+    lineage.address = { ...(lineage.address ?? {}), digest: contentDigest(upstream) };
+    return result;
+}
+function write(abs, data) {
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, data);
+}

package/dist/workspace/lineage-upgrade-cli.js

@@ -0,0 +1,131 @@
+/**
+ * `chant workspace upgrade [<scope>] [--to <ref|dir>] [--allow-code] [--dry-run]
+ * [--output <file>] [--json]` (#2550).
+ *
+ * Stages the upgrade in a worktree (see ./lineage-upgrade.ts), then decides
+ * its gate. The gate is `workspace-upgrade/<scope>` on the gate ledger, and it
+ * binds the digest of the patch the staging produced. The first run records
+ * the pending fact and exits 3, the code `chant run` gives a gated run. After
+ * `chant approve workspace-upgrade <scope>`, the same command stages the same
+ * patch, finds the approval for its digest, and applies the patch to the tree.
+ * A patch that differs from the approved one needs a new approval.
+ */
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../cli/format.js";
+import { approveCommand, describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort } from "../op/gate.js";
+import { WORKSPACE_UPGRADE_GATE_OP } from "../op/gate-name.js";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../lifecycle/local-note.js";
+import { LockError } from "./lineage-lock.js";
+import { applyStagedUpgrade, describeStaged, stageUpgrade } from "./lineage-upgrade.js";
+const USAGE = "chant workspace upgrade [<scope>] [--to <ref|dir>] [--source <repo>[#<member>]] [--allow-code] [--dry-run] [--output <patch file>] [--json]";
+/** The exit code of a gated upgrade: the same as `chant run`'s gated run. */
+export const UPGRADE_GATED_EXIT = 3;
+/** The command, with its output. Returns the exit code and what happened. */
+export async function upgradeCommand(opts) {
+    const staged = await stageUpgrade({
+        root: opts.root,
+        scope: opts.scope,
+        to: opts.to,
+        ...(opts.source !== undefined ? { source: opts.source } : {}),
+        allowCode: opts.allowCode,
+        runChant: opts.runChant,
+    });
+    try {
+        const { dispose: _d, patch: _p, worktree: _w, worktreeProject: _wp, lock: _l, ...view } = staged;
+        const report = (outcome, exitCode, extra = {}) => {
+            if (opts.json)
+                console.log(JSON.stringify({ outcome, ...view, ...extra }, null, 2));
+            return { outcome, exitCode, staged: view };
+        };
+        if (!opts.json)
+            console.log(describeStaged(staged).join("\n"));
+        if (!opts.json && !staged.lock.tracked) {
+            console.error(formatWarning({
+                message: `${staged.lock.path} is not tracked by git (a .gitignore covers it), so it is written beside the patch rather than in it. Commit it with \`git add -f\` so the lineage travels with the project.`,
+            }));
+        }
+        if (!staged.changed && staged.checksOk) {
+            if (!opts.json)
+                console.error(formatSuccess(`scope "${staged.gate}" is already at ${staged.to ?? "its source"}; nothing to upgrade`));
+            return report("up-to-date", 0);
+        }
+        if (opts.output)
+            writeFileSync(resolve(opts.output), staged.patch);
+        if (!staged.checksOk) {
+            if (!opts.json) {
+                for (const c of staged.checks.filter((c) => c.status === "failed")) {
+                    console.error(formatError({ message: `${c.name} failed in the staging worktree`, hint: c.detail }));
+                }
+                console.error(formatError({ message: "the upgrade was not gated: its checks must pass first. The tree is unchanged." }));
+            }
+            return report("checks-failed", 1);
+        }
+        if (opts.dryRun) {
+            if (!opts.json)
+                console.error(formatInfo("--dry-run: staged and checked; no gate recorded, the tree is unchanged"));
+            return report("dry-run", 0);
+        }
+        const gate = staged.gate;
+        const check = await evaluateGate(opts.ledger ?? gitGateLedgerPort({ cwd: staged.repo }), {
+            op: WORKSPACE_UPGRADE_GATE_OP,
+            gate,
+            description: `upgrade ${staged.template} ${staged.from ?? ""} -> ${staged.to ?? ""} in scope ${staged.member ?? staged.scope}`.replace(/\s+/g, " "),
+            planDigest: staged.digest,
+            ...(staged.governance ? { approval: staged.governance.approval } : {}),
+            ...(opts.now ? { now: opts.now } : {}),
+        });
+        if (!check.satisfied) {
+            if (!opts.json) {
+                const sealed = await gateIsSealed(gate);
+                if (check.mismatch)
+                    console.error(formatWarning({ message: describeGateMismatch(WORKSPACE_UPGRADE_GATE_OP, gate, check.mismatch, sealed) }));
+                if (isLifecycleLocalNote(check.pushWarning))
+                    console.error(formatInfo(LIFECYCLE_LOCAL_NOTE));
+                else if (check.pushWarning)
+                    console.error(formatWarning({ message: check.pushWarning }));
+                if (check.quorum)
+                    console.error(formatInfo(`approvals so far: ${check.quorum.approvers.length} of ${check.quorum.need}`));
+                console.error(formatInfo(`Gated: the patch ${staged.digest} waits for approval. Review it (--output <file> writes it), then run \`${approveCommand(WORKSPACE_UPGRADE_GATE_OP, gate, undefined, undefined, sealed)}\` and repeat this command to apply it.`));
+            }
+            return report("gated", UPGRADE_GATED_EXIT, { pending: check.pending });
+        }
+        applyStagedUpgrade(staged);
+        if (!opts.json) {
+            console.error(formatSuccess(`applied the approved upgrade of "${staged.gate}" (${staged.digest}), approved by ${check.resolution.resolvedBy}. Review and commit it.`));
+            if (staged.manualSteps.length > 0) {
+                console.error(formatInfo(`${staged.manualSteps.length} manual step(s) are open; \`chant workspace check\` fails until each is merged and resolved.`));
+            }
+        }
+        return report("applied", 0, { approvedBy: check.resolution.resolvedBy });
+    }
+    finally {
+        staged.dispose();
+    }
+}
+export async function runWorkspaceUpgrade(ctx) {
+    const { args } = ctx;
+    if (args.extraPositional2) {
+        console.error(formatError({ message: `unexpected argument: ${args.extraPositional2}`, hint: USAGE }));
+        return 1;
+    }
+    try {
+        const result = await upgradeCommand({
+            root: process.cwd(),
+            scope: args.extraPositional,
+            to: args.migrateTo,
+            source: args.source,
+            allowCode: args.allowCode,
+            dryRun: args.dryRun,
+            output: args.output,
+            json: args.json,
+        });
+        return result.exitCode;
+    }
+    catch (err) {
+        if (!(err instanceof LockError))
+            throw err;
+        console.error(formatError({ message: err.message, hint: USAGE }));
+        return 1;
+    }
+}