heedvane 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,544 @@
+#!/usr/bin/env node
+/**
+ * heedvane-hook — command routing: init | setup | doctor | uninstall |
+ * listener | status | mcp. Plain argv parsing (no commander); all state
+ * mutations flow through plan → apply; --dry-run writes nothing.
+ */
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { supportedClients } from "./clients/definitions.js";
+import { installHermesPlugin } from "./clients/hermes-plugin.js";
+import { applyEntry } from "./apply.js";
+import { DEFAULT_HEED_YAML_TEMPLATE, loadHeedFile, loadHeedFileAt, withServerUrl } from "./heed-file.js";
+import { planActions, desiredEntriesFor, isClientDetected } from "./plan.js";
+import { appliedFailed, renderApplied, renderDetection, renderPlan, wouldInstallSummary } from "./render.js";
+import { runDoctor } from "./doctor.js";
+import { installSkill } from "./skill/bundle.js";
+import { canonicalSkillFiles, skillDigest } from "./skill/content.js";
+import { emptyState, readState, writeStateAtomic } from "./state.js";
+import { writeDispatcherScript } from "./dispatchers/posix.js";
+import { removeDeferredHookGroups, removeStaleHookGroups, uninstall } from "./uninstall.js";
+import { statusText, runMcpStdio } from "./mcp-server.js";
+import { errorMessage } from "./guards.js";
+import { ensureEndpoint } from "./listener/endpoint.js";
+import { serveHooks } from "./listener/serve.js";
+import { cmdAuth, cmdLogin, cmdSkills } from "./commands/heedvane.js";
+import { cmdMemory } from "./commands/memory.js";
+import { backendAt } from "./backend/credentials.js";
+import { readLogin } from "./backend/login.js";
+const USAGE = `  heedvane-hook — cross-agent steering, guardrails & analysis
+
+  Usage: npx heedvane <command> [flags]   (installed: heedvane <command>)
+
+  Commands:
+    connect         one-step setup: write ~/.heed/heed.yaml, configure detected CLI & GUI agents, and sign in
+    init            write ~/.heed/heed.yaml (if missing), plan, apply
+    setup           plan + apply from an existing heed.yaml
+    doctor          scoped, remediation-carrying health check
+    uninstall       marker-verified removal (never touches heed.yaml)
+    listener        listener controls (start): answers hooks with skill checks, steering and memory
+    login           sign in to Heedvane in the browser (~/.heed/login.json, 0600; refreshed automatically)
+    auth org        CI/headless: store an organization API key read from stdin (~/.heed/credentials.json, 0600)
+    skills sync     install the organization's approved skills and cache the list hooks enforce
+    memory list|show|search   browse this repository's team memory (a folder, one memory, or a question)
+    status          quick state summary
+    mcp             run the MCP stdio server (what agents register)
+
+  Flags: --dry-run --yes --json --agent <id> (repeatable) --client <id> --purge-config --project
+         --server <url> (connect/init: the Heedvane app to use, saved as heedvane.url; --url also works)
+         --org <id> (connect/init: the organization the sign-in must belong to)`;
+function resolveHome(env) {
+    return env.HEED_HOME ?? homedir();
+}
+/** Repeated flag values, comma-split: `--agent a,b` and `--agent a --agent b` both feed the list. */
+function parseRepeatedFlag(args, flag) {
+    const values = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === flag) {
+            values.push(...(args[i + 1] ?? "").split(",").filter(Boolean));
+            i += 1;
+        }
+    }
+    return values;
+}
+/** The value after `name` in the raw arguments, if the flag is there. */
+function flagValue(args, name) {
+    const at = args.indexOf(name);
+    return at < 0 ? undefined : args[at + 1];
+}
+/** Positional (non-flag) arguments, skipping the values of the repeatable flags. */
+function positionalArgs(args, repeatableFlags) {
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        if (repeatableFlags.includes(args[i])) {
+            i += 1; // skip the value
+            continue;
+        }
+        if (!args[i].startsWith("--"))
+            positional.push(args[i]);
+    }
+    return positional;
+}
+/** The parsed argv: boolean flags, repeatable flag values, and positional command words. */
+function parseInvocation(args) {
+    return {
+        flags: {
+            dryRun: args.includes("--dry-run"),
+            yes: args.includes("--yes"),
+            json: args.includes("--json"),
+            purge: args.includes("--purge-config"),
+        },
+        agents: parseRepeatedFlag(args, "--agent"),
+        clients: parseRepeatedFlag(args, "--client"),
+        server: flagValue(args, "--server") ?? flagValue(args, "--url"),
+        org: flagValue(args, "--org"),
+        positional: positionalArgs(args, ["--agent", "--client", "--folder", "--offset", "--url", "--server", "--org", "--token"]),
+    };
+}
+async function main(argv, opts = {}) {
+    const ctx = commandContext(argv, opts);
+    const command = ctx.positional[0];
+    if (!command || command === "help" || command === "--help") {
+        ctx.out(USAGE);
+        return command ? 0 : 2;
+    }
+    return routeCommand(command, ctx);
+}
+function commandContext(argv, opts) {
+    const env = opts.env ?? process.env;
+    const args = [...argv];
+    return {
+        ...parseInvocation(args),
+        home: resolveHome(env),
+        env,
+        out: opts.write ?? ((line) => console.log(line)),
+        args,
+        readStdin: opts.readStdin ?? readProcessStdin,
+        openBrowser: opts.openBrowser ?? openSystemBrowser,
+        interactive: opts.interactive ?? (process.stdin.isTTY === true && process.stdout.isTTY === true),
+        cwd: opts.cwd ?? process.cwd(),
+    };
+}
+async function routeCommand(command, ctx) {
+    switch (command) {
+        case "connect":
+            return cmdInit({ ...ctx, flags: { ...ctx.flags, yes: true } });
+        case "init":
+            return cmdInit(ctx);
+        case "setup":
+            return cmdSetup(ctx);
+        case "doctor":
+            return cmdDoctor(ctx);
+        case "uninstall":
+            return cmdUninstall({ home: ctx.home, env: ctx.env, out: ctx.out, agents: ctx.agents, purge: ctx.flags.purge });
+        default:
+            return routeServiceCommand(command, ctx);
+    }
+}
+async function routeServiceCommand(command, ctx) {
+    switch (command) {
+        case "status": {
+            ctx.out(await statusText());
+            return 0;
+        }
+        case "mcp": {
+            runMcpStdio({ write: (line) => ctx.out(line) });
+            return 0;
+        }
+        case "listener": {
+            return cmdListener({ home: ctx.home, out: ctx.out, rest: ctx.args.slice(ctx.args.indexOf("listener") + 1) });
+        }
+        case "login":
+            return cmdLogin(backendCommandContext(ctx));
+        case "auth":
+        case "skills":
+            return (command === "auth" ? cmdAuth : cmdSkills)(backendCommandContext(ctx));
+        case "memory":
+            return cmdMemory({ home: ctx.home, out: ctx.out, words: ctx.positional.slice(1), flag: (name) => flagValue(ctx.args, name), cwd: ctx.cwd });
+        default:
+            ctx.out(`  ✗ unknown command: ${command}`);
+            ctx.out(USAGE);
+            return 2;
+    }
+}
+function banner(out) {
+    out("  Heedvane Agent Hooks — cross-agent steering, guardrails & analysis");
+    out("");
+}
+function detectionRows(home, env) {
+    return supportedClients({ home, platform: platform(), env }).map((client) => ({
+        client,
+        detected: isClientDetected(client),
+        markerRel: client.markerPath.replace(home, "~"),
+    }));
+}
+function loadOrTemplate(home) {
+    const path = join(home, ".heed", "heed.yaml");
+    if (!existsSync(path))
+        return { heedFile: loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE), existed: false };
+    try {
+        return { heedFile: loadHeedFileAt(path), existed: true };
+    }
+    catch (err) {
+        return { heedFile: loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE), existed: true, error: errorMessage(err) };
+    }
+}
+function planFor(plan) {
+    const effective = plan.agents.length > 0 ? { ...plan.heedFile, agents: [...plan.agents] } : plan.heedFile;
+    return planActions({ home: plan.home, platform: platform(), env: plan.env, heedFile: effective, forced: plan.agents, skillDigest: skillDigest(canonicalSkillFiles()) });
+}
+async function cmdInit(ctx) {
+    const { home, env, out, flags, agents } = ctx;
+    banner(out);
+    const rows = detectionRows(home, env);
+    for (const line of renderDetection(rows))
+        out(line);
+    const loaded = loadOrTemplate(home);
+    if (loaded.error) {
+        out("");
+        out(`  ✗ ~/.heed/heed.yaml does not parse: ${loaded.error}`);
+        out(`    remediation: fix or remove it, then run npx heedvane init`);
+        return 1;
+    }
+    let serverEdit;
+    try {
+        serverEdit = ctx.server === undefined ? null : withServer(home, loaded, ctx.server);
+    }
+    catch (err) {
+        out("");
+        out(`  ✗ --server ${ctx.server} cannot be used: ${errorMessage(err)}`);
+        return 1;
+    }
+    const { heedFile, existed } = serverEdit ?? loaded;
+    const actions = planFor({ home, env, heedFile, agents });
+    // Plain init (no --yes, no --dry-run): show the plan summary, write nothing.
+    if (!flags.yes && !flags.dryRun) {
+        out("");
+        out(wouldInstallSummary(actions));
+        out("  Re-run with --yes to apply, or --dry-run for the full file-by-file plan.");
+        return 0;
+    }
+    if (flags.dryRun) {
+        out("");
+        for (const line of renderPlan(actions))
+            out(line);
+        out("");
+        out(wouldInstallSummary(actions));
+        if (flags.json)
+            outJson(out, { status: "planned", plannedActions: actions, appliedActions: [] });
+        return 0; // zero writes — the fixture home is untouched
+    }
+    // --yes: first non-dry run has approval; proceed to write.
+    return applyAndReport(ctx, { heedFile, agents, existed, ...(serverEdit === null ? {} : { text: serverEdit.text }) });
+}
+/** heed.yaml (or the template) with `--server` as `heedvane.url`; null when it already names that server. Throws on an unusable URL. */
+function withServer(home, loaded, server) {
+    const current = loaded.existed ? readFileSync(join(home, ".heed", "heed.yaml"), "utf8") : DEFAULT_HEED_YAML_TEMPLATE;
+    const text = withServerUrl(current, server);
+    const heedFile = loadHeedFile(text);
+    if (loaded.existed && heedFile.heedvane.url === loaded.heedFile.heedvane.url)
+        return null;
+    return { heedFile, existed: loaded.existed, text };
+}
+async function applyAndReport(ctx, spec) {
+    const { home, env, out, flags } = ctx;
+    const { heedFile, agents } = spec;
+    // The control file comes first (mock order): "✓ Wrote ~/.heed/heed.yaml".
+    writeControlFile(ctx, spec);
+    const actions = planFor({ home, env, heedFile, agents });
+    const dispatcher = {
+        denySkillsWhenUnchecked: heedFile.heedvane.skills.enforce && heedFile.heedvane.skills.whenUnknown === "deny",
+        gating: heedFile.gating.mode,
+    };
+    const applied = await applyPlan(actions, { home, env, out, dispatcher });
+    // The listener port and token every dispatcher reads; kept once issued.
+    await ensureEndpoint(join(home, ".heed"));
+    for (const line of renderApplied(applied))
+        out(line);
+    // Machine state: CLI-owned; preserve an existing endpoint.
+    const root = join(home, ".heed");
+    const existing = await readState(root);
+    const state = existing ?? emptyState();
+    // Record the skill only when this run installed it (or found it current).
+    const skillInstalled = applied.some((a) => a.kind === "skill" && (a.status === "installed" || a.status === "unchanged"));
+    if (skillInstalled)
+        state.skill = { version: "1", digest: skillDigest(canonicalSkillFiles()) };
+    await writeStateAtomic(root, state);
+    if (!flags.dryRun)
+        await signInIfNeeded(ctx, heedFile.heedvane.url);
+    out("");
+    out("  Next: open a new agent session and run /heedvane-status.");
+    out("  Re-run `npx heedvane doctor` after any heed.yaml edit.");
+    const failed = applied.some(appliedFailed);
+    if (flags.json)
+        outJson(out, { status: failed ? "failed" : "applied", plannedActions: actions, appliedActions: applied });
+    return failed ? 1 : 0;
+}
+/** Writes heed.yaml when it is missing, or when `--server` changed its URL. */
+function writeControlFile({ home, out }, { heedFile, existed, text }) {
+    if (existed && text === undefined)
+        return;
+    mkdirSync(join(home, ".heed"), { recursive: true, mode: 0o700 });
+    writeFileSync(join(home, ".heed", "heed.yaml"), text ?? DEFAULT_HEED_YAML_TEMPLATE, { mode: 0o600 });
+    out(existed ? `  ✓ Set heedvane.url in ~/.heed/heed.yaml to ${heedFile.heedvane.url}` : `  ✓ Wrote ~/.heed/heed.yaml (your control file — edit any time)`);
+}
+/** Without a sign-in to `url` (and to `--org`, when named), sign in now when a person is at the terminal, else say how. Never fails setup. */
+async function signInIfNeeded(ctx, url) {
+    const root = join(ctx.home, ".heed");
+    if ((await backendAt(root, url)) !== null && (await onRequestedOrg(root, ctx.org)))
+        return;
+    if (!ctx.interactive) {
+        ctx.out("  Next: sign in with `npx heedvane login` (CI and headless machines: npx heedvane auth org < key-file).");
+        return;
+    }
+    await cmdLogin({ home: ctx.home, out: ctx.out, words: [], project: false, readStdin: async () => "", openBrowser: ctx.openBrowser });
+    if (!(await onRequestedOrg(root, ctx.org))) {
+        ctx.out(`  ✗ This sign-in belongs to another organization than ${ctx.org}. Run \`npx heedvane login\` and pick that organization on the consent page.`);
+    }
+}
+/** True without `--org`; else whether the saved login was granted for that organization. */
+async function onRequestedOrg(root, org) {
+    if (org === undefined)
+        return true;
+    const saved = await readLogin(root).catch(() => null);
+    return saved?.organizationId === org;
+}
+async function cmdSetup(ctx) {
+    const { home, out } = ctx;
+    const path = join(home, ".heed", "heed.yaml");
+    if (!existsSync(path)) {
+        out("  ✗ ~/.heed/heed.yaml not found — setup compiles your control file into agent configs.");
+        out("    remediation: run npx heedvane init");
+        return 1;
+    }
+    let heedFile;
+    try {
+        heedFile = loadHeedFileAt(path, out);
+    }
+    catch (err) {
+        out(`  ✗ ~/.heed/heed.yaml does not parse: ${errorMessage(err)}`);
+        out("    remediation: fix it, then re-run npx heedvane setup");
+        return 1;
+    }
+    banner(out);
+    if (ctx.flags.dryRun) {
+        const actions = planFor({ home, env: ctx.env, heedFile, agents: ctx.agents });
+        for (const line of renderPlan(actions))
+            out(line);
+        out("");
+        out(wouldInstallSummary(actions));
+        if (ctx.flags.json)
+            outJson(out, { status: "planned", plannedActions: actions, appliedActions: [] });
+        return 0; // zero writes
+    }
+    return applyAndReport(ctx, { heedFile, agents: ctx.agents, existed: true });
+}
+/** Hermes' hooks capability rides its native plugin; installHermesPlugin owns creation and ownership checks. */
+async function applyHermesPlugin(client, ctx) {
+    const path = join(ctx.home, ".hermes", "plugins", "heedvane-hooks", "plugin.yaml");
+    const status = await installHermesPlugin(ctx.home, ctx.dispatcher.gating);
+    if (status === "skipped") {
+        return { clientId: client.id, kind: "hooks", status: "skipped", path, reason: "another plugin owns ~/.hermes/plugins/heedvane-hooks — left untouched" };
+    }
+    return { clientId: client.id, kind: "hooks", status: status === "installed" ? "create" : "unchanged", path };
+}
+/** Drop our groups under event keys this client no longer installs; a failed removal becomes the result. */
+async function withoutStaleHookGroups(client, writes, result) {
+    let worst = result;
+    for (const { target, containerKey } of writes) {
+        if (containerKey !== "hooks")
+            continue;
+        for (const item of await removeStaleHookGroups(client, target)) {
+            if (item.status === "failed")
+                return { status: "failed", path: item.path, reason: item.detail };
+            if (worst.status === "unchanged")
+                worst = { status: "update", path: item.path };
+        }
+    }
+    return worst;
+}
+/** Patch every desired entry into the client's config files, then refresh the dispatcher script. */
+async function applyConfigEntries(action, client, ctx) {
+    const desireds = desiredEntriesFor(client, action.kind === "hooks" ? "hooks" : "mcp", { home: ctx.home, env: ctx.env });
+    // One write per file and container: every hook event lands (and is backed up) together.
+    const writes = new Map();
+    for (const d of desireds) {
+        const key = `${d.path}\0${d.containerKey}`;
+        const write = writes.get(key) ?? { target: { path: d.path, format: d.format }, containerKey: d.containerKey, entries: {} };
+        write.entries[d.entryName] = d.entry;
+        writes.set(key, write);
+    }
+    let worst = { status: "unchanged", path: action.path };
+    for (const { target, containerKey, entries } of writes.values()) {
+        const res = await applyEntry(target, { containerKey, entries });
+        if (res.status === "failed" || res.status === "invalid") {
+            worst = res;
+            break;
+        }
+        if (res.status !== "unchanged")
+            worst = res;
+    }
+    if (action.kind === "hooks" && worst.status !== "failed" && worst.status !== "invalid") {
+        worst = await withoutStaleHookGroups(client, writes.values(), worst);
+    }
+    // The dispatcher script the snippet delegates to.
+    await writeDispatcherScript(ctx.home, client.id, ctx.dispatcher);
+    return {
+        clientId: action.clientId,
+        kind: action.kind,
+        status: worst.status,
+        path: worst.path,
+        backupPath: worst.backupPath,
+        reason: worst.reason,
+        remediation: worst.remediation,
+    };
+}
+/** One planned action → one applied result. */
+async function applyAction(action, client, ctx) {
+    if (action.kind === "skill") {
+        const status = await installSkill(join(ctx.home, ".agents", "skills"));
+        return { clientId: action.clientId, kind: "skill", status, path: action.path };
+    }
+    if (client.id === "hermes" && action.kind === "hooks") {
+        return applyHermesPlugin(client, ctx);
+    }
+    return applyConfigEntries(action, client, ctx);
+}
+async function recordDeferredHookRemovals(client, results) {
+    if (!client)
+        return;
+    for (const item of await removeDeferredHookGroups(client)) {
+        if (item.status === "removed") {
+            results.push({ clientId: client.id, kind: "hooks", status: "update", path: item.path });
+        }
+        else if (item.status === "failed") {
+            results.push({ clientId: client.id, kind: "hooks", status: "failed", path: item.path, reason: item.detail });
+        }
+    }
+}
+async function applyPlan(actions, ctx) {
+    const results = [];
+    const done = new Set(); // unique (kind,path) — skill is shared across clients
+    const clients = supportedClients({ home: ctx.home, platform: platform(), env: ctx.env });
+    for (const action of actions) {
+        const client = clients.find((c) => c.id === action.clientId);
+        if (action.kind === "skip") {
+            await recordDeferredHookRemovals(client, results);
+            results.push({ clientId: action.clientId, kind: "skip", status: "skipped", path: action.path, reason: action.reason });
+            continue;
+        }
+        const key = `${action.kind}:${action.path}`;
+        if (done.has(key))
+            continue;
+        done.add(key);
+        if (!client)
+            continue;
+        results.push(await applyAction(action, client, ctx));
+    }
+    return results;
+}
+function outJson(out, envelope) {
+    out(JSON.stringify(envelope));
+}
+// ---------------------------------------------------------------------------
+// doctor / uninstall / listener
+// ---------------------------------------------------------------------------
+/** Glyph for a doctor check line: pass, warn-only, or fail. */
+function checkGlyph(check) {
+    if (check.ok)
+        return "✓";
+    return check.warnOnly ? "·" : "✗";
+}
+async function cmdDoctor(ctx) {
+    const report = await runDoctor({ home: ctx.home, env: ctx.env, clients: ctx.clients.length > 0 ? ctx.clients : undefined, json: ctx.flags.json });
+    if (ctx.flags.json) {
+        ctx.out(JSON.stringify({ status: report.healthy ? "healthy" : "unhealthy", ...report }));
+        return report.healthy ? 0 : 1;
+    }
+    ctx.out(`  Heedvane doctor — ${report.scopedTo ? `scoped to ${report.scopedTo.join(", ")}` : "all checks"}`);
+    ctx.out("");
+    for (const check of report.checks) {
+        ctx.out(`  ${checkGlyph(check)} ${check.name}: ${check.detail}`);
+        if (check.remediation)
+            ctx.out(`      remediation: ${check.remediation}`);
+    }
+    ctx.out("");
+    ctx.out(`  ${report.healthy ? "All scoped checks pass." : "Some checks failed — see remediations above."}`);
+    return report.healthy ? 0 : 1;
+}
+/** Glyph for an uninstall item line: removed, failed, or skipped/absent. */
+function uninstallGlyph(status) {
+    if (status === "removed")
+        return "✓";
+    return status === "failed" ? "✗" : "·";
+}
+async function cmdUninstall(ctx) {
+    const items = await uninstall({ home: ctx.home, env: ctx.env, agents: ctx.agents.length > 0 ? ctx.agents : undefined, purgeConfig: ctx.purge });
+    for (const item of items) {
+        ctx.out(`  ${uninstallGlyph(item.status)} ${item.name}  ${item.path}${item.detail ? ` (${item.detail})` : ""}`);
+    }
+    ctx.out("");
+    ctx.out("  heed.yaml was left untouched (your file). Pass --purge-config to delete it too.");
+    return 0;
+}
+async function cmdListener(ctx) {
+    const sub = ctx.rest[0] ?? "";
+    if (sub !== "start") {
+        ctx.out("  usage: npx heedvane listener start");
+        ctx.out("  v1 runs the listener in the foreground; service install (launchd/systemd) is opt-in later.");
+        return sub === "" ? 2 : 1;
+    }
+    const started = await serveHooks(ctx.home, ctx.out);
+    ctx.out(`  ✓ listener on 127.0.0.1:${started.port}, ${started.replayed} spooled event(s) replayed (Ctrl-C to stop)`);
+    await new Promise((resolve) => {
+        process.on("SIGINT", () => {
+            started.server.close(() => resolve());
+        });
+    });
+    return 0;
+}
+function backendCommandContext(ctx) {
+    return { home: ctx.home, out: ctx.out, words: ctx.positional.slice(1), project: ctx.args.includes("--project"), readStdin: ctx.readStdin, openBrowser: ctx.openBrowser };
+}
+/** All of stdin as text (where `auth` reads its key). */
+/** Open `url` in the system browser; the URL is printed too, so a failure here only costs a click. */
+/**
+ * The command that opens `url` in the default browser. Windows goes through rundll32, not `cmd /c start`:
+ * cmd would cut the sign-in URL at its first `&`.
+ */
+export function browserOpener(platform, url) {
+    const openers = { darwin: ["open", [url]], win32: ["rundll32", ["url.dll,FileProtocolHandler", url]] };
+    return openers[platform] ?? ["xdg-open", [url]];
+}
+function openSystemBrowser(url) {
+    const [command, args] = browserOpener(process.platform, url);
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => undefined); // no browser opener: the printed URL is the way in
+    child.unref();
+}
+async function readProcessStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+export { main };
+// Bin entry: when executed directly (npx / ./dist/cli.js), run the CLI.
+// When imported (tests, programmatic use), main is just exported.
+import { fileURLToPath } from "node:url";
+import { argv } from "node:process";
+const invokedDirectly = (() => {
+    try {
+        return argv[1] !== undefined && realpathSync(argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+})();
+if (invokedDirectly) {
+    void main(argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}

package/dist/clients/definitions.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Declarative table of supported coding-agent clients.
+ *
+ * One source of truth for every agent `heedvane-hook` can integrate with:
+ * detection marker, config targets (path + format + purpose), capabilities,
+ * and the agent's native hook-event set. Path fragments are home-relative;
+ * {@link supportedClients} resolves them into absolute per-platform paths
+ * from a pure `{ home, platform, env }` context (no process state, so the
+ * table is trivially testable against fixture homes).
+ *
+ * This module imports nothing outside `node:path` — the package must stay
+ * standalone-publishable (no intra-monorepo imports, no Effect).
+ */
+/** Env passed to resolvers: { home, platform, env } — pure, testable. */
+export type Env = Record<string, string | undefined>;
+/** Config document dialects the package knows how to parse and patch. */
+export type ClientFormat = "json" | "toml" | "jsonc" | "opencode" | "vscode" | "yaml";
+/** Integration channels per client. `plugin-install` = Hermes-style native plugin. */
+export type Capability = "hooks" | "mcp" | "skill" | "plugin-install";
+/** What a config target is written for. Skill bundles install to the universal
+ * `~/.agents/skills/` directory and therefore carry no per-client target. */
+export type ConfigPurpose = "hooks" | "mcp" | "plugin";
+/** Platforms whose path semantics the resolver implements. */
+export type Platform = NodeJS.Platform;
+/** Pure resolution context — callers pass fixture/real values explicitly. */
+export interface ResolveContext {
+    /** User home directory (fixture or real). */
+    readonly home: string;
+    /** Platform whose path semantics to apply. */
+    readonly platform: Platform;
+    /** Environment variables (only the documented override names are read). */
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+/** Root a client's directory or detection marker is resolved against. */
+export type ClientPathBase = "home" | "xdg-config" | "platform-config";
+/** Base a writable config target is resolved against. */
+export type PathBase = "client" | "home" | "platform-config";
+/** One writable config file for a client. */
+export interface ConfigTarget {
+    /** Path segments relative to {@link PathBase}. */
+    readonly segments: readonly string[];
+    readonly base: PathBase;
+    readonly format: ClientFormat;
+    readonly purpose: ConfigPurpose;
+    /** Honest caveat surfaced by plan/doctor instead of a fake write. */
+    readonly limitation?: string;
+}
+/** A resolved, absolute-path config target. */
+export interface ResolvedConfigTarget {
+    readonly path: string;
+    readonly format: ClientFormat;
+    readonly purpose: ConfigPurpose;
+    readonly limitation?: string;
+}
+/** Static (unresolved) client definition — the declarative table row. */
+export interface ClientDef {
+    readonly id: string;
+    readonly displayName: string;
+    /** Home-relative marker whose existence means "detected" (dir or file). */
+    readonly markerSegments: readonly string[];
+    readonly configs: readonly ConfigTarget[];
+    readonly capabilities: readonly Capability[];
+    /** The agent's native hook events. Empty = no native hooks. */
+    readonly events: readonly string[];
+    /** Root key MCP server entries are written under for this dialect. */
+    readonly mcpServersKey: string;
+    /** Directory base used for marker + `client`-base config targets. */
+    readonly base: ClientPathBase;
+    /** App name inside the per-platform config dir (base `platform-config`). */
+    readonly platformConfigAppName?: string;
+    /** Vendor env var that replaces the client directory itself. */
+    readonly homeOverrideEnv?: string;
+    /** Base for the marker when it differs from {@link ClientDef.base}. */
+    readonly markerBase?: ClientPathBase;
+    /** Honest capability caveat (e.g. Warp's hookless MCP-only story). */
+    readonly limitation?: string;
+    /** Mechanism note that is not a limitation (e.g. Hermes plugin install). */
+    readonly notes?: string;
+    /** How the hooks file holds one hook: Claude Code's `{ matcher, hooks: [...] }` group (default) or a bare `{ command }`. */
+    readonly hookEntries?: HookEntryShape;
+    /** A schema version the hooks file must declare at its top level (`version`). */
+    readonly hooksVersion?: number;
+    /** Another client whose installed hooks this one also runs; when both are managed, only that client's are installed. */
+    readonly runsHooksOf?: string;
+    /** Additional detection markers (e.g. GUI ADE app-support directory when CLI and GUI share configs). */
+    readonly altMarkers?: readonly {
+        readonly segments: readonly string[];
+        readonly base: ClientPathBase;
+    }[];
+}
+/** How a hooks file holds one hook command. */
+export type HookEntryShape = "group" | "flat";
+/** A fully resolved client: absolute marker + config paths for one platform. */
+export interface ResolvedClient {
+    readonly id: string;
+    readonly displayName: string;
+    readonly markerPath: string;
+    readonly altMarkerPaths?: readonly string[];
+    readonly configs: readonly ResolvedConfigTarget[];
+    readonly capabilities: readonly Capability[];
+    readonly events: readonly string[];
+    readonly mcpServersKey: string;
+    readonly limitation?: string;
+    readonly notes?: string;
+    readonly hookEntries?: HookEntryShape;
+    readonly hooksVersion?: number;
+    readonly runsHooksOf?: string;
+}
+/**
+ * Resolve every client definition into absolute marker/config paths for the
+ * given context. Pure: reads only `ctx` — never `process.env`, `os`, or disk.
+ */
+export declare function supportedClients(ctx: ResolveContext): ResolvedClient[];