@intentius/chant 0.79.0 → 0.80.0

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

@@ -0,0 +1,261 @@
+/**
+ * `chant components promote` (#2530), with the ledger, discovery and the
+ * capability registry replaced by fakes.
+ */
+
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { CapabilityRegistry, type DeployContext } from "../../components/capability";
+import type { DriverComponent } from "../../components/driver";
+import type { ReleaseRecord } from "../../lifecycle/release-ledger";
+import type { ParsedArgs } from "../registry";
+
+const appendReleaseRecordMock = vi.fn();
+const readReleaseLedgerMock = vi.fn();
+const pushLifecycleMock = vi.fn();
+const resolveTargetsMock = vi.fn();
+const ran: string[] = [];
+let publishedDigest = "sha256:api";
+let failApplyFor: string | undefined;
+
+vi.mock("../../lifecycle/git", () => ({
+  getHeadCommit: async () => "abc123",
+  fetchLifecycle: async () => true,
+  pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args),
+}));
+
+vi.mock("../../lifecycle/release-ledger", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/release-ledger")>("../../lifecycle/release-ledger");
+  return {
+    ...actual,
+    appendReleaseRecord: (...args: unknown[]) => appendReleaseRecordMock(...args),
+    readReleaseLedger: (...args: unknown[]) => readReleaseLedgerMock(...args),
+  };
+});
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: async () => ({ config: {} }) };
+});
+
+vi.mock("../../components/cli-support", () => ({
+  resolveComponentTargets: (...args: unknown[]) => resolveTargetsMock(...args),
+}));
+
+vi.mock("../../components/fan-out-support", () => ({
+  fanOutRegistry: async () => {
+    const registry = new CapabilityRegistry();
+    const step = (kind: string, output: (ctx: DeployContext) => unknown) =>
+      registry.register({ kind, async run(ctx: DeployContext) { ran.push(`${ctx.env}:${kind}`); return output(ctx); } } as never);
+    step("docker-build", () => ({ digest: "sha256:rebuilt" }));
+    step("publish-image", () => ({ digest: publishedDigest, uri: `reg/api@${publishedDigest}` }));
+    step("apply", (ctx) => {
+      if (ctx.component === failApplyFor) throw new Error("apply failed");
+      return {};
+    });
+    return registry;
+  },
+}));
+
+// Gates read an in-memory ledger rather than the git branch.
+vi.mock("../../op/gate", async () => {
+  const actual = await vi.importActual<typeof import("../../op/gate")>("../../op/gate");
+  const port = actual.memoryGateLedgerPort();
+  return { ...actual, gitGateLedgerPort: () => port };
+});
+
+// The run handler pulls in every runtime; the promote needs only its exit code.
+vi.mock("./run", () => ({ GATED_EXIT_CODE: 3 }));
+
+const { runComponentsPromote, runComponentsRollback } = await import("./promote");
+
+const api: DriverComponent = {
+  name: "api",
+  deploy: [
+    { phase: "Build", steps: [{ kind: "docker-build", context: ".", into: "api.tar" }] },
+    { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:api.tar" }] },
+    { phase: "Apply", steps: [{ kind: "apply", imageRef: "@Publish.digest" }] },
+  ],
+};
+
+const staging: ReleaseRecord = {
+  version: 1,
+  component: "api",
+  env: "staging",
+  digest: "sha256:api",
+  gitSha: "abc123",
+  runId: "run-7",
+  timestamp: "2026-01-02T00:00:00.000Z",
+  actor: "ci",
+};
+
+function args(overrides: Partial<ParsedArgs>): ParsedArgs {
+  return {
+    command: "components",
+    path: "promote",
+    format: "",
+    fix: false,
+    watch: false,
+    verbose: false,
+    help: false,
+    live: false,
+    migrateFrom: "staging",
+    migrateTo: "prod",
+    actor: "bob",
+    runId: "run-9",
+    ...overrides,
+  } as ParsedArgs;
+}
+
+const ctx = (a: Partial<ParsedArgs>) => ({ args: args(a), plugins: [] }) as never;
+
+let errors: string[];
+let logs: string[];
+
+beforeEach(() => {
+  ran.length = 0;
+  publishedDigest = "sha256:api";
+  failApplyFor = undefined;
+  errors = [];
+  logs = [];
+  vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => { errors.push(m.join(" ")); });
+  vi.spyOn(console, "log").mockImplementation((...m: unknown[]) => { logs.push(m.join(" ")); });
+  vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+  appendReleaseRecordMock.mockReset().mockImplementation(async (input: object) => ({ commit: "c0ffee0", record: { version: 1, ...input } }));
+  readReleaseLedgerMock.mockReset().mockResolvedValue({ records: [staging], malformed: 0 });
+  pushLifecycleMock.mockReset().mockResolvedValue(undefined);
+  resolveTargetsMock.mockReset().mockResolvedValue({ success: true, targets: [api] });
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("chant components promote", () => {
+  test("--from and --to are required", async () => {
+    expect(await runComponentsPromote(ctx({ migrateTo: undefined }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/--from <env> and --to <env> are required/);
+  });
+
+  test("deploys the staging digest to prod without building, and records the promotion", async () => {
+    expect(await runComponentsPromote(ctx({}))).toBe(0);
+    expect(readReleaseLedgerMock).toHaveBeenCalledWith("staging");
+    expect(ran).toEqual(["prod:publish-image", "prod:apply"]);
+    expect(appendReleaseRecordMock).toHaveBeenCalledTimes(1);
+    expect(appendReleaseRecordMock.mock.calls[0][0]).toMatchObject({
+      component: "api",
+      env: "prod",
+      digest: "sha256:api",
+      gitSha: "abc123",
+      runId: "run-9",
+      actor: "bob",
+      promotedFrom: { env: "staging", runId: "run-7", timestamp: "2026-01-02T00:00:00.000Z" },
+    });
+    expect(pushLifecycleMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("a digest missing from the source ledger fails clearly and deploys nothing", async () => {
+    expect(await runComponentsPromote(ctx({ component: "api", digest: "sha256:unknown" }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/sha256:unknown is not recorded for "api" in "staging"/);
+    expect(ran).toEqual([]);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+  });
+
+  test("--dry-run prints the plan and deploys nothing", async () => {
+    expect(await runComponentsPromote(ctx({ dryRun: true, json: true }))).toBe(0);
+    expect(ran).toEqual([]);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+    const plan = JSON.parse(logs.join("\n"));
+    expect(plan.items).toEqual([expect.objectContaining({ component: "api", digest: "sha256:api", notRun: ["docker-build"] })]);
+  });
+
+  test("a publish that does not match the recorded digest fails and records nothing", async () => {
+    publishedDigest = "sha256:other";
+    expect(await runComponentsPromote(ctx({}))).toBe(1);
+    expect(ran).toEqual(["prod:publish-image"]);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+  });
+
+  test("a gate in the composition stops the promote with exit 3 and records nothing", async () => {
+    const gated: DriverComponent = {
+      ...api,
+      deploy: [...api.deploy.slice(0, 2), { phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "apply" }] }],
+    };
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [gated] });
+    expect(await runComponentsPromote(ctx({}))).toBe(3);
+    expect(ran).not.toContain("prod:apply");
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+    expect(errors.join("\n")).toMatch(/chant approve api prod-release/);
+  });
+
+  test("a component that deployed is recorded even when another one failed", async () => {
+    const web: DriverComponent = { ...api, name: "web" };
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [api, web] });
+    readReleaseLedgerMock.mockResolvedValue({ records: [staging, { ...staging, component: "web" }], malformed: 0 });
+    failApplyFor = "web";
+    expect(await runComponentsPromote(ctx({}))).toBe(1);
+    expect(appendReleaseRecordMock).toHaveBeenCalledTimes(1);
+    expect(appendReleaseRecordMock.mock.calls[0][0]).toMatchObject({ component: "api", env: "prod" });
+  });
+
+  test("a component with no publish step is refused before anything runs", async () => {
+    resolveTargetsMock.mockResolvedValue({
+      success: true,
+      targets: [{ name: "api", deploy: [{ phase: "Apply", steps: [{ kind: "apply" }] }] }],
+    });
+    expect(await runComponentsPromote(ctx({}))).toBe(1);
+    expect(errors.join("\n")).toMatch(/no publish step/);
+    expect(ran).toEqual([]);
+  });
+});
+
+describe("chant components rollback", () => {
+  const prod = (digest: string, timestamp: string, runId: string): ReleaseRecord =>
+    ({ ...staging, env: "prod", digest, timestamp, runId });
+
+  beforeEach(() => {
+    readReleaseLedgerMock.mockResolvedValue({
+      records: [prod("sha256:old", "2026-01-01T00:00:00.000Z", "run-1"), prod("sha256:new", "2026-01-02T00:00:00.000Z", "run-2")],
+      malformed: 0,
+    });
+  });
+
+  const rb = (a: Partial<ParsedArgs>) => ctx({ migrateFrom: undefined, migrateTo: undefined, path: "rollback", extraPositional: "prod", component: "api", ...a });
+
+  test("an environment and --component are required", async () => {
+    expect(await runComponentsRollback(rb({ component: undefined }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/--component <name> are required/);
+  });
+
+  test("redeploys the previous release from its recorded digest and records what it restored", async () => {
+    expect(await runComponentsRollback(rb({}))).toBe(0);
+    expect(readReleaseLedgerMock).toHaveBeenCalledWith("prod");
+    // Neither a build nor a publish: the environment already has the artifact.
+    expect(ran).toEqual(["prod:apply"]);
+    expect(appendReleaseRecordMock.mock.calls[0][0]).toMatchObject({
+      component: "api",
+      env: "prod",
+      digest: "sha256:old",
+      restores: { env: "prod", runId: "run-1", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    expect(appendReleaseRecordMock.mock.calls[0][0]).not.toHaveProperty("promotedFrom");
+  });
+
+  test("a digest the environment never recorded fails clearly", async () => {
+    expect(await runComponentsRollback(rb({ digest: "sha256:elsewhere" }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/sha256:elsewhere is not recorded for "api" in "prod"/);
+    expect(ran).toEqual([]);
+  });
+
+  test("the environment's gate applies to a rollback", async () => {
+    const gated: DriverComponent = {
+      ...api,
+      name: "api",
+      deploy: [...api.deploy.slice(0, 2), { phase: "Apply", steps: [{ kind: "gate", gate: "rollback-ok" }, { kind: "apply" }] }],
+    };
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [gated] });
+    expect(await runComponentsRollback(rb({}))).toBe(3);
+    expect(ran).not.toContain("prod:apply");
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+    expect(errors.join("\n")).toMatch(/chant approve api rollback-ok/);
+  });
+});

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);
+}