@nocville/npc 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,144 @@
+import { isAgentAlive } from './liveness.js';
+import { withStateLock } from './lock.js';
+import { flushSession, readSessionState, sleep, spawnDetachedAgent, stateFilePath, writeSessionState, } from './session.js';
+export const WATCHDOG_TICK_MS = 15_000;
+export const WATCHDOG_HEARTBEAT_MS = 60_000;
+export const WATCHDOG_OFFLINE_RETRY_MS = 15 * 60_000;
+export async function ensureWatchdog(adapter, config, sessionId, cliPath, lockWaitMs) {
+    if (adapter.processNames?.length === 0 ||
+        !config.apiKey ||
+        process.env['NOCVILLE_NO_WATCHDOG'] === '1')
+        return;
+    await withStateLock(stateFilePath(adapter.stateDir, sessionId), () => {
+        const state = 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 && isAgentAlive({ pid: state.watchdogPid }))
+            return;
+        const pid = spawnDetachedAgent(adapter, config, ['watchdog', sessionId], cliPath);
+        if (pid) {
+            state.watchdogPid = pid;
+            writeSessionState(adapter.stateDir, state);
+        }
+    }, lockWaitMs);
+}
+/** Silent, read-only observer of the agent process; never sends input to it. */
+export async function runWatchdog(adapter, config, sessionId, deps = {}) {
+    if (!sessionId || adapter.processNames?.length === 0)
+        return;
+    const isAlive = deps.isAlive ?? isAgentAlive;
+    const now = deps.now ?? Date.now;
+    const wait = deps.wait ?? 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 withStateLock(stateFilePath(adapter.stateDir, sessionId), () => {
+            const fresh = 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;
+            writeSessionState(adapter.stateDir, fresh);
+        });
+    };
+    for (;;) {
+        await wait(WATCHDOG_TICK_MS);
+        try {
+            const state = 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 withStateLock(stateFilePath(adapter.stateDir, sessionId), () => {
+                    const fresh = 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();
+                    writeSessionState(adapter.stateDir, fresh);
+                    return fresh.offlineRetryStartedAt;
+                });
+                if (startedAt === undefined)
+                    continue;
+                if (now() - startedAt >= WATCHDOG_OFFLINE_RETRY_MS) {
+                    await finish(true, true);
+                    return;
+                }
+                if (await flushSession(adapter, config, sessionId, delivery)) {
+                    await finish();
+                    return;
+                }
+            }
+            else if ((state.rev ?? 0) > (state.pushedRev ?? 0) ||
+                now() - (state.lastPushAt ?? 0) >= WATCHDOG_HEARTBEAT_MS) {
+                await 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/npcs/claude-code/defaults.d.ts

@@ -0,0 +1,15 @@
+export declare const DEFAULTS: {
+    stateDir: string;
+    stateFilePrefix: string;
+    stateFileMaxAge: number;
+    httpTimeout: number;
+    /** Watchdog-backed sessions become unknown after three minutes without a heartbeat. */
+    heartbeatSeconds: number;
+    /** Number of recent activity lines kept in the desk-sign ticker. */
+    activityBufferSize: number;
+    /** Coalesce same-phase activity pushes closer together than this. */
+    minPushGapMs: number;
+    /** Per-hook timeout written into settings.json (seconds) — a safety net only. */
+    hookTimeoutSeconds: number;
+};
+//# sourceMappingURL=defaults.d.ts.map

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

@@ -0,0 +1,17 @@
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const DEFAULTS = {
+    stateDir: join(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/npcs/claude-code/hook-handler.d.ts

@@ -0,0 +1,40 @@
+import type { NpcConfig } from '../../core/types.js';
+import type { AgentHookSpec, HookRunOptions } from '../agent-common/hook-runner.js';
+import type { AgentAdapter } from '../agent-common/session.js';
+import type { HookEvent } from './state-machine.js';
+export declare const CLAUDE_ADAPTER: AgentAdapter;
+/**
+ * Derive a serviceId from the session and project directory.
+ * Format: "claude-{project_name}-{session_id_prefix}" (≤100 chars).
+ */
+export declare function deriveServiceId(sessionId: string, cwd: string): string;
+/**
+ * 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").
+ */
+export declare function humanizeProjectName(cwd: string): string;
+/**
+ * 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.
+ */
+export declare function lookupSessionNameFromStore(sessionId: string, dir?: string): string | 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).
+ */
+export declare function resolveSessionName(event: HookEvent, cached: string | null, dir?: string): string | null;
+export declare const CLAUDE_HOOK_SPEC: AgentHookSpec;
+/**
+ * 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.
+ */
+export declare function handleHookEvent(config: NpcConfig, rawInput?: string, opts?: HookRunOptions): Promise<void>;
+//# sourceMappingURL=hook-handler.d.ts.map

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

@@ -0,0 +1,131 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { runAgentHook, readStdin } from '../agent-common/hook-runner.js';
+import { projectNameOf, sanitizeServiceId } from '../agent-common/session.js';
+import { isCursorInvocation } from '../cursor/normalize.js';
+import { handleCursorHookEvent } from '../cursor/hook-handler.js';
+import { DEFAULTS } from './defaults.js';
+import { claudeTransition, eventName } from './state-machine.js';
+export const CLAUDE_ADAPTER = {
+    command: 'claude-code',
+    label: 'Claude',
+    family: 'claude',
+    stateDir: DEFAULTS.stateDir,
+    heartbeatSeconds: DEFAULTS.heartbeatSeconds,
+    processNames: ['claude'],
+};
+/**
+ * Derive a serviceId from the session and project directory.
+ * Format: "claude-{project_name}-{session_id_prefix}" (≤100 chars).
+ */
+export function deriveServiceId(sessionId, cwd) {
+    return sanitizeServiceId(`claude-${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").
+ */
+export function humanizeProjectName(cwd) {
+    const raw = 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 join(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.
+ */
+export function lookupSessionNameFromStore(sessionId, dir = sessionsStoreDir()) {
+    if (!sessionId)
+        return null;
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    for (const file of files) {
+        if (!file.endsWith('.json'))
+            continue;
+        try {
+            const obj = JSON.parse(readFileSync(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).
+ */
+export function resolveSessionName(event, cached, dir) {
+    const name = 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;
+}
+export const CLAUDE_HOOK_SPEC = {
+    adapter: CLAUDE_ADAPTER,
+    serviceIdFor: deriveServiceId,
+    transition: (event, prev) => claudeTransition(event, prev),
+    resolveName: (event, prev) => {
+        // Only scan the store on the low-frequency events; never on PreToolUse.
+        const name = 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.
+ */
+export async function handleHookEvent(config, rawInput, opts = {}) {
+    const input = rawInput ?? readStdin();
+    let event;
+    try {
+        event = JSON.parse(input);
+    }
+    catch {
+        return;
+    }
+    if (!event || typeof event !== 'object' || Array.isArray(event))
+        return;
+    if (isCursorInvocation(event)) {
+        await handleCursorHookEvent(config, event, opts, 'third-party');
+        return;
+    }
+    await runAgentHook(CLAUDE_HOOK_SPEC, config, event, {
+        minPushGapMs: DEFAULTS.minPushGapMs,
+        ...opts,
+    });
+}
+//# sourceMappingURL=hook-handler.js.map

package/dist/npcs/claude-code/index.d.ts

@@ -0,0 +1,36 @@
+import type { NpcConfig } from '../../core/types.js';
+export { DEFAULTS } from './defaults.js';
+export { processHookEvent, claudeTransition } from './state-machine.js';
+export type { SessionState, HookEvent, StatusOutput, SessionMachineState, } from './state-machine.js';
+export { handleHookEvent, CLAUDE_ADAPTER } from './hook-handler.js';
+export { setupHooks, uninstallHooks } from './setup.js';
+export type { SetupOptions } from './setup.js';
+export interface ClaudeCodeSubcommandOptions {
+    subcommand: string;
+    config: NpcConfig;
+    flags: Record<string, string | boolean>;
+    /** Positional args after the subcommand (e.g. the session id for `flush`). */
+    args?: string[];
+}
+/**
+ * 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.
+ */
+export declare function handleClaudeCodeCommand(opts: ClaudeCodeSubcommandOptions): Promise<void>;
+/**
+ * ClaudeCodeNPC class for programmatic use.
+ */
+export declare class ClaudeCodeNPC {
+    private config;
+    constructor(config: NpcConfig);
+    /** Process a hook event from stdin (in-process push). */
+    handleHook(): Promise<void>;
+    /** Install hooks into Claude Code settings. */
+    setup(): void;
+    /** Remove all Nocville hooks from Claude Code settings. */
+    uninstall(): void;
+    /** Clean up stale session state files. */
+    cleanup(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,92 @@
+import { numberFlag, stringFlag } from '../../core/config.js';
+import { readStdin, runFlushCommand } from '../agent-common/hook-runner.js';
+import { runWatchdog } from '../agent-common/watchdog.js';
+import { cleanupSessionStates } from '../agent-common/session.js';
+import { DEFAULTS } from './defaults.js';
+import { CLAUDE_ADAPTER, handleHookEvent } from './hook-handler.js';
+import { setupHooks, uninstallHooks } from './setup.js';
+export { DEFAULTS } from './defaults.js';
+export { processHookEvent, claudeTransition } from './state-machine.js';
+export { handleHookEvent, CLAUDE_ADAPTER } from './hook-handler.js';
+export { setupHooks, uninstallHooks } from './setup.js';
+/** Remove stale session state files. */
+async function cleanupStateFiles() {
+    const removed = await cleanupSessionStates(DEFAULTS.stateDir, 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.
+ */
+export async function handleClaudeCodeCommand(opts) {
+    const { subcommand, config, flags } = opts;
+    switch (subcommand) {
+        case 'setup': {
+            if (flags['uninstall']) {
+                uninstallHooks();
+                break;
+            }
+            const ok = setupHooks({
+                apiUrl: stringFlag(flags, 'api-url') ?? process.env['NOCVILLE_API_URL'],
+                apiKey: stringFlag(flags, 'api-key') ?? process.env['NOCVILLE_API_KEY'],
+                map: stringFlag(flags, 'map'),
+                cliPath: process.argv[1],
+                debug: config.debug,
+            });
+            if (!ok)
+                process.exitCode = 1;
+            break;
+        }
+        case 'uninstall':
+            uninstallHooks();
+            break;
+        case 'hook':
+            await handleHookEvent(config, readStdin(), { mode: 'detach' });
+            break;
+        case 'watchdog':
+            await runWatchdog(CLAUDE_ADAPTER, config, opts.args?.[0]);
+            break;
+        case 'flush':
+            await runFlushCommand(CLAUDE_ADAPTER, config, opts.args?.[0], 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.
+ */
+export class ClaudeCodeNPC {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Process a hook event from stdin (in-process push). */
+    async handleHook() {
+        await handleHookEvent(this.config);
+    }
+    /** Install hooks into Claude Code settings. */
+    setup() {
+        setupHooks({
+            apiUrl: this.config.apiUrl,
+            apiKey: this.config.apiKey,
+            debug: this.config.debug,
+        });
+    }
+    /** Remove all Nocville hooks from Claude Code settings. */
+    uninstall() {
+        uninstallHooks();
+    }
+    /** Clean up stale session state files. */
+    async cleanup() {
+        await cleanupStateFiles();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/npcs/claude-code/setup.d.ts

@@ -0,0 +1,58 @@
+import type { HooksFile } from '../agent-common/hook-settings.js';
+export { extractFlag } from '../agent-common/hook-settings.js';
+export declare function claudeSettingsPath(): string;
+/**
+ * Hook events to install. Verified against code.claude.com/docs/en/hooks —
+ * all exist; events without matcher support ignore the empty matcher.
+ */
+export declare const CLAUDE_HOOK_EVENTS: readonly ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionRequest", "Notification", "Stop", "SubagentStart", "SubagentStop", "PreCompact"];
+export interface SetupOptions {
+    /** Explicit --api-url (or env). Saved to the user config. */
+    apiUrl?: string;
+    /** Explicit --api-key (or env). Saved to the user config. */
+    apiKey?: string;
+    /** Explicit --map. Saved to the user config. */
+    map?: string;
+    /** Absolute path to the built cli.js; defaults to the running script. */
+    cliPath?: string;
+    /** Override ~/.claude/settings.json (tests). */
+    settingsPath?: string;
+    debug?: boolean;
+    /** Suppress console output (tests). */
+    quiet?: boolean;
+}
+type ClaudeSettings = HooksFile;
+/** Install the nocville group into every Claude Code event. Mutates `settings`. */
+export declare function installHooksInto(settings: ClaudeSettings, command: string, opts?: {
+    timeout?: number;
+    platform?: NodeJS.Platform;
+}): {
+    migrated: number;
+    installed: number;
+};
+/** Remove all nocville entries (nested or legacy flat). Mutates `settings`. */
+export declare function removeHooksFrom(settings: ClaudeSettings): number;
+export { findNocvilleCommand as findExistingNocvilleCommand } from '../agent-common/hook-settings.js';
+/** `'<node>' '<cli.js>' claude-code hook # nocville-npc-hook` — no key on the command line. */
+export declare function buildHookCommand(_cliPath: string): string;
+/**
+ * Credentials embedded in a legacy hook command (`--api-url=… --api-key=…`),
+ * so upgrading setup can move them into the user config.
+ */
+export declare function legacyCredentials(settings: ClaudeSettings): {
+    apiUrl?: string;
+    apiKey?: string;
+};
+/**
+ * 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.
+ */
+export declare function setupHooks(opts: SetupOptions): boolean;
+/** Remove all Nocville hooks from Claude Code settings. */
+export declare function uninstallHooks(opts?: {
+    settingsPath?: string;
+    quiet?: boolean;
+} | boolean): number;
+//# sourceMappingURL=setup.d.ts.map

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

@@ -0,0 +1,121 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { maskKey, persistCredentials } from '../../core/user-config.js';
+import { buildShimHookCommand, stableNodePath, extractFlag, findNocvilleCommand, installHookGroups, readJsonFile, removeHookGroups, resolveCliPath, writeJsonFile, } from '../agent-common/hook-settings.js';
+import { installHookShim } from '../agent-common/shim.js';
+import { ensureStableCliPath } from '../agent-common/runtime.js';
+import { DEFAULTS } from './defaults.js';
+export { extractFlag } from '../agent-common/hook-settings.js';
+export function claudeSettingsPath() {
+    return join(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.
+ */
+export const 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`. */
+export function installHooksInto(settings, command, opts = {}) {
+    return installHookGroups(settings, command, CLAUDE_HOOK_EVENTS, {
+        perEvent: Object.fromEntries(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`. */
+export function removeHooksFrom(settings) {
+    return removeHookGroups(settings);
+}
+export { findNocvilleCommand as findExistingNocvilleCommand } from '../agent-common/hook-settings.js';
+/** `'<node>' '<cli.js>' claude-code hook # nocville-npc-hook` — no key on the command line. */
+export function buildHookCommand(_cliPath) {
+    return buildShimHookCommand('claude-code');
+}
+/**
+ * Credentials embedded in a legacy hook command (`--api-url=… --api-key=…`),
+ * so upgrading setup can move them into the user config.
+ */
+export function legacyCredentials(settings) {
+    const prev = findNocvilleCommand(settings);
+    if (!prev)
+        return {};
+    return { apiUrl: extractFlag(prev, 'api-url'), apiKey: 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.
+ */
+export function setupHooks(opts) {
+    const settingsPath = opts.settingsPath ?? claudeSettingsPath();
+    const dir = join(settingsPath, '..');
+    if (!existsSync(dir)) {
+        console.error(`${dir} does not exist — is Claude Code installed? Skipping Claude Code setup.`);
+        return false;
+    }
+    const settings = 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 = persistCredentials(opts, legacyCredentials(settings));
+    const resolved = resolveCliPath(opts.cliPath);
+    const cliPath = ensureStableCliPath(resolved);
+    installHookShim(stableNodePath(), cliPath);
+    const command = buildHookCommand(cliPath);
+    const { migrated, installed } = installHooksInto(settings, command, {
+        timeout: DEFAULTS.hookTimeoutSeconds,
+    });
+    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: ${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. */
+export function uninstallHooks(opts = {}) {
+    const o = typeof opts === 'boolean' ? {} : opts;
+    const settingsPath = o.settingsPath ?? claudeSettingsPath();
+    const settings = readJsonFile(settingsPath);
+    if (!settings || !existsSync(settingsPath)) {
+        out(o, 'Claude Code: no settings.json — nothing to remove.');
+        return 0;
+    }
+    const removed = removeHooksFrom(settings);
+    if (removed > 0)
+        writeJsonFile(settingsPath, settings);
+    out(o, `✓ Claude Code: removed ${removed} Nocville hook(s) from ${settingsPath}`);
+    return removed;
+}
+//# sourceMappingURL=setup.js.map