@intentius/chant 0.124.48 → 0.124.50

package/dist/workspace/exit-cli.js

@@ -0,0 +1,198 @@
+/**
+ * `chant workspace exit [<member>...] [--dry-run] [--drill] [--output <file>] [--json]`
+ * (#3177).
+ *
+ * Stages the exit in a git worktree (see ./exit.ts), checks the staged tree
+ * with the same static checks the exit drill uses, then decides a gate. The
+ * gate is `workspace-exit/<scope>` on the gate ledger and binds the digest of
+ * the patch, as `workspace upgrade` does: the first run records the pending
+ * fact and exits 3; after `chant approve workspace-exit <scope>` the same
+ * command stages the same patch and applies it to the tree.
+ *
+ * `--drill` skips the worktree and the gate: it runs the exit on a scratch
+ * copy and prints the per-member result, the check CI runs on every commit.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve, sep } from "node:path";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../cli/format.js";
+import { approveCommand, describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort } from "../op/gate.js";
+import { WORKSPACE_EXIT_GATE_OP } from "../op/gate-name.js";
+import { findWorkspaceRoot } from "../project-root.js";
+import { describeDrill, ExitError, exitInDir, planExit, runExitDrill, verifyExit } from "./exit.js";
+import { spawnChant } from "./lineage-upgrade.js";
+const USAGE = "chant workspace exit [<member>...] [--member <name>] [--dry-run] [--drill] [--output <patch file>] [--json]";
+/** The exit code of a gated exit: the same as `chant run`'s gated run. */
+export const EXIT_GATED = 3;
+const EXIT_DIR = ".chant/exit";
+function git(cwd, args) {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+}
+const defaultBuild = (command, cwd, args) => spawnChant(command, cwd, args);
+export async function exitCommand(opts) {
+    const runBuild = opts.runBuild ?? defaultBuild;
+    const names = opts.members ?? [];
+    const print = (lines) => {
+        if (!opts.json)
+            console.log(lines.join("\n"));
+    };
+    if (opts.drill) {
+        const report = await runExitDrill({ root: opts.root, members: names, runBuild });
+        if (opts.json)
+            console.log(JSON.stringify({ outcome: "drill", ...report }, null, 2));
+        else
+            print(describeDrill(report));
+        return { outcome: "drill", exitCode: report.ok ? 0 : 1, report };
+    }
+    let repo;
+    let head;
+    try {
+        repo = git(opts.root, ["rev-parse", "--show-toplevel"]).trim();
+        head = git(opts.root, ["rev-parse", "HEAD"]).trim();
+    }
+    catch {
+        throw new ExitError("chant workspace exit stages its change in a git worktree, so the project must be in a git repository with at least one commit");
+    }
+    const dirty = git(repo, ["status", "--porcelain", "--untracked-files=all"])
+        .split("\n")
+        .filter(Boolean)
+        .filter((l) => !l.slice(3).includes(`${EXIT_DIR}/`));
+    if (dirty.length > 0) {
+        throw new ExitError(`the tree has uncommitted changes (${dirty.slice(0, 5).map((l) => l.slice(3)).join(", ")}${dirty.length > 5 ? ", ..." : ""}). Commit them: the exit stages from HEAD and applies its patch to the tree.`);
+    }
+    const rel = relative(repo, opts.root).split(sep).join("/");
+    const holder = join(opts.root, EXIT_DIR);
+    mkdirSync(holder, { recursive: true });
+    const worktree = mkdtempSync(join(holder, "wt-"));
+    rmSync(worktree, { recursive: true, force: true });
+    git(repo, ["worktree", "add", "--detach", "-q", worktree, head]);
+    const dispose = () => {
+        try {
+            git(repo, ["worktree", "remove", "--force", worktree]);
+        }
+        catch {
+            rmSync(worktree, { recursive: true, force: true });
+        }
+    };
+    try {
+        const project = rel ? join(worktree, rel) : worktree;
+        const plan = planExit(project, names);
+        const result = await exitInDir(plan, runBuild);
+        const report = verifyExit(project, result);
+        git(worktree, ["add", "-A"]);
+        const patch = git(worktree, ["diff", "--cached", "--binary", "HEAD"]);
+        const digest = `sha256:${createHash("sha256").update(patch).digest("hex").slice(0, 16)}`;
+        if (opts.json) {
+            // printed once, below
+        }
+        else {
+            print(describeExit(result, digest));
+            print(describeDrill(report));
+        }
+        const out = (outcome, exitCode, extra = {}) => {
+            if (opts.json)
+                console.log(JSON.stringify({ outcome, digest, ...result, report, ...extra }, null, 2));
+            return { outcome, exitCode, result, report, digest };
+        };
+        if (opts.output)
+            writeFileSync(resolve(opts.output), patch);
+        if (!patch) {
+            if (!opts.json)
+                console.error(formatInfo("nothing to exit: no member changed"));
+            return out("nothing-to-exit", 0);
+        }
+        if (!report.ok) {
+            if (!opts.json)
+                console.error(formatError({ message: "the exit was not gated: its checks must pass first. The tree is unchanged." }));
+            return out("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 out("dry-run", 0);
+        }
+        const gate = names.length > 0 ? names.join("+") : "workspace";
+        const check = await evaluateGate(opts.ledger ?? gitGateLedgerPort({ cwd: repo }), {
+            op: WORKSPACE_EXIT_GATE_OP,
+            gate,
+            description: `leave chant: ${gate}`,
+            planDigest: digest,
+            ...(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_EXIT_GATE_OP, gate, check.mismatch, sealed) }));
+                console.error(formatInfo(`Gated: the patch ${digest} waits for approval. Review it (--output <file> writes it), then run \`${approveCommand(WORKSPACE_EXIT_GATE_OP, gate, undefined, undefined, sealed)}\` and repeat this command to apply it.`));
+            }
+            return out("gated", EXIT_GATED, { pending: check.pending });
+        }
+        applyPatch(repo, patch);
+        if (!opts.json)
+            console.error(formatSuccess(`applied the approved exit (${digest}), approved by ${check.resolution.resolvedBy}. Review and commit it.`));
+        return out("applied", 0, { approvedBy: check.resolution.resolvedBy });
+    }
+    finally {
+        dispose();
+    }
+}
+function applyPatch(repo, patch) {
+    const dir = mkdtempSync(join(tmpdir(), "chant-exit-patch-"));
+    const file = join(dir, "exit.patch");
+    try {
+        writeFileSync(file, patch);
+        git(repo, ["apply", "--binary", "--whitespace=nowarn", file]);
+    }
+    catch (err) {
+        const stderr = err.stderr?.toString().trim();
+        throw new ExitError(`the approved patch no longer applies to the tree${stderr ? `: ${stderr}` : ""}`);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** One line per member, for the terminal. */
+export function describeExit(result, digest) {
+    const lines = [];
+    for (const m of result.members) {
+        lines.push(`${m.name}  ${m.kind}  ${m.status}${m.detail ? ` (${m.detail})` : ""}`);
+        for (const n of m.native)
+            lines.push(`  native: ${n}`);
+        for (const d of m.deploy)
+            lines.push(`  deploy: ${d}`);
+        for (const c of m.ci)
+            lines.push(`  ci: ${c}`);
+        for (const o of m.ops)
+            lines.push(`  kept: ${o}`);
+        for (const s of m.steps)
+            lines.push(`  step: ${s}`);
+    }
+    lines.push(`  patch: ${digest}`);
+    return lines;
+}
+export async function runWorkspaceExit(ctx) {
+    const { args } = ctx;
+    // positionals are ["exit", <member>...]
+    const named = [...(args.positionals ?? []).slice(1), ...(args.members ?? [])];
+    const root = findWorkspaceRoot(process.cwd())?.dir ?? process.cwd();
+    try {
+        const result = await exitCommand({
+            root,
+            members: [...new Set(named)],
+            dryRun: args.dryRun,
+            drill: args.drill,
+            output: args.output,
+            json: args.json,
+        });
+        return result.exitCode;
+    }
+    catch (err) {
+        if (!(err instanceof ExitError))
+            throw err;
+        console.error(formatError({ message: err.message, hint: USAGE }));
+        return 1;
+    }
+}

package/dist/workspace/exit.d.ts

@@ -0,0 +1,159 @@
+/**
+ * `chant workspace exit` (#3177): leave a member, or the workspace, in one
+ * step, and prove on every commit that leaving still works.
+ *
+ * Per member kind:
+ *
+ * - `chant`: build once per lexicon and commit the native output under
+ *   `native/`, rewrite the member's CI files to call the platform's own CLI,
+ *   drop the chant dependencies and `chant.config.*`, and set the member to
+ *   `other` with its outputs listed. Where an Op's `op.json` sits in the
+ *   member and the Op is linear (shell steps only), a plain CI job is written
+ *   beside it. The `op.json` stays.
+ * - `choudoufu`: the roundtrip in choudoufu's `live/MIGRATE.md`. It needs
+ *   stock OpenTofu and the estate's state, so the exit lists its steps and
+ *   changes no file.
+ * - every other kind (`other`, records, ledgers, `workspace`, `repo`): kept
+ *   as files.
+ *
+ * The functions here work on a plain directory, so the same code runs in the
+ * staging worktree (`exit-cli.ts`) and in the drill's scratch copy.
+ * {@link runExitDrill} runs the exit on a scratch copy of a workspace and
+ * checks the result statically: it proves each member holds what a stock
+ * tool needs and nothing that needs chant. It never installs chant or calls
+ * a cloud, so it is a unit-level check CI can run on every commit.
+ */
+/** Runs `chant build` in a directory. The same shape as `ChantRunner` in lineage-upgrade.ts. */
+export type ExitBuildRunner = (command: "build", cwd: string, args: readonly string[]) => Promise<{
+    exitCode: number;
+    output: string;
+}>;
+export interface NativeTarget {
+    /** What the output is. */
+    describes: string;
+    /** The file under the member's `native/` directory, or a path from the member's directory when `inMember`. */
+    file: string;
+    /** The file is written at this path from the member's directory rather than under `native/`. */
+    inMember?: boolean;
+    /** The stock command that deploys it, given the committed file's path from the member's directory and the member name. Null when there is nothing to deploy (CI files, collector config). */
+    deploy: ((file: string, member: string) => string) | null;
+}
+/** The lexicons `workspace exit` knows a native target for. */
+export declare const NATIVE_TARGETS: Record<string, NativeTarget>;
+/** The lexicons a member's `chant.config.*` or `package.json` names, in order. */
+export declare function memberLexicons(dir: string): string[];
+export type ExitAction = "native-build" | "choudoufu-roundtrip" | "keep";
+/** Why a chant member cannot be exited. Closed; each is in `reason-codes.ts`. */
+export declare const EXIT_REFUSAL_CODES: readonly ["missing-dir", "no-lexicon", "lexicon-unsupported"];
+export type ExitRefusalCode = (typeof EXIT_REFUSAL_CODES)[number];
+export interface MemberPlan {
+    name: string;
+    dir: string;
+    kind: string;
+    action: ExitAction;
+    lexicons: string[];
+    /** Set when the member cannot be exited, with the reason code. */
+    refused?: {
+        code: ExitRefusalCode;
+        message: string;
+    };
+}
+export interface ExitPlan {
+    root: string;
+    members: MemberPlan[];
+}
+export declare class ExitError extends Error {
+}
+/** What exiting `names` (every exitable member when none are named) does, read from the declaration. */
+export declare function planExit(root: string, names?: readonly string[]): ExitPlan;
+export interface MemberResult {
+    name: string;
+    dir: string;
+    kind: string;
+    status: "exited" | "kept" | "manual" | "refused" | "failed";
+    /** Why the member was refused; set only with status `refused`. */
+    code?: ExitRefusalCode;
+    /** Native files written, relative to the workspace root. */
+    native: string[];
+    /** The stock command for each native file, relative to the member's directory. */
+    deploy: string[];
+    /** CI files rewritten or written, relative to the workspace root. */
+    ci: string[];
+    /** `op.json` files left in place, relative to the workspace root. */
+    ops: string[];
+    /** Steps a person runs, for a member the exit cannot do alone. */
+    steps: string[];
+    detail?: string;
+}
+export interface ExitResult {
+    members: MemberResult[];
+}
+/** The choudoufu roundtrip, in order (`live/MIGRATE.md`). Run with stock OpenTofu. */
+export declare function choudoufuSteps(member: string, dir: string): string[];
+/**
+ * Exit the planned members in the tree at `plan.root`, editing it in place.
+ * Builds through `runBuild`, so a test can supply output without chant.
+ */
+export declare function exitInDir(plan: ExitPlan, runBuild: ExitBuildRunner): Promise<ExitResult>;
+interface OpJson {
+    name?: string;
+    phases?: {
+        parallel?: boolean;
+        steps?: {
+            kind?: string;
+            fn?: string;
+            args?: {
+                cmd?: unknown;
+            };
+        }[];
+    }[];
+    onFailure?: unknown[];
+}
+/** The plain commands of a linear Op, or undefined when the Op is not linear. */
+export declare function linearCommands(op: OpJson): string[] | undefined;
+/** What the exit drill finds wrong with an exited member. Closed; each is in `reason-codes.ts`. */
+export declare const DRILL_CODES: readonly ["native-missing", "native-unreadable", "chant-dependency", "chant-config-left", "chant-in-ci", "no-deploy-command", "declaration-not-other", "exit-failed", "choudoufu-steps-missing"];
+export type DrillCode = (typeof DRILL_CODES)[number];
+/** Every code `workspace exit` prints: why a member was refused, and what the drill found. */
+export declare const EXIT_CODES: readonly ["missing-dir", "no-lexicon", "lexicon-unsupported", "native-missing", "native-unreadable", "chant-dependency", "chant-config-left", "chant-in-ci", "no-deploy-command", "declaration-not-other", "exit-failed", "choudoufu-steps-missing"];
+export interface DrillFinding {
+    code: DrillCode;
+    message: string;
+}
+export interface DrillMember {
+    name: string;
+    kind: string;
+    status: "passed" | "failed" | "not-run" | "kept";
+    /** Why it is `not-run` or `kept`. */
+    note?: string;
+    findings: DrillFinding[];
+    native: string[];
+    deploy: string[];
+}
+export interface DrillReport {
+    /** True when no member failed. A `not-run` member does not fail the drill; it is listed. */
+    ok: boolean;
+    members: DrillMember[];
+}
+export interface DrillOptions {
+    /** The workspace root to drill. It is copied; the tree is not touched. */
+    root: string;
+    /** Limit to these members. */
+    members?: readonly string[];
+    /** Builds a member's native output. */
+    runBuild: ExitBuildRunner;
+}
+/** Copy a workspace, leaving out `node_modules`, `.git` and chant's own scratch. */
+export declare function copyWorkspace(from: string, to: string): void;
+/**
+ * Run the exit on a scratch copy and check each member for what a stock tool
+ * needs. Nothing here runs chant or a cloud; the build is the one injected
+ * step, and its output is read as text.
+ */
+export declare function runExitDrill(opts: DrillOptions): Promise<DrillReport>;
+/** Check an exited tree at `root` against what {@link exitInDir} reported. */
+export declare function verifyExit(root: string, result: ExitResult): DrillReport;
+/** The drill report as lines for a terminal. */
+export declare function describeDrill(report: DrillReport): string[];
+export {};
+//# sourceMappingURL=exit.d.ts.map

package/dist/workspace/exit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit.d.ts","sourceRoot":"","sources":["../../src/workspace/exit.ts"],"names":[],"mappings":"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"}