wavebrain 0.1.0 → 0.2.0

package/src/cli.mjs

@@ -3,16 +3,17 @@ import os from "node:os";
 import readline from "node:readline";
 import { Conflict, Session, hasBlock, readText } from "./files.mjs";
 import { loadState, ownedBy, saveState, statePath } from "./state.mjs";
+import { stageCapture, unstageCapture } from "./capture.mjs";
 import { KEY_ENV, allTargets, targetById, tilde } from "./targets.mjs";
 
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";
 const DEFAULT_URL = "https://getwavebrain.com/api/mcp";
 const SETUP_URL = "https://getwavebrain.com/dashboard/setup";
 
 const HELP = `wavebrain ${VERSION}: connect your AI agents to WaveBrain (https://getwavebrain.com)
 
 Usage:
-  npx wavebrain init      Pick agents and add WaveBrain to their config
+  npx wavebrain init      Pick agents and connect them to WaveBrain
   npx wavebrain remove    Undo exactly what init added
   npx wavebrain status    Show which agents are configured
 
@@ -23,15 +24,22 @@ Options:
   --key <key>             API key (or set ${KEY_ENV}). Create one at
                           ${SETUP_URL}
   --dry-run               Show what would change without writing anything
+  --no-hooks              MCP server only: skip the hooks, skill and Hermes plugin
+                          that record actions the model forgets to log
   --no-claude-permission  Don't pre-approve WaveBrain's tools in Claude Code
   -y, --yes               Don't ask for confirmation
   --url <url>             MCP server URL (default ${DEFAULT_URL})
   -h, --help, -v, --version
 
+For Claude Code, Codex, Cursor and Hermes, init also installs auto-capture: hooks that
+record deploys, pushes, releases, payments, emails and database writes even when the model
+doesn't call log_action, plus a short skill telling it when to log. Secrets are redacted
+before anything is sent. Turn capture off any time with WAVEBRAIN_HOOKS=off.
+
 Every file is backed up to <file>.bak-wavebrain before it's changed.`;
 
 export function parseArgs(argv) {
-  const o = { command: null, agents: [], key: null, dryRun: false, yes: false, claudePermission: null, url: DEFAULT_URL };
+  const o = { command: null, agents: [], key: null, dryRun: false, yes: false, claudePermission: null, url: DEFAULT_URL, hooks: true };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     const val = () => {
@@ -47,6 +55,7 @@ export function parseArgs(argv) {
     else if (a === "--dry-run") o.dryRun = true;
     else if (a === "--yes" || a === "-y") o.yes = true;
     else if (a === "--no-claude-permission") o.claudePermission = false;
+    else if (a === "--no-hooks") o.hooks = false;
     else if (a === "--claude-permission") o.claudePermission = true;
     else if (a === "-h" || a === "--help") o.command = "help";
     else if (a === "-v" || a === "--version") o.command = "version";
@@ -133,7 +142,7 @@ async function init(o, ctx, io) {
   io.out(`\n${o.dryRun ? "Dry run: nothing will be written.\n" : ""}Using key ${mask(key)} and ${o.url}\n`);
   const state = loadState(ctx);
   const session = new Session({ dryRun: o.dryRun });
-  const opts = { url: o.url, key, keyFromEnv, claudePermission };
+  const opts = { url: o.url, key, keyFromEnv, claudePermission, hooks: o.hooks };
   let failed = 0;
   const nextSteps = [];
 
@@ -168,6 +177,21 @@ async function init(o, ctx, io) {
     }
   }
 
+  // The hook runner and the key it uses, shared by every agent with auto-capture.
+  if (o.hooks && targets.some((t) => t.capture)) {
+    const results = stageCapture(ctx, session, opts);
+    const changed = results.filter((r) => r.kind !== "unchanged");
+    for (const r of results) {
+      const prev = state.records.find((x) => x.ref === r.ref);
+      state.records = state.records.filter((x) => x.ref !== r.ref);
+      state.records.push({ ref: r.ref, target: "capture", file: r.file, createdFile: prev?.createdFile ?? Boolean(r.createdFile) });
+    }
+    if (changed.length) {
+      io.out(`✓ Auto-capture`);
+      for (const r of changed) io.out(`    ${o.dryRun ? "would " + verb(r.kind) : verb(r.kind, true)} ${describe(ctx, r)}`);
+    }
+  }
+
   if (!o.dryRun) saveState(ctx, state);
   if (nextSteps.length) io.out(`\nNext:\n${nextSteps.map((s) => `  ${s}`).join("\n")}`);
   if (!o.dryRun && session.changes.some((c) => c.backup)) io.out(`\nBackups end in .bak-wavebrain. Undo with: npx wavebrain remove`);
@@ -179,11 +203,26 @@ function verb(kind, past) {
 }
 
 function describe(ctx, r) {
-  const what = r.ref.endsWith(":permission")
+  const ref = r.ref;
+  const what = ref.endsWith(":permission")
     ? " (allow mcp__wavebrain__*)"
-    : r.ref.endsWith(":env")
+    : ref.endsWith(":env")
       ? ` (${KEY_ENV})`
-      : " (wavebrain server)";
+      : ref.endsWith(":hooks")
+        ? " (auto-capture hooks)"
+        : ref.endsWith(":features")
+          ? " ([features] hooks = true)"
+          : ref.endsWith(":skill")
+            ? " (when-to-log skill)"
+            : ref.includes(":plugin:")
+              ? " (WaveBrain plugin)"
+              : ref.endsWith(":plugin-enabled")
+                ? " (plugins.enabled: wavebrain)"
+                : ref === "capture:config"
+                  ? " (API key for the hooks)"
+                  : ref.startsWith("capture:")
+                    ? " (hook runner)"
+                    : " (wavebrain server)";
   return tilde(ctx, r.file) + what;
 }
 
@@ -245,6 +284,16 @@ async function remove(o, ctx, io) {
       io.out(`! ${t.label}: ${e.message}`);
     }
   }
+  // Last agent with auto-capture gone: remove the hook runner and its key too.
+  const captureLeft = state.records.some((r) => r.target !== "capture" && targetById(ctx, r.target)?.capture);
+  if (!captureLeft && state.records.some((r) => r.target === "capture")) {
+    const results = unstageCapture(ctx, session).filter((r) => r.kind !== "unchanged");
+    if (results.length) {
+      io.out(`✓ Auto-capture`);
+      for (const r of results) io.out(`    ${o.dryRun ? "would " + verb(r.kind) : verb(r.kind, true)} ${tilde(ctx, r.file)}`);
+    }
+    state.records = state.records.filter((r) => r.target !== "capture");
+  }
   if (!o.dryRun) saveState(ctx, state);
   return 0;
 }

package/src/files.mjs

@@ -35,16 +35,29 @@ export class Session {
     const after = fn(before);
     if (after === before) return "unchanged";
     const kind = before === null ? "created" : after === null ? "deleted" : "updated";
-    const backup = before === null ? null : file + BACKUP_SUFFIX;
+    // Files that are entirely ours (in a wavebrain folder) aren't backed up: a backup of
+    // ~/.wavebrain/config.json would leave the API key behind after `remove`.
+    const ownedFile = /[\\/](\.wavebrain|wavebrain)[\\/]/.test(file);
+    const backup = before === null || ownedFile ? null : file + BACKUP_SUFFIX;
     if (!this.dryRun) {
       let mode;
       if (before !== null) {
         mode = fs.statSync(file).mode & 0o777;
-        fs.copyFileSync(file, backup);
-        fs.chmodSync(backup, mode);
+        if (backup) {
+          fs.copyFileSync(file, backup);
+          fs.chmodSync(backup, mode);
+        }
       }
-      if (after === null) fs.unlinkSync(file);
-      else writeAtomic(file, after, mode);
+      if (after === null) {
+        fs.unlinkSync(file);
+        // Folders that only ever held our files (skills/wavebrain, plugins/wavebrain, ~/.wavebrain/hooks).
+        const dir = path.dirname(file);
+        if (/(^|[\\/])(wavebrain|hooks)$/.test(dir) && /wavebrain/.test(dir)) {
+          try {
+            fs.rmdirSync(dir);
+          } catch {}
+        }
+      } else writeAtomic(file, after, mode);
     }
     this.changes.push({ file, kind, backup });
     return kind;

package/src/targets.mjs

@@ -20,6 +20,17 @@ import {
   yamlUpsertServer,
   envUpsert,
 } from "./files.mjs";
+import {
+  addHooks,
+  codexDisableHooks,
+  codexEnableHooks,
+  hasOurHooks,
+  hermesPluginFiles,
+  hermesPluginToggle,
+  hookCommand,
+  removeHooks,
+  skillText,
+} from "./capture.mjs";
 
 export const SERVER = "wavebrain";
 export const KEY_ENV = "WAVEBRAIN_API_KEY";
@@ -103,6 +114,56 @@ export function tilde(ctx, p) {
   return p.startsWith(ctx.home + path.sep) ? "~" + p.slice(ctx.home.length) : p;
 }
 
+// ---------- auto-capture parts (hooks, skills, plugins) ----------
+
+/**
+ * A capture part is one file we fully own (skill, plugin file) or one shared file we merge into
+ * (hooks.json, settings.json, config.toml). parts(ctx) -> [{ ref, file, apply(text), revert(text, rec) }]
+ */
+function hooksPart(ref, file, format, entries) {
+  return {
+    ref,
+    file,
+    apply: (t) => addHooks(t, file, format, entries),
+    revert: (t, rec) => removeHooks(t, file, format, { deleteIfEmpty: rec?.createdFile }),
+  };
+}
+const ownedFilePart = (ref, file, text) => ({ ref, file, apply: () => text, revert: () => null });
+
+/** Adds capture parts to a target. Skipped entirely with --no-hooks. */
+function withCapture(target, parts, after) {
+  return {
+    ...target,
+    capture: true,
+    files: (ctx) => [...target.files(ctx), ...parts(ctx).map((p) => p.file)],
+    install(ctx, s, opts, owned) {
+      const out = target.install(ctx, s, opts, owned);
+      if (opts.hooks === false) return out;
+      for (const p of parts(ctx)) {
+        const before = readText(p.file);
+        const prev = owned.get(p.ref);
+        out.push({ ref: p.ref, file: p.file, kind: s.edit(p.file, p.apply), createdFile: prev?.createdFile ?? before === null });
+      }
+      if (after) out.push(...after(ctx, s, true));
+      return out;
+    },
+    uninstall(ctx, s, owned) {
+      const out = [];
+      if (after) out.push(...after(ctx, s, false));
+      for (const p of parts(ctx)) {
+        const text = readText(p.file);
+        if (text === null) continue;
+        const rec = owned.get(p.ref);
+        // Our own files go only if we recorded them; merged files only lose our entries.
+        if (!rec && !hasOurHooks(text) && !(p.ref.endsWith(":features") && text.includes("added by wavebrain init"))) continue;
+        const kind = s.edit(p.file, (t) => p.revert(t, rec));
+        if (kind !== "unchanged") out.push({ ref: p.ref, file: p.file, kind });
+      }
+      return [...target.uninstall(ctx, s, owned), ...out];
+    },
+  };
+}
+
 // ---------- Claude Code ----------
 
 function claudeDir(ctx) {
@@ -173,7 +234,7 @@ const codex = {
   files: (ctx) => [codexToml(ctx)],
   detect: (ctx) => exists(codexToml(ctx)) || onPath(ctx, "codex"),
   configured: (ctx) => /^\s*\[mcp_servers\.wavebrain\]/m.test(readText(codexToml(ctx)) ?? ""),
-  next: `Start a new Codex session; /mcp should list wavebrain.`,
+  next: `Start a new Codex session; /mcp should list wavebrain. Codex asks you to review new hooks once: open /hooks and trust the two WaveBrain hooks (auto-capture stays off until you do).`,
   install(ctx, s, { url, key, keyFromEnv }) {
     const f = codexToml(ctx);
     // With the key already in the environment, reference it; otherwise Codex needs it in the file.
@@ -242,7 +303,10 @@ const vscode = jsonTarget({
 // ---------- Hermes ----------
 
 function hermesHome(ctx) {
-  return ctx.env.HERMES_HOME || path.join(ctx.home, ".hermes");
+  const h = ctx.env.HERMES_HOME;
+  // Inside a Hermes profile's terminal, HERMES_HOME is ~/.hermes/profiles/<name>; profiles live one level up.
+  if (h && path.basename(path.dirname(h)) === "profiles") return path.dirname(path.dirname(h));
+  return h || path.join(ctx.home, ".hermes");
 }
 
 function hermesTarget(profile) {
@@ -302,17 +366,73 @@ export function hermesProfiles(ctx) {
 
 // ---------- registry ----------
 
+const CLAUDE_PARTS = (ctx) => {
+  const settings = path.join(claudeDir(ctx), "settings.json");
+  return [
+    hooksPart("claude-code:hooks", settings, "nested", [
+      { event: "PostToolUse", matcher: "Bash|mcp__.*", command: hookCommand(ctx, "claude-code", "observe"), timeout: 10 },
+      // Failed calls arrive here instead of PostToolUse; a failed deploy belongs in the record too.
+      { event: "PostToolUseFailure", matcher: "Bash|mcp__.*", command: hookCommand(ctx, "claude-code", "observe"), timeout: 10 },
+      { event: "Stop", command: hookCommand(ctx, "claude-code", "flush"), timeout: 30 },
+      { event: "SessionEnd", command: hookCommand(ctx, "claude-code", "flush"), timeout: 30 },
+    ]),
+    ownedFilePart("claude-code:skill", path.join(claudeDir(ctx), "skills", "wavebrain", "SKILL.md"), skillText()),
+  ];
+};
+
+const codexHome = (ctx) => ctx.env.CODEX_HOME || path.join(ctx.home, ".codex");
+const CODEX_PARTS = (ctx) => [
+  hooksPart("codex:hooks", path.join(codexHome(ctx), "hooks.json"), "nested", [
+    { event: "PostToolUse", matcher: "*", command: hookCommand(ctx, "codex", "observe"), timeout: 10 },
+    { event: "Stop", command: hookCommand(ctx, "codex", "flush"), timeout: 30 },
+  ]),
+  { ref: "codex:features", file: codexToml(ctx), apply: codexEnableHooks, revert: codexDisableHooks },
+  ownedFilePart("codex:skill", path.join(codexHome(ctx), "skills", "wavebrain", "SKILL.md"), skillText()),
+];
+
+const CURSOR_PARTS = (ctx) => [
+  hooksPart("cursor:hooks", path.join(ctx.home, ".cursor", "hooks.json"), "flat", [
+    { event: "postToolUse", matcher: "Shell|MCP", command: hookCommand(ctx, "cursor", "observe") },
+    { event: "stop", command: hookCommand(ctx, "cursor", "flush") },
+  ]),
+];
+
+function hermesDir(ctx, profile) {
+  return profile ? path.join(hermesHome(ctx), "profiles", profile) : hermesHome(ctx);
+}
+const hermesParts = (profile) => (ctx) =>
+  hermesPluginFiles().map(([f, text]) =>
+    ownedFilePart(`${profile ? `hermes:${profile}` : "hermes"}:plugin:${f}`, path.join(hermesDir(ctx, profile), "plugins", "wavebrain", f), text),
+  );
+/** Hermes only loads third-party plugins on its allow-list. */
+const hermesToggle = (profile) => (ctx, s, on) => {
+  const id = profile ? `hermes:${profile}` : "hermes";
+  if (s.dryRun) return [{ ref: `${id}:plugin-enabled`, file: path.join(hermesDir(ctx, profile), "config.yaml"), kind: on ? "enable plugin" : "disable plugin" }];
+  if (!onPath(ctx, "hermes")) return [];
+  const ok = hermesPluginToggle(ctx, hermesDir(ctx, profile), on);
+  return ok ? [{ ref: `${id}:plugin-enabled`, file: path.join(hermesDir(ctx, profile), "config.yaml"), kind: on ? "enabled plugin" : "disabled plugin" }] : [];
+};
+const hermesWithCapture = (profile) => withCapture(hermesTarget(profile), hermesParts(profile), hermesToggle(profile));
+
 export const BASE_TARGET_IDS = ["claude-code", "codex", "cursor", "windsurf", "claude-desktop", "vscode", "hermes"];
 
-const BASE = { "claude-code": claudeCode, codex, cursor, windsurf, "claude-desktop": claudeDesktop, vscode, hermes: hermesTarget(null) };
+const BASE = {
+  "claude-code": withCapture(claudeCode, CLAUDE_PARTS),
+  codex: withCapture(codex, CODEX_PARTS),
+  cursor: withCapture(cursor, CURSOR_PARTS),
+  windsurf,
+  "claude-desktop": claudeDesktop,
+  vscode,
+  hermes: hermesWithCapture(null),
+};
 
 /** Every target, including one per Hermes profile found. */
 export function allTargets(ctx) {
-  return [...BASE_TARGET_IDS.map((id) => BASE[id]), ...hermesProfiles(ctx).map((p) => hermesTarget(p))];
+  return [...BASE_TARGET_IDS.map((id) => BASE[id]), ...hermesProfiles(ctx).map((p) => hermesWithCapture(p))];
 }
 
 export function targetById(ctx, id) {
   if (BASE[id]) return BASE[id];
   const m = id.match(/^hermes:([A-Za-z0-9._-]+)$/);
-  return m ? hermesTarget(m[1]) : null;
+  return m ? hermesWithCapture(m[1]) : null;
 }