heedvane 0.0.0-stage → 0.2.0

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[];

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 {};