@consiliency/agent-board-cli 1.24.0 → 1.25.0

package/dist/config_edit.js

@@ -0,0 +1,549 @@
+// SETUP SL-2 — text-preserving edits of harness config files (TOML and JSON/JSONC).
+//
+// The readers are doctor's (`parseRestrictedToml`, `parseJsonc`); nothing here has a grammar of its
+// own for what a file MEANS. An edit is text surgery on the one entry setup owns — every comment,
+// blank line and unrelated key stays byte-for-byte — and it is accepted only when doctor's reader,
+// run over the result, sees exactly the requested entry and, with that entry removed, exactly the
+// document it saw before. Anything the surgery cannot place unambiguously is refused with an authored
+// reason rather than appended: a blind second `[mcp_servers.x]` is a duplicate key the reader refuses.
+//
+// Nothing here touches the filesystem; `setup_writers.ts` reads and writes the files.
+import { FORBIDDEN_CONFIG_KEYS, UnparseableConfigError, own, parseJsonc, parseRestrictedToml, } from "./doctor_scopes.js";
+/** A refusal: the reason is an authored code, never file content. */
+export class ConfigEditRefused extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = "ConfigEditRefused";
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------------------------
+/** A canonical form: object keys sorted, prototype-free objects compared like plain ones. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort())
+            out[key] = canonical(value[key]);
+        return out;
+    }
+    return value;
+}
+export function deepEqual(a, b) {
+    return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+}
+/** `doc` with `path` removed (a copy); the parent tables are kept even when left empty. */
+function without(doc, path) {
+    const copy = canonical(doc);
+    let node = copy;
+    for (const part of path.slice(0, -1)) {
+        node = own(node, part);
+        if (node === undefined || node === null || typeof node !== "object")
+            return copy;
+    }
+    delete node[path[path.length - 1]];
+    return copy;
+}
+function lookup(doc, path) {
+    let node = doc;
+    for (const part of path)
+        node = own(node, part);
+    return node;
+}
+/**
+ * The accepted-edit check: the entry is exactly `entry`, and nothing else moved. A parent table the
+ * edit had to create (absent before) is removed from the comparison once empty.
+ */
+function verified(before, after, path, entry) {
+    if (!deepEqual(lookup(after, path), entry))
+        return false;
+    let rest = without(after, path);
+    for (let depth = path.length - 1; depth > 0; depth -= 1) {
+        const parent = path.slice(0, depth);
+        const created = lookup(before, parent) === undefined;
+        const node = lookup(rest, parent);
+        if (created && node !== null && typeof node === "object" && Object.keys(node).length === 0)
+            rest = without(rest, parent);
+    }
+    return deepEqual(without(before, path), rest);
+}
+// ---------------------------------------------------------------------------------------------
+// TOML
+// ---------------------------------------------------------------------------------------------
+const BARE_KEY = /^[A-Za-z0-9_-]+$/;
+const tomlKey = (key) => (BARE_KEY.test(key) ? key : JSON.stringify(key));
+// A JSON string literal is a valid TOML basic string for everything JSON.stringify emits.
+const tomlString = (value) => JSON.stringify(value);
+function tomlValue(value) {
+    if (typeof value === "string")
+        return tomlString(value);
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        // The reader returns a number for integers and finite floats only.
+        if (!Number.isFinite(value))
+            throw new ConfigEditRefused("config_layout_unrecognised");
+        return String(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(tomlValue).join(", ")}]`;
+    const table = value;
+    const pairs = Object.keys(table).map((key) => `${tomlKey(key)} = ${tomlValue(table[key])}`);
+    return pairs.length === 0 ? "{}" : `{ ${pairs.join(", ")} }`;
+}
+/** The block setup writes for `path` (a table header plus one line per key, in the entry's order). */
+export function renderTomlTable(path, entry) {
+    const lines = [`[${path.map(tomlKey).join(".")}]`];
+    for (const key of Object.keys(entry))
+        lines.push(`${tomlKey(key)} = ${tomlValue(entry[key])}`);
+    return `${lines.join("\n")}\n`;
+}
+/** The single-key chain of a parsed fragment (`a.b.c = 0` → [a, b, c]); arrays step into their last element. */
+function chain(parsed) {
+    const path = [];
+    let node = parsed;
+    for (;;) {
+        if (Array.isArray(node))
+            node = node[node.length - 1];
+        const keys = node && typeof node === "object" ? Object.keys(node) : [];
+        if (keys.length !== 1)
+            return path;
+        path.push(keys[0]);
+        node = node[keys[0]];
+    }
+}
+/**
+ * Where every table header and every key/value statement starts, found STRUCTURALLY: strings
+ * (basic, literal, and both multi-line forms), comments, and the brackets of arrays and inline
+ * tables are skipped, so a line inside a multi-line string or a multi-line array is never taken
+ * for a header or a key. Each path is read by doctor's own reader, so quoting and dotted forms
+ * match what the reader means. Returns null when the scan cannot place something (the caller
+ * refuses rather than guesses).
+ */
+function tomlStructure(text) {
+    const headers = [];
+    const keys = [];
+    let table = [];
+    let pos = 0;
+    const lineOf = (at) => text.slice(0, at).split("\n").length - 1;
+    /** Skip one value (or the rest of a statement) to the end of its line, honouring strings and brackets. */
+    const skipValue = () => {
+        let depth = 0;
+        while (pos < text.length) {
+            const char = text[pos];
+            if (text.startsWith("\"\"\"", pos) || text.startsWith("\'\'\'", pos)) {
+                // A multi-line string. A basic one (three double quotes) honours escapes, so a backslash
+                // followed by three quotes does not close it; a literal one (three single quotes) has no
+                // escapes. Up to two extra quotes before the closer belong to the content.
+                const quote = text.slice(pos, pos + 3);
+                let end = pos + 3;
+                for (;;) {
+                    if (end >= text.length)
+                        return false;
+                    if (quote[0] === "\"" && text[end] === "\\") {
+                        end += 2;
+                        continue;
+                    }
+                    if (text.startsWith(quote, end))
+                        break;
+                    end += 1;
+                }
+                while (text[end + 3] === quote[0])
+                    end += 1;
+                pos = end + 3;
+            }
+            else if (char === "\"") {
+                pos += 1;
+                while (pos < text.length && text[pos] !== "\"" && text[pos] !== "\n")
+                    pos += text[pos] === "\\" ? 2 : 1;
+                if (text[pos] !== "\"")
+                    return false;
+                pos += 1;
+            }
+            else if (char === "'") {
+                const end = text.indexOf("'", pos + 1);
+                if (end < 0 || text.slice(pos, end).includes("\n"))
+                    return false;
+                pos = end + 1;
+            }
+            else if (char === "#") {
+                while (pos < text.length && text[pos] !== "\n")
+                    pos += 1;
+            }
+            else if (char === "[" || char === "{") {
+                depth += 1;
+                pos += 1;
+            }
+            else if (char === "]" || char === "}") {
+                depth -= 1;
+                pos += 1;
+            }
+            else if (char === "\n" && depth === 0) {
+                pos += 1;
+                return true;
+            }
+            else
+                pos += 1;
+        }
+        return depth === 0;
+    };
+    while (pos < text.length) {
+        while (pos < text.length && (text[pos] === " " || text[pos] === "\t" || text[pos] === "\r"))
+            pos += 1;
+        if (pos >= text.length)
+            break;
+        const char = text[pos];
+        if (char === "\n") {
+            pos += 1;
+            continue;
+        }
+        if (char === "#") {
+            while (pos < text.length && text[pos] !== "\n")
+                pos += 1;
+            continue;
+        }
+        const index = lineOf(pos);
+        if (char === "[") {
+            const start = pos;
+            if (!skipValue())
+                return null;
+            const header = text.slice(start, pos).trim();
+            let parsed;
+            try {
+                parsed = parseRestrictedToml(header);
+            }
+            catch {
+                return null;
+            }
+            const path = chain(parsed);
+            headers.push({ index, path, array: header.startsWith("[[") });
+            table = path;
+            continue;
+        }
+        // A key/value statement: the key runs to the first `=` outside quotes.
+        let at = pos;
+        while (at < text.length && text[at] !== "=" && text[at] !== "\n") {
+            if (text[at] === "\"" || text[at] === "'") {
+                const close = text.indexOf(text[at], at + 1);
+                if (close < 0)
+                    return null;
+                at = close + 1;
+            }
+            else
+                at += 1;
+        }
+        if (text[at] !== "=")
+            return null;
+        let key;
+        try {
+            key = chain(parseRestrictedToml(`${text.slice(pos, at).trim()} = 0`));
+        }
+        catch {
+            return null;
+        }
+        keys.push({ index, table, key });
+        pos = at + 1;
+        if (!skipValue())
+            return null;
+    }
+    return { headers, keys };
+}
+/**
+ * A table on `path` (or on any prefix of it) that is not an ordinary `[table]`: an inline table or
+ * a dotted key defines it (TOML forbids extending either with a `[header]` later), or an
+ * array-of-tables header makes it an array. Appending `[mcp_servers.<name>]` beside one of those
+ * produces TOML a spec parser refuses, even when a permissive reader accepts it.
+ */
+function unownedDefinition(structure, path) {
+    const prefixes = path.map((_, index) => path.slice(0, index + 1));
+    for (const header of structure.headers) {
+        if (!header.array)
+            continue;
+        if (prefixes.some((prefix) => startsWith(prefix, header.path)) || startsWith(header.path, path))
+            return "config_array_table";
+    }
+    for (const line of structure.keys) {
+        const full = [...line.table, ...line.key];
+        if (prefixes.some((prefix) => line.table.length < prefix.length && startsWith(full, prefix)))
+            return "config_inline_table";
+    }
+    return null;
+}
+const startsWith = (path, prefix) => path.length >= prefix.length && prefix.every((part, index) => path[index] === part);
+function parseToml(text) {
+    try {
+        return parseRestrictedToml(text);
+    }
+    catch (error) {
+        if (error instanceof UnparseableConfigError)
+            throw new ConfigEditRefused("config_unparseable");
+        throw error;
+    }
+}
+/**
+ * Put `entry` at the table `path` (e.g. `["mcp_servers", "agent-board"]`) of a TOML document.
+ * Absent → appended as its own block; equal → the text unchanged; different → the table's own
+ * block(s) (its header, its sub-tables' headers, and their keys) replaced in place by the rendered
+ * block. Keys defined for it any other way (a dotted key under a parent table, an inline table)
+ * are a layout this edit does not own: refused, never appended beside.
+ */
+export function upsertTomlTable(text, path, entry) {
+    if (path.some((part) => FORBIDDEN_CONFIG_KEYS.has(part)))
+        throw new ConfigEditRefused("config_layout_unrecognised");
+    const before = parseToml(text);
+    const existing = lookup(before, path);
+    if (existing !== undefined && deepEqual(existing, entry))
+        return { prior: "exact", text };
+    const structure = tomlStructure(text);
+    if (structure === null)
+        throw new ConfigEditRefused("config_layout_unrecognised");
+    const unowned = unownedDefinition(structure, path);
+    if (unowned !== null)
+        throw new ConfigEditRefused(unowned);
+    const block = renderTomlTable(path, entry);
+    let next;
+    if (existing === undefined) {
+        const base = text === "" || text.endsWith("\n") ? text : `${text}\n`;
+        next = base.trim() === "" ? block : `${base}${base.endsWith("\n\n") ? "" : "\n"}${block}`;
+    }
+    else {
+        const lines = text.split("\n");
+        const headers = structure.headers;
+        const owned = headers.filter((header) => !header.array && startsWith(header.path, path));
+        if (owned.length === 0 || !owned.some((header) => header.path.length === path.length)) {
+            throw new ConfigEditRefused("config_layout_unrecognised");
+        }
+        // Each owned header's block runs to the next header of any kind; trailing blank and comment
+        // lines are left to whatever follows.
+        const ranges = owned.map((header) => {
+            const following = headers.find((other) => other.index > header.index);
+            let end = following ? following.index : lines.length;
+            while (end > header.index + 1 && /^\s*(#.*)?$/.test(lines[end - 1]))
+                end -= 1;
+            return { start: header.index, end };
+        });
+        const out = [];
+        let cursor = 0;
+        ranges.forEach((range, index) => {
+            out.push(...lines.slice(cursor, range.start));
+            if (index === 0)
+                out.push(...block.replace(/\n$/, "").split("\n"));
+            cursor = range.end;
+        });
+        out.push(...lines.slice(cursor));
+        next = out.join("\n");
+    }
+    let after;
+    try {
+        after = parseRestrictedToml(next);
+    }
+    catch {
+        throw new ConfigEditRefused("config_layout_unrecognised");
+    }
+    if (!verified(before, after, path, entry))
+        throw new ConfigEditRefused("config_layout_unrecognised");
+    return { prior: existing === undefined ? "absent" : "differs", text: next };
+}
+/** A JSONC scanner that records where each object member sits; comments and strings are skipped. */
+function scanJsonc(text) {
+    let pos = 0;
+    const fail = () => {
+        throw new ConfigEditRefused("config_unparseable");
+    };
+    const skip = () => {
+        for (;;) {
+            while (pos < text.length && /\s/.test(text[pos]))
+                pos += 1;
+            if (text.startsWith("//", pos)) {
+                while (pos < text.length && text[pos] !== "\n")
+                    pos += 1;
+            }
+            else if (text.startsWith("/*", pos)) {
+                const end = text.indexOf("*/", pos + 2);
+                if (end < 0)
+                    fail();
+                pos = end + 2;
+            }
+            else
+                return;
+        }
+    };
+    const string = () => {
+        const start = pos;
+        pos += 1;
+        while (pos < text.length && text[pos] !== "\"")
+            pos += text[pos] === "\\" ? 2 : 1;
+        if (text[pos] !== "\"")
+            fail();
+        pos += 1;
+        return { start, end: pos };
+    };
+    const value = () => {
+        skip();
+        const start = pos;
+        const char = text[pos];
+        if (char === "{") {
+            pos += 1;
+            const members = [];
+            for (;;) {
+                skip();
+                if (text[pos] === "}") {
+                    pos += 1;
+                    return { kind: "object", span: { start, end: pos }, members };
+                }
+                if (text[pos] !== "\"")
+                    fail();
+                const keySpan = string();
+                let key;
+                try {
+                    key = JSON.parse(text.slice(keySpan.start, keySpan.end));
+                }
+                catch {
+                    return fail();
+                }
+                skip();
+                if (text[pos] !== ":")
+                    fail();
+                pos += 1;
+                const member = { key, keySpan, value: value(), comma: null };
+                members.push(member);
+                skip();
+                if (text[pos] === ",") {
+                    member.comma = pos;
+                    pos += 1;
+                }
+                else if (text[pos] !== "}")
+                    fail();
+            }
+        }
+        if (char === "[") {
+            pos += 1;
+            for (;;) {
+                skip();
+                if (text[pos] === "]") {
+                    pos += 1;
+                    return { kind: "other", span: { start, end: pos } };
+                }
+                value();
+                skip();
+                if (text[pos] === ",")
+                    pos += 1;
+                else if (text[pos] !== "]")
+                    fail();
+            }
+        }
+        if (char === "\"") {
+            string();
+            return { kind: "other", span: { start, end: pos } };
+        }
+        const match = /^(?:true|false|null|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(text.slice(pos));
+        if (!match)
+            return fail();
+        pos += match[0].length;
+        return { kind: "other", span: { start, end: pos } };
+    };
+    const root = value();
+    skip();
+    if (pos !== text.length)
+        fail();
+    return root;
+}
+/** The indentation of the line `index` sits on. */
+function indentAt(text, index) {
+    const lineStart = text.lastIndexOf("\n", index - 1) + 1;
+    return /^[ \t]*/.exec(text.slice(lineStart))[0];
+}
+/** `value` as JSON, its nested lines indented under `indent`, stepped by `unit`. */
+function renderJson(value, indent, unit) {
+    return JSON.stringify(value, null, unit).split("\n").join(`\n${indent}`);
+}
+function unitOf(text) {
+    const match = /\n([ \t]+)\S/.exec(text);
+    return match ? match[1] : "  ";
+}
+/**
+ * Put `entry` at `path` of a JSON/JSONC object document. Empty text is an empty object. Missing
+ * intermediate objects are created; an existing member is replaced in its span; a new member is
+ * inserted before its object's closing brace. `strict` also requires the input to be plain JSON,
+ * for a harness whose reader is strict (an edit never makes a file unreadable to its harness).
+ */
+export function upsertJsonMember(text, path, entry, options = {}) {
+    if (path.length === 0 || path.some((part) => FORBIDDEN_CONFIG_KEYS.has(part)))
+        throw new ConfigEditRefused("config_layout_unrecognised");
+    const source = text.trim() === "" ? "{}\n" : text;
+    let before;
+    try {
+        if (options.strict)
+            JSON.parse(source);
+        before = parseJsonc(source);
+    }
+    catch (error) {
+        if (error instanceof UnparseableConfigError || error instanceof SyntaxError)
+            throw new ConfigEditRefused("config_unparseable");
+        throw error;
+    }
+    if (!before || typeof before !== "object" || Array.isArray(before))
+        throw new ConfigEditRefused("config_not_an_object");
+    const existing = lookup(before, path);
+    if (existing !== undefined && deepEqual(existing, entry))
+        return { prior: "exact", text };
+    const unit = unitOf(source);
+    let node = scanJsonc(source);
+    let next = null;
+    for (let depth = 0; depth < path.length; depth += 1) {
+        if (node.kind !== "object")
+            throw new ConfigEditRefused("config_layout_unrecognised");
+        const matches = node.members.filter((member) => member.key === path[depth]);
+        if (matches.length > 1)
+            throw new ConfigEditRefused("config_layout_unrecognised");
+        const member = matches[0];
+        if (member && depth === path.length - 1) {
+            const indent = indentAt(source, member.keySpan.start);
+            next = source.slice(0, member.value.span.start) + renderJson(entry, indent, unit) + source.slice(member.value.span.end);
+            break;
+        }
+        if (member) {
+            node = member.value;
+            continue;
+        }
+        // Insert the rest of the path as one new member of this object.
+        let value = entry;
+        for (let rest = path.length - 1; rest > depth; rest -= 1)
+            value = { [path[rest]]: value };
+        const close = node.span.end - 1;
+        const last = node.members[node.members.length - 1];
+        const objectIndent = indentAt(source, node.span.start);
+        const memberIndent = last ? indentAt(source, last.keySpan.start) : objectIndent + unit;
+        const rendered = `${JSON.stringify(path[depth])}: ${renderJson(value, memberIndent, unit)}`;
+        if (last) {
+            // After the last member's comma when it has one (a JSONC trailing comma is kept, and ours
+            // follows the same style), else after its value with a comma added.
+            next = last.comma !== null
+                ? `${source.slice(0, last.comma + 1)}\n${memberIndent}${rendered},${source.slice(last.comma + 1)}`
+                : `${source.slice(0, last.value.span.end)},\n${memberIndent}${rendered}${source.slice(last.value.span.end)}`;
+        }
+        else {
+            const inner = source.slice(node.span.start + 1, close);
+            next = `${source.slice(0, node.span.start + 1)}${inner.trimEnd() === "" ? "" : inner.trimEnd()}\n${memberIndent}${rendered}\n${objectIndent}${source.slice(close)}`;
+        }
+        break;
+    }
+    if (next === null)
+        throw new ConfigEditRefused("config_layout_unrecognised");
+    let after;
+    try {
+        if (options.strict)
+            JSON.parse(next);
+        after = parseJsonc(next);
+    }
+    catch {
+        throw new ConfigEditRefused("config_layout_unrecognised");
+    }
+    if (!verified(before, after, path, entry))
+        throw new ConfigEditRefused("config_layout_unrecognised");
+    return { prior: existing === undefined ? "absent" : "differs", text: next };
+}

package/dist/doctor.d.ts

@@ -1,7 +1,7 @@
 import { type IdentityHarness, type OperationSuccess, type OsKeychainExec, type SessionRecordEntry, type TrustOptions } from "@consiliency/agent-board-client";
 import { type ClaudePluginSummary, type RegistrationFs, type RegQuery, type RegistrationVerdict } from "./doctor_scopes.js";
 export type DoctorStatus = "pass" | "fail" | "undetermined";
-export declare const DOCTOR_CHECKS: readonly ["identity_file", "keystore_key", "whoami", "board_membership", "registration", "runtime"];
+export declare const DOCTOR_CHECKS: readonly ["identity_file", "keystore_key", "key_storage", "whoami", "board_membership", "registration", "runtime"];
 export type DoctorCheckName = (typeof DOCTOR_CHECKS)[number];
 export interface DoctorCheck {
     status: DoctorStatus;
@@ -91,6 +91,12 @@ export interface DoctorOptions {
     lookupUserName?: () => string;
     /** Registry probe (Windows/WSL policy keys). Default: `reg query … /v Settings`, 5 s. */
     regQuery?: RegQuery;
+    /** key_storage: the directory holding the packaged `status.sh`. Default `resolveKeyslotDir()`. */
+    keyslotDir?: string;
+    /** key_storage: the host identity the keyslot records bind to. Default `/etc/machine-id`. */
+    machineIdFile?: string;
+    /** key_storage: doctor's own uid. Default `process.getuid()`. */
+    uid?: number;
 }
 /**
  * An error's `code`, only when this repository wrote it: a member of the derived