@intentius/chant 0.13.0 → 0.15.0

package/src/lifecycle/release-ledger.test.ts

@@ -0,0 +1,209 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  appendReleaseRecord,
+  readReleaseLedger,
+  listReleaseEnvironments,
+  validateReleaseRecord,
+  InvalidReleaseRecordError,
+  latestPerComponent,
+  recordsForDigest,
+  type ReleaseRecord,
+  type ReleaseRecordInput,
+} from "./release-ledger";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+function makeInput(overrides?: Partial<ReleaseRecordInput>): ReleaseRecordInput {
+  return {
+    component: "search-service",
+    env: "prod",
+    digest: "sha256:abc123",
+    gitSha: "deadbeef",
+    runId: "run-1",
+    timestamp: "2026-01-01T00:00:00.000Z",
+    actor: "ci-bot",
+    ...overrides,
+  };
+}
+
+describe("release-ledger", () => {
+  describe("validateReleaseRecord", () => {
+    test("no missing fields for a complete record", () => {
+      expect(validateReleaseRecord({ version: 1, ...makeInput() })).toEqual([]);
+    });
+
+    test("reports every missing required field", () => {
+      const missing = validateReleaseRecord({ component: "x" });
+      expect(missing).toContain("env");
+      expect(missing).toContain("digest");
+      expect(missing).toContain("gitSha");
+      expect(missing).toContain("runId");
+      expect(missing).toContain("timestamp");
+      expect(missing).toContain("actor");
+      expect(missing).not.toContain("component");
+    });
+
+    test("empty string counts as missing", () => {
+      expect(validateReleaseRecord({ ...makeInput(), actor: "" })).toEqual(["actor"]);
+    });
+  });
+
+  describe("appendReleaseRecord", () => {
+    test("throws InvalidReleaseRecordError before any git operation on an incomplete record", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await expect(
+          appendReleaseRecord({ ...makeInput(), actor: "" }, { cwd: dir }),
+        ).rejects.toBeInstanceOf(InvalidReleaseRecordError);
+        const ledger = await readReleaseLedger("prod", { cwd: dir });
+        expect(ledger.records).toEqual([]);
+      });
+    });
+
+    test("writes one JSON-lines record readable back via readReleaseLedger", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const { commit, record } = await appendReleaseRecord(makeInput(), { cwd: dir });
+        expect(commit).toMatch(/^[0-9a-f]{40}$/);
+        expect(record.version).toBe(1);
+
+        const { records, malformed } = await readReleaseLedger("prod", { cwd: dir });
+        expect(malformed).toBe(0);
+        expect(records).toHaveLength(1);
+        expect(records[0]).toMatchObject(makeInput());
+      });
+    });
+
+    test("appends rather than replaces — multiple releases accumulate in order", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendReleaseRecord(makeInput({ digest: "sha256:v1", timestamp: "2026-01-01T00:00:00.000Z" }), { cwd: dir });
+        await appendReleaseRecord(makeInput({ digest: "sha256:v2", timestamp: "2026-01-02T00:00:00.000Z" }), { cwd: dir });
+        await appendReleaseRecord(makeInput({ digest: "sha256:v3", timestamp: "2026-01-03T00:00:00.000Z" }), { cwd: dir });
+
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records.map((r) => r.digest)).toEqual(["sha256:v1", "sha256:v2", "sha256:v3"]);
+      });
+    });
+
+    test("never mutates a previously written record — old lines survive new appends byte-identical", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendReleaseRecord(makeInput({ digest: "sha256:v1" }), { cwd: dir });
+        const { records: afterFirst } = await readReleaseLedger("prod", { cwd: dir });
+
+        await appendReleaseRecord(makeInput({ digest: "sha256:v2", component: "other-service" }), { cwd: dir });
+        const { records: afterSecond } = await readReleaseLedger("prod", { cwd: dir });
+
+        expect(afterSecond[0]).toEqual(afterFirst[0]);
+        expect(afterSecond).toHaveLength(2);
+      });
+    });
+
+    test("separate environments get separate ledgers", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendReleaseRecord(makeInput({ env: "staging", digest: "sha256:staging1" }), { cwd: dir });
+        await appendReleaseRecord(makeInput({ env: "prod", digest: "sha256:prod1" }), { cwd: dir });
+
+        const staging = await readReleaseLedger("staging", { cwd: dir });
+        const prod = await readReleaseLedger("prod", { cwd: dir });
+        expect(staging.records.map((r) => r.digest)).toEqual(["sha256:staging1"]);
+        expect(prod.records.map((r) => r.digest)).toEqual(["sha256:prod1"]);
+      });
+    });
+
+    test("release ledger and snapshot coexist on the same orphan branch without clobbering each other", async () => {
+      const { writeSnapshot, readSnapshot } = await import("./git");
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: dir });
+        await appendReleaseRecord(makeInput({ env: "prod" }), { cwd: dir });
+
+        expect(await readSnapshot("prod", "aws", { cwd: dir })).toBeTruthy();
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records).toHaveLength(1);
+      });
+    });
+  });
+
+  describe("readReleaseLedger", () => {
+    test("returns empty for an environment with no ledger", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const { records, malformed } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records).toEqual([]);
+        expect(malformed).toBe(0);
+      });
+    });
+  });
+
+  describe("listReleaseEnvironments", () => {
+    test("lists every environment carrying a release ledger", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendReleaseRecord(makeInput({ env: "prod" }), { cwd: dir });
+        await appendReleaseRecord(makeInput({ env: "staging" }), { cwd: dir });
+        expect(await listReleaseEnvironments({ cwd: dir })).toEqual(["prod", "staging"]);
+      });
+    });
+
+    test("returns empty when no orphan branch exists yet", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await listReleaseEnvironments({ cwd: dir })).toEqual([]);
+      });
+    });
+  });
+
+  describe("latestPerComponent", () => {
+    test("picks the record with the latest timestamp per component", () => {
+      const records: ReleaseRecord[] = [
+        { version: 1, ...makeInput({ digest: "sha256:v1", timestamp: "2026-01-01T00:00:00.000Z" }) },
+        { version: 1, ...makeInput({ digest: "sha256:v2", timestamp: "2026-01-03T00:00:00.000Z" }) },
+        { version: 1, ...makeInput({ digest: "sha256:v1-mid", timestamp: "2026-01-02T00:00:00.000Z" }) },
+      ];
+      const latest = latestPerComponent(records);
+      expect(latest.get("search-service")?.digest).toBe("sha256:v2");
+    });
+
+    test("keeps separate entries per component", () => {
+      const records: ReleaseRecord[] = [
+        { version: 1, ...makeInput({ component: "a", digest: "sha256:a1" }) },
+        { version: 1, ...makeInput({ component: "b", digest: "sha256:b1" }) },
+      ];
+      const latest = latestPerComponent(records);
+      expect(latest.get("a")?.digest).toBe("sha256:a1");
+      expect(latest.get("b")?.digest).toBe("sha256:b1");
+    });
+  });
+
+  describe("recordsForDigest", () => {
+    test("finds every record referencing a given digest", () => {
+      const records: ReleaseRecord[] = [
+        { version: 1, ...makeInput({ env: "staging", digest: "sha256:shared" }) },
+        { version: 1, ...makeInput({ env: "prod", digest: "sha256:shared" }) },
+        { version: 1, ...makeInput({ env: "prod", digest: "sha256:other" }) },
+      ];
+      const found = recordsForDigest(records, "sha256:shared");
+      expect(found).toHaveLength(2);
+      expect(found.every((r) => r.digest === "sha256:shared")).toBe(true);
+    });
+  });
+});

package/src/lifecycle/release-ledger.ts

@@ -0,0 +1,185 @@
+/**
+ * Release ledger — the recorded half of build & deploy observability (#568,
+ * epic #551 "Build & deploy observability").
+ *
+ * chant already has the *live-truth* half: ownership markers stamp stack/env
+ * identity on live resources, `lifecycle diff --live` / `lifecycle plan`
+ * compare declared vs live, and snapshots on `chant/lifecycle` give a
+ * forensic timeline (see ./snapshot.ts, ./live-diff.ts, ./change-set.ts).
+ * What was missing is the *record* half: "what we recorded deploying",
+ * independent of whether the thing is still running.
+ *
+ * A release record is immutable and append-only: each deploy appends one line
+ * to `<env>/releases.jsonl` on the `chant/lifecycle` orphan branch (see
+ * ./git.ts's `appendReleaseRecord`/`readReleaseLedger`) — never rewritten,
+ * never replaced in place, mirroring how the snapshot branch itself is
+ * treated as observational evidence rather than a mutable state file. The
+ * append-only property is what makes "which build was in staging on
+ * Tuesday" answerable months later even after staging has moved on to a
+ * dozen newer digests.
+ *
+ * The binding key is the artifact **digest** (`sha256:...`), the same
+ * identity `BuildArchive` manifests and `publish-image`/`load-image-on-host`
+ * promote by (see ../components/verbs/build-archive.ts,
+ * ../components/verbs/publish.ts). Because publish promotes by digest never
+ * rebuilding, the same identity threads build → dev → staging → prod, so
+ * "which build is in prod, and is it the one tested in staging" is a
+ * straightforward digest comparison over this ledger — never a guess through
+ * CI logs.
+ */
+
+import { sortedJsonReplacer } from "../utils";
+import { appendReleaseRecordLine, readReleaseLedgerLines, listLedgerEnvironments as gitListLedgerEnvironments } from "./git";
+
+/**
+ * One immutable deploy record: `(component, env, artifact digest, git sha,
+ * run id, timestamp, actor)`, referencing the build archive by digest — the
+ * exact shape epic #551 "Build & deploy observability" asks for.
+ */
+export interface ReleaseRecord {
+  /** Schema version, so an incompatible future shape can be detected before being misread. */
+  version: 1;
+  /** Component this deploy released (matches `Component.name`, ../components/component.ts). */
+  component: string;
+  /** Environment this deploy targeted. */
+  env: string;
+  /**
+   * Content-addressed digest of the promoted artifact (`sha256:...`) — the
+   * same digest `publish-image`/`load-image-on-host` return
+   * (`PublishImageOutput.digest`, ../components/verbs/publish.ts) and the
+   * one `BuildArchiveManifest` entries carry
+   * (../components/verbs/build-archive.ts). The join key for every query
+   * this ledger answers.
+   */
+  digest: string;
+  /** Git commit SHA the deploy was built from. */
+  gitSha: string;
+  /** Orchestrator run identifier (a `DriverRunResult`/Op run id, or a CI run id in generate mode) — the pointer back into the deploy event log. */
+  runId: string;
+  /**
+   * When this record was written. The caller supplies this — the session
+   * cannot call `Date.now()` reliably in every context, so the CLI resolves
+   * a real `new Date()` at record time and passes it in as an ISO-8601
+   * string; library code never defaults this internally.
+   */
+  timestamp: string;
+  /** Who/what triggered the deploy (a username, a CI actor, a service account). */
+  actor: string;
+  /** Optional: the archive's own manifest digest (../components/verbs/build-archive.ts's `manifestDigest`), when the caller has it — lets a reader recover full build contents/provenance, not just the promoted image digest. */
+  manifestDigest?: string;
+}
+
+/** Required, non-empty-string fields every `ReleaseRecord` must carry. */
+const REQUIRED_STRING_FIELDS: Array<keyof ReleaseRecord> = [
+  "component",
+  "env",
+  "digest",
+  "gitSha",
+  "runId",
+  "timestamp",
+  "actor",
+];
+
+/** Thrown by `appendReleaseRecord` when the record is missing a required field — a release record can never be recorded partially, since it is never editable afterward. */
+export class InvalidReleaseRecordError extends Error {
+  constructor(public readonly missing: string[]) {
+    super(`release record is missing required field(s): ${missing.join(", ")}`);
+    this.name = "InvalidReleaseRecordError";
+  }
+}
+
+/** Validate that a release record carries every required field as a non-empty string. */
+export function validateReleaseRecord(record: Partial<ReleaseRecord>): string[] {
+  const missing: string[] = [];
+  for (const field of REQUIRED_STRING_FIELDS) {
+    const value = record[field];
+    if (typeof value !== "string" || value.length === 0) missing.push(field);
+  }
+  return missing;
+}
+
+/** Input a caller supplies to record one deploy — `version` is filled in, everything else is required (see `ReleaseRecord`). */
+export type ReleaseRecordInput = Omit<ReleaseRecord, "version">;
+
+/**
+ * Append one immutable release record to the `<env>` ledger on the
+ * `chant/lifecycle` orphan branch. Throws `InvalidReleaseRecordError` before
+ * any git operation runs if a required field is missing — never partially
+ * records, since nothing about a release record is editable after the fact.
+ *
+ * Does not push to the remote; call `pushLifecycle` (./git.ts) afterward, the
+ * same two-step (`write` then `push`) shape `takeSnapshot` (./snapshot.ts)
+ * uses, so a caller recording several releases in one run can batch the push.
+ */
+export async function appendReleaseRecord(
+  input: ReleaseRecordInput,
+  opts?: { cwd?: string },
+): Promise<{ commit: string; record: ReleaseRecord }> {
+  const missing = validateReleaseRecord(input);
+  if (missing.length > 0) throw new InvalidReleaseRecordError(missing);
+
+  const record: ReleaseRecord = { version: 1, ...input };
+  const json = JSON.stringify(record, sortedJsonReplacer);
+  const commit = await appendReleaseRecordLine(record.env, json, opts);
+  return { commit, record };
+}
+
+/**
+ * Read every release record for `environment`, oldest first. Malformed lines
+ * (a hand-edited or corrupted ledger) are skipped rather than throwing, since
+ * a status query should degrade gracefully rather than fail outright on one
+ * bad line — but each skip is reported so callers/tests can surface it.
+ */
+export async function readReleaseLedger(
+  environment: string,
+  opts?: { cwd?: string },
+): Promise<{ records: ReleaseRecord[]; malformed: number }> {
+  const lines = await readReleaseLedgerLines(environment, opts);
+  const records: ReleaseRecord[] = [];
+  let malformed = 0;
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line) as ReleaseRecord;
+      if (validateReleaseRecord(parsed).length > 0) {
+        malformed++;
+        continue;
+      }
+      records.push(parsed);
+    } catch {
+      malformed++;
+    }
+  }
+  return { records, malformed };
+}
+
+/** List every environment that has release records on the orphan branch. */
+export async function listReleaseEnvironments(opts?: { cwd?: string }): Promise<string[]> {
+  return gitListLedgerEnvironments(opts);
+}
+
+/**
+ * The latest release record per component in `records` — "what we recorded
+ * deploying" reduces to one row per component by taking the most recent
+ * `timestamp` (ties broken by ledger order, i.e. later append wins), since
+ * a component may have many historical records in one environment's ledger.
+ */
+export function latestPerComponent(records: ReleaseRecord[]): Map<string, ReleaseRecord> {
+  const latest = new Map<string, ReleaseRecord>();
+  for (const record of records) {
+    const current = latest.get(record.component);
+    if (!current || record.timestamp >= current.timestamp) {
+      latest.set(record.component, record);
+    }
+  }
+  return latest;
+}
+
+/**
+ * Find every release record across `records` that references `digest` — the
+ * cross-environment query "is the build in prod the one tested in staging"
+ * reduces to: read both envs' ledgers, then check whether the same digest
+ * appears in each. Sorted oldest first, matching ledger order.
+ */
+export function recordsForDigest(records: ReleaseRecord[], digest: string): ReleaseRecord[] {
+  return records.filter((r) => r.digest === digest);
+}