@intentius/chant 0.124.12 → 0.124.14

package/dist/workspace/box-listing.js

@@ -0,0 +1,298 @@
+/**
+ * `chant workspace box listing set <member>` (#3308): change a box's listing,
+ * `members[i].box.listing` in the declaration (#3146, ws-077), through chant.
+ *
+ * ws-074 makes the repo the database and lets a tool write only through
+ * chant's write contract. The listing is configuration on the box block, so
+ * before this a tool such as hud would have had to edit `chant.workspace.json`
+ * itself. This write changes only the listing's own properties, in place, so
+ * the file keeps its formatting, key order and, in a `.jsonc` file, its
+ * comments. It can copy a cover image into the repository and point the
+ * listing at it. It validates the declaration it would write, judges every
+ * path it writes by the write scope at base (`judgePath`, the rule `check
+ * --changes` applies to the commit later), refuses a bare `--by` name under
+ * `identity.attribution: "identified"` (ws-080), prints one JSON document
+ * (`box-listing-write.schema.json`) and never commits: the caller commits, as
+ * after the records writes. Like them it holds the working tree's write lock
+ * (#3173, ws-089) from reading the declaration to writing it.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { listingView, treeBytes } 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 { workingTree } from "./tree.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_LISTING_CONTRACT_VERSION = 1;
+/** `$id` of the JSON Schema for what `box listing set` prints, shipped beside this file. */
+export const BOX_LISTING_WRITE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/box-listing-write/v1/box-listing-write.schema.json";
+/** Why a listing write wrote nothing. Closed. */
+export const BOX_LISTING_ERROR_CODES = [
+    ...WORKSPACE_ERROR_CODES,
+    "write-usage-invalid",
+    "write-input-invalid",
+    "listing-member-unknown",
+    "listing-box-missing",
+    "listing-cover-invalid",
+    "write-scope-member",
+    "write-scope-protected",
+    "write-scope-class-unknown",
+    "agent-unknown",
+    ...IDENTITY_CODES,
+    ...WRITE_LOCK_CODES,
+];
+/** The listing properties a write may set. Any `x-` key is passed through as well. */
+export const LISTING_FIELDS = ["published", "title", "line", "cover"];
+/** The largest cover image the write copies, in bytes. */
+export const COVER_MAX_BYTES = 5 * 1024 * 1024;
+/** The picture formats a cover may be, by the extension its file takes. */
+const COVER_TYPES = [
+    { type: "image/png", ext: "png", exts: ["png"], magic: (b) => b.length >= 8 && [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a].every((x, i) => b[i] === x) },
+    { type: "image/jpeg", ext: "jpg", exts: ["jpg", "jpeg"], magic: (b) => b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
+    {
+        type: "image/webp",
+        ext: "webp",
+        exts: ["webp"],
+        magic: (b) => b.length >= 12 && String.fromCharCode(...b.slice(0, 4)) === "RIFF" && String.fromCharCode(...b.slice(8, 12)) === "WEBP",
+    },
+];
+class ListingWriteError 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);
+/** A path from the workspace root that stays inside it, with / separators, or a reason it isn't one. */
+function workspacePath(raw, what) {
+    const p = toPosix(raw).replace(/^\.\//, "");
+    const norm = posix.normalize(p);
+    if (p === "" || isAbsolute(raw) || norm.startsWith("../") || norm === ".." || norm !== p || p.endsWith("/")) {
+        throw new ListingWriteError("listing-cover-invalid", `${what} ${JSON.stringify(raw)} is not a file path from the workspace root: give it relative, normalised and inside the workspace`);
+    }
+    if (p.split("/")[0] === ".git")
+        throw new ListingWriteError("listing-cover-invalid", `${what} ${JSON.stringify(raw)} is inside .git`);
+    return p;
+}
+function sniff(bytes, what) {
+    const t = COVER_TYPES.find((c) => c.magic(bytes));
+    if (!t)
+        throw new ListingWriteError("listing-cover-invalid", `${what} is not a PNG, JPEG or WebP picture`);
+    return t;
+}
+/** The listing fields given with --from: a JSON object of published, title, line, cover and x- keys; null for a key takes it out. */
+function readFields(text) {
+    if (text === undefined || text.trim() === "")
+        return {};
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (err) {
+        throw new ListingWriteError("write-input-invalid", `the listing fields are not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!isObject(value))
+        throw new ListingWriteError("write-input-invalid", "the listing fields are a JSON object, such as {\"title\": \"...\", \"line\": \"...\"}");
+    for (const [k, v] of Object.entries(value)) {
+        if (k.startsWith("x-"))
+            continue;
+        if (!LISTING_FIELDS.includes(k))
+            throw new ListingWriteError("write-input-invalid", `${k} is not a listing field; a listing takes ${LISTING_FIELDS.join(", ")} and x- keys`);
+        if (v === null)
+            continue;
+        if (k === "published" && typeof v !== "boolean")
+            throw new ListingWriteError("write-input-invalid", "published is true or false, or null to take it out");
+        if (k !== "published" && typeof v !== "string")
+            throw new ListingWriteError("write-input-invalid", `${k} is a string, or null to take it out`);
+    }
+    return value;
+}
+/** Write `bytes` to `file` through a sibling temporary file, so a reader never sees half of it. */
+function writeAtomically(file, bytes) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.chant-${process.pid}.tmp`;
+    writeFileSync(tmp, bytes);
+    renameSync(tmp, file);
+}
+/** Run the write and build the document it prints. Never throws for a refusal. */
+export function boxListingSet(req) {
+    const head = { $schema: BOX_LISTING_WRITE_SCHEMA_ID, contract: BOX_LISTING_CONTRACT_VERSION, chant: readerVersion() };
+    try {
+        return withWriteLockSync(req.cwd, { verb: "box listing 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 ListingWriteError)
+            return fail(err.code, err.message);
+        // A path write is never judged write-scope-kind, which is for record kinds.
+        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 ListingWriteError("write-usage-invalid", "box listing set needs the member whose box it lists: box listing set <member>");
+    if (req.coverPath !== undefined && req.cover === undefined)
+        throw new ListingWriteError("write-usage-invalid", "--cover-path says where --cover's image goes, and no --cover was given");
+    const fields = readFields(req.fields);
+    if (req.cover !== undefined && "cover" in fields)
+        throw new ListingWriteError("write-usage-invalid", "give the cover once: --cover copies an image in, and a cover field names a file already in the workspace");
+    if (req.cover === undefined && req.fields === undefined)
+        throw new ListingWriteError("write-usage-invalid", "box listing set needs --from <file|-> with the listing fields, --cover <image>, or both");
+    const located = locateWorkspace(req.cwd);
+    const declaration = readDeclaration(located.tree);
+    const member = declaration.members.find((m) => m.name === req.member);
+    if (!member) {
+        throw new ListingWriteError("listing-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 ListingWriteError("listing-box-missing", `member ${member.name} declares no box block, so it has no listing; a listing is what a box shows of itself (#3146)`);
+    const repoBase = located.top ?? located.rootOnDisk;
+    const fromRepo = (pathInWorkspace) => toPosix(relative(repoBase, join(located.rootOnDisk, ...pathInWorkspace.split("/"))));
+    const declFile = join(located.rootOnDisk, declaration.file);
+    const before = readFileSync(declFile, "utf-8");
+    const jsonc = declaration.file.endsWith(".jsonc");
+    // The cover: an image copied in, or a file already in the workspace.
+    let copy = null;
+    if (req.cover !== undefined) {
+        const src = resolve(req.cwd, req.cover);
+        let bytes;
+        try {
+            if (statSync(src).size > COVER_MAX_BYTES)
+                throw new ListingWriteError("listing-cover-invalid", `--cover ${req.cover} is larger than ${COVER_MAX_BYTES} bytes; a cover is a picture for a listing, so make it smaller`);
+            bytes = readFileSync(src);
+        }
+        catch (err) {
+            if (err instanceof ListingWriteError)
+                throw err;
+            throw new ListingWriteError("listing-cover-invalid", `--cover ${req.cover} can't be read: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const type = sniff(bytes, `--cover ${req.cover}`);
+        const current = member.box.listing?.cover ?? null;
+        const dir = member.dir === "." ? "" : `${member.dir}/`;
+        const path = req.coverPath !== undefined
+            ? workspacePath(req.coverPath, "--cover-path")
+            : current !== null && type.exts.includes(posix.extname(current).slice(1).toLowerCase())
+                ? current
+                : `${dir}listing/cover.${type.ext}`;
+        const ext = posix.extname(path).slice(1).toLowerCase();
+        if (!type.exts.includes(ext))
+            throw new ListingWriteError("listing-cover-invalid", `--cover ${req.cover} is ${type.type}, and ${path} has the extension .${ext}; name it .${type.ext}`);
+        if (path === declaration.file)
+            throw new ListingWriteError("listing-cover-invalid", `--cover-path names the declaration itself`);
+        copy = { path, bytes, type, replaced: current !== null && current !== path ? current : null };
+        fields.cover = path;
+    }
+    else if (typeof fields.cover === "string") {
+        const path = workspacePath(fields.cover, "cover");
+        const bytes = treeBytes(workingTree(located.rootOnDisk))(path);
+        if (bytes === null)
+            throw new ListingWriteError("listing-cover-invalid", `cover ${path} is not a file in the workspace; copy an image in with --cover <image> instead`);
+        sniff(bytes, `cover ${path}`);
+        fields.cover = path;
+    }
+    // The declaration, with only the listing's own properties changed.
+    const boxPointer = member.box.pointer;
+    const listingPointer = `${boxPointer}/listing`;
+    const parsedBefore = parseJsonText(before, { jsonc });
+    if (!parsedBefore.ok)
+        throw new WorkspaceReadError("declaration-unparseable", parsedBefore.message);
+    const rawListing = valueAt(parsedBefore.value, listingPointer);
+    let after = before;
+    const expected = structuredClone(parsedBefore.value);
+    const expectedBox = valueAt(expected, boxPointer);
+    if (rawListing === undefined) {
+        const value = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== null));
+        after = setProperty(after, jsonc, boxPointer, "listing", value);
+        expectedBox.listing = value;
+    }
+    else {
+        const expectedListing = expectedBox.listing;
+        for (const [k, v] of Object.entries(fields)) {
+            if (v === null) {
+                after = removeProperty(after, jsonc, listingPointer, k);
+                delete expectedListing[k];
+            }
+            else {
+                after = setProperty(after, jsonc, listingPointer, k, v);
+                expectedListing[k] = v;
+            }
+        }
+    }
+    const parsedAfter = parseJsonText(after, { jsonc });
+    if (!parsedAfter.ok || JSON.stringify(parsedAfter.value) !== JSON.stringify(expected)) {
+        // An edit that does not read back as the value meant is never written.
+        throw new Error(`box listing 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 ListingWriteError("write-input-invalid", `the listing would make the declaration invalid: ${err.describe()}`);
+        throw err;
+    }
+    const nextMember = next.members.find((m) => m.name === member.name);
+    // The write scope at base, for each file written, and who --by names.
+    const source = scopeSource(req.cwd);
+    if (req.by !== undefined)
+        refuseUnidentified(source, [req.by], "--by", { agent: req.agent });
+    if (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 judge = (path, change) => {
+            const verdict = judgePath(source.declaration, writer, path, change);
+            if (!verdict.ok)
+                throw new ListingWriteError(verdict.code, verdict.message);
+        };
+        if (after !== before)
+            judge(declaration.file, { before: () => before, after: () => after });
+        if (copy)
+            judge(copy.path);
+    }
+    // Write: the cover first, so the declaration never names a cover that isn't there.
+    const paths = [];
+    const coverFile = copy ? join(located.rootOnDisk, ...copy.path.split("/")) : null;
+    const coverChanged = copy !== null && !(existsSync(coverFile) && sha256(readFileSync(coverFile)) === sha256(copy.bytes));
+    if (copy && coverChanged) {
+        if (!req.dryRun)
+            writeAtomically(coverFile, copy.bytes);
+        paths.push(fromRepo(copy.path));
+    }
+    if (after !== before) {
+        if (!req.dryRun)
+            writeAtomically(declFile, after);
+        paths.push(fromRepo(declaration.file));
+    }
+    const read = treeBytes(workingTree(located.rootOnDisk));
+    const readAfter = (p) => (copy && p === copy.path ? copy.bytes : read(p));
+    return {
+        ...head,
+        member: member.name,
+        declaration: { path: fromRepo(declaration.file), sha256: sha256(after) },
+        paths,
+        changed: paths.length > 0,
+        dryRun: req.dryRun === true,
+        previous: listingView(member.box.listing, read),
+        listing: listingView(nextMember.box.listing, readAfter),
+        cover: copy ? { path: copy.path, sha256: sha256(copy.bytes), bytes: copy.bytes.length, type: copy.type.type, replaced: copy.replaced } : null,
+    };
+}

package/dist/workspace/box-publish.js

@@ -0,0 +1,352 @@
+/**
+ * `chant workspace box publish <member> <item> | --records` (#3165, ws-088):
+ * the one call a surface such as hud makes to publish a box's work.
+ *
+ * Publishing is the orchestrator's: studio's kit merges a built work item's
+ * branch into the box's checkout, pushes it to the box's `factory.publish`
+ * repo through its broker, opens the pull request, and sends the records a
+ * person kept uncommitted. The box block names the command that does it,
+ * `box.publisher`, so nothing is injected into a surface's environment.
+ *
+ * chant does none of that work. It reads the publisher from the declaration,
+ * applies the identity rule to `--by` (ws-080), runs the publisher from the
+ * workspace root with no shell and a JSON request on stdin, reads the last
+ * JSON object it prints, and checks the commit it names for the apply record
+ * of ws-075: `Chant-Applied-By` naming `--by`, `Chant-Applied-At`,
+ * `Chant-Applied-Commit` and a `Chant-Record` for the item, or a
+ * `Chant-Record` for each record sent. It prints one document,
+ * `box-publish.schema.json`, and never commits, pushes or calls a forge.
+ *
+ * The publisher's protocol, which `box-publish.schema.json` also states:
+ *
+ * - stdin: one JSON object, `$defs.request`.
+ * - exit 0 and a JSON object on the last line of stdout that holds one:
+ *   `$defs.answer`, with `ok: true`.
+ * - exit 2: a refusal, nothing was published, stderr says why.
+ * - any other exit: a failure, stderr says why and what was done.
+ */
+import { spawnSync } from "node:child_process";
+import { factoryView } from "./box-factory.js";
+import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError } from "./declaration.js";
+import { IDENTITY_CODES, IdentityError, refuseUnidentified } from "./identity.js";
+import { commitDetails, tryGit } from "./intent.js";
+import { readChantTrailers } from "./trailers.js";
+import { locateWorkspace } from "./which-chant.js";
+import { scopeSource } from "./write-scope.js";
+/** The version of the document this command prints, and of the request it gives a publisher. */
+export const BOX_PUBLISH_CONTRACT_VERSION = 1;
+/** `$id` of the JSON Schema for what `box publish` prints, shipped beside this file. */
+export const BOX_PUBLISH_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/box-publish/v1/box-publish.schema.json";
+/** How long a publisher may run before chant stops it: a push and a pull request through a broker, with room to spare. */
+export const PUBLISH_TIMEOUT_MS = 600000;
+/** Why a publish printed no result. Closed. */
+export const BOX_PUBLISH_ERROR_CODES = [
+    ...WORKSPACE_ERROR_CODES,
+    "write-usage-invalid",
+    "publish-member-unknown",
+    "publish-none",
+    "publish-refused",
+    "publish-failed",
+    "publish-answer-invalid",
+    "publish-unrecorded",
+    ...IDENTITY_CODES,
+];
+class PublishError extends Error {
+    constructor(code, message, answer) {
+        super(message);
+        this.code = code;
+        this.answer = answer;
+    }
+}
+const RECORD_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const COMMIT_ID = /^[0-9a-f]{40,64}$/;
+const REPO = /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}$/;
+const MAX_MESSAGE = 2000;
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/**
+ * Split a command into words as a POSIX shell splits plain words: blanks
+ * separate words, single quotes keep everything, double quotes keep
+ * everything but `\\`, `\"`, `\$` and `` \` ``, and a backslash outside quotes
+ * escapes the next character. Nothing else a shell does (variables, `~`,
+ * globs, pipes, redirection) happens: those characters are part of a word.
+ */
+export function splitCommand(text) {
+    const words = [];
+    let word = "";
+    let inWord = false;
+    let quote = null;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (quote === "'") {
+            if (c === "'")
+                quote = null;
+            else
+                word += c;
+            continue;
+        }
+        if (quote === '"') {
+            if (c === '"')
+                quote = null;
+            else if (c === "\\" && i + 1 < text.length && '\\"$`'.includes(text[i + 1]))
+                word += text[++i];
+            else
+                word += c;
+            continue;
+        }
+        if (c === " " || c === "\t" || c === "\n") {
+            if (inWord)
+                words.push(word);
+            word = "";
+            inWord = false;
+            continue;
+        }
+        inWord = true;
+        if (c === "'" || c === '"')
+            quote = c;
+        else if (c === "\\") {
+            if (i + 1 < text.length)
+                word += text[++i];
+        }
+        else
+            word += c;
+    }
+    if (quote !== null)
+        throw new Error(`it has an unclosed ${quote} quote`);
+    if (inWord)
+        words.push(word);
+    if (words.length === 0)
+        throw new Error("it is empty");
+    return words;
+}
+/** The last line of `stdout` that is a JSON object, or null. */
+function lastJsonObject(stdout) {
+    const lines = stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const value = JSON.parse(lines[i]);
+            if (isObject(value))
+                return value;
+        }
+        catch {
+            // Not this line.
+        }
+    }
+    return null;
+}
+const clip = (text) => {
+    const t = text.trim();
+    return t.length > MAX_MESSAGE ? `...${t.slice(-MAX_MESSAGE)}` : t;
+};
+const line = (v) => typeof v === "string" && v.trim() !== "" && !/[\u0000-\u001f\u007f]/.test(v);
+/** The publisher's answer, checked field by field, or a reason it is not one. */
+export function readAnswer(answer) {
+    if (answer.ok !== true)
+        return "it has no ok: true";
+    const out = { commit: null, records: [], pullRequest: null, pushed: null, local: null };
+    if (answer.commit !== undefined && answer.commit !== null) {
+        if (typeof answer.commit !== "string" || !COMMIT_ID.test(answer.commit))
+            return `its commit ${JSON.stringify(answer.commit)} is not a full commit id`;
+        out.commit = answer.commit;
+    }
+    if (answer.records !== undefined) {
+        if (!Array.isArray(answer.records))
+            return "its records is not a list";
+        for (const [i, r] of answer.records.entries()) {
+            if (!isObject(r) || !line(r.kind) || !line(r.id) || !line(r.path))
+                return `records[${i}] is not { kind, id, path, title }`;
+            if (r.title !== undefined && r.title !== null && typeof r.title !== "string")
+                return `records[${i}].title is not a string`;
+            out.records.push({ kind: r.kind, id: r.id, path: r.path, title: typeof r.title === "string" ? r.title : null });
+        }
+    }
+    if (answer.pullRequest !== undefined && answer.pullRequest !== null) {
+        const pr = answer.pullRequest;
+        let https = false;
+        try {
+            https = isObject(pr) && typeof pr.url === "string" && new URL(pr.url).protocol === "https:";
+        }
+        catch {
+            https = false;
+        }
+        if (!isObject(pr) || !https || typeof pr.number !== "number" || !Number.isSafeInteger(pr.number) || pr.number <= 0 || !line(pr.branch) || !line(pr.base)) {
+            return "its pullRequest is not { url (https), number, branch, base, head }";
+        }
+        if (pr.head !== undefined && pr.head !== null && !(typeof pr.head === "string" && REPO.test(pr.head)))
+            return "its pullRequest.head is not owner/name";
+        out.pullRequest = { url: pr.url, number: pr.number, branch: pr.branch, base: pr.base, head: typeof pr.head === "string" ? pr.head : null };
+    }
+    if (answer.pushed !== undefined && answer.pushed !== null) {
+        const p = answer.pushed;
+        if (!isObject(p) || !line(p.branch) || !line(p.repo))
+            return "its pushed is not { branch, repo }";
+        out.pushed = { branch: p.branch, repo: p.repo };
+    }
+    if (answer.local !== undefined && answer.local !== null) {
+        if (typeof answer.local !== "string")
+            return "its local is not a string";
+        out.local = answer.local;
+    }
+    return out;
+}
+/** Run the publish and build the document it prints. Never throws for a refusal. */
+export function boxPublish(req) {
+    const head = { $schema: BOX_PUBLISH_SCHEMA_ID, contract: BOX_PUBLISH_CONTRACT_VERSION, chant: readerVersion() };
+    const action = req.records ? "records" : "item";
+    try {
+        return publish(req, action, head);
+    }
+    catch (err) {
+        const fail = (code, message, answer) => ({
+            ...head,
+            member: req.member || null,
+            action,
+            item: req.item ?? null,
+            error: { code, message },
+            ...(answer ? { answer } : {}),
+        });
+        if (err instanceof PublishError)
+            return fail(err.code, err.message, err.answer);
+        if (err instanceof IdentityError)
+            return fail(err.code, err.message);
+        if (err instanceof WorkspaceReadError)
+            return fail(err.code, err.describe());
+        throw err;
+    }
+}
+function publish(req, action, head) {
+    if (!req.member)
+        throw new PublishError("write-usage-invalid", "box publish needs the member whose box publishes: box publish <member> <item>, or box publish <member> --records");
+    if (action === "item") {
+        if (req.item === undefined)
+            throw new PublishError("write-usage-invalid", "box publish needs the work item to publish, or --records for the records kept uncommitted");
+        if (!RECORD_ID.test(req.item))
+            throw new PublishError("write-usage-invalid", `${JSON.stringify(req.item)} is not a work item id`);
+    }
+    else if (req.item !== undefined) {
+        throw new PublishError("write-usage-invalid", `--records publishes the records kept uncommitted and takes no work item, and was given ${req.item}`);
+    }
+    if (req.head !== undefined && !REPO.test(req.head))
+        throw new PublishError("write-usage-invalid", `--head names the fork to push to as owner/name, not ${JSON.stringify(req.head)}`);
+    const by = req.by?.trim() || null;
+    if (by === null && !req.dryRun)
+        throw new PublishError("write-usage-invalid", "box publish needs --by: who publishes, which the apply record names");
+    const located = locateWorkspace(req.cwd);
+    if (!located.top)
+        throw new WorkspaceReadError("not-a-git-repository", "box publish reads the commit a publisher made, and this directory is not in a git repository");
+    const declaration = readDeclaration(located.tree);
+    const member = declaration.members.find((m) => m.name === req.member);
+    if (!member) {
+        throw new PublishError("publish-member-unknown", `no member is named ${req.member}; the declaration's members are ${declaration.members.map((m) => m.name).join(", ") || "none"}`);
+    }
+    const publisher = member.box?.publisher ?? null;
+    if (publisher === null) {
+        throw new PublishError("publish-none", member.box
+            ? `member ${member.name}'s box block names no publisher, so nothing publishes its work; an orchestrator such as studio names one (box.publisher, ws-088)`
+            : `member ${member.name} declares no box block, so it has no publisher (box.publisher, ws-088)`);
+    }
+    let argv;
+    try {
+        argv = splitCommand(publisher);
+    }
+    catch (err) {
+        throw new PublishError("publish-failed", `member ${member.name}'s publisher ${JSON.stringify(publisher)} can't be run: ${err.message}`);
+    }
+    if (by !== null)
+        refuseUnidentified(scopeSource(req.cwd), [by], "--by", { agent: req.agent });
+    const factory = declaration.members.find((m) => m.box?.factory)?.box?.factory ?? null;
+    const request = {
+        contract: BOX_PUBLISH_CONTRACT_VERSION,
+        action,
+        member: member.name,
+        item: req.item ?? null,
+        by,
+        head: req.head ?? null,
+        dryRun: req.dryRun === true,
+        workspace: { root: located.rootOnDisk },
+        factory: factoryView(factory),
+    };
+    const timeoutMs = req.timeoutMs ?? PUBLISH_TIMEOUT_MS;
+    const run = spawnSync(argv[0], argv.slice(1), {
+        cwd: located.rootOnDisk,
+        input: `${JSON.stringify(request)}\n`,
+        env: { ...(req.env ?? process.env), CHANT_PUBLISH_CONTRACT: String(BOX_PUBLISH_CONTRACT_VERSION) },
+        encoding: "utf-8",
+        timeout: timeoutMs,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    const stdout = run.stdout ?? "";
+    const stderr = run.stderr ?? "";
+    const printed = lastJsonObject(stdout);
+    if (run.error) {
+        const e = run.error;
+        if (e.code === "ETIMEDOUT")
+            throw new PublishError("publish-failed", `the publisher gave no answer within ${timeoutMs}ms and was stopped; what it had done by then stays done`, printed ?? undefined);
+        throw new PublishError("publish-failed", e.code === "ENOENT" ? `the publisher ${argv[0]} was not found` : `the publisher could not be run: ${e.message}`);
+    }
+    if (run.status !== 0) {
+        const said = clip(stderr) || `it exited ${run.status ?? `on ${run.signal}`} and said nothing on stderr`;
+        if (run.status === 2)
+            throw new PublishError("publish-refused", said, printed ?? undefined);
+        throw new PublishError("publish-failed", said, printed ?? undefined);
+    }
+    if (printed === null)
+        throw new PublishError("publish-answer-invalid", "the publisher exited 0 and printed no JSON object on stdout");
+    const answer = readAnswer(printed);
+    if (typeof answer === "string")
+        throw new PublishError("publish-answer-invalid", `the publisher's answer is not one box-publish.schema.json allows: ${answer}`, printed);
+    let applied = null;
+    if (!req.dryRun) {
+        if (answer.commit === null)
+            throw new PublishError("publish-unrecorded", `the publisher answered with no commit, so the ${action === "item" ? "apply" : "records"} commit can't be checked for its trailers`, printed);
+        if (action === "records" && answer.records.length === 0)
+            throw new PublishError("publish-answer-invalid", "the publisher sent records and named none", printed);
+        applied = checkRecord(located.top, answer, action, req.item ?? null, by, printed);
+    }
+    return {
+        ...head,
+        member: member.name,
+        action,
+        item: req.item ?? null,
+        by,
+        dryRun: req.dryRun === true,
+        publisher,
+        ...answer,
+        applied,
+        answer: printed,
+    };
+}
+/**
+ * The apply record on the commit the publisher named (ws-075): for an item,
+ * Chant-Applied-By naming `by`, Chant-Applied-At, Chant-Applied-Commit and a
+ * Chant-Record for the item; for records, a Chant-Record for each one sent.
+ */
+function checkRecord(top, answer, action, item, by, printed) {
+    const sha = answer.commit;
+    if (tryGit(top, ["cat-file", "-e", `${sha}^{commit}`]) === undefined) {
+        throw new PublishError("publish-unrecorded", `the publisher named commit ${sha}, which this repository does not have`, printed);
+    }
+    const commit = commitDetails(top, [sha]).get(sha);
+    const trailers = readChantTrailers(commit?.trailers ?? {});
+    const missing = [];
+    if (action === "records") {
+        for (const r of answer.records)
+            if (!trailers.records.some((t) => t.kind === r.kind && t.id === r.id))
+                missing.push(`Chant-Record: ${r.kind}:${r.id}`);
+        if (missing.length)
+            throw new PublishError("publish-unrecorded", `commit ${sha.slice(0, 12)} sends records without naming them: it lacks ${missing.join(", ")} (ws-075)`, printed);
+        return null;
+    }
+    if (!trailers.records.some((t) => t.id === item))
+        missing.push(`Chant-Record: <kind>:${item}`);
+    if (trailers.applied === null)
+        missing.push(`Chant-Applied-By: ${by}`);
+    else if (trailers.applied.by !== by)
+        missing.push(`Chant-Applied-By: ${by} (it names ${trailers.applied.by})`);
+    if (trailers.applied?.at === null || trailers.applied?.at === undefined || Number.isNaN(Date.parse(trailers.applied.at)))
+        missing.push("Chant-Applied-At: <ISO 8601>");
+    if (trailers.applied?.commit === null || trailers.applied?.commit === undefined)
+        missing.push("Chant-Applied-Commit: <the applied branch's tip>");
+    if (missing.length)
+        throw new PublishError("publish-unrecorded", `commit ${sha.slice(0, 12)} applies ${item} without its apply record: it lacks ${missing.join(", ")} (ws-075)`, printed);
+    return { by: trailers.applied.by, at: trailers.applied.at, commit: trailers.applied.commit };
+}