@intentius/chant 0.110.0 → 0.112.0

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

@@ -4,7 +4,7 @@
  * `graph --intent` shows it for the box's files.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
 import { cleanScratch, commitAll, contract, REPO, repo } from "./__fixtures__/contract-repo";
@@ -134,13 +134,13 @@ describe("the box block's intent", () => {
 describe("a box planted as a question", () => {
   test("a proposed intent reports its question and no answer, and passes the checks", async () => {
     const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:app"]) });
-    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "proposed", question: QUESTION, choice: null, answer: null, decided_by: null, decided_on: null });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "proposed", question: QUESTION, choice: null, answer: null, decided_by: null, decided_on: null, approved: false });
     expect(await intentFindings(root)).toEqual([]);
   });
 
   test("a decided intent reports the answer and who gave it, and graph --intent shows it for the box's files", async () => {
     const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "decided", ["member:app"]) });
-    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "decided", question: QUESTION, choice: CHOICE, answer: ANSWER, decided_by: "alex", decided_on: "2026-09-26" });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "decided", question: QUESTION, choice: CHOICE, answer: ANSWER, decided_by: "alex", decided_on: "2026-09-26", approved: true });
     expect(await intentFindings(root)).toEqual([]);
     commitAll(root, "plant the box");
     const { doc } = await intentGraph({ cwd: root, region: "app" });
@@ -148,6 +148,16 @@ describe("a box planted as a question", () => {
     expect(doc.nodes.filter((n) => n.kind === "decision").map((n) => (n.kind === "decision" ? [n.record, n.state, n.decided_by] : []))).toEqual([["box-001", "decided", "alex"]]);
   });
 
+  test("approved follows the decision kind's approval ranks, not the state's name (#3609)", async () => {
+    const records = { "decisions/box-001-what-app-is-for.md": decision("box-001", "decided", ["member:app"]) };
+    const root = workspace({ intent: "box-001" }, records);
+    const kind = join(root, "decisions", "decision.kind.mjs");
+    const text = readFileSync(kind, "utf-8");
+    expect(text).toContain("decided: 1,");
+    writeFileSync(kind, text.replace("decided: 1,", "decided: 0,"));
+    expect((await boxOf(root))?.intent).toMatchObject({ state: "decided", approved: false });
+  });
+
   test("a decided intent whose choice names an option not in options[] reports a null answer", async () => {
     const data = { ...BASE, id: "box-001", title: "Intent box-001", state: "decided", question: QUESTION, choice: { option: "z", reason: "no such option" }, rejected: [], evidence: [], decided_by: "alex", decided_on: "2026-09-26", constrains: ["member:app"] };
     const record = `---\n${JSON.stringify(data, null, 2)}\n---\n\n# box-001\n`;
@@ -157,7 +167,7 @@ describe("a box planted as a question", () => {
 
   test("an intent no decision record has fails WSP126, and status reports only its id", async () => {
     const root = workspace({ intent: "box-009" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:app"]) });
-    expect((await boxOf(root))?.intent).toEqual({ id: "box-009", state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-009", state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null, approved: false });
     expect(await intentFindings(root)).toEqual([["WSP126", "error", "box-intent-unknown", "app"]]);
     const [d] = (await runDeclarationChecks(root)).diagnostics.filter((x) => x.ruleId === "WSP126");
     expect(d.message).toContain("no record of decisions/decision.kind.mjs has that id");

package/src/workspace/box-intent.ts

@@ -37,6 +37,12 @@ export interface BoxIntent {
   answer: string | null;
   decided_by: string | null;
   decided_on: string | null;
+  /**
+   * Whether the record's state counts as approved (#3609): the decision
+   * kind's `approval` rank for it is above 0, the rule the factory's pick
+   * holds dispatch with. False with no record, and for a kind with no ranks.
+   */
+  approved: boolean;
 }
 
 /** The decision record a box's intent names, as the checks read it. */
@@ -71,7 +77,7 @@ function answerOf(choice: unknown, options: unknown): string | null {
 
 /** The intent of `id` with no record: every field but the id null. */
 export function unresolvedIntent(id: string): BoxIntent {
-  return { id, state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null };
+  return { id, state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null, approved: false };
 }
 
 /**
@@ -96,6 +102,7 @@ export async function resolveBoxIntents(declaration: Declaration, root: string,
     try {
       const read = await readRecordsFor({ kind: k.file, cwd: root, workGaps: false });
       const field = read.loaded.kind.constrains?.field ?? "constrains";
+      const approval = read.loaded.kind.approval ?? {};
       for (const r of read.result.records) {
         if (r.id === null || found.has(r.id)) continue;
         const data = r.data ?? {};
@@ -112,6 +119,7 @@ export async function resolveBoxIntents(declaration: Declaration, root: string,
             answer: answerOf(data.choice, data.options),
             decided_by: str(data.decided_by),
             decided_on: str(data.decided_on),
+            approved: r.state !== null && (approval[r.state] ?? 0) > 0,
           },
         });
       }

package/src/workspace/declaration-extensions.test.ts

@@ -0,0 +1,79 @@
+/**
+ * #3595: the x- keys a declaration holds come back from `status --json` and
+ * `ls --json` on the object that holds them, so a reader never parses the
+ * declaration to get back what it wrote through chant.
+ */
+
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, repo } from "./__fixtures__/contract-repo";
+import { extensionsAt, parseDeclaration } from "./declaration";
+import { listWorkspace } from "./ls";
+import lsSchema from "./ls.schema.json";
+import { workspaceStatus } from "./status";
+import statusSchema from "./status.schema.json";
+
+afterAll(cleanScratch);
+
+const APP = { owner: "alex", createdAt: "2026-10-01T00:00:00.000Z", repo: "acme/fern", branch: "main" };
+
+const DECLARATION = {
+  name: "fern",
+  schema: 1,
+  "x-lobby": { slot: 3 },
+  members: [
+    { name: "app", dir: "app", kind: "other", because: "the app", "x-member": 1 },
+    {
+      name: "steward",
+      dir: "steward",
+      kind: "other",
+      because: "the box",
+      box: {
+        "x-factory": { intent: "box-001" },
+        capabilities: [{ name: "inference", scope: ["chat"], "x-cap": true }],
+        services: [{ name: "app", cmd: "node app.mjs", "x-svc": "a" }],
+        factory: { builds: ["app"], check: { run: "npm test", "x-check": 2 }, publish: { repo: "acme/fern", "x-pub": "p" }, "x-fac": "f" },
+        listing: { title: "Fern", line: "A review queue", "x-studio-app": APP },
+        ship: { op: "ship", "x-ship": "s" },
+      },
+    },
+  ],
+};
+
+describe("x- keys in the read contract (#3595)", () => {
+  const root = repo({ "chant.workspace.json": `${JSON.stringify(DECLARATION, null, 2)}\n`, "app/a.txt": "", "steward/s.txt": "" }, true);
+
+  test("extensionsAt reads the x- keys at a pointer, and nothing where there is no object", () => {
+    const decl = parseDeclaration(JSON.stringify(DECLARATION), "chant.workspace.json");
+    expect(extensionsAt(decl, "")).toEqual({ "x-lobby": { slot: 3 } });
+    expect(extensionsAt(decl, "/members/0")).toEqual({ "x-member": 1 });
+    expect(extensionsAt(decl, "/members/1/box/listing")).toEqual({ "x-studio-app": APP });
+    expect(extensionsAt(decl, "/members/0/box")).toEqual({});
+    expect(extensionsAt(decl, "/members/0/name")).toEqual({});
+    expect(extensionsAt({ ...decl }, "")).toEqual({});
+  });
+
+  test("status --json keeps them on the member, the box and the box's parts", async () => {
+    const out = await workspaceStatus({ cwd: root, env: "box" });
+    contract(statusSchema).expectValid(out);
+    if ("error" in out) throw new Error(out.error.message);
+    const [app, steward] = out.members;
+    expect(app).toMatchObject({ name: "app", "x-member": 1 });
+    const box = steward.box!;
+    expect(box).toMatchObject({ "x-factory": { intent: "box-001" } });
+    expect(box.capabilities[0]).toMatchObject({ name: "inference", "x-cap": true });
+    expect(box.services[0]).toMatchObject({ name: "app", "x-svc": "a" });
+    expect(box.factory).toMatchObject({ "x-fac": "f", check: { run: "npm test", "x-check": 2 }, publish: { repo: "acme/fern", "x-pub": "p" } });
+    expect(box.listing).toMatchObject({ title: "Fern", "x-studio-app": APP });
+    expect(box.ship).toMatchObject({ op: "ship", "x-ship": "s" });
+    expect(Object.keys(steward).filter((k) => k.startsWith("x-"))).toEqual([]);
+  });
+
+  test("ls --json keeps them on each member and on the workspace", () => {
+    const out = listWorkspace({ cwd: root });
+    contract(lsSchema).expectValid(out);
+    if ("error" in out) throw new Error(out.error.message);
+    expect(out.workspace).toMatchObject({ name: "fern", "x-lobby": { slot: 3 } });
+    expect(out.members[0]).toMatchObject({ name: "app", "x-member": 1 });
+    expect(Object.keys(out.members[1]).filter((k) => k.startsWith("x-"))).toEqual([]);
+  });
+});

package/src/workspace/declaration-write-cli.ts

@@ -0,0 +1,82 @@
+/**
+ * `chant workspace member add <name> --from <file|->`, `chant workspace
+ * member remove <name>` and `chant workspace host set <name> --from
+ * <file|->` (#3596): the command lines of `declaration-write.ts`.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { CommandContext } from "../cli/registry";
+import { readerVersion } from "./declaration";
+import {
+  DECLARATION_WRITE_CONTRACT_VERSION,
+  DECLARATION_WRITE_SCHEMA_ID,
+  declarationWrite,
+  type DeclarationWriteAction,
+  type DeclarationWriteDocument,
+} from "./declaration-write";
+import { AGENT_ENV } from "./write-scope";
+
+const USAGE: Record<DeclarationWriteAction, string> = {
+  "member add": "chant workspace member add <name> --from <file|-> [--by <principal>] [--dry-run] [--json]",
+  "member remove": "chant workspace member remove <name> [--by <principal>] [--dry-run] [--json]",
+  "host set": "chant workspace host set <name> --from <file|-> [--by <principal>] [--dry-run] [--json]",
+};
+
+const print = (doc: DeclarationWriteDocument): number => {
+  console.log(JSON.stringify(doc, null, 2));
+  return "error" in doc ? 1 : 0;
+};
+
+/** `chant workspace member add|remove <name>`. */
+export function runWorkspaceMember(ctx: CommandContext): number {
+  const [, verb, ...rest] = ctx.args.positionals ?? [];
+  const action = verb === "add" ? "member add" : verb === "remove" ? "member remove" : null;
+  if (action === null) return usage("member add", rest[0], `chant workspace member takes add <name> or remove <name>${verb === undefined ? "" : `, not ${verb}`}`);
+  return run(ctx, action, rest);
+}
+
+/** `chant workspace host set <name>`. */
+export function runWorkspaceHost(ctx: CommandContext): number {
+  const [, verb, ...rest] = ctx.args.positionals ?? [];
+  if (verb !== "set") return usage("host set", rest[0], `chant workspace host takes set <name>${verb === undefined ? "" : `, not ${verb}`}`);
+  return run(ctx, "host set", rest);
+}
+
+function usage(action: DeclarationWriteAction, name: string | undefined, message: string): number {
+  return print({
+    $schema: DECLARATION_WRITE_SCHEMA_ID,
+    contract: DECLARATION_WRITE_CONTRACT_VERSION,
+    chant: readerVersion(),
+    action,
+    name: name ?? null,
+    error: { code: "write-usage-invalid", message: `${message}; ${USAGE[action]}` },
+  });
+}
+
+function run(ctx: CommandContext, action: DeclarationWriteAction, rest: string[]): number {
+  const { args } = ctx;
+  const cwd = process.cwd();
+  const [name, ...extra] = rest;
+  if (name === undefined) return usage(action, undefined, `${action} needs a name`);
+  if (extra.length > 0) return usage(action, name, `${action} takes one name, and was also given ${extra.join(" ")}`);
+  for (const [flag, v] of [["--set", args.set], ["--kind", args.kind], ["--at", args.at], ["--cover", args.cover]] as const) {
+    if (v !== undefined) return usage(action, name, `${action} takes no ${flag}`);
+  }
+  let entry: string | undefined;
+  if (args.migrateFrom !== undefined) {
+    try {
+      entry = readFileSync(args.migrateFrom === "-" ? 0 : resolve(cwd, args.migrateFrom), "utf-8");
+    } catch (err) {
+      return print({
+        $schema: DECLARATION_WRITE_SCHEMA_ID,
+        contract: DECLARATION_WRITE_CONTRACT_VERSION,
+        chant: readerVersion(),
+        action,
+        name,
+        error: { code: "write-input-invalid", message: `--from ${args.migrateFrom} could not be read: ${err instanceof Error ? err.message : String(err)}` },
+      });
+    }
+  }
+  return print(declarationWrite({ cwd, action, name, entry, by: args.by, agent: process.env[AGENT_ENV] || undefined, dryRun: args.dryRun === true }));
+}

package/src/workspace/declaration-write.test.ts

@@ -0,0 +1,155 @@
+/**
+ * #3596: a declaration's members and hosts written through chant, the way a
+ * local lobby plants, retires and starts boxes, without editing the file.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, repo } from "./__fixtures__/contract-repo";
+import { readDeclaration } from "./declaration";
+import { declarationWrite, type DeclarationWriteDocument, type DeclarationWriteRequest } from "./declaration-write";
+import schema from "./member-write.schema.json";
+import { appendElement, removeElement, setElement } from "./json-edit";
+import { parseJsonText } from "./jsonc";
+import { workingTree } from "./tree";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(schema);
+
+const HOST = { name: "local", ports: { from: 18100, to: 18199, perBox: 10 }, stateRoot: "${STUDIO_LOBBY_HOME}/boxes" };
+const box = (name: string, slot: number) => ({
+  name,
+  dir: `boxes/${name}`,
+  kind: "other",
+  because: "a box the lobby planted",
+  box: { host: "local", slot, ports: { door: 0, site: 1 }, state: { record: "box.json" }, cookies: ["hud_session"] },
+});
+
+const JSONC = `{
+  // the lobby
+  "name": "studio-lobby",
+  "schema": 1,
+  "minReader": "0.93.0",
+  "members": [
+    // planted boxes
+  ],
+}
+`;
+
+function lobby(text = JSONC, file = "chant.workspace.jsonc"): string {
+  return repo({ [file]: text });
+}
+
+function run(root: string, req: Omit<DeclarationWriteRequest, "cwd" | "entry"> & { entry?: unknown }): DeclarationWriteDocument {
+  const doc = declarationWrite({ ...req, cwd: root, entry: req.entry === undefined ? undefined : JSON.stringify(req.entry) });
+  expectValid(doc);
+  return doc;
+}
+
+const code = (doc: DeclarationWriteDocument) => ("error" in doc ? doc.error.code : null);
+const declOf = (root: string) => readDeclaration(workingTree(root));
+
+describe("host set and member add|remove on a lobby's declaration (#3596)", () => {
+  test("the first start writes the host, plants two boxes and retires one, keeping the file's comments", () => {
+    const root = lobby();
+    const host = run(root, { action: "host set", name: "local", entry: HOST });
+    expect(host).toMatchObject({ action: "host set", name: "local", changed: true, previous: null, entry: HOST, paths: ["chant.workspace.jsonc"] });
+
+    const fern = run(root, { action: "member add", name: "fern", entry: box("fern", 0) });
+    expect(fern).toMatchObject({ changed: true, previous: null, entry: box("fern", 0) });
+    expect(run(root, { action: "member add", name: "moss", entry: { ...box("moss", 1), name: undefined } })).toMatchObject({ changed: true });
+    expect(declOf(root).members.map((m) => [m.name, m.box?.isolation?.slot])).toEqual([
+      ["fern", 0],
+      ["moss", 1],
+    ]);
+
+    const text = readFileSync(join(root, "chant.workspace.jsonc"), "utf-8");
+    expect(text).toContain("// the lobby");
+    expect(text).toContain("// planted boxes");
+    expect(declarationWrite({ cwd: root, action: "host set", name: "local", entry: JSON.stringify(HOST) })).toMatchObject({ changed: false, previous: HOST, paths: [] });
+
+    const retire = run(root, { action: "member remove", name: "fern" });
+    expect(retire).toMatchObject({ changed: true, previous: box("fern", 0), entry: null });
+    expect(declOf(root).members.map((m) => m.name)).toEqual(["moss"]);
+    expect(readFileSync(join(root, "chant.workspace.jsonc"), "utf-8")).toContain("// planted boxes");
+  });
+
+  test("host set replaces a host in place, and a dry run writes nothing", () => {
+    const root = lobby(`${JSON.stringify({ name: "l", schema: 1, members: [], hosts: [HOST] }, null, 2)}\n`, "chant.workspace.json");
+    const before = readFileSync(join(root, "chant.workspace.json"), "utf-8");
+    const wider = { ...HOST, ports: { from: 18100, to: 18299, perBox: 10 } };
+    const dry = run(root, { action: "host set", name: "local", entry: wider, dryRun: true });
+    expect(dry).toMatchObject({ changed: true, dryRun: true, previous: HOST, entry: wider });
+    expect(readFileSync(join(root, "chant.workspace.json"), "utf-8")).toBe(before);
+    run(root, { action: "host set", name: "local", entry: wider });
+    expect(declOf(root).hosts.map((h) => h.ports.to)).toEqual([18299]);
+  });
+
+  test("refuses a name taken, a member not there, an entry that doesn't read, and two boxes in one slot", () => {
+    const root = lobby();
+    run(root, { action: "host set", name: "local", entry: HOST });
+    run(root, { action: "member add", name: "fern", entry: box("fern", 0) });
+    const before = readFileSync(join(root, "chant.workspace.jsonc"), "utf-8");
+
+    expect(run(root, { action: "member add", name: "fern", entry: box("fern", 0) })).toMatchObject({ changed: false });
+    expect(code(run(root, { action: "member add", name: "fern", entry: box("fern", 2) }))).toBe("member-exists");
+    expect(code(run(root, { action: "member remove", name: "ghost" }))).toBe("member-unknown");
+    const invalid = run(root, { action: "member add", name: "moss", entry: { ...box("moss", 1), because: undefined } });
+    expect(code(invalid)).toBe("write-input-invalid");
+    expect("error" in invalid && invalid.error.message).toMatch(/needs "because"/);
+    const shared = run(root, { action: "member add", name: "moss", entry: box("moss", 0) });
+    expect(code(shared)).toBe("box-isolation-collision");
+    expect("error" in shared && shared.error.message).toMatch(/fern\.door and moss\.door/);
+    expect(code(run(root, { action: "member add", name: "moss", entry: { ...box("moss", 1), name: "fern" } }))).toBe("write-input-invalid");
+    expect(code(run(root, { action: "host set", name: "local", entry: { ...HOST, stateRoot: "/var/boxes" } }))).toBe("box-isolation-literal");
+    expect(code(run(root, { action: "member remove", name: "fern", entry: {} }))).toBe("write-usage-invalid");
+    expect(code(run(root, { action: "host set", name: "local" }))).toBe("write-usage-invalid");
+    expect(readFileSync(join(root, "chant.workspace.jsonc"), "utf-8")).toBe(before);
+  });
+
+  test("a writer the write scope at base keeps off the declaration is refused, unless except allows members and hosts", () => {
+    const decl = (except?: string[]) => ({
+      name: "l",
+      schema: 1,
+      members: [{ name: "root", dir: ".", kind: "other", because: "the lobby" }],
+      writeScope: { human: { protected: [except ? { path: "chant.workspace.json", except } : "chant.workspace.json"] } },
+    });
+    const root = repo({ "chant.workspace.json": `${JSON.stringify(decl(), null, 2)}\n` }, true);
+    git(root, "branch", "-M", "main");
+    expect(code(run(root, { action: "host set", name: "local", entry: HOST }))).toBe("write-scope-protected");
+    writeFileSync(join(root, "chant.workspace.json"), `${JSON.stringify(decl(["members", "hosts"]), null, 2)}\n`);
+    git(root, "commit", "-q", "-am", "allow the lobby's writes");
+    expect(run(root, { action: "host set", name: "local", entry: HOST })).toMatchObject({ changed: true });
+    expect(run(root, { action: "member add", name: "fern", entry: box("fern", 0) })).toMatchObject({ changed: true });
+  });
+});
+
+describe("array edits in place (#3596)", () => {
+  const read = (text: string) => {
+    const r = parseJsonText(text, { jsonc: true });
+    if (!r.ok) throw new Error(r.message);
+    return r.value;
+  };
+
+  test("append to an empty, a multi-line and a one-line array", () => {
+    expect(read(appendElement('{ "a": [] }', false, "/a", { x: 1 }))).toEqual({ a: [{ x: 1 }] });
+    const multi = '{\n  "a": [\n    1, // one\n    2\n  ]\n}\n';
+    const out = appendElement(multi, true, "/a", 3);
+    expect(out).toBe('{\n  "a": [\n    1, // one\n    2,\n    3\n  ]\n}\n');
+    expect(appendElement('{ "a": [1, 2] }', false, "/a", 3)).toBe('{ "a": [1, 2, 3] }');
+    expect(read(appendElement('{\n  "a": [\n    1,\n  ],\n}', true, "/a", 2))).toEqual({ a: [1, 2] });
+  });
+
+  test("remove the first, a middle, the last and the only element, and replace one", () => {
+    const text = '{\n  "a": [\n    1,\n    2,\n    3\n  ]\n}\n';
+    expect(removeElement(text, false, "/a", 0)).toBe('{\n  "a": [\n    2,\n    3\n  ]\n}\n');
+    expect(removeElement(text, false, "/a", 1)).toBe('{\n  "a": [\n    1,\n    3\n  ]\n}\n');
+    expect(removeElement(text, false, "/a", 2)).toBe('{\n  "a": [\n    1,\n    2\n  ]\n}\n');
+    expect(removeElement('{ "a": [1] }', false, "/a", 0)).toBe('{ "a": [] }');
+    expect(removeElement('{\n  "a": [\n    // kept\n    1\n  ]\n}', true, "/a", 0)).toBe('{\n  "a": [\n    // kept\n  ]\n}');
+    expect(read(setElement(text, false, "/a", 1, { b: true }))).toEqual({ a: [1, { b: true }, 3] });
+    expect(() => removeElement(text, false, "/a", 3)).toThrow(/no element 3/);
+  });
+});