@mauribadnights/clooks 0.2.0 → 0.3.0

package/dist/server.js

@@ -11,7 +11,12 @@ const fs_1 = require("fs");
 const child_process_1 = require("child_process");
 const handlers_js_1 = require("./handlers.js");
 const prefetch_js_1 = require("./prefetch.js");
+const watcher_js_1 = require("./watcher.js");
+const auth_js_1 = require("./auth.js");
+const shortcircuit_js_1 = require("./shortcircuit.js");
+const ratelimit_js_1 = require("./ratelimit.js");
 const constants_js_1 = require("./constants.js");
+const manifest_js_1 = require("./manifest.js");
 function log(msg) {
     const line = `[${new Date().toISOString()}] ${msg}\n`;
     try {
@@ -79,21 +84,69 @@ function sendJson(res, status, data) {
  */
 function createServer(manifest, metrics) {
     const startTime = Date.now();
+    const denyCache = new shortcircuit_js_1.DenyCache();
+    const rateLimiter = new ratelimit_js_1.RateLimiter();
+    const ctx = {
+        server: null,
+        metrics,
+        startTime,
+        manifest,
+        denyCache,
+        rateLimiter,
+    };
+    const authToken = manifest.settings?.authToken ?? '';
+    // Periodic cleanup for deny cache and rate limiter (every 60s)
+    ctx.cleanupInterval = setInterval(() => {
+        denyCache.cleanup();
+        rateLimiter.cleanup();
+    }, 60_000);
+    // Unref so it doesn't keep the process alive
+    if (ctx.cleanupInterval && typeof ctx.cleanupInterval === 'object' && 'unref' in ctx.cleanupInterval) {
+        ctx.cleanupInterval.unref();
+    }
     const server = (0, http_1.createServer)(async (req, res) => {
         const url = req.url ?? '/';
         const method = req.method ?? 'GET';
-        // Health check endpoint
+        // Public health endpoint — minimal, no auth
         if (method === 'GET' && url === '/health') {
-            const handlerCount = Object.values(manifest.handlers)
+            sendJson(res, 200, { status: 'ok' });
+            return;
+        }
+        // Detailed health endpoint — authenticated if authToken configured
+        if (method === 'GET' && url === '/health/detail') {
+            if (authToken) {
+                const authHeader = req.headers['authorization'];
+                if (!(0, auth_js_1.validateAuth)(authHeader, authToken)) {
+                    sendJson(res, 401, { error: 'Unauthorized' });
+                    return;
+                }
+            }
+            const handlerCount = Object.values(ctx.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,
+                port: ctx.manifest.settings?.port ?? constants_js_1.DEFAULT_PORT,
             });
             return;
         }
+        // Auth check for all POST requests
+        if (method === 'POST' && authToken) {
+            const source = req.socket.remoteAddress ?? 'unknown';
+            // Rate limiting check
+            if (!rateLimiter.check(source)) {
+                sendJson(res, 429, { error: 'Too many requests' });
+                return;
+            }
+            const authHeader = req.headers['authorization'];
+            if (!(0, auth_js_1.validateAuth)(authHeader, authToken)) {
+                rateLimiter.record(source);
+                log(`Auth failure from ${source}`);
+                sendJson(res, 401, { error: 'Unauthorized' });
+                return;
+            }
+        }
         // Hook endpoint: POST /hooks/:eventName
         const hookMatch = url.match(/^\/hooks\/([A-Za-z]+)$/);
         if (method === 'POST' && hookMatch) {
@@ -103,7 +156,14 @@ function createServer(manifest, metrics) {
                 return;
             }
             const event = eventName;
-            const handlers = manifest.handlers[event] ?? [];
+            // On SessionStart, reset session-isolated handlers across ALL events
+            if (event === 'SessionStart') {
+                const allHandlers = Object.values(ctx.manifest.handlers)
+                    .flat()
+                    .filter((h) => h != null);
+                (0, handlers_js_1.resetSessionIsolatedHandlers)(allHandlers);
+            }
+            const handlers = ctx.manifest.handlers[event] ?? [];
             if (handlers.length === 0) {
                 sendJson(res, 200, {});
                 return;
@@ -118,12 +178,20 @@ function createServer(manifest, metrics) {
                 sendJson(res, 400, { error: 'Invalid JSON body' });
                 return;
             }
+            // Short-circuit: skip PostToolUse if PreToolUse denied this tool
+            if (event === 'PostToolUse' && input.tool_name && input.session_id) {
+                if (denyCache.isDenied(input.session_id, input.tool_name)) {
+                    log(`PostToolUse skipped — PreToolUse denied for ${input.tool_name}`);
+                    sendJson(res, 200, {});
+                    return;
+                }
+            }
             log(`Hook: ${eventName} (${handlers.length} handler${handlers.length > 1 ? 's' : ''})`);
             try {
                 // Pre-fetch shared context if configured
                 let context;
-                if (manifest.prefetch && manifest.prefetch.length > 0) {
-                    context = await (0, prefetch_js_1.prefetchContext)(manifest.prefetch, input);
+                if (ctx.manifest.prefetch && ctx.manifest.prefetch.length > 0) {
+                    context = await (0, prefetch_js_1.prefetchContext)(ctx.manifest.prefetch, input);
                 }
                 const results = await (0, handlers_js_1.executeHandlers)(event, input, handlers, context);
                 // Record metrics and costs
@@ -138,10 +206,10 @@ function createServer(manifest, metrics) {
                         filtered: result.filtered,
                         usage: result.usage,
                         cost_usd: result.cost_usd,
+                        session_id: input.session_id,
                     });
                     // Track cost for LLM handlers
                     if (result.usage && result.cost_usd !== undefined && result.cost_usd > 0) {
-                        // Find the handler config to get model info
                         const handlerConfig = handlers.find(h => h.id === result.id);
                         if (handlerConfig && handlerConfig.type === 'llm') {
                             const llmConfig = handlerConfig;
@@ -157,6 +225,27 @@ function createServer(manifest, metrics) {
                         }
                     }
                 }
+                // Short-circuit: if PreToolUse had a deny, record it in the cache
+                if (event === 'PreToolUse' && input.tool_name && input.session_id) {
+                    const hasDeny = results.some(r => {
+                        if (!r.ok || !r.output || typeof r.output !== 'object')
+                            return false;
+                        const out = r.output;
+                        // Check hookSpecificOutput.permissionDecision === 'deny'
+                        if (out.hookSpecificOutput && typeof out.hookSpecificOutput === 'object') {
+                            const hso = out.hookSpecificOutput;
+                            if (hso.permissionDecision === 'deny')
+                                return true;
+                        }
+                        // Check decision === 'block'
+                        if (out.decision === 'block')
+                            return true;
+                        return false;
+                    });
+                    if (hasDeny) {
+                        denyCache.recordDeny(input.session_id, input.tool_name);
+                    }
+                }
                 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);
@@ -170,12 +259,13 @@ function createServer(manifest, metrics) {
         // 404 for everything else
         sendJson(res, 404, { error: 'Not found' });
     });
-    return { server, metrics, startTime, manifest };
+    ctx.server = server;
+    return ctx;
 }
 /**
  * Start the daemon: bind the server and write PID file.
  */
-function startDaemon(manifest, metrics) {
+function startDaemon(manifest, metrics, options) {
     return new Promise((resolve, reject) => {
         const ctx = createServer(manifest, metrics);
         const port = manifest.settings?.port ?? constants_js_1.DEFAULT_PORT;
@@ -195,12 +285,75 @@ function startDaemon(manifest, metrics) {
                 (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');
+            // Start file watcher unless disabled
+            if (!options?.noWatch) {
+                ctx.watcher = (0, watcher_js_1.startWatcher)(constants_js_1.MANIFEST_PATH, () => {
+                    try {
+                        const newManifest = (0, manifest_js_1.loadCompositeManifest)();
+                        // Diff handlers: find removed, added, and changed handlers
+                        const oldIds = new Set();
+                        const oldHandlerMap = new Map();
+                        for (const handlers of Object.values(ctx.manifest.handlers)) {
+                            if (!handlers)
+                                continue;
+                            for (const h of handlers) {
+                                oldIds.add(h.id);
+                                oldHandlerMap.set(h.id, h);
+                            }
+                        }
+                        const newIds = new Set();
+                        const newHandlerMap = new Map();
+                        for (const handlers of Object.values(newManifest.handlers)) {
+                            if (!handlers)
+                                continue;
+                            for (const h of handlers) {
+                                newIds.add(h.id);
+                                newHandlerMap.set(h.id, h);
+                            }
+                        }
+                        // Removed handlers: clean up their state
+                        for (const id of oldIds) {
+                            if (!newIds.has(id)) {
+                                (0, handlers_js_1.cleanupHandlerState)(id);
+                                log(`  Handler removed: ${id}`);
+                            }
+                        }
+                        // Added handlers: initialize fresh state (happens automatically on first use)
+                        for (const id of newIds) {
+                            if (!oldIds.has(id)) {
+                                log(`  Handler added: ${id}`);
+                            }
+                        }
+                        // Changed handlers with sessionIsolation: reset state
+                        for (const id of newIds) {
+                            if (oldIds.has(id)) {
+                                const newH = newHandlerMap.get(id);
+                                const oldH = oldHandlerMap.get(id);
+                                if (newH.sessionIsolation && JSON.stringify(oldH) !== JSON.stringify(newH)) {
+                                    (0, handlers_js_1.cleanupHandlerState)(id);
+                                    log(`  Handler changed (session-isolated, state reset): ${id}`);
+                                }
+                            }
+                        }
+                        ctx.manifest = newManifest;
+                        log('Manifest reloaded successfully');
+                    }
+                    catch (err) {
+                        log(`Manifest reload failed (keeping previous config): ${err instanceof Error ? err.message : err}`);
+                    }
+                }, (err) => {
+                    log(`Watcher error: ${err.message}`);
+                }) ?? undefined;
+            }
             log(`Daemon started on 127.0.0.1:${port} (pid ${process.pid})`);
             resolve(ctx);
         });
         // Graceful shutdown
         const shutdown = () => {
             log('Shutting down...');
+            (0, watcher_js_1.stopWatcher)(ctx.watcher ?? null);
+            if (ctx.cleanupInterval)
+                clearInterval(ctx.cleanupInterval);
             ctx.server.close(() => {
                 try {
                     if ((0, fs_1.existsSync)(constants_js_1.PID_FILE))
@@ -283,8 +436,12 @@ function isDaemonRunning() {
 /**
  * Start daemon as a detached background process.
  */
-function startDaemonBackground() {
-    const child = (0, child_process_1.spawn)(process.execPath, [process.argv[1], 'start', '--foreground'], {
+function startDaemonBackground(options) {
+    const args = [process.argv[1], 'start', '--foreground'];
+    if (options?.noWatch) {
+        args.push('--no-watch');
+    }
+    const child = (0, child_process_1.spawn)(process.execPath, args, {
         detached: true,
         stdio: 'ignore',
     });

package/dist/shortcircuit.d.ts

@@ -0,0 +1,20 @@
+/**
+ * In-memory cache of denied PreToolUse calls.
+ * Keyed by session_id + tool_name.
+ * Entries expire after TTL_MS (30 seconds).
+ */
+export declare class DenyCache {
+    private cache;
+    private static TTL_MS;
+    private makeKey;
+    /** Record a denied PreToolUse. */
+    recordDeny(sessionId: string, toolName: string): void;
+    /** Check if a tool call was recently denied. */
+    isDenied(sessionId: string, toolName: string): boolean;
+    /** Clean up expired entries. */
+    cleanup(): void;
+    /** Clear all entries. */
+    clear(): void;
+    /** Get current cache size (for testing). */
+    get size(): number;
+}

package/dist/shortcircuit.js

@@ -0,0 +1,49 @@
+"use strict";
+// clooks short-circuit chains — deny cache for PreToolUse → PostToolUse
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DenyCache = void 0;
+/**
+ * In-memory cache of denied PreToolUse calls.
+ * Keyed by session_id + tool_name.
+ * Entries expire after TTL_MS (30 seconds).
+ */
+class DenyCache {
+    cache = new Map(); // key → timestamp
+    static TTL_MS = 30_000;
+    makeKey(sessionId, toolName) {
+        return `${sessionId}:${toolName}`;
+    }
+    /** Record a denied PreToolUse. */
+    recordDeny(sessionId, toolName) {
+        this.cache.set(this.makeKey(sessionId, toolName), Date.now());
+    }
+    /** Check if a tool call was recently denied. */
+    isDenied(sessionId, toolName) {
+        const ts = this.cache.get(this.makeKey(sessionId, toolName));
+        if (ts === undefined)
+            return false;
+        if (Date.now() - ts > DenyCache.TTL_MS) {
+            this.cache.delete(this.makeKey(sessionId, toolName));
+            return false;
+        }
+        return true;
+    }
+    /** Clean up expired entries. */
+    cleanup() {
+        const now = Date.now();
+        for (const [key, ts] of this.cache) {
+            if (now - ts > DenyCache.TTL_MS) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    /** Clear all entries. */
+    clear() {
+        this.cache.clear();
+    }
+    /** Get current cache size (for testing). */
+    get size() {
+        return this.cache.size;
+    }
+}
+exports.DenyCache = DenyCache;

package/dist/types.d.ts

@@ -30,6 +30,8 @@ export interface LLMHandlerConfig {
     filter?: string;
     timeout?: number;
     enabled?: boolean;
+    sessionIsolation?: boolean;
+    depends?: string[];
 }
 /** Script handler config */
 export interface ScriptHandlerConfig {
@@ -39,6 +41,8 @@ export interface ScriptHandlerConfig {
     filter?: string;
     timeout?: number;
     enabled?: boolean;
+    sessionIsolation?: boolean;
+    depends?: string[];
 }
 /** Inline handler config */
 export interface InlineHandlerConfig {
@@ -48,6 +52,8 @@ export interface InlineHandlerConfig {
     filter?: string;
     timeout?: number;
     enabled?: boolean;
+    sessionIsolation?: boolean;
+    depends?: string[];
 }
 /** Union of all handler configs */
 export type HandlerConfig = ScriptHandlerConfig | InlineHandlerConfig | LLMHandlerConfig;
@@ -67,6 +73,7 @@ export interface Manifest {
         port?: number;
         logLevel?: 'debug' | 'info' | 'warn' | 'error';
         anthropicApiKey?: string;
+        authToken?: string;
     };
 }
 /** Token usage from API response */
@@ -95,6 +102,7 @@ export interface MetricEntry {
     filtered?: boolean;
     usage?: TokenUsage;
     cost_usd?: number;
+    session_id?: string;
 }
 /** Extended handler result with cost info */
 export interface HandlerResult {
@@ -120,3 +128,31 @@ export interface DiagnosticResult {
     status: 'ok' | 'warn' | 'error';
     message: string;
 }
+/** Plugin extras metadata (freeform, extensible) */
+export interface PluginExtras {
+    skills?: string[];
+    agents?: string[];
+    readme?: string;
+    [key: string]: unknown;
+}
+/** Plugin manifest (clooks-plugin.yaml) */
+export interface PluginManifest {
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    handlers: Partial<Record<HookEvent, HandlerConfig[]>>;
+    prefetch?: PrefetchKey[];
+    extras?: PluginExtras;
+}
+/** Installed plugin registry entry */
+export interface InstalledPlugin {
+    name: string;
+    version: string;
+    path: string;
+    installedAt: string;
+}
+/** Plugin registry file format (installed.json) */
+export interface PluginRegistry {
+    plugins: InstalledPlugin[];
+}

package/dist/watcher.d.ts

@@ -0,0 +1,18 @@
+import { type FSWatcher } from 'fs';
+type ReloadCallback = () => void;
+type ErrorCallback = (err: Error) => void;
+export interface WatcherOptions {
+    onReload: ReloadCallback;
+    onError?: ErrorCallback;
+}
+/**
+ * Watch manifest.yaml for changes.
+ * Calls onReload when changes detected (debounced).
+ * If the manifest file doesn't exist, watches the config directory for its creation.
+ */
+export declare function startWatcher(manifestPath: string, onReload: ReloadCallback, onError?: ErrorCallback): FSWatcher | null;
+/**
+ * Stop watching for file changes.
+ */
+export declare function stopWatcher(watcher: FSWatcher | null): void;
+export {};

package/dist/watcher.js

@@ -0,0 +1,120 @@
+"use strict";
+// clooks file watcher — watch manifest.yaml for changes and hot-reload
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startWatcher = startWatcher;
+exports.stopWatcher = stopWatcher;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const DEBOUNCE_MS = 500;
+/**
+ * Watch manifest.yaml for changes.
+ * Calls onReload when changes detected (debounced).
+ * If the manifest file doesn't exist, watches the config directory for its creation.
+ */
+function startWatcher(manifestPath, onReload, onError) {
+    let lastChange = 0;
+    // If manifest exists, watch it directly
+    if ((0, fs_1.existsSync)(manifestPath)) {
+        return watchFile(manifestPath, onReload, onError);
+    }
+    // Manifest doesn't exist — watch the config directory for its creation
+    const configDir = (0, path_1.dirname)(manifestPath);
+    if (!(0, fs_1.existsSync)(configDir)) {
+        try {
+            (0, fs_1.mkdirSync)(configDir, { recursive: true });
+        }
+        catch {
+            // Can't create config dir — give up
+            if (onError)
+                onError(new Error(`Cannot create config directory: ${configDir}`));
+            return null;
+        }
+    }
+    const baseName = manifestPath.split('/').pop() ?? manifestPath.split('\\').pop() ?? '';
+    let dirWatcher = null;
+    try {
+        dirWatcher = (0, fs_1.watch)(configDir, (eventType, filename) => {
+            if (filename !== baseName)
+                return;
+            if (!(0, fs_1.existsSync)(manifestPath))
+                return;
+            const now = Date.now();
+            if (now - lastChange < DEBOUNCE_MS)
+                return;
+            lastChange = now;
+            // Manifest appeared — close directory watcher, start file watcher
+            try {
+                dirWatcher?.close();
+            }
+            catch {
+                // ignore
+            }
+            // Switch to watching the file directly
+            const fileWatcher = watchFile(manifestPath, onReload, onError);
+            if (fileWatcher) {
+                // Copy the ref so stopWatcher can close it (caller still holds the dir watcher ref)
+                // We can't replace the caller's reference, but the dir watcher is closed.
+                // The onReload fires so the caller picks up the new manifest.
+            }
+            try {
+                onReload();
+            }
+            catch (err) {
+                if (onError)
+                    onError(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        dirWatcher.on('error', (err) => {
+            if (onError)
+                onError(err);
+        });
+        return dirWatcher;
+    }
+    catch {
+        if (onError)
+            onError(new Error(`Failed to watch config directory: ${configDir}`));
+        return null;
+    }
+}
+/** Watch an existing file directly. */
+function watchFile(filePath, onReload, onError) {
+    let lastChange = 0;
+    try {
+        const watcher = (0, fs_1.watch)(filePath, (eventType) => {
+            if (eventType !== 'change' && eventType !== 'rename')
+                return;
+            const now = Date.now();
+            if (now - lastChange < DEBOUNCE_MS)
+                return;
+            lastChange = now;
+            try {
+                onReload();
+            }
+            catch (err) {
+                if (onError)
+                    onError(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        watcher.on('error', (err) => {
+            if (onError)
+                onError(err);
+        });
+        return watcher;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stop watching for file changes.
+ */
+function stopWatcher(watcher) {
+    if (watcher) {
+        try {
+            watcher.close();
+        }
+        catch {
+            // Ignore close errors
+        }
+    }
+}

package/hooks/check-update.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+// clooks built-in: check for updates on session start
+// Runs in background, non-blocking. Injects a notice if update available.
+
+const { execSync } = require('child_process');
+
+try {
+  // Get installed version
+  const pkgPath = require.resolve('@mauribadnights/clooks/package.json');
+  const pkg = JSON.parse(require('fs').readFileSync(pkgPath, 'utf-8'));
+  const current = pkg.version;
+
+  // Check npm (with short timeout to not block session start)
+  const latest = execSync('npm view @mauribadnights/clooks version 2>/dev/null', {
+    encoding: 'utf-8',
+    timeout: 5000,
+  }).trim();
+
+  if (latest && latest !== current && isNewer(latest, current)) {
+    // Output as additionalContext so it's injected into Claude's context
+    const msg = `[clooks] Update available: ${current} \u2192 ${latest}. Run: clooks update`;
+    process.stdout.write(JSON.stringify({ additionalContext: msg }));
+  }
+} catch {
+  // Silently fail — update checks should never block sessions
+}
+
+function isNewer(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return true;
+    if ((pa[i] || 0) < (pb[i] || 0)) return false;
+  }
+  return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mauribadnights/clooks",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Persistent hook runtime for Claude Code — eliminates process spawning overhead and gives you observability",
   "bin": {
     "clooks": "./dist/cli.js"
@@ -32,6 +32,7 @@
   },
   "files": [
     "dist",
+    "hooks",
     "README.md",
     "LICENSE"
   ],