@compr/opscontext-mcp 2.1.0 → 2.1.1

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to OpsContext for AI Agents (previously ContextEngine — MCP server + CLI) are documented here.
 
+## [2.1.1] — 2026-06-23 — Phase 1c: one-command install + Claude Code terminal capture
+
+Closes the last surface gap from 2.1.0. Before this patch, "use OpsContext" meant running `nohup npx ...` every time the Mac restarted and hand-editing `~/.claude/settings.json` to wire Claude Code hooks. Now both are single commands. This is the release that lets non-technical users actually adopt OpsContext.
+
+### Added
+- **`src/install-autostart.ts`** (LOCK `[AUTOSTART-INSTALL]`) — installs a macOS LaunchAgent at `~/Library/LaunchAgents/com.opscontext.mcp.plist`. Set-and-forget — server starts at every login, KeepAlive restarts on crash, logs to `~/.contextengine/logs/mcp-{stdout,stderr}.log`. Companion `uninstall-autostart` + `autostart-status` commands. Auto-detects either a global npm install or a dev tree; pins node path absolutely (launchd has no PATH).
+- **`src/install-claude-hook.ts`** (LOCK `[CLAUDE-HOOK-INSTALL]`) — copies `defaults/claude-code-hook.sh` to `~/.claude/hooks/opscontext-emit.sh` and splices three entries into `~/.claude/settings.json` under `hooks`: `UserPromptSubmit` → `vscode.prompt_submit`, `PostToolUse` (`.*` matcher) → `vscode.tool_call`, `SessionStart` → `vscode.session_start`. **Idempotent + preserves every existing hook entry** (backs up settings.json before any change). Closes the terminal-side capture gap — every Claude Code session in any project now feeds the audit log.
+- **`defaults/claude-code-hook.sh`** — the actual shell hook: ~3 KB, pure bash + jq + curl, ~28 ms latency per invocation, **silent on every failure** (never blocks Claude Code), 1-second hard timeout on the HTTP call. Posts to `127.0.0.1:7842/events` with shared secret in `X-OpsContext-Secret` header. LOCK `[OPSCONTEXT-CC-HOOK]`.
+- **New CLI subcommands:**
+  - `opscontext install-autostart [--force]`
+  - `opscontext uninstall-autostart`
+  - `opscontext autostart-status`
+  - `opscontext install-claude-hook`
+  - `opscontext uninstall-claude-hook`
+
+### Fixed
+- **`chrome-extension/src/options/options.html`** — Secret field placeholder said `32 hex chars` but the actual secret is 64 hex (256-bit). Updated to `64 hex chars` to match what `init-extension-secret` writes. No backwards-compat issue — placeholder text only, not validation.
+- **`chrome-extension` content scripts now bundled as IIFE** (companion `@compr/opscontext-chrome@0.1.1`). The MV3 manifest can't put `"type": "module"` on `content_scripts` entries — only on `background`. The previous build shipped `dist/content/claude.js` with top-level `import` statements which Chrome silently rejected, dark-launching the entire capture surface (Options page still saved the secret fine because popup/options DO support modules via inline `<script type="module">`). New `scripts/bundle-content.mjs` runs esbuild after `tsc` to inline all `./shared/*` and `../lib/*` imports into a single IIFE per content entry. LOCK `[CONTENT-SCRIPT-BUNDLE]`. Reload the unpacked extension after rebuild for the fix to take effect.
+
+### Why this matters
+- Before: `nohup npx -y --package=@compr/opscontext-mcp@2.1.0 -- opscontext > /tmp/opscontext-mcp.log 2>&1 < /dev/null &` every reboot, plus hand-editing JSON for Claude Code hooks. Friction kills adoption.
+- After: `opscontext install-autostart && opscontext install-claude-hook`. Two commands, ever. Server auto-starts at login forever; terminal Claude Code sessions feed audit log automatically.
+
+### Architecture notes
+- Hook namespace stays `vscode.*` (not `claude_code.*`) so the published 2.1.0 detector heuristics fire today without a parallel namespace migration. `payload.surface = "claude-code"` disambiguates source for any caller that cares.
+- LaunchAgent uses `gui/$UID` domain (per-user, no root) — same pattern as the user's existing `com.invocme.backup-*` plists.
+- Hook deliberately emits on PostToolUse ONLY (not PreToolUse) — emitting both would double-count for the `stuck` heuristic and skew `silent_failure` counts.
+- All transport via HTTP `POST /events` not direct file writes — keeps event writes serialized through the running MCP server's single in-process chain cache, sidestepping the historic concurrent-write race (8 chain breaks on 2026-06-10/11, all `system` actor, all pre-flag-day; zero breaks since).
+
+### Known surface gaps still open
+- `Stop` hook event not emitted (would enable "assistant gave up mid-task" detection — Phase 3.1).
+- No Linux support yet for `install-autostart` (systemd --user unit equivalent is ~30 min of work).
+- No tool-result exit codes from VS Code extension yet (candidate for vscode-ext 0.10).
+
 ## [2.1.0] — 2026-06-23 — Phase 1: cross-surface capture + drift detector + local event ingest
 
 The first feature release after the OpsContext rebrand. Closes the wedge the audit identified: **no other tool captures AI interactions across browser + IDE + terminal and feeds them into a tamper-evident audit log with policy enforcement**. Now we do.

package/defaults/claude-code-hook.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# OpsContext — Claude Code hook emitter
+#
+# 🔒 LOCKED [OPSCONTEXT-CC-HOOK] — 2026-06-23
+# ⛔ NEVER block on success or fail loudly. Claude Code waits for hooks to
+#    complete before continuing — any error must exit 0 + silent.
+# ⛔ NEVER emit on PreToolUse. PostToolUse alone — PreToolUse would double-
+#    count vs PostToolUse for the `stuck` heuristic and skew `silent_failure`.
+# ⛔ NEVER print to stdout (would be interpreted as a hook decision message).
+# WHY: This hook is the ONLY way Claude Code terminal sessions get into the
+#    OpsContext audit log. If it's slow or breaks, the user disables it and
+#    loses cross-surface drift visibility — the entire wedge collapses.
+# FIX: To support a new Claude Code hook event, add a case branch. Keep the
+#    exit-0-on-any-error discipline. Events go via HTTP (NOT direct file
+#    write) so the running MCP server's in-process chain cache prevents the
+#    concurrent-write race.
+
+set +e
+
+EVENT_KIND="${1:-}"
+SECRET_FILE="$HOME/.contextengine/extension-secret"
+ENDPOINT="${OPSCONTEXT_EVENT_URL:-http://127.0.0.1:7842/events}"
+
+# Bail fast if not initialized — never block Claude Code
+[ -r "$SECRET_FILE" ] || exit 0
+SECRET=$(cat "$SECRET_FILE" 2>/dev/null)
+[ -n "$SECRET" ] || exit 0
+
+INPUT=$(cat)
+[ -n "$INPUT" ] || exit 0
+
+NOW=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
+
+case "$EVENT_KIND" in
+  UserPromptSubmit)
+    PAYLOAD=$(printf '%s' "$INPUT" | jq -c --arg ts "$NOW" '{
+      v: 1, ts: $ts, event: "vscode.prompt_submit", actor: "claude-code",
+      payload: {
+        surface: "claude-code",
+        text: ((.prompt // "")[:4000]),
+        session: (.session_id // ""),
+        cwd: (.cwd // ""),
+        char_count: ((.prompt // "") | length)
+      }
+    }' 2>/dev/null)
+    ;;
+  PostToolUse)
+    PAYLOAD=$(printf '%s' "$INPUT" | jq -c --arg ts "$NOW" '{
+      v: 1, ts: $ts, event: "vscode.tool_call", actor: "claude-code",
+      payload: ({
+        surface: "claude-code",
+        tool: (.tool_name // ""),
+        args_preview: (
+          (.tool_input.command
+            // .tool_input.file_path
+            // .tool_input.pattern
+            // (.tool_input | tostring)
+            // ""
+          )[:200]
+        ),
+        session: (.session_id // ""),
+        cwd: (.cwd // "")
+      } + (
+        if (.tool_response.is_error == true)
+            or ((.tool_response.error // "") != "")
+            or ((.tool_response.interrupt // false) == true)
+        then { error: ((.tool_response.error
+                        // (.tool_response.content | tostring)
+                        // "tool reported error")[:500]) }
+        else {}
+        end
+      ))
+    }' 2>/dev/null)
+    ;;
+  SessionStart)
+    PAYLOAD=$(printf '%s' "$INPUT" | jq -c --arg ts "$NOW" '{
+      v: 1, ts: $ts, event: "vscode.session_start", actor: "claude-code",
+      payload: {
+        surface: "claude-code",
+        session: (.session_id // ""),
+        cwd: (.cwd // ""),
+        source: (.source // "")
+      }
+    }' 2>/dev/null)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+[ -n "$PAYLOAD" ] || exit 0
+
+# POST with 1s hard timeout. Any error → silent (curl >/dev/null 2>&1, exit 0).
+curl -sS --max-time 1.0 \
+  -H "Content-Type: application/json" \
+  -H "X-OpsContext-Secret: $SECRET" \
+  --data "{\"events\":[$PAYLOAD]}" \
+  "$ENDPOINT" >/dev/null 2>&1
+
+exit 0

package/dist/cli.js

@@ -1784,6 +1784,11 @@ Usage:
                                        Author + validate the declarative .contextengine/policy.json
   contextengine init-extension-secret [--force]
                                        Generate ~/.contextengine/extension-secret for the browser ext
+  contextengine install-autostart [--force]
+                                       Install macOS LaunchAgent so MCP server auto-starts at login
+                                       (uninstall-autostart / autostart-status — companion commands)
+  contextengine install-claude-hook    Wire Claude Code terminal sessions into the OpsContext audit log
+                                       (UserPromptSubmit + PostToolUse + SessionStart hook entries)
   contextengine watch [--json] [--severity info|warn|critical] [--once] [--window SECONDS]
                                        Stream drift / loop / stuck-tool / fabrication alerts from the audit log
   contextengine emit-event <kind> <payload-json> [--actor NAME]
@@ -2004,6 +2009,36 @@ else if (command === "init-extension-secret") {
         process.exit(1);
     });
 }
+else if (command === "install-autostart") {
+    import("./install-autostart.js").then((m) => m.cliInstallAutostart(process.argv.slice(3))).catch((err) => {
+        console.error("Error:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}
+else if (command === "uninstall-autostart") {
+    import("./install-autostart.js").then((m) => m.cliUninstallAutostart(process.argv.slice(3))).catch((err) => {
+        console.error("Error:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}
+else if (command === "autostart-status") {
+    import("./install-autostart.js").then((m) => m.cliAutostartStatus(process.argv.slice(3))).catch((err) => {
+        console.error("Error:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}
+else if (command === "install-claude-hook") {
+    import("./install-claude-hook.js").then((m) => m.cliInstallClaudeHook(process.argv.slice(3))).catch((err) => {
+        console.error("Error:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}
+else if (command === "uninstall-claude-hook") {
+    import("./install-claude-hook.js").then((m) => m.cliUninstallClaudeHook(process.argv.slice(3))).catch((err) => {
+        console.error("Error:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}
 else if (command === "stats") {
     cliStats();
 }

package/dist/install-autostart.d.ts

@@ -0,0 +1,4 @@
+export declare function cliInstallAutostart(args: string[]): Promise<void>;
+export declare function cliUninstallAutostart(args: string[]): Promise<void>;
+export declare function cliAutostartStatus(args: string[]): Promise<void>;
+//# sourceMappingURL=install-autostart.d.ts.map

package/dist/install-autostart.js

@@ -0,0 +1,300 @@
+// 🔒 LOCKED [AUTOSTART-INSTALL] — 2026-06-23
+// ⛔ NEVER bootstrap into a `system/` domain (would need root + run as root).
+//    Use `gui/$UID` — per-user agent, started at user login, runs as the user.
+// ⛔ NEVER write the plist before checking if a server is already listening on
+//    the port. A pre-existing process means we'd race with the launchd-managed
+//    one for port 7842.
+// ⛔ NEVER ship a plist that calls `npx -y @latest` — every restart would
+//    fetch the registry, eating ~3s and breaking offline. Pin a specific
+//    node path + a specific dist path.
+// WHY: This is the "set it and forget it" entrypoint for non-technical users.
+//    If it fails silently or starts duplicating processes, the entire
+//    auto-capture story collapses and the user has to type `nohup npx ...`
+//    forever — defeating the whole point.
+// FIX: To add platform support beyond macOS, branch on process.platform and
+//    add equivalent systemd / NSSM logic. Keep `gui/$UID` and KeepAlive
+//    discipline in any new platform.
+import { existsSync, writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { homedir, platform } from "os";
+import { execSync } from "child_process";
+const LABEL = "com.opscontext.mcp";
+const PLIST_FILE = join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+const LOG_DIR = join(homedir(), ".contextengine", "logs");
+const PORT = 7842;
+/** Resolve an absolute node binary path that launchd can find without PATH. */
+function detectNodePath() {
+    // process.execPath is the node that's running THIS script — absolute path.
+    // launchd runs without the user's interactive shell, so we MUST pass an
+    // absolute path (no PATH lookup of "node" works under launchd).
+    return process.execPath;
+}
+/** Find a stable path to the opscontext entrypoint that survives version
+ *  upgrades. Order: (1) globally installed bin → resolve symlink to real path;
+ *  (2) ./dist/index.js next to this module (dev tree). Falls through with
+ *  null if neither is found. */
+function detectOpscontextEntry() {
+    // Try global install via `npm root -g`
+    try {
+        const globalRoot = execSync("npm root -g 2>/dev/null", { encoding: "utf-8" }).trim();
+        const candidate = join(globalRoot, "@compr", "opscontext-mcp", "dist", "index.js");
+        if (existsSync(candidate))
+            return { kind: "global", path: candidate };
+    }
+    catch {
+        /* no npm root available; fall through */
+    }
+    // Try dev tree relative to this module's location (dist/install-autostart.js)
+    // → __dirname/.. would be dist/, then ../ would be repo root, then dist/index.js
+    try {
+        // import.meta.url style would be nicer but cli.ts is CommonJS-ish; use __dirname
+        // via require.resolve fallback. We're loaded from dist/, so look at sibling.
+        const here = dirname(__filename || "");
+        const candidate = join(here, "index.js");
+        if (existsSync(candidate))
+            return { kind: "devtree", path: candidate };
+    }
+    catch {
+        /* ignore */
+    }
+    return null;
+}
+function buildPlist(nodePath, entryPath, nodeBinDir) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${LABEL}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>${nodePath}</string>
+        <string>${entryPath}</string>
+    </array>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>${nodeBinDir}:/usr/local/bin:/usr/bin:/bin</string>
+        <key>HOME</key>
+        <string>${homedir()}</string>
+        <key>OPSCONTEXT_SKIP_CLAUDE_MEMORY</key>
+        <string>1</string>
+    </dict>
+
+    <key>WorkingDirectory</key>
+    <string>${homedir()}</string>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+
+    <key>StandardOutPath</key>
+    <string>${join(LOG_DIR, "mcp-stdout.log")}</string>
+
+    <key>StandardErrorPath</key>
+    <string>${join(LOG_DIR, "mcp-stderr.log")}</string>
+
+    <key>ProcessType</key>
+    <string>Background</string>
+</dict>
+</plist>
+`;
+}
+function isMacOS() {
+    return platform() === "darwin";
+}
+function userId() {
+    return process.getuid?.() ?? 501;
+}
+function portIsOurs() {
+    try {
+        execSync(`lsof -nP -iTCP:${PORT} -sTCP:LISTEN >/dev/null 2>&1`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function waitForPort(timeoutSec = 30) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutSec * 1000) {
+        if (portIsOurs())
+            return true;
+        execSync("sleep 1");
+    }
+    return false;
+}
+export async function cliInstallAutostart(args) {
+    const help = args.includes("-h") || args.includes("--help");
+    if (help) {
+        console.log(`Usage: opscontext install-autostart [--force]
+
+Installs OpsContext as a macOS LaunchAgent so the MCP server starts
+automatically at every login and restarts if it crashes.
+
+After running this once, you never need to start the server manually again.
+Browser extension events + Claude Code hook events + VS Code emitter events
+all flow through the auto-started server.
+
+  --force   Re-create the plist even if one already exists (use after a
+            node version upgrade or after moving the install location).
+
+To stop / uninstall:        opscontext uninstall-autostart
+To check status:            opscontext autostart-status
+To view server logs:        tail -f ~/.contextengine/logs/mcp-stderr.log
+`);
+        return;
+    }
+    if (!isMacOS()) {
+        console.error(`❌ install-autostart currently supports macOS only (this is ${platform()}).`);
+        console.error(`   For Linux: write a systemd --user unit. For Windows: NSSM or Task Scheduler.`);
+        process.exit(1);
+    }
+    const force = args.includes("--force") || args.includes("-f");
+    if (existsSync(PLIST_FILE) && !force) {
+        console.error(`❌ ${PLIST_FILE} already exists.`);
+        console.error(`   Pass --force to overwrite, or run: opscontext autostart-status`);
+        process.exit(1);
+    }
+    const nodePath = detectNodePath();
+    const entry = detectOpscontextEntry();
+    if (!entry) {
+        console.error(`❌ Could not locate opscontext entrypoint.`);
+        console.error(`   Either install globally:  npm install -g @compr/opscontext-mcp`);
+        console.error(`   Or run from a clone:      cd .../ContextEngine && npm run build`);
+        process.exit(1);
+    }
+    // Ensure log dir
+    mkdirSync(LOG_DIR, { recursive: true });
+    mkdirSync(dirname(PLIST_FILE), { recursive: true });
+    const nodeBinDir = dirname(nodePath);
+    const plist = buildPlist(nodePath, entry.path, nodeBinDir);
+    writeFileSync(PLIST_FILE, plist);
+    console.log(`✅ Wrote ${PLIST_FILE}`);
+    console.log(`   node:  ${nodePath}`);
+    console.log(`   entry: ${entry.path}  (${entry.kind})`);
+    // Stop any currently-running unmanaged opscontext server on the port —
+    // it would race with launchd for port 7842.
+    if (portIsOurs()) {
+        console.log(`   detected existing process on :${PORT} — relying on launchctl bootout to clean it.`);
+    }
+    // Idempotent bootstrap: bootout (ignore failure) → bootstrap
+    const uid = userId();
+    try {
+        execSync(`launchctl bootout gui/${uid}/${LABEL}`, { stdio: "ignore" });
+    }
+    catch {
+        /* not loaded — fine */
+    }
+    try {
+        execSync(`launchctl bootstrap gui/${uid} ${PLIST_FILE}`, { stdio: "inherit" });
+    }
+    catch (err) {
+        console.error(`❌ launchctl bootstrap failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    console.log(`   waiting for the server to bind port ${PORT}...`);
+    if (waitForPort(30)) {
+        console.log(`✅ OpsContext is now running as a LaunchAgent (started at every login).`);
+        console.log(``);
+        console.log(`Verify:      curl -s http://127.0.0.1:${PORT}/health | jq .`);
+        console.log(`Logs:        tail -f ~/.contextengine/logs/mcp-stderr.log`);
+        console.log(`Stop:        opscontext uninstall-autostart`);
+    }
+    else {
+        console.error(`⚠️ Server didn't bind port ${PORT} within 30s.`);
+        console.error(`   Check the logs: tail -50 ~/.contextengine/logs/mcp-stderr.log`);
+        process.exit(1);
+    }
+}
+export async function cliUninstallAutostart(args) {
+    const help = args.includes("-h") || args.includes("--help");
+    if (help) {
+        console.log(`Usage: opscontext uninstall-autostart
+
+Removes the LaunchAgent and stops the OpsContext MCP server. The audit log
+and extension secret are NOT touched — only the auto-start wiring goes away.
+You can re-install with: opscontext install-autostart`);
+        return;
+    }
+    if (!isMacOS()) {
+        console.error(`❌ Only macOS LaunchAgents supported here.`);
+        process.exit(1);
+    }
+    const uid = userId();
+    let removed = false;
+    try {
+        execSync(`launchctl bootout gui/${uid}/${LABEL}`, { stdio: "ignore" });
+        removed = true;
+    }
+    catch {
+        /* not loaded */
+    }
+    if (existsSync(PLIST_FILE)) {
+        const { unlinkSync } = await import("fs");
+        unlinkSync(PLIST_FILE);
+        console.log(`✅ Removed ${PLIST_FILE}`);
+    }
+    else {
+        console.log(`   (no plist at ${PLIST_FILE})`);
+    }
+    if (removed) {
+        console.log(`✅ Stopped the running ${LABEL} agent.`);
+    }
+    else {
+        console.log(`   (no running ${LABEL} agent found)`);
+    }
+    console.log(``);
+    console.log(`Audit log and extension secret kept at ~/.contextengine/ — re-install any time.`);
+}
+export async function cliAutostartStatus(args) {
+    if (args.includes("-h") || args.includes("--help")) {
+        console.log(`Usage: opscontext autostart-status
+
+Shows whether OpsContext is configured to auto-start (LaunchAgent present),
+whether it's currently running (port 7842 listening), and the path to the
+running entrypoint.`);
+        return;
+    }
+    if (!isMacOS()) {
+        console.log(`platform:  ${platform()} (LaunchAgent applies to macOS only)`);
+        return;
+    }
+    const plistExists = existsSync(PLIST_FILE);
+    const portUp = portIsOurs();
+    const uid = userId();
+    let launchctlState = "not loaded";
+    try {
+        const out = execSync(`launchctl print gui/${uid}/${LABEL} 2>/dev/null || true`, { encoding: "utf-8" });
+        const match = out.match(/state\s*=\s*(\S+)/);
+        if (match)
+            launchctlState = match[1];
+    }
+    catch {
+        /* ignore */
+    }
+    console.log(`OpsContext auto-start status`);
+    console.log(`─────────────────────────────`);
+    console.log(`  plist:       ${plistExists ? "✅ " + PLIST_FILE : "❌ not installed (run: opscontext install-autostart)"}`);
+    console.log(`  launchctl:   ${launchctlState}`);
+    console.log(`  port ${PORT}:   ${portUp ? "✅ listening" : "❌ not listening"}`);
+    if (portUp) {
+        try {
+            const health = execSync(`curl -sf http://127.0.0.1:${PORT}/health`, { encoding: "utf-8", timeout: 2000 });
+            console.log(`  health:      ${health.trim()}`);
+        }
+        catch {
+            console.log(`  health:      ⚠ port open but /health didn't respond`);
+        }
+    }
+    console.log(``);
+    console.log(`Logs: ~/.contextengine/logs/mcp-stderr.log`);
+}
+//# sourceMappingURL=install-autostart.js.map

package/dist/install-claude-hook.d.ts

@@ -0,0 +1,3 @@
+export declare function cliInstallClaudeHook(args: string[]): Promise<void>;
+export declare function cliUninstallClaudeHook(args: string[]): Promise<void>;
+//# sourceMappingURL=install-claude-hook.d.ts.map

package/dist/install-claude-hook.js

@@ -0,0 +1,180 @@
+// 🔒 LOCKED [CLAUDE-HOOK-INSTALL] — 2026-06-23
+// ⛔ NEVER overwrite existing entries in hooks.PostToolUse — must APPEND.
+//    Users (and CE itself via the dogfood settings) commonly have
+//    matcher-specific PostToolUse entries (e.g. "Read|Edit|Write" gating)
+//    that would be silently destroyed by a replace.
+// ⛔ NEVER write to ~/.claude/settings.json without parsing first. A typo
+//    or non-JSON state means Claude Code refuses to start.
+// ⛔ NEVER emit on PreToolUse — would double-count vs PostToolUse for the
+//    `stuck` heuristic and skew `silent_failure` counts.
+// WHY: Claude Code hook wiring is the ONLY way the user's terminal Claude
+//    Code sessions get into the OpsContext audit log. The installer has to
+//    be safe (idempotent, preserve existing) AND legible (clear error
+//    messages) AND fast (one command). If users have to hand-edit JSON,
+//    they won't.
+// FIX: To add a new hook event, extend EVENT_KINDS + the splice block.
+//    Keep the "preserve existing" discipline in every code path.
+import { existsSync, readFileSync, writeFileSync, copyFileSync, chmodSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const CLAUDE_DIR = join(homedir(), ".claude");
+const SETTINGS_FILE = join(CLAUDE_DIR, "settings.json");
+const HOOKS_DIR = join(CLAUDE_DIR, "hooks");
+const HOOK_SCRIPT = join(HOOKS_DIR, "opscontext-emit.sh");
+const EVENT_KINDS = ["UserPromptSubmit", "PostToolUse", "SessionStart"];
+function readSettings() {
+    if (!existsSync(SETTINGS_FILE))
+        return {};
+    try {
+        return JSON.parse(readFileSync(SETTINGS_FILE, "utf-8"));
+    }
+    catch (err) {
+        throw new Error(`${SETTINGS_FILE} is not valid JSON — refusing to touch. (${err instanceof Error ? err.message : err})`);
+    }
+}
+function backupSettings() {
+    if (!existsSync(SETTINGS_FILE))
+        return "";
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const backup = `${SETTINGS_FILE}.bak-pre-opscontext-${ts}`;
+    copyFileSync(SETTINGS_FILE, backup);
+    return backup;
+}
+function hookAlreadyWired(entries, hookScript) {
+    if (!entries)
+        return false;
+    return entries.some((e) => e.hooks?.some((h) => h.command?.startsWith(hookScript)));
+}
+/** Path to the reference hook script bundled with this package. */
+function bundledHookSource() {
+    // dist/install-claude-hook.js → ../defaults/claude-code-hook.sh in dev tree,
+    // or .../node_modules/@compr/opscontext-mcp/defaults/claude-code-hook.sh
+    // when globally / locally installed via npm. Both follow the same relative
+    // shape because npm copies defaults/ via the `files` whitelist.
+    const candidates = [
+        join(__dirname || "", "..", "defaults", "claude-code-hook.sh"),
+        join(__dirname || "", "defaults", "claude-code-hook.sh"),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+export async function cliInstallClaudeHook(args) {
+    const help = args.includes("-h") || args.includes("--help");
+    if (help) {
+        console.log(`Usage: opscontext install-claude-hook
+
+Wires OpsContext into Claude Code's hook system so every terminal Claude
+Code session sends prompts + tool calls to the OpsContext audit log.
+
+Events emitted (all go through the local HTTP endpoint, never the network):
+  • UserPromptSubmit → vscode.prompt_submit  (feeds the loop heuristic)
+  • PostToolUse      → vscode.tool_call      (feeds stuck + silent_failure)
+  • SessionStart     → vscode.session_start
+
+The installer:
+  1. Copies the bundled hook script to ~/.claude/hooks/opscontext-emit.sh
+  2. Splices three entries into ~/.claude/settings.json under "hooks"
+  3. Preserves every existing hook entry (idempotent, safe to re-run)
+
+A timestamped backup is written next to settings.json before any change.
+
+Pre-req: the MCP server must be auto-started or running (otherwise the hook
+silently no-ops, which is the safe default — you won't lose events later).
+Run: opscontext install-autostart
+`);
+        return;
+    }
+    // Step 1: Install / verify the hook script
+    mkdirSync(HOOKS_DIR, { recursive: true });
+    const src = bundledHookSource();
+    if (!src) {
+        console.error(`❌ Could not find bundled hook script defaults/claude-code-hook.sh.`);
+        console.error(`   This means the install is incomplete. Reinstall opscontext:`);
+        console.error(`     npm install -g @compr/opscontext-mcp`);
+        process.exit(1);
+    }
+    copyFileSync(src, HOOK_SCRIPT);
+    chmodSync(HOOK_SCRIPT, 0o755);
+    console.log(`✅ Installed hook script: ${HOOK_SCRIPT}`);
+    // Step 2: Splice into settings.json
+    const settings = readSettings();
+    const backup = backupSettings();
+    if (backup)
+        console.log(`✅ Backed up settings.json → ${backup}`);
+    settings.hooks ??= {};
+    const hookCmdPrefix = `${HOOK_SCRIPT}`; // command string starts with this
+    let added = 0;
+    let skipped = 0;
+    for (const kind of EVENT_KINDS) {
+        settings.hooks[kind] ??= [];
+        if (hookAlreadyWired(settings.hooks[kind], hookCmdPrefix)) {
+            skipped++;
+            continue;
+        }
+        const entry = {
+            hooks: [
+                {
+                    type: "command",
+                    command: `${HOOK_SCRIPT} ${kind}`,
+                    timeout: 5,
+                },
+            ],
+        };
+        // PostToolUse needs a matcher (PreToolUse/PostToolUse are tool-matched);
+        // ".*" matches every tool. Other events are not tool-scoped.
+        if (kind === "PostToolUse")
+            entry.matcher = ".*";
+        settings.hooks[kind].push(entry);
+        added++;
+    }
+    writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`✅ ${added} hook entries added, ${skipped} already present.`);
+    console.log(``);
+    console.log(`Test live:`);
+    console.log(`  1. Open a NEW VS Code terminal (settings.json is read at session start).`);
+    console.log(`  2. Run \`claude\` and ask anything — Claude will use tools.`);
+    console.log(`  3. In any other terminal:`);
+    console.log(`     tail -f ~/.contextengine/audit.log | grep --line-buffered '"actor":"claude-code"'`);
+    console.log(``);
+    console.log(`To remove: opscontext uninstall-claude-hook   (or hand-edit ~/.claude/settings.json)`);
+}
+export async function cliUninstallClaudeHook(args) {
+    if (args.includes("-h") || args.includes("--help")) {
+        console.log(`Usage: opscontext uninstall-claude-hook
+
+Removes OpsContext hook entries from ~/.claude/settings.json. The hook
+script file (~/.claude/hooks/opscontext-emit.sh) is left in place — delete
+manually if you want it gone. The audit log is NOT touched.`);
+        return;
+    }
+    const settings = readSettings();
+    if (!settings.hooks) {
+        console.log(`   (no hooks block in settings.json — nothing to remove)`);
+        return;
+    }
+    const backup = backupSettings();
+    if (backup)
+        console.log(`✅ Backed up settings.json → ${backup}`);
+    let removed = 0;
+    for (const kind of EVENT_KINDS) {
+        const entries = settings.hooks[kind];
+        if (!entries)
+            continue;
+        const filtered = entries.filter((e) => !e.hooks?.some((h) => h.command?.includes("opscontext-emit.sh")));
+        removed += entries.length - filtered.length;
+        if (filtered.length === 0) {
+            delete settings.hooks[kind];
+        }
+        else {
+            settings.hooks[kind] = filtered;
+        }
+    }
+    writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`✅ Removed ${removed} hook entries.`);
+    console.log(`   Hook script kept at: ${HOOK_SCRIPT}`);
+    console.log(`   Audit log untouched.`);
+}
+//# sourceMappingURL=install-claude-hook.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "OpsContext for AI Agents — read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident audit log + policy-as-code hooks. The ops + compliance layer Claude Code can't grow natively.",
   "type": "module",
   "main": "dist/index.js",