@intentius/chant 0.102.0 → 0.104.1

package/src/workspace/__fixtures__/studio-template-84c8b21.json

@@ -2,7 +2,7 @@
  "$comment": "The studio kit's app template, arugula-salad/studio 84c8b21 template/, which is chud's template at jhgaylor/chud 43afcf1 with the chud CLI steps taken out of its prose and delivery/package.json. The fixture for chant workspace upgrade's chud-lexicon-exit migration (INTENTIUS/chant#2737). Data only: nothing here is imported or run by chant's tests, and delivery/ names @intentius/chud-runtime, which chant never installs.",
  "source": "https://github.com/arugula-salad/studio/tree/84c8b21/template",
  "files": {
-  ".github/workflows/ci.yml": "name: ci\n\non:\n  push:\n    branches:\n      - main\n  pull_request: {}\n\npermissions:\n  contents: read\n\nconcurrency:\n  group: ci-${{ github.ref }}\n  cancel-in-progress: '${{ github.event_name == ''pull_request'' }}'\n\njobs:\n  ci:\n    runs-on: ubuntu-latest\n    timeout-minutes: 20\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v7\n      - name: Setup Node.js\n        uses: actions/setup-node@v7\n        with:\n          node-version: '22.x'\n          cache: npm\n          cache-dependency-path: delivery/package-lock.json\n      - name: Read access to @intentius/chud-runtime\n        env:\n          CHUD_RUNTIME_TOKEN: '${{ secrets.CHUD_RUNTIME_TOKEN }}'\n          CHUD_RUNTIME_DEPLOY_KEY: '${{ secrets.CHUD_RUNTIME_DEPLOY_KEY }}'\n        run: |\n          if [ -n \"$CHUD_RUNTIME_TOKEN\" ]; then\n            git config --global url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf ssh://git@github.com/\n            git config --global --add url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf git@github.com:\n          elif [ -n \"$CHUD_RUNTIME_DEPLOY_KEY\" ]; then\n            mkdir -p ~/.ssh && chmod 700 ~/.ssh\n            printf '%s\\n' \"$CHUD_RUNTIME_DEPLOY_KEY\" > ~/.ssh/id_ed25519 && chmod 600 ~/.ssh/id_ed25519\n            echo \"github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl\" >> ~/.ssh/known_hosts\n          else\n            echo \"neither CHUD_RUNTIME_TOKEN nor CHUD_RUNTIME_DEPLOY_KEY is set: a private @intentius/chud-runtime will not install\"\n          fi\n      - name: Install\n        run: npm ci\n        working-directory: delivery\n      - name: Workflow YAML is built from ci/ci.ts\n        run: npm run ci:check\n        working-directory: delivery\n      - name: chant workspace check\n        run: npx chant workspace check\n        working-directory: delivery\n      - name: chant build\n        run: npx chant build -o \"$RUNNER_TEMP/chant-build.out\"\n        working-directory: delivery\n      - name: chant lint\n        run: npx chant lint\n        working-directory: delivery\n      - name: App tests and approved contract checks\n        run: npm run check\n        working-directory: delivery\n",
+  ".github/workflows/ci.yml": "name: ci\n\non:\n  push:\n    branches:\n      - main\n  pull_request: {}\n\npermissions:\n  contents: read\n\nconcurrency:\n  group: ci-${{ github.ref }}\n  cancel-in-progress: '${{ github.event_name == ''pull_request'' }}'\n\njobs:\n  ci:\n    runs-on: ubuntu-latest\n    timeout-minutes: 20\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      - name: Setup Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: '22.x'\n          cache: npm\n          cache-dependency-path: delivery/package-lock.json\n      - name: Read access to @intentius/chud-runtime\n        env:\n          CHUD_RUNTIME_TOKEN: '${{ secrets.CHUD_RUNTIME_TOKEN }}'\n          CHUD_RUNTIME_DEPLOY_KEY: '${{ secrets.CHUD_RUNTIME_DEPLOY_KEY }}'\n        run: |\n          if [ -n \"$CHUD_RUNTIME_TOKEN\" ]; then\n            git config --global url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf ssh://git@github.com/\n            git config --global --add url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf git@github.com:\n          elif [ -n \"$CHUD_RUNTIME_DEPLOY_KEY\" ]; then\n            mkdir -p ~/.ssh && chmod 700 ~/.ssh\n            printf '%s\\n' \"$CHUD_RUNTIME_DEPLOY_KEY\" > ~/.ssh/id_ed25519 && chmod 600 ~/.ssh/id_ed25519\n            echo \"github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl\" >> ~/.ssh/known_hosts\n          else\n            echo \"neither CHUD_RUNTIME_TOKEN nor CHUD_RUNTIME_DEPLOY_KEY is set: a private @intentius/chud-runtime will not install\"\n          fi\n      - name: Install\n        run: npm ci\n        working-directory: delivery\n      - name: Workflow YAML is built from ci/ci.ts\n        run: npm run ci:check\n        working-directory: delivery\n      - name: chant workspace check\n        run: npx chant workspace check\n        working-directory: delivery\n      - name: chant build\n        run: npx chant build -o \"$RUNNER_TEMP/chant-build.out\"\n        working-directory: delivery\n      - name: chant lint\n        run: npx chant lint\n        working-directory: delivery\n      - name: App tests and approved contract checks\n        run: npm run check\n        working-directory: delivery\n",
   ".gitignore": "node_modules/\n.chud/\n.data/\n.hud/\n# chant build output (the Ops as op.json)\ndist/\n",
   "CLAUDE.md": "# {{chant:name}}: notes for agents\n\nThis repo is a chant workspace made from the studio kit's template\n(`chant init --from <studio>/template`, then the kit's `box/setup-app.mjs`).\nIt holds everything about {{chant:name}}: the app, the contracts it must\nmeet, the decisions made about it, the agents that build it, and the Ops that\nship it. `chant.workspace.json` declares its members, and chant finds\neverything through them.\n\nYou are probably running as hud's agent in the app's page: the app's own\nserver (its `dev` script, `node --watch`) behind hud's proxy. Your working\ndirectory is this one (the workspace root), and your job is to build the app\nin `app/`. See `app/CLAUDE.md`. Decisions and work items are chant records:\nwrite them with `chant workspace records`, and hud shows them.\n\n## Where things are\n\n| Member | Directory | What it holds |\n|---|---|---|\n| app | `app/` | The product. Edited live while its `dev` script runs. |\n| delivery | `delivery/` | The chant project: `chant.config.ts` (this repo's settings as `buildParams`: ports and how to run the app), `ops/` (the release, rollback, upgrade and dispatch Ops), `deploy/` (the app as a chant component and the sites it ships to), `agents/team.ts` (the agents that build the app, as fountain specs), `decisions/` (the decision points and the ship gate's Cedar policy), `ci/ci.ts` (this repo's CI), `.chant/` (the write-scope policy and the contract-sizing lint rules), and `node_modules/`. |\n| design | `design/` | chud's records, written by the design app: `contracts/` (and `contracts/checks/`), `drivers/`, `evidence/`, `sessions/`, `context/`, `proposals/`. Also the design app's overrides and the screen specs in `screens/`. |\n| design-client | `design-client/` | A placeholder for a vendored design client. Nothing here yet. |\n\n`work/` at the root holds the units of work: chant work items\n(`W-NNN-<slug>.md`, `work.kind.mjs` and `work.schema.json` beside them), one\nper agent run or piece of manual work, with chud's fields under `x-chud`.\nchud writes them through `chant workspace records new|amend`; list them with\n`chant workspace records --kind work/work.kind.mjs`.\n\n`decisions/` at the root holds the decision records: chant decision records\n(`decision.kind.mjs` and `decision.schema.json` beside them define the\nformat), the template's `ref-001`, `ref-002` and `chud-001`, and the\n`chud-NNN` records the design app writes. Each cites the issue in\n`chud.decisions.issue` (`delivery/chant.config.ts`) as its source, or\n`chud-001`'s when none is set. List the\ncurrent ones with\n`chant workspace records --kind decisions/decision.kind.mjs --current`.\n\nA decision pins the files it rests on by path and hash: an `evidence` entry\n`{ title, path, sha256, as_of }`, `path` from the workspace root and inside a\nmember (such as `design/screens/home.json`), and `sha256` the hash of the\nfile's bytes, which `chant workspace records pin <path>` prints. What it\ngoverns goes in `constrains` as `member:<name>` or `path:<path>`. `chant\nworkspace records` reports each pin as `pinned`, `drifted` (the file changed\nsince), `missing` or `stale` (a superseding decision pins the file at the\nsame hash, and the file has not changed since). A drifted pin means the file\nmoved away from what was decided: say so, and do not re-pin it yourself. The\ndesign app pins a file by name (`POST /api/decisions` with `{ title, path }`\nin `evidence` hashes it) and re-pins with `PUT /api/decisions/<id>`.\n\nEvidence (`design/evidence/<sha256>.json`) and design sessions\n(`design/sessions/S-NNNN.json`) are chant record kinds too, declared on the\ndesign member in `chant.workspace.json` (`design/evidence/evidence.kind.mjs`,\n`design/sessions/session.kind.mjs`). Read them with\n`chant workspace records --json`, which reads every declared kind. An\nevidence record's id is the sha256 of its bytes; a file whose name is not\nthat hash carries `asset-drift` and is not evidence. A closed session is\nsealed, and an edit to it is `session-seal-mismatch`. Only the design app and\nthe Ops' Check phases write these files, and each write is read back through\nchant before it is committed. Never write or edit one by hand, and never\nrename one.\n\n- Records keep their core fields in YAML front matter (or JSON), validated\n  against the schemas in\n  `delivery/node_modules/@intentius/chud-runtime/schemas/`. Extra fields must\n  start with `x-`.\n- `delivery/node_modules/@intentius/chud-runtime` is the machinery (the design\n  app, the Op steps). It is a versioned dependency: never edit it. Upgrade it\n  with the upgrade Op (`npm run upgrade` in `delivery/`), which stops at a\n  gate for a person.\n- `.chud/`: local state (hud data, staged releases, the local site). Never\n  edit it, and never commit it.\n\nEvery path chud records (a unit's scope, a protected path, a record's `file`)\nis relative to this directory, the git top-level.\n\n## Rules\n\n- Contracts and decisions are written by the design app. Read the ones that\n  touch your work and do not undo them. Never edit `design/contracts/`,\n  `decisions/`, `work/`, `design/evidence/`, `design/drivers/`,\n  `design/context/`, `design/sessions/`, `delivery/decisions/`,\n  `delivery/.chant/`, `delivery/chant.config.ts` or `chant.workspace.json`\n  (or the paths `chud.protectedPaths` in `delivery/chant.config.ts` adds)\n  from the app's page. This is enforced: an agent run's changes there are thrown\n  away, and a release refuses to plan while a commit that changes them lacks\n  the design app's `Chud-Author: design-app` trailer.\n- Never commit, tag or push. Committing, planning and shipping happen in the\n  design app, through the release Op and its gate.\n\n## Why a line is the way it is\n\nThe design app's commits for a unit of work carry trailers that tie the\ncommit to that unit: `Chud-Unit: W-NNN`, `Chud-Contract: C-NNN` (or\n`Chud-Driver: D-NNN` for a split) and one `Chud-Evidence: <sha256>` per\nevidence record the unit cites, beside `Chud-Author: design-app`.\n`decisions/decision.kind.mjs` exports `commitJoins`, which joins a commit\nto its unit from the work item whose `x-chud.result.commit` is the commit\n(chant 0.86's `list` on the hook's context), and from those trailers for the\nunit's other commits, so\n\n```sh\nchant workspace graph --intent app/server.js --json\n```\n\nlists the commits that touched the file (a `path:start-end` region narrows\nit to lines), each joined to the unit that made it (`work/W-NNN-<slug>.md`),\nthe contract it served and the evidence it cited, with the decisions whose\n`constrains` cover the file and what they pin, and the work items whose\nwindow a commit fell in (`worked`). Read it before changing code\na decision governs. The template pins chant 0.86, which has all of this.\nchant marks a commit inside a decision's window `decided-by-window`, and the\nkind adds `plugin:chud:contract-moved` for a unit commit whose contract's\ncriteria differ from those the first unit under that decision served: the\ncontract moved with no decision. Record a decision before you change what a\ncontract asks for.\n",
   "README.md": "# {{chant:name}}\n\nA chant workspace made from the studio kit's template\n([arugula-salad/studio](https://github.com/arugula-salad/studio) `template/`),\nwhich is chant's reference workspace with an app, a delivery project and\nrecords laid onto it. It started as chud's template (jhgaylor/chud 43afcf1)\nand moved into the kit when chud began to retire (arugula-salad/studio#37).\nThe app is built with hud in the page, and releases ship through chant Ops.\n\n```sh\nchant init --from <studio checkout>/template --param name=\"{{chant:name}}\" [--param issue=owner/repo#1] <dir>\nnode <studio checkout>/box/setup-app.mjs <dir>   # free ports, npm install in delivery/, git init, the first commit\ncd <dir>/app && npm run dev                      # the app, restarted on every change (node --watch)\n```\n\nA studio box does both steps in `box/provision-template.sh` and runs the\napp's `dev` script behind hud's proxy. No chud command runs.\n\n[`chant.workspace.json`](chant.workspace.json) declares the members, and\n`chant workspace ls` lists them. The release Op finds everything through them.\n\n| Member | Directory | Kind | What it is |\n|---|---|---|---|\n| app | [`app/`](app) | `other` | the product: a Node HTTP server with SQLite migrations and its own tests |\n| delivery | [`delivery/`](delivery) | `chant` | the chant project, which still runs on chud's runtime package (`@intentius/chud-runtime`) and the chud lexicon until they are split out of chud (INTENTIUS/chant#2713): the release, rollback, upgrade and dispatch Ops, the sites releases ship to, the agents that build the app, the decision points, the write-scope policy and this repo's CI |\n| design-client | [`design-client/`](design-client) | `other`, role `design-app` | a placeholder for a vendored design client (chant's reference workspace, #2524 D18) |\n| design | [`design/`](design) | `other` | the design data: chud's records (contracts, drivers, evidence, sessions, context, proposals), the screen specs, and the design app's overrides |\n\nThe root also holds [`decisions/`](decisions), the decision records. They\nare chant decision records, the format of chant's `docs/design/decisions/`\n(the kind file and schema are beside them): `ref-001` and `ref-002` from\nchant's reference workspace, `chud-001`, and the `chud-NNN` records the design\napp writes as the team decides. Each cites the issue this app's design is\ntracked in (`chud.decisions.issue` in `delivery/chant.config.ts`, the\ntemplate's optional `issue` parameter) as its source, or without one the\nsource of `chud-001`:\n\n```sh\nchant workspace records --kind decisions/decision.kind.mjs --current\n```\n\n[`work/`](work) holds the units of work: every agent run and piece of\nmanual work is a chant work item (`W-NNN-<slug>.md`, chant's work kind with\nchud's fields under `x-chud`), written by chud through `chant workspace\nrecords new` and `records amend`. Both kinds are declared in\n`chant.workspace.json` `records`:\n\n```sh\nchant workspace records --kind work/work.kind.mjs\n```\n\n`.chant/workspace.lock.json`, written by `chant init --from`, records the\ntemplate's lineage: where it came from, at which commit, and the parameters\nit was made with.\n\n## Everyday commands\n\nIn `delivery/`:\n\n```sh\nnpm run release      # chant run release --on chud: check, plan, stop at the ship gate\nchant approve release ship --plan <digest>\nnpm run release      # ship it\nnpm run rollback\nnpm run upgrade      # move to a newer @intentius/chud-runtime, through its gate\nnpm run check        # the app's tests and every approved contract's check (CI runs this)\nnpm run lint         # chant lint agents, with the contract-sizing rules\n```\n\nAt the root:\n\n```sh\nchant workspace check\nchant workspace build\nchant workspace lint\n```\n\n`CLAUDE.md` is the map for agents, and `design/CLAUDE.md` has the rules for\nthe records.\n",

package/src/workspace/app-kind.test.ts

@@ -0,0 +1,196 @@
+/**
+ * The app member kind and member fields (#3151, ws-093): a data-only kinds
+ * file that declares the fields its members set, a probe that reads a key of
+ * a JSON file, WSP005 on a field the kind doesn't declare, and status --json
+ * printing every field with its defaults.
+ */
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "./checks";
+import { createKindRegistry, parseKindData, probeKind, readPackageKinds, resolveKind, resolveMemberFields, type MemberKind } from "./kinds";
+import { workspaceStatus } from "./status";
+import { workingTree } from "./tree";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const canonical = join(here, "reference-kinds", "app");
+const reference = join(here, "..", "..", "..", "..", "reference-workspace");
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-3151-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+/** A workspace that pins a copy of the app kind at kinds/app. */
+function appWorkspace(members: unknown[], files: Record<string, string> = {}): string {
+  const root = repo({ "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, members, pins: [{ path: "kinds/app" }] }, null, 2), ...files });
+  cpSync(canonical, join(root, "kinds", "app"), { recursive: true });
+  return root;
+}
+
+const app = (): MemberKind => {
+  const read = readPackageKinds(canonical, "kinds/app");
+  expect(read.problems).toEqual([]);
+  return read.kinds[0];
+};
+
+const pkg = (scripts: Record<string, string>) => JSON.stringify({ name: "web", scripts });
+
+describe("the app kind's file", () => {
+  test("is valid kind data: one kind, app, with the outputs and fields a delivery member and an orchestrator read", () => {
+    const k = app();
+    expect(k.name).toBe("app");
+    expect(k.outputs).toEqual({ from: "declared", names: ["source", "url"] });
+    expect(Object.keys(k.fields ?? {})).toEqual(["scripts", "env", "health"]);
+  });
+
+  test("the reference workspace pins a byte-for-byte copy of it", () => {
+    const files = readdirSync(canonical).sort();
+    expect(readdirSync(join(reference, "kinds", "app")).sort()).toEqual(files);
+    for (const f of files) expect(readFileSync(join(reference, "kinds", "app", f), "utf-8")).toBe(readFileSync(join(canonical, f), "utf-8"));
+  });
+
+  test("its probe claims a Node package with a start script and nothing else, and a chant project outranks it", () => {
+    const tree = workingTree(
+      repo({
+        "web/package.json": pkg({ start: "node server.js" }),
+        "lib/package.json": pkg({ test: "node --test" }),
+        "broken/package.json": "{ not json",
+        "none/README.md": "",
+        "both/package.json": pkg({ start: "node x.js" }),
+        "both/chant.config.ts": "",
+      }),
+    );
+    const k = app();
+    expect(["web", "lib", "broken", "none"].map((d) => probeKind(k, tree, d))).toEqual([true, false, false, false]);
+    const kinds = createKindRegistry([k]);
+    expect(resolveKind(kinds, tree, "both").winner?.name).toBe("chant");
+    expect(resolveKind(kinds, tree, "web").winner?.name).toBe("app");
+  });
+});
+
+describe("anyJsonKey and fields in a kinds file", () => {
+  const base = { name: "svc", description: "a service", precedence: 10, probe: { anyJsonKey: { in: ["svc.json"], pointers: ["/run", "/a~1b/c"] } } };
+  const file = (kinds: unknown[]) => JSON.stringify({ schema: 1, kinds });
+
+  test("anyJsonKey takes JSON Pointers, with ~1 for a slash in a key", () => {
+    const tree = workingTree(repo({ "a/svc.json": '{"run":null}', "b/svc.json": '{"a/b":{"c":1}}', "c/svc.json": '{"a":{"b":{"c":1}}}' }));
+    const k = parseKindData(file([base]), "p").kinds[0];
+    expect(["a", "b", "c"].map((d) => probeKind(k, tree, d))).toEqual([true, true, false]);
+  });
+
+  test("a pointer must start with a slash, and a field's type, description and default are checked", () => {
+    expect(parseKindData(file([{ ...base, probe: { anyJsonKey: { in: ["svc.json"], pointers: ["run"] } } }]), "p").problems[0]).toMatch(/pointers/);
+    expect(parseKindData(file([{ ...base, fields: { port: { type: "integer", description: "the port", default: 80 } } }]), "p").problems).toEqual([]);
+    expect(parseKindData(file([{ ...base, fields: { port: { type: "number", description: "the port" } } }]), "p").problems.length).toBeGreaterThan(0);
+    expect(parseKindData(file([{ ...base, fields: { port: { type: "integer", description: "the port", default: "80" } } }]), "p").problems).toEqual([
+      "p: kind svc declares field port whose default is \"80\", and the field is an integer",
+    ]);
+    expect(parseKindData(file([{ ...base, fields: { path: { type: "string", description: "a path", default: "x", pattern: "^/" } } }]), "p").problems).toEqual([
+      'p: kind svc declares field path whose default is "x", which does not match ^/',
+    ]);
+    expect(parseKindData(file([{ ...base, fields: { path: { type: "string", description: "a path", pattern: "(" } } }]), "p").problems[0]).toMatch(/not a regular expression/);
+  });
+});
+
+describe("resolveMemberFields", () => {
+  test("fills every declared field from its default, and keeps what the entry sets", () => {
+    const r = resolveMemberFields(app(), { health: "/healthz", scripts: { start: "serve" } });
+    expect(r.problems).toEqual([]);
+    expect(r.fields).toEqual({
+      scripts: { start: "serve", dev: "dev", test: "test", migrate: "migrate" },
+      env: { port: "PORT", data: "APP_DATA", revision: "APP_REVISION" },
+      health: "/healthz",
+    });
+  });
+
+  test("a field the kind doesn't declare, a value of the wrong type or pattern, and an object given a scalar are problems, and read as the default", () => {
+    const r = resolveMemberFields(app(), { healthz: "/x", health: "health", env: { port: 8080, host: "x" }, scripts: "start" });
+    expect(r.problems.map((p) => p.path)).toEqual(["healthz", "scripts", "env/host", "env/port", "health"]);
+    expect(r.fields?.health).toBe("/health");
+    expect(r.fields?.env).toEqual({ port: "PORT", data: "APP_DATA", revision: "APP_REVISION" });
+  });
+
+  test("a kind with no fields reads as null, and fields set on it are one problem; an unknown kind has nothing to check", () => {
+    const other: MemberKind = { ...app(), name: "plain", fields: undefined };
+    expect(resolveMemberFields(other, null)).toEqual({ fields: null, problems: [] });
+    expect(resolveMemberFields(other, { health: "/" }).problems).toHaveLength(1);
+    expect(resolveMemberFields(undefined, { health: "/" })).toEqual({ fields: null, problems: [] });
+  });
+});
+
+describe("chant workspace check and status on an app member", () => {
+  const ids = async (root: string) => (await runDeclarationChecks(root)).diagnostics.map((d) => `${d.ruleId}:${d.entity ?? ""}:${d.message}`);
+
+  test("an app member with valid fields checks clean, and a delivery member may link to its source", async () => {
+    const root = appWorkspace(
+      [
+        { name: "web", dir: "web", kind: "app", fields: { health: "/healthz" } },
+        { name: "deploy", dir: "deploy", kind: "chant", links: [{ member: "web", output: "source" }] },
+      ],
+      { "web/package.json": pkg({ start: "node server.js" }), "deploy/chant.config.ts": "" },
+    );
+    expect(await ids(root)).toEqual([]);
+  });
+
+  test("a bad field, fields on a kind that declares none, and an app with no start script fail WSP005", async () => {
+    const root = appWorkspace(
+      [
+        { name: "web", dir: "web", kind: "app", fields: { health: "healthz", port: 3000 } },
+        { name: "lib", dir: "lib", kind: "app" },
+        { name: "deploy", dir: "deploy", kind: "chant", fields: { health: "/" } },
+      ],
+      { "web/package.json": pkg({ start: "node server.js" }), "lib/package.json": pkg({ test: "x" }), "deploy/chant.config.ts": "" },
+    );
+    const found = await ids(root);
+    expect(found).toHaveLength(4);
+    expect(found.every((f) => f.startsWith("WSP005:"))).toBe(true);
+    expect(found.join("\n")).toMatch(/web: field health is "healthz", which does not match \^\//);
+    expect(found.join("\n")).toMatch(/web: kind app declares no field port/);
+    expect(found.join("\n")).toMatch(/lib \(lib\) is not an app/);
+    expect(found.join("\n")).toMatch(/deploy: kind chant declares no fields/);
+  });
+
+  test("an other member that is a Node package with a start script is claimed by the app kind (WSP008), and one without isn't", async () => {
+    const root = appWorkspace(
+      [
+        { name: "server", dir: "server", kind: "other", because: "a server" },
+        { name: "tools", dir: "tools", kind: "other", because: "scripts" },
+      ],
+      { "server/package.json": pkg({ start: "node s.js" }), "tools/package.json": pkg({ build: "x" }) },
+    );
+    const found = await ids(root);
+    expect(found.filter((f) => f.startsWith("WSP008"))).toEqual([expect.stringMatching(/^WSP008:server:.*declare it as app/)]);
+  });
+
+  test("status --json prints each member's fields, with defaults, and null for a kind with none", async () => {
+    const root = appWorkspace([
+      { name: "web", dir: "web", kind: "app", fields: { scripts: { migrate: "db:migrate" } } },
+      { name: "notes", dir: "notes", kind: "other", because: "notes" },
+    ], { "web/package.json": pkg({ start: "node server.js" }), "notes/README.md": "" });
+    execFileSync("git", ["add", "-A"], { cwd: root });
+    execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-qm", "init"], { cwd: root });
+    const doc = await workspaceStatus({ cwd: root, env: "prod" });
+    if ("error" in doc) throw new Error(doc.error.message);
+    const byName = Object.fromEntries(doc.members.map((m) => [m.name, m.fields]));
+    expect(byName.web).toEqual({
+      scripts: { start: "start", dev: "dev", test: "test", migrate: "db:migrate" },
+      env: { port: "PORT", data: "APP_DATA", revision: "APP_REVISION" },
+      health: "/health",
+    });
+    expect(byName.notes).toBeNull();
+  });
+});

package/src/workspace/box-cli.ts

@@ -0,0 +1,113 @@
+/**
+ * `chant workspace box`: a member's box block. Two verbs:
+ *
+ * - `box listing set <member>` (#3308) changes the box's listing
+ *   (`box-listing.ts`). A box's other configuration is changed by editing the
+ *   declaration in a reviewed change.
+ * - `box publish <member> <item> | --records` (#3165, ws-088) runs the
+ *   publisher the box block names and checks what it did (`box-publish.ts`).
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { BOX_LISTING_CONTRACT_VERSION, BOX_LISTING_WRITE_SCHEMA_ID, boxListingSet, type BoxListingWriteDocument } from "./box-listing";
+import { BOX_PUBLISH_CONTRACT_VERSION, BOX_PUBLISH_SCHEMA_ID, boxPublish, type BoxPublishDocument } from "./box-publish";
+import { readerVersion } from "./declaration";
+import { AGENT_ENV } from "./write-scope";
+
+const USAGE = "chant workspace box listing set <member> [--from <file|->] [--cover <image> [--cover-path <path>]] [--by <principal>] [--dry-run] [--json]";
+const PUBLISH_USAGE = "chant workspace box publish <member> (<item> | --records) [--by <principal>] [--head <owner/name>] [--dry-run] [--json]";
+
+export async function runWorkspaceBox(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const cwd = process.cwd();
+  // workspace box <noun> <verb> <member>, or workspace box publish <member> [<item>]
+  const [, noun, verb, member, ...extra] = args.positionals ?? [];
+  // For publish, the third positional is the member and the fourth the item.
+  if (noun === "publish") return runPublish(ctx, verb, member === undefined ? [] : [member, ...extra]);
+  if (noun !== "listing" || verb !== "set") {
+    console.error(
+      formatError({
+        message: noun === undefined ? "chant workspace box takes listing set <member> or publish <member>" : `chant workspace box takes listing set <member> or publish <member>, not ${[noun, verb].filter(Boolean).join(" ")}`,
+        hint: `${USAGE}\n${PUBLISH_USAGE}`,
+      }),
+    );
+    return 1;
+  }
+  const print = (doc: BoxListingWriteDocument): number => {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc ? 1 : 0;
+  };
+  const usage = (message: string) =>
+    print({ $schema: BOX_LISTING_WRITE_SCHEMA_ID, contract: BOX_LISTING_CONTRACT_VERSION, chant: readerVersion(), member: member ?? null, error: { code: "write-usage-invalid", message } });
+  if (member === undefined) return usage("box listing set needs the member whose box it lists: box listing set <member>");
+  if (extra.length > 0) return usage(`box listing set takes one member, and was also given ${extra.join(" ")}`);
+  for (const [flag, v] of [["--set", args.set], ["--kind", args.kind], ["--at", args.at]] as const) {
+    if (v !== undefined) return usage(`box listing set takes its fields with --from, not ${flag}`);
+  }
+  let fields: string | undefined;
+  if (args.migrateFrom !== undefined) {
+    try {
+      fields = readFileSync(args.migrateFrom === "-" ? 0 : resolve(cwd, args.migrateFrom), "utf-8");
+    } catch (err) {
+      return print({
+        $schema: BOX_LISTING_WRITE_SCHEMA_ID,
+        contract: BOX_LISTING_CONTRACT_VERSION,
+        chant: readerVersion(),
+        member,
+        error: { code: "write-input-invalid", message: `--from ${args.migrateFrom} could not be read: ${err instanceof Error ? err.message : String(err)}` },
+      });
+    }
+  }
+  return print(
+    boxListingSet({
+      cwd,
+      member,
+      fields,
+      cover: args.cover,
+      coverPath: args.coverPath,
+      by: args.by,
+      agent: process.env[AGENT_ENV] || undefined,
+      dryRun: args.dryRun === true,
+    }),
+  );
+}
+
+/** `box publish <member> <item>` or `box publish <member> --records`. */
+function runPublish(ctx: CommandContext, member: string | undefined, rest: string[]): number {
+  const { args } = ctx;
+  const [item, ...extra] = rest;
+  const print = (doc: BoxPublishDocument): number => {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc ? 1 : 0;
+  };
+  const usage = (message: string) =>
+    print({
+      $schema: BOX_PUBLISH_SCHEMA_ID,
+      contract: BOX_PUBLISH_CONTRACT_VERSION,
+      chant: readerVersion(),
+      member: member ?? null,
+      action: args.records ? "records" : "item",
+      item: item ?? null,
+      error: { code: "write-usage-invalid", message: `${message}; ${PUBLISH_USAGE}` },
+    });
+  if (member === undefined) return usage("box publish needs the member whose box publishes");
+  if (extra.length > 0) return usage(`box publish takes one work item, and was also given ${extra.join(" ")}`);
+  for (const [flag, v] of [["--from", args.migrateFrom], ["--set", args.set], ["--kind", args.kind], ["--at", args.at], ["--cover", args.cover]] as const) {
+    if (v !== undefined) return usage(`box publish takes no ${flag}`);
+  }
+  return print(
+    boxPublish({
+      cwd: process.cwd(),
+      member,
+      item,
+      records: args.records === true,
+      by: args.by,
+      head: args.head,
+      dryRun: args.dryRun === true,
+      agent: process.env[AGENT_ENV] || undefined,
+    }),
+  );
+}

package/src/workspace/box-factory.test.ts

@@ -79,6 +79,7 @@ describe("the factory on a box block (#3146)", () => {
       check: { run: "npm run --silent check && npm test --silent", kind: "test" },
       checks: "checks",
       builders: "steward",
+      tiers: [],
       publish: { forge: "github", repo: "arugula-salad/studio", base: null, branchPrefix: "box/", head: null },
       pointer: "/members/1/box/factory",
     });
@@ -223,7 +224,7 @@ describe("protected paths in writeScope (#3146)", () => {
     expect(judgePath(d, writer, "chant.workspace.json", { before: () => before, after: () => alsoName })).toMatchObject({
       ok: false,
       code: "write-scope-protected",
-      message: expect.stringContaining("outside the top-level keys it allows (diagrams)"),
+      message: expect.stringContaining("outside what its except allows (diagrams)"),
     });
     // Without the change in hand, an except entry can't be satisfied.
     expect(judgePath(d, writer, "chant.workspace.json")).toMatchObject({ ok: false, code: "write-scope-protected" });
@@ -262,6 +263,8 @@ describe("the read contract: status, graph, agent and check --changes (#3146)",
       check: { run: "npm run --silent check && npm test --silent", kind: "test" },
       checks: "checks",
       builders: "steward",
+      tiers: [],
+      builderFor: { studio: {} },
       publish: { forge: "github", repo: "arugula-salad/studio", base: null, branchPrefix: "box/", head: null },
     });
     expect(box.listing).toEqual({

package/src/workspace/box-factory.ts

@@ -11,7 +11,7 @@
  */
 
 import { createHash } from "node:crypto";
-import type { BoxFactory, BoxListing, Declaration, FactoryCheckKind } from "./declaration";
+import type { BoxFactory, BoxListing, Declaration, FactoryCheckKind, FactoryTier } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import type { WorkspaceTree } from "./tree";
 
@@ -36,6 +36,15 @@ export interface FactoryView {
   check: { run: string; kind: FactoryCheckKind } | null;
   checks: string | null;
   builders: string | null;
+  /** Which builder agent builds at which tier, as declared (#3152, ws-094); empty when none is. */
+  tiers: FactoryTier[];
+  /**
+   * The builder for each member the factory builds, by tier (#3152): the
+   * entry for the tier that names the member's kind, else the tier's entry
+   * with no kinds. A tier with no entry for the member is left out, so a
+   * reader resolves a work item's tier with one lookup, without studio.
+   */
+  builderFor: Record<string, Record<string, { agent: string; session: string | null }>>;
   publish: { forge: "github"; repo: string; base: string | null; branchPrefix: string; head: string | null } | null;
 }
 
@@ -62,17 +71,37 @@ export function plantability(declaration: Declaration): Plantable {
   };
 }
 
-export function factoryView(f: BoxFactory | null): FactoryView | null {
+/** A box's factory as the read contract prints it. `members` gives each built member's kind, for `builderFor`. */
+export function factoryView(f: BoxFactory | null, members: readonly { name: string; kind: string }[] = []): FactoryView | null {
   if (f === null) return null;
   return {
     builds: [...f.builds],
     check: f.check === null ? null : { ...f.check },
     checks: f.checks,
     builders: f.builders,
+    tiers: f.tiers.map((t) => ({ ...t, kinds: t.kinds === null ? null : [...t.kinds] })),
+    builderFor: builderTable(f, members),
     publish: f.publish === null ? null : { ...f.publish },
   };
 }
 
+/** The builder table (#3152): for each built member, each tier's agent, by the member's kind first and the tier's default second. */
+export function builderTable(f: BoxFactory, members: readonly { name: string; kind: string }[]): FactoryView["builderFor"] {
+  const tiers = [...new Set(f.tiers.map((t) => t.tier))];
+  const out: FactoryView["builderFor"] = {};
+  for (const name of f.builds) {
+    const kind = members.find((m) => m.name === name)?.kind;
+    const row: Record<string, { agent: string; session: string | null }> = {};
+    for (const tier of tiers) {
+      const entry =
+        f.tiers.find((t) => t.tier === tier && kind !== undefined && t.kinds?.includes(kind)) ?? f.tiers.find((t) => t.tier === tier && t.kinds === null);
+      if (entry) row[tier] = { agent: entry.agent, session: entry.session };
+    }
+    out[name] = row;
+  }
+  return out;
+}
+
 /** The listing, hashing the cover through `read` (bytes, or null when the file can't be read). */
 export function listingView(l: BoxListing | null, read: (path: string) => Uint8Array | null): ListingView | null {
   if (l === null) return null;
@@ -97,7 +126,11 @@ export function treeBytes(tree: WorkspaceTree): (path: string) => Uint8Array | n
 }
 
 /** The box fields the graph prints on a member (#3146): its factory and listing, or null when the member's box declares neither. */
-export function graphBox(box: { factory: BoxFactory | null; listing: BoxListing | null } | null, tree: WorkspaceTree): { factory: FactoryView | null; listing: ListingView | null } | null {
+export function graphBox(
+  box: { factory: BoxFactory | null; listing: BoxListing | null } | null,
+  tree: WorkspaceTree,
+  members: readonly { name: string; kind: string }[] = [],
+): { factory: FactoryView | null; listing: ListingView | null } | null {
   if (box === null || (box.factory === null && box.listing === null)) return null;
-  return { factory: factoryView(box.factory), listing: listingView(box.listing, treeBytes(tree)) };
+  return { factory: factoryView(box.factory, members), listing: listingView(box.listing, treeBytes(tree)) };
 }