@nocville/npc 0.0.0-stage → 0.2.0

package/dist/cjs/npcs/agent-common/shim.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_POINTER = exports.SHIM_PATH = void 0;
+exports.installHookShim = installHookShim;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const user_config_js_1 = require("../../core/user-config.js");
+const runtime_js_1 = require("./runtime.js");
+const SHIM_PATH = () => (0, node_path_1.join)((0, node_path_1.dirname)((0, user_config_js_1.userConfigPath)()), 'bin', 'nocville-hook');
+exports.SHIM_PATH = SHIM_PATH;
+const RUNTIME_POINTER = () => (0, node_path_1.join)((0, node_path_1.dirname)((0, user_config_js_1.userConfigPath)()), 'runtime', 'current.json');
+exports.RUNTIME_POINTER = RUNTIME_POINTER;
+function writeChanged(path, content, mode) {
+    try {
+        if ((0, node_fs_1.readFileSync)(path, 'utf8') === content)
+            return;
+    }
+    catch {
+        /* first install */
+    }
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, content, { mode });
+    (0, node_fs_1.renameSync)(tmp, path);
+}
+// Resolve relative to the shim itself, including custom XDG/NOCVILLE_CONFIG installs.
+// JSON is parsed by Node, never interpolated into shell code or decoded with sed.
+const SHIM = `#!/bin/sh
+# nocville-npc-hook: stable one-way hook launcher
+DIR=$(CDPATH= cd -- "$(dirname -- "$0")" 2>/dev/null && pwd) || exit 0
+IFS= read -r NODE < "$DIR/../runtime/node-path" 2>/dev/null || NODE=''
+if [ ! -x "$NODE" ]; then NODE=$(command -v node 2>/dev/null); fi
+for candidate in "$NODE" /opt/homebrew/bin/node /usr/local/bin/node "$HOME/.volta/bin/node"; do
+  if [ -x "$candidate" ]; then NODE="$candidate"; break; fi
+done
+if [ ! -x "$NODE" ]; then cat >/dev/null; if { [ "$1" = gemini ] || [ "$1" = cursor ] || [ "$1" = claude-code ]; }; then printf '{}\\n'; fi; exit 0; fi
+exec "$NODE" "$DIR/launch.cjs" "$DIR/../runtime/current.json" "$@"
+`;
+// Without Node, return a neutral empty object for both Claude and imported Cursor.
+// No payload is evaluated by either shell. Native Codex remains silent.
+const WINDOWS_SHIM = String.raw `@echo off
+setlocal DisableDelayedExpansion
+set "NOCVILLE_NODE="
+set /p "NOCVILLE_NODE="<"%~dp0..\runtime\node-path" 2>nul
+if exist "%NOCVILLE_NODE%" goto launch
+set "NOCVILLE_NODE="
+for /f "delims=" %%N in ('where node.exe 2^>nul') do if not defined NOCVILLE_NODE set "NOCVILLE_NODE=%%N"
+if not defined NOCVILLE_NODE goto no_node
+:launch
+"%NOCVILLE_NODE%" "%~dp0launch.cjs" "%~dp0..\runtime\current.json" %*
+exit /b 0
+:no_node
+more >nul
+if "%~1"=="cursor" echo {}
+if "%~1"=="gemini" echo {}
+if "%~1"=="claude-code" echo {}
+exit /b 0
+`;
+const LAUNCHER = `// Stable bootstrap. Hooks never return decisions or emit launcher errors.
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+const agent = process.argv[3];
+const hook = !process.argv[4] || process.argv[4] === 'hook';
+let neutral = hook && (agent === 'gemini' || agent === 'cursor');
+let input = Buffer.alloc(0);
+try {
+  input = fs.readFileSync(0);
+  if (hook && agent === 'claude-code') {
+    try {
+      const event = JSON.parse(input.toString('utf8'));
+      const transcript = typeof event?.transcript_path === 'string' ? event.transcript_path.replace(/\\\\/g, '/') : '';
+      neutral = typeof event?.cursor_version === 'string' ||
+        (typeof event?.conversation_id === 'string' && !/(?:^|\\/)\\.claude(?:\\/|$)/.test(transcript));
+    } catch {}
+  }
+  const pointer = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+  if (typeof pointer.cli !== 'string' || !fs.existsSync(pointer.cli)) throw new Error('missing runtime');
+  const node = typeof pointer.node === 'string' && fs.existsSync(pointer.node) ? pointer.node : process.execPath;
+  // Buffer stdin once for payload-based imported-Cursor detection, then replay it unchanged.
+  // Never forward child stdout, even in debug mode or on an unexpected failure.
+  spawnSync(node, [pointer.cli, ...process.argv.slice(3)], { input, stdio: ['pipe', 'ignore', 'inherit'], windowsHide: true });
+} catch {}
+if (neutral) process.stdout.write('{}\\n');
+`;
+function installHookShim(nodePath, cliPath) {
+    writeChanged((0, exports.RUNTIME_POINTER)(), JSON.stringify({ node: nodePath, cli: cliPath }, null, 2) + '\n', 0o600);
+    writeChanged((0, node_path_1.join)((0, node_path_1.dirname)((0, exports.RUNTIME_POINTER)()), 'node-path'), nodePath + '\n', 0o600);
+    writeChanged((0, node_path_1.join)((0, node_path_1.dirname)((0, exports.SHIM_PATH)()), 'launch.cjs'), LAUNCHER, 0o600);
+    writeChanged((0, exports.SHIM_PATH)(), SHIM, 0o755);
+    (0, node_fs_1.chmodSync)((0, exports.SHIM_PATH)(), 0o755);
+    // Both launchers use the same bootstrap, including imported-Cursor detection.
+    writeChanged((0, exports.SHIM_PATH)() + '.cmd', WINDOWS_SHIM.replace(/\n/g, '\r\n'), 0o755);
+    (0, runtime_js_1.pruneOldRuntimes)((0, node_path_1.dirname)((0, exports.RUNTIME_POINTER)()));
+    return (0, exports.SHIM_PATH)();
+}
+//# sourceMappingURL=shim.js.map

package/dist/cjs/npcs/agent-common/watchdog.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WATCHDOG_OFFLINE_RETRY_MS = exports.WATCHDOG_HEARTBEAT_MS = exports.WATCHDOG_TICK_MS = void 0;
+exports.ensureWatchdog = ensureWatchdog;
+exports.runWatchdog = runWatchdog;
+const liveness_js_1 = require("./liveness.js");
+const lock_js_1 = require("./lock.js");
+const session_js_1 = require("./session.js");
+exports.WATCHDOG_TICK_MS = 15_000;
+exports.WATCHDOG_HEARTBEAT_MS = 60_000;
+exports.WATCHDOG_OFFLINE_RETRY_MS = 15 * 60_000;
+async function ensureWatchdog(adapter, config, sessionId, cliPath, lockWaitMs) {
+    if (adapter.processNames?.length === 0 ||
+        !config.apiKey ||
+        process.env['NOCVILLE_NO_WATCHDOG'] === '1')
+        return;
+    await (0, lock_js_1.withStateLock)((0, session_js_1.stateFilePath)(adapter.stateDir, sessionId), () => {
+        const state = (0, session_js_1.readSessionState)(adapter.stateDir, sessionId);
+        // No heartbeat without proven liveness. Keep the long fallback on unsupported hosts.
+        if (!state || state.offline || !state.agentPid)
+            return;
+        if (state.watchdogPid && (0, liveness_js_1.isAgentAlive)({ pid: state.watchdogPid }))
+            return;
+        const pid = (0, session_js_1.spawnDetachedAgent)(adapter, config, ['watchdog', sessionId], cliPath);
+        if (pid) {
+            state.watchdogPid = pid;
+            (0, session_js_1.writeSessionState)(adapter.stateDir, state);
+        }
+    }, lockWaitMs);
+}
+/** Silent, read-only observer of the agent process; never sends input to it. */
+async function runWatchdog(adapter, config, sessionId, deps = {}) {
+    if (!sessionId || adapter.processNames?.length === 0)
+        return;
+    const isAlive = deps.isAlive ?? liveness_js_1.isAgentAlive;
+    const now = deps.now ?? Date.now;
+    const wait = deps.wait ?? session_js_1.sleep;
+    const selfPid = deps.selfPid ?? process.pid;
+    let unknownTicks = 0;
+    let rejected = false;
+    let heartbeatRejected = false;
+    const delivery = {
+        ...deps,
+        onResult: (result) => {
+            if (!result.success && [400, 401, 403, 404].includes(result.statusCode ?? 0))
+                rejected = true;
+            deps.onResult?.(result);
+        },
+    };
+    // Do not clear a replacement observer's ownership. A failed write retries on the next tick.
+    const finish = async (terminal = false, abandoned = false) => {
+        await (0, lock_js_1.withStateLock)((0, session_js_1.stateFilePath)(adapter.stateDir, sessionId), () => {
+            const fresh = (0, session_js_1.readSessionState)(adapter.stateDir, sessionId);
+            if (!fresh || (fresh.watchdogPid && fresh.watchdogPid !== selfPid))
+                return;
+            if (terminal && !fresh.offline) {
+                fresh.offline = true;
+                fresh.rev = (fresh.rev ?? 0) + 1;
+            }
+            if (abandoned)
+                fresh.offlineDeliveryStopped = true;
+            fresh.watchdogPid = undefined;
+            (0, session_js_1.writeSessionState)(adapter.stateDir, fresh);
+        });
+    };
+    for (;;) {
+        await wait(exports.WATCHDOG_TICK_MS);
+        try {
+            const state = (0, session_js_1.readSessionState)(adapter.stateDir, sessionId);
+            if (!state)
+                return;
+            if (state.watchdogPid && state.watchdogPid !== selfPid)
+                return;
+            if (rejected || state.offlineDeliveryStopped) {
+                await finish(true, true);
+                return;
+            }
+            if (heartbeatRejected) {
+                await finish();
+                return;
+            }
+            if (!state.offline && !state.agentPid) {
+                if (++unknownTicks >= 3) {
+                    await finish();
+                    return;
+                }
+                continue;
+            }
+            const terminal = state.offline || !isAlive({ pid: state.agentPid, startedAt: state.agentStartedAt });
+            if (terminal) {
+                if (state.offline && (state.pushedRev ?? 0) >= (state.rev ?? 0)) {
+                    await finish();
+                    return;
+                }
+                const startedAt = await (0, lock_js_1.withStateLock)((0, session_js_1.stateFilePath)(adapter.stateDir, sessionId), () => {
+                    const fresh = (0, session_js_1.readSessionState)(adapter.stateDir, sessionId);
+                    if (!fresh ||
+                        fresh.agentPid !== state.agentPid ||
+                        (fresh.watchdogPid && fresh.watchdogPid !== selfPid))
+                        return undefined;
+                    if (!fresh.offline) {
+                        fresh.offline = true;
+                        fresh.rev = (fresh.rev ?? 0) + 1;
+                    }
+                    fresh.offlineRetryStartedAt ??= now();
+                    (0, session_js_1.writeSessionState)(adapter.stateDir, fresh);
+                    return fresh.offlineRetryStartedAt;
+                });
+                if (startedAt === undefined)
+                    continue;
+                if (now() - startedAt >= exports.WATCHDOG_OFFLINE_RETRY_MS) {
+                    await finish(true, true);
+                    return;
+                }
+                if (await (0, session_js_1.flushSession)(adapter, config, sessionId, delivery)) {
+                    await finish();
+                    return;
+                }
+            }
+            else if ((state.rev ?? 0) > (state.pushedRev ?? 0) ||
+                now() - (state.lastPushAt ?? 0) >= exports.WATCHDOG_HEARTBEAT_MS) {
+                await (0, session_js_1.flushSession)(adapter, config, sessionId, {
+                    ...deps,
+                    force: true,
+                    onResult: (result) => {
+                        if (!result.success && [400, 401, 403, 404].includes(result.statusCode ?? 0))
+                            heartbeatRejected = true;
+                        deps.onResult?.(result);
+                    },
+                });
+                if (heartbeatRejected) {
+                    // A rejected heartbeat is not evidence the agent died. A later hook
+                    // can restart observation after credentials/routing recover.
+                    await finish();
+                    return;
+                }
+            }
+            if (rejected) {
+                await finish(true, true);
+                return;
+            }
+        }
+        catch {
+            // A transient state-lock/filesystem error must not kill an otherwise live observer.
+            continue;
+        }
+    }
+}
+//# sourceMappingURL=watchdog.js.map

package/dist/cjs/npcs/claude-code/defaults.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULTS = void 0;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+exports.DEFAULTS = {
+    stateDir: (0, node_path_1.join)((0, node_os_1.tmpdir)(), 'nocville-claude-code'),
+    stateFilePrefix: 'session-',
+    stateFileMaxAge: 24 * 60 * 60 * 1000, // 24 hours
+    httpTimeout: 4000,
+    /** Watchdog-backed sessions become unknown after three minutes without a heartbeat. */
+    heartbeatSeconds: 90,
+    /** Number of recent activity lines kept in the desk-sign ticker. */
+    activityBufferSize: 8,
+    /** Coalesce same-phase activity pushes closer together than this. */
+    minPushGapMs: 1500,
+    /** Per-hook timeout written into settings.json (seconds) — a safety net only. */
+    hookTimeoutSeconds: 10,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/cjs/npcs/claude-code/hook-handler.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAUDE_HOOK_SPEC = exports.CLAUDE_ADAPTER = void 0;
+exports.deriveServiceId = deriveServiceId;
+exports.humanizeProjectName = humanizeProjectName;
+exports.lookupSessionNameFromStore = lookupSessionNameFromStore;
+exports.resolveSessionName = resolveSessionName;
+exports.handleHookEvent = handleHookEvent;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const hook_runner_js_1 = require("../agent-common/hook-runner.js");
+const session_js_1 = require("../agent-common/session.js");
+const normalize_js_1 = require("../cursor/normalize.js");
+const hook_handler_js_1 = require("../cursor/hook-handler.js");
+const defaults_js_1 = require("./defaults.js");
+const state_machine_js_1 = require("./state-machine.js");
+exports.CLAUDE_ADAPTER = {
+    command: 'claude-code',
+    label: 'Claude',
+    family: 'claude',
+    stateDir: defaults_js_1.DEFAULTS.stateDir,
+    heartbeatSeconds: defaults_js_1.DEFAULTS.heartbeatSeconds,
+    processNames: ['claude'],
+};
+/**
+ * Derive a serviceId from the session and project directory.
+ * Format: "claude-{project_name}-{session_id_prefix}" (≤100 chars).
+ */
+function deriveServiceId(sessionId, cwd) {
+    return (0, session_js_1.sanitizeServiceId)(`claude-${(0, session_js_1.projectNameOf)(cwd)}-${sessionId.slice(0, 8)}`);
+}
+/**
+ * Humanize a project dir name into a banner label: split on punctuation and
+ * title-case each word ("gridbreak" -> "Gridbreak", "my-cool-app" -> "My Cool App").
+ */
+function humanizeProjectName(cwd) {
+    const raw = (0, session_js_1.projectNameOf)(cwd);
+    const words = raw
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+    if (words.length === 0)
+        return raw;
+    return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+/** Default location of Claude Code's per-session sidecar files. */
+function sessionsStoreDir() {
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), '.claude', 'sessions');
+}
+/**
+ * Correlate a session_id to its user-facing name via the local session store.
+ * Claude Code writes ~/.claude/sessions/<pid>.json — keyed by pid, each holding
+ * `{ sessionId, name, ... }` — so we scan for the file whose sessionId matches.
+ * `dir` is injectable for testing.
+ */
+function lookupSessionNameFromStore(sessionId, dir = sessionsStoreDir()) {
+    if (!sessionId)
+        return null;
+    let files;
+    try {
+        files = (0, node_fs_1.readdirSync)(dir);
+    }
+    catch {
+        return null;
+    }
+    for (const file of files) {
+        if (!file.endsWith('.json'))
+            continue;
+        try {
+            const obj = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, file), 'utf-8'));
+            if (obj.sessionId === sessionId && typeof obj.name === 'string' && obj.name.trim()) {
+                return obj.name.trim();
+            }
+        }
+        catch {
+            // Skip unreadable / partially-written session files.
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the user-facing session name. Checked fresh only on the cheap,
+ * low-frequency events (SessionStart carries `session_title`; UserPromptSubmit
+ * falls back to the store scan) so renames propagate; otherwise the cached
+ * value is reused. Returns null when unknown (banner falls back to the project).
+ */
+function resolveSessionName(event, cached, dir) {
+    const name = (0, state_machine_js_1.eventName)(event);
+    const shouldRefresh = name === 'SessionStart' || name === 'UserPromptSubmit' || !cached;
+    if (!shouldRefresh)
+        return cached;
+    const fromPayload = typeof event.session_title === 'string' ? event.session_title.trim() : '';
+    if (fromPayload)
+        return fromPayload;
+    return lookupSessionNameFromStore(event.session_id ?? '', dir) ?? cached;
+}
+exports.CLAUDE_HOOK_SPEC = {
+    adapter: exports.CLAUDE_ADAPTER,
+    serviceIdFor: deriveServiceId,
+    transition: (event, prev) => (0, state_machine_js_1.claudeTransition)(event, prev),
+    resolveName: (event, prev) => {
+        // Only scan the store on the low-frequency events; never on PreToolUse.
+        const name = (0, state_machine_js_1.eventName)(event);
+        if (prev && name !== 'SessionStart' && name !== 'UserPromptSubmit')
+            return undefined;
+        return resolveSessionName(event, prev?.name ?? null) ?? undefined;
+    },
+};
+/**
+ * Handle a single Claude Code hook event.
+ *
+ * Reads the JSON payload (from `rawInput` if provided, else stdin), updates the
+ * per-session state file, and pushes an NPC status update (banner
+ * "Claude · <session name or project>"). Defaults to an in-process push; the CLI
+ * passes `mode: 'detach'` so the push runs in a background process. Never throws.
+ */
+async function handleHookEvent(config, rawInput, opts = {}) {
+    const input = rawInput ?? (0, hook_runner_js_1.readStdin)();
+    let event;
+    try {
+        event = JSON.parse(input);
+    }
+    catch {
+        return;
+    }
+    if (!event || typeof event !== 'object' || Array.isArray(event))
+        return;
+    if ((0, normalize_js_1.isCursorInvocation)(event)) {
+        await (0, hook_handler_js_1.handleCursorHookEvent)(config, event, opts, 'third-party');
+        return;
+    }
+    await (0, hook_runner_js_1.runAgentHook)(exports.CLAUDE_HOOK_SPEC, config, event, {
+        minPushGapMs: defaults_js_1.DEFAULTS.minPushGapMs,
+        ...opts,
+    });
+}
+//# sourceMappingURL=hook-handler.js.map

package/dist/cjs/npcs/claude-code/index.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClaudeCodeNPC = exports.uninstallHooks = exports.setupHooks = exports.CLAUDE_ADAPTER = exports.handleHookEvent = exports.claudeTransition = exports.processHookEvent = exports.DEFAULTS = void 0;
+exports.handleClaudeCodeCommand = handleClaudeCodeCommand;
+const config_js_1 = require("../../core/config.js");
+const hook_runner_js_1 = require("../agent-common/hook-runner.js");
+const watchdog_js_1 = require("../agent-common/watchdog.js");
+const session_js_1 = require("../agent-common/session.js");
+const defaults_js_1 = require("./defaults.js");
+const hook_handler_js_1 = require("./hook-handler.js");
+const setup_js_1 = require("./setup.js");
+var defaults_js_2 = require("./defaults.js");
+Object.defineProperty(exports, "DEFAULTS", { enumerable: true, get: function () { return defaults_js_2.DEFAULTS; } });
+var state_machine_js_1 = require("./state-machine.js");
+Object.defineProperty(exports, "processHookEvent", { enumerable: true, get: function () { return state_machine_js_1.processHookEvent; } });
+Object.defineProperty(exports, "claudeTransition", { enumerable: true, get: function () { return state_machine_js_1.claudeTransition; } });
+var hook_handler_js_2 = require("./hook-handler.js");
+Object.defineProperty(exports, "handleHookEvent", { enumerable: true, get: function () { return hook_handler_js_2.handleHookEvent; } });
+Object.defineProperty(exports, "CLAUDE_ADAPTER", { enumerable: true, get: function () { return hook_handler_js_2.CLAUDE_ADAPTER; } });
+var setup_js_2 = require("./setup.js");
+Object.defineProperty(exports, "setupHooks", { enumerable: true, get: function () { return setup_js_2.setupHooks; } });
+Object.defineProperty(exports, "uninstallHooks", { enumerable: true, get: function () { return setup_js_2.uninstallHooks; } });
+/** Remove stale session state files. */
+async function cleanupStateFiles() {
+    const removed = await (0, session_js_1.cleanupSessionStates)(defaults_js_1.DEFAULTS.stateDir, defaults_js_1.DEFAULTS.stateFileMaxAge);
+    console.log(`Cleanup complete: ${removed} stale file(s) removed`);
+}
+/**
+ * claude-code subcommands: setup | uninstall | hook | flush | cleanup.
+ * `hook` and `flush` are invoked by Claude Code / ourselves and must stay
+ * silent on stdout and never exit non-zero.
+ */
+async function handleClaudeCodeCommand(opts) {
+    const { subcommand, config, flags } = opts;
+    switch (subcommand) {
+        case 'setup': {
+            if (flags['uninstall']) {
+                (0, setup_js_1.uninstallHooks)();
+                break;
+            }
+            const ok = (0, setup_js_1.setupHooks)({
+                apiUrl: (0, config_js_1.stringFlag)(flags, 'api-url') ?? process.env['NOCVILLE_API_URL'],
+                apiKey: (0, config_js_1.stringFlag)(flags, 'api-key') ?? process.env['NOCVILLE_API_KEY'],
+                map: (0, config_js_1.stringFlag)(flags, 'map'),
+                cliPath: process.argv[1],
+                debug: config.debug,
+            });
+            if (!ok)
+                process.exitCode = 1;
+            break;
+        }
+        case 'uninstall':
+            (0, setup_js_1.uninstallHooks)();
+            break;
+        case 'hook':
+            await (0, hook_handler_js_1.handleHookEvent)(config, (0, hook_runner_js_1.readStdin)(), { mode: 'detach' });
+            break;
+        case 'watchdog':
+            await (0, watchdog_js_1.runWatchdog)(hook_handler_js_1.CLAUDE_ADAPTER, config, opts.args?.[0]);
+            break;
+        case 'flush':
+            await (0, hook_runner_js_1.runFlushCommand)(hook_handler_js_1.CLAUDE_ADAPTER, config, opts.args?.[0], (0, config_js_1.numberFlag)(flags, 'delay'), flags['stats'] === true);
+            break;
+        case 'cleanup':
+            await cleanupStateFiles();
+            break;
+        default: {
+            console.error(`Unknown claude-code subcommand: ${subcommand}`);
+            console.error('Available subcommands: setup, uninstall, hook, cleanup');
+            process.exitCode = 1;
+        }
+    }
+}
+/**
+ * ClaudeCodeNPC class for programmatic use.
+ */
+class ClaudeCodeNPC {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Process a hook event from stdin (in-process push). */
+    async handleHook() {
+        await (0, hook_handler_js_1.handleHookEvent)(this.config);
+    }
+    /** Install hooks into Claude Code settings. */
+    setup() {
+        (0, setup_js_1.setupHooks)({
+            apiUrl: this.config.apiUrl,
+            apiKey: this.config.apiKey,
+            debug: this.config.debug,
+        });
+    }
+    /** Remove all Nocville hooks from Claude Code settings. */
+    uninstall() {
+        (0, setup_js_1.uninstallHooks)();
+    }
+    /** Clean up stale session state files. */
+    async cleanup() {
+        await cleanupStateFiles();
+    }
+}
+exports.ClaudeCodeNPC = ClaudeCodeNPC;
+//# sourceMappingURL=index.js.map

package/dist/cjs/npcs/claude-code/setup.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findExistingNocvilleCommand = exports.CLAUDE_HOOK_EVENTS = exports.extractFlag = void 0;
+exports.claudeSettingsPath = claudeSettingsPath;
+exports.installHooksInto = installHooksInto;
+exports.removeHooksFrom = removeHooksFrom;
+exports.buildHookCommand = buildHookCommand;
+exports.legacyCredentials = legacyCredentials;
+exports.setupHooks = setupHooks;
+exports.uninstallHooks = uninstallHooks;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const user_config_js_1 = require("../../core/user-config.js");
+const hook_settings_js_1 = require("../agent-common/hook-settings.js");
+const shim_js_1 = require("../agent-common/shim.js");
+const runtime_js_1 = require("../agent-common/runtime.js");
+const defaults_js_1 = require("./defaults.js");
+var hook_settings_js_2 = require("../agent-common/hook-settings.js");
+Object.defineProperty(exports, "extractFlag", { enumerable: true, get: function () { return hook_settings_js_2.extractFlag; } });
+function claudeSettingsPath() {
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), '.claude', 'settings.json');
+}
+/**
+ * Hook events to install. Verified against code.claude.com/docs/en/hooks —
+ * all exist; events without matcher support ignore the empty matcher.
+ */
+exports.CLAUDE_HOOK_EVENTS = [
+    'SessionStart',
+    'SessionEnd',
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'PermissionRequest',
+    'Notification',
+    'Stop',
+    'SubagentStart',
+    'SubagentStop',
+    'PreCompact',
+];
+/** Install the nocville group into every Claude Code event. Mutates `settings`. */
+function installHooksInto(settings, command, opts = {}) {
+    return (0, hook_settings_js_1.installHookGroups)(settings, command, exports.CLAUDE_HOOK_EVENTS, {
+        perEvent: Object.fromEntries(exports.CLAUDE_HOOK_EVENTS.map((event) => [
+            event,
+            {
+                ...((opts.platform ?? process.platform) === 'win32' ? { shell: 'powershell' } : {}),
+                ...(event === 'SessionEnd'
+                    ? { timeout: 5 }
+                    : { async: true, timeout: opts.timeout ?? 10 }),
+            },
+        ])),
+    });
+}
+/** Remove all nocville entries (nested or legacy flat). Mutates `settings`. */
+function removeHooksFrom(settings) {
+    return (0, hook_settings_js_1.removeHookGroups)(settings);
+}
+var hook_settings_js_3 = require("../agent-common/hook-settings.js");
+Object.defineProperty(exports, "findExistingNocvilleCommand", { enumerable: true, get: function () { return hook_settings_js_3.findNocvilleCommand; } });
+/** `'<node>' '<cli.js>' claude-code hook # nocville-npc-hook` — no key on the command line. */
+function buildHookCommand(_cliPath) {
+    return (0, hook_settings_js_1.buildShimHookCommand)('claude-code');
+}
+/**
+ * Credentials embedded in a legacy hook command (`--api-url=… --api-key=…`),
+ * so upgrading setup can move them into the user config.
+ */
+function legacyCredentials(settings) {
+    const prev = (0, hook_settings_js_1.findNocvilleCommand)(settings);
+    if (!prev)
+        return {};
+    return { apiUrl: (0, hook_settings_js_1.extractFlag)(prev, 'api-url'), apiKey: (0, hook_settings_js_1.extractFlag)(prev, 'api-key') };
+}
+function out(opts, msg) {
+    if (!opts.quiet)
+        console.log(msg);
+}
+/**
+ * Install Nocville hooks into Claude Code settings (matcher-group format,
+ * absolute node/cli paths, 10s timeout safety net). Idempotent: migrates and
+ * de-duplicates legacy entries and moves any legacy inline credentials into
+ * ~/.config/nocville/config.json. Returns false if setup could not complete.
+ */
+function setupHooks(opts) {
+    const settingsPath = opts.settingsPath ?? claudeSettingsPath();
+    const dir = (0, node_path_1.join)(settingsPath, '..');
+    if (!(0, node_fs_1.existsSync)(dir)) {
+        console.error(`${dir} does not exist — is Claude Code installed? Skipping Claude Code setup.`);
+        return false;
+    }
+    const settings = (0, hook_settings_js_1.readJsonFile)(settingsPath);
+    if (settings === null) {
+        console.error(`Could not parse ${settingsPath}; fix it (or move it aside) and re-run setup.`);
+        return false;
+    }
+    const creds = (0, user_config_js_1.persistCredentials)(opts, legacyCredentials(settings));
+    const resolved = (0, hook_settings_js_1.resolveCliPath)(opts.cliPath);
+    const cliPath = (0, runtime_js_1.ensureStableCliPath)(resolved);
+    (0, shim_js_1.installHookShim)((0, hook_settings_js_1.stableNodePath)(), cliPath);
+    const command = buildHookCommand(cliPath);
+    const { migrated, installed } = installHooksInto(settings, command, {
+        timeout: defaults_js_1.DEFAULTS.hookTimeoutSeconds,
+    });
+    (0, hook_settings_js_1.writeJsonFile)(settingsPath, settings);
+    out(opts, `✓ Claude Code: installed Nocville hooks for ${installed} events in ${settingsPath}`);
+    if (migrated > 0)
+        out(opts, `  (migrated ${migrated} legacy entr${migrated === 1 ? 'y' : 'ies'})`);
+    out(opts, `  Hook runs: ${process.execPath} ${cliPath}`);
+    out(opts, `  API: ${creds.apiUrl ?? 'https://nocville.com'}  key: ${(0, user_config_js_1.maskKey)(creds.apiKey)}`);
+    if (!creds.apiKey) {
+        out(opts, '  ⚠ No API key saved yet — run: nocville-npc init --api-key=<your team key>');
+    }
+    out(opts, '  New Claude Code sessions will appear in your office. Restart running sessions.');
+    return true;
+}
+/** Remove all Nocville hooks from Claude Code settings. */
+function uninstallHooks(opts = {}) {
+    const o = typeof opts === 'boolean' ? {} : opts;
+    const settingsPath = o.settingsPath ?? claudeSettingsPath();
+    const settings = (0, hook_settings_js_1.readJsonFile)(settingsPath);
+    if (!settings || !(0, node_fs_1.existsSync)(settingsPath)) {
+        out(o, 'Claude Code: no settings.json — nothing to remove.');
+        return 0;
+    }
+    const removed = removeHooksFrom(settings);
+    if (removed > 0)
+        (0, hook_settings_js_1.writeJsonFile)(settingsPath, settings);
+    out(o, `✓ Claude Code: removed ${removed} Nocville hook(s) from ${settingsPath}`);
+    return removed;
+}
+//# sourceMappingURL=setup.js.map