@intentius/chant 0.101.0 → 0.104.0

package/src/terraform/hcl2json.ts

@@ -0,0 +1,81 @@
+/**
+ * The optional HCL parser, loaded lazily. Kept apart from `parse.ts` so a
+ * caller that only needs the loader (the terraform lexicon's HCL reader) does
+ * not pull in the dependency graph, the state reader and the carve tables.
+ *
+ * `@cdktn/hcl2json` is NOT a chant dependency: it carries a ~1.8 MB wasm blob
+ * and only HCL users need it. If it is absent the loader fails with a
+ * one-line install hint.
+ */
+
+import { appendFileSync } from "fs";
+import type { Hcl2JsonTree } from "./types";
+
+/** Minimal shape of the parser exports we depend on. */
+export interface Hcl2Json {
+  parse: (filename: string, hcl: string) => Promise<Hcl2JsonTree>;
+  /** Expression-AST reference extraction (#998) — one traversal accessor per reference. */
+  getReferencesInExpression: (filename: string, expression: string) => Promise<Array<{ value: string }>>;
+}
+
+export class Hcl2JsonNotInstalled extends Error {
+  constructor(cause: unknown) {
+    super(
+      "Terraform carve-out needs the HCL parser, which is not installed.\n" +
+        "  Install it once:  npm install -D @cdktn/hcl2json\n" +
+        `(underlying error: ${cause instanceof Error ? cause.message : String(cause)})`,
+    );
+    this.name = "Hcl2JsonNotInstalled";
+  }
+}
+
+/**
+ * The environment variable that turns on parser-input recording (chant #2483).
+ *
+ * When set to a file path, every `parse(filename, source)` and every
+ * `getReferencesInExpression(filename, expression)` this process makes is
+ * appended to that file as one JSON line before the real call runs. That is
+ * how `scripts/check-hcl-parser-parity.ts` gets hold of the inline HCL the
+ * test suite parses, which no corpus walk on disk would find: run the suite
+ * with this set, then replay the file through two parsers and compare. Off
+ * unless set, and never changes a result.
+ */
+export const HCL2JSON_RECORD_ENV = "CHANT_HCL2JSON_RECORD";
+
+/** One recorded parser input, as {@link HCL2JSON_RECORD_ENV} writes it. */
+export interface Hcl2JsonRecordLine {
+  kind: "parse" | "refs";
+  filename: string;
+  text: string;
+}
+
+function recording(parser: Hcl2Json, path: string): Hcl2Json {
+  const note = (line: Hcl2JsonRecordLine): void => {
+    appendFileSync(path, `${JSON.stringify(line)}\n`);
+  };
+  return {
+    parse: (filename, hcl) => {
+      note({ kind: "parse", filename, text: hcl });
+      return parser.parse(filename, hcl);
+    },
+    getReferencesInExpression: (filename, expression) => {
+      note({ kind: "refs", filename, text: expression });
+      return parser.getReferencesInExpression(filename, expression);
+    },
+  };
+}
+
+/**
+ * Lazy-load the optional HCL parser. Throws `Hcl2JsonNotInstalled` with an
+ * install hint when the package is missing, rather than a raw MODULE_NOT_FOUND.
+ */
+export async function loadHcl2json(): Promise<Hcl2Json> {
+  let parser: Hcl2Json;
+  try {
+    parser = (await import("@cdktn/hcl2json")) as Hcl2Json;
+  } catch (err) {
+    throw new Hcl2JsonNotInstalled(err);
+  }
+  const record = process.env[HCL2JSON_RECORD_ENV];
+  return record ? recording(parser, record) : parser;
+}

package/src/terraform/parse.ts

@@ -1,87 +1,24 @@
 /**
  * Thin wasm glue for the carve-out advisor (#214 T1): read a Terraform estate's
  * `.tf` files, run them through `@cdktn/hcl2json`, merge into one tree, and hand
- * off to the pure `buildGraph`.
- *
- * `@cdktn/hcl2json` is NOT a chant dependency — it carries a ~1.8 MB wasm blob
- * and only carve-out users need it. It is lazy-loaded here and, if absent, the
- * advisor fails with a one-line install hint.
+ * off to the pure `buildGraph`. The parser loader lives in `./hcl2json`, which
+ * this module re-exports.
  */
 
-import { appendFileSync, readdirSync, readFileSync } from "fs";
+import { readdirSync, readFileSync } from "fs";
 import { join } from "path";
 import { buildGraph, collectExpressions, type ExpressionRefs } from "./graph";
 import { readStateInstanceCounts, applyStateCounts } from "./state";
+import { loadHcl2json, type Hcl2Json } from "./hcl2json";
 import type { Hcl2JsonTree, TfGraph } from "./types";
 
-/** Minimal shape of the parser exports we depend on. */
-export interface Hcl2Json {
-  parse: (filename: string, hcl: string) => Promise<Hcl2JsonTree>;
-  /** Expression-AST reference extraction (#998) — one traversal accessor per reference. */
-  getReferencesInExpression: (filename: string, expression: string) => Promise<Array<{ value: string }>>;
-}
-
-export class Hcl2JsonNotInstalled extends Error {
-  constructor(cause: unknown) {
-    super(
-      "Terraform carve-out needs the HCL parser, which is not installed.\n" +
-        "  Install it once:  npm install -D @cdktn/hcl2json\n" +
-        `(underlying error: ${cause instanceof Error ? cause.message : String(cause)})`,
-    );
-    this.name = "Hcl2JsonNotInstalled";
-  }
-}
-
-/**
- * The environment variable that turns on parser-input recording (chant #2483).
- *
- * When set to a file path, every `parse(filename, source)` and every
- * `getReferencesInExpression(filename, expression)` this process makes is
- * appended to that file as one JSON line before the real call runs. That is
- * how `scripts/check-hcl-parser-parity.ts` gets hold of the inline HCL the
- * test suite parses, which no corpus walk on disk would find: run the suite
- * with this set, then replay the file through two parsers and compare. Off
- * unless set, and never changes a result.
- */
-export const HCL2JSON_RECORD_ENV = "CHANT_HCL2JSON_RECORD";
-
-/** One recorded parser input, as {@link HCL2JSON_RECORD_ENV} writes it. */
-export interface Hcl2JsonRecordLine {
-  kind: "parse" | "refs";
-  filename: string;
-  text: string;
-}
-
-function recording(parser: Hcl2Json, path: string): Hcl2Json {
-  const note = (line: Hcl2JsonRecordLine): void => {
-    appendFileSync(path, `${JSON.stringify(line)}\n`);
-  };
-  return {
-    parse: (filename, hcl) => {
-      note({ kind: "parse", filename, text: hcl });
-      return parser.parse(filename, hcl);
-    },
-    getReferencesInExpression: (filename, expression) => {
-      note({ kind: "refs", filename, text: expression });
-      return parser.getReferencesInExpression(filename, expression);
-    },
-  };
-}
-
-/**
- * Lazy-load the optional HCL parser. Throws `Hcl2JsonNotInstalled` with an
- * install hint when the package is missing, rather than a raw MODULE_NOT_FOUND.
- */
-export async function loadHcl2json(): Promise<Hcl2Json> {
-  let parser: Hcl2Json;
-  try {
-    parser = (await import("@cdktn/hcl2json")) as Hcl2Json;
-  } catch (err) {
-    throw new Hcl2JsonNotInstalled(err);
-  }
-  const record = process.env[HCL2JSON_RECORD_ENV];
-  return record ? recording(parser, record) : parser;
-}
+export {
+  loadHcl2json,
+  Hcl2JsonNotInstalled,
+  HCL2JSON_RECORD_ENV,
+  type Hcl2Json,
+  type Hcl2JsonRecordLine,
+} from "./hcl2json";
 
 /**
  * Resolve every interpolated string in the merged tree through the parser's

package/src/workspace/agent-cli.ts

@@ -60,6 +60,8 @@ export type AgentDocument =
         members: string[];
         /** Every declared kind in reach: the workspace's own and the member's. */
         records: AgentKindScope[];
+        /** The paths writeScope.agent.protected keeps the session from writing, with the JSON keys each still allows (#3146). */
+        protected: { path: string; except: string[] }[];
       };
       /** The spec, as records --current --json prints it. */
       spec: SpecView;
@@ -77,10 +79,11 @@ export async function agentSession(q: { cwd: string; name: string }): Promise<Ag
       throw new WorkspaceReadError("declaration-missing", "no chant.workspace.json or .jsonc between this directory and the git root, so no agent session is declared");
     }
     const decl = source.declaration;
-    const writer = resolveWriter(decl, source.policy, { agent: q.name });
+    const writer = resolveWriter(decl, source.policy, { agent: q.name }, source.classes);
     const agent = writer.agent!;
     const member = decl.members.find((m) => m.name === agent.member)!;
-    const rules = scopeOf(decl, writer)!.records;
+    const scope = scopeOf(decl, writer)!;
+    const rules = scope.records;
     // The spec query, over every declared kind in the working tree.
     const set = await queryDeclaredRecords(declaredKindFiles(q.cwd), { cwd: q.cwd, current: true });
     const loadedName = new Map(set.kinds.map((k) => [k.declared.path, "error" in k ? null : k.kind.name]));
@@ -94,7 +97,7 @@ export async function agentSession(q: { cwd: string; name: string }): Promise<Ag
       ...head,
       workspace: { name: decl.name, root: source.root ?? ".", scopeFrom: source.from },
       agent: { name: agent.name, member: { name: member.name, dir: member.dir, kind: member.kind }, principals: agent.principals },
-      scope: { members: [member.name], records },
+      scope: { members: [member.name], records, protected: scope.protected.map((p) => ({ path: p.path, except: [...p.except] })) },
       spec: set.spec ?? { kinds: [], records: [] },
       reload: [`chant workspace agent ${agent.name} --json`, "chant workspace records --current --json"],
     };
@@ -126,6 +129,7 @@ export async function runWorkspaceAgent(ctx: CommandContext): Promise<number> {
   const out: string[] = [];
   out.push(`agent     ${doc.agent.name}, bound to member ${doc.agent.member.name} (${doc.agent.member.dir}), scope read from ${doc.workspace.scopeFrom}`);
   for (const r of doc.scope.records) out.push(`records   ${r.name ?? r.kind ?? r.path} (${r.path}): ${r.verbs.length > 0 ? r.verbs.join(", ") : "not writable"}`);
+  for (const p of doc.scope.protected) out.push(`protected ${p.path}${p.except.length > 0 ? ` (except ${p.except.join(", ")})` : ""}`);
   out.push(`spec      ${doc.spec.records.length} current records of ${doc.spec.kinds.length} spec kinds`);
   for (const r of doc.spec.records) out.push(`          ${r.kind}/${r.id ?? "?"} ${r.state ?? ""} ${r.path}`);
   out.push(`reload    ${doc.reload.join("; ")}`);

package/src/workspace/agent.schema.json

@@ -165,6 +165,28 @@
                   }
                 }
               }
+            },
+            "protected": {
+              "type": "array",
+              "description": "Added in contract 1 by #3146. The paths writeScope.agent.protected keeps the session from writing even inside its member, each a glob from the workspace root that also covers everything under a directory it matches, with the top-level keys of a JSON file a write may still change in except. Empty when none is listed. check --changes reports a write to one with write-scope-protected.",
+              "items": {
+                "type": "object",
+                "required": [
+                  "path",
+                  "except"
+                ],
+                "properties": {
+                  "path": {
+                    "type": "string"
+                  },
+                  "except": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
             }
           }
         },

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