@intentius/chant 0.62.0 → 0.64.0

package/src/lifecycle/plan-digest.ts

@@ -0,0 +1,86 @@
+/**
+ * Plan identity for a gate (#2300, measured on INTENTIUS/choudoufu#1026).
+ *
+ * A gate resolution used to carry the op, the gate, the approver and a
+ * timestamp, and nothing about what was approved. Approve, edit the root,
+ * re-run, and the second run re-planned and applied: the resolution had
+ * authorised the *next run* of that op rather than the plan the approver
+ * read. This module is the missing half — one string that identifies a plan,
+ * written onto the pending fact the run records, onto the resolution `chant
+ * approve` appends, and compared by {@link latestResolutionForPlan} when a
+ * later run decides the gate.
+ *
+ * ## What a digest covers
+ *
+ * The change set, and only the change set: what a run proposes to create,
+ * update, replace or destroy, at which addresses, with which values. Two
+ * plans share a digest exactly when applying either one would do the same
+ * thing to the estate.
+ *
+ * ## What it deliberately does not cover
+ *
+ * - **When the plan was taken.** A plan file's own `timestamp`, and the
+ *   resolution's. Re-planning an unchanged root a minute later must produce
+ *   the same digest, or every approval would expire on the clock rather than
+ *   on the content.
+ * - **Which run took it.** `runId`, the CI job number, the workflow attempt.
+ *   Approving a plan and re-running the workflow is the whole loop; binding
+ *   the run id would make the approval unusable by the run that consumes it.
+ * - **The tool that produced it.** The terraform/choudoufu version, the plan
+ *   file's binary bytes and its path on disk. The digest is taken over the
+ *   `show -json` rendering rather than the file, so a plan-format bump does
+ *   not read as a changed plan.
+ * - **Who approved it, or where.** `resolvedBy`, `note`, `url` — those
+ *   describe the approval, not the plan.
+ *
+ * The identity is therefore a claim about consequence, not about provenance.
+ * That is the claim an approver is actually making.
+ */
+import { sortedJsonReplacer } from "../utils";
+import { getRuntime } from "../runtime-adapter";
+
+/** The hash a plan digest is taken with, and the prefix every digest carries. */
+export const PLAN_DIGEST_ALGORITHM = "sha256";
+
+/** Shape of a well-formed digest: `sha256:` and 64 lowercase hex characters. */
+const PLAN_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+/**
+ * Hash a plan's change set into a stable identity.
+ *
+ * `kind` names the shape `subject` is in (`"terraform-plan"`,
+ * `"lifecycle-diff"`), and is hashed alongside it so two different kinds of
+ * plan can never collide into the same digest by coincidence — a gate bound
+ * to a terraform plan must not be satisfiable by a lifecycle diff that
+ * happened to serialize identically.
+ *
+ * `subject` is canonicalised by {@link sortedJsonReplacer}, so object key
+ * order — which neither terraform's JSON writer nor `JSON.parse` guarantees
+ * across versions — does not change the answer. It is the caller's job to
+ * hand in a projection that already excludes the volatile fields this
+ * module's doc comment lists.
+ */
+export function computePlanDigest(kind: string, subject: unknown): string {
+  const canonical = JSON.stringify({ kind, subject }, sortedJsonReplacer);
+  return `${PLAN_DIGEST_ALGORITHM}:${getRuntime().hash(canonical)}`;
+}
+
+/**
+ * Whether `raw` is a digest this code produced. Used at the `chant approve
+ * --plan` boundary, so a typo, a truncated copy-paste or a plan *file* path
+ * is refused before it is written into an immutable resolution that would
+ * then never match anything.
+ */
+export function isPlanDigest(raw: unknown): raw is string {
+  return typeof raw === "string" && PLAN_DIGEST_PATTERN.test(raw);
+}
+
+/**
+ * A digest as it reads in a message, and the one place that decides how an
+ * absent one reads. Records written before #2300 carry no digest at all, and
+ * "(none — recorded before plan-bound gates)" is what a refusal has to say
+ * about them instead of printing `undefined`.
+ */
+export function describePlanDigest(digest: string | undefined): string {
+  return digest ?? "(none — recorded before plan-bound gates)";
+}

package/src/lifecycle/run-ledger.ts

@@ -105,6 +105,7 @@ export function buildRunRecord(
       ...(record.outcome ? { outcome: record.outcome } : {}),
       ...(record.approval ? { approval: record.approval } : {}),
       ...(record.error !== undefined ? { error: record.error } : {}),
+      ...(record.refusal !== undefined ? { refusal: record.refusal } : {}),
     });
     if (record.outcome) outcomes[record.outcome.name] = record.outcome.value;
   }

package/src/op/activities/lexicon-upgrade.test.ts

@@ -257,9 +257,9 @@ describe("lexiconUpgrade issue mode", () => {
 
   test("on a GitHub Actions job (GITHUB_REPOSITORY set), opens the sticky issue via gh api (#2297)", async () => {
     const checkPinned: CheckPinnedFn = vi.fn(async () => pinnedResult());
-    const calls: string[] = [];
-    const gh = vi.fn(async (cmd: string) => {
-      calls.push(cmd);
+    const calls: Array<{ cmd: string; env?: NodeJS.ProcessEnv }> = [];
+    const gh = vi.fn(async (cmd: string, opts?: { env?: NodeJS.ProcessEnv }) => {
+      calls.push({ cmd, env: opts?.env });
       if (cmd.includes("--paginate")) return { stdout: "", stderr: "" }; // no owned issue yet
       if (cmd.includes("--method POST")) return { stdout: "https://github.com/acme/infra/issues/11\n", stderr: "" };
       return { stdout: "", stderr: "" };
@@ -267,6 +267,8 @@ describe("lexiconUpgrade issue mode", () => {
 
     vi.stubEnv("GITHUB_REPOSITORY", "acme/infra");
     vi.stubEnv("GITHUB_API_URL", "");
+    vi.stubEnv("CHANT_FORGEJO_TOKEN", "");
+    vi.stubEnv("GH_TOKEN", "ghs-workflow");
     try {
       const r = await lexiconUpgrade({
         lexicon: "gcp",
@@ -276,10 +278,14 @@ describe("lexiconUpgrade issue mode", () => {
       });
 
       expect(r.issueUrl).toBe("https://github.com/acme/infra/issues/11");
-      expect(calls.some((c) => c.includes("gh issue create"))).toBe(false);
-      const post = calls.find((c) => c.includes("--method POST"));
-      expect(post).toContain("https://api.github.com/repos/acme/infra/issues");
-      expect(post).toContain("<!-- chant-lexicon-upgrade:gcp -->");
+      expect(calls.some((c) => c.cmd.includes("gh issue create"))).toBe(false);
+      const post = calls.find((c) => c.cmd.includes("--method POST"));
+      expect(post?.cmd).toContain("https://api.github.com/repos/acme/infra/issues");
+      expect(post?.cmd).toContain("<!-- chant-lexicon-upgrade:gcp -->");
+      // #2320: the shared `postOrUpdateGithubIssue` resolves the credential
+      // and hands it to the runner, so this caller gets the same forwarding
+      // reconcilePr's issue mode does rather than leaving `gh` to guess.
+      for (const call of calls) expect(call.env?.GH_TOKEN).toBe("ghs-workflow");
     } finally {
       vi.unstubAllEnvs();
     }
@@ -287,9 +293,9 @@ describe("lexiconUpgrade issue mode", () => {
 
   test("a re-run on a GitHub Actions job PATCHes the issue it already owns (#2297)", async () => {
     const checkPinned: CheckPinnedFn = vi.fn(async () => pinnedResult());
-    const calls: string[] = [];
-    const gh = vi.fn(async (cmd: string) => {
-      calls.push(cmd);
+    const calls: Array<{ cmd: string; env?: NodeJS.ProcessEnv }> = [];
+    const gh = vi.fn(async (cmd: string, opts?: { env?: NodeJS.ProcessEnv }) => {
+      calls.push({ cmd, env: opts?.env });
       if (cmd.includes("--paginate")) return { stdout: "11\n", stderr: "" }; // marker search found issue 11
       if (cmd.includes("--method PATCH")) return { stdout: "https://github.com/acme/infra/issues/11\n", stderr: "" };
       return { stdout: "", stderr: "" };
@@ -297,6 +303,10 @@ describe("lexiconUpgrade issue mode", () => {
 
     vi.stubEnv("GITHUB_REPOSITORY", "acme/infra");
     vi.stubEnv("GITHUB_API_URL", "");
+    // The cross-instance case (#2320): a Forgejo token that must outrank the
+    // job's own `github.token`, on the path that used to forward neither.
+    vi.stubEnv("CHANT_FORGEJO_TOKEN", "forgejo-cross-instance");
+    vi.stubEnv("GH_TOKEN", "ghs-this-instance-only");
     try {
       const r = await lexiconUpgrade({
         lexicon: "gcp",
@@ -306,8 +316,10 @@ describe("lexiconUpgrade issue mode", () => {
       });
 
       expect(r.issueUrl).toBe("https://github.com/acme/infra/issues/11");
-      expect(calls.some((c) => c.includes("--method POST"))).toBe(false);
-      expect(calls.some((c) => c.includes("gh issue create"))).toBe(false);
+      expect(calls.some((c) => c.cmd.includes("--method POST"))).toBe(false);
+      expect(calls.some((c) => c.cmd.includes("gh issue create"))).toBe(false);
+      const patch = calls.find((c) => c.cmd.includes("--method PATCH"));
+      expect(patch?.env?.GH_TOKEN).toBe("forgejo-cross-instance");
     } finally {
       vi.unstubAllEnvs();
     }

package/src/op/activities/lexicon-upgrade.ts

@@ -120,8 +120,21 @@ export type CheckRollingFn = (opts: {
   verbose?: boolean;
 }) => Promise<RollingUpgradeResult>;
 
-/** Minimal shell-exec interface for gh/git invocations. */
-export type GhRunner = (cmd: string) => Promise<{ stdout: string; stderr: string }>;
+/**
+ * Minimal shell-exec interface for gh/git invocations.
+ *
+ * `opts` carries the environment `postOrUpdateGithubIssue` resolves the issue
+ * credential into (chant #2320) — the same `GhExec` shape reconcile.ts
+ * declares, so the two stay one signature and this can keep being passed
+ * straight through. Every other call site here forwards nothing and passes
+ * nothing. A mock runner is free to ignore the argument; the default one
+ * hands it to `execAsync`, which is what makes CHANT_FORGEJO_TOKEN actually
+ * reach `gh` on a cross-instance Forgejo run.
+ */
+export type GhRunner = (
+  cmd: string,
+  opts?: { env?: NodeJS.ProcessEnv },
+) => Promise<{ stdout: string; stderr: string }>;
 
 /** Applies a pinned version bump permanently (no revert). Async (core loads the lexicon's pin descriptor); a sync mock is also accepted. */
 export type ApplyBumpFn = (
@@ -283,7 +296,7 @@ function shellQuote(s: string): string {
   return `'${s.replace(/'/g, "'\\''")}'`;
 }
 
-const defaultGh: GhRunner = async (cmd) => execAsync(cmd);
+const defaultGh: GhRunner = async (cmd, opts) => execAsync(cmd, { ...opts });
 
 /**
  * The hidden marker that makes this lexicon's upgrade-status issue findable
@@ -320,6 +333,9 @@ async function postLexiconIssue(
   const marker = lexiconUpgradeIssueMarker(lexicon);
   const repo = process.env.GITHUB_REPOSITORY;
   if (repo) {
+    // `postOrUpdateGithubIssue` resolves the token itself and hands it back
+    // through `gh`'s second argument (#2320), so this runner has to forward
+    // what it is given rather than dropping it — see `GhRunner`.
     return postOrUpdateGithubIssue(repo, marker, title, body, gh);
   }
   const { stdout } = await gh(

package/src/op/activities/lifecycle.ts

@@ -1,5 +1,6 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
+import { computePlanDigest } from "../../lifecycle/plan-digest";
 
 const execAsync = promisify(exec);
 
@@ -39,6 +40,40 @@ export interface LifecycleDiffResult {
    * `chant lifecycle diff --live`).
    */
   drifted: boolean;
+  /**
+   * This diff's identity (#2300) — the change set `chant lifecycle diff`
+   * reported, hashed. `ApplyOp` hands it to its gate step's `plan`, so an
+   * approval binds to the change set the approver read rather than to the
+   * next run of the Op.
+   *
+   * Computed over {@link normalizeDiffChangeSet}'s canonical form of
+   * `output`, so incidental whitespace does not read as a changed plan, while
+   * any added, removed or reworded row does.
+   */
+  planDigest: string;
+}
+
+/**
+ * The change set half of a `chant lifecycle diff` render, canonicalised for
+ * digesting (#2300).
+ *
+ * The diff render is line-oriented: section headers and the resource rows
+ * under them. Two runs over an unchanged environment print the same lines, so
+ * the lines are the change set. Normalising is deliberately minimal — CRLF to
+ * LF, trailing whitespace off each line, blank lines dropped — because
+ * anything more aggressive would start discarding rows, and a digest that
+ * discards rows is a digest that approves changes nobody saw.
+ *
+ * Unlike a terraform plan there is no timestamp to strip: the diff render
+ * carries none. If one is ever added it has to be dropped here, or every
+ * approval would be stale the moment it was written.
+ */
+export function normalizeDiffChangeSet(output: string): string[] {
+  return output
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .map((line) => line.replace(/\s+$/, ""))
+    .filter((line) => line !== "");
 }
 
 /**
@@ -59,6 +94,20 @@ function detectDrift(output: string): boolean {
   return DRIFT_HEADERS.some((h) => output.includes(`${h} (`) || output.includes(`\n${h}`));
 }
 
+/**
+ * The identity of one `chant lifecycle diff` result (#2300). The environment
+ * and the `--live` flag are hashed alongside the change set because they say
+ * what the change set is *of*: the same rows against `staging` are not an
+ * approval to apply against `prod`.
+ */
+function lifecycleDiffDigest(args: LifecycleDiffArgs, output: string): string {
+  return computePlanDigest("lifecycle-diff", {
+    env: args.env,
+    live: args.live === true,
+    changeSet: normalizeDiffChangeSet(output),
+  });
+}
+
 /**
  * Run `chant lifecycle diff <env>` and return the output + structured drift
  * flag. Read-only; intended for use inside watch/observation Ops.
@@ -75,11 +124,11 @@ export async function lifecycleDiff(args: LifecycleDiffArgs, signal?: AbortSigna
     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) };
+    return { output, exitCode: 0, drifted: detectDrift(output), planDigest: lifecycleDiffDigest(args, 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) };
+    return { output, exitCode: e.code ?? 1, drifted: detectDrift(output), planDigest: lifecycleDiffDigest(args, output) };
   }
 }