@intentius/chant 0.124.46 → 0.124.49

package/src/workspace/checks/org.ts

@@ -0,0 +1,169 @@
+/**
+ * Org scope (#3168): members of kind `repo`, which name another repository's
+ * workspace by URL and pinned revision, and the org-level workspace that
+ * holds only such members.
+ *
+ * | Id | Check |
+ * |---|---|
+ * | WSP013 | an org workspace holds only repo members |
+ * | WSP014 | every repository the forge lists is declared (with `--forge-repos`) |
+ * | WSP015 | every declared repository is one the forge lists (with `--forge-repos`) |
+ * | WSP016 | no repo member's URL carries a password or token |
+ *
+ * The forge's list is input, never fetched here: a warden enumerates the
+ * org's repositories from its own API and hands the list to
+ * `chant workspace check --forge-repos <file>`, so the check stays offline.
+ */
+
+import { isAbsolute, resolve } from "node:path";
+import { REPO_KIND } from "../kinds";
+import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
+
+/** One repository the forge lists. */
+export interface ForgeRepo {
+  url: string;
+  /** An archived repository need not be declared, and declaring one is not a drop. */
+  archived: boolean;
+}
+
+/** The forge's repository list for `--forge-repos` (#3168), as a warden writes it. */
+export interface ForgeRepoList {
+  /** The file it was read from, for messages. */
+  source: string;
+  repos: ForgeRepo[];
+}
+
+/**
+ * Parse a forge repository list. Three shapes are read: `{ "repos": [...] }`
+ * (a warden may add `forge` and `org` beside it), a bare array, and, for each
+ * repository, a URL string or `{ "url", "archived"? }`. Throws an Error that
+ * says what is wrong.
+ */
+export function parseForgeRepos(text: string, source: string): ForgeRepoList {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    throw new Error(`${source} is not JSON (${(err as Error).message})`);
+  }
+  const list = Array.isArray(raw) ? raw : raw !== null && typeof raw === "object" && Array.isArray((raw as { repos?: unknown }).repos) ? (raw as { repos: unknown[] }).repos : undefined;
+  if (!list) throw new Error(`${source} is neither an array of repositories nor an object with a repos array`);
+  const repos = list.map((r, i): ForgeRepo => {
+    if (typeof r === "string" && r.length > 0) return { url: r, archived: false };
+    if (r !== null && typeof r === "object" && typeof (r as { url?: unknown }).url === "string") {
+      return { url: (r as { url: string }).url, archived: (r as { archived?: unknown }).archived === true };
+    }
+    throw new Error(`${source}: repos[${i}] is neither a URL nor an object with a url`);
+  });
+  return { source, repos };
+}
+
+/**
+ * A repository URL reduced to what names the repository, so the forge's
+ * https URL and a declaration's ssh or scp-style URL compare equal:
+ * `host/owner/repo`, lowercased, with no scheme, user, port, `.git` or
+ * trailing slash. A local path or file URL becomes its absolute path,
+ * resolved from `base`.
+ */
+export function repoKey(url: string, base: string = process.cwd()): string {
+  const trimmed = url.trim();
+  const scp = /^(?:[^@/\s]+@)?([^:/\s]+):(?!\/\/)(.+)$/.exec(trimmed);
+  let hostPath: string | undefined;
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+    let u: URL;
+    try {
+      u = new URL(trimmed);
+    } catch {
+      return trimmed.toLowerCase();
+    }
+    if (u.protocol === "file:") return stripGit(decodeURIComponent(u.pathname));
+    hostPath = `${u.hostname}${u.pathname}`;
+  } else if (scp && !isAbsolute(trimmed) && !/^[a-z]:[\\/]/i.test(trimmed)) {
+    hostPath = `${scp[1]}/${scp[2]}`;
+  } else {
+    return stripGit(resolve(base, trimmed));
+  }
+  return stripGit(hostPath.replace(/\/+/g, "/")).toLowerCase();
+}
+
+function stripGit(path: string): string {
+  return path.replace(/\/+$/, "").replace(/\.git$/, "");
+}
+
+/** Whether a URL carries a password or token, which a declaration must never hold. */
+export function urlCredential(url: string): boolean {
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) return false;
+  try {
+    const u = new URL(url);
+    // ssh://git@host is a user name, not a secret; a password, or any user on http(s), is one.
+    return u.password !== "" || (u.username !== "" && /^https?:$/.test(u.protocol));
+  } catch {
+    return false;
+  }
+}
+
+const repoMembers = (ctx: Parameters<WorkspaceCheck["check"]>[0]) => ctx.declaration.members.filter((m) => m.kind === REPO_KIND && m.repo !== null);
+
+function finding(check: WorkspaceCheck, message: string, pointer: string, entity?: string): WorkspaceDiagnostic {
+  return { checkId: check.id, severity: check.severity, message, pointer, ...(entity !== undefined ? { entity } : {}) };
+}
+
+export const ORG_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: "WSP013",
+    name: "org-member-local",
+    description: "An org workspace (scope org) holds only members of kind repo, each a reference to another repository's workspace (#3168).",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      if (ctx.declaration.scope !== "org") return [];
+      return ctx.declaration.entries
+        .filter((e) => e.kind !== REPO_KIND)
+        .map((e) =>
+          finding(this, `${e.type === "group" ? "example group" : "member"} ${e.name} is kind ${e.kind}, and an org workspace holds only repo members; move it into a repository's own workspace and reference that`, `${e.pointer}/kind`, e.name),
+        );
+    },
+  },
+  {
+    id: "WSP014",
+    name: "org-repo-undeclared",
+    description: "With --forge-repos, every repository the forge lists, archived ones aside, is named by a repo member (#3168).",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const forge = ctx.facts?.forgeRepos;
+      if (!forge) return [];
+      const declared = new Set(repoMembers(ctx).map((m) => repoKey(m.repo!.url)));
+      return forge.repos
+        .filter((r) => !r.archived && !declared.has(repoKey(r.url)))
+        .map((r) => finding(this, `the forge lists ${r.url} (${forge.source}), and no repo member names it; add a member of kind repo with its url and pinned rev`, "/members"));
+    },
+  },
+  {
+    id: "WSP015",
+    name: "org-repo-dropped",
+    description: "With --forge-repos, every repository a repo member names is one the forge still lists (#3168).",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      const forge = ctx.facts?.forgeRepos;
+      if (!forge) return [];
+      const listed = new Set(forge.repos.map((r) => repoKey(r.url)));
+      return repoMembers(ctx)
+        .filter((m) => !listed.has(repoKey(m.repo!.url)))
+        .map((m) => finding(this, `member ${m.name} names ${m.repo!.url}, which the forge no longer lists (${forge.source}); remove the member or say why it stays`, `${m.pointer}/repo/url`, m.name));
+    },
+  },
+  {
+    id: "WSP016",
+    name: "repo-url-credential",
+    description: "No repo member's URL carries a password or token: the declaration is committed, and git's own credential helpers supply access (#3168).",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return repoMembers(ctx)
+        .filter((m) => urlCredential(m.repo!.url))
+        .map((m) => finding(this, `member ${m.name}'s repo url carries a credential; name the repository without one and let git's credential helper supply access`, `${m.pointer}/repo/url`, m.name));
+    },
+  },
+];

package/src/workspace/checks.ts

@@ -21,7 +21,8 @@
  *
  * | Ids | Checks |
  * |---|---|
- * | WSP001 to WSP011 | the declaration and member kinds (this file) |
+ * | WSP001 to WSP012 | the declaration and member kinds (this file), and a member's file against its kind's schema (#3672) |
+ * | WSP013 to WSP016 | org scope: repo members and the org workspace, checked against the forge's list with `--forge-repos` (#3168) |
  * | WSP071, WSP072 | member ledgers |
  * | WSP081 to WSP083 | recorded pipelines |
  * | WSP091 to WSP099 | member links (#2539, #2558), and those a kind's reader finds in a member's files (#3932) |
@@ -38,6 +39,8 @@
  * | WSP141, WSP142 | member links resolved against a live read, with `--live` (#2549) |
  * | WSP131 to WSP133 | diagram artifacts: source and render exist, a recorded source hash still matches (#2764) |
  * | WSP151 | what a member under `ci.workflow` still lacks (#4168 step 6) |
+ * | WSP152 | a member's generated pipeline targets the branch `ci.branches` routes it to (#4325) |
+ * | WSP153 | an Op gate's approval block that `identity.gates` does not set at base (#4404) |
  * | WSP161 to WSP165 | the security groups the declaration opts into: what each still lacks (#4168 step 7) |
  */
 
@@ -48,7 +51,7 @@ import type { PostSynthDiagnostic } from "../lint/post-synth";
 import { readDeclaration, resolveGroups, WorkspaceReadError, type Declaration, type Entry, type ErrorLocation, type ResolvedGroup } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
-import { loadKindRegistry, probeKind, resolveKind, resolveMemberFields, type KindLoadProblem, type KindRegistry } from "./kinds";
+import { checkMemberFile, loadKindRegistry, probeKind, REPO_KIND, resolveKind, resolveMemberFields, type KindLoadProblem, type KindRegistry } from "./kinds";
 import { coreClassRegistry, loadClassRegistry, unknownScopeClasses, type ClassRegistry } from "./principal-classes";
 import { gitTop, workingTree, type WorkspaceTree } from "./tree";
 import { LINK_CHECKS, linkTable } from "./checks/links";
@@ -62,9 +65,13 @@ import { BOX_CHECKS } from "./checks/boxes";
 import { DIAGRAM_CHECKS } from "./checks/diagrams";
 import { SECURITY_CHECKS } from "./checks/security";
 import { CI_WORKFLOW_CHECKS } from "./checks/ci-workflow";
+import { CI_BRANCH_CHECKS } from "./checks/ci-branch";
+import { GATE_APPROVAL_CHECKS } from "./checks/gate-approval";
+import { ORG_CHECKS, type ForgeRepoList } from "./checks/org";
 import { loadDeclaredKinds, type DeclaredKind } from "./declared-kinds";
 import { resolveBoxIntents, type ResolvedBoxIntent } from "./box-intent";
-import { gatherLexiconOutputs, type MemberLexiconOutputs } from "./lexicon-outputs";
+import { gatherLexiconLinks, gatherLexiconOutputs, type MemberLexiconOutputs } from "./lexicon-outputs";
+import type { KindLinkRead } from "./kind-link-readers";
 
 /**
  * What the checks beyond the declaration read, gathered from the checkout
@@ -88,6 +95,10 @@ export interface WorkspaceFacts {
   boxIntents?: readonly ResolvedBoxIntent[];
   /** The outputs linked members' lexicons report about their declarations, read by folding their source (#3931). */
   lexiconOutputs?: ReadonlyMap<string, MemberLexiconOutputs>;
+  /** The links members' lexicons read from their declarations, such as an otel clickhouse exporter's tables (#4397). */
+  lexiconLinks?: ReadonlyMap<string, KindLinkRead>;
+  /** The forge's repository list, from `--forge-repos` (#3168). */
+  forgeRepos?: ForgeRepoList;
 }
 
 /** What every declaration check reads. */
@@ -174,9 +185,9 @@ function entryFinding(check: WorkspaceCheck, entry: Entry, field: string | null,
   };
 }
 
-/** The dir exists and the kind is known: the members every probe check reads. */
+/** The dir exists and the kind is known: the members every probe check reads. A repo member has no directory here (#3168). */
 function readableMembers(ctx: WorkspaceCheckContext) {
-  return ctx.declaration.members.filter((m) => ctx.tree.stat(memberDir(m.dir)) === "dir" && ctx.kinds.get(m.kind) !== undefined);
+  return ctx.declaration.members.filter((m) => m.kind !== REPO_KIND && ctx.tree.stat(memberDir(m.dir)) === "dir" && ctx.kinds.get(m.kind) !== undefined);
 }
 
 /** The first id of the read failure, used by {@link runDeclarationChecks} when the declaration can't be read. */
@@ -240,7 +251,7 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
     configurable: true,
     check(ctx) {
       return ctx.declaration.members
-        .filter((m) => ctx.tree.stat(memberDir(m.dir)) !== "dir")
+        .filter((m) => m.kind !== REPO_KIND && ctx.tree.stat(memberDir(m.dir)) !== "dir")
         .map((m) => entryFinding(this, m, "dir", `member ${m.name}'s directory ${m.dir} does not exist${ctx.tree.label}`));
     },
   },
@@ -359,6 +370,43 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
       return out;
     },
   },
+  {
+    id: "WSP012",
+    name: "member-file-invalid",
+    description: "Every member of a kind that names a member file has that file, and it passes the kind's JSON Schema (#3672).",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of readableMembers(ctx)) {
+        const kind = ctx.kinds.get(m.kind)!;
+        const mf = kind.memberFile;
+        if (!mf) continue;
+        const file = memberDir(m.dir) === "" ? mf.path : `${memberDir(m.dir)}/${mf.path}`;
+        if (!mf.validate) {
+          out.push(entryFinding(this, m, "kind", `member ${m.name}'s ${mf.path} can't be checked: kind ${m.kind}'s schema ${mf.schema} did not load (see WSP002)`));
+          continue;
+        }
+        if (ctx.tree.stat(file) !== "file") {
+          out.push(entryFinding(this, m, "dir", `member ${m.name} (${m.dir}) has no ${mf.path}, which kind ${m.kind} requires${ctx.tree.label}`));
+          continue;
+        }
+        let text: string;
+        try {
+          text = ctx.tree.read(file);
+        } catch (err) {
+          out.push(entryFinding(this, m, "dir", `member ${m.name}'s ${mf.path} can't be read: ${(err as Error).message}`));
+          continue;
+        }
+        for (const p of checkMemberFile(mf, mf.path, text)) {
+          out.push({ ...entryFinding(this, m, null, `member ${m.name}'s ${mf.path} fails kind ${m.kind}'s schema ${mf.schema}: ${p.message}`), treeFile: file, line: 1, column: 1 });
+        }
+      }
+      return out;
+    },
+  },
+  // Org scope (#3168), WSP013 to WSP016.
+  ...ORG_CHECKS,
   // Member ledgers (#2538).
   ...LEDGER_CHECKS,
   // Recorded pipelines (#2542).
@@ -377,6 +425,10 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   ...LIVE_CHECKS,
   // What a member under ci.workflow still lacks (#4168 step 6), WSP151.
   ...CI_WORKFLOW_CHECKS,
+  // A member's pipeline targets the branch ci.branches routes it to (#4325), WSP152.
+  ...CI_BRANCH_CHECKS,
+  // An Op gate's approval block that identity.gates does not set at base (#4404), WSP153.
+  ...GATE_APPROVAL_CHECKS,
   // The security groups the declaration opts into (#4168 step 7), WSP161 to WSP165.
   ...SECURITY_CHECKS,
 ];
@@ -463,6 +515,8 @@ export interface DeclarationCheckOptions {
    * account now. `onStderr` gets each member's stderr.
    */
   live?: { env: string; onStderr?: (text: string) => void };
+  /** The forge's repository list, from `--forge-repos` (#3168), for WSP014 and WSP015. Read under `--at` too: it is input, not the tree. */
+  forgeRepos?: ForgeRepoList;
 }
 
 /**
@@ -534,12 +588,19 @@ export async function runDeclarationChecks(
   // A box's intent is read from the working tree's records, so not under --at (#2850).
   const boxIntents = declaredKinds && !options.tree ? await resolveBoxIntents(declaration, root, declaredKinds) : undefined;
   // A linked member's lexicons name its tables and columns as outputs (#3931); reading them folds its source, never runs it.
+  // A member's lexicons may also read other members' outputs from its declarations (#4397); their targets are read too.
+  const outputsTree = options.tree ? workingTree(root) : tree;
+  const lexiconLinks = options.gather === false ? undefined : await gatherLexiconLinks(root, declaration, outputsTree, groups, registry, { atRevision: options.tree !== undefined });
   const lexiconOutputs =
-    options.gather === false ? undefined : await gatherLexiconOutputs(root, declaration, options.tree ? workingTree(root) : tree, groups, registry, { atRevision: options.tree !== undefined });
+    options.gather === false
+      ? undefined
+      : await gatherLexiconOutputs(root, declaration, outputsTree, groups, registry, { atRevision: options.tree !== undefined, ...(lexiconLinks ? { lexiconLinks } : {}) });
   const facts: WorkspaceFacts = {
     ...(lexiconOutputs && lexiconOutputs.size > 0 ? { lexiconOutputs } : {}),
+    ...(lexiconLinks && lexiconLinks.size > 0 ? { lexiconLinks } : {}),
     ...gathered,
     ...(options.records ? { records: options.records } : {}),
+    ...(options.forgeRepos ? { forgeRepos: options.forgeRepos } : {}),
     ...(declaredKinds ? { declaredKinds } : {}),
     ...(boxIntents ? { boxIntents } : {}),
     ...(options.live && !options.tree ? { live: await gatherLiveLinkFacts(root, declaration, registry, options.live.env, options.live.onStderr) } : {}),

package/src/workspace/ci-branches.ts

@@ -40,6 +40,37 @@ export function routeConflicts(branches: MemberGlobs | undefined, members: reado
   return members.map((member) => ({ member, branches: keysMatching(branches, member) })).filter((c) => c.branches.length > 1);
 }
 
+/**
+ * The branches `chant ci serve` polls (#4325), and the ones among them a job
+ * is told with `--branch`.
+ *
+ * - A routed member polls its route alone. A `named` branch that differs
+ *   from the route is refused, as `chant build --pr-loop` refuses it.
+ * - An unrouted member polls `fallback`, which may not be a routed branch.
+ * - Where no member is in play (the workspace root), `fallback` and then each
+ *   routed branch, so every branch a member applies from is watched.
+ *
+ * `fallback` is the branch `--branch` names, else the default branch.
+ */
+export function servedBranches(
+  branches: MemberGlobs | undefined,
+  member: string | undefined,
+  fallback: string,
+  named: boolean,
+): { served: string[]; routed: string[] } {
+  const keys = Object.keys(branches ?? {});
+  if (member === undefined) return { served: [fallback, ...keys.filter((k) => k !== fallback)], routed: keys };
+  const own = routedBranch(branches, member);
+  if (own !== null) {
+    if (named && fallback !== own) throw new Error(`--branch ${fallback}: ci.branches routes member ${member} to ${own}, so ci serve polls ${own}`);
+    return { served: [own], routed: [own] };
+  }
+  if (keys.includes(fallback)) {
+    throw new Error(`--branch ${fallback}: ci.branches applies only the members its globs match from ${fallback}, and member ${member} is not one`);
+  }
+  return { served: [fallback], routed: [] };
+}
+
 /**
  * Whether a push to `pushed` applies `member`, with a line that says why.
  * A routed member applies only from its branch. Any other member applies

package/src/workspace/ci-green-branches.test.ts

@@ -0,0 +1,153 @@
+/**
+ * #4325: `ci.green` names several branches when `ci.branches` routes members
+ * to branches of their own. Each is judged as the single branch always was, a
+ * one-branch declaration reads as before, and `release cut` takes a commit of
+ * any of them.
+ */
+
+import { afterAll, describe, expect, test } from "vitest";
+import { greenBranches, parseDeclaration } from "./declaration";
+import { cleanScratch, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { ciList, ciTick, formatTick, greenOn, lastGreen } from "./ci-green";
+import type { CheckRun, CiForge } from "./ci-green-forge";
+import { buildTriggerEdits, renderCiGreenWorkflow } from "./ci-green-workflow";
+import { checkOnGreenBranches, checkOnTrunk, resolveTrunk, WorkstationCheckError } from "../lifecycle/release-workstation";
+
+afterAll(cleanScratch);
+
+const PHASES = { test: ["test"] };
+const decl = (green: unknown) => JSON.stringify({ name: "w", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "x" }], ci: { green } });
+const parse = (branch: unknown) => parseDeclaration(decl({ branch, phases: PHASES, require: ["test"] }), "chant.workspace.json").ci!.green!;
+
+describe("ci.green.branch as one branch or several (#4325)", () => {
+  test("a string reads exactly as it did: no branches field", () => {
+    const g = parse("main");
+    expect(g.branch).toBe("main");
+    expect("branches" in g).toBe(false);
+    expect(greenBranches(g)).toEqual(["main"]);
+    // A list of one is the same declaration.
+    expect(parse(["main"])).toEqual(g);
+  });
+
+  test("a list judges each branch, and the first is the trunk readers use", () => {
+    const g = parse(["main", "release"]);
+    expect(g.branch).toBe("main");
+    expect(g.branches).toEqual(["main", "release"]);
+    expect(greenBranches(g)).toEqual(["main", "release"]);
+  });
+
+  test("an empty list, a repeated branch and a malformed name are refused", () => {
+    for (const bad of [[], ["main", "main"], ["main", "has space"], [3]]) {
+      expect(() => parse(bad), JSON.stringify(bad)).toThrow();
+    }
+  });
+
+  test("greenOn picks a branch ci.green names and refuses one it doesn't", () => {
+    const g = parse(["main", "release"]);
+    expect(greenOn(g, undefined).branch).toBe("main");
+    expect(greenOn(g, "release").branch).toBe("release");
+    expect("branches" in greenOn(g, "release")).toBe(false);
+    expect(() => greenOn(g, "staging")).toThrow(/judges main, release, not staging/);
+  });
+});
+
+// ── The tick, against a real remote ──────────────────────────────────────────
+
+const NOW = new Date();
+const run = (id: number, name: string, conclusion: string): CheckRun => ({ id, name, status: "completed", conclusion, completedAt: null, url: `https://example.com/runs/${id}` });
+
+function commit(root: string, file: string): string {
+  writeFiles(root, { [file]: `${file}\n` });
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", file);
+  return git(root, "rev-parse", "HEAD");
+}
+
+/** A checkout with `main` and `release` pushed to a bare origin, one commit each past a shared base. */
+function twoBranches(green: unknown): { root: string; origin: string; main: string; release: string } {
+  const origin = scratchDir("chant-ci-branches-origin-");
+  git(origin, "init", "-q", "--bare");
+  const root = scratchDir("chant-ci-branches-work-");
+  git(root, "init", "-q");
+  git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+  writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green } }) });
+  git(root, "remote", "add", "origin", origin);
+  commit(root, "app/base.txt");
+  git(root, "checkout", "-q", "-b", "release");
+  const release = commit(root, "app/release.txt");
+  git(root, "checkout", "-q", "main");
+  const main = commit(root, "app/main.txt");
+  git(root, "push", "-q", "origin", "main", "release");
+  return { root, origin, main, release };
+}
+
+const remoteTags = (origin: string) => git(origin, "for-each-ref", "--format=%(refname:lstrip=2)", "refs/tags/").split("\n").filter(Boolean).sort();
+const forge = (shas: string[]): CiForge => ({ kind: "github", checkRuns: async (sha) => (shas.includes(sha) ? [run(1, "test", "success")] : []) });
+
+describe("the tick judges each branch ci.green names (#4325)", () => {
+  test("a commit of a routed branch gets a green tag, and last-green reads each branch", async () => {
+    const { root, origin, main, release } = twoBranches({ branch: ["main", "release"], phases: PHASES, require: ["test"] });
+    const result = await ciTick({ cwd: root, forge: forge([main, release]), now: NOW });
+    expect(result.branch).toBe("main");
+    expect(result.routed?.map((r) => r.branch)).toEqual(["release"]);
+    expect(result.made.sort()).toEqual([`ci/green/${main}`, `ci/green/${release}`].sort());
+    expect(remoteTags(origin)).toEqual([`ci/green/${main}`, `ci/green/${release}`].sort());
+    // The tag says which branch it judged.
+    const note = git(origin, "tag", "-l", "--format=%(contents)", `ci/green/${release}`);
+    expect(JSON.parse(note.slice(note.indexOf("{")))).toMatchObject({ tag: "green", commit: release, branch: "release" });
+
+    expect((lastGreen({ cwd: root }) as { commit: { sha: string } }).commit.sha).toBe(main);
+    const onRelease = lastGreen({ cwd: root, branch: "release" }) as { branch: string; commit: { sha: string } };
+    expect([onRelease.branch, onRelease.commit.sha]).toEqual(["release", release]);
+    expect(lastGreen({ cwd: root, branch: "staging" })).toMatchObject({ error: { code: "ci-branch-unknown" } });
+
+    const listed = await ciList({ cwd: root, branch: "release", now: NOW });
+    expect("commits" in listed && listed.commits.filter((c) => c.state === "green").map((c) => c.sha)).toEqual([release]);
+
+    const text = formatTick(result);
+    expect(text).toContain("main, commits within 24h");
+    expect(text).toContain("release, commits within 24h");
+  });
+
+  test("a one-branch declaration ticks one branch, with no routed results", async () => {
+    const { root, main, release } = twoBranches({ branch: "main", phases: PHASES, require: ["test"] });
+    const result = await ciTick({ cwd: root, forge: forge([main, release]), now: NOW });
+    expect(result.routed).toBeUndefined();
+    expect(result.made).toEqual([`ci/green/${main}`]);
+    expect(lastGreen({ cwd: root, branch: "release" })).toMatchObject({ error: { code: "ci-branch-unknown" } });
+  });
+});
+
+describe("the generated tick workflow follows the branches (#4325)", () => {
+  const green = (branch: string | string[]) => parse(branch);
+
+  test("workflow_run lists every branch, and one branch renders as before", () => {
+    const render = (g: ReturnType<typeof green>) => renderCiGreenWorkflow({ green: g, workflows: ["ci"], chantVersion: "0.0.0", workspaceRoot: ".", install: undefined, chant: undefined, npmLock: undefined, push: undefined });
+    const many = render(green(["main", "release"]));
+    expect(many).toMatch(/branches:\n\s+- "?main"?\n\s+- "?release"?\n/);
+    // The checkout stays on the first branch, which holds the declaration the tick reads.
+    expect(many).toMatch(/ref: "?main"?/);
+    expect(render(green("main"))).not.toContain("release");
+  });
+
+  test("a push-triggered build lists every branch", () => {
+    const sources = [{ path: ".github/workflows/ci.yml", text: "name: ci\non:\n  push:\n    branches: [main]\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps: []\n" }];
+    const g = parseDeclaration(decl({ branch: ["main", "release"], phases: { test: { runs: ["test"], build: "newest" } }, require: ["test"] }), "chant.workspace.json").ci!.green!;
+    const [edit] = buildTriggerEdits(g, sources as never, { compose: false });
+    expect(edit!.text).toMatch(/branches:\n\s+- main\n\s+- release/);
+  });
+});
+
+describe("release cut takes a commit of any branch ci.green names (#4325)", () => {
+  test("a routed branch's commit is on trunk for the cut, and an unrelated one is not", () => {
+    const { root, main, release } = twoBranches({ branch: ["main", "release"], phases: PHASES, require: ["test"] });
+    git(root, "fetch", "-q", "origin");
+    const trunk = resolveTrunk(root, "main");
+    expect(() => checkOnTrunk(root, main, trunk)).not.toThrow();
+    expect(() => checkOnTrunk(root, release, trunk)).toThrow(WorkstationCheckError);
+    expect(checkOnGreenBranches(root, main, trunk, ["release"]).branch).toBe("main");
+    expect(checkOnGreenBranches(root, release, trunk, ["release"]).branch).toBe("release");
+    // Without the routed branch listed, the first branch's refusal stands.
+    expect(() => checkOnGreenBranches(root, release, trunk, [])).toThrow(WorkstationCheckError);
+  });
+});

package/src/workspace/ci-green-cli.ts

@@ -32,12 +32,12 @@ import { findWorkspaceRoot } from "../project-root";
 import { ciList, ciTick, CiGreenError, formatList, formatTick, lastGreen, RUNNER_KEY_ENV } from "./ci-green";
 import { ciForgeFromEnv } from "./ci-green-forge";
 import { ACTIONS_NAME, buildTriggerEdits, CI_GREEN_WORKFLOW_FILE, ciGreenHeader, type PushToken, readWorkflowSources, renderCiGreenWorkflow, workflowsHolding, writeWorkflowFile } from "./ci-green-workflow";
-import { readDeclaration, readerVersion, WorkspaceReadError, type CiSource } from "./declaration";
+import { greenBranches, readDeclaration, readerVersion, WorkspaceReadError, type CiSource } from "./declaration";
 import { recordGeneratedFiles, resolveMemberContext, shellArg } from "./member-pipeline";
 import { gitTop, workingTree } from "./tree";
 
 const USAGE =
-  "chant ci last-green [--json] [--from <rev>] | ci list [--json] [--limit <n>] [--since <rev>] [--forge github] [--source checks|runs] | ci tick [--dry-run] [--forge github] [--source checks|runs] [--key <runner key.pem>] | " +
+  "chant ci last-green [--json] [--from <rev>] [--branch <branch>] | ci list [--json] [--branch <branch>] [--limit <n>] [--since <rev>] [--forge github] [--source checks|runs] | ci tick [--dry-run] [--forge github] [--source checks|runs] [--key <runner key.pem>] | " +
   "ci workflow [--workflow <name>]... [--output <file>] [--chant <command>] [--install <command>] [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>] [--runner-key-secret <NAME>]";
 
 export { RUNNER_KEY_ENV };
@@ -56,7 +56,7 @@ function warnIgnored(ignored: readonly { tag: string; status: string; reason: st
 }
 
 export async function runCiLastGreen(ctx: CommandContext): Promise<number> {
-  const doc = lastGreen({ cwd: process.cwd(), ...(ctx.args.migrateFrom !== undefined ? { from: ctx.args.migrateFrom } : {}) });
+  const doc = lastGreen({ cwd: process.cwd(), ...(ctx.args.branch !== undefined ? { branch: ctx.args.branch } : {}), ...(ctx.args.migrateFrom !== undefined ? { from: ctx.args.migrateFrom } : {}) });
   if (ctx.args.json) {
     console.log(JSON.stringify(doc, null, 2));
     return "error" in doc ? 1 : 0;
@@ -81,7 +81,7 @@ export async function runCiList(ctx: CommandContext): Promise<number> {
     // Only an explicit --forge reaches the network; without it the list reads local refs and tags.
     const forge = ctx.args.forge !== undefined ? ciForgeFromEnv(ctx.args.forge) : undefined;
     const source = sourceOf(ctx.args);
-    const doc = await ciList({ cwd: process.cwd(), limit, since: ctx.args.since, forge, ...(source ? { source } : {}) });
+    const doc = await ciList({ cwd: process.cwd(), ...(ctx.args.branch !== undefined ? { branch: ctx.args.branch } : {}), limit, since: ctx.args.since, forge, ...(source ? { source } : {}) });
     if (ctx.args.json) {
       console.log(JSON.stringify(doc, null, 2));
       return "error" in doc ? 1 : 0;
@@ -185,14 +185,14 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
     const yaml = renderCiGreenWorkflow({ green, workflows, chantVersion: readerVersion(), workspaceRoot, chant: ctx.args.ciChant, install: ctx.args.ciInstall, npmLock, push, ...(runnerKeySecret ? { runnerKeySecret } : {}), ...(compose ? { compose } : {}) });
     const written = writeWorkflowFile(target, ciGreenHeader(command, member ? "member" : "root") + yaml);
     if (member) recordGeneratedFiles(member.memberRoot, [{ path: fromRepo, command }]);
-    console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${green.branch}${compose ? " or a chant/compose/ branch" : ""}, and every 15 minutes.`);
+    console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${greenBranches(green).join(", ")}${compose ? " or a chant/compose/ branch" : ""}, and every 15 minutes.`);
     for (const e of edits) {
       if (!e.changed) continue;
       const path = writeWorkflowFile(join(repoRoot, e.path), e.text);
       console.log(
         e.build === "newest"
-          ? `Wrote ${path}'s triggers and concurrency: ${e.phases.join(", ")} build${e.phases.length === 1 ? "s" : ""} the newest commit on ${green.branch} when a run ends, and a ci/build/<sha> tag by hand.`
-          : `Wrote ${path}'s triggers and concurrency: ${e.phases.join(", ")} build${e.phases.length === 1 ? "s" : ""} every commit on ${green.branch}, none cancelled, and a ci/build/<sha> tag by hand when the forge ran nothing.`,
+          ? `Wrote ${path}'s triggers and concurrency: ${e.phases.join(", ")} build${e.phases.length === 1 ? "s" : ""} the newest commit on ${greenBranches(green).join(", ")} when a run ends, and a ci/build/<sha> tag by hand.`
+          : `Wrote ${path}'s triggers and concurrency: ${e.phases.join(", ")} build${e.phases.length === 1 ? "s" : ""} every commit on ${greenBranches(green).join(", ")}, none cancelled, and a ci/build/<sha> tag by hand when the forge ran nothing.`,
       );
     }
     return 0;

package/src/workspace/ci-green-workflow.test.ts

@@ -14,6 +14,7 @@ import { runCiWorkflow } from "./ci-green-cli";
 import { BUILD_BLOCK_MARKER, buildTriggerEdits, CI_GREEN_WORKFLOW_FILE, dispatchableWorkflows, jobCheckRuns, renderCiGreenWorkflow, workflowsHolding, writeTopLevel } from "./ci-green-workflow";
 import { parseDeclaration } from "./declaration";
 import { cleanScratch, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { ACTION_PINS, usesRef } from "../action-pins";
 
 afterAll(cleanScratch);
 
@@ -82,7 +83,7 @@ describe("the workflows that hold required check runs (#3573)", () => {
     expect(doc.concurrency).toEqual({ group: "chant-ci-green", "cancel-in-progress": false });
     expect(doc.permissions).toEqual({ contents: "write", checks: "read" });
     const steps = doc.jobs.tick.steps;
-    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0 } });
+    expect(steps[0]).toEqual({ uses: usesRef(ACTION_PINS.checkout6), with: { ref: "main", "fetch-depth": 0 } });
     expect(steps[2].run).toBe("npx --yes @intentius/chant@0.108.0 ci tick");
     expect(steps[2]["working-directory"]).toBeUndefined();
     expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
@@ -128,7 +129,7 @@ describe("the token the tick pushes its tags with (#3573)", () => {
     const plain = renderCiGreenWorkflow(base);
     const text = renderCiGreenWorkflow({ ...base, push: { secret: "CI_GREEN_TOKEN" } });
     const steps = (parseYAMLDocument(text) as Yaml).jobs.tick.steps;
-    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN || github.token }}" } });
+    expect(steps[0]).toEqual({ uses: usesRef(ACTION_PINS.checkout6), with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN || github.token }}" } });
     // Check runs are still read with the Actions token: a fine-grained token can't call the Checks API.
     expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
     expect((parseYAMLDocument(text) as Yaml).permissions).toEqual({ contents: "write", checks: "read" });
@@ -147,7 +148,7 @@ describe("the token the tick pushes its tags with (#3573)", () => {
     const steps = (parseYAMLDocument(renderCiGreenWorkflow({ ...base, push: { appIdVar: "CI_GREEN_APP_ID", appKeySecret: "CI_GREEN_APP_KEY" } })) as Yaml).jobs.tick.steps;
     expect(steps[0]).toMatchObject({
       id: "app-token",
-      uses: "actions/create-github-app-token@v2",
+      uses: usesRef(ACTION_PINS.createGithubAppToken2),
       with: { "app-id": "${{ vars.CI_GREEN_APP_ID }}", "private-key": "${{ secrets.CI_GREEN_APP_KEY }}" },
     });
     expect(steps[1].with.token).toBe("${{ steps.app-token.outputs.token }}");