@mauribadnights/clooks 0.1.0

package/dist/migrate.js

@@ -0,0 +1,171 @@
+"use strict";
+// clooks migration utilities — convert shell hooks to HTTP hooks
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSettingsPath = getSettingsPath;
+exports.migrate = migrate;
+exports.restore = restore;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const constants_js_1 = require("./constants.js");
+const yaml_1 = require("yaml");
+/**
+ * Find the Claude Code settings.json path.
+ */
+function getSettingsPath(options) {
+    const home = options?.homeDir ?? (0, os_1.homedir)();
+    const candidates = [
+        (0, path_1.join)(home, '.claude', 'settings.local.json'),
+        (0, path_1.join)(home, '.claude', 'settings.json'),
+    ];
+    for (const candidate of candidates) {
+        if ((0, fs_1.existsSync)(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Migrate Claude Code settings.json command hooks to clooks HTTP hooks.
+ *
+ * 1. Read settings.json
+ * 2. Extract command hooks → generate manifest.yaml handler entries
+ * 3. Back up original settings.json
+ * 4. Rewrite settings with HTTP hooks pointing to localhost:7890
+ * 5. Keep SessionStart with ensure-running command hook + HTTP hook
+ */
+function migrate(options) {
+    const configDir = options?.configDir ?? constants_js_1.CONFIG_DIR;
+    const settingsBackup = options?.settingsBackup ?? constants_js_1.SETTINGS_BACKUP;
+    const settingsPath = getSettingsPath(options);
+    if (!settingsPath) {
+        throw new Error('Could not find Claude Code settings.json (checked ~/.claude/settings.json and ~/.claude/settings.local.json)');
+    }
+    const raw = (0, fs_1.readFileSync)(settingsPath, 'utf-8');
+    const settings = JSON.parse(raw);
+    if (!settings.hooks || typeof settings.hooks !== 'object') {
+        throw new Error('No hooks found in settings.json — nothing to migrate');
+    }
+    // Check if already migrated (HTTP hooks pointing to clooks inside nested rule groups)
+    const alreadyMigrated = Object.values(settings.hooks).some((ruleGroups) => ruleGroups?.some((rule) => rule.hooks?.some((e) => e.type === 'http' && e.url?.includes(`localhost:${constants_js_1.DEFAULT_PORT}`))));
+    if (alreadyMigrated) {
+        throw new Error('Settings already contain HTTP hooks pointing to clooks. Use "clooks restore" first if you want to re-migrate.');
+    }
+    // Ensure config dir exists
+    if (!(0, fs_1.existsSync)(configDir)) {
+        (0, fs_1.mkdirSync)(configDir, { recursive: true });
+    }
+    // Back up original settings
+    (0, fs_1.writeFileSync)(settingsBackup, raw, 'utf-8');
+    // Extract command hooks and build manifest
+    const manifestHandlers = {};
+    let handlerIndex = 0;
+    // NOTE: In v0.1, matchers from the original rule groups are not preserved in the
+    // migrated HTTP hooks — all command hooks are consolidated into matcher-less rule groups.
+    // This is acceptable because clooks dispatches based on event type, not matchers.
+    for (const [eventName, ruleGroups] of Object.entries(settings.hooks)) {
+        if (!constants_js_1.HOOK_EVENTS.includes(eventName) || !Array.isArray(ruleGroups))
+            continue;
+        const event = eventName;
+        // Flatten command hooks from ALL rule groups for this event
+        const commandHooks = [];
+        for (const rule of ruleGroups) {
+            if (!Array.isArray(rule.hooks))
+                continue;
+            for (const entry of rule.hooks) {
+                if (entry.type === 'command' && entry.command) {
+                    commandHooks.push(entry);
+                }
+            }
+        }
+        if (commandHooks.length === 0)
+            continue;
+        manifestHandlers[event] = commandHooks.map((hook) => {
+            handlerIndex++;
+            return {
+                id: `migrated-${event.toLowerCase()}-${handlerIndex}`,
+                type: 'script',
+                command: hook.command,
+                timeout: hook.timeout ? hook.timeout * 1000 : 5000, // Claude uses seconds, we use ms
+                enabled: true,
+            };
+        });
+    }
+    // Write manifest.yaml
+    const manifest = {
+        handlers: manifestHandlers,
+        settings: { port: constants_js_1.DEFAULT_PORT, logLevel: 'info' },
+    };
+    const yamlStr = '# clooks manifest — auto-generated by migrate\n' +
+        `# Migrated from: ${settingsPath}\n` +
+        `# Date: ${new Date().toISOString()}\n\n` +
+        (0, yaml_1.stringify)(manifest);
+    const manifestPath = (0, path_1.join)(configDir, 'manifest.yaml');
+    (0, fs_1.writeFileSync)(manifestPath, yamlStr, 'utf-8');
+    // Rewrite settings.json with HTTP hooks in the nested rule group format
+    const newHooks = {};
+    for (const eventName of constants_js_1.HOOK_EVENTS) {
+        const hadHandlers = manifestHandlers[eventName]?.length ?? 0;
+        // Also check if there were existing non-command hooks to preserve (flatten from rule groups)
+        const existingNonCommand = [];
+        for (const rule of (settings.hooks[eventName] ?? [])) {
+            if (!Array.isArray(rule.hooks))
+                continue;
+            for (const entry of rule.hooks) {
+                if (entry.type !== 'command') {
+                    existingNonCommand.push(entry);
+                }
+            }
+        }
+        if (hadHandlers === 0 && existingNonCommand.length === 0 && eventName !== 'SessionStart')
+            continue;
+        const hookEntries = [...existingNonCommand];
+        // For SessionStart, add ensure-running command hook
+        if (eventName === 'SessionStart') {
+            hookEntries.push({
+                type: 'command',
+                command: 'clooks ensure-running',
+            });
+        }
+        // Add HTTP hook
+        if (hadHandlers > 0) {
+            hookEntries.push({
+                type: 'http',
+                url: `http://localhost:${constants_js_1.DEFAULT_PORT}/hooks/${eventName}`,
+            });
+        }
+        if (hookEntries.length > 0) {
+            // Wrap in a single rule group (no matcher — clooks handles dispatch)
+            newHooks[eventName] = [{ hooks: hookEntries }];
+        }
+    }
+    // Ensure SessionStart always has ensure-running even if no hooks were migrated for it
+    if (!newHooks['SessionStart']) {
+        newHooks['SessionStart'] = [
+            { hooks: [{ type: 'command', command: 'clooks ensure-running' }] },
+        ];
+    }
+    settings.hooks = newHooks;
+    (0, fs_1.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    return {
+        manifestPath,
+        settingsPath,
+        handlersCreated: handlerIndex,
+    };
+}
+/**
+ * Restore original settings.json from backup.
+ */
+function restore(options) {
+    const settingsBackup = options?.settingsBackup ?? constants_js_1.SETTINGS_BACKUP;
+    if (!(0, fs_1.existsSync)(settingsBackup)) {
+        throw new Error('No backup found at ' + settingsBackup);
+    }
+    const settingsPath = getSettingsPath(options);
+    if (!settingsPath) {
+        throw new Error('Could not find Claude Code settings.json to restore');
+    }
+    const backup = (0, fs_1.readFileSync)(settingsBackup, 'utf-8');
+    (0, fs_1.writeFileSync)(settingsPath, backup, 'utf-8');
+    return settingsPath;
+}

package/dist/server.d.ts

@@ -0,0 +1,29 @@
+import { type Server } from 'http';
+import { MetricsCollector } from './metrics.js';
+import type { Manifest } from './types.js';
+export interface ServerContext {
+    server: Server;
+    metrics: MetricsCollector;
+    startTime: number;
+    manifest: Manifest;
+}
+/**
+ * Create the HTTP server for hook handling.
+ */
+export declare function createServer(manifest: Manifest, metrics: MetricsCollector): ServerContext;
+/**
+ * Start the daemon: bind the server and write PID file.
+ */
+export declare function startDaemon(manifest: Manifest, metrics: MetricsCollector): Promise<ServerContext>;
+/**
+ * Stop a running daemon by reading PID file and sending SIGTERM.
+ */
+export declare function stopDaemon(): boolean;
+/**
+ * Check if daemon is currently running.
+ */
+export declare function isDaemonRunning(): boolean;
+/**
+ * Start daemon as a detached background process.
+ */
+export declare function startDaemonBackground(): void;

package/dist/server.js

@@ -0,0 +1,266 @@
+"use strict";
+// clooks HTTP server — persistent hook daemon
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServer = createServer;
+exports.startDaemon = startDaemon;
+exports.stopDaemon = stopDaemon;
+exports.isDaemonRunning = isDaemonRunning;
+exports.startDaemonBackground = startDaemonBackground;
+const http_1 = require("http");
+const fs_1 = require("fs");
+const child_process_1 = require("child_process");
+const handlers_js_1 = require("./handlers.js");
+const constants_js_1 = require("./constants.js");
+function log(msg) {
+    const line = `[${new Date().toISOString()}] ${msg}\n`;
+    try {
+        if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
+            (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
+        }
+        (0, fs_1.appendFileSync)(constants_js_1.LOG_FILE, line, 'utf-8');
+    }
+    catch {
+        // If we can't write logs, continue anyway
+    }
+}
+/**
+ * Merge multiple handler results into a single HTTP response body.
+ *
+ * - additionalContext: joined with newlines from all results that have it
+ * - hookSpecificOutput: last writer wins
+ * - decision/reason: last writer wins (for PostToolUse/Stop block decisions)
+ */
+function mergeResults(results) {
+    const merged = {};
+    const contexts = [];
+    for (const result of results) {
+        if (!result.ok || !result.output || typeof result.output !== 'object')
+            continue;
+        const out = result.output;
+        if (typeof out.additionalContext === 'string' && out.additionalContext) {
+            contexts.push(out.additionalContext);
+        }
+        if (out.hookSpecificOutput !== undefined) {
+            merged.hookSpecificOutput = out.hookSpecificOutput;
+        }
+        if (out.decision !== undefined) {
+            merged.decision = out.decision;
+        }
+        if (out.reason !== undefined) {
+            merged.reason = out.reason;
+        }
+    }
+    if (contexts.length > 0) {
+        merged.additionalContext = contexts.join('\n');
+    }
+    return merged;
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.on('data', (chunk) => {
+            body += chunk.toString();
+        });
+        req.on('end', () => resolve(body));
+        req.on('error', reject);
+    });
+}
+function sendJson(res, status, data) {
+    const body = JSON.stringify(data);
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+    });
+    res.end(body);
+}
+/**
+ * Create the HTTP server for hook handling.
+ */
+function createServer(manifest, metrics) {
+    const startTime = Date.now();
+    const server = (0, http_1.createServer)(async (req, res) => {
+        const url = req.url ?? '/';
+        const method = req.method ?? 'GET';
+        // Health check endpoint
+        if (method === 'GET' && url === '/health') {
+            const handlerCount = Object.values(manifest.handlers)
+                .reduce((sum, arr) => sum + (arr?.length ?? 0), 0);
+            sendJson(res, 200, {
+                status: 'ok',
+                uptime: Math.floor((Date.now() - startTime) / 1000),
+                handlers_loaded: handlerCount,
+                port: manifest.settings?.port ?? constants_js_1.DEFAULT_PORT,
+            });
+            return;
+        }
+        // Hook endpoint: POST /hooks/:eventName
+        const hookMatch = url.match(/^\/hooks\/([A-Za-z]+)$/);
+        if (method === 'POST' && hookMatch) {
+            const eventName = hookMatch[1];
+            if (!constants_js_1.HOOK_EVENTS.includes(eventName)) {
+                sendJson(res, 400, { error: `Unknown hook event: ${eventName}` });
+                return;
+            }
+            const event = eventName;
+            const handlers = manifest.handlers[event] ?? [];
+            if (handlers.length === 0) {
+                sendJson(res, 200, {});
+                return;
+            }
+            let input;
+            try {
+                const body = await readBody(req);
+                input = JSON.parse(body);
+            }
+            catch (err) {
+                log(`Failed to parse request body for ${eventName}: ${err}`);
+                sendJson(res, 400, { error: 'Invalid JSON body' });
+                return;
+            }
+            log(`Hook: ${eventName} (${handlers.length} handler${handlers.length > 1 ? 's' : ''})`);
+            try {
+                const results = await (0, handlers_js_1.executeHandlers)(event, input, handlers);
+                // Record metrics
+                for (const result of results) {
+                    metrics.record({
+                        ts: new Date().toISOString(),
+                        event,
+                        handler: result.id,
+                        duration_ms: result.duration_ms,
+                        ok: result.ok,
+                        error: result.error,
+                    });
+                }
+                const merged = mergeResults(results);
+                log(`  -> ${results.filter((r) => r.ok).length}/${results.length} ok, response keys: ${Object.keys(merged).join(', ') || '(empty)'}`);
+                sendJson(res, 200, merged);
+            }
+            catch (err) {
+                log(`Error executing handlers for ${eventName}: ${err}`);
+                sendJson(res, 500, { error: 'Internal handler error' });
+            }
+            return;
+        }
+        // 404 for everything else
+        sendJson(res, 404, { error: 'Not found' });
+    });
+    return { server, metrics, startTime, manifest };
+}
+/**
+ * Start the daemon: bind the server and write PID file.
+ */
+function startDaemon(manifest, metrics) {
+    return new Promise((resolve, reject) => {
+        const ctx = createServer(manifest, metrics);
+        const port = manifest.settings?.port ?? constants_js_1.DEFAULT_PORT;
+        ctx.server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                log(`Port ${port} already in use`);
+                reject(new Error(`Port ${port} is already in use. Is another clooks instance running?`));
+            }
+            else {
+                log(`Server error: ${err.message}`);
+                reject(err);
+            }
+        });
+        ctx.server.listen(port, '127.0.0.1', () => {
+            // Write PID file
+            if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
+                (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
+            }
+            (0, fs_1.writeFileSync)(constants_js_1.PID_FILE, String(process.pid), 'utf-8');
+            log(`Daemon started on 127.0.0.1:${port} (pid ${process.pid})`);
+            resolve(ctx);
+        });
+        // Graceful shutdown
+        const shutdown = () => {
+            log('Shutting down...');
+            ctx.server.close(() => {
+                try {
+                    if ((0, fs_1.existsSync)(constants_js_1.PID_FILE))
+                        (0, fs_1.unlinkSync)(constants_js_1.PID_FILE);
+                }
+                catch {
+                    // ignore
+                }
+                metrics.flush();
+                log('Daemon stopped.');
+                process.exit(0);
+            });
+            // Force exit after 5s
+            setTimeout(() => {
+                process.exit(1);
+            }, 5000);
+        };
+        process.on('SIGTERM', shutdown);
+        process.on('SIGINT', shutdown);
+    });
+}
+/**
+ * Stop a running daemon by reading PID file and sending SIGTERM.
+ */
+function stopDaemon() {
+    if (!(0, fs_1.existsSync)(constants_js_1.PID_FILE)) {
+        return false;
+    }
+    const pidStr = (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim();
+    const pid = parseInt(pidStr, 10);
+    if (isNaN(pid)) {
+        (0, fs_1.unlinkSync)(constants_js_1.PID_FILE);
+        return false;
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch (err) {
+        // Process doesn't exist — clean up stale PID
+        try {
+            (0, fs_1.unlinkSync)(constants_js_1.PID_FILE);
+        }
+        catch {
+            // ignore
+        }
+        return false;
+    }
+    // Give it a moment, then clean up PID file
+    // The daemon itself should remove it, but clean up just in case
+    setTimeout(() => {
+        try {
+            if ((0, fs_1.existsSync)(constants_js_1.PID_FILE))
+                (0, fs_1.unlinkSync)(constants_js_1.PID_FILE);
+        }
+        catch {
+            // ignore
+        }
+    }, 2000);
+    return true;
+}
+/**
+ * Check if daemon is currently running.
+ */
+function isDaemonRunning() {
+    if (!(0, fs_1.existsSync)(constants_js_1.PID_FILE))
+        return false;
+    const pidStr = (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim();
+    const pid = parseInt(pidStr, 10);
+    if (isNaN(pid))
+        return false;
+    try {
+        // Signal 0 tests if process exists
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Start daemon as a detached background process.
+ */
+function startDaemonBackground() {
+    const child = (0, child_process_1.spawn)(process.execPath, [process.argv[1], 'start', '--foreground'], {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+/** Hook event names supported by Claude Code */
+export type HookEvent = 'SessionStart' | 'UserPromptSubmit' | 'PreToolUse' | 'PostToolUse' | 'Stop' | 'SubagentStart' | 'SubagentStop' | 'Notification' | 'ConfigChange';
+/** Hook input payload from Claude Code */
+export interface HookInput {
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    permission_mode: string;
+    hook_event_name: HookEvent;
+    prompt?: string;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    source?: string;
+    stop_hook_active?: boolean;
+    [key: string]: unknown;
+}
+/** Handler types in manifest */
+export type HandlerType = 'script' | 'inline';
+/** Configuration for a single handler */
+export interface HandlerConfig {
+    id: string;
+    type: HandlerType;
+    command?: string;
+    module?: string;
+    timeout?: number;
+    enabled?: boolean;
+}
+/** The full manifest structure */
+export interface Manifest {
+    handlers: Partial<Record<HookEvent, HandlerConfig[]>>;
+    settings?: {
+        port?: number;
+        logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    };
+}
+/** Result from executing a single handler */
+export interface HandlerResult {
+    id: string;
+    ok: boolean;
+    output?: unknown;
+    error?: string;
+    duration_ms: number;
+}
+/** A single metrics entry */
+export interface MetricEntry {
+    ts: string;
+    event: HookEvent;
+    handler: string;
+    duration_ms: number;
+    ok: boolean;
+    error?: string;
+}
+/** Runtime state for tracking consecutive failures */
+export interface HandlerState {
+    consecutiveFailures: number;
+    disabled: boolean;
+    totalFires: number;
+    totalErrors: number;
+}
+/** Diagnostic result from doctor checks */
+export interface DiagnosticResult {
+    check: string;
+    status: 'ok' | 'warn' | 'error';
+    message: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// clooks type definitions
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mauribadnights/clooks",
+  "version": "0.1.0",
+  "description": "Persistent hook runtime for Claude Code — eliminates process spawning overhead and gives you observability",
+  "bin": {
+    "clooks": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "license": "MIT",
+  "author": "mauribadnights",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mauribadnights/clooks.git"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "hooks",
+    "daemon",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "commander": "^14.0.3",
+    "yaml": "^2.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
+  }
+}