@compr/opscontext-mcp 2.0.2 → 2.1.1

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.0.2",
+  "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",