@mauribadnights/clooks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mauribadnights
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# clooks
+
+Persistent hook runtime for Claude Code — eliminate cold starts, get observability.
+
+## The Problem
+
+Claude Code spawns a fresh process for every hook invocation. Power users with multiple hooks (safety guards, context injectors, custom scripts) accumulate **100+ process spawns per session**. Each Node.js cold start costs 50-100ms. That's 6-11 seconds of pure overhead per session — and you get zero visibility into what your hooks are doing.
+
+## How clooks Fixes It
+
+One persistent HTTP server handles all your hooks. Claude Code's [built-in HTTP hook support](https://docs.anthropic.com/en/docs/claude-code/hooks) POSTs to `localhost:7890` instead of spawning processes. **One process instead of hundreds.**
+
+```
+┌─────────────┐     POST /hooks/PreToolUse     ┌──────────────────┐
+│             │ ──────────────────────────────► │                  │
+│ Claude Code │     POST /hooks/Stop           │  clooks daemon  │
+│             │ ──────────────────────────────► │  (persistent)    │
+│             │     POST /hooks/...            │                  │
+│             │ ──────────────────────────────► │  ┌────────────┐ │
+│             │                                │  │ handler A  │ │
+│             │ ◄────────────── JSON ───────── │  │ handler B  │ │
+│             │                                │  │ handler C  │ │
+└─────────────┘                                │  └────────────┘ │
+                                               │  metrics.jsonl  │
+                                               └──────────────────┘
+```
+
+## Quick Start
+
+```bash
+npm install -g clooks
+
+# If you have existing hooks in settings.json:
+clooks migrate    # converts command hooks → HTTP hooks + manifest
+
+# Or start fresh:
+clooks init       # creates ~/.clooks/manifest.yaml
+
+clooks start      # starts the daemon
+```
+
+That's it. Claude Code will now POST to your daemon instead of spawning processes.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `clooks start` | Start the daemon (background by default, `--foreground` for debug) |
+| `clooks stop` | Stop the daemon |
+| `clooks status` | Show daemon status, uptime, and handler count |
+| `clooks stats` | Show hook execution metrics (fires, errors, latency) |
+| `clooks migrate` | Convert `settings.json` command hooks to HTTP hooks |
+| `clooks restore` | Restore original `settings.json` from backup |
+| `clooks doctor` | Run diagnostic health checks |
+| `clooks init` | Create default config directory and example manifest |
+| `clooks ensure-running` | Start daemon if not running (used by SessionStart hook) |
+
+## Manifest Format
+
+Handlers are defined in `~/.clooks/manifest.yaml`:
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: safety-guard
+      type: script
+      command: node ~/hooks/guard.js
+      timeout: 3000
+      enabled: true
+
+    - id: context-injector
+      type: inline
+      module: ~/hooks/context.js
+      timeout: 2000
+
+  Stop:
+    - id: session-logger
+      type: script
+      command: ~/hooks/log-session.sh
+
+settings:
+  port: 7890
+  logLevel: info
+```
+
+**Handler types:**
+- `script` — runs a shell command, pipes hook JSON to stdin, reads JSON from stdout
+- `inline` — imports a JS module and calls its default export (faster, no subprocess)
+
+## Stats
+
+```
+$ clooks stats
+
+Event               Fires     Errors    Avg (ms)    Min (ms)    Max (ms)
+------------------------------------------------------------------------
+PreToolUse          47        0         1.2         0.8         3.1
+Stop                12        0         2.4         1.1         5.6
+UserPromptSubmit    12        1         1.8         0.9         4.2
+
+Total fires: 71 | Total errors: 1 | Spawns saved: ~71
+```
+
+## How It Works with Claude Code
+
+After `clooks migrate`, your `settings.json` looks like this:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{ "hooks": [
+      { "type": "command", "command": "clooks ensure-running" }
+    ]}],
+    "PreToolUse": [{ "hooks": [
+      { "type": "http", "url": "http://localhost:7890/hooks/PreToolUse" }
+    ]}]
+  }
+}
+```
+
+The `SessionStart` command hook ensures the daemon is running (fast no-op if already up). All other hooks are HTTP POSTs — no process spawning, no cold starts.
+
+Handlers that fail 3 times consecutively are auto-disabled to prevent cascading failures.
+
+## Configuration
+
+| Item | Default |
+|---|---|
+| Port | `7890` |
+| Config directory | `~/.clooks/` |
+| Manifest | `~/.clooks/manifest.yaml` |
+| Metrics | `~/.clooks/metrics.jsonl` |
+| Daemon log | `~/.clooks/daemon.log` |
+| PID file | `~/.clooks/daemon.pid` |
+
+## Comparison
+
+|  | Without clooks | With clooks |
+|---|---|---|
+| **Process model** | New process per hook invocation | One persistent HTTP server |
+| **Cold start** | 50-100ms per invocation | 0ms (already running) |
+| **State** | Stateless — each invocation starts fresh | Persistent — share state across invocations |
+| **Observability** | None | Metrics, stats, logs, doctor diagnostics |
+| **Failure handling** | Silent | Auto-disable after 3 consecutive failures |
+
+## License
+
+MIT
+
+## Roadmap
+
+- **v0.2:** Matcher support in manifest, LLM call batching, token cost tracking
+- **v0.3:** Plugin ecosystem, dependency resolution between handlers

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+"use strict";
+// clooks CLI entry point
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const manifest_js_1 = require("./manifest.js");
+const metrics_js_1 = require("./metrics.js");
+const server_js_1 = require("./server.js");
+const migrate_js_1 = require("./migrate.js");
+const doctor_js_1 = require("./doctor.js");
+const constants_js_1 = require("./constants.js");
+const fs_1 = require("fs");
+const program = new commander_1.Command();
+program
+    .name('clooks')
+    .description('Persistent hook runtime for Claude Code')
+    .version('0.1.0');
+// --- start ---
+program
+    .command('start')
+    .description('Start the clooks daemon')
+    .option('-f, --foreground', 'Run in foreground (default: background/detached)')
+    .action(async (opts) => {
+    if (!opts.foreground) {
+        // Background mode: check if already running, then spawn detached
+        if ((0, server_js_1.isDaemonRunning)()) {
+            console.log('Daemon is already running.');
+            process.exit(0);
+        }
+        // Ensure config dir exists
+        if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
+            (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
+        }
+        console.log('Starting clooks daemon in background...');
+        (0, server_js_1.startDaemonBackground)();
+        // Give it a moment to start
+        await new Promise((r) => setTimeout(r, 500));
+        if ((0, server_js_1.isDaemonRunning)()) {
+            const pid = (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim();
+            console.log(`Daemon started (pid ${pid}), listening on 127.0.0.1:${constants_js_1.DEFAULT_PORT}`);
+        }
+        else {
+            console.log('Daemon started. Check ~/.clooks/daemon.log if issues arise.');
+        }
+        process.exit(0);
+    }
+    // Foreground mode: run the actual server
+    try {
+        const manifest = (0, manifest_js_1.loadManifest)();
+        const metrics = new metrics_js_1.MetricsCollector();
+        const port = manifest.settings?.port ?? constants_js_1.DEFAULT_PORT;
+        const handlerCount = Object.values(manifest.handlers)
+            .reduce((sum, arr) => sum + (arr?.length ?? 0), 0);
+        await (0, server_js_1.startDaemon)(manifest, metrics);
+        console.log(`clooks daemon running on 127.0.0.1:${port} (${handlerCount} handler${handlerCount !== 1 ? 's' : ''})`);
+    }
+    catch (err) {
+        console.error('Failed to start daemon:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+// --- stop ---
+program
+    .command('stop')
+    .description('Stop the clooks daemon')
+    .action(() => {
+    if ((0, server_js_1.stopDaemon)()) {
+        console.log('Daemon stopped.');
+    }
+    else {
+        console.log('Daemon is not running (no PID file or process not found).');
+    }
+});
+// --- status ---
+program
+    .command('status')
+    .description('Show daemon status')
+    .action(async () => {
+    const running = (0, server_js_1.isDaemonRunning)();
+    if (!running) {
+        console.log('Status: stopped');
+        return;
+    }
+    const pid = (0, fs_1.existsSync)(constants_js_1.PID_FILE) ? (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim() : '?';
+    // Try to hit health endpoint
+    try {
+        const { get } = await import('http');
+        const data = await new Promise((resolve, reject) => {
+            const req = get(`http://127.0.0.1:${constants_js_1.DEFAULT_PORT}/health`, (res) => {
+                let body = '';
+                res.on('data', (chunk) => { body += chunk.toString(); });
+                res.on('end', () => resolve(body));
+            });
+            req.on('error', reject);
+            req.setTimeout(3000, () => { req.destroy(); reject(new Error('timeout')); });
+        });
+        const health = JSON.parse(data);
+        console.log(`Status: running`);
+        console.log(`PID: ${pid}`);
+        console.log(`Port: ${health.port}`);
+        console.log(`Uptime: ${formatUptime(health.uptime)}`);
+        console.log(`Handlers loaded: ${health.handlers_loaded}`);
+    }
+    catch {
+        console.log(`Status: running (pid ${pid})`);
+        console.log(`Note: Could not reach health endpoint on port ${constants_js_1.DEFAULT_PORT}`);
+    }
+});
+// --- stats ---
+program
+    .command('stats')
+    .description('Show hook execution metrics')
+    .action(() => {
+    const metrics = new metrics_js_1.MetricsCollector();
+    console.log(metrics.formatStatsTable());
+});
+// --- migrate ---
+program
+    .command('migrate')
+    .description('Migrate Claude Code settings.json to use clooks HTTP hooks')
+    .action(() => {
+    try {
+        const result = (0, migrate_js_1.migrate)();
+        console.log('Migration complete!');
+        console.log(`  Settings: ${result.settingsPath}`);
+        console.log(`  Manifest: ${result.manifestPath}`);
+        console.log(`  Handlers created: ${result.handlersCreated}`);
+        console.log(`  Backup: ~/.clooks/settings.backup.json`);
+        console.log('\nRun "clooks start" to start the daemon.');
+    }
+    catch (err) {
+        console.error('Migration failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+// --- restore ---
+program
+    .command('restore')
+    .description('Restore original settings.json from backup')
+    .action(() => {
+    try {
+        const path = (0, migrate_js_1.restore)();
+        console.log(`Restored settings to: ${path}`);
+    }
+    catch (err) {
+        console.error('Restore failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+// --- doctor ---
+program
+    .command('doctor')
+    .description('Run diagnostic health checks')
+    .action(async () => {
+    const results = await (0, doctor_js_1.runDoctor)();
+    const icons = { ok: '[OK]', warn: '[WARN]', error: '[ERR]' };
+    for (const r of results) {
+        console.log(`  ${icons[r.status]}  ${r.check}: ${r.message}`);
+    }
+    const errors = results.filter((r) => r.status === 'error').length;
+    const warns = results.filter((r) => r.status === 'warn').length;
+    console.log(`\n${results.length} checks: ${results.length - errors - warns} ok, ${warns} warnings, ${errors} errors`);
+    if (errors > 0)
+        process.exit(1);
+});
+// --- ensure-running ---
+program
+    .command('ensure-running')
+    .description('Start daemon if not already running (used by SessionStart hook)')
+    .action(async () => {
+    if ((0, server_js_1.isDaemonRunning)()) {
+        // Already running — exit silently and fast
+        process.exit(0);
+    }
+    // Ensure config dir exists
+    if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
+        (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
+    }
+    // If no manifest, create a default one
+    const { MANIFEST_PATH } = await import('./constants.js');
+    if (!(0, fs_1.existsSync)(MANIFEST_PATH)) {
+        (0, manifest_js_1.createDefaultManifest)();
+    }
+    (0, server_js_1.startDaemonBackground)();
+    process.exit(0);
+});
+// --- init ---
+program
+    .command('init')
+    .description('Create default config directory and example manifest')
+    .action(() => {
+    if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
+        (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
+    }
+    const path = (0, manifest_js_1.createDefaultManifest)();
+    console.log(`Created: ${path}`);
+    console.log('Edit this file to configure your hook handlers.');
+});
+program.parse();
+function formatUptime(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+    const h = Math.floor(seconds / 3600);
+    const m = Math.floor((seconds % 3600) / 60);
+    return `${h}h ${m}m`;
+}

package/dist/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_PORT = 7890;
+export declare const CONFIG_DIR: string;
+export declare const MANIFEST_PATH: string;
+export declare const PID_FILE: string;
+export declare const METRICS_FILE: string;
+export declare const LOG_FILE: string;
+export declare const SETTINGS_BACKUP: string;
+export declare const MAX_CONSECUTIVE_FAILURES = 3;
+export declare const DEFAULT_HANDLER_TIMEOUT = 5000;
+export declare const HOOK_EVENTS: string[];

package/dist/constants.js

@@ -0,0 +1,26 @@
+"use strict";
+// clooks constants
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_EVENTS = exports.DEFAULT_HANDLER_TIMEOUT = exports.MAX_CONSECUTIVE_FAILURES = exports.SETTINGS_BACKUP = exports.LOG_FILE = exports.METRICS_FILE = exports.PID_FILE = exports.MANIFEST_PATH = exports.CONFIG_DIR = exports.DEFAULT_PORT = void 0;
+const os_1 = require("os");
+const path_1 = require("path");
+exports.DEFAULT_PORT = 7890;
+exports.CONFIG_DIR = (0, path_1.join)((0, os_1.homedir)(), '.clooks');
+exports.MANIFEST_PATH = (0, path_1.join)(exports.CONFIG_DIR, 'manifest.yaml');
+exports.PID_FILE = (0, path_1.join)(exports.CONFIG_DIR, 'daemon.pid');
+exports.METRICS_FILE = (0, path_1.join)(exports.CONFIG_DIR, 'metrics.jsonl');
+exports.LOG_FILE = (0, path_1.join)(exports.CONFIG_DIR, 'daemon.log');
+exports.SETTINGS_BACKUP = (0, path_1.join)(exports.CONFIG_DIR, 'settings.backup.json');
+exports.MAX_CONSECUTIVE_FAILURES = 3;
+exports.DEFAULT_HANDLER_TIMEOUT = 5000; // ms
+exports.HOOK_EVENTS = [
+    'SessionStart',
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PostToolUse',
+    'Stop',
+    'SubagentStart',
+    'SubagentStop',
+    'Notification',
+    'ConfigChange',
+];

package/dist/doctor.d.ts

@@ -0,0 +1,5 @@
+import type { DiagnosticResult } from './types.js';
+/**
+ * Run all diagnostic checks and return results.
+ */
+export declare function runDoctor(): Promise<DiagnosticResult[]>;

package/dist/doctor.js

@@ -0,0 +1,166 @@
+"use strict";
+// clooks doctor — diagnostics and health checks
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctor = runDoctor;
+const fs_1 = require("fs");
+const http_1 = require("http");
+const child_process_1 = require("child_process");
+const path_1 = require("path");
+const os_1 = require("os");
+const constants_js_1 = require("./constants.js");
+const manifest_js_1 = require("./manifest.js");
+const server_js_1 = require("./server.js");
+/**
+ * Run all diagnostic checks and return results.
+ */
+async function runDoctor() {
+    const results = [];
+    // 1. Config directory exists
+    results.push(checkConfigDir());
+    // 2. Manifest exists and is valid
+    results.push(checkManifest());
+    // 3. Daemon is running (PID file + process alive)
+    results.push(checkDaemonRunning());
+    // 4. Port is reachable
+    results.push(await checkPortReachable());
+    // 5. Script handler commands are executable
+    results.push(...checkHandlerCommands());
+    // 6. Settings.json has HTTP hooks pointing to clooks
+    results.push(checkSettingsHooks());
+    // 7. No stale PID file
+    results.push(checkStalePid());
+    return results;
+}
+function checkConfigDir() {
+    if ((0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
+        return { check: 'Config directory', status: 'ok', message: `${constants_js_1.CONFIG_DIR} exists` };
+    }
+    return { check: 'Config directory', status: 'error', message: `${constants_js_1.CONFIG_DIR} does not exist. Run "clooks start" to create it.` };
+}
+function checkManifest() {
+    if (!(0, fs_1.existsSync)(constants_js_1.MANIFEST_PATH)) {
+        return { check: 'Manifest', status: 'warn', message: 'manifest.yaml not found. No handlers configured.' };
+    }
+    try {
+        (0, manifest_js_1.loadManifest)();
+        return { check: 'Manifest', status: 'ok', message: 'manifest.yaml is valid' };
+    }
+    catch (err) {
+        return { check: 'Manifest', status: 'error', message: `manifest.yaml is invalid: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+function checkDaemonRunning() {
+    if ((0, server_js_1.isDaemonRunning)()) {
+        const pid = (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim();
+        return { check: 'Daemon process', status: 'ok', message: `Running (pid ${pid})` };
+    }
+    return { check: 'Daemon process', status: 'warn', message: 'Daemon is not running' };
+}
+function checkPortReachable() {
+    return new Promise((resolve) => {
+        const req = (0, http_1.get)(`http://127.0.0.1:${constants_js_1.DEFAULT_PORT}/health`, (res) => {
+            let data = '';
+            res.on('data', (chunk) => {
+                data += chunk.toString();
+            });
+            res.on('end', () => {
+                try {
+                    const parsed = JSON.parse(data);
+                    if (parsed.status === 'ok') {
+                        resolve({ check: 'Port reachable', status: 'ok', message: `127.0.0.1:${constants_js_1.DEFAULT_PORT} responds with status ok` });
+                    }
+                    else {
+                        resolve({ check: 'Port reachable', status: 'warn', message: `Port responds but status is: ${parsed.status}` });
+                    }
+                }
+                catch {
+                    resolve({ check: 'Port reachable', status: 'warn', message: 'Port responds but returned invalid JSON' });
+                }
+            });
+        });
+        req.on('error', () => {
+            resolve({ check: 'Port reachable', status: 'error', message: `Cannot reach 127.0.0.1:${constants_js_1.DEFAULT_PORT}` });
+        });
+        req.setTimeout(3000, () => {
+            req.destroy();
+            resolve({ check: 'Port reachable', status: 'error', message: 'Health check timed out' });
+        });
+    });
+}
+function checkHandlerCommands() {
+    const results = [];
+    try {
+        const manifest = (0, manifest_js_1.loadManifest)();
+        for (const [_event, handlers] of Object.entries(manifest.handlers)) {
+            for (const handler of handlers) {
+                if (handler.type !== 'script' || !handler.command)
+                    continue;
+                // Extract the base command (first word)
+                const baseCmd = handler.command.split(/\s+/)[0];
+                // Skip built-in shell commands
+                if (['echo', 'cat', 'true', 'false', 'test', '['].includes(baseCmd)) {
+                    results.push({ check: `Handler "${handler.id}"`, status: 'ok', message: `Command: ${baseCmd} (shell builtin)` });
+                    continue;
+                }
+                try {
+                    (0, child_process_1.execSync)(`which ${baseCmd}`, { stdio: 'pipe' });
+                    results.push({ check: `Handler "${handler.id}"`, status: 'ok', message: `Command "${baseCmd}" found in PATH` });
+                }
+                catch {
+                    results.push({ check: `Handler "${handler.id}"`, status: 'error', message: `Command "${baseCmd}" not found in PATH` });
+                }
+            }
+        }
+    }
+    catch {
+        // If manifest can't be loaded, skip handler checks (already caught by checkManifest)
+    }
+    if (results.length === 0) {
+        results.push({ check: 'Handler commands', status: 'ok', message: 'No script handlers to check' });
+    }
+    return results;
+}
+function checkSettingsHooks() {
+    const candidates = [
+        (0, path_1.join)((0, os_1.homedir)(), '.claude', 'settings.local.json'),
+        (0, path_1.join)((0, os_1.homedir)(), '.claude', 'settings.json'),
+    ];
+    for (const path of candidates) {
+        if (!(0, fs_1.existsSync)(path))
+            continue;
+        try {
+            const raw = (0, fs_1.readFileSync)(path, 'utf-8');
+            const settings = JSON.parse(raw);
+            if (!settings.hooks) {
+                return { check: 'Settings hooks', status: 'warn', message: 'No hooks configured in ' + path };
+            }
+            // settings.hooks[event] is an array of rule groups, each with a hooks[] array
+            const hasHttpHook = 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 (hasHttpHook) {
+                return { check: 'Settings hooks', status: 'ok', message: `HTTP hooks point to clooks in ${path}` };
+            }
+            return { check: 'Settings hooks', status: 'warn', message: `No HTTP hooks pointing to clooks in ${path}. Run "clooks migrate".` };
+        }
+        catch {
+            return { check: 'Settings hooks', status: 'error', message: `Failed to parse ${path}` };
+        }
+    }
+    return { check: 'Settings hooks', status: 'warn', message: 'No Claude Code settings.json found' };
+}
+function checkStalePid() {
+    if (!(0, fs_1.existsSync)(constants_js_1.PID_FILE)) {
+        return { check: 'Stale PID', status: 'ok', message: 'No PID file' };
+    }
+    const pidStr = (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim();
+    const pid = parseInt(pidStr, 10);
+    if (isNaN(pid)) {
+        return { check: 'Stale PID', status: 'error', message: 'PID file contains invalid value' };
+    }
+    try {
+        process.kill(pid, 0);
+        return { check: 'Stale PID', status: 'ok', message: `PID ${pid} is alive` };
+    }
+    catch {
+        return { check: 'Stale PID', status: 'error', message: `Stale PID file: process ${pid} is dead. Remove ${constants_js_1.PID_FILE} or run "clooks start".` };
+    }
+}

package/dist/handlers.d.ts

@@ -0,0 +1,19 @@
+import type { HandlerConfig, HandlerResult, HandlerState, HookEvent, HookInput } from './types.js';
+/** Reset all handler states (useful for testing) */
+export declare function resetHandlerStates(): void;
+/** Get a copy of the handler states map */
+export declare function getHandlerStates(): Map<string, HandlerState>;
+/**
+ * Execute all handlers for an event in parallel.
+ * Returns merged results array.
+ */
+export declare function executeHandlers(_event: HookEvent, input: HookInput, handlers: HandlerConfig[]): Promise<HandlerResult[]>;
+/**
+ * Execute a script handler: spawn a child process, pipe input JSON to stdin,
+ * read stdout as JSON response.
+ */
+export declare function executeScriptHandler(handler: HandlerConfig, input: HookInput): Promise<HandlerResult>;
+/**
+ * Execute an inline handler: dynamically import a JS module and call its default export.
+ */
+export declare function executeInlineHandler(handler: HandlerConfig, input: HookInput): Promise<HandlerResult>;