@intentius/chant 0.124.26 → 0.124.28

package/src/workspace/releases.schema.json

@@ -0,0 +1,391 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/releases/v1/releases.schema.json",
+  "title": "chant release list output",
+  "description": "What `chant release list --json` prints (#4026, ws-104): every release of one member, each the compiled output of one green commit, with its artifact digests, one target per environment, its cuts and the environments that run it. It reads the local chant/lifecycle branch and never fetches. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.124.28 and newer; the read contract as a whole by chant 0.81.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "Exit code 0, with or without releases.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "member",
+        "releases",
+        "reason"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/releases/v1/releases.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": false,
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The workspace member read, its path of names joined with / when nested, or null for a project outside a workspace (the flat ledger layout)."
+        },
+        "releases": {
+          "type": "array",
+          "description": "Newest cut first. A release stored with no cut comes last.",
+          "items": {
+            "$ref": "#/$defs/release"
+          }
+        },
+        "reason": {
+          "description": "Null when everything was read. ledger-malformed when some release files or cut lines could not be read; the rest are listed.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "code",
+                "message"
+              ],
+              "properties": {
+                "code": {
+                  "enum": [
+                    "ledger-malformed"
+                  ]
+                },
+                "message": {
+                  "type": "string"
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "release": {
+      "type": "object",
+      "required": [
+        "releaseDigest",
+        "label",
+        "member",
+        "commit",
+        "artifactDigests",
+        "targets",
+        "cuts",
+        "environments"
+      ],
+      "properties": {
+        "releaseDigest": {
+          "type": "string",
+          "pattern": "^(jcs1-)?sha256:[0-9a-f]{64}$",
+          "description": "computePlanDigest(\"release\", subject) over member, commit, artifactDigests, and each target's env, templates and the name and value of each param. The file is _releases/<releaseDigest>.json on chant/lifecycle, with : written as _."
+        },
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The release's label, from its cuts, or null. A label names one release in a member and a release takes at most one label."
+        },
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The full sha of the green commit the release was cut from."
+        },
+        "artifactDigests": {
+          "type": "array",
+          "description": "Each image and asset built once from the commit, sorted by component, then path. A config-only release carries the previous release's entries.",
+          "items": {
+            "type": "object",
+            "required": [
+              "component",
+              "kind",
+              "path",
+              "digest"
+            ],
+            "properties": {
+              "component": {
+                "type": "string"
+              },
+              "kind": {
+                "enum": [
+                  "image",
+                  "asset"
+                ]
+              },
+              "path": {
+                "type": "string"
+              },
+              "digest": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "targets": {
+          "type": "array",
+          "description": "One per environment the member declares, sorted by env.",
+          "items": {
+            "$ref": "#/$defs/target"
+          }
+        },
+        "cuts": {
+          "type": "array",
+          "description": "Each cut of the release, oldest first.",
+          "items": {
+            "$ref": "#/$defs/cut"
+          }
+        },
+        "environments": {
+          "type": "array",
+          "description": "The environments that run the release, sorted by env: in each, the components whose latest deploy record names this release in releaseDigest. A promote with --release writes that field. An environment can run components of several releases.",
+          "items": {
+            "type": "object",
+            "required": [
+              "env",
+              "components"
+            ],
+            "properties": {
+              "env": {
+                "type": "string"
+              },
+              "components": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "target": {
+      "type": "object",
+      "required": [
+        "env",
+        "templates",
+        "params"
+      ],
+      "properties": {
+        "env": {
+          "type": "string"
+        },
+        "templates": {
+          "type": "array",
+          "description": "The files the environment's deploys read, compiled for it, sorted by component, then path.",
+          "items": {
+            "type": "object",
+            "required": [
+              "component",
+              "path",
+              "digest"
+            ],
+            "properties": {
+              "component": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The component whose deploy reads it, or null for a project with no components."
+              },
+              "path": {
+                "type": "string",
+                "description": "The path the deploy step names, relative to the member's directory."
+              },
+              "digest": {
+                "type": "string",
+                "pattern": "^(jcs1-)?sha256:[0-9a-f]{64}$",
+                "description": "sha256 of the file's bytes."
+              }
+            }
+          }
+        },
+        "params": {
+          "type": "array",
+          "description": "The resolved build parameters the environment was compiled with, sorted by name. source is outside the release digest.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "value",
+              "source"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "value": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  }
+                ]
+              },
+              "source": {
+                "type": "string",
+                "description": "cli, params-file, env or default."
+              }
+            }
+          }
+        }
+      }
+    },
+    "cut": {
+      "type": "object",
+      "required": [
+        "label",
+        "actor",
+        "timestamp",
+        "runOrigin",
+        "signature"
+      ],
+      "properties": {
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "actor": {
+          "type": "string"
+        },
+        "timestamp": {
+          "type": "string",
+          "description": "ISO 8601."
+        },
+        "runOrigin": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "forge"
+              ],
+              "properties": {
+                "forge": {
+                  "enum": [
+                    "github",
+                    "gitlab",
+                    "op",
+                    "local"
+                  ]
+                },
+                "repo": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string"
+                }
+              }
+            }
+          ],
+          "description": "The CI run the cut ran in: the forge (github for GitHub and Forgejo, gitlab), the repo or project, and a link to the run. Null outside CI."
+        },
+        "signature": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Added by #4031, written by chant 0.124.28 and newer. The cut's armored ssh signature (ssh-keygen -Y sign, namespace chant-release) by the actor's key, over the release digest, the label (empty for none), the actor and the timestamp, joined by LF with no final newline. Null for an unsigned cut. A reader checks it against .chant/allowed_signers at base; signatureCheck is chant's own check."
+        },
+        "signatureCheck": {
+          "type": "object",
+          "description": "Added within contract version 1 by #4031, written by chant 0.124.28 and newer. Whether signature verifies for actor against the signers file at base and, when the declaration at base names a release gate in identity.gates with a class, whether the role grants in .chant/trust.json at base put actor in it. Judged on every read.",
+          "required": [
+            "status",
+            "key",
+            "reason"
+          ],
+          "properties": {
+            "status": {
+              "enum": [
+                "verified",
+                "unsigned",
+                "unverified"
+              ],
+              "description": "verified: the signature verifies, and the actor is in the release gate's class when it names one. unsigned: the cut has no signature. unverified: it has one that does not count, and reason says why."
+            },
+            "key": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "The fingerprint (SHA256:...) of the key in the signature, or null for an unsigned cut or a signature that can't be read. Reported, never trusted."
+            },
+            "reason": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was read. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/releases/v1/releases.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "not-a-git-repository",
+                "ledger-unreadable"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/workspace/releases.test.ts

@@ -0,0 +1,108 @@
+/**
+ * The `releases` read (#4026, ws-104): releases with their targets, cuts and
+ * the environments that run them, held to `releases.schema.json`.
+ */
+
+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 { contract } from "./__fixtures__/contract-repo";
+import releasesSchema from "./releases.schema.json";
+import { releasesDocument, RELEASES_SCHEMA_ID } from "./releases";
+import { appendCut, makeRelease, persistRelease } from "../lifecycle/release-store";
+import { appendReleaseRecord } from "../lifecycle/release-ledger";
+import { writeLedgerFiles } from "../lifecycle/git";
+
+const { expectValid } = contract(releasesSchema);
+
+function initRepo(dir: string): void {
+  for (const args of [["init", "-q", "-b", "main"], ["config", "user.email", "t@chant.dev"], ["config", "user.name", "T"]]) spawnSync("git", args, { cwd: dir });
+  writeFileSync(join(dir, "README.md"), "x\n");
+  spawnSync("git", ["add", "."], { cwd: dir });
+  spawnSync("git", ["commit", "-q", "-m", "init"], { cwd: dir });
+}
+
+const release = (commit: string) =>
+  makeRelease({
+    member: null,
+    commit,
+    artifactDigests: [{ component: "api", kind: "image", path: "api.tar", digest: `sha256:${"a".repeat(64)}` }],
+    targets: [
+      { env: "staging", templates: [{ component: "api", path: "t.json", digest: `sha256:${"b".repeat(64)}` }], params: [{ name: "tier", value: "small", source: "default" }] },
+      { env: "prod", templates: [{ component: "api", path: "t.json", digest: `sha256:${"c".repeat(64)}` }], params: [{ name: "tier", value: "large", source: "default" }] },
+    ],
+  });
+
+const deploy = (env: string, component: string, releaseDigest?: string, timestamp = "2026-10-16T12:00:00.000Z") =>
+  appendReleaseRecord({ component, env, digest: `sha256:${"a".repeat(64)}`, gitSha: "1".repeat(40), runId: "r", timestamp, actor: "ci", ...(releaseDigest ? { releaseDigest } : {}) }, { cwd: dirOf.current });
+const dirOf = { current: "" };
+
+describe("releasesDocument", () => {
+  test("lists each release with its targets, cuts and the environments whose latest deploy names it", async () => {
+    await withTestDir(async (dir) => {
+      dirOf.current = dir;
+      initRepo(dir);
+      const r1 = release("1".repeat(40));
+      const r2 = release("2".repeat(40));
+      await persistRelease(r1, [], { cwd: dir });
+      await persistRelease(r2, [], { cwd: dir });
+      await appendCut({ releaseDigest: r1.releaseDigest, label: "v1", actor: "alice", timestamp: "2026-10-16T10:00:00.000Z", runOrigin: null }, { cwd: dir });
+      await appendCut({ releaseDigest: r2.releaseDigest, label: "v2", actor: "bob", timestamp: "2026-10-16T11:00:00.000Z", runOrigin: { forge: "github", repo: "o/r" } }, { cwd: dir });
+      await deploy("staging", "api", r2.releaseDigest);
+      await deploy("prod", "api", r1.releaseDigest);
+      await deploy("staging", "web");
+
+      const doc = await releasesDocument({ cwd: dir });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc).toMatchObject({ $schema: RELEASES_SCHEMA_ID, contract: 1, member: null, reason: null });
+      expect(doc.releases.map((r) => [r.label, r.environments])).toEqual([
+        ["v2", [{ env: "staging", components: ["api"] }]],
+        ["v1", [{ env: "prod", components: ["api"] }]],
+      ]);
+      expect(doc.releases[0]).toMatchObject({
+        releaseDigest: r2.releaseDigest,
+        commit: "2".repeat(40),
+        artifactDigests: r2.artifactDigests,
+        targets: r2.targets,
+        cuts: [{ label: "v2", actor: "bob", timestamp: "2026-10-16T11:00:00.000Z", runOrigin: { forge: "github", repo: "o/r" }, signature: null }],
+      });
+    });
+  });
+
+  test("a release file that is not a release and a cut line that is not a cut are left out under ledger-malformed", async () => {
+    await withTestDir(async (dir) => {
+      dirOf.current = dir;
+      initRepo(dir);
+      const r = release("3".repeat(40));
+      await persistRelease(r, [], { cwd: dir });
+      await writeLedgerFiles(
+        [
+          { path: `_releases/jcs1-sha256_${"9".repeat(64)}.json`, content: "{not json" },
+          { path: "_releases/cuts.jsonl", content: `{"version":1}\n` },
+        ],
+        "broken",
+        { cwd: dir },
+      );
+      const doc = await releasesDocument({ cwd: dir });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.releases.map((x) => x.releaseDigest)).toEqual([r.releaseDigest]);
+      expect(doc.reason).toEqual({ code: "ledger-malformed", message: "1 release file(s) and 1 cut line(s) could not be read and are left out" });
+    });
+  });
+
+  test("an empty ledger lists no releases, and outside git the read fails with not-a-git-repository", async () => {
+    await withTestDir(async (dir) => {
+      const outside = await releasesDocument({ cwd: dir });
+      expectValid(outside);
+      expect(outside).toMatchObject({ error: { code: "not-a-git-repository" } });
+      initRepo(dir);
+      const empty = await releasesDocument({ cwd: dir });
+      expectValid(empty);
+      expect(empty).toMatchObject({ releases: [], reason: null });
+    });
+  });
+});

package/src/workspace/releases.ts

@@ -0,0 +1,122 @@
+/**
+ * The `releases` read (#4026, ws-104): every release of one member with its
+ * targets, its cuts, and the environments that run it.
+ *
+ * `chant release list --json` prints this document. It reads the local
+ * `chant/lifecycle` branch and never fetches. An environment runs a release
+ * for the components whose latest deploy record there names the release in
+ * `releaseDigest`. A promote under a release writes that field; deploys made
+ * any other way do not name a release yet (#4043), so they list nowhere.
+ *
+ * Each cut carries `signatureCheck` (#4031): whether its signature verifies
+ * for its actor against the signers at base, and, when the declaration names
+ * a `release` gate with a class, whether the actor is in it.
+ *
+ * A release file that is not a release, or whose content does not hash to its
+ * digest, and a cut line that is not a cut, are left out and counted under
+ * `reason` with `ledger-malformed`; the rest are listed. A read that fails
+ * outright is the failure `ledger-unreadable`.
+ */
+
+import { execFileSync } from "node:child_process";
+import { latestPerComponent, listReleaseEnvironments, readReleaseLedger } from "../lifecycle/release-ledger";
+import { readAllReleases, readCuts, type Release, type ReleaseCut } from "../lifecycle/release-store";
+import { resolveMemberLedger } from "../lifecycle/member-ledger";
+import { readerVersion } from "./declaration";
+import { checkReleaseSignature, type GateAdmissionRule, type ReleaseSignatureCheck } from "./identity-gate-rule";
+
+export const RELEASES_CONTRACT_VERSION = 1;
+export const RELEASES_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/releases/v1/releases.schema.json";
+
+/** Why the read stopped. Closed; each code is in `reason-codes.ts`. */
+export const RELEASES_ERROR_CODES = ["not-a-git-repository", "ledger-unreadable"] as const;
+/** Why some entries were left out. */
+export const RELEASES_REASON_CODES = ["ledger-malformed"] as const;
+
+/** One release as the document lists it. */
+export interface ReleaseEntry extends Omit<Release, "version"> {
+  /** The label its cuts gave it, or null. */
+  label: string | null;
+  /** Its cuts, oldest first, each with whether its signature verifies against the signers at base (#4031). */
+  cuts: Array<Omit<ReleaseCut, "version" | "releaseDigest"> & { signatureCheck: ReleaseSignatureCheck }>;
+  /** The environments that run it, and in each the components whose latest deploy names it. Sorted by env. */
+  environments: Array<{ env: string; components: string[] }>;
+}
+
+export type ReleasesDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      /** The member read, its path of names joined with `/`, or null for a project outside a workspace. */
+      member: string | null;
+      /** Newest cut first; a release with no cut comes last. */
+      releases: ReleaseEntry[];
+      reason: { code: (typeof RELEASES_REASON_CODES)[number]; message: string } | null;
+    }
+  | { $schema: string; contract: number; chant: string; error: { code: (typeof RELEASES_ERROR_CODES)[number]; message: string } };
+
+/**
+ * The rule a cut's signature is judged by (#4031): the declaration's
+ * `identity.gates.release` and the signers and role grants, all read at base.
+ */
+export async function releaseRule(cwd: string): Promise<GateAdmissionRule> {
+  const { scopeSource } = await import("./write-scope");
+  const { releaseRuleFrom } = await import("./identity");
+  return releaseRuleFrom(scopeSource(cwd)).rule;
+}
+
+/** Read the releases of the member at `cwd`. */
+export async function releasesDocument(req: { cwd: string }): Promise<ReleasesDocument> {
+  const head = { $schema: RELEASES_SCHEMA_ID, contract: RELEASES_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    execFileSync("git", ["rev-parse", "--git-dir"], { cwd: req.cwd, stdio: "ignore" });
+  } catch {
+    return { ...head, error: { code: "not-a-git-repository", message: "releases are read from the chant/lifecycle branch, and this directory is not in a git repository" } };
+  }
+  try {
+    const ledger = await resolveMemberLedger(req.cwd);
+    const loc = { cwd: req.cwd };
+    const { releases, malformed: badReleases } = await readAllReleases(loc);
+    const { cuts, malformed: badCuts } = await readCuts(loc);
+
+    const running = new Map<string, Map<string, string[]>>();
+    for (const env of await listReleaseEnvironments(loc)) {
+      const { records } = await readReleaseLedger(env, loc);
+      for (const record of latestPerComponent(records).values()) {
+        const digest = (record as { releaseDigest?: unknown }).releaseDigest;
+        if (typeof digest !== "string") continue;
+        const envs = running.get(digest) ?? new Map<string, string[]>();
+        envs.set(env, [...(envs.get(env) ?? []), record.component].sort());
+        running.set(digest, envs);
+      }
+    }
+
+    const rule = await releaseRule(req.cwd);
+    const entries: ReleaseEntry[] = releases.map(({ version: _v, ...release }) => {
+      const own = cuts.filter((c) => c.releaseDigest === release.releaseDigest);
+      return {
+        ...release,
+        label: own.find((c) => c.label !== null)?.label ?? null,
+        cuts: own.map(({ version: _cv, releaseDigest: _d, ...cut }) => ({ ...cut, signatureCheck: checkReleaseSignature(rule, { releaseDigest: release.releaseDigest, ...cut }) })),
+        environments: [...(running.get(release.releaseDigest) ?? new Map<string, string[]>())]
+          .map(([env, components]) => ({ env, components }))
+          .sort((a, b) => (a.env < b.env ? -1 : 1)),
+      };
+    });
+    const latest = (e: ReleaseEntry): string => e.cuts.map((c) => c.timestamp).sort().at(-1) ?? "";
+    entries.sort((a, b) => (latest(b) !== latest(a) ? (latest(b) < latest(a) ? -1 : 1) : a.releaseDigest < b.releaseDigest ? -1 : 1));
+
+    const bad = badReleases + badCuts;
+    return {
+      ...head,
+      member: ledger.members.length > 0 ? ledger.members.join("/") : null,
+      releases: entries,
+      reason: bad > 0
+        ? { code: "ledger-malformed", message: `${badReleases} release file(s) and ${badCuts} cut line(s) could not be read and are left out` }
+        : null,
+    };
+  } catch (err) {
+    return { ...head, error: { code: "ledger-unreadable", message: `reading the releases failed: ${err instanceof Error ? err.message : String(err)}` } };
+  }
+}