@intentius/chant 0.78.0 → 0.80.0

package/src/cli/handlers/promote.ts

@@ -0,0 +1,325 @@
+/**
+ * `chant components promote --from <env> --to <env>` (#2530) and `chant
+ * components rollback <env>` (#2531): 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. 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 {
+  planPromotion,
+  planRollback,
+  withoutBuildSteps,
+  runPromotion,
+  promotionRecord,
+  rollbackRecord,
+  gateApprover,
+  type DeployRunInfo,
+  type PromotionItem,
+  type PromotionPlan,
+} from "../../components/promote";
+import type { DriverComponent } from "../../components/driver";
+import { writeGatedRunSummary } from "../../op/gate-summary";
+import { approveCommand } 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:...>]] [--dry-run] [--json]";
+const ROLLBACK_USAGE =
+  "chant components rollback <env> --component <name> [--digest <sha256:...>] [--dry-run] [--json]";
+
+type Verb = "promote" | "rollback";
+
+function renderPlan(verb: Verb, plan: PromotionPlan, removed: Map<string, string[]>): void {
+  console.error(formatBold(verb === "promote" ? `promote ${plan.from} -> ${plan.to}` : `rollback ${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 and rollback, 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) {
+    const result = withoutBuildSteps(byName.get(item.component)!, verb === "rollback" ? { pinDigest: item.digest } : {});
+    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}`
+          : `Rolled back ${formatBold(r.component)} in ${plan.to} to ${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` }));
+    console.error(formatInfo(`approve : ${approveCommand(pending.op, pending.gate)}`));
+    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 } : {}),
+    });
+    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;
+
+  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.digest ? { digest: args.digest } : {}),
+  });
+  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);
+}

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

@@ -0,0 +1,160 @@
+/**
+ * `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 workflow is named after its Op (#2580); forgejo workflows carry no name", 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 github\n`;
+    for (const op of ["nightly-audit", "weekly-report"]) {
+      const github = readFileSync(join(dir, "github", `${op}.yml`), "utf-8");
+      expect(github.startsWith(`${header}name: ${op}\n\non:\n`)).toBe(true);
+      const forgejo = readFileSync(join(dir, "forgejo", `${op}.yml`), "utf-8");
+      expect(forgejo).not.toMatch(/^name:/m);
+    }
+  });
+
+  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/);
+  });
+});

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

@@ -0,0 +1,133 @@
+/**
+ * `chant run --generate <provider>` (#2533): the CLI for `generateOpsPipeline`
+ * (../../op/generate-pipeline.ts), the Op counterpart to `chant build
+ * --components --generate <lexicon>`.
+ *
+ * The generator is a library function with no caller of its own. A pipeline
+ * committed to a repository needs a named command that regenerates it, so a
+ * drift check (#2524 D14) can rerun that command and compare. This handler is
+ * that command and adds nothing to the generator's output beyond one header
+ * line: every file it writes is the generator's own `yaml`, byte for byte,
+ * under a first line carrying {@link GENERATED_MARKER} and the command that
+ * produced it.
+ *
+ * Where the specs come from:
+ *
+ *  - by default, every discovered Op that declares its own `schedule`, as a
+ *    bare `{ name }` spec. `generateOpsPipeline` fills the cron in from the Op
+ *    (`withOpSchedules`), so the result is exactly what a direct call with
+ *    those names returns;
+ *  - with `--spec <file>`, a JSON file holding either a `ScheduledOpSpec[]`
+ *    or `{ ops, options }`, for Ops triggered by a pull request or a push, a
+ *    finding mode, setup steps, or generator options. The file is passed to
+ *    the generator unchanged.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { discoverOps } from "../../op/discover";
+import { generateOpsPipeline } from "../../op/generate-pipeline";
+import { GENERATED_MARKER } from "../../discovery/files";
+import type { ComponentPipelineOptions, ScheduledOpSpec } from "../../lexicon";
+import { formatBold, formatError, formatSuccess } from "../format";
+import type { CommandContext } from "../registry";
+
+/** Where each forge reads its pipeline files from, relative to the repository root. `--output` overrides it. */
+export const DEFAULT_OP_PIPELINE_DIRS: Record<string, string> = {
+  github: ".github/workflows",
+  forgejo: ".forgejo/workflows",
+  gitlab: ".",
+};
+
+/** The first line of every file this command writes. */
+export function opPipelineHeader(provider: string, specFile?: string): string {
+  const command = `chant run --generate ${provider}${specFile ? ` --spec ${specFile}` : ""}`;
+  return `# ${GENERATED_MARKER}. Regenerate with: ${command}\n`;
+}
+
+interface SpecFile {
+  ops: ScheduledOpSpec[];
+  options?: ComponentPipelineOptions;
+}
+
+/** Read `--spec`: a `ScheduledOpSpec[]`, or `{ ops, options }`. Throws with the file named on anything else. */
+export function readOpSpecFile(path: string): SpecFile {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf-8"));
+  } catch (err) {
+    throw new Error(`--spec ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const shape = "an array of Op specs, or { \"ops\": [...], \"options\": {...} }";
+  const ops = Array.isArray(parsed) ? parsed : (parsed as { ops?: unknown } | null)?.ops;
+  if (!Array.isArray(ops)) throw new Error(`--spec ${path} must hold ${shape}`);
+  for (const [i, spec] of ops.entries()) {
+    if (typeof (spec as { name?: unknown })?.name !== "string") {
+      throw new Error(`--spec ${path}: entry ${i} has no "name". Each entry names the Op it generates a pipeline for.`);
+    }
+  }
+  const options = Array.isArray(parsed) ? undefined : (parsed as { options?: ComponentPipelineOptions }).options;
+  return { ops: ops as ScheduledOpSpec[], ...(options ? { options } : {}) };
+}
+
+export async function runOpGenerate(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const provider = args.generate as string;
+  const specPath = args.opsSpec;
+
+  let ops: ScheduledOpSpec[];
+  let options: ComponentPipelineOptions | undefined;
+  if (specPath) {
+    try {
+      ({ ops, options } = readOpSpecFile(resolve(specPath)));
+    } catch (err) {
+      console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+      return 1;
+    }
+  } else {
+    const discovered = await discoverOps();
+    if (discovered.errors.length > 0) {
+      for (const e of discovered.errors) console.error(formatError({ message: e }));
+      return 1;
+    }
+    ops = [...discovered.ops.entries()]
+      .filter(([, op]) => op.config.schedule)
+      .map(([name]) => name)
+      .sort()
+      .map((name) => ({ name }));
+    if (ops.length === 0) {
+      console.error(formatError({
+        message: "No Op declares a schedule, so there is nothing to generate",
+        hint: "Give an Op a `schedule`, or pass --spec <file.json> naming the Ops and their triggers.",
+      }));
+      return 1;
+    }
+  }
+
+  const result = await generateOpsPipeline(ops, provider, options);
+  if (!result.success) {
+    console.error(formatError({ message: result.error ?? "Failed to generate Op pipelines" }));
+    return 1;
+  }
+
+  const header = opPipelineHeader(provider, specPath);
+  const outDir = args.output ?? DEFAULT_OP_PIPELINE_DIRS[provider] ?? ".";
+  const files = (result.files ?? []).map((f) => ({
+    name: f.name,
+    path: join(outDir, f.name),
+    content: header + f.yaml,
+  }));
+
+  if (args.format === "json") {
+    console.log(JSON.stringify({ files, jobs: result.jobs ?? [] }, null, 2));
+    return 0;
+  }
+
+  for (const file of files) {
+    const target = resolve(file.path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, file.content);
+    console.error(formatSuccess(`wrote ${formatBold(file.path)}`));
+  }
+  return 0;
+}

package/src/cli/handlers/run.ts

@@ -1,3 +1,4 @@
+import { lexiconNames } from "../../lexicon-module";
 import { resolve, dirname } from "node:path";
 import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
 import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
@@ -20,6 +21,7 @@ import { ndjsonProgressSink } from "../../components/run-progress";
 import { maybeRecordAutoRelease } from "../../components/auto-release";
 import { maybePersistBuildManifest } from "../../components/manifest-persistence";
 import type { DriverComponentResult } from "../../components/driver";
+import { runOpGenerate } from "./run-generate";
 
 /**
  * The exit code a run that stopped at an unapproved gate uses (#2119).
@@ -124,7 +126,7 @@ async function resolveOpRuntime(ctx: CommandContext): Promise<OpRuntimeProvider
   // long wait to be told a name is wrong.
   let configured: string[] = [];
   try {
-    configured = (await loadChantConfig(resolve("."))).config.lexicons ?? [];
+    configured = lexiconNames((await loadChantConfig(resolve("."))).config.lexicons ?? []);
   } catch {
     // No/unreadable chant.config.ts — the error below says so by listing nothing.
   }
@@ -524,6 +526,16 @@ function refusesPolicyGateUnderSandbox(ctx: CommandContext, config: OpConfig, op
 }
 
 export async function runOp(ctx: CommandContext): Promise<number> {
+  if (ctx.args.generate) {
+    if (ctx.args.components) {
+      console.error(formatError({
+        message: "`chant run --components --generate` is not a command",
+        hint: "Generate a component pipeline with `chant build --components --generate <lexicon>`, or Op pipelines with `chant run --generate <provider>`.",
+      }));
+      return 1;
+    }
+    return runOpGenerate(ctx);
+  }
   if (ctx.args.components && ctx.args.report) {
     console.error(formatError({
       message: "--report is not supported with --components",