@intentius/chant 0.124.27 → 0.124.28

package/src/cli/handlers/release.ts

@@ -0,0 +1,206 @@
+/**
+ * `chant release` (#4026, ws-104): the release is what graduates.
+ *
+ *   release cut [<label>] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json]
+ *       cut a release of this member from the checkout's HEAD, which must be green;
+ *       --sign signs the cut with the actor's ssh key (#4031); `--src`, `-o` and
+ *       `--lexicon` shape the build of a project with no components (#4046)
+ *   release list [--json]
+ *       every release of this member with its targets, its cuts and where it runs;
+ *       `--json` prints the read contract's `releases` document
+ *   release export <label|digest> --env <env> [-o <dir>] [--json]
+ *       write the files the release recorded for <env>, checked against their digests (#4046)
+ *   release compile --env <env> [--build <command>] [--artifacts --component <a,b>] --json
+ *       internal: what the cut runs in a child process per environment
+ *
+ * The workstation UX for `cut` grows in #4027. A declaration whose
+ * `identity.gates` names a `release` gate requires a signed cut by an actor
+ * in its class (#4031).
+ */
+
+import { resolve } from "node:path";
+import { formatBold, formatError, formatSuccess, formatWarning } from "../format";
+import { parseParamFlags } from "../build-params-cli";
+import type { CommandContext } from "../registry";
+
+const USAGE =
+  "chant release cut [<label>] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
+
+/** The build inputs `release cut` and `release compile` share. */
+function compileInputs(ctx: CommandContext, params: Record<string, string> | undefined): import("../../components/release-compile").CompileInputs {
+  const { args } = ctx;
+  return {
+    projectDir: resolve("."),
+    ...(args.buildCommand ? { buildCommand: args.buildCommand } : {}),
+    ...(params ? { params } : {}),
+    ...(args.paramsFile ? { paramsFile: args.paramsFile } : {}),
+    ...(args.src ? { src: args.src } : {}),
+    ...(args.output ? { output: args.output } : {}),
+    ...(args.lexicon ? { lexicon: args.lexicon } : {}),
+  };
+}
+
+function resolveActor(ctx: CommandContext): string | undefined {
+  return ctx.args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER;
+}
+
+export async function runReleaseCut(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const positional = args.extraPositional;
+  if (positional && args.label && positional !== args.label) {
+    console.error(formatError({ message: `the label is given twice, as "${positional}" and --label "${args.label}"`, hint: USAGE }));
+    return 1;
+  }
+  const label = positional ?? args.label ?? null;
+  const actor = resolveActor(ctx);
+  if (!actor) {
+    console.error(formatError({ message: "Could not resolve --actor from the environment", hint: "Pass --actor explicitly, or set GITHUB_ACTOR / GITLAB_USER_LOGIN / USER." }));
+    return 1;
+  }
+  const cwd = resolve(".");
+  const { spawnTargetCompiler, ReleaseCompileError } = await import("../../components/release-compile");
+  const { cutRelease, ReleaseCutError } = await import("../../lifecycle/release-cut");
+  const { ReleaseLabelError } = await import("../../lifecycle/release-store");
+  const { pushLifecycleReport } = await import("../../lifecycle/git");
+  const params = parseParamFlags(args.param);
+  const compiler = spawnTargetCompiler(compileInputs(ctx, params));
+  try {
+    const result = await cutRelease({ cwd, compiler, label, actor, ...(args.sign !== undefined ? { sign: args.sign } : {}) });
+    const push = await pushLifecycleReport({ cwd }).catch(() => ({ pushed: false, pushWarning: undefined }));
+    if (args.json) {
+      console.log(JSON.stringify({ release: result.release, label: result.label, cut: result.cut, stored: result.stored, reused: result.reused }, null, 2));
+    } else {
+      const name = result.label ? formatBold(result.label) : "unlabelled release";
+      if (result.cut) console.error(formatSuccess(`Cut ${name}: ${result.release.releaseDigest}`));
+      else console.error(formatSuccess(`Already cut${result.label ? ` as ${formatBold(result.label)}` : ""}: ${result.release.releaseDigest}`));
+      console.error(`  commit ${result.release.commit}`);
+      if (result.cut) console.error(result.cut.signature ? `  signed by ${result.cut.actor}` : "  not signed");
+      console.error(`  artifacts ${result.release.artifactDigests.length}, targets ${result.release.targets.map((t) => `${t.env} (${t.templates.length} template${t.templates.length === 1 ? "" : "s"})`).join(", ")}`);
+      for (const r of result.reused) console.error(`  ${r.component}: artifacts unchanged, carried from ${r.from}`);
+      console.log(result.release.releaseDigest);
+    }
+    if (push.pushWarning) console.error(formatWarning({ message: push.pushWarning }));
+    return 0;
+  } catch (err) {
+    if (err instanceof ReleaseCutError) {
+      console.error(formatError({ message: `${err.message} [${err.code}]`, ...(err.fix ? { hint: err.fix } : {}) }));
+      return 1;
+    }
+    if (err instanceof ReleaseLabelError) {
+      console.error(formatError({ message: `${err.message} [${err.code}]` }));
+      return 1;
+    }
+    if (err instanceof ReleaseCompileError) {
+      console.error(formatError({ message: `no release was cut: ${err.message}` }));
+      return 1;
+    }
+    throw err;
+  }
+}
+
+export async function runReleaseList(ctx: CommandContext): Promise<number> {
+  const { releasesDocument } = await import("../../workspace/releases");
+  const doc = await releasesDocument({ cwd: resolve(".") });
+  if (ctx.args.json) {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc ? 1 : 0;
+  }
+  if ("error" in doc) {
+    console.error(formatError({ message: doc.error.message, hint: USAGE }));
+    return 1;
+  }
+  if (doc.reason) console.error(formatWarning({ message: doc.reason.message }));
+  if (doc.releases.length === 0) {
+    console.error("No releases. Cut one from a green commit: chant release cut <label>");
+    return 0;
+  }
+  for (const r of doc.releases) {
+    const where = r.environments.map((e) => e.env).join(", ") || "not deployed from the release";
+    // #4031: the newest cut's signature, as the policy at base judges it.
+    const newest = r.cuts.at(-1);
+    const signature = newest ? (newest.signatureCheck.status === "verified" ? `signed by ${newest.actor}` : newest.signatureCheck.status) : "-";
+    console.log(`${(r.label ?? "-").padEnd(16)}  ${r.releaseDigest}  ${r.commit.slice(0, 12)}  ${signature}  ${where}`);
+    if (newest?.signatureCheck.status === "unverified") console.error(`  ${r.label ?? r.releaseDigest}: ${newest.signatureCheck.reason}`);
+  }
+  return 0;
+}
+
+/**
+ * `release export <label|digest> --env <env> [-o <dir>]` (#4046): write each
+ * file the release's target for <env> records, at the path it was compiled to,
+ * under <dir> (the member's directory by default), after checking each one's
+ * bytes against its digest. This is how a project with no components deploys
+ * a release: its own deploy reads these files instead of building again.
+ */
+export async function runReleaseExport(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const ref = args.extraPositional;
+  if (!ref || !args.env) {
+    console.error(formatError({ message: "release export needs a release and an environment", hint: USAGE }));
+    return 1;
+  }
+  const { fetchLifecycle } = await import("../../lifecycle/git");
+  const { resolveRelease, readReleaseTemplate } = await import("../../lifecycle/release-store");
+  const { targetFor, targetFiles, writePinnedTemplates } = await import("../../components/release-promote");
+  await fetchLifecycle().catch(() => false);
+  const found = await resolveRelease(ref);
+  if (!found) {
+    console.error(formatError({ message: `no release is labelled or digested "${ref}" in this member`, hint: "List them with: chant release list" }));
+    return 1;
+  }
+  const target = targetFor(found.release, args.env);
+  if ("error" in target) {
+    console.error(formatError({ message: target.error }));
+    return 1;
+  }
+  const read = await targetFiles(found.release, target.target, (digest) => readReleaseTemplate(digest));
+  if ("errors" in read) {
+    for (const e of read.errors) console.error(formatError({ message: e }));
+    return 1;
+  }
+  const dir = resolve(args.output ?? ".");
+  writePinnedTemplates(dir, read.files);
+  if (args.json) {
+    console.log(
+      JSON.stringify(
+        { releaseDigest: found.release.releaseDigest, label: found.label, env: args.env, dir, templates: target.target.templates, params: target.target.params },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.error(formatSuccess(`Wrote ${read.files.length} file(s) of ${found.label ? formatBold(found.label) : found.release.releaseDigest} for "${args.env}"`));
+    for (const f of read.files) console.log(f.path);
+  }
+  return 0;
+}
+
+/** Internal: compile one environment, or build artifacts, in this process, and print the JSON the cut reads. */
+export async function runReleaseCompile(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const env = args.env;
+  if (!env) {
+    console.error(formatError({ message: "release compile needs --env <env>" }));
+    return 1;
+  }
+  const { compileEnvironment, buildReleaseArtifacts } = await import("../../components/release-compile");
+  const params = parseParamFlags(args.param);
+  const inputs = compileInputs(ctx, params);
+  try {
+    if (args.artifacts) {
+      const names = (args.component ?? "").split(",").map((n) => n.trim()).filter(Boolean);
+      console.log(JSON.stringify({ artifacts: await buildReleaseArtifacts(inputs, env, names) }));
+    } else {
+      console.log(JSON.stringify(await compileEnvironment(inputs, env)));
+    }
+    return 0;
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+}
+
+export async function runReleaseUnknown(ctx: CommandContext): Promise<number> {
+  console.error(formatError({ message: `Unknown release subcommand: ${ctx.args.path}`, hint: USAGE }));
+  return 1;
+}

package/src/cli/handlers/run-auto-release.test.ts

@@ -0,0 +1,71 @@
+/**
+ * What `recordAutoReleasesForRun` hands the release record (#4020): the run
+ * and its origin, and for a component that passed a gate, who approved it and
+ * which resolution admitted it.
+ */
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+
+const maybeRecordAutoReleaseMock = vi.fn();
+vi.mock("../../components/auto-release", async () => {
+  const actual = await vi.importActual<typeof import("../../components/auto-release")>("../../components/auto-release");
+  return { ...actual, maybeRecordAutoRelease: (...args: unknown[]) => maybeRecordAutoReleaseMock(...args) };
+});
+vi.mock("../../components/manifest-persistence", async () => {
+  const actual = await vi.importActual<typeof import("../../components/manifest-persistence")>("../../components/manifest-persistence");
+  return { ...actual, maybePersistBuildManifest: async () => ({ persisted: false, reason: "no-manifest" }) };
+});
+
+import { autoReleaseRun, recordAutoReleasesForRun } from "./run";
+import type { DriverComponentResult } from "../../components/driver";
+
+const gatedResult = {
+  component: "api",
+  ok: true,
+  status: "ok",
+  records: [
+    { component: "api", phase: "Deploy", kind: "gate:approve-prod", status: "ok", durationMs: 1, approval: { gate: "approve-prod", resolvedBy: "alice", timestamp: "2026-10-16T10:05:00.000Z" } },
+    { component: "api", phase: "Deploy", kind: "apply", status: "ok", durationMs: 1 },
+  ],
+} as unknown as DriverComponentResult;
+const plainResult = { component: "worker", ok: true, status: "ok", records: [] } as unknown as DriverComponentResult;
+
+beforeEach(() => {
+  maybeRecordAutoReleaseMock.mockReset().mockResolvedValue({ recorded: false, reason: "no-digest" });
+});
+afterEach(() => vi.unstubAllEnvs());
+
+describe("recordAutoReleasesForRun", () => {
+  test("a component that passed a gate records its approver and admission, one that did not records neither", async () => {
+    await recordAutoReleasesForRun([gatedResult, plainResult], "prod", "9001", false, { forge: "github", repo: "acme/app" });
+    const [gated, plain] = maybeRecordAutoReleaseMock.mock.calls.map((c) => c[0]);
+    expect(gated).toMatchObject({
+      component: "api", runId: "9001", runOrigin: { forge: "github", repo: "acme/app" },
+      approver: "alice", admission: { op: "api", gate: "approve-prod", resolvedAt: "2026-10-16T10:05:00.000Z" },
+    });
+    expect(plain).not.toHaveProperty("approver");
+    expect(plain).not.toHaveProperty("admission");
+  });
+
+  test("the origin defaults to local", async () => {
+    await recordAutoReleasesForRun([plainResult], "prod", "local-1", false);
+    expect(maybeRecordAutoReleaseMock.mock.calls[0][0]).toMatchObject({ runId: "local-1", runOrigin: { forge: "local" } });
+  });
+});
+
+describe("autoReleaseRun", () => {
+  test("in CI it names the CI run, so the release and the gate it passed name one run", () => {
+    vi.stubEnv("GITHUB_RUN_ID", "9001");
+    vi.stubEnv("GITHUB_REPOSITORY", "acme/app");
+    vi.stubEnv("GITHUB_SERVER_URL", "https://github.example");
+    expect(autoReleaseRun("local-1")).toEqual({
+      runId: "9001",
+      runOrigin: { forge: "github", repo: "acme/app", url: "https://github.example/acme/app/actions/runs/9001" },
+    });
+  });
+
+  test("outside CI it keeps the local id", () => {
+    vi.stubEnv("GITHUB_RUN_ID", "");
+    vi.stubEnv("CI_PIPELINE_ID", "");
+    expect(autoReleaseRun("local-1")).toEqual({ runId: "local-1", runOrigin: { forge: "local" } });
+  });
+});

package/src/cli/handlers/run-events-cmd.test.ts

@@ -0,0 +1,92 @@
+/** #4042: `chant run events <run> [--json] [--follow]`. */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { ParsedArgs } from "../registry";
+import { runOpEvents } from "./run";
+import { openRunEventStore } from "../../run-event-store";
+import { openRunEventStream, runEventRunOf } from "../../run-event-stream";
+
+function args(o: Partial<ParsedArgs>): ParsedArgs {
+  return { command: "run", path: ".", format: "", fix: false, watch: false, verbose: false, help: false, live: false, ...o };
+}
+
+let dir: string;
+let cwd: string;
+let out: string[];
+beforeEach(() => {
+  cwd = process.cwd();
+  vi.stubEnv("CHANT_RUN_EVENTS_DIR", "");
+  dir = realpathSync(mkdtempSync(join(tmpdir(), "run-events-cmd-")));
+  execFileSync("git", ["init", "-q", "-b", "main"], { cwd: dir });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "--allow-empty", "-m", "init"], { cwd: dir });
+  process.chdir(dir);
+  out = [];
+  vi.spyOn(process.stdout, "write").mockImplementation((s: string | Uint8Array) => (out.push(String(s)), true));
+  vi.spyOn(console, "log").mockImplementation((s: string) => void out.push(`${s}\n`));
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+  process.chdir(cwd);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+async function stream(runId: string, name = "deploy-api") {
+  const store = (await openRunEventStore(dir, runId))!;
+  return openRunEventStream(runEventRunOf({ kind: "op", name, runId }), store.write);
+}
+
+describe("chant run events", () => {
+  test("--json replays a settled run's lines and exits with its verdict", async () => {
+    const s = await stream("r-done");
+    s.emit({ type: "run-start", waves: null });
+    s.settle("failed", "boom");
+    const exit = await runOpEvents({ args: args({ extraPositional: "r-done", json: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    const events = out.join("").trim().split("\n").map((l) => JSON.parse(l));
+    expect(events.map((e) => e.type)).toEqual(["run-start", "run-settle"]);
+    expect(events[1]).toMatchObject({ status: "failed", error: "boom" });
+  });
+
+  test("--json replays a run in progress up to now and exits 0", async () => {
+    const s = await stream("r-live");
+    s.emit({ type: "run-start", waves: null });
+    s.emit({ type: "phase-start", component: null, phase: "Build" });
+    const exit = await runOpEvents({ args: args({ extraPositional: "deploy-api", json: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    expect(out.join("").trim().split("\n").map((l) => JSON.parse(l).type)).toEqual(["run-start", "phase-start"]);
+  });
+
+  test("--follow prints each event of a run in progress, then the verdict", async () => {
+    const s = await stream("r-follow");
+    s.emit({ type: "run-start", waves: null });
+    const done = runOpEvents({ args: args({ extraPositional: "r-follow", json: true, follow: true }), plugins: [], serializers: [] });
+    await new Promise((r) => setTimeout(r, 150));
+    expect(out.join("").trim().split("\n")).toHaveLength(1);
+    s.emit({ type: "phase-start", component: null, phase: "Build" });
+    s.emit({ type: "phase-settle", component: null, phase: "Build", status: "gated" });
+    s.settle("gated");
+    expect(await done).toBe(3);
+    expect(out.join("").trim().split("\n").map((l) => JSON.parse(l).type)).toEqual(["run-start", "phase-start", "phase-settle", "run-settle"]);
+  });
+
+  test("without --json each event is one line for a person", async () => {
+    const s = await stream("r-human");
+    s.emit({ type: "run-start", waves: null });
+    s.settle("ok");
+    expect(await runOpEvents({ args: args({ extraPositional: "r-human" }), plugins: [], serializers: [] })).toBe(0);
+    expect(out.join("")).toMatch(/run-start/);
+    expect(out.join("")).toMatch(/run-settle\s+ok/);
+  });
+
+  test("a run with no kept events is refused by name; no run is refused", async () => {
+    expect(await runOpEvents({ args: args({ extraPositional: "nope" }), plugins: [], serializers: [] })).toBe(1);
+    expect(await runOpEvents({ args: args({}), plugins: [], serializers: [] })).toBe(1);
+    expect(await runOpEvents({ args: args({ extraPositional: "x", on: "fountain" }), plugins: [], serializers: [] })).toBe(1);
+  });
+});

package/src/cli/handlers/run.test.ts

@@ -98,6 +98,7 @@ vi.mock("../../lifecycle/run-ledger", async (importOriginal) => {
 
 const { runOpList, runOpStatus, runOpLog, runOpSignalRenamed, runOpApprove, runOpCancel, runOp, runOpComponents } =
   await import("./run");
+const { checkRunEventLines } = await import("../../workspace/__fixtures__/run-event-check");
 
 function makeArgs(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
   return {
@@ -1554,6 +1555,35 @@ describe("runOpComponents", () => {
     vi.restoreAllMocks();
   });
 
+  test("--events-json streams the run-event stream as runComponents emits it, and ends one that never reached a component (#4041)", async () => {
+    runComponentsMock.mockImplementation(
+      async (_path: string, _selector: string, options: { onRunEvent?: (b: unknown) => void }) => {
+        options.onRunEvent?.({ type: "run-start", waves: [["svc"]] });
+        options.onRunEvent?.({ type: "run-settle", status: "ok", durationMs: null });
+        return {
+          success: true,
+          selected: ["svc"],
+          run: { order: ["svc"], waves: [["svc"]], results: [{ component: "svc", ok: true, status: "ok", records: [] }], ok: true, status: "ok" },
+        };
+      },
+    );
+    const stdoutWrite = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    expect(await runOpComponents({ args: makeArgs({ path: "svc", eventsJson: true }), plugins: [], serializers: [] })).toBe(0);
+    const events = checkRunEventLines(stdoutWrite.mock.calls.map((c) => String(c[0])));
+    expect(events[0]).toMatchObject({ type: "run-start", kind: "component", name: "svc", waves: [["svc"]] });
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "ok" });
+
+    stdoutWrite.mockClear();
+    runComponentsMock.mockReset().mockResolvedValue({ success: false, selected: [], error: "no component named svc" });
+    expect(await runOpComponents({ args: makeArgs({ path: "svc", eventsJson: true }), plugins: [], serializers: [] })).toBe(1);
+    const failed = checkRunEventLines(stdoutWrite.mock.calls.map((c) => String(c[0])));
+    expect(failed.map((e) => e.type)).toEqual(["run-start", "run-settle"]);
+    expect(failed.at(-1)).toMatchObject({ status: "failed", error: "no component named svc" });
+    vi.restoreAllMocks();
+  });
+
   test("without --progress-json, runComponents receives onProgress: undefined and nothing streams", async () => {
     runComponentsMock.mockResolvedValue({
       success: true,