@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/box-factory-write.js

@@ -0,0 +1,196 @@
+/**
+ * `chant workspace box factory set <member>` (#3600): change a box's
+ * factory, `members[i].box.factory` in the declaration (#3146, ws-077),
+ * through chant.
+ *
+ * A box planted from a shared template can't carry where it publishes:
+ * `factory.publish.repo` must be a real owner/name, so the template leaves
+ * it out and whoever plants the box, which knows the box's repo, sets it
+ * here. The write is the factory's sibling of `box listing set` (#3308): it
+ * changes only the factory's own top-level properties, in place, so the file
+ * keeps its formatting, key order and comments; it validates the declaration
+ * it would write, judges the declaration by the write scope at base (so a
+ * protected declaration takes it when its `except` names
+ * `/members/*\/box/factory/publish`), refuses a bare `--by` name under
+ * `identity.attribution: "identified"`, holds the working tree's write lock,
+ * prints one JSON document (`box-factory-write.schema.json`) and never
+ * commits.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { factoryView } from "./box-factory.js";
+import { parseDeclaration, readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError } from "./declaration.js";
+import { IDENTITY_CODES, IdentityError, refuseUnidentified } from "./identity.js";
+import { removeProperty, setProperty, valueAt } from "./json-edit.js";
+import { parseJsonText } from "./jsonc.js";
+import { locateWorkspace } from "./which-chant.js";
+import { judgePath, resolveWriter, scopeSource, unknownClassVerdict, WriteScopeError } from "./write-scope.js";
+import { withWriteLockSync, WriteLockError, WRITE_LOCK_CODES } from "./write-lock.js";
+/** The version of the document this write prints. */
+export const BOX_FACTORY_CONTRACT_VERSION = 1;
+/** `$id` of the JSON Schema for what `box factory set` prints, shipped beside this file. */
+export const BOX_FACTORY_WRITE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/box-factory-write/v1/box-factory-write.schema.json";
+/** Why a factory write wrote nothing. Closed. */
+export const BOX_FACTORY_ERROR_CODES = [
+    ...WORKSPACE_ERROR_CODES,
+    "write-usage-invalid",
+    "write-input-invalid",
+    "factory-member-unknown",
+    "factory-box-missing",
+    "write-scope-member",
+    "write-scope-protected",
+    "write-scope-class-unknown",
+    "agent-unknown",
+    ...IDENTITY_CODES,
+    ...WRITE_LOCK_CODES,
+];
+/** The factory properties a write may set. Any `x-` key is passed through as well. */
+export const FACTORY_FIELDS = ["builds", "check", "checks", "builders", "tiers", "publish"];
+class FactoryWriteError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const toPosix = (p) => (sep === "/" ? p : p.split(sep).join("/"));
+const sha256 = (b) => createHash("sha256").update(b).digest("hex");
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** The factory fields given with --from: a JSON object of the factory's fields and x- keys; null for a key takes it out. */
+function readFields(text) {
+    if (text === undefined || text.trim() === "")
+        throw new FactoryWriteError("write-usage-invalid", "box factory set needs the factory fields: --from <file|->, such as {\"publish\": {\"repo\": \"owner/name\"}}");
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (err) {
+        throw new FactoryWriteError("write-input-invalid", `the factory fields are not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!isObject(value))
+        throw new FactoryWriteError("write-input-invalid", "the factory fields are a JSON object, such as {\"publish\": {\"repo\": \"owner/name\"}}");
+    for (const k of Object.keys(value)) {
+        if (k.startsWith("x-") || FACTORY_FIELDS.includes(k))
+            continue;
+        throw new FactoryWriteError("write-input-invalid", `${k} is not a factory field; a factory takes ${FACTORY_FIELDS.join(", ")} and x- keys`);
+    }
+    return value;
+}
+/** Write `text` to `file` through a sibling temporary file, so a reader never sees half of it. */
+function writeAtomically(file, text) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.chant-${process.pid}.tmp`;
+    writeFileSync(tmp, text);
+    renameSync(tmp, file);
+}
+/** Run the write and build the document it prints. Never throws for a refusal. */
+export function boxFactorySet(req) {
+    const head = { $schema: BOX_FACTORY_WRITE_SCHEMA_ID, contract: BOX_FACTORY_CONTRACT_VERSION, chant: readerVersion() };
+    try {
+        return withWriteLockSync(req.cwd, { verb: "box factory set", by: req.by ?? null, agent: req.agent || null }, req.dryRun, () => write(req, head));
+    }
+    catch (err) {
+        const fail = (code, message) => ({ ...head, member: req.member || null, error: { code, message } });
+        if (err instanceof FactoryWriteError)
+            return fail(err.code, err.message);
+        if (err instanceof WriteScopeError)
+            return fail(err.code, err.message);
+        if (err instanceof IdentityError)
+            return fail(err.code, err.message);
+        if (err instanceof WriteLockError)
+            return fail(err.code, err.message);
+        if (err instanceof WorkspaceReadError)
+            return fail(err.code, err.describe());
+        throw err;
+    }
+}
+function write(req, head) {
+    if (!req.member)
+        throw new FactoryWriteError("write-usage-invalid", "box factory set needs the member whose box builds: box factory set <member>");
+    const fields = readFields(req.fields);
+    const located = locateWorkspace(req.cwd);
+    const declaration = readDeclaration(located.tree);
+    const member = declaration.members.find((m) => m.name === req.member);
+    if (!member) {
+        throw new FactoryWriteError("factory-member-unknown", `no member is named ${req.member}; the declaration's members are ${declaration.members.map((m) => m.name).join(", ") || "none"}`);
+    }
+    if (!member.box)
+        throw new FactoryWriteError("factory-box-missing", `member ${member.name} declares no box block, so it has no factory; a factory is what a box builds (#3146)`);
+    const repoBase = located.top ?? located.rootOnDisk;
+    const declPath = toPosix(relative(repoBase, join(located.rootOnDisk, declaration.file)));
+    const declFile = join(located.rootOnDisk, declaration.file);
+    const before = readFileSync(declFile, "utf-8");
+    const jsonc = declaration.file.endsWith(".jsonc");
+    // The declaration, with only the factory's own properties changed.
+    const boxPointer = member.box.pointer;
+    const factoryPointer = `${boxPointer}/factory`;
+    const parsed = parseJsonText(before, { jsonc });
+    if (!parsed.ok)
+        throw new WorkspaceReadError("declaration-unparseable", parsed.message);
+    const raw = valueAt(parsed.value, factoryPointer);
+    let after = before;
+    const expected = structuredClone(parsed.value);
+    const expectedBox = valueAt(expected, boxPointer);
+    if (raw === undefined) {
+        const value = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== null));
+        if (Object.keys(value).length > 0) {
+            after = setProperty(after, jsonc, boxPointer, "factory", value);
+            expectedBox.factory = value;
+        }
+    }
+    else {
+        const expectedFactory = expectedBox.factory;
+        for (const [k, v] of Object.entries(fields)) {
+            if (v === null) {
+                after = removeProperty(after, jsonc, factoryPointer, k);
+                delete expectedFactory[k];
+            }
+            else if (!isDeepStrictEqual(expectedFactory[k], v)) {
+                after = setProperty(after, jsonc, factoryPointer, k, v);
+                expectedFactory[k] = v;
+            }
+        }
+    }
+    const reread = parseJsonText(after, { jsonc });
+    if (!reread.ok || !isDeepStrictEqual(reread.value, expected)) {
+        // An edit that does not read back as the value meant is never written.
+        throw new Error(`box factory set: editing ${declaration.file} in place did not give the declaration intended; nothing was written`);
+    }
+    let next;
+    try {
+        next = parseDeclaration(after, declaration.file);
+    }
+    catch (err) {
+        if (err instanceof WorkspaceReadError)
+            throw new FactoryWriteError("write-input-invalid", `the factory would make the declaration invalid: ${err.describe()}`);
+        throw err;
+    }
+    const nextMember = next.members.find((m) => m.name === member.name);
+    // The write scope at base, and who --by names.
+    const source = scopeSource(req.cwd);
+    if (req.by !== undefined)
+        refuseUnidentified(source, [req.by], "--by", { agent: req.agent });
+    if (after !== before && (source.declaration !== null || (req.agent !== undefined && req.agent !== ""))) {
+        const writer = resolveWriter(source.declaration, source.policy, { agent: req.agent || null, principal: req.by ?? null }, source.classes);
+        const unknown = unknownClassVerdict(source.declaration, writer, source.classes);
+        if (!unknown.ok)
+            throw new WriteScopeError(unknown.code, unknown.message);
+        const verdict = judgePath(source.declaration, writer, declaration.file, { before: () => before, after: () => after });
+        if (!verdict.ok)
+            throw new FactoryWriteError(verdict.code, verdict.message);
+    }
+    const changed = after !== before;
+    if (changed && !req.dryRun)
+        writeAtomically(declFile, after);
+    return {
+        ...head,
+        member: member.name,
+        declaration: { path: declPath, sha256: sha256(after) },
+        paths: changed ? [declPath] : [],
+        changed,
+        dryRun: req.dryRun === true,
+        previous: factoryView(member.box.factory, declaration.members),
+        factory: factoryView(nextMember.box.factory, next.members),
+    };
+}

package/dist/workspace/box-factory-write.schema.json

@@ -0,0 +1,342 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/box-factory-write/v1/box-factory-write.schema.json",
+  "title": "chant workspace box factory set output",
+  "description": "What `chant workspace box factory set <member> --from <file|->` prints (#3600): the box's factory before and after, as `status --json` prints it, and the file the write changed, or the reason it wrote nothing. The write changes only the factory's own top-level properties, members[i].box.factory in the declaration, in place, keeping the file's formatting and comments. It never commits. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.110.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The factory was written, or would be with --dry-run, or already held what was given (changed false). Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "member",
+        "declaration",
+        "paths",
+        "changed",
+        "dryRun",
+        "previous",
+        "factory"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/box-factory-write/v1/box-factory-write.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string",
+          "description": "The chant that wrote it."
+        },
+        "member": {
+          "type": "string",
+          "description": "The member whose box block holds the factory."
+        },
+        "declaration": {
+          "type": "object",
+          "required": [
+            "path",
+            "sha256"
+          ],
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "The declaration file, relative to the repository root (the working directory outside git), with / separators."
+            },
+            "sha256": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "The sha256 of the declaration's bytes after the write, or as they would be with --dry-run."
+            }
+          }
+        },
+        "paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The declaration, relative to the repository root, when the write changed it or would with --dry-run; empty when the factory already held what was given."
+        },
+        "changed": {
+          "type": "boolean",
+          "description": "Whether the declaration changed: paths is not empty."
+        },
+        "dryRun": {
+          "type": "boolean",
+          "description": "True when --dry-run was given: nothing was written, and the document says what would have been."
+        },
+        "previous": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/factory"
+            }
+          ],
+          "description": "The factory before the write, as status --json prints it, or null when the box declared none."
+        },
+        "factory": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/factory"
+            }
+          ],
+          "description": "The factory after the write, as status --json prints it, or null when the box still declares none."
+        }
+      }
+    },
+    "factory": {
+      "type": "object",
+      "required": [
+        "builds",
+        "check",
+        "checks",
+        "builders",
+        "tiers",
+        "builderFor",
+        "publish"
+      ],
+      "properties": {
+        "builds": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "The members the factory builds, in declaration order. A work item a person asks for constrains member:<the first>."
+        },
+        "check": {
+          "description": "The verdict command, run from the workspace root, and what it is; null when none is declared.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "run",
+                "kind"
+              ],
+              "properties": {
+                "run": {
+                  "type": "string"
+                },
+                "kind": {
+                  "enum": [
+                    "test",
+                    "build",
+                    "lint",
+                    "plan",
+                    "conformance"
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        "checks": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Where a work item's builder writes its check, from the workspace root, or null for the orchestrator's choice."
+        },
+        "builders": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The member that declares the builder agents, or null."
+        },
+        "tiers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "tier",
+              "agent",
+              "kinds",
+              "session"
+            ],
+            "properties": {
+              "tier": {
+                "type": "string"
+              },
+              "agent": {
+                "type": "string"
+              },
+              "kinds": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ]
+              },
+              "session": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            }
+          },
+          "description": "Which builder agent builds at which tier, as declared (#3152, ws-094), each { tier, agent, kinds, session } with kinds and session null when not declared; empty when none is. Added in contract 1 by chant 0.103.0."
+        },
+        "builderFor": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "required": [
+                "agent",
+                "session"
+              ],
+              "properties": {
+                "agent": {
+                  "type": "string"
+                },
+                "session": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              }
+            }
+          },
+          "description": "The builder for each member the factory builds, by tier (#3152): member name, then tier, then { agent, session }. For a member the entry naming its kind is used, else the tier's entry with no kinds; a tier with neither is left out. Added in contract 1 by chant 0.103.0."
+        },
+        "publish": {
+          "description": "Where a finished build is published, or null when the factory doesn't publish past the box.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "forge",
+                "repo",
+                "base",
+                "branchPrefix",
+                "head"
+              ],
+              "properties": {
+                "forge": {
+                  "const": "github"
+                },
+                "repo": {
+                  "type": "string",
+                  "description": "owner/name: where the pull request is opened."
+                },
+                "base": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The branch the pull request targets, or null for the repository's default branch."
+                },
+                "branchPrefix": {
+                  "type": "string",
+                  "description": "What the published branch's name starts with, before the work item's id. chant/work/ unless declared."
+                },
+                "head": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "owner/name of the fork the branch is pushed to, or null to push to repo."
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was written. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "member",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/box-factory-write/v1/box-factory-write.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "revision-unknown",
+                "write-usage-invalid",
+                "write-input-invalid",
+                "factory-member-unknown",
+                "factory-box-missing",
+                "write-scope-member",
+                "write-scope-protected",
+                "write-scope-class-unknown",
+                "agent-unknown",
+                "principal-unidentified",
+                "write-lock-timeout",
+                "write-lock-not-held"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/workspace/box-factory.js

@@ -0,0 +1,88 @@
+/**
+ * The factory and listing on a box block, and whether a workspace is
+ * plantable (#3146, ws-077), as `chant workspace status --json` and
+ * `chant workspace graph --json` print them.
+ *
+ * Every field here is opt-in (#3174): a workspace with no box, or a box with
+ * no `factory` or `listing`, reads as `null` for each, and plantability is a
+ * fact about the declaration, never a check that fails. A records-only
+ * workspace and an infra workspace with a factory and no box services both
+ * read and check cleanly; they just aren't plantable.
+ */
+import { createHash } from "node:crypto";
+/** Why a workspace isn't plantable. Closed. */
+export const PLANTABLE_REASON_CODES = ["box-none", "box-several"];
+/** Whether the declaration is plantable (#3146): exactly one member's box block declares services. */
+export function plantability(declaration) {
+    const boxes = declaration.members.filter((m) => (m.box?.services.length ?? 0) > 0);
+    if (boxes.length === 1)
+        return { plantable: true, box: boxes[0].name, reason: null };
+    if (boxes.length === 0) {
+        return { plantable: false, box: null, reason: { code: "box-none", message: "no member's box block declares services, so there is no box to plant" } };
+    }
+    return {
+        plantable: false,
+        box: null,
+        reason: { code: "box-several", message: `members ${boxes.map((m) => m.name).join(", ")} each declare box services, and a planted workspace runs one box` },
+    };
+}
+/** A box's factory as the read contract prints it. `members` gives each built member's kind, for `builderFor`. */
+export function factoryView(f, members = []) {
+    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, members) {
+    const tiers = [...new Set(f.tiers.map((t) => t.tier))];
+    const out = {};
+    for (const name of f.builds) {
+        const kind = members.find((m) => m.name === name)?.kind;
+        const row = {};
+        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, read) {
+    if (l === null)
+        return null;
+    let cover = null;
+    if (l.cover !== null) {
+        const bytes = read(l.cover);
+        cover = { path: l.cover, sha256: bytes === null ? null : createHash("sha256").update(bytes).digest("hex") };
+    }
+    return { published: l.published, title: l.title, line: l.line, cover };
+}
+/** A reader of a file's bytes in `tree` for {@link listingView}: null when the file can't be read. */
+export function treeBytes(tree) {
+    return (path) => {
+        try {
+            if (tree.stat(path) !== "file")
+                return null;
+            return tree.bytes ? tree.bytes(path) : new TextEncoder().encode(tree.read(path));
+        }
+        catch {
+            return null;
+        }
+    };
+}
+/** 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, tree, members = []) {
+    if (box === null || (box.factory === null && box.listing === null))
+        return null;
+    return { factory: factoryView(box.factory, members), listing: listingView(box.listing, treeBytes(tree)) };
+}