@intentius/chant 0.124.32 → 0.124.33

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.33",
   "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);
+  });
+});

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

@@ -0,0 +1,157 @@
+/**
+ * `chant lifecycle health <env> [lexicon] [--json]` (#4177): whether each
+ * declared resource that has a health read is up, separate from drift.
+ *
+ * It builds the project as `lifecycle diff` does, so the entity names are the
+ * graph's node ids, then asks each lexicon with a health read about the
+ * entities whose types it names. An environment's declared endpoint is applied
+ * for the read, as on the other live reads (#1166).
+ *
+ * The JSON is the {@link HEALTH_SCHEMA} shape. A single-stack project prints
+ * `lexicons` at the top level; a multi-stack one nests them under `stacks`,
+ * the same split `lifecycle diff --live --json` makes.
+ */
+
+import { resolve } from "node:path";
+import { build } from "../../build";
+import { loadChantConfig } from "../../config";
+import { isObservableDeclarable } from "../../declarable";
+import { HEALTH_SCHEMA, healthApplicable, observeHealthFor, summarizeHealth, type HealthLexicon, type HealthReadResult } from "../../health";
+import { applyLiveEndpoint } from "../../live-endpoint";
+import type { SerializerResult } from "../../serializer";
+import { CHANT_VERSION } from "../version";
+import { commandBuildParams } from "../build-params-cli";
+import { resolveBuildModes, resolveProjectBuildOptions } from "../build-options";
+import { formatBold, formatError, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+import { resolveStackTargets } from "./lifecycle";
+
+type ByLexicon = Record<string, HealthReadResult>;
+
+export async function runLifecycleHealth(ctx: CommandContext): Promise<number> {
+  const { args, plugins } = ctx;
+  const environment = args.extraPositional;
+  const lexiconFilter = args.extraPositional2;
+  if (!environment) {
+    console.error(formatError({ message: "Environment is required: chant lifecycle health <environment> [lexicon]" }));
+    return 1;
+  }
+
+  const readers = plugins.filter(
+    (p) => p.observeHealth && (p.healthTypes?.length ?? 0) > 0 && (!lexiconFilter || p.name === lexiconFilter),
+  );
+  if (readers.length === 0) {
+    console.error(formatWarning({
+      message: lexiconFilter
+        ? `${lexiconFilter}: no health read in this lexicon`
+        : "No configured lexicon has a health read (aws, azure and gcp do)",
+    }));
+    return 1;
+  }
+
+  const projectRoot = resolve(".");
+  const { config } = await loadChantConfig(projectRoot);
+  const declaredParams = await commandBuildParams(config.buildParams, args);
+  if (!declaredParams) return 1;
+  const targets = resolveStackTargets(args, config);
+  const buildOptions = resolveProjectBuildOptions({
+    config,
+    configDir: projectRoot,
+    plugins,
+    modes: resolveBuildModes(config, { fold: args.fold, sandbox: args.sandbox }),
+    buildParams: declaredParams,
+  });
+  const serializers = readers.map((p) => p.serializer);
+
+  const endpoint = applyLiveEndpoint(config.environments, environment, readers);
+  if (endpoint.notice) console.error(formatWarning({ message: endpoint.notice }));
+
+  const perStack: Record<string, ByLexicon> = {};
+  let single: ByLexicon | undefined;
+  let anyBuildError = false;
+  const observedAt = new Date().toISOString();
+
+  try {
+    for (const target of targets) {
+      const buildResult = await build(target.root, serializers, undefined, buildOptions);
+      if (buildResult.errors.length > 0) {
+        console.error(formatError({
+          message: `Build failed for ${target.stack ? `stack "${target.stack}"` : "project"}; fix errors before reading health`,
+        }));
+        anyBuildError = true;
+        continue;
+      }
+      const byLexicon: ByLexicon = {};
+      for (const plugin of readers) {
+        const declared = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+        for (const [name, entity] of buildResult.entities) {
+          if (entity.lexicon === plugin.name && isObservableDeclarable(entity)) {
+            declared.set(name, {
+              entityType: entity.entityType,
+              props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
+            });
+          }
+        }
+        const entities = healthApplicable(plugin as HealthLexicon, declared);
+        if (entities.size === 0) continue;
+        const raw = buildResult.outputs.get(plugin.name);
+        const buildOutput = raw === undefined ? "" : typeof raw === "string" ? raw : (raw as SerializerResult).primary;
+        byLexicon[plugin.name] = await observeHealthFor(plugin as HealthLexicon, {
+          environment,
+          buildOutput,
+          entities,
+          ...(target.stack ? { stack: target.stack } : {}),
+          ...(target.region ? { region: target.region } : {}),
+        });
+      }
+      if (target.stack) perStack[target.stack] = byLexicon;
+      else single = byLexicon;
+    }
+  } finally {
+    endpoint.restore();
+  }
+
+  const all = single ? [single] : Object.values(perStack);
+  const summary = summarizeHealth(all.flatMap((b) => Object.values(b)));
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      schema: HEALTH_SCHEMA,
+      chantVersion: CHANT_VERSION,
+      environment,
+      observedAt,
+      ...(single ? { lexicons: single } : { stacks: perStack }),
+      summary,
+    }));
+  } else {
+    if (single) renderHealth(single);
+    else for (const [stack, byLexicon] of Object.entries(perStack)) {
+      console.log(`\n${formatBold(`■ stack ${stack}`)}`);
+      renderHealth(byLexicon);
+    }
+    const total = summary.healthy + summary.unhealthy + summary.unknown + summary.unobserved + summary.absent;
+    if (total === 0) {
+      console.error(formatWarning({ message: "No declared resource has a health read" }));
+    } else {
+      console.error(
+        `${summary.healthy} healthy, ${summary.unhealthy} unhealthy, ${summary.unknown} unknown` +
+          (summary.unobserved > 0 ? `, ${summary.unobserved} not observed` : "") +
+          (summary.absent > 0 ? `, ${summary.absent} not deployed` : ""),
+      );
+    }
+  }
+  return anyBuildError ? 1 : 0;
+}
+
+function renderHealth(byLexicon: ByLexicon): void {
+  for (const [lexicon, result] of Object.entries(byLexicon)) {
+    console.log(formatBold(lexicon));
+    for (const [name, entry] of Object.entries(result.entities)) {
+      console.log(`  ${entry.state.padEnd(9)} ${name} (${entry.type}): ${entry.detail}`);
+    }
+    for (const [name, hole] of Object.entries(result.unobserved)) {
+      console.log(`  ${"not read".padEnd(9)} ${name}${hole.type ? ` (${hole.type})` : ""}: ${hole.reason}${hole.detail ? `, ${hole.detail}` : ""}`);
+    }
+    for (const name of result.absent) console.log(`  ${"absent".padEnd(9)} ${name}: not deployed`);
+  }
+}

package/src/cli/handlers/lifecycle.ts

@@ -90,7 +90,7 @@ interface StackTarget {
  * observed as the stack named after the environment (unchanged behavior). An
  * explicit `--src` always wins and forces a single scoped target.
  */
-function resolveStackTargets(args: ParsedArgs, config: ChantConfig): StackTarget[] {
+export function resolveStackTargets(args: ParsedArgs, config: ChantConfig): StackTarget[] {
   if (args.src) return [{ root: resolve(args.src) }];
   if (config.stacks && config.stacks.length > 0) {
     return config.stacks.map((s) => ({ stack: s.name, root: resolve(s.src), region: s.region }));