@intentius/chant 0.79.0 → 0.80.0

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",

package/src/cli/main.test.ts

@@ -1,6 +1,8 @@
 import { describe, test, expect } from "vitest";
 import { EventEmitter } from "node:events";
-import { parseArgs, waitForStreamDrain } from "./main";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { commandRegistry, parseArgs, waitForStreamDrain } from "./main";
 import { resolveCommand, type CommandDef, type ParsedArgs } from "./registry";
 
 describe("parseArgs", () => {
@@ -298,6 +300,12 @@ describe("parseArgs", () => {
 
   // ── --no-release-record (#597) ───────────────────────────────────────────
 
+  test("--promote-to <env> sets promoteTo, and a missing value is refused (#2575)", () => {
+    expect(parseArgs(["build", "--components", "--generate", "github", "--promote-to", "prod"]).promoteTo).toBe("prod");
+    expect(() => parseArgs(["build", "--components", "--generate", "github", "--promote-to"])).toThrow(/--promote-to needs an environment/);
+    expect(() => parseArgs(["build", "--promote-to", "--env", "x"])).toThrow(/--promote-to needs an environment/);
+  });
+
   test("parses --no-release-record for run --components", () => {
     const result = parseArgs(["run", "--components", "search-service", "--env", "staging", "--no-release-record"]);
     expect(result.components).toBe(true);
@@ -633,6 +641,30 @@ describe("parseArgs — run flags", () => {
   });
 });
 
+describe("workspace records (#2546)", () => {
+  test("parses --kind, --current, --at and --json", () => {
+    const args = parseArgs(["workspace", "records", "--kind", "docs/k.kind.mjs", "--current", "--at", "HEAD~1", "--json"]);
+    expect(args).toMatchObject({ command: "workspace", path: "records", kind: "docs/k.kind.mjs", current: true, at: "HEAD~1", json: true });
+    expect(parseArgs(["workspace", "records", "--kind=docs/k.kind.mjs"]).kind).toBe("docs/k.kind.mjs");
+    expect(parseArgs(["workspace", "records"]).current).toBeUndefined();
+    expect(() => parseArgs(["workspace", "records", "--kind"])).toThrow(/--kind needs a kind file/);
+    expect(() => parseArgs(["workspace", "records", "--kind", "--json"])).toThrow(/--kind needs a kind file/);
+  });
+
+  test("resolves to the records command, and anything else under workspace to its fallback", () => {
+    expect(resolveCommand(parseArgs(["workspace", "records", "--kind", "k.mjs"]), commandRegistry)?.def.name).toBe("workspace records");
+    expect(resolveCommand(parseArgs(["workspace", "ls"]), commandRegistry)?.def.name).toBe("workspace");
+  });
+
+  // #2525 rule 5: the workspace code loads only when a workspace command runs.
+  // The level-0 goldens catch it at run time; this catches it in review.
+  test("main.ts never imports workspace code statically", () => {
+    const source = readFileSync(join(import.meta.dirname, "main.ts"), "utf-8");
+    expect(source).not.toMatch(/^import[^;]*from\s+["'][^"']*workspace/m);
+    expect(source).toMatch(/await import\("\.\.\/workspace\/records-cli"\)/);
+  });
+});
+
 describe("waitForStreamDrain", () => {
   // Minimal writable stub — just the surface waitForStreamDrain reads.
   function fakeStream(len: number): NodeJS.WriteStream & { writableLength: number } {

package/src/cli/main.ts

@@ -27,6 +27,7 @@ import { runCarveStatus } from "./handlers/carve-status";
 import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleTeardown, runLifecycleWhoami, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runComponentsStatus, runComponentsReleaseRecord, runComponentsExport, runComponentsUnknown } from "./handlers/components";
 import { runComponentsFanOut } from "./handlers/fan-out";
+import { runComponentsPromote, runComponentsRollback } from "./handlers/promote";
 import { runScenarioCheck, runScenarioUnknown } from "./handlers/scenario";
 import { runGraph } from "./handlers/graph";
 import { runExplain } from "./handlers/explain";
@@ -93,6 +94,7 @@ const BOOLEAN_FLAGS = new Set([
   "--fail-on-drift",
   "--durable-requests",
   "--skip-mcp",
+  "--current",
 ]);
 
 /**
@@ -205,8 +207,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (v !== "source" && v !== "live") throw new Error(`--overlay-anchor must be 'source' or 'live', got '${v}'`);
       result.overlayAnchor = v;
     } else if (arg === "--from") {
-      // Shared by `migrate --from <lexicon>` and `import --from <env>`; the
-      // two commands never run together, so one field carries both.
+      // Shared by `migrate --from <lexicon>`, `import --from <env>` and
+      // `components promote --from <env>`; the commands never run together,
+      // so one field carries all three.
       result.migrateFrom = args[++i];
     } else if (arg === "--kustomize") {
       // `chant import --kustomize <dir>` (#1548): render the overlay, import
@@ -265,6 +268,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.src = args[++i];
     } else if (arg === "--env") {
       result.env = args[++i];
+    } else if (arg === "--promote-to") {
+      result.promoteTo = args[++i];
+      if (!result.promoteTo || result.promoteTo.startsWith("-")) throw new Error("--promote-to needs an environment: --promote-to <env>");
     } else if (arg === "--tier") {
       result.tier = args[++i];
     } else if (arg === "--agents") {
@@ -277,6 +283,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.runtime = args[++i];
     } else if (arg === "--fail-on") {
       result.failOn = args[++i];
+    } else if (arg === "--max-files") {
+      // Validated by the audit handler, like `--limit` below.
+      result.maxFiles = Number(args[++i]);
     } else if (arg === "--theme") {
       result.theme = args[++i];
     } else if (arg === "--stacks") {
@@ -285,6 +294,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.components = true;
     } else if (arg === "--generate") {
       result.generate = args[++i];
+    } else if (arg === "--spec") {
+      result.opsSpec = args[++i];
     } else if (arg === "--dump-outputs") {
       result.dumpOutputs = args[++i];
     } else if (arg === "--seed-outputs") {
@@ -342,6 +353,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.deep = true;
     } else if (arg === "--at") {
       result.at = args[++i];
+    } else if (arg === "--kind") {
+      // `chant workspace records --kind <kind file>` (#2546)
+      result.kind = args[++i];
+      if (!result.kind || result.kind.startsWith("-")) throw new Error("--kind needs a kind file: --kind <path>");
+    } else if (arg === "--current") {
+      result.current = true;
     } else if (arg === "--ambient") {
       result.ambient = true;
     } else if (arg === "--check-live") {
@@ -491,10 +508,11 @@ Commands:
   init                  Initialize a new chant project
   init lexicon <name>   Scaffold a new lexicon plugin project
   build                 Build infrastructure from specification files
-                        (--components --generate gitlab: generate mode (#563) —
-                         synthesize a thin .gitlab-ci.yml that triggers each
-                         discovered component's own deploy in wave order,
-                         instead of a normal lexicon build)
+                        (--components --generate github|gitlab|forgejo:
+                         generate mode (#563), which synthesizes a thin CI
+                         pipeline that triggers each discovered component's
+                         own deploy in wave order, instead of a normal
+                         lexicon build)
   lint                  Check specifications for issues
   list                  List discovered entities
   describe              Show the effective config for one component
@@ -509,7 +527,8 @@ Commands:
   audit [path|url]      Audit a repo's CI YAML for security issues
                         (--format stylish|json|sarif|markdown|html, -o <file>,
                          --tier merge-worthy|all, --fail-on merge-worthy|warning|error|none,
-                         --template <file> / --theme <file> for the html report)
+                         --template <file> / --theme <file> for the html report,
+                         --max-files <n> to walk more than 1000 files)
                         --agents audits this machine's agent configuration —
                         instruction files, MCP servers, skills, plugins,
                         permissions — instead of a repository
@@ -556,6 +575,11 @@ Ops:
   run approve <op> <gate>  Record a gate's resolution and wake the runtime
   run cancel <name>     Cancel the active run (requires --force)
   run log <name>        Show run history for an Op
+  run --generate <provider>  Write one CI pipeline file per scheduled Op for
+                        github, gitlab or forgejo (#2533), from every Op that
+                        declares a schedule or from --spec <file.json>.
+                        Files go to the forge's own directory unless
+                        --output <dir>; --format json prints them instead
   run --components <name|all>  Run discovered Component(s) through the interpret
                         driver on the local executor (--env <env>; #585).
                         On success, auto-emits a release-ledger record per
@@ -615,6 +639,13 @@ Ops:
                         predicts the account. The level reaches the engine
                         verbatim; without the flag nothing is asked (#2377)
 
+Workspace (first-test slice, #2546):
+  workspace records --kind <kind file> [--current] [--at <rev>] [--json]
+                        Read the records a record kind locates, validated
+                        against its schema, with reason codes for invalid
+                        ones. --current leaves out superseded records; --at
+                        reads a commit's git objects. Needs no workspace file
+
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch
                             --deep: also record each resource's property tree,
@@ -670,6 +701,15 @@ Component release ledger + status:
                             [--digest <manifestDigest>] -o <dir> [--json]);
                             copies every image/template/asset/sbom entry
                             byte-for-byte plus a self-describing manifest.json
+  components promote        Deploy the digests one environment's release
+                            ledger records to another, without a build
+                            (--from <env> --to <env> [--component <name>
+                             [--digest <sha256:...>]]; --dry-run prints the
+                             plan; the target's gates still apply)
+  components rollback <env> Redeploy an earlier release of an environment
+                            from its recorded digest (--component <name>
+                            [--digest <sha256:...>]; defaults to the release
+                            before the current one; --dry-run prints the plan)
 
 Lexicon development:
   dev generate          Generate lexicon artifacts (+ validate + coverage)
@@ -744,9 +784,14 @@ Options:
   --use-composites      Rewrite to composite calls when patterns match (migrate)
   --components          Target discovered Component declarations instead of
                         lexicon resources (list, describe, graph, build, run)
-  --generate <lexicon>  Generate mode (build --components only): synthesize CI
-                        YAML for <lexicon> instead of running a normal build.
-                        Only "gitlab" is implemented for v1.
+  --generate <lexicon>  Generate mode: synthesize CI YAML for <lexicon> (github,
+                        gitlab or forgejo) instead of running. build
+                        --components: one pipeline for the components; run:
+                        one pipeline file per scheduled Op
+  --spec <file>         (run --generate) JSON Op specs: an array, or
+                        { ops, options }
+  --promote-to <env>    (build --components --generate) Add a job that
+                        promotes the deployed releases to <env>
   --no-release-record   Skip auto-emitting a release-ledger record after a
                         successful \`run --components\` deploy (default: on;
                         also settable via chant.config.ts's
@@ -778,18 +823,18 @@ Options:
                         project source; network egress is NOT blocked (see
                         docs). Default: off (also settable via
                         chant.config.ts's build.sandbox: true; #1045)
-  --param <name=value>  (build, graph, run --components, components fan-out)
-                        Bind a declared
-                        build-time parameter (chant.config.ts's buildParams)
+  --param <name=value>  (build, graph, run --components, components fan-out,
+                        components promote, components rollback) Bind a
+                        declared build-time parameter (chant.config.ts's buildParams)
                         to a value, for source to read as params.<name>
                         (#1064) instead of process.env — repeatable.
                         Distinct from the AWS lexicon's deploy-time
                         Parameter(): this resolves before synthesis, so it
                         can change which resources are produced at all.
                         Highest precedence.
-  --params-file <path>  (build, graph, run --components, components fan-out)
-                        JSON file of
-                        { "name": value } build-time parameter values
+  --params-file <path>  (build, graph, run --components, components fan-out,
+                        components promote, components rollback) JSON file
+                        of { "name": value } build-time parameter values
                         (#1064). Second precedence, after --param.
 
 Examples:
@@ -800,6 +845,7 @@ Examples:
   chant build ./infra/ --fold
   chant build ./infra/ --components --generate gitlab
   chant build ./infra/ --components --generate gitlab --output .gitlab-ci.yml
+  chant run --generate github
   chant run --components search-service --env staging
   chant run --components all --env production
   chant components export prod --component search-service -o ./dist/search-service
@@ -994,6 +1040,10 @@ export const commandRegistry: CommandDef[] = [
   { name: "graph", handler: runGraph },
   { name: "vendor", handler: runVendor },
 
+  // Workspace reads (#2524). Imported on first use, so a level-0 command never
+  // loads anything under workspace/ (#2525 rule 5, pinned by #2526's goldens).
+  { name: "workspace records", handler: async (ctx) => (await import("../workspace/records-cli")).runWorkspaceRecords(ctx) },
+
   // State subcommands
   { name: "lifecycle snapshot", requiresPlugins: true, handler: runLifecycleSnapshot },
   { name: "lifecycle show", handler: runLifecycleShow },
@@ -1015,6 +1065,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
   { name: "components release", handler: runComponentsReleaseRecord },
   { name: "components export", handler: runComponentsExport },
+  { name: "components promote", handler: runComponentsPromote },
+  { name: "components rollback", handler: runComponentsRollback },
 
   // Local emulators of configured lexicons (#920). Compound so the action word
   // lands in args.path (not consumed as a project dir) and projectPath is forced ".".
@@ -1034,6 +1086,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "dev", handler: runDevUnknown },
   { name: "serve", handler: runServeUnknown },
   { name: "components", handler: runComponentsUnknown },
+  { name: "workspace", handler: async (ctx) => (await import("../workspace/records-cli")).runWorkspaceUnknown(ctx) },
 ];
 
 /**

package/src/cli/mcp/op-tools.ts

@@ -14,6 +14,7 @@
  * run.
  */
 
+import { lexiconNames } from "../../lexicon-module";
 import { resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { createLocalOpRuntime } from "../../op/runtimes/local";
@@ -39,7 +40,7 @@ async function runtimeFor(name: unknown): Promise<OpRuntimeProvider> {
   }
 
   const configured = await loadChantConfig(resolve("."))
-    .then(({ config }) => config.lexicons ?? [])
+    .then(({ config }) => lexiconNames(config.lexicons ?? []))
     .catch(() => [] as string[]);
   if (!configured.includes(wanted)) {
     throw new Error(