heedvane 0.0.0-stage → 0.2.0

package/dist/uninstall.js

@@ -0,0 +1,159 @@
+/**
+ * `npx heedvane uninstall` — marker-verified removal. Only entries whose
+ * serialized form carries our identity are removed; everything else is left
+ * byte-identical. heed.yaml is NEVER touched (the user's file) unless
+ * --purge-config is passed, and even then it is deleted, not rewritten.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { supportedClients } from "./clients/definitions.js";
+import { hermesPluginOwned } from "./clients/hermes-plugin.js";
+import { applyEntry } from "./apply.js";
+import { isOurHookGroup, parseDoc } from "./config-doc.js";
+import { isHeedvaneEntry } from "./mcp.js";
+import { hooksTarget, isClientDetected } from "./plan.js";
+import { skillInstallDir } from "./skill/bundle.js";
+import { statePath } from "./state.js";
+import { unlinkOptional } from "./best-effort.js";
+/** Hook events carrying one of our groups, with the user's own groups that must survive. */
+function ourHookEvents(doc) {
+    const hooks = doc["hooks"];
+    if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks))
+        return [];
+    return Object.entries(hooks)
+        .filter(([, groups]) => Array.isArray(groups) && groups.some(isOurHookGroup))
+        .map(([event, groups]) => ({ event, theirs: groups.filter((group) => !isOurHookGroup(group)) }));
+}
+function ourMcpEntryNames(doc, containerKeys) {
+    const names = [];
+    for (const key of containerKeys) {
+        const c = doc[key];
+        if (c === null || typeof c !== "object" || Array.isArray(c))
+            continue;
+        for (const [k, v] of Object.entries(c)) {
+            if (isHeedvaneEntry(k, v))
+                names.push(`${key}::${k}`);
+        }
+    }
+    return names;
+}
+/** The doc's parsed value, or null when the config is absent or unparseable — nothing marker-verified to remove. */
+function parseClientDoc(path, format) {
+    try {
+        return parseDoc(readFileSync(path, "utf8"), format).value;
+    }
+    catch {
+        return null; // absent or unparseable — nothing marker-verified to remove
+    }
+}
+/**
+ * Remove our hook groups from every event of one parsed config except those in `keep`, leaving the
+ * user's own groups. Setup passes the events it installs, so a key an earlier version wrote under a
+ * name the harness skips (Gemini's and Cursor's snake_case keys) does not linger.
+ */
+async function removeOurHookGroups(client, target, scope) {
+    const items = [];
+    for (const { event, theirs } of ourHookEvents(scope.doc)) {
+        if (scope.keep.has(event))
+            continue;
+        // Writing no groups of ours keeps the user's own (entryValue merges); drop the key only when ours was all it held.
+        const res = theirs.length > 0
+            ? await applyEntry(target, { containerKey: "hooks", entries: { [event]: [] } })
+            : await applyEntry(target, { containerKey: "hooks", remove: event });
+        items.push({ clientId: client.id, name: `${event} hook`, path: target.path, status: res.status === "update" ? "removed" : "failed", detail: res.reason });
+    }
+    return items;
+}
+/** Setup's half: our hook groups under any event this client no longer installs, removed from its hooks file. */
+export async function removeStaleHookGroups(client, target) {
+    const doc = parseClientDoc(target.path, target.format);
+    return doc === null ? [] : removeOurHookGroups(client, target, { doc, keep: new Set(client.events) });
+}
+/** When hooksDeferredTo skips a client whose hooks an earlier run installed, remove our hook groups so events do not fire twice. */
+export async function removeDeferredHookGroups(client) {
+    const target = hooksTarget(client);
+    if (target === undefined)
+        return [];
+    const doc = parseClientDoc(target.path, target.format);
+    return doc === null ? [] : removeOurHookGroups(client, target, { doc, keep: new Set() });
+}
+/** Remove every marker-verified entry of one config file; one item per removal. */
+async function removeMarkedEntries(client, target, doc) {
+    // Both kinds can live in the same file (claude settings.json carries
+    // hooks AND mcpServers) — remove ours from every container.
+    const items = await removeOurHookGroups(client, target, { doc, keep: new Set() });
+    for (const qualified of ourMcpEntryNames(doc, [client.mcpServersKey, "mcp_servers", "mcp"])) {
+        const [containerKey, entryName] = qualified.split("::");
+        const res = await applyEntry(target, { containerKey, remove: entryName });
+        items.push({ clientId: client.id, name: `MCP ${entryName}`, path: target.path, status: res.status === "update" ? "removed" : "failed", detail: res.reason });
+    }
+    return items;
+}
+/** One non-hermes client's config files: parse each and remove our marked entries. */
+async function uninstallClientConfigs(client, items) {
+    for (const target of client.configs) {
+        if (target.format === "yaml")
+            continue;
+        const doc = parseClientDoc(target.path, target.format);
+        if (doc === null)
+            continue;
+        items.push(...(await removeMarkedEntries(client, { path: target.path, format: target.format }, doc)));
+    }
+}
+export async function uninstall(input) {
+    const { home, env } = input;
+    const items = [];
+    const scope = input.agents && input.agents.length > 0 ? new Set(input.agents) : null;
+    for (const client of supportedClients({ home, platform: process.platform, env })) {
+        if (scope && !scope.has(client.id))
+            continue;
+        if (!input.agents || input.agents.length === 0) {
+            // Default scope: detected clients only. Explicit list may force.
+            if (!existsMarker(client))
+                continue;
+        }
+        if (client.id !== "hermes") {
+            await uninstallClientConfigs(client, items);
+        }
+        else {
+            items.push(await uninstallHermesPlugin(home));
+        }
+        // Agent-hook dispatcher scripts owned by this client.
+        const script = join(home, ".heed", "agent-hooks", `${client.id}-hook.sh`);
+        await unlinkOptional(script);
+    }
+    // Skill dir + machine state (never heed.yaml) are shared by every agent: a scoped uninstall keeps them.
+    items.push(...(await removeSharedFiles(home, scope !== null)));
+    if (input.purgeConfig) {
+        await unlinkOptional(join(home, ".heed", "heed.yaml"));
+        items.push({ clientId: "*", name: "heed.yaml (purged)", path: join(home, ".heed", "heed.yaml"), status: "removed" });
+    }
+    return items;
+}
+/** The Hermes plugin dir, removed only when its plugin.yaml declares our plugin. */
+async function uninstallHermesPlugin(home) {
+    const pluginDir = join(home, ".hermes", "plugins", "heedvane-hooks");
+    const item = { clientId: "hermes", name: "hermes plugin", path: pluginDir };
+    if (await hermesPluginOwned(home)) {
+        await rm(pluginDir, { recursive: true, force: true });
+        return { ...item, status: "removed" };
+    }
+    return existsSync(pluginDir) ? { ...item, status: "skipped", detail: "not ours — left untouched" } : { ...item, status: "absent" };
+}
+/** The skill bundle and state.json every agent shares: a scoped uninstall keeps them. */
+async function removeSharedFiles(home, scoped) {
+    const skillDir = skillInstallDir(join(home, ".agents", "skills"));
+    if (scoped) {
+        return [{ clientId: "*", name: "skill bundle and state.json", path: skillDir, status: "skipped", detail: "shared by other agents — run uninstall without --agent to remove" }];
+    }
+    await rm(skillDir, { recursive: true, force: true });
+    await unlinkOptional(statePath(join(home, ".heed")));
+    return [
+        { clientId: "*", name: "skill bundle", path: skillDir, status: "removed" },
+        { clientId: "*", name: "state.json", path: statePath(join(home, ".heed")), status: "removed" },
+    ];
+}
+function existsMarker(client) {
+    return isClientDetected(client);
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "heedvane",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Heedvane for coding agents: one command installs steering, guardrails, team memory and skill checks into Claude Code, Codex, Cursor, Gemini CLI and more.",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "heedvane": "dist/cli.js",
+    "heedvane-hook": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --import ./tests/register-ts-resolver.mjs --test \"tests/**/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
+    "build": "tsc -p tsconfig.json",
+    "prepack": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "jsonc-parser": "^3.3.1",
+    "smol-toml": "^1.9.1",
+    "write-file-atomic": "^5.0.1",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/write-file-atomic": "^4.0.3",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/heedvane-hooks/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: heedvane-hooks
+description: Use when a user asks about heedvane hooks status, events, or how their coding agents are monitored — reports live hook installation state and the canonical event contract.
+---
+
+# heedvane-hooks
+
+## Overview
+
+Heedvane hooks give coding agents (Claude Code, Codex, Gemini CLI, Cursor, Warp, OpenCode, Hermes) a shared steering/guardrail/analysis channel without touching their internals. Three strictly separated layers:
+
+1. **Hook contract** — a harness-neutral event taxonomy (`pre_tool_use`, `post_tool_use`, …), one JSON envelope, one normalizer. See `references/events.md`.
+2. **Per-agent adapters** — native hook config injection where the harness has hooks (Claude, Codex, Gemini, Cursor); MCP registration as the universal fallback (Warp has no native hooks — policy arrives via MCP); an honest skip where neither exists.
+3. **Setup mechanism** — `heedvane-hook` CLI: `init` / `setup` / `doctor` / `uninstall` with backup → atomic write → read-back verify. Human intent lives in `~/.heed/heed.yaml`; machine state in `~/.heed/state.json`.
+
+Which sessions run the hooks follows `heed.yaml` `gating.mode`: with `always` (the default) every session is governed, with `pane` only sessions launched with `HEED_SESSION` set. The dispatcher script (for Hermes, its plugin) decides, from the mode `setup` bakes into it, and always exits 0. Observability never blocks the agent.
+
+## When to Use
+
+- "Is my heedvane install healthy?" / "why aren't hooks firing?"
+- "What events does heedvane capture?" / "what shape is the payload?"
+- "Which of my agents are monitored?"
+- After the user edits `~/.heed/heed.yaml` and wants the change applied/verified.
+
+Do **not** use this skill to author policies — an organization's policies are defined and assigned on the Heedvane server, never in `heed.yaml`.
+
+## Checking status
+
+1. Run the doctor (scoped, exit-code-carrying):
+
+   ```sh
+   npx heedvane doctor --json
+   ```
+
+   Or unscoped plain text: `npx heedvane doctor`. Every failing check carries a `remediation` string — surface it verbatim.
+
+2. Read the control file — it is the single source of truth for intent:
+
+   ```sh
+   cat ~/.heed/heed.yaml
+   ```
+
+   `agents: auto` manages every detected agent; an explicit list filters. `install.hooks/skill/mcp` toggles channels per agent.
+
+3. **Never edit agent configs by hand.** `~/.claude/settings.json`, `~/.codex/hooks.json`, etc. are compiled outputs. Edit `heed.yaml`, then re-run:
+
+   ```sh
+   npx heedvane setup
+   ```
+
+4. Machine state (installed digests, endpoint, protocol version) is `~/.heed/state.json` — CLI-owned, never hand-edit.
+
+## Event contract summary
+
+- Canonical events (v1, snake_case): `session_start`, `session_end`, `user_prompt_submit`, `pre_tool_use`, `post_tool_use`, `post_tool_use_failure`, `permission_request`, `stop`, `stop_failure`, `subagent_start`, `subagent_stop`, `notification`, `pre_compact`. Unknown harness events pass through as `unknown_event` (never dropped).
+- Envelope: `{ "v": 1, "event", "agent", "session", "pane", "receivedAt", "payload": { … } }` — strings capped at 8 KB, nodes at 500.
+- Per-harness mapping (Claude's PascalCase `:class` names → canonical; Codex/Gemini are already snake_case) is tabled in `references/events.md`. Read that file before reasoning about any specific payload.
+
+## Steering, approved skills and memory
+
+With the listener running (`npx heedvane listener start`) and a sign-in (`npx heedvane login`; CI and headless machines: `npx heedvane auth org` with the key on stdin), the listener answers each hook with a verdict instead of only recording it:
+
+- **Steering:** every rule of the organization that matches is enforced: a tool call is denied or a stop is blocked, with the rule's message as the reason. A session's stops are blocked at most four times in a row; the next one ends the turn so the person sees why, and no later stop of that session is blocked. No hook waits on Heedvane. Command and path rules are synced to the listener at each session start and checked locally, so they hold even when Heedvane is slow or down. Heedvane judges every event in the background, and a rule it finds violated blocks the agent's next tool call or stop.
+- **Organization instructions:** the organization's non-negotiable rules are added as context at session start or with each prompt. They cannot be turned off, and the rules named with them enforce them.
+- **Approved skills:** `npx heedvane skills sync` installs the organization's approved skills into `~/.agents/skills` and `~/.claude/skills` and caches the list in `~/.heed/approved-skills.json`. Using any other skill (the Skill tool, or reading its `SKILL.md`) is denied; writing a skill is not. `heed.yaml` `heedvane.skills` sets `enforce`, `strict` (also compare file hashes) and `whenUnknown` (what to do before the first sync or while the listener is down).
+- **Private memory** (local only, never sent to Heedvane): at session start the hook adds `~/.heed/memory/MEMORY.md` (every repository) and `~/.heed/memory/<owner>/<name>.md` (this repository) as context, so every agent sees them. To save a private memory, append a short line to the right file.
+
+- **Team memory:** at session start the hook adds a table of contents of this repository's team memory (folders and titles, never the text). Browse and read it with `npx heedvane memory list [folder]`, `npx heedvane memory show <id>` and `npx heedvane memory search "<question>" [--folder <folder>]`.
+
+Backend failures never block the agent: without Heedvane's answer, the locally checked rules decide, and every enforcement is reported to Heedvane.
+
+## Common Pitfalls
+
+- **Do not rewrite `~/.claude/settings.json` (or any agent config) manually while hooks are installed.** Hand edits fight the compiler; the next `setup` will either back up your change or report the file invalid. Edit `heed.yaml` instead.
+- **Spool files are diagnostics, not policy.** When the listener is unreachable, hook payloads spool to `~/.heed/spool/` (5 MB cap, 7-day TTL) so nothing is lost — but spool presence is not enforcement, and clearing it loses observability history only.
+- Warp gets policies **via MCP only** — that is the designed happy path, not an error to fix.
+- If `doctor` reports `invalid` on a config, the file does not parse; heedvane never overwrites malformed configs. Fix or move the file aside yourself, then re-run.
+- Re-running `setup` after no changes reports "already current" — idempotence is a feature, not a stalled run.
+
+## Verification Checklist
+
+- [ ] `npx heedvane doctor` exits 0 and every check line shows ok
+- [ ] `~/.heed/heed.yaml` parses and says `schemaVersion: v1`
+- [ ] `~/.heed/state.json` skill digest matches the installed skill
+- [ ] A new agent session (launched with `HEED_SESSION` set, or any session with `gating.mode: always`) produces events in the listener log or `~/.heed/spool/`
+- [ ] Backups exist: `<config>.heedvane.backup` next to every patched config
+- [ ] `/heedvane-status` in a fresh agent session reports the same agents as `doctor`

package/skills/heedvane-hooks/references/events.md

@@ -0,0 +1,69 @@
+# Heedvane event contract (v1)
+
+Harness-neutral taxonomy + JSON envelope. One normalizer maps every
+per-source payload into the canonical shape; unknown events pass through
+as `unknown_event` rather than being dropped.
+
+## Canonical events (v1)
+
+| Event | Fires when |
+| --- | --- |
+| `session_start` | A managed agent session begins |
+| `session_end` | The session ends (clean or crash) |
+| `user_prompt_submit` | The user submits a prompt |
+| `pre_tool_use` | Before a tool call executes |
+| `post_tool_use` | After a tool call returns |
+| `post_tool_use_failure` | A tool call raises/errors |
+| `permission_request` | The agent asks for approval |
+| `stop` | The agent turn completes |
+| `stop_failure` | The turn aborts with an error |
+| `subagent_start` | A subagent/task tool spawns |
+| `subagent_stop` | The subagent finishes |
+| `notification` | Harness notification (idle, attention, updates) |
+| `pre_compact` | Before the harness compacts the conversation |
+
+## Envelope
+
+```json
+{
+  "v": 1,
+  "event": "pre_tool_use",
+  "agent": "claude",
+  "session": "sess_01HQ…",
+  "pane": "iterm:tab-3",
+  "receivedAt": "2026-10-10T12:00:00.000Z",
+  "payload": { "tool": "Bash", "input": { "command": "ls" } }
+}
+```
+
+Caps (Orca's numbers): strings ≤ 8 KB, ≤ 500 nodes per payload; oversized
+fields are truncated at ingest, never dropped.
+
+## Per-harness mapping
+
+| Canonical | Claude Code / Codex | Gemini CLI | Cursor | Hermes plugin |
+| --- | --- | --- | --- | --- |
+| `session_start` | `SessionStart` | `SessionStart` | `sessionStart` | `on_session_start` |
+| `session_end` | `SessionEnd` | `SessionEnd` | `sessionEnd` | `on_session_finalize` |
+| `user_prompt_submit` | `UserPromptSubmit` | `BeforeAgent` | `beforeSubmitPrompt` | `pre_llm_call` |
+| `pre_tool_use` | `PreToolUse` | `BeforeTool` | `preToolUse` | `pre_tool_call` |
+| `post_tool_use` | `PostToolUse` | `AfterTool` | `postToolUse` | `post_tool_call` |
+| `post_tool_use_failure` | `PostToolUseFailure` | — | — | — |
+| `permission_request` | `PermissionRequest` | — | — | `pre_approval_request` |
+| `stop` | `Stop` | `AfterAgent` | `stop` | — |
+| `stop_failure` | `StopFailure` | — | — | — |
+| `subagent_start` | `SubagentStart` | — | — | — |
+| `subagent_stop` | `SubagentStop` | — | `subagentStop` | — |
+| `notification` | `Notification` | `Notification` | — | — |
+| `pre_compact` | `PreCompact` | `PreCompress` | — | — |
+
+Hermes' `on_session_end` fires once per turn despite its name, so it passes
+through as `unknown_event`, as does `post_approval_response`. Cursor's session
+is its `conversation_id`.
+
+Warp emits no native events at all — it has no hooks. Policy for Warp
+arrives via MCP tool calls; nothing in this table applies to it.
+
+Payload keys per source keep their harness names inside `payload` (e.g.
+Claude's `tool_input`, Codex's `tool_input`) after normalization of the
+envelope itself; the normalizer never invents fields.