@intentius/chant 0.80.0 → 0.81.0

package/src/workspace/records-contract.test.ts

@@ -13,6 +13,7 @@ import { afterAll, describe, expect, test } from "vitest";
 import { queryRecords, RECORDS_CONTRACT_VERSION, RECORDS_OUTPUT_SCHEMA_ID, type RecordsDocument } from "./records-cli";
 import { READ_ERROR_CODES, RECORD_REASON_CODES } from "./records";
 import schema from "./records.schema.json";
+import { PROVENANCE_LEVELS } from "./trust/attestor";
 
 const REPO = join(import.meta.dirname, "..", "..", "..", "..");
 const KIND = "docs/design/decisions/decision.kind.mjs";
@@ -52,6 +53,10 @@ describe("records output schema", () => {
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...READ_ERROR_CODES]);
   });
 
+  test("lists exactly the provenance levels (#2547)", () => {
+    expect(schema.$defs.provenance.properties.level.enum).toEqual([...PROVENANCE_LEVELS]);
+  });
+
   test("the chant repo's decisions validate, current and not", async () => {
     for (const current of [false, true]) {
       const doc = await queryRecords({ kind: KIND, current, cwd: REPO });

package/src/workspace/records.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json",
   "title": "chant workspace records output",
-  "description": "What `chant workspace records --json` prints, version 1 of the read contract for records (#2536). This is the first-test slice (#2546): records are unsealed and there is no workspace declaration yet. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version.",
+  "description": "What `chant workspace records --json` prints, version 1 of the read contract for records (#2536). This is the first-test slice (#2546): records are unsealed and there is no workspace declaration yet. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
   "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
   "$defs": {
     "result": {
@@ -28,6 +28,7 @@
         },
         "error": false,
         "current": { "type": "boolean", "description": "Whether superseded records were left out (--current)." },
+        "trust": { "$ref": "#/$defs/trust" },
         "records": {
           "description": "One entry per file the kind locates, sorted by path.",
           "type": "array",
@@ -61,7 +62,8 @@
         "data": {
           "type": ["object", "null"],
           "description": "The front matter as JSON, following the kind's schema when valid is true. Null when it could not be parsed."
-        }
+        },
+        "provenance": { "$ref": "#/$defs/provenance" }
       },
       "allOf": [
         {
@@ -71,6 +73,34 @@
         }
       ]
     },
+    "trust": {
+      "description": "Added in contract 1 by #2547. Where provenance was judged from: the policy read at the base revision, never the tree read.",
+      "type": "object",
+      "required": ["base", "baseFrom", "active", "signersPath", "problems"],
+      "properties": {
+        "base": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit id the policy was read at, or null when there is no base." },
+        "baseFrom": { "enum": ["flag", "origin/HEAD", "main", "master", null], "description": "flag when --base was given; otherwise the target branch that was found." },
+        "active": { "type": "boolean", "description": "Whether a signers file exists at base. False means attestation is off and every record is unattested." },
+        "signersPath": { "type": "string", "description": "The signers file, relative to the repository root." },
+        "problems": { "type": "array", "items": { "type": "string" }, "description": "Why the policy could not be read. Nothing is attested when this is not empty." }
+      }
+    },
+    "provenance": {
+      "description": "Added in contract 1 by #2547. How far the record's authorship is established, judged by the signers at base.",
+      "type": "object",
+      "required": ["level", "commit", "reason"],
+      "properties": {
+        "level": {
+          "enum": ["attested", "attested-unverifiable-here", "adopted", "unattested"],
+          "description": "attested: the last commit to change the file is signed by a signer the policy at base lists. attested-unverifiable-here: it carries a signature nothing here can check. adopted: it lies in a commit range the policy adopts. unattested: none of these, including uncommitted content."
+        },
+        "commit": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40,64}$", "description": "The commit the record's content comes from, or null for uncommitted content." },
+        "attestor": { "type": "string", "description": "The attestor that answered, such as ssh-commit." },
+        "principal": { "type": "string", "description": "The signer, when attested." },
+        "key": { "type": "string", "description": "The signing key's fingerprint, when known." },
+        "reason": { "type": "string" }
+      }
+    },
     "reason": {
       "type": "object",
       "required": ["code", "message"],

package/src/workspace/records.ts

@@ -21,6 +21,7 @@ import { dirname, posix, relative, resolve, sep } from "node:path";
 import yaml from "js-yaml";
 import { z } from "zod";
 import { importLexiconModule, registerLexiconDeclarations } from "../lexicon-module";
+import type { ReasonCode } from "./reason-codes";
 import type { RecordSource } from "./record-source";
 
 // ── Reason codes ─────────────────────────────────────────────────────────────
@@ -40,7 +41,7 @@ export const RECORD_REASON_CODES = [
   "record-supersedes-unknown",
   /** A second closed record supersedes a record another one already superseded. */
   "record-supersedes-conflict",
-] as const;
+] as const satisfies readonly ReasonCode[];
 export type RecordReasonCode = (typeof RECORD_REASON_CODES)[number];
 
 /**
@@ -64,7 +65,7 @@ export const READ_ERROR_CODES = [
   "not-a-git-repository",
   /** `--at` names no commit. */
   "revision-unknown",
-] as const;
+] as const satisfies readonly ReasonCode[];
 export type ReadErrorCode = (typeof READ_ERROR_CODES)[number];
 
 export class RecordReadError extends Error {

package/src/workspace/root-refusal.ts

@@ -0,0 +1,97 @@
+/**
+ * `chant build` and `chant lint` at the root of a declared workspace (#2537,
+ * #2524 D0 and D12, ws-023).
+ *
+ * Once `chant.workspace.json` declares members, their directories leave the
+ * root project. A top-level `chant build` there would quietly build less than
+ * it did before the file existed, so both commands refuse with `WSP000` and
+ * point to `chant workspace build` and `chant workspace lint`. `--root-only`,
+ * or `rootOnly: true` in the root's `chant.config`, lets them run on the root
+ * project alone, with the member directories and example-group matches left
+ * out of discovery.
+ *
+ * `main.ts` decides with `findWorkspaceRoot` and `findProjectRoot`, which only
+ * test whether files exist, and imports this module only when the command's
+ * project is a declared root. A project with no declaration never loads it.
+ */
+
+import { relative } from "node:path";
+import { formatError } from "../cli/format";
+import { ownerOf, readDeclaration, resolveGroups, rootExclusions, WorkspaceReadError } from "./declaration";
+import { workingTree } from "./tree";
+
+/** The code a refusal carries. `WSP` ids name workspace findings (#2524 D16); `000` is the refusal itself. */
+export const ROOT_REFUSAL_CODE = "WSP000";
+
+export interface RootGuardInput {
+  verb: "build" | "lint";
+  /** The command's target, absolute. */
+  target: string;
+  /** The directory holding the declaration, absolute. */
+  workspaceDir: string;
+  /** `--root-only` on the command line, or `rootOnly: true` in the root's chant.config. */
+  rootOnly: boolean;
+}
+
+export type RootGuardResult =
+  /** The target belongs to a member or an example group, so it is not the root project; nothing changes. */
+  | { action: "not-root" }
+  /** The command runs on the root project with these directories (relative to the root) left out. */
+  | { action: "root-only"; excluded: string[] }
+  /** The command stops; `message` says why and what to run instead. */
+  | { action: "refuse"; message: string };
+
+/** Decide what a root `build` or `lint` does. Pure apart from reading the declaration. */
+export function decideRootCommand(input: RootGuardInput): RootGuardResult {
+  const tree = workingTree(input.workspaceDir);
+  let declaration;
+  let groups;
+  try {
+    declaration = readDeclaration(tree);
+    groups = resolveGroups(declaration, tree);
+  } catch (err) {
+    if (!(err instanceof WorkspaceReadError)) throw err;
+    return {
+      action: "refuse",
+      message:
+        `${ROOT_REFUSAL_CODE}: ${input.workspaceDir} holds a workspace declaration that can't be read, so chant ${input.verb} ` +
+        `can't tell which directories belong to the root project. ${err.code}: ${err.describe()}`,
+    };
+  }
+  const rel = relative(input.workspaceDir, input.target).split("\\").join("/") || ".";
+  const owner = ownerOf(declaration, groups, rel === "." ? "." : rel);
+  if (owner && ("group" in owner || owner.member.dir !== ".")) return { action: "not-root" };
+
+  const excluded = rootExclusions(declaration, groups).map((e) => e.dir);
+  if (input.rootOnly) return { action: "root-only", excluded };
+
+  const members = declaration.members.filter((m) => m.dir !== ".").length;
+  const matches = groups.reduce((n, g) => n + g.matches.length, 0);
+  const moved = [
+    `${members} member${members === 1 ? "" : "s"}`,
+    ...(matches > 0 ? [`${matches} example project${matches === 1 ? "" : "s"}`] : []),
+  ].join(" and ");
+  return {
+    action: "refuse",
+    message:
+      `${ROOT_REFUSAL_CODE}: this is the root of workspace ${declaration.name} (${declaration.file}), which moves ` +
+      `${moved} out of the root project. Run chant workspace ${input.verb} to ${input.verb} each member with its own ` +
+      `toolchain, or pass --root-only (or set rootOnly: true in chant.config) to ${input.verb} the root project alone.`,
+  };
+}
+
+/**
+ * Apply {@link decideRootCommand}: print the refusal and return 1, or return
+ * undefined so the command goes on. A root-only run needs nothing set up:
+ * every discovery walk under a declaration already leaves the member
+ * directories and group matches out (#2527, `workspaceMemberDirs` in
+ * `../discovery/walk.ts`), and `excluded` names the same directories.
+ */
+export function guardRootCommand(input: RootGuardInput): number | undefined {
+  const result = decideRootCommand(input);
+  if (result.action === "refuse") {
+    console.error(formatError({ message: result.message }));
+    return 1;
+  }
+  return undefined;
+}

package/src/workspace/status-contract.test.ts

@@ -0,0 +1,308 @@
+/**
+ * The read contract for `chant workspace status --json` (#2544, #2524 D15,
+ * D19): the output schema is a valid draft 2020-12 document, its closed code
+ * lists match the code, and real output validates against it, for workspaces
+ * built here with a `chant/lifecycle` branch holding member ledgers in both
+ * layouts, and for the chant repo's own declaration (#2557).
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import { afterAll, describe, expect, test, vi } from "vitest";
+import type { CommandContext } from "../cli/registry";
+import { listWorkspace } from "./ls";
+import {
+  formatStatus,
+  runWorkspaceStatus,
+  STATUS_CONTRACT_VERSION,
+  STATUS_ERROR_CODES,
+  STATUS_OUTPUT_SCHEMA_ID,
+  STATUS_REASON_CODES,
+  workspaceStatus,
+  type StatusDocument,
+} from "./status";
+import schema from "./status.schema.json";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+const validate = ajv.compile(schema);
+
+function expectValid(doc: StatusDocument): void {
+  const ok = validate(doc);
+  expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+}
+
+function result(doc: StatusDocument): Extract<StatusDocument, { members: unknown }> {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+function git(cwd: string, args: string[], env?: NodeJS.ProcessEnv, input?: string): string {
+  return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], {
+    cwd,
+    encoding: "utf-8",
+    input,
+    env: { ...process.env, ...env },
+    stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+  }).trim();
+}
+
+/** A git repository holding `files`, committed. */
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-status-")));
+  scratch.push(root);
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  git(root, ["init", "-q", "-b", "main"]);
+  git(root, ["add", "-A"]);
+  git(root, ["commit", "-q", "--allow-empty", "-m", "init"]);
+  return root;
+}
+
+/**
+ * Write `files` as the whole tree of a `chant/lifecycle` commit, the way the
+ * lifecycle code stores ledgers, without touching the working tree or index.
+ */
+function lifecycle(root: string, files: Record<string, string>): string {
+  const index = join(root, ".git", "status-test-index");
+  const env = { GIT_INDEX_FILE: index };
+  rmSync(index, { force: true });
+  for (const [path, text] of Object.entries(files)) {
+    const blob = git(root, ["hash-object", "-w", "--stdin"], env, text);
+    git(root, ["update-index", "--add", "--cacheinfo", `100644,${blob},${path}`], env);
+  }
+  const tree = git(root, ["write-tree"], env);
+  const commit = git(root, ["commit-tree", tree, "-m", "ledger"], env);
+  git(root, ["update-ref", "refs/heads/chant/lifecycle", commit]);
+  rmSync(index, { force: true });
+  return commit;
+}
+
+let n = 0;
+/** One ledger line. */
+function release(component: string, env: string, digest: string, gitSha: string, extra: Record<string, string> = {}): string {
+  n++;
+  return JSON.stringify({
+    version: 1,
+    component,
+    env,
+    digest,
+    gitSha,
+    runId: `run-${n}`,
+    timestamp: `2026-09-${String(10 + n).padStart(2, "0")}T00:00:00.000Z`,
+    actor: "ci",
+    ...extra,
+  });
+}
+const jsonl = (...lines: string[]) => lines.join("\n") + "\n";
+
+const D = (c: string) => `sha256:${c.repeat(64)}`;
+
+const declaration = (members: unknown[]) => JSON.stringify({ name: "acme", schema: 1, members }, null, 2);
+
+/** web has moved to _members/ (#2538); api and the root member still read the flat ledger. */
+function twoLayouts(): string {
+  const root = repo({
+    "chant.workspace.json": declaration([
+      { name: "site", dir: ".", kind: "other", because: "the root project" },
+      { name: "web", dir: "apps/web", kind: "chant" },
+      { name: "api", dir: "apps/api", kind: "chant" },
+      { name: "examples", kind: "examples", glob: "examples/*" },
+    ]),
+    "apps/web/chant.config.ts": "",
+    "apps/api/chant.config.ts": "",
+  });
+  lifecycle(root, {
+    "_members/web/staging/releases.jsonl": jsonl(release("web", "staging", D("0"), "0".repeat(40)), release("web", "staging", D("a"), "a".repeat(40))),
+    "_members/web/prod/releases.jsonl": jsonl(release("web", "prod", D("a"), "a".repeat(40))),
+    "staging/releases.jsonl": jsonl(
+      release("api", "staging", D("b"), "b".repeat(40)),
+      release("worker", "staging", D("d"), "d".repeat(40)),
+    ),
+    "prod/releases.jsonl": jsonl(release("api", "prod", D("c"), "c".repeat(40))),
+  });
+  return root;
+}
+
+describe("status output schema", () => {
+  test("is a valid draft 2020-12 document with the published $id", () => {
+    expect(schema.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
+    expect(ajv.validateSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(STATUS_OUTPUT_SCHEMA_ID);
+    expect(STATUS_CONTRACT_VERSION).toBe(1);
+  });
+
+  test("lists exactly the reason and error codes the code can return", () => {
+    expect(schema.$defs.environment.properties.reason.oneOf[1].properties!.code.enum).toEqual([...STATUS_REASON_CODES]);
+    expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...STATUS_ERROR_CODES]);
+  });
+});
+
+describe("chant workspace status on built workspaces", () => {
+  test("lists each member's latest release per environment, from _members/ and from the flat layout", async () => {
+    const root = twoLayouts();
+    const doc = result(await workspaceStatus({ cwd: join(root, "apps", "web"), env: "staging" }));
+    expectValid(doc);
+    expect(doc.lifecycle.commit).toBe(git(root, ["rev-parse", "chant/lifecycle"]));
+    expect(doc.members.map((m) => m.name)).toEqual(["site", "web", "api"]);
+    const [site, web, api] = doc.members;
+    expect(web.environments).toHaveLength(1);
+    expect(web.environments[0].ledger).toEqual({ layout: "members", path: "_members/web/staging/releases.jsonl", shared: false });
+    // The later of the two records wins.
+    expect(web.environments[0].releases.map((r) => [r.component, r.digest, r.gitSha])).toEqual([["web", D("a"), "a".repeat(40)]]);
+    // api has no _members/api/ yet, so it falls back to the flat ledger, which the root member reads too.
+    expect(api.environments[0].ledger).toEqual({ layout: "flat", path: "staging/releases.jsonl", shared: true });
+    expect(site.environments[0].ledger).toEqual({ layout: "flat", path: "staging/releases.jsonl", shared: true });
+    expect(api.environments[0].releases.map((r) => r.component)).toEqual(["api", "worker"]);
+    expect(web.compare).toBeNull();
+    expect(doc.summary).toEqual({ members: 3, released: 3, unreadable: 0, differing: null });
+  });
+
+  test("--compare-to shows both environments and marks the members whose digests differ", async () => {
+    const root = twoLayouts();
+    const doc = result(await workspaceStatus({ cwd: root, env: "staging", compareTo: "prod" }));
+    expectValid(doc);
+    const web = doc.members.find((m) => m.name === "web")!;
+    const api = doc.members.find((m) => m.name === "api")!;
+    expect(web.environments.map((e) => [e.env, e.ledger.path])).toEqual([
+      ["staging", "_members/web/staging/releases.jsonl"],
+      ["prod", "_members/web/prod/releases.jsonl"],
+    ]);
+    expect(web.compare).toEqual({ differs: false, components: [{ component: "web", state: "same", digest: D("a"), compareDigest: D("a") }] });
+    expect(api.compare).toEqual({
+      differs: true,
+      components: [
+        { component: "api", state: "differs", digest: D("b"), compareDigest: D("c") },
+        { component: "worker", state: "only-env", digest: D("d"), compareDigest: null },
+      ],
+    });
+    expect(doc.summary).toEqual({ members: 3, released: 3, unreadable: 0, differing: 2 });
+
+    const text = formatStatus(doc);
+    expect(text).toContain("acme  staging compared to prod  (chant/lifecycle at ");
+    expect(text).toMatch(/web\s+web\s+sha256:aaaaaaaaaaaa aaaaaaaa\s+sha256:aaaaaaaaaaaa aaaaaaaa\n/);
+    expect(text).toMatch(/api\s+api\s+sha256:bbbbbbbbbbbb bbbbbbbb\s+sha256:cccccccccccc cccccccc\s+differs/);
+    expect(text).toMatch(/api\s+worker\s+sha256:dddddddddddd dddddddd\s+-\s+only-env/);
+    expect(text).toContain("3 members, 3 with a release in staging, 2 differ from prod, 0 unreadable");
+  });
+
+  test("compares on the input digest when a release has one", async () => {
+    const root = repo({ "chant.workspace.json": declaration([{ name: "chart", dir: "chart", kind: "other", because: "helm" }]) });
+    lifecycle(root, {
+      "staging/releases.jsonl": jsonl(release("chart", "staging", D("1"), "1".repeat(40), { inputDigest: D("9") })),
+      "prod/releases.jsonl": jsonl(release("chart", "prod", D("2"), "1".repeat(40), { inputDigest: D("9") })),
+    });
+    const doc = result(await workspaceStatus({ cwd: root, env: "staging", compareTo: "prod" }));
+    expectValid(doc);
+    expect(doc.members[0].compare?.components[0]).toMatchObject({ state: "same", digest: D("1"), compareDigest: D("2") });
+    expect(doc.members[0].environments[0].ledger.shared).toBe(false);
+  });
+
+  test("a member whose ledger can't be read is listed with a reason code, and the read still succeeds", async () => {
+    const root = twoLayouts();
+    lifecycle(root, {
+      "_members/web/staging/releases.jsonl": jsonl(release("web", "staging", D("a"), "a".repeat(40)), "{not json", JSON.stringify({ component: "web" })),
+      "staging/releases.jsonl": jsonl(release("api", "staging", D("b"), "b".repeat(40))),
+    });
+    const doc = result(
+      await workspaceStatus({
+        cwd: root,
+        env: "staging",
+        compareTo: "prod",
+        readLedger: async (path, cwd) => {
+          if (path === "prod/releases.jsonl") throw new Error("fatal: bad object\nmore");
+          const { readReleaseLedger } = await import("../lifecycle/release-ledger");
+          return readReleaseLedger(path.slice(0, -"/releases.jsonl".length), { cwd });
+        },
+      }),
+    );
+    expectValid(doc);
+    const web = doc.members.find((m) => m.name === "web")!;
+    const api = doc.members.find((m) => m.name === "api")!;
+    expect(web.readable).toBe(false);
+    expect(web.environments[0].reason).toEqual({
+      code: "ledger-malformed",
+      message: "_members/web/staging/releases.jsonl: 2 lines are not a release record and were skipped",
+    });
+    expect(web.environments[0].releases.map((r) => r.digest)).toEqual([D("a")]);
+    expect(api.environments[1].reason).toEqual({ code: "ledger-unreadable", message: "prod/releases.jsonl: fatal: bad object" });
+    expect(api.environments[1].releases).toEqual([]);
+    expect(doc.summary.unreadable).toBe(3);
+    expect(formatStatus(doc)).toContain("  ledger-unreadable: prod/releases.jsonl: fatal: bad object");
+  });
+
+  test("a checkout with no chant/lifecycle branch lists every member with no release", async () => {
+    const root = repo({ "chant.workspace.json": declaration([{ name: "web", dir: "web", kind: "chant" }]) });
+    const doc = result(await workspaceStatus({ cwd: root, env: "prod" }));
+    expectValid(doc);
+    expect(doc.lifecycle.commit).toBeNull();
+    expect(doc.members[0].environments[0]).toMatchObject({ releases: [], reason: null, ledger: { layout: "flat", shared: false } });
+    expect(formatStatus(doc)).toContain("web     -          no release");
+  });
+
+  test("every failure validates with its code", async () => {
+    const empty = repo({});
+    const outside = realpathSync(mkdtempSync(join(tmpdir(), "chant-status-nogit-")));
+    scratch.push(outside);
+    writeFileSync(join(outside, "chant.workspace.json"), declaration([]));
+    const broken = repo({ "chant.workspace.json": '{ "name": "acme", "schema": 1 "members": [] }' });
+    const ok = repo({ "chant.workspace.json": declaration([]) });
+    const docs = [
+      await workspaceStatus({ cwd: empty, env: "prod" }),
+      await workspaceStatus({ cwd: outside, env: "prod" }),
+      await workspaceStatus({ cwd: broken, env: "prod" }),
+      await workspaceStatus({ cwd: ok, env: "_members" }),
+      await workspaceStatus({ cwd: ok, env: "prod", compareTo: "../x" }),
+    ];
+    for (const doc of docs) expectValid(doc);
+    expect(docs.map((d) => ("error" in d ? d.error.code : "ok"))).toEqual([
+      "declaration-missing",
+      "not-a-git-repository",
+      "declaration-unparseable",
+      "environment-invalid",
+      "environment-invalid",
+    ]);
+  });
+
+  test("the command needs an environment, refuses --live, and exits 0 with unreadable members", async () => {
+    const root = twoLayouts();
+    const err = vi.spyOn(console, "error").mockImplementation(() => {});
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const run = (args: Record<string, unknown>) => runWorkspaceStatus({ args: { extraPositional2: root, ...args } } as unknown as CommandContext);
+      expect(await run({})).toBe(1);
+      expect(String(err.mock.calls.at(-1)?.[0])).toContain("needs an environment");
+      expect(await run({ extraPositional: "prod", compareTo: "--live" })).toBe(1);
+      expect(String(err.mock.calls.at(-1)?.[0])).toContain("doesn't read live state yet");
+      expect(await run({ extraPositional: "prod", compareTo: "staging", json: true })).toBe(0);
+      const printed = JSON.parse(String(log.mock.calls.at(-1)?.[0])) as StatusDocument;
+      expectValid(printed);
+      expect(await run({ extraPositional: "../prod", json: true })).toBe(1);
+    } finally {
+      err.mockRestore();
+      log.mockRestore();
+    }
+  });
+});
+
+describe("chant workspace status on the chant repo (#2557)", () => {
+  test("validates and lists every declared member", async () => {
+    const doc = result(await workspaceStatus({ cwd: join(REPO, "packages", "core"), env: "prod", compareTo: "staging" }));
+    expectValid(doc);
+    expect(doc.workspace).toMatchObject({ name: "chant", root: ".", file: "chant.workspace.json" });
+    const ls = listWorkspace({ cwd: REPO });
+    if ("error" in ls) throw new Error(ls.error.message);
+    expect(doc.members.map((m) => m.name)).toEqual(ls.members.map((m) => m.name));
+  });
+});