@mauribadnights/clooks 0.1.0

package/dist/handlers.js

@@ -0,0 +1,192 @@
+"use strict";
+// clooks hook handlers — execution engine
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetHandlerStates = resetHandlerStates;
+exports.getHandlerStates = getHandlerStates;
+exports.executeHandlers = executeHandlers;
+exports.executeScriptHandler = executeScriptHandler;
+exports.executeInlineHandler = executeInlineHandler;
+const child_process_1 = require("child_process");
+const url_1 = require("url");
+const path_1 = require("path");
+const constants_js_1 = require("./constants.js");
+/** Runtime state per handler ID */
+const handlerStates = new Map();
+function getState(id) {
+    let state = handlerStates.get(id);
+    if (!state) {
+        state = { consecutiveFailures: 0, disabled: false, totalFires: 0, totalErrors: 0 };
+        handlerStates.set(id, state);
+    }
+    return state;
+}
+/** Reset all handler states (useful for testing) */
+function resetHandlerStates() {
+    handlerStates.clear();
+}
+/** Get a copy of the handler states map */
+function getHandlerStates() {
+    return new Map(handlerStates);
+}
+/**
+ * Execute all handlers for an event in parallel.
+ * Returns merged results array.
+ */
+async function executeHandlers(_event, input, handlers) {
+    const promises = handlers.map(async (handler) => {
+        // Skip disabled handlers (both manifest-disabled and auto-disabled)
+        if (handler.enabled === false) {
+            return { id: handler.id, ok: true, output: undefined, duration_ms: 0 };
+        }
+        const state = getState(handler.id);
+        if (state.disabled) {
+            return {
+                id: handler.id,
+                ok: false,
+                error: `Auto-disabled after ${constants_js_1.MAX_CONSECUTIVE_FAILURES} consecutive failures`,
+                duration_ms: 0,
+            };
+        }
+        state.totalFires++;
+        const start = performance.now();
+        let result;
+        try {
+            if (handler.type === 'script') {
+                result = await executeScriptHandler(handler, input);
+            }
+            else if (handler.type === 'inline') {
+                result = await executeInlineHandler(handler, input);
+            }
+            else {
+                result = {
+                    id: handler.id,
+                    ok: false,
+                    error: `Unknown handler type: ${handler.type}`,
+                    duration_ms: 0,
+                };
+            }
+        }
+        catch (err) {
+            result = {
+                id: handler.id,
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+                duration_ms: performance.now() - start,
+            };
+        }
+        // Update failure tracking
+        if (result.ok) {
+            state.consecutiveFailures = 0;
+        }
+        else {
+            state.consecutiveFailures++;
+            state.totalErrors++;
+            if (state.consecutiveFailures >= constants_js_1.MAX_CONSECUTIVE_FAILURES) {
+                state.disabled = true;
+            }
+        }
+        return result;
+    });
+    return Promise.all(promises);
+}
+/**
+ * Execute a script handler: spawn a child process, pipe input JSON to stdin,
+ * read stdout as JSON response.
+ */
+function executeScriptHandler(handler, input) {
+    const timeout = handler.timeout ?? constants_js_1.DEFAULT_HANDLER_TIMEOUT;
+    return new Promise((resolve) => {
+        const start = performance.now();
+        const child = (0, child_process_1.spawn)('sh', ['-c', handler.command], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        // Write input JSON to stdin and close it
+        child.stdin.write(JSON.stringify(input));
+        child.stdin.end();
+        const timer = setTimeout(() => {
+            child.kill('SIGTERM');
+        }, timeout);
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            const duration_ms = performance.now() - start;
+            if (code !== 0) {
+                resolve({
+                    id: handler.id,
+                    ok: false,
+                    error: `Exit code ${code}${stderr ? ': ' + stderr.trim() : ''}`,
+                    duration_ms,
+                });
+                return;
+            }
+            // Try to parse stdout as JSON
+            let output = undefined;
+            if (stdout.trim()) {
+                try {
+                    output = JSON.parse(stdout.trim());
+                }
+                catch {
+                    // If stdout isn't valid JSON, wrap it as additionalContext
+                    output = { additionalContext: stdout.trim() };
+                }
+            }
+            resolve({ id: handler.id, ok: true, output, duration_ms });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({
+                id: handler.id,
+                ok: false,
+                error: `Spawn error: ${err.message}`,
+                duration_ms: performance.now() - start,
+            });
+        });
+    });
+}
+/**
+ * Execute an inline handler: dynamically import a JS module and call its default export.
+ */
+async function executeInlineHandler(handler, input) {
+    const timeout = handler.timeout ?? constants_js_1.DEFAULT_HANDLER_TIMEOUT;
+    const start = performance.now();
+    try {
+        const modulePath = (0, path_1.resolve)(handler.module);
+        const moduleUrl = (0, url_1.pathToFileURL)(modulePath).href;
+        const mod = await import(moduleUrl);
+        if (typeof mod.default !== 'function') {
+            return {
+                id: handler.id,
+                ok: false,
+                error: `Module "${handler.module}" does not export a default function`,
+                duration_ms: performance.now() - start,
+            };
+        }
+        // Run with timeout
+        const result = await Promise.race([
+            mod.default(input),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Inline handler timed out after ${timeout}ms`)), timeout)),
+        ]);
+        return {
+            id: handler.id,
+            ok: true,
+            output: result,
+            duration_ms: performance.now() - start,
+        };
+    }
+    catch (err) {
+        return {
+            id: handler.id,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+            duration_ms: performance.now() - start,
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createServer, startDaemon, stopDaemon, isDaemonRunning } from './server.js';
+export { loadManifest, validateManifest, createDefaultManifest } from './manifest.js';
+export { MetricsCollector } from './metrics.js';
+export { migrate, restore, getSettingsPath } from './migrate.js';
+export type { MigratePathOptions } from './migrate.js';
+export { runDoctor } from './doctor.js';
+export { executeHandlers } from './handlers.js';
+export { DEFAULT_PORT, CONFIG_DIR, MANIFEST_PATH, PID_FILE, METRICS_FILE, LOG_FILE } from './constants.js';
+export type { HookEvent, HookInput, HandlerType, HandlerConfig, Manifest, HandlerResult, MetricEntry, HandlerState, DiagnosticResult, } from './types.js';

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+// clooks — public API exports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOG_FILE = exports.METRICS_FILE = exports.PID_FILE = exports.MANIFEST_PATH = exports.CONFIG_DIR = exports.DEFAULT_PORT = exports.executeHandlers = exports.runDoctor = exports.getSettingsPath = exports.restore = exports.migrate = exports.MetricsCollector = exports.createDefaultManifest = exports.validateManifest = exports.loadManifest = exports.isDaemonRunning = exports.stopDaemon = exports.startDaemon = exports.createServer = void 0;
+var server_js_1 = require("./server.js");
+Object.defineProperty(exports, "createServer", { enumerable: true, get: function () { return server_js_1.createServer; } });
+Object.defineProperty(exports, "startDaemon", { enumerable: true, get: function () { return server_js_1.startDaemon; } });
+Object.defineProperty(exports, "stopDaemon", { enumerable: true, get: function () { return server_js_1.stopDaemon; } });
+Object.defineProperty(exports, "isDaemonRunning", { enumerable: true, get: function () { return server_js_1.isDaemonRunning; } });
+var manifest_js_1 = require("./manifest.js");
+Object.defineProperty(exports, "loadManifest", { enumerable: true, get: function () { return manifest_js_1.loadManifest; } });
+Object.defineProperty(exports, "validateManifest", { enumerable: true, get: function () { return manifest_js_1.validateManifest; } });
+Object.defineProperty(exports, "createDefaultManifest", { enumerable: true, get: function () { return manifest_js_1.createDefaultManifest; } });
+var metrics_js_1 = require("./metrics.js");
+Object.defineProperty(exports, "MetricsCollector", { enumerable: true, get: function () { return metrics_js_1.MetricsCollector; } });
+var migrate_js_1 = require("./migrate.js");
+Object.defineProperty(exports, "migrate", { enumerable: true, get: function () { return migrate_js_1.migrate; } });
+Object.defineProperty(exports, "restore", { enumerable: true, get: function () { return migrate_js_1.restore; } });
+Object.defineProperty(exports, "getSettingsPath", { enumerable: true, get: function () { return migrate_js_1.getSettingsPath; } });
+var doctor_js_1 = require("./doctor.js");
+Object.defineProperty(exports, "runDoctor", { enumerable: true, get: function () { return doctor_js_1.runDoctor; } });
+var handlers_js_1 = require("./handlers.js");
+Object.defineProperty(exports, "executeHandlers", { enumerable: true, get: function () { return handlers_js_1.executeHandlers; } });
+var constants_js_1 = require("./constants.js");
+Object.defineProperty(exports, "DEFAULT_PORT", { enumerable: true, get: function () { return constants_js_1.DEFAULT_PORT; } });
+Object.defineProperty(exports, "CONFIG_DIR", { enumerable: true, get: function () { return constants_js_1.CONFIG_DIR; } });
+Object.defineProperty(exports, "MANIFEST_PATH", { enumerable: true, get: function () { return constants_js_1.MANIFEST_PATH; } });
+Object.defineProperty(exports, "PID_FILE", { enumerable: true, get: function () { return constants_js_1.PID_FILE; } });
+Object.defineProperty(exports, "METRICS_FILE", { enumerable: true, get: function () { return constants_js_1.METRICS_FILE; } });
+Object.defineProperty(exports, "LOG_FILE", { enumerable: true, get: function () { return constants_js_1.LOG_FILE; } });

package/dist/manifest.d.ts

@@ -0,0 +1,15 @@
+import type { Manifest } from './types.js';
+/**
+ * Load and validate the manifest from disk.
+ * Returns a Manifest with empty handlers if the file doesn't exist.
+ */
+export declare function loadManifest(): Manifest;
+/**
+ * Validate a parsed manifest object.
+ * Throws on invalid structure.
+ */
+export declare function validateManifest(manifest: Manifest): void;
+/**
+ * Create a default commented example manifest.yaml in CONFIG_DIR.
+ */
+export declare function createDefaultManifest(): string;

package/dist/manifest.js

@@ -0,0 +1,115 @@
+"use strict";
+// clooks manifest parser (YAML hook definitions)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadManifest = loadManifest;
+exports.validateManifest = validateManifest;
+exports.createDefaultManifest = createDefaultManifest;
+const fs_1 = require("fs");
+const yaml_1 = require("yaml");
+const constants_js_1 = require("./constants.js");
+/**
+ * Load and validate the manifest from disk.
+ * Returns a Manifest with empty handlers if the file doesn't exist.
+ */
+function loadManifest() {
+    if (!(0, fs_1.existsSync)(constants_js_1.MANIFEST_PATH)) {
+        return { handlers: {} };
+    }
+    const raw = (0, fs_1.readFileSync)(constants_js_1.MANIFEST_PATH, 'utf-8');
+    const parsed = (0, yaml_1.parse)(raw);
+    if (!parsed || typeof parsed !== 'object') {
+        return { handlers: {} };
+    }
+    const manifest = parsed;
+    validateManifest(manifest);
+    return manifest;
+}
+/**
+ * Validate a parsed manifest object.
+ * Throws on invalid structure.
+ */
+function validateManifest(manifest) {
+    if (!manifest.handlers || typeof manifest.handlers !== 'object') {
+        throw new Error('Manifest must have a "handlers" object');
+    }
+    const seenIds = new Set();
+    for (const [eventName, handlers] of Object.entries(manifest.handlers)) {
+        if (!constants_js_1.HOOK_EVENTS.includes(eventName)) {
+            throw new Error(`Unknown hook event: "${eventName}". Valid events: ${constants_js_1.HOOK_EVENTS.join(', ')}`);
+        }
+        if (!Array.isArray(handlers)) {
+            throw new Error(`Handlers for "${eventName}" must be an array`);
+        }
+        for (const handler of handlers) {
+            if (!handler.id || typeof handler.id !== 'string') {
+                throw new Error(`Each handler must have a string "id" (event: ${eventName})`);
+            }
+            if (seenIds.has(handler.id)) {
+                throw new Error(`Duplicate handler id: "${handler.id}"`);
+            }
+            seenIds.add(handler.id);
+            if (!handler.type || !['script', 'inline'].includes(handler.type)) {
+                throw new Error(`Handler "${handler.id}" must have type "script" or "inline"`);
+            }
+            if (handler.type === 'script' && !handler.command) {
+                throw new Error(`Script handler "${handler.id}" must have a "command" field`);
+            }
+            if (handler.type === 'inline' && !handler.module) {
+                throw new Error(`Inline handler "${handler.id}" must have a "module" field`);
+            }
+        }
+    }
+    // Validate settings if present
+    if (manifest.settings) {
+        if (manifest.settings.port !== undefined) {
+            if (typeof manifest.settings.port !== 'number' || manifest.settings.port < 1 || manifest.settings.port > 65535) {
+                throw new Error('settings.port must be a number between 1 and 65535');
+            }
+        }
+        if (manifest.settings.logLevel !== undefined) {
+            const validLevels = ['debug', 'info', 'warn', 'error'];
+            if (!validLevels.includes(manifest.settings.logLevel)) {
+                throw new Error(`settings.logLevel must be one of: ${validLevels.join(', ')}`);
+            }
+        }
+    }
+}
+/**
+ * Create a default commented example manifest.yaml in CONFIG_DIR.
+ */
+function createDefaultManifest() {
+    if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
+        (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
+    }
+    const example = {
+        handlers: {
+            PreToolUse: [
+                {
+                    id: 'example-guard',
+                    type: 'script',
+                    command: 'echo \'{"additionalContext":"checked by clooks"}\'',
+                    timeout: 3000,
+                    enabled: true,
+                },
+            ],
+        },
+        settings: {
+            port: 7890,
+            logLevel: 'info',
+        },
+    };
+    const yamlStr = '# clooks manifest — define your hook handlers here\n' +
+        '# Docs: https://github.com/mauribadnights/clooks\n' +
+        '#\n' +
+        '# Handler types:\n' +
+        '#   script  — runs a shell command, pipes hook JSON to stdin, reads stdout\n' +
+        '#   inline  — imports a JS/TS module and calls its default export\n' +
+        '#\n' +
+        '# Available events:\n' +
+        '#   SessionStart, UserPromptSubmit, PreToolUse, PostToolUse,\n' +
+        '#   Stop, SubagentStart, SubagentStop, Notification, ConfigChange\n' +
+        '#\n\n' +
+        (0, yaml_1.stringify)(example);
+    (0, fs_1.writeFileSync)(constants_js_1.MANIFEST_PATH, yamlStr, 'utf-8');
+    return constants_js_1.MANIFEST_PATH;
+}

package/dist/metrics.d.ts

@@ -0,0 +1,27 @@
+import type { MetricEntry } from './types.js';
+interface AggregatedStats {
+    event: string;
+    fires: number;
+    errors: number;
+    avgDuration: number;
+    minDuration: number;
+    maxDuration: number;
+}
+export declare class MetricsCollector {
+    private entries;
+    /** Record a metric entry in memory and append to disk. */
+    record(entry: MetricEntry): void;
+    /** Get aggregated stats per event type. */
+    getStats(): AggregatedStats[];
+    /** Get stats for a specific session. */
+    getSessionStats(sessionId: string): AggregatedStats[];
+    /** Flush is a no-op since we append on every record, but provided for API completeness. */
+    flush(): void;
+    /** Format stats as a CLI-friendly table. */
+    formatStatsTable(): string;
+    /** Estimate how many process spawns were saved. */
+    estimateSpawnsSaved(): number;
+    /** Load all entries from disk + memory (deduped by combining disk file). */
+    private loadAll;
+}
+export {};

package/dist/metrics.js

@@ -0,0 +1,122 @@
+"use strict";
+// clooks metrics and observability
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsCollector = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const constants_js_1 = require("./constants.js");
+class MetricsCollector {
+    entries = [];
+    /** Record a metric entry in memory and append to disk. */
+    record(entry) {
+        this.entries.push(entry);
+        try {
+            const dir = (0, path_1.dirname)(constants_js_1.METRICS_FILE);
+            if (!(0, fs_1.existsSync)(dir)) {
+                (0, fs_1.mkdirSync)(dir, { recursive: true });
+            }
+            (0, fs_1.appendFileSync)(constants_js_1.METRICS_FILE, JSON.stringify(entry) + '\n', 'utf-8');
+        }
+        catch {
+            // Non-critical — metrics should not crash the daemon
+        }
+    }
+    /** Get aggregated stats per event type. */
+    getStats() {
+        const all = this.loadAll();
+        const byEvent = new Map();
+        for (const entry of all) {
+            const existing = byEvent.get(entry.event) ?? [];
+            existing.push(entry);
+            byEvent.set(entry.event, existing);
+        }
+        const stats = [];
+        for (const [event, entries] of byEvent) {
+            const durations = entries.map((e) => e.duration_ms);
+            stats.push({
+                event,
+                fires: entries.length,
+                errors: entries.filter((e) => !e.ok).length,
+                avgDuration: durations.reduce((a, b) => a + b, 0) / durations.length,
+                minDuration: Math.min(...durations),
+                maxDuration: Math.max(...durations),
+            });
+        }
+        return stats.sort((a, b) => b.fires - a.fires);
+    }
+    /** Get stats for a specific session. */
+    getSessionStats(sessionId) {
+        const all = this.loadAll().filter((e) => {
+            // MetricEntry doesn't have session_id, but we stored it in the entry if available
+            return e.session_id === sessionId;
+        });
+        const byEvent = new Map();
+        for (const entry of all) {
+            const existing = byEvent.get(entry.event) ?? [];
+            existing.push(entry);
+            byEvent.set(entry.event, existing);
+        }
+        const stats = [];
+        for (const [event, entries] of byEvent) {
+            const durations = entries.map((e) => e.duration_ms);
+            stats.push({
+                event,
+                fires: entries.length,
+                errors: entries.filter((e) => !e.ok).length,
+                avgDuration: durations.reduce((a, b) => a + b, 0) / durations.length,
+                minDuration: Math.min(...durations),
+                maxDuration: Math.max(...durations),
+            });
+        }
+        return stats.sort((a, b) => b.fires - a.fires);
+    }
+    /** Flush is a no-op since we append on every record, but provided for API completeness. */
+    flush() {
+        // Already written on each record()
+    }
+    /** Format stats as a CLI-friendly table. */
+    formatStatsTable() {
+        const stats = this.getStats();
+        if (stats.length === 0) {
+            return 'No metrics recorded yet.';
+        }
+        const header = padRow(['Event', 'Fires', 'Errors', 'Avg (ms)', 'Min (ms)', 'Max (ms)']);
+        const separator = '-'.repeat(header.length);
+        const rows = stats.map((s) => padRow([
+            s.event,
+            String(s.fires),
+            String(s.errors),
+            s.avgDuration.toFixed(1),
+            s.minDuration.toFixed(1),
+            s.maxDuration.toFixed(1),
+        ]));
+        const totalFires = stats.reduce((sum, s) => sum + s.fires, 0);
+        const totalErrors = stats.reduce((sum, s) => sum + s.errors, 0);
+        const footer = `\nTotal fires: ${totalFires} | Total errors: ${totalErrors} | Spawns saved: ~${totalFires}`;
+        return [header, separator, ...rows, footer].join('\n');
+    }
+    /** Estimate how many process spawns were saved. */
+    estimateSpawnsSaved() {
+        const all = this.loadAll();
+        return all.length;
+    }
+    /** Load all entries from disk + memory (deduped by combining disk file). */
+    loadAll() {
+        if (!(0, fs_1.existsSync)(constants_js_1.METRICS_FILE)) {
+            return [...this.entries];
+        }
+        try {
+            const raw = (0, fs_1.readFileSync)(constants_js_1.METRICS_FILE, 'utf-8');
+            const lines = raw.trim().split('\n').filter(Boolean);
+            return lines.map((line) => JSON.parse(line));
+        }
+        catch {
+            return [...this.entries];
+        }
+    }
+}
+exports.MetricsCollector = MetricsCollector;
+function padRow(cols) {
+    const widths = [20, 8, 8, 10, 10, 10];
+    return cols.map((col, i) => col.padEnd(widths[i])).join('  ');
+}

package/dist/migrate.d.ts

@@ -0,0 +1,31 @@
+/** Options for overriding default paths (used by tests to avoid touching real filesystem). */
+export interface MigratePathOptions {
+    /** Override the home directory used to locate settings.json */
+    homeDir?: string;
+    /** Override the config directory (~/.clooks) */
+    configDir?: string;
+    /** Override the settings backup path */
+    settingsBackup?: string;
+}
+/**
+ * Find the Claude Code settings.json path.
+ */
+export declare function getSettingsPath(options?: MigratePathOptions): string | 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
+ */
+export declare function migrate(options?: MigratePathOptions): {
+    manifestPath: string;
+    settingsPath: string;
+    handlersCreated: number;
+};
+/**
+ * Restore original settings.json from backup.
+ */
+export declare function restore(options?: MigratePathOptions): string;