@intentius/chant 0.56.0 → 0.58.0

package/src/op/activities/lifecycle.ts

@@ -0,0 +1,85 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+export interface LifecycleSnapshotArgs {
+  /** Environment name (e.g. "dev", "staging", "prod"). */
+  env: string;
+}
+
+/**
+ * Take a chant lifecycle snapshot for the given environment.
+ * Uses fastIdempotent profile — 5m timeout, 3 retries.
+ */
+export async function lifecycleSnapshot(args: LifecycleSnapshotArgs, signal?: AbortSignal): Promise<void> {
+  const { stdout, stderr } = await execAsync(`chant lifecycle snapshot ${args.env}`, { signal });
+  if (stdout) console.log(stdout);
+  if (stderr) console.error(stderr);
+}
+
+export interface LifecycleDiffArgs {
+  /** Environment name (e.g. "dev", "staging", "prod"). */
+  env: string;
+  /**
+   * When true, run `chant lifecycle diff <env> --live` (queries cloud APIs).
+   * When false (default), run digest-only diff against the last snapshot.
+   */
+  live?: boolean;
+}
+
+export interface LifecycleDiffResult {
+  /** Combined stdout + stderr from the chant command. */
+  output: string;
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /**
+   * True when the diff output contains any drift indicators
+   * (MISSING / ORPHAN / DRIFTED / DISAPPEARED section headers from
+   * `chant lifecycle diff --live`).
+   */
+  drifted: boolean;
+}
+
+/**
+ * Section headers emitted by `chant lifecycle diff --live` that indicate a
+ * non-empty drift category. See packages/core/src/cli/handlers/state.ts.
+ */
+const DRIFT_HEADERS = [
+  "MISSING",
+  "ORPHAN",
+  "DISAPPEARED",
+  "DRIFTED",
+  "ARTIFACTS ADDED",
+  "ARTIFACTS REMOVED",
+  "ARTIFACTS CHANGED",
+];
+
+function detectDrift(output: string): boolean {
+  return DRIFT_HEADERS.some((h) => output.includes(`${h} (`) || output.includes(`\n${h}`));
+}
+
+/**
+ * Run `chant lifecycle diff <env>` and return the output + structured drift
+ * flag. Read-only; intended for use inside watch/observation Ops.
+ * Uses fastIdempotent profile.
+ *
+ * The `drifted` field is computed by scanning the output for any of the
+ * MISSING / ORPHAN / DRIFTED / DISAPPEARED section headers documented in
+ * cli/state.mdx. Pair with `outcomeAttribute: { name: "Drift", from: "drifted" }`
+ * on a WatchOp activity step to surface drift as the run's `Drift` outcome.
+ */
+export async function lifecycleDiff(args: LifecycleDiffArgs, signal?: AbortSignal): Promise<LifecycleDiffResult> {
+  const liveFlag = args.live ? " --live" : "";
+  try {
+    const { stdout, stderr } = await execAsync(`chant lifecycle diff ${args.env}${liveFlag}`, { signal });
+    const output = `${stdout}${stderr}`.trim();
+    if (output) console.log(output);
+    return { output, exitCode: 0, drifted: detectDrift(output) };
+  } catch (err) {
+    const e = err as { code?: number; stdout?: string; stderr?: string };
+    const output = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
+    if (output) console.error(output);
+    return { output, exitCode: e.code ?? 1, drifted: detectDrift(output) };
+  }
+}

package/src/op/activities/pipeline-audit.test.ts

@@ -0,0 +1,67 @@
+import { describe, test, expect } from "vitest";
+import {
+  pipelineSupplyChainAudit,
+  collectPipelineRefs,
+  type PipelineRefResolution,
+  type GitlabRefResolver,
+} from "./pipeline-audit";
+
+const PIPELINE = `include:
+  - project: my-group/ci-templates
+    ref: v1.2.3
+    file: /build.yml
+  - component: gitlab.example.com/my-group/my-comp@1.0.0
+
+build:
+  image:
+    name: node:20
+  script:
+    - npm ci
+`;
+
+function recordedResolver(records: Record<string, PipelineRefResolution>): GitlabRefResolver {
+  return async (kind, identifier, ref) =>
+    records[`${kind}:${identifier}@${ref}`] ?? { exists: true, archived: false, advisories: [] };
+}
+
+describe("collectPipelineRefs (#303)", () => {
+  test("collects include:project, component, and image refs", () => {
+    const refs = collectPipelineRefs(PIPELINE);
+    const ids = refs.map((r) => `${r.refKind}:${r.identifier}`);
+    expect(ids).toContain("include:my-group/ci-templates");
+    expect(ids).toContain("component:gitlab.example.com/my-group/my-comp");
+    expect(ids).toContain("image:node:20");
+    expect(refs.find((r) => r.refKind === "include")?.ref).toBe("v1.2.3");
+    expect(refs.find((r) => r.refKind === "component")?.ref).toBe("1.0.0");
+  });
+
+  test("skips variable-based images", () => {
+    const refs = collectPipelineRefs(`build:\n  image:\n    name: $CI_REGISTRY_IMAGE:latest\n`);
+    expect(refs.filter((r) => r.refKind === "image")).toHaveLength(0);
+  });
+});
+
+describe("pipelineSupplyChainAudit (#303)", () => {
+  test("flags unresolved, archived, and moved references", async () => {
+    const resolver = recordedResolver({
+      "include:my-group/ci-templates@v1.2.3": { exists: true, archived: true, advisories: [] },
+      "component:gitlab.example.com/my-group/my-comp@1.0.0": { exists: false, archived: false, advisories: [] },
+      "image:node:20@20": { exists: true, archived: false, advisories: ["GHSA-img"], movedTo: undefined },
+    });
+    const result = await pipelineSupplyChainAudit({ yaml: PIPELINE, resolver, mode: "merge-request" });
+    const kinds = result.findings.map((f) => `${f.identifier}:${f.kind}`);
+
+    expect(kinds).toContain("my-group/ci-templates:archived");
+    expect(kinds).toContain("gitlab.example.com/my-group/my-comp:unresolved");
+    expect(kinds).toContain("node:20:advisory");
+    expect(result.mode).toBe("merge-request");
+    expect(result.summary).toContain("Pipeline include/component audit");
+  });
+
+  test("clean pipeline yields no findings", async () => {
+    const resolver = recordedResolver({});
+    const result = await pipelineSupplyChainAudit({ yaml: PIPELINE, resolver });
+    expect(result.findings).toHaveLength(0);
+    expect(result.summary).toContain("No live drift");
+  });
+});

package/src/op/activities/pipeline-audit.ts

@@ -0,0 +1,201 @@
+/**
+ * pipelineSupplyChainAudit — the live counterpart to the gitlab post-synth
+ * include/component/image checks (#297).
+ *
+ * Some include/component checks can only be answered against a moving external
+ * truth: whether a pinned component/include ref still resolves upstream, whether
+ * the upstream project was archived or moved, or whether a new advisory now
+ * covers a component/image already in use. These change independent of the
+ * source, so they cannot live in the deterministic build — this activity owns
+ * *only* the checks that require live resolution.
+ *
+ * Dependency-free and primitives-only: it reads the emitted `.gitlab-ci.yml`
+ * (passed as a string) and resolves references through an injectable
+ * `GitlabRefResolver`, so `chant run` can schedule it and tests can run
+ * it against recorded responses with no live network.
+ */
+
+/** What the audit produces on findings. For GitLab the PR mode is a merge request. */
+export type PipelineAuditMode = "report" | "issue" | "merge-request";
+
+/** The kind of reference being resolved. */
+export type PipelineRefKind = "include" | "component" | "image";
+
+/** Live resolution of a single pipeline reference against its upstream. */
+export interface PipelineRefResolution {
+  /** Does the project/component/image (at this ref/version) still resolve? */
+  exists: boolean;
+  /** Has the upstream project been archived? */
+  archived: boolean;
+  /** Has the upstream project moved (new path), if known. */
+  movedTo?: string;
+  /** Disclosed advisory identifiers affecting this reference. */
+  advisories: string[];
+}
+
+/** Pluggable upstream resolver — overridden in tests with recorded responses. */
+export type GitlabRefResolver = (kind: PipelineRefKind, identifier: string, ref: string) => Promise<PipelineRefResolution>;
+
+export type PipelineAuditFindingKind = "unresolved" | "archived" | "moved" | "advisory";
+
+export interface PipelineAuditFinding {
+  kind: PipelineAuditFindingKind;
+  refKind: PipelineRefKind;
+  /** project path / component address / image. */
+  identifier: string;
+  /** ref / version / tag. */
+  ref: string;
+  detail: string;
+}
+
+export interface PipelineAuditArgs {
+  /** One emitted `.gitlab-ci.yml` document. */
+  yaml?: string;
+  /** Several emitted documents. */
+  yamls?: string[];
+  /** Path to an emitted `.gitlab-ci.yml` to read at run time (default `.gitlab-ci.yml`). */
+  pipelineFile?: string;
+  /** What to produce. Default: report. */
+  mode?: PipelineAuditMode;
+  /** Injectable upstream resolver. Defaults to the live GitLab REST resolver. */
+  resolver?: GitlabRefResolver;
+}
+
+export interface PipelineAuditResult {
+  mode: PipelineAuditMode;
+  findings: PipelineAuditFinding[];
+  summary: string;
+}
+
+interface CollectedRef {
+  refKind: PipelineRefKind;
+  identifier: string;
+  ref: string;
+}
+
+/**
+ * Collect `include:project` (+ ref), `component:` (with @version), and `image:`
+ * references from a `.gitlab-ci.yml`.
+ */
+export function collectPipelineRefs(yaml: string): CollectedRef[] {
+  const out: CollectedRef[] = [];
+
+  // include:\n  - project: group/proj\n    ref: main
+  const projectRe = /-\s+project:\s*['"]?([^\s'"]+)['"]?[\s\S]*?ref:\s*['"]?([^\s'"]+)['"]?/g;
+  let m: RegExpExecArray | null;
+  while ((m = projectRe.exec(yaml)) !== null) {
+    out.push({ refKind: "include", identifier: m[1], ref: m[2] });
+  }
+
+  // - component: host/group/comp@1.0.0
+  const componentRe = /-\s+component:\s*['"]?([^\s'"@]+)@([^\s'"]+)['"]?/g;
+  while ((m = componentRe.exec(yaml)) !== null) {
+    out.push({ refKind: "component", identifier: m[1], ref: m[2] });
+  }
+
+  // Images: inline `image: name` or block `image:\n  name: ...` (and services).
+  const lines = yaml.split("\n");
+  const imgSeen = new Set<string>();
+  const addImage = (raw: string) => {
+    const image = raw.trim().replace(/^['"]|['"]$/g, "");
+    if (!image || image.includes("$") || imgSeen.has(image)) return;
+    imgSeen.add(image);
+    const at = image.lastIndexOf("@");
+    const colon = image.lastIndexOf(":");
+    const ref = at !== -1 ? image.slice(at + 1) : colon > image.lastIndexOf("/") ? image.slice(colon + 1) : "latest";
+    out.push({ refKind: "image", identifier: image, ref });
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const inline = lines[i].match(/^\s+image:[ \t]+(\S.*)$/);
+    if (inline) { addImage(inline[1]); continue; }
+    if (/^\s+image:\s*$/.test(lines[i]) || /^\s+-\s+name:[ \t]+(\S.*)$/.test(lines[i])) {
+      const svcName = lines[i].match(/^\s+-\s+name:[ \t]+(\S.*)$/);
+      if (svcName) { addImage(svcName[1]); continue; }
+      const nameLine = lines.slice(i + 1, i + 4).find((l) => /^\s+name:[ \t]+/.test(l));
+      if (nameLine) addImage(nameLine.replace(/^\s+name:[ \t]+/, ""));
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Default resolver: query the GitLab REST API for project existence / archive /
+ * move status. Best-effort and resilient — errors yield an "unknown" resolution
+ * (exists=true, no findings) rather than a false positive. Component/image
+ * advisory lookups are left to a configured resolver.
+ */
+export const defaultGitlabRefResolver: GitlabRefResolver = async (kind, identifier) => {
+  const unknown: PipelineRefResolution = { exists: true, archived: false, advisories: [] };
+  if (kind === "image") return unknown; // image advisory feeds are resolver-specific
+  const host = "https://gitlab.com";
+  const project = kind === "component" ? identifier.split("/").slice(1, 3).join("/") : identifier;
+  try {
+    const resp = await fetch(`${host}/api/v4/projects/${encodeURIComponent(project)}`, {
+      headers: process.env.GITLAB_TOKEN ? { "PRIVATE-TOKEN": process.env.GITLAB_TOKEN } : {},
+    });
+    if (resp.status === 404) return { exists: false, archived: false, advisories: [] };
+    if (!resp.ok) return unknown;
+    const p = (await resp.json()) as { archived?: boolean };
+    return { exists: true, archived: !!p.archived, advisories: [] };
+  } catch {
+    return unknown;
+  }
+};
+
+function renderSummary(findings: PipelineAuditFinding[]): string {
+  if (findings.length === 0) return "## Pipeline include/component audit\n\nNo live drift detected against upstream references.\n";
+  let out = `## Pipeline include/component audit\n\n${findings.length} finding(s) against live upstream truth:\n\n`;
+  out += "| Reference | Ref | Finding | Detail |\n|---|---|---|---|\n";
+  for (const f of findings) out += `| ${f.identifier} (${f.refKind}) | ${f.ref} | ${f.kind} | ${f.detail} |\n`;
+  return out;
+}
+
+async function readFileBestEffort(path: string): Promise<string[]> {
+  try {
+    const { readFile } = await import("node:fs/promises");
+    return [await readFile(path, "utf-8")];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve each include/component/image reference in the emitted pipeline against
+ * live upstreams and report drift.
+ */
+export async function pipelineSupplyChainAudit(args: PipelineAuditArgs): Promise<PipelineAuditResult> {
+  const resolver = args.resolver ?? defaultGitlabRefResolver;
+  const mode = args.mode ?? "report";
+  let yamls = args.yamls ?? (args.yaml ? [args.yaml] : []);
+  if (yamls.length === 0) {
+    yamls = await readFileBestEffort(args.pipelineFile ?? ".gitlab-ci.yml");
+  }
+
+  const findings: PipelineAuditFinding[] = [];
+  const seen = new Set<string>();
+  for (const yaml of yamls) {
+    for (const { refKind, identifier, ref } of collectPipelineRefs(yaml)) {
+      const key = `${refKind}:${identifier}@${ref}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const res = await resolver(refKind, identifier, ref);
+      if (!res.exists) {
+        findings.push({ kind: "unresolved", refKind, identifier, ref, detail: `${refKind} "${identifier}@${ref}" no longer resolves upstream` });
+        continue;
+      }
+      if (res.archived) {
+        findings.push({ kind: "archived", refKind, identifier, ref, detail: `${identifier} has been archived upstream` });
+      }
+      if (res.movedTo) {
+        findings.push({ kind: "moved", refKind, identifier, ref, detail: `${identifier} moved to ${res.movedTo}` });
+      }
+      for (const adv of res.advisories) {
+        findings.push({ kind: "advisory", refKind, identifier, ref, detail: `disclosed advisory ${adv} covers ${identifier}` });
+      }
+    }
+  }
+
+  return { mode, findings, summary: renderSummary(findings) };
+}

package/src/op/activities/policy.test.ts

@@ -0,0 +1,19 @@
+import { describe, test, expect } from "vitest";
+import { resolve } from "node:path";
+import { policyGate } from "./policy";
+
+// The #201 org-policy example: a compliant workload + a policy pack
+// (ORG-COST-CENTER all-envs, ORG-PROD-TLS prod-only). policyGate builds it and
+// runs the policies — passing in dev, blocking in prod.
+const orgPolicySrc = resolve(import.meta.dirname, "../../../../../lexicons/k8s/examples/org-policy/src");
+
+describe("policyGate activity (#201 T4 — gate an apply on policy)", () => {
+  test("passes when policy is satisfied (no env, and dev)", async () => {
+    await expect(policyGate({ path: orgPolicySrc })).resolves.toBeUndefined();
+    await expect(policyGate({ path: orgPolicySrc, env: "dev" })).resolves.toBeUndefined();
+  }, 30_000);
+
+  test("blocks the apply on a prod policy violation", async () => {
+    await expect(policyGate({ path: orgPolicySrc, env: "prod" })).rejects.toThrow(/ORG-PROD-TLS/);
+  }, 30_000);
+});

package/src/op/activities/policy.ts

@@ -0,0 +1,37 @@
+import { nonRetryableFailure } from "../activity-failure";
+import { evaluateProjectPolicies } from "../../lint/policy";
+
+export interface PolicyGateArgs {
+  /** Project/source directory to build and evaluate. Default ".". */
+  path?: string;
+  /** Environment for policy evaluation (falls back to `ownership.env`). */
+  env?: string;
+}
+
+/**
+ * Gate an apply on organizational policy: build the project, run its
+ * `lint.policies` over the resolved resources, and **block** on any violation.
+ * Place it as a step before the apply phase — a violation fails the run
+ * (non-retryable; the `policyCheck` profile is single-attempt) so nothing is
+ * applied. A clean evaluation passes through.
+ *
+ * A plain activity on every runtime, not a `gate` step.
+ */
+export async function policyGate(args: PolicyGateArgs, _signal?: AbortSignal): Promise<void> {
+  const { violations, suppressed, env } = await evaluateProjectPolicies({ path: args.path ?? ".", env: args.env });
+  if (violations.length > 0) {
+    const summary = violations
+      .map((v) => `[${v.checkId}]${v.entity ? ` ${v.entity}:` : ""} ${v.message}`)
+      .join("; ");
+    throw nonRetryableFailure(
+      `Organizational policy blocked the apply — ${violations.length} violation(s): ${summary}`,
+      "PolicyViolation",
+    );
+  }
+  // chant #1138 — a check `lint.rules` turned "off" is counted here rather
+  // than vanishing silently, mirroring `chant build`'s own suppressed-count line.
+  if (suppressed.length > 0) {
+    console.log(`[policy] ${suppressed.length} finding(s) suppressed via lint.rules`);
+  }
+  console.log(`[policy] ${env ? `env=${env}: ` : ""}no violations — apply may proceed`);
+}

package/src/op/activities/reconcile.test.ts

@@ -0,0 +1,81 @@
+import { describe, test, expect } from "vitest";
+import { reconcilePr, reconcileSummary, reconcileBranchName, entriesFromPlan } from "./reconcile";
+
+const entries = [
+  { name: "bucket", action: "adopt", type: "AWS::S3::Bucket" },
+  { name: "queue", action: "update", type: "AWS::SQS::Queue" },
+];
+
+describe("reconcileBranchName (#122)", () => {
+  test("deterministic, slugified per env", () => {
+    expect(reconcileBranchName("prod")).toBe("chant/reconcile-prod");
+    expect(reconcileBranchName("us-east/1")).toBe("chant/reconcile-us-east-1");
+  });
+});
+
+describe("reconcileSummary (#122)", () => {
+  test("summarizes which entries triggered the reconcile", () => {
+    const body = reconcileSummary("prod", entries);
+    expect(body).toContain("live environment `prod`");
+    expect(body).toContain("| bucket | adopt | AWS::S3::Bucket |");
+    expect(body).toContain("| queue | update | AWS::SQS::Queue |");
+  });
+
+  test("handles an empty entry set", () => {
+    expect(reconcileSummary("prod", [])).toContain("_(none)_");
+  });
+});
+
+describe("entriesFromPlan (#123)", () => {
+  test("maps a ChangeSet, dropping noop entries", () => {
+    const plan = JSON.stringify({
+      env: "prod",
+      entries: [
+        { name: "a", action: "create", type: "T1", evidence: {}, ownership: "unknown" },
+        { name: "b", action: "noop", type: "T2", evidence: {}, ownership: "unknown" },
+        { name: "c", action: "delete", type: "T3", evidence: {}, ownership: "owned" },
+      ],
+    });
+    expect(entriesFromPlan(plan)).toEqual([
+      { name: "a", action: "create", type: "T1" },
+      { name: "c", action: "delete", type: "T3" },
+    ]);
+  });
+
+  test("tolerates an empty / entry-less plan", () => {
+    expect(entriesFromPlan(JSON.stringify({ env: "prod" }))).toEqual([]);
+  });
+});
+
+describe("reconcilePr report mode (#122)", () => {
+  test("returns the summary without any git/network IO", async () => {
+    const result = await reconcilePr({ env: "prod", entries, mode: "report" });
+    expect(result.mode).toBe("report");
+    expect(result.prUrl).toBeUndefined();
+    expect(result.branch).toBeUndefined();
+    expect(result.summary).toContain("| bucket | adopt | AWS::S3::Bucket |");
+    expect(result.entries).toEqual(entries);
+  });
+});
+
+describe("reconcilePr pre-built body (#2087)", () => {
+  test("a caller-supplied body is used verbatim, in place of the change-set table", async () => {
+    const plan = "Terraform will perform the following actions:\n\n  # null_resource.first will be created";
+    const result = await reconcilePr({ env: "app", mode: "report", body: plan });
+    expect(result.summary).toBe(plan);
+    expect(result.summary).not.toContain("| Entry | Action | Type |");
+  });
+
+  test("supplying a body derives no plan, so nothing shells to `chant lifecycle plan`", async () => {
+    // No `entries`, no mock, no network: if the derivation still ran this
+    // would spawn `chant lifecycle plan --json` and reject.
+    const result = await reconcilePr({ env: "app", mode: "report", body: "drift" });
+    expect(result.entries).toEqual([]);
+  });
+
+  test("explicit entries still ride alongside a supplied body", async () => {
+    const result = await reconcilePr({ env: "prod", mode: "report", entries, body: "drift" });
+    expect(result.summary).toBe("drift");
+    expect(result.entries).toEqual(entries);
+  });
+});

package/src/op/activities/reconcile.ts

@@ -0,0 +1,187 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+/** What the reconcile activity does with the regenerated source. */
+export type ReconcileMode = "pull-request" | "issue" | "report";
+
+/** A change-set entry that triggered reconciliation. */
+export interface ReconcileEntry {
+  /** chant entity name. */
+  name: string;
+  /** create | update | delete | adopt | noop (from `chant lifecycle plan`). */
+  action: string;
+  /** Resource type, when known. */
+  type?: string;
+}
+
+export interface ReconcilePrArgs {
+  /** Environment to reconcile from (passed to `chant import --from`). */
+  env: string;
+  /**
+   * The change-set entries that triggered this reconcile. Omit to derive them
+   * from `chant lifecycle plan <env> --json` at run time — the form used inside
+   * an Op, where the entries aren't known until the activity runs.
+   */
+  entries?: ReconcileEntry[];
+  /** What to produce. Default: pull-request. */
+  mode?: ReconcileMode;
+  /** Output directory for regenerated source. Default: ./infra. */
+  output?: string;
+  /** Branch to open the PR from. Default: chant/reconcile-<env>. */
+  branch?: string;
+  /** Restrict live import to chant-owned resources. */
+  owned?: boolean;
+  /** PR / issue title. Default derived from env. */
+  title?: string;
+  /**
+   * A finding body built by the caller, used verbatim as the issue/PR body in
+   * place of {@link reconcileSummary} (chant #2087).
+   *
+   * The summary this activity writes itself is a change-set table, which is
+   * the right artifact when the finding IS a change set. Some observe-dial
+   * Ops already hold a better one: `TerraformWatchOp` carries the
+   * `terraform plan -no-color` render its own Plan step produced, and
+   * re-deriving that from `chant lifecycle plan` here would both lose the
+   * plan and run a second, differently-timed read.
+   *
+   * Supplying it also suppresses the `chant lifecycle plan --json` derivation
+   * that fills `entries`: a caller that already knows what it wants to say
+   * is not asking this activity to go and find out.
+   */
+  body?: string;
+}
+
+export interface ReconcileResult {
+  mode: ReconcileMode;
+  /** Branch created (pull-request mode). */
+  branch?: string;
+  /** Opened PR URL (pull-request mode). */
+  prUrl?: string;
+  /** Opened issue URL (issue mode). */
+  issueUrl?: string;
+  /** The markdown summary used as the PR/issue body. */
+  summary: string;
+  /** The entries that triggered the reconcile. */
+  entries: ReconcileEntry[];
+}
+
+/** Default branch name for a reconcile PR. Deterministic — no timestamp. */
+export function reconcileBranchName(env: string): string {
+  const safe = env.replace(/[^a-zA-Z0-9._-]+/g, "-");
+  return `chant/reconcile-${safe}`;
+}
+
+/**
+ * Build the markdown body summarizing which change-set entries triggered the
+ * reconcile. Pure — used as the PR/issue body and returned in `report` mode.
+ */
+export function reconcileSummary(env: string, entries: ReconcileEntry[]): string {
+  const lines = [
+    `Reconcile from live environment \`${env}\`.`,
+    "",
+    "This PR regenerates chant TypeScript from live state to close the gap between the cloud and source. It was triggered by the following change-set entries:",
+    "",
+    "| Entry | Action | Type |",
+    "|---|---|---|",
+  ];
+  for (const e of entries) {
+    lines.push(`| ${e.name} | ${e.action} | ${e.type ?? ""} |`);
+  }
+  if (entries.length === 0) {
+    lines.push("| _(none)_ | | |");
+  }
+  lines.push("");
+  lines.push("Review the diff before merging — live import may surface values that need redaction.");
+  return lines.join("\n");
+}
+
+function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Map a `chant lifecycle plan --json` ChangeSet to reconcile entries, dropping
+ * `noop` entries (nothing to reconcile). Pure — exported for testing.
+ */
+export function entriesFromPlan(planJson: string): ReconcileEntry[] {
+  const cs = JSON.parse(planJson) as {
+    entries?: Array<{ name: string; action: string; type?: string }>;
+  };
+  return (cs.entries ?? [])
+    .filter((e) => e.action !== "noop")
+    .map((e) => ({ name: e.name, action: e.action, type: e.type }));
+}
+
+/** Derive reconcile entries from `chant lifecycle plan`. */
+async function derivePlanEntries(
+  env: string,
+  owned: boolean,
+  signal?: AbortSignal,
+): Promise<ReconcileEntry[]> {
+  const ownedFlag = owned ? " --owned" : "";
+  const { stdout } = await execAsync(
+    `chant lifecycle plan ${shellQuote(env)}${ownedFlag} --json`,
+    { signal },
+  );
+  return entriesFromPlan(stdout);
+}
+
+/**
+ * Reconcile activity: turn regenerated TypeScript into a reviewable artifact.
+ *
+ * - `report` — return the summary only; no git, no network.
+ * - `issue` — open a GitHub issue describing the drift (no code change).
+ * - `pull-request` — create a branch, regenerate source via
+ *   `chant import --from <env>`, commit, push, and open a PR whose diff is the
+ *   regenerated TypeScript. Never commits to the main branch.
+ *
+ * The body is {@link reconcileSummary}'s change-set table unless `args.body`
+ * supplies one, in which case that text is used verbatim and no plan is
+ * derived (chant #2087).
+ *
+ * Requires `chant` and (for non-report modes) `gh`/`git` in the environment.
+ */
+export async function reconcilePr(args: ReconcilePrArgs, signal?: AbortSignal): Promise<ReconcileResult> {
+  const mode = args.mode ?? "pull-request";
+  const owned = args.owned ?? false;
+  // A caller-supplied body means the finding is already written, so there is
+  // nothing for `chant lifecycle plan` to tell us (#2087).
+  const entries = args.entries ?? (args.body !== undefined ? [] : await derivePlanEntries(args.env, owned, signal));
+  const summary = args.body ?? reconcileSummary(args.env, entries);
+  const title = args.title ?? `Reconcile ${args.env}: ${entries.length} change(s) from live`;
+
+  if (mode === "report") {
+    return { mode, summary, entries };
+  }
+
+  if (mode === "issue") {
+    const { stdout } = await execAsync(
+      `gh issue create --title ${shellQuote(title)} --body ${shellQuote(summary)}`,
+      { signal },
+    );
+    return { mode, summary, entries, issueUrl: stdout.trim() };
+  }
+
+  // pull-request
+  const branch = args.branch ?? reconcileBranchName(args.env);
+  const output = args.output ?? "./infra";
+  const ownedFlag = owned ? " --owned" : "";
+
+  // Never touch the main branch: cut a fresh branch first.
+  await execAsync(`git checkout -b ${shellQuote(branch)}`, { signal });
+  await execAsync(
+    `chant import --from ${shellQuote(args.env)}${ownedFlag} --output ${shellQuote(output)} --force`,
+    { signal },
+  );
+  await execAsync(`git add ${shellQuote(output)}`, { signal });
+  await execAsync(`git commit -m ${shellQuote(title)}`, { signal });
+  await execAsync(`git push -u origin ${shellQuote(branch)}`, { signal });
+  const { stdout } = await execAsync(
+    `gh pr create --title ${shellQuote(title)} --body ${shellQuote(summary)} --head ${shellQuote(branch)}`,
+    { signal },
+  );
+
+  return { mode, branch, summary, entries, prUrl: stdout.trim() };
+}