@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/__fixtures__/contract-repo.js

@@ -0,0 +1,103 @@
+/**
+ * Helpers the read-contract tests share (#2536): throwaway git repositories,
+ * a draft 2020-12 validator, and a fake chant toolchain.
+ */
+import { execFileSync } from "node:child_process";
+import { chmodSync, 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 { expect } from "vitest";
+/** The chant checkout these tests run in. */
+export const REPO = realpathSync(join(import.meta.dirname, "..", "..", "..", "..", ".."));
+const scratch = [];
+/** Remove every directory {@link scratchDir} and {@link repo} made. Call it from `afterAll`. */
+export function cleanScratch() {
+    for (const d of scratch.splice(0))
+        rmSync(d, { recursive: true, force: true });
+}
+export function scratchDir(prefix = "chant-contract-") {
+    const d = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+    scratch.push(d);
+    return d;
+}
+export function git(cwd, ...args) {
+    return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+}
+/** Write `files` under `root`; a value of `{ text, mode }` sets the mode too. */
+export function writeFiles(root, files) {
+    for (const [path, value] of Object.entries(files)) {
+        const full = join(root, path);
+        mkdirSync(dirname(full), { recursive: true });
+        writeFileSync(full, typeof value === "string" ? value : value.text);
+        if (typeof value !== "string")
+            chmodSync(full, value.mode);
+    }
+}
+/** A git repository holding `files`, with nothing committed unless `commit` is set. */
+export function repo(files, commit = false) {
+    const root = scratchDir("chant-contract-repo-");
+    writeFiles(root, files);
+    git(root, "init", "-q");
+    if (commit) {
+        git(root, "add", "-A");
+        git(root, "commit", "-q", "-m", "one");
+    }
+    return root;
+}
+export function commitAll(root, message = "next") {
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", message);
+    return git(root, "rev-parse", "HEAD");
+}
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+/** A validator for `schema`, and an assertion that a document passes it. */
+export function contract(schema) {
+    const validate = ajv.compile(schema);
+    return {
+        validate,
+        expectValid(doc) {
+            const ok = validate(doc);
+            expect(ok, `${JSON.stringify(validate.errors, null, 2)}\n${JSON.stringify(doc, null, 2).slice(0, 2000)}`).toBe(true);
+        },
+    };
+}
+export function validSchema(schema) {
+    return ajv.validateSchema(schema);
+}
+export const declaration = (members, extra = {}) => JSON.stringify({ name: "acme", schema: 1, ...extra, members }, null, 2);
+/**
+ * A chant older than `workspace member-run`: it answers `chant graph` in the
+ * member's directory with one node per line of the member's `ids.txt`.
+ */
+export const FAKE_GRAPH_CHANT = `#!/bin/sh
+case "$1" in
+  graph)
+    printf '{"version":1,"nodes":['
+    sep=""
+    while read -r id; do printf '%s{"id":"%s","kind":"Thing","lexicon":"fake","attrs":{}}' "$sep" "$id"; sep=","; done < ids.txt
+    printf '],"edges":[],"groups":{"byLexicon":{}}}\\n'
+    ;;
+  *) echo "Error: Unknown command: $1" >&2; exit 1 ;;
+esac
+`;
+/**
+ * A chant older than `workspace member-run` that answers from files (#2662):
+ * `chant graph --components` prints the member's `components.json`, or an
+ * empty IR when there is none, and plain `chant graph` prints `ir.json`. A
+ * `components.json` holding `FAIL` makes the component graph exit 1.
+ */
+export const FAKE_FILE_GRAPH_CHANT = `#!/bin/sh
+[ "$1" = graph ] || { echo "Error: Unknown command: $1" >&2; exit 1; }
+case " $* " in
+  *" --components "*)
+    if [ ! -f components.json ]; then printf '{"version":1,"nodes":[],"edges":[],"groups":{}}\\n'
+    elif grep -q FAIL components.json; then echo "Error: component discovery failed" >&2; exit 1
+    else cat components.json; fi ;;
+  *) cat ir.json ;;
+esac
+`;

package/dist/workspace/__fixtures__/decide-workspace.js

@@ -0,0 +1,112 @@
+/**
+ * A throwaway workspace for the decide tests: a git repository with an answer
+ * kind (the reference workspace's), a task kind the points read through the
+ * read contract, three points (a noul, a choice and a score), and a box member
+ * that declares one brokered capability and one without a broker.
+ */
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+/** The chant checkout the tests run in. */
+export const REPO = realpathSync(join(import.meta.dirname, "..", "..", "..", "..", ".."));
+const REF = join(REPO, "reference-workspace");
+export const MODEL = "jev-1.13.0";
+const model = (extra = {}) => ({ kind: "model", backend: "systemone", model: MODEL, threshold: 0.8, ...extra });
+export const POINTS = {
+    points: {
+        triage: {
+            title: "Does this task need a person now",
+            question: { type: "noul", instructions: "Does the task need a person to look at it today?", criteria: { true: "A person looks at it today.", false: "It can wait." } },
+            inputs: { "record.size": "the task's size in points", "record.risky": "whether the task touches production" },
+            deciders: [{ kind: "table", rows: [{ when: { "record.size": 0 }, answer: false }] }, model(), { kind: "quorum", count: 1 }],
+        },
+        route: {
+            title: "Which team takes this task",
+            question: { type: "choice", instructions: "Pick the team that takes the task.", criteria: { platform: "The platform team.", app: "The app team.", docs: "The docs team." } },
+            inputs: { "record.title": "the task's title", "record.size": "the task's size in points" },
+            deciders: [model({ unreachable: "fail" }), { kind: "quorum", count: 1 }],
+        },
+        effort: {
+            title: "How much effort this task takes",
+            question: { type: "score", instructions: "Rate the effort the task takes.", criteria: ["low", "medium", "high"] },
+            inputs: { "record.size": "the task's size in points", "member.kind": "the kind of the member the task is in" },
+            deciders: [model(), { kind: "quorum", count: 1 }],
+        },
+    },
+};
+const TASK_KIND = `export const recordKind = {
+  name: "task",
+  location: { dir: ".", match: "^T-[0-9]+\\\\.md$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:intentius:chant:test-task:1", path: "task.schema.json" },
+  idField: "id",
+  stateField: "state",
+  states: ["open", "done"],
+  closedStates: ["done"],
+};
+`;
+const TASK_SCHEMA = {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    $id: "urn:intentius:chant:test-task:1",
+    type: "object",
+    required: ["id", "title", "state"],
+    properties: {
+        id: { type: "string" },
+        title: { type: "string" },
+        state: { enum: ["open", "done"] },
+        size: { type: "integer" },
+        risky: { type: "boolean" },
+    },
+    additionalProperties: false,
+};
+const task = (id, title, size, risky) => `---\nid: "${id}"\ntitle: "${title}"\nstate: "open"\nsize: ${size}\nrisky: ${risky}\n---\n\n# ${title}\n`;
+const scratch = [];
+export function cleanScratch() {
+    for (const d of scratch.splice(0))
+        rmSync(d, { recursive: true, force: true });
+}
+export function git(cwd, ...args) {
+    return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+/** Make the workspace and commit it. Returns its root. */
+export function workspace(points = POINTS) {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-decide-")));
+    scratch.push(root);
+    const files = {
+        "chant.workspace.json": JSON.stringify({
+            name: "decide-test",
+            schema: 1,
+            members: [
+                { name: "app", dir: "app", kind: "other", because: "a plain Node server" },
+                {
+                    name: "box",
+                    dir: "box",
+                    kind: "other",
+                    because: "the box the steward runs in",
+                    box: { capabilities: [{ name: "inference", broker: "lobby", scope: ["agent"] }, { name: "raw" }] },
+                },
+            ],
+            records: [{ kind: "answers/answer.kind.mjs" }, { kind: "tasks/task.kind.mjs" }],
+        }, null, 2),
+        "app/server.mjs": "export const port = 8080;\n",
+        "box/README.md": "The box.\n",
+        "decisions/points.json": JSON.stringify(points, null, 2),
+        "tasks/task.kind.mjs": TASK_KIND,
+        "tasks/task.schema.json": JSON.stringify(TASK_SCHEMA, null, 2),
+        "tasks/T-1.md": task("T-1", "Rotate the deploy key", 5, true),
+        "tasks/T-2.md": task("T-2", "Fix a typo in the README", 1, false),
+    };
+    for (const [path, text] of Object.entries(files)) {
+        mkdirSync(dirname(join(root, path)), { recursive: true });
+        writeFileSync(join(root, path), text);
+    }
+    cpSync(join(REF, "answers", "answer.kind.mjs"), join(root, "answers", "answer.kind.mjs"));
+    cpSync(join(REF, "answers", "answer.schema.json"), join(root, "answers", "answer.schema.json"));
+    git(root, "init", "-q");
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", "one");
+    return root;
+}
+/** The front matter text of a written record. */
+export const recordText = (root, path) => readFileSync(join(root, path), "utf-8");

package/dist/workspace/__fixtures__/sessions.js

@@ -0,0 +1,91 @@
+/**
+ * A repository with the reference workspace's decisions and design member,
+ * and helpers that write sessions and review entries into it, for the
+ * session and records --since tests (#2673).
+ */
+import { cpSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sessionSeal } from "../record-sessions.js";
+import { commitAll, git, REPO, scratchDir } from "./contract-repo.js";
+export const SESSIONS_KIND = "design/sessions/session.kind.mjs";
+export const DECISIONS_KIND = "decisions/decision.kind.mjs";
+/** A git repository holding a copy of the reference workspace's decisions and design member. */
+export function sessionsRepo() {
+    const root = scratchDir("chant-sessions-");
+    for (const d of ["decisions", "design"])
+        cpSync(join(REPO, "reference-workspace", d), join(root, d), { recursive: true });
+    git(root, "init", "-q");
+    commitAll(root, "reference");
+    return root;
+}
+/** A session file's text, sealed when it is closed. */
+export function sessionText(s) {
+    const lines = [
+        "---",
+        "schema: 1",
+        `id: "${s.id}"`,
+        `title: "Session ${s.id}"`,
+        `state: "${s.state}"`,
+        "agenda:",
+        ...(s.agenda ?? ["ref-001"]).map((r) => `  - record: "${r}"`),
+        "attendance:",
+        '  - principal: "lex00"',
+        '    class: "person"',
+        '  - principal: "alice"',
+        '    class: "person"',
+        '  - principal: "helper"',
+        '    class: "agent"',
+        'opened: "2026-09-24T18:00:00Z"',
+        `closed: ${s.state === "closed" ? '"2026-09-24T19:00:00Z"' : "null"}`,
+        ...(s.verdicts?.length
+            ? ["verdicts:", ...s.verdicts.flatMap((v) => [`  - record: "${v.record}"`, `    principal: "${v.principal}"`, `    verdict: "${v.verdict}"`])]
+            : ["verdicts: []"]),
+        ...(s.state === "closed" ? ['closed_digest: "SEAL"'] : []),
+        "---",
+        "",
+        `# Session ${s.id}`,
+        "",
+    ];
+    const text = lines.join("\n");
+    return s.state === "closed" ? text.replace('"SEAL"', `"${sessionSeal(text, "closed_digest")}"`) : text;
+}
+/** Rewrite ref-001 with the given review entries, each naming `session`. */
+export function reviewed(root, reviewers, session, state = "decided") {
+    const file = join(root, "decisions", "ref-001-how-the-app-is-deployed.md");
+    const reviews = reviewers.map((r) => `  - reviewer: "${r}"\n    verdict: "agree"\n    on: "2026-09-24"\n    session: "${session}"`).join("\n");
+    writeFileSync(file, readFileSync(file, "utf-8")
+        .replace(/^state: .*$/m, `state: "${state}"`)
+        .replace(/^reviews: .*$/m, reviewers.length ? `reviews:\n${reviews}` : "reviews: []"));
+}
+/**
+ * Declare the fixture's two kinds in a chant.workspace.json (#2693): the
+ * decisions at the root and the session kind in the design member, as the
+ * reference workspace declares them, so review --session, close and
+ * --since <session id> find the session kind.
+ */
+export function declareSessions(root) {
+    writeFileSync(join(root, "chant.workspace.json"), `${JSON.stringify({
+        name: "sessions",
+        schema: 1,
+        members: [{ name: "design", dir: "design", kind: "other", because: "the session fixture", records: [{ kind: "sessions/session.kind.mjs" }] }],
+        records: [{ kind: DECISIONS_KIND }],
+        pins: [],
+    }, null, 2)}\n`);
+}
+/** The fields of a new open session, as a UI sends them to records new. */
+export function newSessionFields(over = {}) {
+    return JSON.stringify({
+        schema: 1,
+        title: "Second walk",
+        state: "open",
+        agenda: [{ record: "ref-001" }, { record: "ref-002" }],
+        attendance: [
+            { principal: "lex00", class: "person" },
+            { principal: "alice", class: "person" },
+        ],
+        opened: "2026-09-25T09:00:00Z",
+        closed: null,
+        verdicts: [],
+        ...over,
+    });
+}

package/dist/workspace/__fixtures__/two-member-workspace.js

@@ -0,0 +1,34 @@
+/**
+ * A throwaway git repository holding a workspace with two members (api and
+ * web), optionally a root member, and an example group with one match. Used
+ * by the per-member pipeline tests (#2542).
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+/** A git repository holding a workspace with two members, a root member and an example group. */
+export function twoMemberWorkspace(options = {}) {
+    const repo = realpathSync(mkdtempSync(join(tmpdir(), "chant-member-pipeline-")));
+    execFileSync("git", ["init", "-q"], { cwd: repo });
+    const ws = options.prefix ? join(repo, options.prefix) : repo;
+    const members = [
+        { name: "api", dir: "services/api", kind: "chant" },
+        { name: "web", dir: "apps/web", kind: "chant" },
+        { name: "samples", kind: "examples", glob: "examples/*" },
+    ];
+    if (options.root)
+        members.unshift({ name: "platform", dir: ".", kind: "chant" });
+    const files = {
+        "chant.workspace.json": JSON.stringify({ name: "shop", schema: 1, members }, null, 2),
+        "services/api/chant.config.ts": "export default {};\n",
+        "services/api/src/infra.ts": "\n",
+        "apps/web/chant.config.ts": "export default {};\n",
+        "examples/demo/chant.config.ts": "export default {};\n",
+    };
+    for (const [path, text] of Object.entries(files)) {
+        mkdirSync(dirname(join(ws, path)), { recursive: true });
+        writeFileSync(join(ws, path), text);
+    }
+    return repo;
+}

package/dist/workspace/agent-cli.js

@@ -0,0 +1,99 @@
+/**
+ * `chant workspace agent [<name>] [--json]` (#2524 D20, #2548, ws-067): what
+ * an agent session reloads from, read from the repository alone.
+ *
+ * A session is declared in the declaration's `agents` list and bound to one
+ * member or several (ws-101). This prints the session, its members, its
+ * write scope (the files
+ * and the record kinds, with their verbs, it may write) and the spec: the
+ * `spec` block `chant workspace records --current --json` prints (#2546). An
+ * agent that resumes needs nothing else: no memory of an earlier run, no
+ * state outside the checkout.
+ *
+ * The session and its scope come from the declaration at base, as the
+ * write paths and `check --changes` read them; the spec from the working
+ * tree, which is what the agent works on. Without a name, the session
+ * `CHANT_AGENT` names.
+ */
+import { formatError } from "../cli/format.js";
+import { readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, WRITE_VERBS } from "./declaration.js";
+import { declaredKindFiles, queryDeclaredRecords } from "./records-cli.js";
+import { AGENT_ENV, resolveWriter, scopeOf, scopeSource, WriteScopeError } from "./write-scope.js";
+/** The version of the `agent` document this chant writes. */
+export const AGENT_CONTRACT_VERSION = 1;
+export const AGENT_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/agent/v1/agent.schema.json";
+/** Why the session can't be printed. Closed. */
+export const AGENT_ERROR_CODES = [...WORKSPACE_ERROR_CODES, "agent-unknown"];
+/** The session `name` names, as {@link AgentDocument} prints it. Never throws a read or scope error. */
+export async function agentSession(q) {
+    const head = { $schema: AGENT_OUTPUT_SCHEMA_ID, contract: AGENT_CONTRACT_VERSION, chant: readerVersion() };
+    try {
+        const source = scopeSource(q.cwd);
+        if (source.declaration === null || source.from === null) {
+            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 }, source.classes);
+        const agent = writer.agent;
+        const bound = agent.members.map((name) => decl.members.find((m) => m.name === name));
+        const members = bound.map((m) => ({ name: m.name, dir: m.dir, kind: m.kind }));
+        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]));
+        const records = [...decl.records, ...bound.flatMap((m) => m.records)].map((d) => {
+            const kind = loadedName.get(d.path) ?? null;
+            const names = [kind, d.name].filter((n) => n !== null);
+            const verbs = rules === null ? [...WRITE_VERBS] : WRITE_VERBS.filter((v) => names.some((n) => (rules[n] ?? []).includes(v)));
+            return { path: d.path, kind, name: d.name, member: d.member, verbs };
+        });
+        return {
+            ...head,
+            workspace: { name: decl.name, root: source.root ?? ".", scopeFrom: source.from },
+            agent: { name: agent.name, member: members[0], members, principals: agent.principals },
+            scope: { members: members.map((m) => m.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"],
+        };
+    }
+    catch (err) {
+        if (err instanceof WorkspaceReadError || err instanceof WriteScopeError) {
+            return { ...head, error: { code: err.code, message: err instanceof WorkspaceReadError ? err.describe() : err.message } };
+        }
+        throw err;
+    }
+}
+const USAGE = "chant workspace agent [<name>] [--json]";
+/** `chant workspace agent`: exit 0 when the session was printed, 1 otherwise. */
+export async function runWorkspaceAgent(ctx) {
+    const { args } = ctx;
+    const name = args.extraPositional ?? (process.env[AGENT_ENV] || undefined);
+    if (!name) {
+        console.error(formatError({ message: `name the agent session, or set ${AGENT_ENV}`, hint: USAGE }));
+        return 1;
+    }
+    const doc = await agentSession({ cwd: process.cwd(), name });
+    if (args.json || args.format === "json")
+        console.log(JSON.stringify(doc, null, 2));
+    if ("error" in doc) {
+        if (!args.json && args.format !== "json")
+            console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+        return 1;
+    }
+    if (args.json || args.format === "json")
+        return 0;
+    const out = [];
+    const bound = doc.agent.members.map((m) => `${m.name} (${m.dir})`).join(", ");
+    out.push(`agent     ${doc.agent.name}, bound to ${doc.agent.members.length === 1 ? "member" : "members"} ${bound}, 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("; ")}`);
+    console.log(out.join("\n"));
+    return 0;
+}