@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/box-intent.js

@@ -0,0 +1,126 @@
+/**
+ * A box's intent (#2850): the decision record its box block names.
+ *
+ * A new box starts as a question, and the first answer to it is what the box
+ * is for. That answer is a decision record, so the intent graph, hud and a
+ * box's runtime all read the same thing. The box block names the record's
+ * id in `intent`; the record is looked for among the records of every
+ * declared kind named `decision` (the entry's `name`, or the kind file's
+ * `recordKind.name`), read from the working tree through the same reader as
+ * `chant workspace records`.
+ *
+ * `chant workspace status --json` reports the record's state and answer
+ * under the member's `box.intent`, and `chant workspace check` fails when no
+ * decision record has the id (WSP126) and warns when the record constrains
+ * no member or path of this workspace at all (WSP127, #2857): the member it
+ * names need not be the box's own, since a decision naming another member
+ * can be what the box is for, such as the app it runs.
+ */
+import { loadDeclaredKinds } from "./declared-kinds.js";
+import { constraintCovers, isWorkspacePath } from "./record-assets.js";
+import { workingTree } from "./tree.js";
+/** The declared kind name a box's intent is looked for in. */
+export const INTENT_KIND_NAME = "decision";
+const str = (v) => (typeof v === "string" ? v : null);
+/** The label of `options[]`'s entry whose id is `choice.option`, or null when no option is chosen. */
+function answerOf(choice, options) {
+    const chosen = choice && typeof choice === "object" ? choice.option : null;
+    if (typeof chosen !== "string" || !Array.isArray(options))
+        return null;
+    const found = options.find((o) => !!o && typeof o === "object" && o.id === chosen);
+    return found && typeof found.label === "string" ? found.label : null;
+}
+/** The intent of `id` with no record: every field but the id null. */
+export function unresolvedIntent(id) {
+    return { id, state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null, approved: false };
+}
+/**
+ * Resolve the intent of every box that names one, reading the records of each
+ * declared decision kind once. `kinds` are the declared kinds already loaded,
+ * when the caller has them. Only the working tree is read.
+ */
+export async function resolveBoxIntents(declaration, root, kinds) {
+    const boxes = declaration.members.filter((m) => m.box?.intent != null);
+    if (boxes.length === 0)
+        return [];
+    const loaded = kinds ?? (await loadDeclaredKinds(declaration, workingTree(root), root));
+    const decisionKinds = loaded.filter((k) => (k.declared.name ?? k.kind) === INTENT_KIND_NAME);
+    const found = new Map();
+    const problems = [];
+    const { readRecordsFor } = await import("./records-cli.js");
+    const { RecordReadError } = await import("./records.js");
+    for (const k of decisionKinds) {
+        if (k.reason) {
+            problems.push(`${k.declared.path} can't be loaded: ${k.reason.message}`);
+            continue;
+        }
+        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 ?? {};
+                const constrains = Array.isArray(data[field]) ? data[field].filter((c) => typeof c === "string") : [];
+                found.set(r.id, {
+                    kind: k.declared.path,
+                    path: r.path,
+                    constrains,
+                    intent: {
+                        id: r.id,
+                        state: r.state,
+                        question: str(data.question),
+                        choice: data.choice ?? null,
+                        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,
+                    },
+                });
+            }
+        }
+        catch (err) {
+            if (!(err instanceof RecordReadError))
+                throw err;
+            problems.push(`${k.declared.path} can't be read: ${err.message}`);
+        }
+    }
+    const why = decisionKinds.length === 0
+        ? `the declaration names no record kind called ${INTENT_KIND_NAME}`
+        : `no record of ${decisionKinds.map((k) => k.declared.path).join(" or ")} has that id` + (problems.length > 0 ? ` (${problems.join("; ")})` : "");
+    return boxes.map((m) => {
+        const record = found.get(m.box.intent) ?? null;
+        return { member: m.name, id: m.box.intent, pointer: `${m.box.pointer}/intent`, record, why: record ? "" : why };
+    });
+}
+/**
+ * Whether a constrains entry covers something of the box: `member:<name>`, or
+ * a `path:` entry that is the member's directory, a directory above it or a
+ * path inside it.
+ */
+export function constrainsBox(entry, member) {
+    if (entry === `member:${member.name}`)
+        return true;
+    if (!entry.startsWith("path:"))
+        return false;
+    const path = entry.slice("path:".length);
+    if (!isWorkspacePath(path))
+        return false;
+    // The root member holds every path.
+    if (member.dir === ".")
+        return true;
+    return constraintCovers(path, member.dir) || constraintCovers(member.dir, path);
+}
+/**
+ * Whether a constrains entry names a member or path of this workspace at
+ * all: `member:<name>` for any declared member, or a `path:` entry that is
+ * some member's directory, a directory above it or a path inside it. An
+ * intent's constrains can govern a member other than the one whose box
+ * names it (a box run by one member can be what a decision about another
+ * member's app is for), so this asks only whether the entry is real, not
+ * whether it reaches a particular member.
+ */
+export function constrainsWorkspace(entry, members) {
+    return members.some((m) => constrainsBox(entry, m));
+}

package/dist/workspace/box-isolation.js

@@ -0,0 +1,169 @@
+/**
+ * Box isolation (#2727): the ports, state paths and cookie names each box
+ * uses, derived from its identity and its host, never chosen by a runtime.
+ *
+ * A box is a member with a `box` block (#2726), and its name is the
+ * member's. A box's identity is its host, its name and its slot, from the
+ * block's `host` and `slot`. Everything else
+ * follows from those and the host's declaration, and nothing else goes in:
+ *
+ * - port `p` is `host.ports.from + slot * host.ports.perBox + offset(p)`;
+ * - the state directory is `<host.stateRoot>/<box name>`, and state entry
+ *   `k` is that directory joined with the entry's relative path;
+ * - cookie `c` is `<c>_<box name>`.
+ *
+ * So the same declaration gives the same values on every machine and every
+ * run, and adding or removing a box changes no other box's values. The state
+ * paths keep their environment reference (`${XDG_STATE_HOME}` by default):
+ * the runtime that sets them expands it on its machine, and chant never
+ * reads the machine.
+ *
+ * Distinct names on one host give distinct state paths and cookie names by
+ * construction (a member name has no `_`, so `<c>_<box>` splits one way).
+ * Ports are the only value two boxes can share: two boxes on one host with
+ * the same slot, or two ports in one box at the same offset. `chant
+ * workspace check` compares every value anyway (WSP123), so an entry whose
+ * path escapes its directory is caught too.
+ */
+import { DEFAULT_STATE_ROOT } from "./declaration.js";
+import { pointerToken } from "./jsonc.js";
+/** The host's state root as written, or the default. */
+export function stateRootOf(host) {
+    return host.stateRoot ?? DEFAULT_STATE_ROOT;
+}
+const trimSlash = (s) => s.replace(/\/+$/, "");
+/** Resolve the isolation of the box named `name` on its host. */
+export function resolveIsolation(name, box, host) {
+    const first = host.ports.from + box.slot * host.ports.perBox;
+    const stateDir = `${trimSlash(stateRootOf(host))}/${name}`;
+    return {
+        host: box.host,
+        slot: box.slot,
+        portRange: { from: first, to: first + host.ports.perBox - 1 },
+        ports: Object.fromEntries(Object.entries(box.ports).map(([name, offset]) => [name, first + offset])),
+        stateDir,
+        state: Object.fromEntries(Object.entries(box.state).map(([name, path]) => [name, `${stateDir}/${path.replace(/^\.\/+/, "")}`])),
+        cookies: Object.fromEntries(box.cookies.map((c) => [c, `${c}_${name}`])),
+    };
+}
+/** Every box that declares its isolation, resolved, in member order. The declaration read already checked each box's host exists. */
+export function resolveBoxes(declaration) {
+    const hosts = new Map(declaration.hosts.map((h) => [h.name, h]));
+    const out = [];
+    for (const m of declaration.members) {
+        const iso = m.box?.isolation;
+        if (iso)
+            out.push({ member: m, isolation: resolveIsolation(m.name, iso, hosts.get(iso.host)) });
+    }
+    return out;
+}
+// ── Literal machine paths (WSP124) ───────────────────────────────────────────
+const ENV_REF = /^\$(\{[A-Za-z_][A-Za-z0-9_]*\}|[A-Za-z_][A-Za-z0-9_]*)/;
+const HOME_REF = /^\$(\{HOME\}|HOME)(?![A-Za-z0-9_])/;
+/**
+ * Why a host's `stateRoot` is a literal machine path, or undefined when it is
+ * not. A state root starts with an environment reference the runtime expands,
+ * and that reference is not `$HOME`: a path under a home directory names one
+ * person's machine layout (`${HOME}/<user>/...`), where `${XDG_STATE_HOME}`
+ * names the place the machine keeps state.
+ */
+export function stateRootLiteral(root) {
+    if (HOME_REF.test(root))
+        return "starts at $HOME, which names one person's machine layout; use ${XDG_STATE_HOME} or another variable the runtime sets";
+    if (!ENV_REF.test(root))
+        return "does not start with an environment reference such as ${XDG_STATE_HOME}, so it names one machine's layout";
+    if (root.split("/").includes(".."))
+        return "has a .. segment";
+    return undefined;
+}
+/**
+ * Why a state entry's path is not one relative to the box's state directory,
+ * or undefined when it is: absolute, home-relative, starting with an
+ * environment reference, a Windows drive path, or with a `..` segment.
+ */
+export function statePathLiteral(path) {
+    if (path.startsWith("/"))
+        return "is absolute";
+    if (path.startsWith("~"))
+        return "starts at a home directory";
+    if (path.startsWith("$"))
+        return "starts with an environment reference";
+    if (/^[A-Za-z]:[\\/]/.test(path) || path.includes("\\"))
+        return "is a Windows path";
+    if (path.split("/").includes(".."))
+        return "has a .. segment, which leaves the box's state directory";
+    return undefined;
+}
+/** Every literal machine path in the hosts and boxes. */
+export function boxLiterals(declaration) {
+    const out = [];
+    for (const h of declaration.hosts) {
+        if (h.stateRoot === null)
+            continue;
+        const why = stateRootLiteral(h.stateRoot);
+        if (why)
+            out.push({ box: null, message: `host ${h.name}'s stateRoot ${JSON.stringify(h.stateRoot)} ${why}`, pointer: `${h.pointer}/stateRoot` });
+    }
+    for (const m of declaration.members) {
+        for (const [name, path] of Object.entries(m.box?.isolation?.state ?? {})) {
+            const why = statePathLiteral(path);
+            if (why) {
+                out.push({
+                    box: m.name,
+                    message: `member ${m.name}'s box gives state ${name} the path ${JSON.stringify(path)}, which ${why}; state paths are relative to the box's state directory, which chant derives from the host's stateRoot and the member's name`,
+                    pointer: `${m.box.pointer}/state/${pointerToken(name)}`,
+                });
+            }
+        }
+    }
+    return out;
+}
+/** Collapse `.`, `..` and repeated slashes, so two spellings of one path compare equal. */
+function normalizePath(path) {
+    const out = [];
+    for (const seg of path.split("/")) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === ".." && out.length > 0 && out[out.length - 1] !== "..")
+            out.pop();
+        else
+            out.push(seg);
+    }
+    return (path.startsWith("/") ? "/" : "") + out.join("/");
+}
+/**
+ * Every value two holders on one host resolve to. Ports collide within a box
+ * too, since two listeners can't share a port; state entries in one box may
+ * name one file on purpose (a runtime and the door both reading hud's
+ * identity), and cookies are unique in a box by the schema.
+ */
+export function boxCollisions(declaration) {
+    const resolved = resolveBoxes(declaration);
+    const seen = new Map();
+    const add = (host, what, value, box, name, pointer) => {
+        const key = `${host}\u0000${what}\u0000${value}`;
+        let c = seen.get(key);
+        if (!c) {
+            c = { host, what, value, holders: [] };
+            seen.set(key, c);
+        }
+        c.holders.push({ box, name, pointer });
+    };
+    for (const { member, isolation: r } of resolved) {
+        const at = member.box.pointer;
+        const box = member.name;
+        for (const [name, port] of Object.entries(r.ports))
+            add(r.host, "port", String(port), box, name, `${at}/ports/${pointerToken(name)}`);
+        const files = new Set();
+        for (const [name, path] of Object.entries(r.state)) {
+            const file = normalizePath(path);
+            if (files.has(file))
+                continue;
+            files.add(file);
+            add(r.host, "state", file, box, name, `${at}/state/${pointerToken(name)}`);
+        }
+        Object.entries(r.cookies).forEach(([name, cookie], i) => add(r.host, "cookie", cookie, box, name, `${at}/cookies/${i}`));
+    }
+    // A state file is counted once per box above, so two holders are two boxes.
+    return [...seen.values()].filter((c) => c.holders.length > 1);
+}

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

@@ -0,0 +1,204 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/box-listing-write/v1/box-listing-write.schema.json",
+  "title": "chant workspace box listing set output",
+  "description": "What `chant workspace box listing set <member> [--from <file|->] [--cover <image>]` prints (#3308): the box's listing before and after, the files the write changed, and the cover it copied, or the reason it wrote nothing. The write changes only members[i].box.listing in the declaration, in place, keeping the file's formatting and comments, and the cover file it copies. 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.103.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The listing 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", "listing", "cover"],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/box-listing-write/v1/box-listing-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 listing."
+        },
+        "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": "Every file the write changed, or would change with --dry-run, relative to the repository root: the cover it copied, then the declaration. Empty when the listing and cover already held what was given."
+        },
+        "changed": {
+          "type": "boolean",
+          "description": "Whether any file changed: paths is not empty."
+        },
+        "dryRun": {
+          "type": "boolean",
+          "description": "True when --dry-run was given and nothing was written."
+        },
+        "previous": {
+          "description": "The listing before the write, as chant workspace status --json prints it, or null when the box declared none.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/listing"
+            }
+          ]
+        },
+        "listing": {
+          "$ref": "#/$defs/listing",
+          "description": "The listing after the write, as chant workspace status --json prints it, defaults filled in and the cover hashed."
+        },
+        "cover": {
+          "description": "The image --cover copied in, or null without --cover.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": ["path", "sha256", "bytes", "type", "replaced"],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "description": "Where it was copied, from the workspace root: --cover-path, else the listing's cover when its extension fits, else <member dir>/listing/cover.<png|jpg|webp>."
+                },
+                "sha256": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$"
+                },
+                "bytes": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "type": {
+                  "enum": ["image/png", "image/jpeg", "image/webp"]
+                },
+                "replaced": {
+                  "type": ["string", "null"],
+                  "description": "The cover the listing named before, from the workspace root, when it was another file. That file is left in place; the caller removes it in the same commit if nothing else uses it."
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "listing": {
+      "type": "object",
+      "required": ["published", "title", "line", "cover"],
+      "properties": {
+        "published": {
+          "type": "boolean"
+        },
+        "title": {
+          "type": "string"
+        },
+        "line": {
+          "type": "string"
+        },
+        "cover": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": ["path", "sha256"],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "description": "From the workspace root."
+                },
+                "sha256": {
+                  "type": ["string", "null"],
+                  "pattern": "^[0-9a-f]{64}$"
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "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-listing-write/v1/box-listing-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",
+                "listing-member-unknown",
+                "listing-box-missing",
+                "listing-cover-invalid",
+                "write-scope-member",
+                "write-scope-protected",
+                "write-scope-class-unknown",
+                "agent-unknown",
+                "principal-unidentified",
+                "write-lock-timeout",
+                "write-lock-not-held"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}