@intentius/chant 0.79.0 → 0.81.0

package/src/cli/handlers/promote.ts

@@ -0,0 +1,391 @@
+/**
+ * `chant components promote --from <env> --to <env>` (#2530), `chant
+ * components rollback <env>` (#2531) and `chant components redeploy <env>`
+ * (#2604): deploy digests a release ledger already records, without a build.
+ * A promote takes them from another environment's ledger; a rollback takes an
+ * earlier release from the environment's own, and a redeploy the release it
+ * records as current. The
+ * mechanism lives in ../../components/promote.ts; these handlers read the
+ * ledger, print the plan, run it, and append the release records.
+ *
+ * Every component that deployed gets a record, even when a later component
+ * failed or stopped at a gate, so the ledger never misses a deploy that
+ * happened. Unlike an auto-recorded release, the record is what these
+ * commands are for, so a failed write is an error rather than a warning.
+ */
+
+import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { loadChantConfig, type ChantConfig } from "../../config";
+import { fetchLifecycle, getHeadCommit, pushLifecycle } from "../../lifecycle/git";
+import {
+  appendReleaseRecord,
+  readReleaseLedger,
+  resolveRunId,
+  type ReleaseRecord,
+  type ReleaseRecordInput,
+} from "../../lifecycle/release-ledger";
+import { resolveComponentTargets } from "../../components/cli-support";
+import { applyConfigDefaults } from "../../components/config-defaults";
+import { fanOutRegistry } from "../../components/fan-out-support";
+import { renderDriverHuman } from "../../components/driver-output";
+import { ndjsonProgressSink } from "../../components/run-progress";
+import {
+  parseDigestPins,
+  planPromotion,
+  planRollback,
+  planRedeploy,
+  withoutBuildSteps,
+  runPromotion,
+  promotionRecord,
+  rollbackRecord,
+  redeployRecord,
+  gateApprover,
+  type DeployRunInfo,
+  type PromotionItem,
+  type PromotionPlan,
+} from "../../components/promote";
+import type { DriverComponent } from "../../components/driver";
+import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary";
+import { approveCommand, describeGateMismatch } from "../../op/gate";
+import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
+import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
+import { GATED_EXIT_CODE } from "./run";
+import type { CommandContext } from "../registry";
+
+const PROMOTE_USAGE =
+  "chant components promote --from <env> --to <env> [--component <name> [--digest <sha256:...>] | --digest <component>=<sha256:...> ...] [--dry-run] [--json]";
+const ROLLBACK_USAGE =
+  "chant components rollback <env> --component <name> [--digest <sha256:...>] [--dry-run] [--json]";
+const REDEPLOY_USAGE =
+  "chant components redeploy <env> --component <name> [--digest <sha256:...>] [--dry-run] [--json]";
+
+type Verb = "promote" | "rollback" | "redeploy";
+
+function renderPlan(verb: Verb, plan: PromotionPlan, removed: Map<string, string[]>): void {
+  console.error(formatBold(verb === "promote" ? `promote ${plan.from} -> ${plan.to}` : `${verb} ${plan.to}`));
+  for (const item of plan.items) {
+    console.error(`  ${item.component}  ${item.digest}`);
+    console.error(`    released to ${plan.from} at ${item.source.timestamp} (run ${item.source.runId}, git ${item.source.gitSha.slice(0, 12)})`);
+    const kinds = removed.get(item.component) ?? [];
+    if (kinds.length > 0) console.error(`    not run: ${kinds.join(", ")}`);
+  }
+  for (const skipped of plan.notPromoted) {
+    console.error(`  ${skipped.component}  not promoted: ${skipped.reason}`);
+  }
+}
+
+function planJson(plan: PromotionPlan, removed: Map<string, string[]>) {
+  return {
+    from: plan.from,
+    to: plan.to,
+    items: plan.items.map((i) => ({
+      component: i.component,
+      digest: i.digest,
+      source: i.source,
+      notRun: removed.get(i.component) ?? [],
+    })),
+    notPromoted: plan.notPromoted,
+  };
+}
+
+function resolveActor(ctx: CommandContext): string | undefined {
+  return ctx.args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER;
+}
+
+/** Config, params and the declared components, or the exit code of a refusal already printed. */
+async function loadProject(ctx: CommandContext, selector: string) {
+  const { args } = ctx;
+  const projectPath = resolve(".");
+  const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
+  const paramsResolution = resolveCliBuildParams(config.buildParams, {
+    cli: parseParamFlags(args.param),
+    paramsFile: args.paramsFile,
+    verbose: args.verbose,
+  });
+  if (!paramsResolution.success) {
+    for (const message of paramsResolution.errors) console.error(message);
+    return 1;
+  }
+  const targets = await resolveComponentTargets(projectPath, selector, args.sandbox, paramsResolution.provenance);
+  if (!targets.success) {
+    console.error(formatError({ message: targets.error ?? "Could not discover components" }));
+    return 1;
+  }
+  return { projectPath, config, targets: targets.targets };
+}
+
+async function readLedger(env: string): Promise<ReleaseRecord[]> {
+  const ledger = await readReleaseLedger(env);
+  if (ledger.malformed > 0) {
+    console.error(formatWarning({ message: `${ledger.malformed} malformed line(s) in the "${env}" release ledger were skipped` }));
+  }
+  return ledger.records;
+}
+
+/**
+ * Prepare, run and record a plan. Shared by promote, rollback and redeploy,
+ * which differ only in how the plan was chosen, whether the publish step runs,
+ * and which field names the earlier release on the new record.
+ */
+async function deployPlan(
+  ctx: CommandContext,
+  verb: Verb,
+  plan: PromotionPlan,
+  project: { projectPath: string; config: ChantConfig; targets: DriverComponent[] },
+  actor: string | undefined,
+  record: (item: PromotionItem, env: string, run: DeployRunInfo) => ReleaseRecordInput,
+): Promise<number> {
+  const { args } = ctx;
+  const byName = new Map(project.targets.map((c) => [c.name, applyConfigDefaults(c, project.config)]));
+  const prepared: DriverComponent[] = [];
+  const removed = new Map<string, string[]>();
+  const refusals: string[] = [];
+  for (const item of plan.items) {
+    // A rollback and a redeploy deploy a release this environment already
+    // received, so neither runs the publish step.
+    const result = withoutBuildSteps(
+      byName.get(item.component)!,
+      verb === "promote" ? {} : { pinDigest: item.digest, verb: `a ${verb}` },
+    );
+    if ("error" in result) refusals.push(result.error);
+    else {
+      prepared.push(result.component);
+      removed.set(item.component, result.removed);
+    }
+  }
+  if (refusals.length > 0) {
+    for (const message of refusals) console.error(formatError({ message }));
+    console.error(formatError({ message: `nothing was deployed` }));
+    return 1;
+  }
+
+  // The composition deployed is this checkout's. Say so when it is not the
+  // commit the artifact was built from.
+  const head = await getHeadCommit().catch(() => undefined);
+  for (const item of plan.items) {
+    if (head && head !== item.source.gitSha) {
+      console.error(formatWarning({
+        message: `${item.component}: the artifact was built from ${item.source.gitSha.slice(0, 12)}, ` +
+          `but its deploy steps come from this checkout at ${head.slice(0, 12)}`,
+      }));
+    }
+  }
+
+  if (args.dryRun) {
+    if (args.json) console.log(JSON.stringify(planJson(plan, removed), null, 2));
+    else renderPlan(verb, plan, removed);
+    return 0;
+  }
+  if (!args.json) renderPlan(verb, plan, removed);
+
+  const seededOutputs: Record<string, Record<string, unknown>> = {};
+  for (const file of args.seedOutputs ?? []) {
+    try {
+      Object.assign(seededOutputs, JSON.parse(readFileSync(resolve(file), "utf8")));
+    } catch (err) {
+      console.error(formatError({ message: `--seed-outputs: could not read "${file}": ${err instanceof Error ? err.message : String(err)}` }));
+      return 1;
+    }
+  }
+
+  const registry = await fanOutRegistry(project.projectPath, project.config);
+  const run = await runPromotion({
+    plan,
+    components: prepared,
+    registry,
+    componentOutputs: seededOutputs,
+    ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
+  });
+  if (!args.json) renderDriverHuman(run);
+
+  // Record every component that deployed, whatever happened to the rest: a
+  // component that reached the environment and is missing from its ledger
+  // would be exactly the unrecorded deploy the ledger exists to rule out.
+  const deployed = plan.items.filter((item) => run.results.some((r) => r.component === item.component && r.status === "ok"));
+  const { runId, runOrigin } = resolveRunId(args.runId);
+  const timestamp = new Date().toISOString();
+  const recorded: ReleaseRecord[] = [];
+  let recordError: string | undefined;
+  if (deployed.length > 0) {
+    try {
+      for (const item of deployed) {
+        const approver = gateApprover(run.results.find((r) => r.component === item.component));
+        const { record: written } = await appendReleaseRecord(
+          record(item, plan.to, { runId, ...(runOrigin ? { runOrigin } : {}), actor: actor!, timestamp, ...(approver ? { approver } : {}) }),
+        );
+        recorded.push(written);
+      }
+      await pushLifecycle();
+    } catch (err) {
+      recordError = err instanceof Error ? err.message : String(err);
+    }
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify({ ...planJson(plan, removed), run, recorded }, null, 2));
+  } else {
+    for (const r of recorded) {
+      console.error(formatSuccess(
+        verb === "promote"
+          ? `Promoted ${formatBold(r.component)} ${plan.from} -> ${plan.to}: ${r.digest}`
+          : verb === "rollback"
+            ? `Rolled back ${formatBold(r.component)} in ${plan.to} to ${r.digest}`
+            : `Redeployed ${formatBold(r.component)} in ${plan.to} at ${r.digest}`,
+      ));
+    }
+  }
+
+  if (recordError !== undefined) {
+    console.error(formatError({
+      message: `deployed to "${plan.to}", but the release record was not written: ${recordError}`,
+      hint: `Pull the chant/lifecycle branch and check \`chant components status ${plan.to}\` before running this again.`,
+    }));
+    return 1;
+  }
+
+  if (run.status === "gated" && run.gate) {
+    const pending = run.gate;
+    console.error(formatWarning({ message: `component "${run.gatedComponent}" is gated on "${pending.gate}" — pending approval` }));
+    // #2574: an approval stands, but for another environment, plan or none.
+    if (run.gateMismatch) {
+      console.error(formatWarning({ message: describeGateMismatch(pending.op, pending.gate, run.gateMismatch) }));
+    }
+    console.error(formatInfo(`approve : ${approveCommand(pending.op, pending.gate, pending.environment)}`));
+    console.error(formatInfo(`then run the same ${verb} again`));
+    writeGatedRunSummary({
+      op: pending.op,
+      gate: pending.gate,
+      ...(pending.description ? { description: pending.description } : {}),
+      expiresAt: pending.expiresAt,
+      ...(pending.url ? { url: pending.url } : {}),
+      ...(pending.planDigest ? { planDigest: pending.planDigest } : {}),
+      ...(await summaryLedgerPrefix()),
+      ...(pending.environment ? { environment: pending.environment } : {}),
+    });
+    return GATED_EXIT_CODE;
+  }
+
+  if (run.status !== "ok") {
+    console.error(formatError({ message: `${verb} failed at "${run.failedComponent ?? "unknown"}"` }));
+    return 1;
+  }
+  return 0;
+}
+
+/** Refuse before anything deploys when nobody can be named on the record. */
+function actorOrRefuse(ctx: CommandContext): { actor: string | undefined } | number {
+  const actor = resolveActor(ctx);
+  if (!actor && !ctx.args.dryRun) {
+    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;
+  }
+  return { actor };
+}
+
+export async function runComponentsPromote(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const from = args.migrateFrom;
+  const to = args.migrateTo;
+  if (!from || !to) {
+    console.error(formatError({ message: "--from <env> and --to <env> are required", hint: PROMOTE_USAGE }));
+    return 1;
+  }
+  const who = actorOrRefuse(ctx);
+  if (typeof who === "number") return who;
+
+  const project = await loadProject(ctx, args.component ?? "all");
+  if (typeof project === "number") return project;
+
+  // Without --component, each --digest is <component>=<digest> (#2602): a
+  // generated promote job pins every component to the release its own
+  // pipeline run recorded, rather than whatever is latest in --from.
+  const digests = args.digests ?? (args.digest ? [args.digest] : []);
+  let pins: Record<string, string> | undefined;
+  if (!args.component && digests.length > 0) {
+    const parsed = parseDigestPins(digests);
+    if ("error" in parsed) {
+      console.error(formatError({ message: parsed.error, hint: PROMOTE_USAGE }));
+      return 1;
+    }
+    pins = parsed.pins;
+  } else if (args.component && digests.length > 1) {
+    console.error(formatError({ message: "--component takes one --digest", hint: PROMOTE_USAGE }));
+    return 1;
+  }
+
+  await fetchLifecycle().catch(() => false);
+  const plan = planPromotion({
+    from,
+    to,
+    sourceRecords: await readLedger(from),
+    declared: project.targets.map((c) => c.name),
+    ...(args.component ? { component: args.component } : {}),
+    ...(args.component && args.digest ? { digest: args.digest } : {}),
+    ...(pins ? { pins } : {}),
+  });
+  if ("error" in plan) {
+    console.error(formatError({ message: plan.error, hint: PROMOTE_USAGE }));
+    return 1;
+  }
+  return deployPlan(ctx, "promote", plan, project, who.actor, promotionRecord);
+}
+
+export async function runComponentsRollback(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const env = args.extraPositional;
+  if (!env || !args.component) {
+    console.error(formatError({ message: "an environment and --component <name> are required", hint: ROLLBACK_USAGE }));
+    return 1;
+  }
+  const who = actorOrRefuse(ctx);
+  if (typeof who === "number") return who;
+
+  const project = await loadProject(ctx, args.component);
+  if (typeof project === "number") return project;
+
+  await fetchLifecycle().catch(() => false);
+  const plan = planRollback({
+    env,
+    records: await readLedger(env),
+    declared: project.targets.map((c) => c.name),
+    component: args.component,
+    ...(args.digest ? { digest: args.digest } : {}),
+  });
+  if ("error" in plan) {
+    console.error(formatError({ message: plan.error, hint: ROLLBACK_USAGE }));
+    return 1;
+  }
+  return deployPlan(ctx, "rollback", plan, project, who.actor, rollbackRecord);
+}
+
+export async function runComponentsRedeploy(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const env = args.extraPositional;
+  if (!env || !args.component) {
+    console.error(formatError({ message: "an environment and --component <name> are required", hint: REDEPLOY_USAGE }));
+    return 1;
+  }
+  const who = actorOrRefuse(ctx);
+  if (typeof who === "number") return who;
+
+  const project = await loadProject(ctx, args.component);
+  if (typeof project === "number") return project;
+
+  await fetchLifecycle().catch(() => false);
+  const plan = planRedeploy({
+    env,
+    records: await readLedger(env),
+    declared: project.targets.map((c) => c.name),
+    component: args.component,
+    ...(args.digest ? { digest: args.digest } : {}),
+  });
+  if ("error" in plan) {
+    console.error(formatError({ message: plan.error, hint: REDEPLOY_USAGE }));
+    return 1;
+  }
+  return deployPlan(ctx, "redeploy", plan, project, who.actor, redeployRecord);
+}

package/src/cli/handlers/run-generate-member.test.ts

@@ -0,0 +1,83 @@
+/**
+ * `chant run --generate` inside a workspace member (#2542). Discovery is
+ * stubbed; the lexicon plugins are the real ones.
+ */
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import type { ParsedArgs } from "../registry";
+import type { OpConfig } from "../../op/types";
+import { twoMemberWorkspace } from "../../workspace/__fixtures__/two-member-workspace";
+
+const discovered = new Map<string, { config: Partial<OpConfig>; filePath: string; exportName: string }>();
+vi.mock("../../op/discover", () => ({
+  discoverOps: async () => ({ ops: discovered, errors: [] }),
+}));
+
+const { runOp } = await import("./run");
+const { generateOpsPipeline } = await import("../../op/generate-pipeline");
+const { parseArgs } = await import("../main");
+
+function ctx(argv: string[]) {
+  return { args: parseArgs(argv) as ParsedArgs, plugins: [], serializers: [] };
+}
+
+let repo: string;
+let cwd: string;
+let logs: string[];
+beforeEach(() => {
+  repo = twoMemberWorkspace();
+  cwd = process.cwd();
+  discovered.clear();
+  discovered.set("nightly-audit", {
+    config: { name: "nightly-audit", phases: [], schedule: { cron: "0 6 * * *" } } as Partial<OpConfig>,
+    filePath: "nightly-audit.op.ts",
+    exportName: "default",
+  });
+  logs = [];
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(console, "log").mockImplementation((s: string) => {
+    logs.push(s);
+  });
+});
+afterEach(() => {
+  process.chdir(cwd);
+  vi.restoreAllMocks();
+  rmSync(repo, { recursive: true, force: true });
+});
+
+describe("chant run --generate in a workspace member", () => {
+  test("github: the file is named after the member, at the repository root, and recorded", async () => {
+    process.chdir(join(repo, "services/api"));
+    expect(await runOp(ctx(["run", "--generate", "github"]))).toBe(0);
+
+    expect(readdirSync(join(repo, ".github/workflows"))).toEqual(["api-nightly-audit.yml"]);
+    expect(existsSync(join(repo, "services/api/.github"))).toBe(false);
+    const member = { name: "api", dir: "services/api", fileDir: ".github/workflows" };
+    const direct = await generateOpsPipeline([{ name: "nightly-audit" }], "github", { member });
+    const text = readFileSync(join(repo, ".github/workflows/api-nightly-audit.yml"), "utf-8");
+    expect(text).toBe(
+      "# Generated by chant — do not edit directly. Regenerate with: chant run --generate github (in the member's directory)\n" + direct.files![0].yaml,
+    );
+    const record = JSON.parse(readFileSync(join(repo, "services/api/.chant/generated.json"), "utf-8"));
+    expect(record.files).toEqual([{ path: ".github/workflows/api-nightly-audit.yml", command: "chant run --generate github" }]);
+  });
+
+  test("gitlab: the member's file goes in .gitlab/ci", async () => {
+    process.chdir(join(repo, "apps/web"));
+    expect(await runOp(ctx(["run", "--generate", "gitlab"]))).toBe(0);
+    const text = readFileSync(join(repo, ".gitlab/ci/web-ops.gitlab-ci.yml"), "utf-8");
+    expect(text).toContain("web-nightly-audit:");
+    expect(text).toContain("cd apps/web");
+  });
+
+  test("--format json names the member and writes nothing", async () => {
+    process.chdir(join(repo, "services/api"));
+    expect(await runOp(ctx(["run", "--generate", "forgejo", "--format", "json"]))).toBe(0);
+    const out = JSON.parse(logs.join("\n"));
+    expect(out.member).toBe("api");
+    expect(out.files.map((f: { path: string }) => f.path)).toEqual([".forgejo/workflows/api-nightly-audit.yml"]);
+    expect(existsSync(join(repo, ".forgejo"))).toBe(false);
+  });
+});

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

@@ -0,0 +1,158 @@
+/**
+ * `chant run --generate <provider>` (#2533). Discovery is stubbed so the
+ * scheduled Ops are fixed; the github, gitlab and forgejo lexicon plugins are
+ * the real ones, so "identical to calling `generateOpsPipeline` directly" is
+ * checked against the real generators.
+ */
+
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ParsedArgs } from "../registry";
+import type { OpConfig } from "../../op/types";
+
+const discovered = new Map<string, { config: Partial<OpConfig>; filePath: string; exportName: string }>();
+
+vi.mock("../../op/discover", () => ({
+  discoverOps: async () => ({ ops: discovered, errors: [] }),
+}));
+
+const { runOp } = await import("./run");
+const { generateOpsPipeline } = await import("../../op/generate-pipeline");
+const { GENERATED_MARKER } = await import("../../discovery/files");
+const { parseArgs } = await import("../main");
+
+function ctx(argv: string[]) {
+  const args = parseArgs(argv) as ParsedArgs;
+  return { args, plugins: [], serializers: [] };
+}
+
+let dir: string;
+let errSpy: ReturnType<typeof vi.spyOn>;
+let logSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "chant-run-generate-"));
+  discovered.clear();
+  discovered.set("nightly-audit", {
+    config: { name: "nightly-audit", phases: [], schedule: { cron: "0 6 * * *" } } as Partial<OpConfig>,
+    filePath: "nightly-audit.op.ts",
+    exportName: "default",
+  });
+  discovered.set("weekly-report", {
+    config: { name: "weekly-report", phases: [], schedule: { cron: "0 7 * * 1" } } as Partial<OpConfig>,
+    filePath: "weekly-report.op.ts",
+    exportName: "default",
+  });
+  discovered.set("deploy", {
+    config: { name: "deploy", phases: [] } as Partial<OpConfig>,
+    filePath: "deploy.op.ts",
+    exportName: "default",
+  });
+  errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  errSpy.mockRestore();
+  logSpy.mockRestore();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("chant run --generate <provider>", () => {
+  test.each(["github", "gitlab", "forgejo"])(
+    "%s: each file is the generator's own output under one marker line",
+    async (provider) => {
+      const out = join(dir, provider);
+      expect(await runOp(ctx(["run", "--generate", provider, "--output", out]))).toBe(0);
+
+      const direct = await generateOpsPipeline([{ name: "nightly-audit" }, { name: "weekly-report" }], provider);
+      expect(direct.success).toBe(true);
+      const header = `# ${GENERATED_MARKER}. Regenerate with: chant run --generate ${provider}\n`;
+
+      expect(readdirSync(out).sort()).toEqual(direct.files!.map((f) => f.name).sort());
+      for (const file of direct.files!) {
+        expect(readFileSync(join(out, file.name), "utf-8")).toBe(header + file.yaml);
+      }
+    },
+  );
+
+  test("github and forgejo get one file per scheduled Op; an Op with no schedule is left out", async () => {
+    for (const provider of ["github", "forgejo"]) {
+      const out = join(dir, provider);
+      expect(await runOp(ctx(["run", "--generate", provider, "--output", out]))).toBe(0);
+      expect(readdirSync(out).sort()).toEqual(["nightly-audit.yml", "weekly-report.yml"]);
+    }
+  });
+
+  test("each github (#2580) and forgejo (#2601) workflow is named after its Op", async () => {
+    for (const provider of ["github", "forgejo"]) {
+      expect(await runOp(ctx(["run", "--generate", provider, "--output", join(dir, provider)]))).toBe(0);
+      const header = `# ${GENERATED_MARKER}. Regenerate with: chant run --generate ${provider}\n`;
+      for (const op of ["nightly-audit", "weekly-report"]) {
+        const written = readFileSync(join(dir, provider, `${op}.yml`), "utf-8");
+        expect(written.startsWith(`${header}name: ${op}\n\non:\n`)).toBe(true);
+      }
+    }
+  });
+
+  test("--spec passes its ops and options to the generator unchanged", async () => {
+    const specFile = join(dir, "ops.json");
+    const spec = {
+      ops: [
+        { name: "deploy", trigger: { kind: "pull_request", branches: ["main"] }, findingMode: "comment" },
+        { name: "nightly-audit" },
+      ],
+      options: { opsStage: "chant" },
+    };
+    writeFileSync(specFile, JSON.stringify(spec));
+    const out = join(dir, "gitlab");
+    expect(await runOp(ctx(["run", "--generate", "gitlab", "--spec", specFile, "--output", out]))).toBe(0);
+
+    const direct = await generateOpsPipeline(spec.ops as never, "gitlab", spec.options);
+    expect(direct.files!.map((f) => f.name)).toEqual(["chant.gitlab-ci.yml"]);
+    const written = readFileSync(join(out, "chant.gitlab-ci.yml"), "utf-8");
+    expect(written).toBe(
+      `# ${GENERATED_MARKER}. Regenerate with: chant run --generate gitlab --spec ${specFile}\n` + direct.files![0].yaml,
+    );
+    expect(written).toContain('$CI_PIPELINE_SOURCE == "merge_request_event"');
+  });
+
+  test("--format json prints the files and jobs and writes nothing", async () => {
+    const out = join(dir, "none");
+    expect(await runOp(ctx(["run", "--generate", "github", "--output", out, "--format", "json"]))).toBe(0);
+    const printed = JSON.parse(String(logSpy.mock.calls[0][0]));
+    expect(printed.files.map((f: { path: string }) => f.path)).toEqual([
+      join(out, "nightly-audit.yml"),
+      join(out, "weekly-report.yml"),
+    ]);
+    expect(printed.files[0].content.startsWith(`# ${GENERATED_MARKER}`)).toBe(true);
+    expect(printed.jobs).toHaveLength(2);
+    expect(() => readdirSync(out)).toThrow();
+  });
+
+  test("with no scheduled Op and no --spec, it fails and says what to do", async () => {
+    discovered.delete("nightly-audit");
+    discovered.delete("weekly-report");
+    expect(await runOp(ctx(["run", "--generate", "github", "--output", dir]))).toBe(1);
+    expect(String(errSpy.mock.calls.flat().join("\n"))).toMatch(/No Op declares a schedule/);
+  });
+
+  test("a provider with no Op generator fails by name", async () => {
+    expect(await runOp(ctx(["run", "--generate", "aws", "--output", dir]))).toBe(1);
+    expect(String(errSpy.mock.calls.flat().join("\n"))).toMatch(/does not support Op generate mode/);
+  });
+
+  test("a --spec entry without a name is refused", async () => {
+    const specFile = join(dir, "bad.json");
+    writeFileSync(specFile, JSON.stringify([{ trigger: { kind: "push" } }]));
+    expect(await runOp(ctx(["run", "--generate", "github", "--spec", specFile, "--output", dir]))).toBe(1);
+    expect(String(errSpy.mock.calls.flat().join("\n"))).toMatch(/entry 0 has no "name"/);
+  });
+
+  test("--components with --generate on run is refused", async () => {
+    expect(await runOp(ctx(["run", "--components", "--generate", "github"]))).toBe(1);
+    expect(String(errSpy.mock.calls.flat().join("\n"))).toMatch(/build --components --generate/);
+  });
+});