@intentius/chant 0.124.32 → 0.124.34

package/dist/workspace/release-workflow.js

@@ -0,0 +1,150 @@
+/**
+ * `chant release workflow` (#4168 step 6): the publish workflow, generated
+ * the way `chant ci workflow` writes the tick, where the guides used to have
+ * one pasted (guide/release-from-workstation.mdx).
+ *
+ * The job runs on a `release/**` tag, checks the tag out, fetches the ci tags
+ * and `chant/lifecycle`, builds what the targets upload, and runs `chant
+ * release publish` for the label the tag names. The security groups decide
+ * the rest, and nothing is on without one (#4168 section 8):
+ *
+ * - `supply-chain` adds `--require-provenance`, so a run with no OIDC token
+ *   fails rather than publishing without provenance.
+ * - `verified-releases` adds a `chant release verify` step before the publish.
+ *
+ * The OIDC permission (`id-token: write`, or GitLab's `id_tokens`) is always
+ * there: it costs nothing, and with it what the job uploads carries
+ * provenance whether or not the group requires it.
+ */
+import { GENERATED_MARKER } from "../discovery/files.js";
+export const RELEASE_WORKFLOW_FORGES = ["github", "forgejo", "gitlab"];
+/** Where each forge's publish workflow is written, relative to the repository root. */
+export const RELEASE_WORKFLOW_FILES = {
+    github: ".github/workflows/chant-release.yml",
+    forgejo: ".forgejo/workflows/chant-release.yml",
+    // GitLab reads one .gitlab-ci.yml, which includes this file: `include: { local: .gitlab/chant-release.yml }`.
+    gitlab: ".gitlab/chant-release.yml",
+};
+/** The flags `chant release publish` gets under the groups. */
+export function publishFlags(groups) {
+    return [...(groups.has("supply-chain") ? ["--require-provenance"] : []), "--yes"];
+}
+/** The workflow file's text, without the generated-by header. */
+export function renderReleaseWorkflow(input) {
+    const chant = input.chant ?? "npx chant";
+    const install = input.install ?? "npm ci";
+    const build = input.build === undefined ? "npm run build" : input.build;
+    const root = input.workspaceRoot && input.workspaceRoot !== "." ? input.workspaceRoot : null;
+    const verify = input.groups.has("verified-releases");
+    const flags = publishFlags(input.groups).join(" ");
+    if (input.forge === "gitlab") {
+        const label = '"${CI_COMMIT_TAG#release/}"';
+        const lines = [
+            "chant-release-publish:",
+            "  rules:",
+            "    - if: $CI_COMMIT_TAG =~ /^release\\//",
+            "  id_tokens:",
+            "    SIGSTORE_ID_TOKEN:",
+            "      aud: sigstore",
+            "  script:",
+            ...(root ? [`    - cd ${root}`] : []),
+            `    - ${install}`,
+            ...(build ? [`    - ${build}`] : []),
+            "    - git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'",
+            "    - git fetch origin chant/lifecycle:chant/lifecycle",
+            ...(verify ? [`    - ${chant} release verify ${label}`] : []),
+            `    - ${chant} release publish ${label} ${flags}`,
+        ];
+        return `${lines.join("\n")}\n`;
+    }
+    const label = '"${GITHUB_REF_NAME#release/}"';
+    const lines = [
+        "name: chant release publish",
+        "on:",
+        "  push:",
+        '    tags: ["release/**"]',
+        "permissions:",
+        "  contents: write",
+        "  id-token: write",
+        "jobs:",
+        "  publish:",
+        "    runs-on: ubuntu-latest",
+        ...(root ? ["    defaults:", "      run:", `        working-directory: ${root}`] : []),
+        "    steps:",
+        "      - uses: actions/checkout@v4",
+        "        with:",
+        "          fetch-depth: 0",
+        "      - uses: actions/setup-node@v4",
+        "        with:",
+        "          node-version: 24",
+        "          registry-url: https://registry.npmjs.org",
+        `      - run: ${install}`,
+        ...(build ? [`      - run: ${build}`] : []),
+        "      - run: git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'",
+        "      - run: git fetch origin chant/lifecycle:chant/lifecycle",
+        ...(verify ? [`      - run: ${chant} release verify ${label}`] : []),
+        `      - run: ${chant} release publish ${label} ${flags}`,
+    ];
+    return `${lines.join("\n")}\n`;
+}
+/** The header that marks the file generated, naming the command that regenerates it. */
+export function releaseWorkflowHeader(command) {
+    return `# ${GENERATED_MARKER}. Regenerate with: ${command} (in the workspace root)\n`;
+}
+/**
+ * `chant release workflow [--forge github|gitlab|forgejo] [--install <command>]
+ * [--build <command>|--no-build] [--chant <command>] [--output <file>]`: write
+ * the publish workflow for the workspace's forge, under its security groups.
+ */
+export async function runReleaseWorkflow(ctx) {
+    const { existsSync, mkdirSync, realpathSync, writeFileSync } = await import("node:fs");
+    const { dirname, join, relative, resolve, sep } = await import("node:path");
+    const { formatError, formatSuccess } = await import("../cli/format.js");
+    const { findWorkspaceRoot } = await import("../project-root.js");
+    const { gitTop } = await import("./tree.js");
+    const { securityGroupsAt } = await import("./security.js");
+    const { shellArg } = await import("./member-pipeline.js");
+    const usage = "chant release workflow [--forge github|gitlab|forgejo] [--install <command>] [--build <command>] [--chant <command>] [--output <file>]";
+    const { args } = ctx;
+    const found = findWorkspaceRoot(process.cwd());
+    if (!found) {
+        console.error(formatError({ message: "no chant.workspace.json between this directory and the git root", hint: usage }));
+        return 1;
+    }
+    const root = realpathSync(found.dir);
+    const repoRoot = gitTop(root) ?? root;
+    const forge = (args.forge ??
+        (existsSync(join(repoRoot, ".github", "workflows")) ? "github" : existsSync(join(repoRoot, ".forgejo", "workflows")) ? "forgejo" : existsSync(join(repoRoot, ".gitlab-ci.yml")) ? "gitlab" : "github"));
+    if (!RELEASE_WORKFLOW_FORGES.includes(forge)) {
+        console.error(formatError({ message: `--forge ${JSON.stringify(forge)} is not one of ${RELEASE_WORKFLOW_FORGES.join(", ")}`, hint: usage }));
+        return 1;
+    }
+    const groups = securityGroupsAt(root);
+    const workspaceRoot = relative(repoRoot, root).split(sep).join("/") || ".";
+    const text = renderReleaseWorkflow({
+        forge,
+        groups,
+        workspaceRoot,
+        ...(args.ciInstall ? { install: args.ciInstall } : {}),
+        ...(args.buildCommand ? { build: args.buildCommand } : {}),
+        ...(args.ciChant ? { chant: args.ciChant } : {}),
+    });
+    const target = args.output ? resolve(process.cwd(), args.output) : join(repoRoot, RELEASE_WORKFLOW_FILES[forge]);
+    const parts = ["chant", "release", "workflow", "--forge", forge];
+    if (args.ciInstall)
+        parts.push("--install", args.ciInstall);
+    if (args.buildCommand)
+        parts.push("--build", args.buildCommand);
+    if (args.ciChant)
+        parts.push("--chant", args.ciChant);
+    if (args.output)
+        parts.push("--output", relative(root, target).split(sep).join("/"));
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, releaseWorkflowHeader(parts.map(shellArg).join(" ")) + text);
+    const shown = relative(process.cwd(), target).split(sep).join("/") || target;
+    const extras = [groups.has("supply-chain") ? "requires OIDC provenance (supply-chain)" : null, groups.has("verified-releases") ? "verifies the release first (verified-releases)" : null].filter(Boolean);
+    console.log(formatSuccess(`Wrote ${shown}: publishes the release a release/** tag names${extras.length > 0 ? `, and ${extras.join(" and ")}` : ""}.`));
+    if (forge === "gitlab")
+        console.log(`Include it from .gitlab-ci.yml: include: [{ local: ${RELEASE_WORKFLOW_FILES.gitlab} }]`);
+    return 0;
+}

package/dist/workspace/security.d.ts

@@ -0,0 +1,40 @@
+import type { Declaration } from "./declaration.js";
+import { type ScopeSource } from "./write-scope.js";
+export declare const SECURITY_GROUPS: readonly ["verified-releases", "supply-chain", "who-ran-it", "review-rules", "isolated-runners"];
+export type SecurityGroup = (typeof SECURITY_GROUPS)[number];
+/**
+ * The groups `declaration` turns on for `member` (a member name): the
+ * top-level list plus that member's own. Empty for no declaration or no
+ * `security` key anywhere.
+ */
+export declare function securityGroupsOf(declaration: Pick<Declaration, "security" | "members"> | null | undefined, member?: string | null): ReadonlySet<SecurityGroup>;
+/** The member of `source`'s declaration whose directory holds `cwd`, or null. */
+export declare function memberAtCwd(source: Pick<ScopeSource, "declaration" | "rootOnDisk">, cwd: string): string | null;
+/** The groups `source` turns on for a command run in `cwd`: the top-level list and the list of the member holding `cwd`. */
+export declare function securityGroupsIn(source: Pick<ScopeSource, "declaration" | "rootOnDisk">, cwd: string): ReadonlySet<SecurityGroup>;
+/**
+ * The groups the workspace holding `cwd` turns on for the member holding
+ * `cwd`, read at base (the target branch tip) when there is one, else from
+ * the working tree, as the release gate is read. Empty outside a workspace.
+ */
+export declare function securityGroupsAt(cwd: string, at?: string): ReadonlySet<SecurityGroup>;
+/** One row of the security feature table (#4168 section 8). */
+export interface SecurityFeature {
+    feature: string;
+    /** What happens with no group and no setting. */
+    byDefault: string;
+    /** What turns it on alone. */
+    setting: string;
+    group: SecurityGroup | null;
+    /** The `workspace check` reason codes that report it missing under its group. */
+    codes: readonly string[];
+}
+/**
+ * Every security feature, the group that raises it and the setting that
+ * turns it on alone. The reference page's table is printed from this list
+ * (`securityFeatureTable`), and a test compares the two.
+ */
+export declare const SECURITY_FEATURES: readonly SecurityFeature[];
+/** The reference page's table of {@link SECURITY_FEATURES}, as markdown. */
+export declare function securityFeatureTable(): string;
+//# sourceMappingURL=security.d.ts.map

package/dist/workspace/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/workspace/security.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAE9D,eAAO,MAAM,eAAe,YAAI,mBAAmB,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,kBAAkB,CAAU,CAAC;AAEhI,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW,GAAG,WAAW,CAAC,aAAa,CAAC,CAGpK;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,aAAa,GAAG,YAAY,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW/G;AAED,4HAA4H;AAC5H,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,aAAa,GAAG,YAAY,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC,aAAa,CAAC,CAEjI;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,aAAa,CAAC,CAErF;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5B,iFAAiF;IACjF,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EAgBvD,CAAC;AAEF,4EAA4E;AAC5E,wBAAgB,oBAAoB,IAAI,MAAM,CAG7C"}

package/dist/workspace/security.js

@@ -0,0 +1,99 @@
+/**
+ * The security groups a workspace opts into (#4168 section 8): the
+ * declaration's top-level `security`, such as `["verified-releases"]`, plus
+ * the `security` of the member a command runs in (#4168 step 7). With no
+ * `security` key none is on, and a security feature the workspace has not
+ * turned on never refuses, warns or hides anything (the rule #4156 set for
+ * runner signing).
+ *
+ * What each group turns on:
+ * - `verified-releases`: `chant release publish` refuses a release with no
+ *   verified signature, as the `release` gate in `identity.gates` does, and
+ *   `chant components promote --release` verifies the release first.
+ * - `supply-chain`: a publish without OIDC provenance warns, and a target
+ *   with no SBOM source is refused (`publish-sbom-missing`).
+ * - `who-ran-it`: `chant ci tick` refuses to tag without a runner key.
+ * - `review-rules`: `chant components pr-apply` counts an approval only from
+ *   someone who approved the pull request on the forge, as
+ *   `--require-review` does, and a generated pull-request pipeline passes
+ *   the flag.
+ * - `isolated-runners`: `chant ci run apply`, under `chant ci serve` too,
+ *   refuses to start without a provisioner's runner-start statement for the
+ *   job (#4147), as `--require-runner-start` does, and a generated
+ *   pull-request pipeline passes the flag. A `--local` run is exempt.
+ *
+ * Each feature still turns on alone: `identity.gates.release`,
+ * `--require-provenance`, `--require-review`, `ci.green.signedSince`.
+ * `chant workspace check` reports what a declared group still lacks
+ * (./checks/security.ts, WSP161 to WSP165). {@link SECURITY_FEATURES} is the
+ * table the reference page prints.
+ */
+import { realpathSync } from "node:fs";
+import { relative, sep } from "node:path";
+import { memberHolding } from "./record-assets.js";
+import { scopeSource } from "./write-scope.js";
+export const SECURITY_GROUPS = ["verified-releases", "supply-chain", "who-ran-it", "review-rules", "isolated-runners"];
+/**
+ * The groups `declaration` turns on for `member` (a member name): the
+ * top-level list plus that member's own. Empty for no declaration or no
+ * `security` key anywhere.
+ */
+export function securityGroupsOf(declaration, member = null) {
+    const own = member === null ? [] : (declaration?.members?.find((m) => m.name === member)?.security ?? []);
+    return new Set([...(declaration?.security ?? []), ...own]);
+}
+/** The member of `source`'s declaration whose directory holds `cwd`, or null. */
+export function memberAtCwd(source, cwd) {
+    if (!source.declaration || source.rootOnDisk === null)
+        return null;
+    let rel;
+    try {
+        rel = relative(realpathSync(source.rootOnDisk), realpathSync(cwd));
+    }
+    catch {
+        rel = relative(source.rootOnDisk, cwd);
+    }
+    if (rel.startsWith(".."))
+        return null;
+    const posix = sep === "/" ? rel : rel.split(sep).join("/");
+    return memberHolding(posix === "" ? "." : posix, source.declaration.members);
+}
+/** The groups `source` turns on for a command run in `cwd`: the top-level list and the list of the member holding `cwd`. */
+export function securityGroupsIn(source, cwd) {
+    return securityGroupsOf(source.declaration, memberAtCwd(source, cwd));
+}
+/**
+ * The groups the workspace holding `cwd` turns on for the member holding
+ * `cwd`, read at base (the target branch tip) when there is one, else from
+ * the working tree, as the release gate is read. Empty outside a workspace.
+ */
+export function securityGroupsAt(cwd, at) {
+    return securityGroupsIn(scopeSource(cwd, at), cwd);
+}
+/**
+ * Every security feature, the group that raises it and the setting that
+ * turns it on alone. The reference page's table is printed from this list
+ * (`securityFeatureTable`), and a test compares the two.
+ */
+export const SECURITY_FEATURES = [
+    { feature: "Publish refuses an unsigned release", byDefault: "off: publishes and records `signature: unsigned`", setting: "`identity.gates.release`", group: "verified-releases", codes: ["security-signers-missing", "security-publish-allows-unsigned"] },
+    { feature: "Signed cut in the release gate's class", byDefault: "off", setting: "`identity.gates.release` with a `class`", group: "verified-releases", codes: ["security-release-gate-missing"] },
+    { feature: "Promote verifies the release", byDefault: "off: `chant release verify` on demand", setting: "`chant release verify`", group: "verified-releases", codes: [] },
+    { feature: "SBOM on every target", byDefault: "off: a target with no SBOM source publishes without one", setting: "`sbom` on the target", group: "supply-chain", codes: ["security-sbom-disabled", "security-sbom-unsourced"] },
+    { feature: "OIDC provenance", byDefault: "off: a plan field", setting: "`--require-provenance`", group: "supply-chain", codes: ["security-publish-no-provenance"] },
+    { feature: "SBOM and verify steps on components", byDefault: "off", setting: "a `generate-sbom` or `verify` step", group: "supply-chain", codes: ["security-component-no-sbom", "security-component-no-verify"] },
+    { feature: "Signed green tags and runs", byDefault: "off: every tag counts", setting: "`ci.green.signedSince`", group: "who-ran-it", codes: ["security-signed-since-unset"] },
+    { feature: "Trusted runner keys", byDefault: "off", setting: "`.chant/trust.json` with a runner role", group: "who-ran-it", codes: ["security-runner-untrusted"] },
+    { feature: "Tick signs its tags", byDefault: "off: unsigned tags", setting: "`--key` or `CHANT_RUNNER_KEY`", group: "who-ran-it", codes: ["security-tick-no-key"] },
+    { feature: "Forge review required, authors never count", byDefault: "off", setting: "`--require-review`, `requireReview: true`", group: "review-rules", codes: ["security-review-not-required"] },
+    { feature: "Identified attribution", byDefault: "off: `any`", setting: "`identity.attribution: \"identified\"`", group: "review-rules", codes: ["security-attribution-any"] },
+    { feature: "Signed approvals", byDefault: "off", setting: "`identity.gates.<gate>`", group: "review-rules", codes: ["security-gate-unsigned"] },
+    { feature: "Apply jobs require a runner-start statement", byDefault: "off", setting: "`--require-runner-start`", group: "isolated-runners", codes: ["security-runner-start-no-key", "security-runner-start-no-role", "security-trust-unreadable"] },
+    { feature: "Secrets file", byDefault: "off", setting: "`--secrets`", group: null, codes: [] },
+    { feature: "Env allowlist and log redaction", byDefault: "on: `ci run`'s contract, a listed exception", setting: "`--pass-env`", group: null, codes: [] },
+];
+/** The reference page's table of {@link SECURITY_FEATURES}, as markdown. */
+export function securityFeatureTable() {
+    const rows = SECURITY_FEATURES.map((f) => `| ${f.feature} | ${f.byDefault} | ${f.setting} | ${f.group ? `\`${f.group}\`` : "none"} | ${f.codes.map((c) => `\`${c}\``).join(", ") || "none"} |`);
+    return ["| Feature | Default | Turns it on alone | Group | Checked as |", "|---|---|---|---|---|", ...rows].join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.124.32",
+  "version": "0.124.34",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -52,6 +52,7 @@
     },
     "./workspace/*.schema.json": "./src/workspace/*.schema.json",
     "./notify.schema.json": "./src/notify.schema.json",
+    "./health.schema.json": "./src/health.schema.json",
     "./workspace/factory-rules": {
       "development": "./src/workspace/factory-rules.ts",
       "types": "./dist/workspace/factory-rules.d.ts",
@@ -103,6 +104,12 @@
       "import": "./dist/notify-verify.js",
       "default": "./src/notify-verify.ts"
     },
+    "./runner-start": {
+      "development": "./src/runner-start.ts",
+      "types": "./dist/runner-start.d.ts",
+      "import": "./dist/runner-start.js",
+      "default": "./src/runner-start.ts"
+    },
     "./notify": {
       "development": "./src/notify.ts",
       "types": "./dist/notify.d.ts",

package/src/__fixtures__/pr-loop/pr-plan.note.golden.md

@@ -18,7 +18,7 @@ A reviewer who approved this pull request approves the plan with:
 chant approve pr-12 pr-apply --plan jcs1-sha256:7623a8677afb0bf98d77c602521a3abfa96f76cff25675d350a28c2e26a7bad0 --approver github:<your-login> --sign
 ```
 
-It applies on merge if the plan is still this one. If it moved, the apply refuses and names both digests.
+On merge the plan is recorded, and a release deploys it. With apply on merge it applies if the plan is still this one; if it moved, the apply refuses and names both digests.
 
 ### Plan summary
 

package/src/ci-jobs.ts

@@ -417,6 +417,12 @@ export const GITLAB_SCHEDULE_SOURCE = '$CI_PIPELINE_SOURCE == "schedule"';
 /** A job variable that makes the runner clone the whole history, which a job reading the base commit needs. */
 export const GITLAB_FULL_HISTORY = { GIT_DEPTH: "0" } as const;
 
+/** The tags a build request is pushed as (#4169), as a glob for a trigger. */
+export const BUILD_REQUEST_TAGS = "ci/build/**";
+
+/** The `rules:` if-expression for a build request's tag (#4169). */
+export const GITLAB_BUILD_REQUEST_RULE = "$CI_COMMIT_TAG =~ /^ci\\/build\\//";
+
 /** The `rules:` if-expression for a push to `branch`, a quoted name or an expression such as `$CI_DEFAULT_BRANCH`. */
 export function gitlabPushRule(branch: string): string {
   return `$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == ${branch}`;
@@ -462,11 +468,14 @@ export function gitlabRules(subject: string, trigger: OpTrigger, selector: { var
         return { if: `${GITLAB_MERGE_REQUEST_SOURCE} && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "${branch}"` };
       });
     }
-    case "push":
-      return pushBranches(trigger.branches).map((branch) => {
+    case "push": {
+      const rules = pushBranches(trigger.branches).map((branch) => {
         assertGitlabBranch(subject, branch);
         return { if: gitlabPushRule(JSON.stringify(branch)) };
       });
+      // #4169: a newest build also runs at each build request's tag.
+      return trigger.build === "newest" ? [...rules, { if: GITLAB_BUILD_REQUEST_RULE }] : rules;
+    }
   }
 }
 

package/src/cli/handlers/build.test.ts

@@ -148,6 +148,42 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
     vi.restoreAllMocks();
   });
 
+  test("--pr-loop asks for --require-review only under --require-review or the review-rules security group (#4168)", async () => {
+    const { mkdtempSync, mkdirSync, writeFileSync, rmSync } = await import("node:fs");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const { execFileSync } = await import("node:child_process");
+    const root = mkdtempSync(join(tmpdir(), "chant-build-review-rules-"));
+    try {
+      execFileSync("git", ["init", "-q"], { cwd: root });
+      mkdirSync(join(root, "app"));
+      const declare = (extra: Record<string, unknown>) =>
+        writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, ...extra, members: [{ name: "app", dir: "app", kind: "chant", because: "the app" }] }));
+      generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "jobs: {}", stages: [], jobs: [] });
+      vi.spyOn(console, "log").mockImplementation(() => {});
+      const path = join(root, "app");
+      const output = join(root, "out.yml");
+
+      declare({});
+      expect(await runBuild({ args: makeArgs({ path, output, generate: "github", prLoop: true }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock.mock.calls[0][2].prLoop).toEqual({});
+      expect(await runBuild({ args: makeArgs({ path, output, generate: "github", prLoop: true, requireReview: true }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock.mock.calls[1][2].prLoop).toEqual({ requireReview: true });
+
+      declare({ security: ["review-rules"] });
+      expect(await runBuild({ args: makeArgs({ path, output, generate: "github", prLoop: true }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock.mock.calls[2][2].prLoop).toEqual({ requireReview: true });
+
+      // #4168 step 7: a member's own group counts, and isolated-runners asks for --require-runner-start.
+      writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, members: [{ name: "app", dir: "app", kind: "chant", because: "the app", security: ["isolated-runners"] }] }));
+      expect(await runBuild({ args: makeArgs({ path, output, generate: "github", prLoop: true }), plugins: [], serializers: [] })).toBe(0);
+      expect(generateComponentsPipelineMock.mock.calls[3][2].prLoop).toEqual({ requireRunnerStart: true });
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+      vi.restoreAllMocks();
+    }
+  });
+
   test("--pr-loop without --report-url bakes the workspace's ci.reportUrl into the jobs, and the flag wins (#4160)", async () => {
     const { mkdtempSync, mkdirSync, writeFileSync, rmSync } = await import("node:fs");
     const { tmpdir } = await import("node:os");

package/src/cli/handlers/build.ts

@@ -17,8 +17,12 @@ import type { PrLoopPipelineOptions } from "../../components/pr-pipeline";
  * flags the generated jobs pass to pr-plan and pr-apply. `--pr-build` and
  * `--pr-build-command` (#4088) add the build and lint steps before both.
  * `reportUrl` is `--report-url`, else the workspace's `ci.reportUrl` (#4160).
+ * `requireReview` is `--require-review`, or a workspace that opts into the
+ * `review-rules` security group (#4168); off otherwise. `requireRunnerStart`
+ * is `--require-runner-start`, or the `isolated-runners` group. `--apply-on-merge`
+ * (#4168) writes the apply job on merge in place of the record job.
  */
-function prLoopOption(args: CommandContext["args"], reportUrl: string | undefined): PrLoopPipelineOptions {
+function prLoopOption(args: CommandContext["args"], reportUrl: string | undefined, requireReview = false, requireRunnerStart = false): PrLoopPipelineOptions {
   return {
     ...(args.gate ? { gate: args.gate } : {}),
     ...(args.branch ? { branch: args.branch } : {}),
@@ -26,6 +30,9 @@ function prLoopOption(args: CommandContext["args"], reportUrl: string | undefine
     ...(reportUrl ? { reportUrl } : {}),
     ...(args.prBuild ? { build: true } : {}),
     ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
+    ...(args.requireReview === true || requireReview ? { requireReview: true } : {}),
+    ...(args.requireRunnerStart === true || requireRunnerStart ? { requireRunnerStart: true } : {}),
+    ...(args.applyOnMerge ? { applyOnMerge: true } : {}),
   };
 }
 
@@ -102,6 +109,14 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
       return 1;
     }
   }
+  // #4168: the review-rules group turns on --require-review in the generated apply. Read only inside a workspace.
+  let reviewRules = false;
+  let isolatedRunners = false;
+  if (found && args.prLoop) {
+    const groups = (await import("../../workspace/security")).securityGroupsAt(resolve(args.path));
+    reviewRules = groups.has("review-rules");
+    isolatedRunners = groups.has("isolated-runners");
+  }
   if (found) {
     memberPipeline = await import("../../workspace/member-pipeline");
     try {
@@ -116,7 +131,7 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
         params: args.param,
         paramsFile: args.paramsFile,
         ...(args.waveGate ? { waveGate: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } } : {}),
-        ...(args.prLoop ? { prLoop: prLoopOption(args, reportUrl) } : {}),
+        ...(args.prLoop ? { prLoop: prLoopOption(args, reportUrl, reviewRules, isolatedRunners) } : {}),
         ...(args.image ? { image: args.image } : {}),
         ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
       });
@@ -146,7 +161,7 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
         ? { gatedWaves: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } }
         : {}),
       // #3183: a plan job per pull request and an apply job per merge.
-      ...(args.prLoop ? { prLoop: prLoopOption(args, reportUrl) } : {}),
+      ...(args.prLoop ? { prLoop: prLoopOption(args, reportUrl, reviewRules, isolatedRunners) } : {}),
       // #4002: the job image and the lines that install what it lacks, chant itself included.
       ...(args.image ? { image: args.image } : {}),
       ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),

package/src/cli/handlers/lifecycle-health.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { createMockPlugin } from "@intentius/chant-test-utils";
+import type { BuildResult } from "../../build";
+import type { LexiconPlugin } from "../../lexicon";
+import type { ParsedArgs } from "../registry";
+import { HEALTH_SCHEMA_ID } from "../../health";
+import { UNOBSERVED_REASONS } from "../../observation";
+import { contract, validSchema } from "../../workspace/__fixtures__/contract-repo";
+import schema from "../../health.schema.json";
+
+const { expectValid, validate } = contract(schema);
+
+const buildMock = vi.fn();
+const loadChantConfigMock = vi.fn();
+vi.mock("../../build", () => ({ build: (...args: unknown[]) => buildMock(...args) }));
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args) };
+});
+
+const { runLifecycleHealth } = await import("./lifecycle-health");
+
+function args(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
+  return { command: "lifecycle", path: "health", format: "", fix: false, watch: false, verbose: false, help: false, extraPositional: "prod", ...overrides } as ParsedArgs;
+}
+
+function buildResult(entities: Array<[string, string, string]>): BuildResult {
+  return {
+    outputs: new Map([["aws", "{}"]]),
+    entities: new Map(entities.map(([name, lexicon, entityType]) => [name, { lexicon, entityType, kind: "resource", props: {} }])),
+    dependencies: new Map(),
+    errors: [],
+    warnings: [],
+    manifest: { lexicons: ["aws"], outputs: {}, deployOrder: ["aws"] },
+    sourceFileCount: 1,
+  } as unknown as BuildResult;
+}
+
+describe("chant lifecycle health (#4177)", () => {
+  let out: string[];
+  let err: string[];
+  beforeEach(() => {
+    out = [];
+    err = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { out.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { err.push(s); });
+    loadChantConfigMock.mockResolvedValue({ config: { environments: ["prod"] } });
+    buildMock.mockReset();
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  test("asks only about the types the lexicon names, and prints chant-health/v1", async () => {
+    buildMock.mockResolvedValue(buildResult([["web", "aws", "AWS::ECS::Service"], ["bucket", "aws", "AWS::S3::Bucket"]]));
+    const asked: string[][] = [];
+    const plugin: LexiconPlugin = {
+      ...createMockPlugin({ name: "aws" }),
+      healthTypes: ["AWS::ECS::Service"],
+      observeHealth: async (o) => {
+        asked.push([...o.entities.keys()]);
+        return { entities: { web: { type: "AWS::ECS::Service", state: "unhealthy", detail: "0/2 running", observedAt: "t" } }, unobserved: {}, absent: [] };
+      },
+    };
+    const exit = await runLifecycleHealth({ args: args({ json: true }), plugins: [plugin], serializers: [plugin.serializer] });
+    expect(exit).toBe(0);
+    expect(asked).toEqual([["web"]]);
+    const json = JSON.parse(out[0]!);
+    expect(json.schema).toBe("chant-health/v1");
+    expect(typeof json.chantVersion).toBe("string");
+    expect(json.lexicons.aws.entities.web.state).toBe("unhealthy");
+    expect(json.summary).toEqual({ healthy: 0, unhealthy: 1, unknown: 0, unobserved: 0, absent: 0 });
+    expectValid(json);
+  });
+
+  test("a reader that throws is not read, never unhealthy", async () => {
+    buildMock.mockResolvedValue(buildResult([["web", "aws", "AWS::ECS::Service"]]));
+    const plugin: LexiconPlugin = {
+      ...createMockPlugin({ name: "aws" }),
+      healthTypes: ["AWS::ECS::Service"],
+      observeHealth: async () => {
+        throw new Error("no route to host");
+      },
+    };
+    await runLifecycleHealth({ args: args(), plugins: [plugin], serializers: [plugin.serializer] });
+    expect(out.join("\n")).toContain("not read  web (AWS::ECS::Service): read-failed, no route to host");
+    expect(err.join("\n")).toContain("0 healthy, 0 unhealthy, 0 unknown, 1 not observed");
+  });
+
+  test("refuses with no environment, and with no lexicon that reads health", async () => {
+    const plain = createMockPlugin({ name: "aws" });
+    expect(await runLifecycleHealth({ args: args({ extraPositional: undefined }), plugins: [plain], serializers: [] })).toBe(1);
+    expect(await runLifecycleHealth({ args: args(), plugins: [plain], serializers: [] })).toBe(1);
+    expect(err.join("\n")).toContain("No configured lexicon has a health read");
+  });
+
+  test("the JSON of a read that failed follows the schema", async () => {
+    buildMock.mockResolvedValue(buildResult([["web", "aws", "AWS::ECS::Service"], ["gone", "aws", "AWS::ECS::Service"]]));
+    const plugin: LexiconPlugin = {
+      ...createMockPlugin({ name: "aws" }),
+      healthTypes: ["AWS::ECS::Service"],
+      observeHealth: async () => ({ entities: {}, unobserved: { web: { type: "AWS::ECS::Service", reason: "no-credentials", detail: "no AWS credentials" } }, absent: ["gone"] }),
+    };
+    await runLifecycleHealth({ args: args({ json: true }), plugins: [plugin], serializers: [plugin.serializer] });
+    const json = JSON.parse(out[0]!);
+    expect(json.summary).toEqual({ healthy: 0, unhealthy: 0, unknown: 0, unobserved: 1, absent: 1 });
+    expectValid(json);
+  });
+});
+
+describe("the chant-health/v1 schema (#4177)", () => {
+  test("is a valid schema with the exported id, and names every unobserved reason", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(HEALTH_SCHEMA_ID);
+    expect([...schema.$defs.hole.properties.reason.enum].sort()).toEqual([...UNOBSERVED_REASONS].sort());
+  });
+
+  test("a document with neither lexicons nor stacks, or a state outside the three, does not validate", () => {
+    const base = { schema: "chant-health/v1", chantVersion: "0.124.33", environment: "prod", observedAt: "t", summary: { healthy: 0, unhealthy: 0, unknown: 0, unobserved: 0, absent: 0 } };
+    expect(validate(base)).toBe(false);
+    expectValid({ ...base, stacks: { east: {} } });
+    const bad = { ...base, lexicons: { aws: { entities: { web: { type: "AWS::ECS::Service", state: "down", detail: "", observedAt: "t" } }, unobserved: {}, absent: [] } } };
+    expect(validate(bad)).toBe(false);
+  });
+});