heedvane 0.0.0-stage → 0.1.0

package/dist/config-doc.js

@@ -0,0 +1,465 @@
+/**
+ * Per-format parse / patch / serialize for agent config files.
+ *
+ * Formats:
+ *  - "json"     — strict JSON (JSON.parse), servers key `mcpServers`
+ *  - "jsonc"    — JSON with comments (jsonc-parser), style preserved via
+ *                 format edits; servers key `mcpServers`
+ *  - "toml"     — smol-toml parse/stringify, servers key `mcp_servers`
+ *  - "vscode"   — strict JSON, servers key `servers`
+ *  - "opencode" — strict JSON, servers key `mcp`
+ *
+ * A ParsedDoc carries the parsed value; for JSONC it also carries the original
+ * text so mutations can be applied as edits that preserve comments and the
+ * user's existing style. JSONC mutation MUST go through withServer /
+ * removeServer — mutating doc.value directly leaves the edit buffer stale.
+ */
+import { applyEdits as applyJsoncEdits, modify as modifyJsonc, parse as parseJsonc, parseTree as parseJsoncTree, } from "jsonc-parser";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { SNIPPET_MARKER, isHeedvaneEntry } from "./mcp.js";
+import { errorMessage, isRecord } from "./guards.js";
+class ConfigParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigParseError";
+    }
+}
+/** Thrown when the servers table exists but is not an object (never overwrite such a file). */
+class ServersTableError extends Error {
+    serversKey;
+    constructor(serversKey) {
+        super(`"${serversKey}" exists but is not an object`);
+        this.name = "ServersTableError";
+        this.serversKey = serversKey;
+    }
+}
+function defaultServersKey(format) {
+    switch (format) {
+        case "toml":
+            return "mcp_servers";
+        case "vscode":
+            return "servers";
+        case "opencode":
+            return "mcp";
+        case "jsonc":
+        case "json":
+            return "mcpServers";
+    }
+}
+const JSONC_EDIT_OPTS = { formattingOptions: { insertSpaces: true, tabSize: 2 } };
+/** Parse config text into a ParsedDoc. Throws ConfigParseError on malformed input. */
+export function parseDoc(text, format) {
+    if (format === "toml") {
+        let value;
+        try {
+            value = parseToml(text);
+        }
+        catch (e) {
+            throw new ConfigParseError(`invalid TOML: ${errorMessage(e)}`);
+        }
+        if (!isRecord(value))
+            throw new ConfigParseError("TOML document is not a table at the top level");
+        return { format, value, text, edited: false };
+    }
+    if (format === "jsonc") {
+        const errors = [];
+        const value = parseJsonc(text, errors, { allowTrailingComma: true });
+        if (errors.length > 0 || value === undefined) {
+            throw new ConfigParseError("invalid JSONC");
+        }
+        if (!isRecord(value))
+            throw new ConfigParseError("JSONC document is not an object at the top level");
+        return { format, value, text, edited: false };
+    }
+    // json | vscode | opencode
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (e) {
+        throw new ConfigParseError(`invalid JSON: ${errorMessage(e)}`);
+    }
+    if (!isRecord(value))
+        throw new ConfigParseError("JSON document is not an object at the top level");
+    return { format, value };
+}
+/**
+ * Serialize a doc back to text.
+ * - JSON family: 2-space pretty JSON with trailing newline.
+ * - JSONC: if the doc carries an edit buffer (edited), return it verbatim —
+ *   comments and surrounding style preserved. If the doc was never edited and
+ *   `originalText` is given, return `originalText` unchanged (no semantic
+ *   change => no byte change). Otherwise fall back to pretty JSON.
+ * - TOML: the edit buffer when it decodes to the doc's value (comments preserved),
+ *   else smol-toml stringify.
+ */
+export function serializeDoc(doc, format, originalText) {
+    if (doc.format !== format)
+        throw new Error(`doc format ${doc.format} does not match requested ${format}`);
+    if (format === "jsonc") {
+        if (doc.edited && typeof doc.text === "string")
+            return doc.text;
+        if (originalText !== undefined)
+            return originalText;
+        return JSON.stringify(doc.value, null, 2) + "\n";
+    }
+    if (format === "toml") {
+        const edited = tomlEditedText(doc);
+        if (edited !== undefined)
+            return edited;
+        let out;
+        try {
+            out = stringifyToml(doc.value);
+        }
+        catch (e) {
+            throw new Error(`failed to serialize TOML: ${errorMessage(e)}`, { cause: e });
+        }
+        return out.endsWith("\n") ? out : out + "\n";
+    }
+    return JSON.stringify(doc.value, null, 2) + "\n";
+}
+/** The container key naming the document's own top level (Cursor's `version`), not a table inside it. */
+export const TOP_LEVEL = ".";
+/**
+ * Compat helper (A's API): read `doc[containerKey][entryName]` without the
+ * per-format servers-key machinery, or `doc[entryName]` for {@link TOP_LEVEL}.
+ * `undefined` when either level is missing or not a plain object.
+ */
+export function readEntry(doc, containerKey, entryName) {
+    if (containerKey === TOP_LEVEL)
+        return doc.value[entryName];
+    const container = doc.value[containerKey];
+    if (!isRecord(container))
+        return undefined;
+    return container[entryName];
+}
+/** The servers map of a doc, or undefined when absent. Throws ServersTableError when present but not an object. */
+export function getServers(doc, format, serversKey = defaultServersKey(format)) {
+    if (doc.format !== format)
+        throw new Error(`doc format ${doc.format} does not match requested ${format}`);
+    const v = doc.value[serversKey];
+    if (v === undefined)
+        return undefined;
+    if (!isRecord(v))
+        throw new ServersTableError(serversKey);
+    return v;
+}
+function ensureServersContainer(doc, serversKey) {
+    const v = doc.value[serversKey];
+    if (v === undefined) {
+        doc.value[serversKey] = {};
+        return;
+    }
+    if (!isRecord(v))
+        throw new ServersTableError(serversKey);
+}
+/** JSONC: ensure `<key> = {}` exists in the text buffer, preserving style. */
+function jsoncEnsureTable(text, key) {
+    const parsed = parseJsonc(text, [], { allowTrailingComma: true });
+    const container = isRecord(parsed) ? parsed[key] : undefined;
+    if (container === undefined) {
+        return applyJsoncEdits(text, modifyJsonc(text, [key], {}, JSONC_EDIT_OPTS));
+    }
+    if (!isRecord(container))
+        throw new ServersTableError(key);
+    return text;
+}
+function jsoncSyncValue(doc) {
+    const parsed = parseJsonc(doc.text, [], { allowTrailingComma: true });
+    if (!isRecord(parsed))
+        throw new ConfigParseError("JSONC edit produced a non-object document");
+    doc.value = parsed;
+}
+function jsoncPrepareBuffer(doc) {
+    if (typeof doc.text !== "string")
+        doc.text = JSON.stringify(doc.value, null, 2);
+    return doc.text;
+}
+/** Set (or, with `undefined`, remove) one top-level key of a JSON or JSONC document, keeping JSONC comments. */
+export function withTopLevelKey(doc, edit) {
+    const { key, value } = edit;
+    const { format } = doc;
+    if (format === "jsonc") {
+        const text = jsoncPrepareBuffer(doc);
+        doc.text = applyJsoncEdits(text, modifyJsonc(text, [key], value, JSONC_EDIT_OPTS));
+        doc.edited = true;
+        jsoncSyncValue(doc);
+        return doc;
+    }
+    if (format !== "json")
+        throw new Error(`top-level keys are only edited in JSON documents, not ${format}`);
+    if (value === undefined)
+        delete doc.value[key];
+    else
+        doc.value[key] = value;
+    return doc;
+}
+/** Find the `property` node for `key` inside an object node. */
+function findPropertyNode(obj, key) {
+    if (obj.type !== "object" || !obj.children)
+        return undefined;
+    for (const prop of obj.children) {
+        if (prop.type === "property" && prop.children && prop.children[0].type === "string" && prop.children[0].value === key) {
+            return prop;
+        }
+    }
+    return undefined;
+}
+/**
+ * Style-preserving removal of `servers[name]` from JSONC text.
+ *
+ * jsonc-parser's own delete (modify with undefined) reformats the whole
+ * containing object and strips comments around the removed entry — losing
+ * the user's comments on SIBLING entries. Instead we remove exactly the
+ * property's own text: its indentation, the entry, its trailing comma, the
+ * rest of its line, and (if the entry started its own line) a comment-only
+ * line directly above it. Neighbouring comments and entries are untouched.
+ */
+/** Offset moved back over the line's leading indentation whitespace. */
+function indentStart(text, offset) {
+    let start = offset;
+    while (start > 0 && (text[start - 1] === " " || text[start - 1] === "\t"))
+        start -= 1;
+    return start;
+}
+/**
+ * If `start` sits at the beginning of a line whose line directly above is a
+ * comment-only line, that comment belongs to the entry — return the comment's
+ * own start. Otherwise return `start` unchanged.
+ */
+function commentLineAboveStart(text, start) {
+    const prevNl = text.lastIndexOf("\n", start - 1);
+    if (prevNl === -1)
+        return start;
+    const prevLine = text.slice(prevNl + 1, start).trim();
+    if (!/^(\/\/.*|\/\*.*\*\/)$/.test(prevLine))
+        return start;
+    const commentStart = indentStart(text, prevNl + 1);
+    if (commentStart === prevNl + 1 || text.slice(commentStart, prevNl).trim().length === prevLine.length) {
+        return commentStart; // only whitespace before the comment on that line
+    }
+    return start;
+}
+/** One past the entry's own text: trailing comma, any trailing padding, then the line's newline. */
+function removalEnd(text, propEnd) {
+    let end = propEnd;
+    if (text[end] === ",")
+        end += 1; // trailing comma goes with the entry
+    // Consume the rest of the line (up to and including its newline) so no
+    // blank husk is left behind.
+    while (end < text.length && text[end] !== "\n" && text[end] !== "\r") {
+        if (text[end] !== " " && text[end] !== "\t")
+            break; // more content on this line — keep it
+        end += 1;
+    }
+    if (text[end] === "\r")
+        end += 1;
+    if (text[end] === "\n")
+        end += 1;
+    return end;
+}
+function jsoncRemoveProperty(text, serversKey, name) {
+    const root = parseJsoncTree(text, [], { allowTrailingComma: true });
+    if (!root)
+        return text;
+    const serversObj = findPropertyNode(root, serversKey)?.children?.[1];
+    const propNode = serversObj !== undefined ? findPropertyNode(serversObj, name) : undefined;
+    if (!propNode)
+        return text;
+    // Eat back the entry's indentation; a comment-only line directly above it
+    // belongs to the entry and is removed too.
+    const start = commentLineAboveStart(text, indentStart(text, propNode.offset));
+    const end = removalEnd(text, propNode.offset + propNode.length);
+    return applyJsoncEdits(text, [{ offset: start, length: end - start, content: "" }]);
+}
+/**
+ * Set `servers[name] = desired`, creating the servers table when missing.
+ * For JSONC the change is applied as a format edit on the preserved text.
+ * Returns the same doc (mutated), for chaining.
+ */
+export function withServer(doc, format, edit) {
+    const { serversKey, name, desired } = edit;
+    if (doc.format !== format)
+        throw new Error(`doc format ${doc.format} does not match requested ${format}`);
+    if (format === "jsonc") {
+        let text = jsoncPrepareBuffer(doc);
+        text = jsoncEnsureTable(text, serversKey);
+        const value = entryValue(serversKey, readEntry(doc, serversKey, name), desired);
+        doc.text = applyJsoncEdits(text, modifyJsonc(text, [serversKey, name], value, JSONC_EDIT_OPTS));
+        doc.edited = true;
+        jsoncSyncValue(doc);
+        return doc;
+    }
+    ensureServersContainer(doc, serversKey);
+    const servers = doc.value[serversKey];
+    servers[name] = entryValue(serversKey, servers[name], desired);
+    if (format === "toml")
+        tomlEditTable(doc, { key: serversKey, name, value: servers[name] });
+    return doc;
+}
+/**
+ * TOML: rewrite only our entry in the edit buffer, leaving every other line, comment included, as it
+ * was. A table entry is the `[<key>.<name>]` table (and its sub-tables); a scalar entry is its
+ * `name = …` line inside `[<key>]`. `value` undefined removes it, and then a `[<key>]` left empty.
+ */
+function tomlEditTable(doc, table) {
+    const { key, name, value } = table;
+    if (typeof doc.text !== "string")
+        return; // fresh doc: serializeDoc stringifies the value
+    const ours = new RegExp(`^\\s*\\[\\s*${escapeRegExp(key)}\\s*\\.\\s*${escapeRegExp(name)}\\s*[\\].]`);
+    let skipping = false;
+    const kept = doc.text.split("\n").filter((line) => {
+        if (/^\s*\[/.test(line))
+            skipping = ours.test(line);
+        return !skipping;
+    });
+    let lines = withoutSectionKey(kept, key, name);
+    if (value !== undefined && !isRecord(value))
+        lines = withSectionLine(lines, key, stringifyToml({ [name]: value }).trim());
+    if (value === undefined && isRecord(doc.value[key]) && Object.keys(doc.value[key]).length === 0)
+        lines = withoutEmptySection(doc, lines, key);
+    let text = lines.join("\n").replace(/\n*$/, "\n");
+    if (isRecord(value))
+        text += `\n${stringifyToml({ [key]: { [name]: value } })}`;
+    doc.text = text;
+    doc.edited = true;
+}
+/** The index of the `[<key>]` header line, or -1. */
+function sectionHeader(lines, key) {
+    const header = new RegExp(`^\\s*\\[\\s*${escapeRegExp(key)}\\s*\\]\\s*(#.*)?$`);
+    return lines.findIndex((line) => header.test(line));
+}
+/** The lines without a one-line `name = …` inside `[<key>]` (a multi-line value fails the readback check). */
+function withoutSectionKey(lines, key, name) {
+    const start = sectionHeader(lines, key);
+    if (start === -1)
+        return [...lines];
+    const assignment = new RegExp(`^\\s*(["']?)${escapeRegExp(name)}\\1\\s*=`);
+    let inSection = true;
+    return lines.filter((line, index) => {
+        if (index > start && /^\s*\[/.test(line))
+            inSection = false;
+        return index <= start || !inSection || !assignment.test(line);
+    });
+}
+/** The lines with `line` first under the `[<key>]` header, adding the header at the end when missing. */
+function withSectionLine(lines, key, line) {
+    const start = sectionHeader(lines, key);
+    if (start === -1)
+        return [...lines.join("\n").replace(/\n*$/, "").split("\n"), "", `[${key}]`, line];
+    return [...lines.slice(0, start + 1), line, ...lines.slice(start + 1)];
+}
+/**
+ * Drop a `[<key>]` header with nothing but blank lines under it, and the empty table from the value.
+ * A table that was only implied by its sub-tables (`[<key>.<name>]`) has no header: once the last
+ * sub-table is gone, it is gone from the value too.
+ */
+function withoutEmptySection(doc, lines, key) {
+    const start = sectionHeader(lines, key);
+    if (start === -1) {
+        const subTable = new RegExp(`^\\s*\\[\\s*${escapeRegExp(key)}\\s*\\.`);
+        if (!lines.some((line) => subTable.test(line)))
+            delete doc.value[key];
+        return [...lines];
+    }
+    const next = lines.findIndex((line, index) => index > start && /^\s*\[/.test(line));
+    const body = lines.slice(start + 1, next === -1 ? lines.length : next);
+    if (body.some((line) => line.trim() !== ""))
+        return [...lines];
+    delete doc.value[key];
+    return [...lines.slice(0, start), ...(next === -1 ? [] : lines.slice(next))];
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** The TOML edit buffer, when edited and it decodes to exactly the doc's value; undefined otherwise. */
+function tomlEditedText(doc) {
+    if (!doc.edited || typeof doc.text !== "string")
+        return undefined;
+    try {
+        return valuesEqual(parseToml(doc.text), doc.value) ? doc.text : undefined;
+    }
+    catch {
+        return undefined; // the line edit did not fit this file's layout: stringify the value instead
+    }
+}
+/** A hooks entry we own: its command (Cursor's flat entry) or one of its group's commands carries the snippet marker. */
+export function isOurHookGroup(group) {
+    if (!isRecord(group))
+        return false;
+    return isOurCommand(group) || (Array.isArray(group["hooks"]) && group["hooks"].some(isOurCommand));
+}
+function isOurCommand(hook) {
+    return isRecord(hook) && typeof hook["command"] === "string" && hook["command"].includes(SNIPPET_MARKER);
+}
+/**
+ * The value an entry should hold once ours is applied. A `hooks` event holds a list of
+ * groups shared with the user's own hooks: theirs are kept in order and ours replaced.
+ * A top-level version keeps a higher one already there.
+ */
+export function entryValue(containerKey, current, desired) {
+    // A schema version the file already declares at or above ours (Cursor's `version`) is the person's or a newer tool's: kept.
+    if (containerKey === TOP_LEVEL)
+        return typeof desired === "number" && typeof current === "number" && current >= desired ? current : desired;
+    if (containerKey !== "hooks" || !Array.isArray(desired))
+        return desired;
+    const theirs = Array.isArray(current) ? current.filter((group) => !isOurHookGroup(group)) : [];
+    return [...theirs, ...desired];
+}
+/**
+ * Delete `servers[name]` when present. No-op when the table or the entry is
+ * absent. For JSONC the deletion is a style-preserving edit.
+ */
+export function removeServer(doc, format, ref) {
+    const { serversKey, name } = ref;
+    if (doc.format !== format)
+        throw new Error(`doc format ${doc.format} does not match requested ${format}`);
+    if (format === "jsonc") {
+        const servers = getServers(doc, format, serversKey);
+        if (servers === undefined || !(name in servers))
+            return doc;
+        const text = jsoncPrepareBuffer(doc);
+        doc.text = jsoncRemoveProperty(text, serversKey, name);
+        doc.edited = true;
+        jsoncSyncValue(doc);
+        return doc;
+    }
+    const servers = getServers(doc, format, serversKey);
+    if (servers === undefined)
+        return doc;
+    delete servers[name];
+    if (format === "toml")
+        tomlEditTable(doc, { key: serversKey, name, value: undefined });
+    return doc;
+}
+/**
+ * Deep-equal over sorted keys (key order ignored, array order preserved).
+ * Returns true when `a` and `b` are semantically the same config value.
+ */
+export function valuesEqual(a, b) {
+    return canonicalize(a) === canonicalize(b);
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalize).join(",")}]`;
+    if (isRecord(value)) {
+        const keys = Object.keys(value).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k])}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "undefined";
+}
+/**
+ * Marker detection: does the doc carry a heedvane-managed entry? True when
+ * `name` is the reserved name or carries an identity marker, or when ANY
+ * entry in the servers table is marker-carrying (our entry may live under a
+ * user-chosen name). False when the doc has no heedvane entry.
+ */
+export function detectMarker(doc, format, ref) {
+    const { serversKey, name } = ref;
+    const servers = getServers(doc, format, serversKey);
+    if (servers === undefined)
+        return false;
+    if (Object.prototype.hasOwnProperty.call(servers, name) && isHeedvaneEntry(name, servers[name]))
+        return true;
+    return Object.keys(servers).some((k) => isHeedvaneEntry(k, servers[k]));
+}

package/dist/dispatchers/posix.d.ts

@@ -0,0 +1,32 @@
+import type { HeedGatingConfig } from "../heed-file.js";
+/**
+ * On-disk dispatcher (Task 6 recipe), and the one place that decides which sessions run the hooks
+ * (heed.yaml `gating.mode`, baked in at setup).
+ *
+ * Written by setup to ~/.heed/agent-hooks/<agent>-hook.sh — never inlined in agent
+ * configs, so policy updates rewrite only this file. Observe-only v1: every path
+ * exits 0; the agent is never blocked and never sees stderr noise.
+ *
+ * Spool fallback (Orca's spool_hook_event): appends one JSON line to
+ * <heed root>/spool/pane-<key>.jsonl, beside endpoint.env (HEED_AGENT_HOOK_ENDPOINT, else
+ * $HEED_AGENT_HOOK_ROOT or ~/.heed), 5 MB cap per pane file, 7-day TTL via
+ * `find -mtime`, 0600 perms, JSON-escaped envelope carrying
+ * paneKey/tabId/worktreeId/launchToken/source/receivedAt/payload.
+ *
+ * Live path: curl POST to http://127.0.0.1:$HEED_AGENT_HOOK_PORT/hook/<agent> with
+ * X-Heed-Agent-Hook-Token and X-Heed-Hook-Version: 1, 0.5s connect / 0.8s max, falling back to spool
+ * on any failure. The listener answers from this machine alone; only a session start waits (2s max)
+ * for the session's one fetch of the steering policy.
+ */
+export interface DispatcherOptions {
+    /** heed.yaml `heedvane.skills.whenUnknown: deny`: with no listener to check it, deny a skill use. */
+    denySkillsWhenUnchecked?: boolean;
+    /** heed.yaml `gating.mode`: `pane` (the default) runs the hooks only in sessions launched with
+     *  HEED_SESSION set; `always` runs them in every session. */
+    gating?: HeedGatingConfig["mode"];
+}
+export declare function dispatcherScript(agentId: string, options?: DispatcherOptions): string;
+/** The on-disk dispatcher directory under the heed root. */
+export declare function agentHooksDir(home: string): string;
+/** Write (or update) the dispatcher script for one agent. Idempotent, mode 0700. */
+export declare function writeDispatcherScript(home: string, agent: string, options?: DispatcherOptions): Promise<void>;