heedvane 0.0.0-stage → 0.1.0

package/dist/clients/definitions.js

@@ -0,0 +1,427 @@
+/**
+ * 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).
+ */
+import { posix, win32 } from "node:path";
+// Single owner of the canonical taxonomy: src/events/contract.ts.
+import { CANONICAL_EVENTS } from "../events/contract.js";
+/** Harness-neutral canonical taxonomy (v1). Native sets normalize into this.
+ *  Single owner: src/events/contract.ts — re-exported here for the table. */
+/** Claude Code's 14 native hook events (verified against its hook contract). */
+const CLAUDE_EVENTS = [
+    "SessionStart",
+    "SessionEnd",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PermissionRequest",
+    "Stop",
+    "StopFailure",
+    "SubagentStart",
+    "SubagentStop",
+    "TeammateIdle",
+    "PreCompact",
+    "PostCompact",
+];
+/** Codex's 11 native hook events (Claude's set minus TeammateIdle/PostCompact). */
+const CODEX_EVENTS = [
+    "SessionStart",
+    "SessionEnd",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PermissionRequest",
+    "Stop",
+    "StopFailure",
+    "SubagentStart",
+    "SubagentStop",
+];
+/** Gemini CLI's own hook event names; its registry skips any other key (https://geminicli.com/docs/hooks/reference/). */
+const GEMINI_EVENTS = [
+    "SessionStart",
+    "SessionEnd",
+    "BeforeAgent",
+    "AfterAgent",
+    "BeforeTool",
+    "AfterTool",
+    "PreCompress",
+    "Notification",
+];
+/** Cursor's camelCase hook event names (https://cursor.com/docs/hooks). */
+const CURSOR_EVENTS = [
+    "sessionStart",
+    "sessionEnd",
+    "beforeSubmitPrompt",
+    "preToolUse",
+    "postToolUse",
+    "stop",
+    "subagentStop",
+];
+/** Kimi Code documents Claude-style PascalCase hook events in config.toml. */
+const KIMI_EVENTS = ["PreToolUse", "PostToolUse"];
+const settings = (segments, purpose) => ({
+    segments,
+    base: "client",
+    format: "json",
+    purpose,
+});
+/**
+ * The declarative table. First-class rows (claude, codex, gemini, cursor,
+ * warp, opencode, hermes) are behavior-tested; the remaining rows ride the
+ * same resolver and get snapshot tests only.
+ */
+const SUPPORTED_CLIENTS = [
+    {
+        id: "claude",
+        displayName: "Claude Code",
+        markerSegments: [".claude"],
+        base: "home",
+        platformConfigAppName: "Claude",
+        altMarkers: [{ segments: [], base: "platform-config" }],
+        homeOverrideEnv: "CLAUDE_CONFIG_DIR",
+        configs: [
+            settings(["settings.json"], "hooks"),
+            { segments: [".claude.json"], base: "home", format: "json", purpose: "mcp" },
+        ],
+        capabilities: ["hooks", "mcp", "skill"],
+        events: CLAUDE_EVENTS,
+        mcpServersKey: "mcpServers",
+    },
+    {
+        id: "codex",
+        displayName: "Codex",
+        markerSegments: [".codex"],
+        base: "home",
+        platformConfigAppName: "Codex",
+        altMarkers: [{ segments: [], base: "platform-config" }],
+        homeOverrideEnv: "CODEX_HOME",
+        configs: [
+            { segments: ["hooks.json"], base: "client", format: "json", purpose: "hooks" },
+            { segments: ["config.toml"], base: "client", format: "toml", purpose: "mcp" },
+        ],
+        capabilities: ["hooks", "mcp", "skill"],
+        events: CODEX_EVENTS,
+        mcpServersKey: "mcp_servers",
+    },
+    {
+        id: "gemini",
+        displayName: "Gemini CLI",
+        markerSegments: [".gemini"],
+        base: "home",
+        configs: [
+            settings(["settings.json"], "hooks"),
+            settings(["settings.json"], "mcp"),
+        ],
+        capabilities: ["hooks", "mcp", "skill"],
+        events: GEMINI_EVENTS,
+        mcpServersKey: "mcpServers",
+    },
+    {
+        id: "cursor",
+        displayName: "Cursor",
+        markerSegments: [".cursor"],
+        base: "home",
+        configs: [
+            { segments: ["hooks.json"], base: "client", format: "json", purpose: "hooks" },
+            { segments: ["mcp.json"], base: "client", format: "json", purpose: "mcp" },
+        ],
+        capabilities: ["hooks", "mcp", "skill"],
+        events: CURSOR_EVENTS,
+        mcpServersKey: "mcpServers",
+        hookEntries: "flat",
+        hooksVersion: 1,
+        // Cursor loads ~/.claude/settings.json hooks by default (https://cursor.com/docs/reference/third-party-hooks).
+        runsHooksOf: "claude",
+    },
+    {
+        id: "warp",
+        displayName: "Warp",
+        markerSegments: [".warp"],
+        base: "home",
+        configs: [
+            {
+                segments: [".mcp.json"],
+                base: "client",
+                format: "json",
+                purpose: "mcp",
+                limitation: "Warp has no native hook events (hooks unavailable); ~/.warp/.mcp.json is project-level, and user-level MCP requires explicit in-app approval of the import.",
+            },
+        ],
+        capabilities: ["mcp", "skill"],
+        events: [],
+        mcpServersKey: "mcpServers",
+        limitation: "Warp exposes no native hook events — policies ship via MCP only, and the MCP import needs explicit user approval in Warp.",
+    },
+    {
+        id: "opencode",
+        displayName: "OpenCode",
+        markerSegments: ["opencode"],
+        base: "xdg-config",
+        configs: [
+            { segments: ["opencode.json"], base: "client", format: "opencode", purpose: "hooks" },
+            { segments: ["opencode.json"], base: "client", format: "opencode", purpose: "mcp" },
+        ],
+        capabilities: ["hooks", "mcp", "skill"],
+        events: [
+            "session_start",
+            "session_end",
+            "user_prompt_submit",
+            "pre_tool_use",
+            "post_tool_use",
+            "permission_request",
+        ],
+        mcpServersKey: "mcp",
+    },
+    {
+        id: "hermes",
+        displayName: "Hermes",
+        markerSegments: [".hermes"],
+        base: "home",
+        configs: [
+            { segments: ["plugins", "heedvane-hooks"], base: "client", format: "yaml", purpose: "plugin" },
+        ],
+        capabilities: ["plugin-install", "skill"],
+        events: [
+            "on_session_start",
+            "pre_llm_call",
+            "pre_tool_call",
+            "post_tool_call",
+            "pre_approval_request",
+            "post_approval_response",
+            "on_session_end",
+            "on_session_finalize",
+        ],
+        mcpServersKey: "mcpServers",
+        notes: "Hermes integrates via a plugin install (~/.hermes/plugins/heedvane-hooks) using its native hook API — not a hooks.json/config.toml write.",
+    },
+    {
+        // --- Snapshot-tested rows (same table, same resolver, no bespoke tests) ---
+        id: "qwen-code",
+        displayName: "Qwen Code",
+        markerSegments: [".qwen"],
+        base: "home",
+        configs: [
+            settings(["settings.json"], "hooks"),
+            settings(["settings.json"], "mcp"),
+        ],
+        capabilities: ["hooks", "mcp", "skill"],
+        events: CANONICAL_EVENTS,
+        mcpServersKey: "mcpServers",
+    },
+    {
+        id: "kimi",
+        displayName: "Kimi Code",
+        markerSegments: [".kimi-code"],
+        base: "home",
+        homeOverrideEnv: "KIMI_CODE_HOME",
+        configs: [
+            { segments: ["config.toml"], base: "client", format: "toml", purpose: "hooks" },
+            { segments: ["config.toml"], base: "client", format: "toml", purpose: "mcp" },
+        ],
+        capabilities: ["hooks", "mcp", "skill"],
+        events: KIMI_EVENTS,
+        mcpServersKey: "mcp_servers",
+    },
+    {
+        id: "droid",
+        displayName: "Droid (Factory)",
+        markerSegments: [".factory"],
+        base: "home",
+        configs: [
+            { segments: ["mcp.json"], base: "client", format: "json", purpose: "mcp" },
+        ],
+        capabilities: ["mcp", "skill"],
+        events: [],
+        mcpServersKey: "mcpServers",
+    },
+    {
+        id: "antigravity",
+        displayName: "Antigravity",
+        markerSegments: [".gemini", "antigravity"],
+        altMarkers: [{ segments: [".gemini", "config"], base: "home" }],
+        base: "home",
+        configs: [
+            { segments: [".gemini", "config", "hooks.json"], base: "home", format: "json", purpose: "hooks" },
+            { segments: ["mcp_config.json"], base: "client", format: "json", purpose: "mcp" },
+        ],
+        capabilities: ["hooks", "mcp", "skill"],
+        events: CLAUDE_EVENTS,
+        mcpServersKey: "mcpServers",
+    },
+    {
+        id: "copilot_cli",
+        displayName: "GitHub Copilot CLI",
+        markerSegments: [".copilot"],
+        base: "home",
+        homeOverrideEnv: "COPILOT_HOME",
+        configs: [
+            { segments: ["mcp.json"], base: "client", format: "json", purpose: "mcp" },
+        ],
+        capabilities: ["mcp", "skill"],
+        events: [],
+        mcpServersKey: "mcpServers",
+    },
+    {
+        id: "windsurf",
+        displayName: "Windsurf",
+        markerSegments: [".codeium", "windsurf"],
+        base: "home",
+        configs: [
+            { segments: ["mcp_config.json"], base: "client", format: "json", purpose: "mcp" },
+        ],
+        capabilities: ["mcp"],
+        events: [],
+        mcpServersKey: "mcpServers",
+    },
+    {
+        id: "vscode",
+        displayName: "VS Code",
+        markerSegments: [".vscode"],
+        markerBase: "home",
+        base: "platform-config",
+        platformConfigAppName: "Code",
+        configs: [
+            { segments: ["User", "mcp.json"], base: "client", format: "vscode", purpose: "mcp" },
+        ],
+        capabilities: ["mcp"],
+        events: [],
+        mcpServersKey: "servers",
+    },
+    {
+        id: "claude_desktop",
+        displayName: "Claude Desktop",
+        markerSegments: [],
+        base: "platform-config",
+        platformConfigAppName: "Claude",
+        configs: [
+            { segments: ["claude_desktop_config.json"], base: "client", format: "json", purpose: "mcp" },
+        ],
+        capabilities: ["mcp", "skill"],
+        events: [],
+        mcpServersKey: "mcpServers",
+    },
+];
+const pathImplFor = (platform) => (platform === "win32" ? win32 : posix);
+function xdgConfigRoot(ctx, p) {
+    const override = ctx.env["XDG_CONFIG_HOME"];
+    return override ? absoluteOrHome(override, ctx, p) : p.join(ctx.home, ".config");
+}
+function platformConfigDir(def, ctx, p) {
+    const appName = def.platformConfigAppName;
+    if (!appName)
+        throw new Error(`Client ${def.id} uses base "platform-config" without platformConfigAppName`);
+    switch (ctx.platform) {
+        case "darwin":
+            return p.join(ctx.home, "Library", "Application Support", appName);
+        case "win32": {
+            const appData = ctx.env["APPDATA"] ?? p.join(ctx.home, "AppData", "Roaming");
+            return p.join(absoluteOrHome(appData, ctx, p), appName);
+        }
+        default:
+            return p.join(xdgConfigRoot(ctx, p), appName);
+    }
+}
+/** Treat a relative env override as home-relative so resolution never throws. */
+function absoluteOrHome(value, ctx, p) {
+    return p.isAbsolute(value) ? value : p.join(ctx.home, value);
+}
+/** The client's own directory (marker + `client`-base configs resolve here). */
+function clientDir(def, ctx, p) {
+    switch (def.base) {
+        case "home": {
+            const override = def.homeOverrideEnv ? ctx.env[def.homeOverrideEnv] : undefined;
+            if (override)
+                return absoluteOrHome(override, ctx, p);
+            return p.join(ctx.home, ...def.markerSegments);
+        }
+        case "xdg-config":
+            return p.join(xdgConfigRoot(ctx, p), ...def.markerSegments);
+        case "platform-config":
+            return p.join(platformConfigDir(def, ctx, p), ...def.markerSegments);
+    }
+}
+function resolveMarkerBase(target, ctx, p) {
+    const { def, markerBase, segments } = target;
+    switch (markerBase) {
+        case "home":
+            return p.join(ctx.home, ...segments);
+        case "xdg-config":
+            return p.join(xdgConfigRoot(ctx, p), ...segments);
+        case "platform-config":
+            return p.join(platformConfigDir(def, ctx, p), ...segments);
+    }
+}
+function markerPath(def, ctx, p) {
+    const markerBase = def.markerBase ?? def.base;
+    if (markerBase === def.base)
+        return clientDir(def, ctx, p);
+    return resolveMarkerBase({ def, markerBase, segments: def.markerSegments }, ctx, p);
+}
+function resolveConfigTarget(def, target, resolve) {
+    const { ctx, p } = resolve;
+    let path;
+    switch (target.base) {
+        case "client": {
+            // When the marker lives outside the platform config dir (markerBase
+            // override), `client`-base targets resolve against the app config dir
+            // root itself, not the marker-relative client directory.
+            const base = def.base === "platform-config" && def.markerBase !== def.base
+                ? platformConfigDir(def, ctx, p)
+                : clientDir(def, ctx, p);
+            path = p.join(base, ...target.segments);
+            break;
+        }
+        case "home":
+            path = p.join(ctx.home, ...target.segments);
+            break;
+        case "platform-config":
+            path = p.join(platformConfigDir(def, ctx, p), ...target.segments);
+            break;
+    }
+    return target.limitation === undefined
+        ? { path, format: target.format, purpose: target.purpose }
+        : { path, format: target.format, purpose: target.purpose, limitation: target.limitation };
+}
+function assertSupportedPlatform(platform) {
+    if (platform !== "darwin" && platform !== "linux" && platform !== "win32") {
+        throw new Error(`Unsupported platform: ${String(platform)}`);
+    }
+}
+/**
+ * Resolve every client definition into absolute marker/config paths for the
+ * given context. Pure: reads only `ctx` — never `process.env`, `os`, or disk.
+ */
+export function supportedClients(ctx) {
+    assertSupportedPlatform(ctx.platform);
+    const p = pathImplFor(ctx.platform);
+    return SUPPORTED_CLIENTS.map((def) => ({
+        id: def.id,
+        displayName: def.displayName,
+        markerPath: markerPath(def, ctx, p),
+        ...(def.altMarkers === undefined
+            ? {}
+            : {
+                altMarkerPaths: def.altMarkers.map((m) => resolveMarkerBase({ def, markerBase: m.base, segments: m.segments }, ctx, p)),
+            }),
+        configs: def.configs.map((target) => resolveConfigTarget(def, target, { ctx, p })),
+        capabilities: def.capabilities,
+        events: def.events,
+        mcpServersKey: def.mcpServersKey,
+        ...(def.limitation === undefined ? {} : { limitation: def.limitation }),
+        ...(def.notes === undefined ? {} : { notes: def.notes }),
+        ...(def.hookEntries === undefined ? {} : { hookEntries: def.hookEntries }),
+        ...(def.hooksVersion === undefined ? {} : { hooksVersion: def.hooksVersion }),
+        ...(def.runsHooksOf === undefined ? {} : { runsHooksOf: def.runsHooksOf }),
+    }));
+}

package/dist/clients/hermes-plugin.d.ts

@@ -0,0 +1,33 @@
+import type { HeedGatingConfig } from "../heed-file.js";
+/**
+ * The hooks this plugin registers with the Hermes host. `pre_tool_call` and `pre_llm_call` are directive
+ * hooks: Hermes acts on what they return. `on_session_end` fires once per turn despite its name;
+ * `on_session_finalize` is the session's end (https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks).
+ */
+export declare const HERMES_EVENTS: readonly ["on_session_start", "pre_llm_call", "pre_tool_call", "post_tool_call", "pre_approval_request", "post_approval_response", "on_session_end", "on_session_finalize"];
+export type HermesPluginFile = {
+    relativePath: string;
+    content: string;
+};
+export type HermesPluginInstallStatus = "installed" | "skipped" | "unchanged";
+/** heed.yaml `gating.mode`, baked into the plugin at setup as the POSIX dispatcher gets it. */
+type GatingMode = HeedGatingConfig["mode"];
+/** The two files that make up the Hermes plugin, ready to install. */
+export declare function hermesPluginFiles(gating?: GatingMode): HermesPluginFile[];
+/** Does `<home>/.hermes/plugins/heedvane-hooks/plugin.yaml` declare our plugin? Uninstall removes only then. */
+export declare function hermesPluginOwned(home: string): Promise<boolean>;
+/**
+ * Install the Hermes plugin into `<home>/.hermes/plugins/heedvane-hooks/`.
+ *
+ * - "skipped"  — a foreign plugin owns the target directory. Whether Hermes is installed at all
+ *                is the planner's decision (detected, or named with `--agent`).
+ * - "unchanged" — the dir is heed-owned and every file already matches.
+ * - "installed" — files were written (fresh install or update).
+ *
+ * A heed-owned directory is one whose plugin.yaml exists and contains
+ * `name: heedvane-hooks`. Differing heed-owned files are backed up to
+ * `<file>.heedvane.backup` before being replaced. Foreign plugin.yaml files
+ * are never overwritten.
+ */
+export declare function installHermesPlugin(home: string, gating?: GatingMode): Promise<HermesPluginInstallStatus>;
+export {};