@mauribadnights/clooks 0.2.0 → 0.3.0

package/dist/metrics.js

@@ -6,15 +6,43 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const constants_js_1 = require("./constants.js");
 class MetricsCollector {
+    static MAX_ENTRIES = 1000;
     entries = [];
-    /** Record a metric entry in memory and append to disk. */
+    ringIndex = 0;
+    totalRecorded = 0;
+    static METRICS_MAX_BYTES = 5 * 1024 * 1024; // 5MB
+    static COSTS_MAX_BYTES = 1 * 1024 * 1024; // 1MB
+    /** Rotate a log file if it exceeds maxBytes. Keeps one backup (.1). */
+    rotateIfNeeded(filePath, maxBytes) {
+        try {
+            if (!(0, fs_1.existsSync)(filePath))
+                return;
+            const stat = (0, fs_1.statSync)(filePath);
+            if (stat.size >= maxBytes) {
+                (0, fs_1.renameSync)(filePath, filePath + '.1');
+            }
+        }
+        catch {
+            // Non-critical — rotation failure is not fatal
+        }
+    }
+    /** Record a metric entry in memory (ring buffer) and append to disk. */
     record(entry) {
-        this.entries.push(entry);
+        // Ring buffer: overwrite oldest when full
+        if (this.entries.length < MetricsCollector.MAX_ENTRIES) {
+            this.entries.push(entry);
+        }
+        else {
+            this.entries[this.ringIndex] = entry;
+            this.ringIndex = (this.ringIndex + 1) % MetricsCollector.MAX_ENTRIES;
+        }
+        this.totalRecorded++;
         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 });
             }
+            this.rotateIfNeeded(constants_js_1.METRICS_FILE, MetricsCollector.METRICS_MAX_BYTES);
             (0, fs_1.appendFileSync)(constants_js_1.METRICS_FILE, JSON.stringify(entry) + '\n', 'utf-8');
         }
         catch {
@@ -46,10 +74,7 @@ class MetricsCollector {
     }
     /** 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 all = this.loadAll().filter((e) => e.session_id === sessionId);
         const byEvent = new Map();
         for (const entry of all) {
             const existing = byEvent.get(entry.event) ?? [];
@@ -108,6 +133,7 @@ class MetricsCollector {
             if (!(0, fs_1.existsSync)(dir)) {
                 (0, fs_1.mkdirSync)(dir, { recursive: true });
             }
+            this.rotateIfNeeded(constants_js_1.COSTS_FILE, MetricsCollector.COSTS_MAX_BYTES);
             (0, fs_1.appendFileSync)(constants_js_1.COSTS_FILE, JSON.stringify(entry) + '\n', 'utf-8');
         }
         catch {

package/dist/migrate.js

@@ -8,6 +8,7 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
 const constants_js_1 = require("./constants.js");
+const builtin_hooks_js_1 = require("./builtin-hooks.js");
 const yaml_1 = require("yaml");
 /**
  * Find the Claude Code settings.json path.
@@ -91,6 +92,20 @@ function migrate(options) {
             };
         });
     }
+    // Install built-in hook scripts
+    (0, builtin_hooks_js_1.installBuiltinHooks)();
+    // Add update checker to SessionStart handlers
+    const checkUpdatePath = (0, path_1.join)(constants_js_1.HOOKS_DIR, 'check-update.js');
+    if (!manifestHandlers['SessionStart']) {
+        manifestHandlers['SessionStart'] = [];
+    }
+    manifestHandlers['SessionStart'].unshift({
+        id: 'clooks-check-update',
+        type: 'script',
+        command: `node ${checkUpdatePath}`,
+        timeout: 6000,
+        enabled: true,
+    });
     // Write manifest.yaml
     const manifest = {
         handlers: manifestHandlers,
@@ -129,10 +144,14 @@ function migrate(options) {
         }
         // Add HTTP hook
         if (hadHandlers > 0) {
-            hookEntries.push({
+            const httpHook = {
                 type: 'http',
                 url: `http://localhost:${constants_js_1.DEFAULT_PORT}/hooks/${eventName}`,
-            });
+            };
+            if (manifest.settings?.authToken) {
+                httpHook.headers = { Authorization: `Bearer ${manifest.settings.authToken}` };
+            }
+            hookEntries.push(httpHook);
         }
         if (hookEntries.length > 0) {
             // Wrap in a single rule group (no matcher — clooks handles dispatch)

package/dist/plugin.d.ts

@@ -0,0 +1,50 @@
+import type { PluginManifest, PluginRegistry, InstalledPlugin, Manifest } from './types.js';
+/**
+ * Load the plugin registry (installed.json).
+ */
+export declare function loadRegistry(registryPath?: string): PluginRegistry;
+/**
+ * Save the plugin registry.
+ */
+export declare function saveRegistry(registry: PluginRegistry, registryPath?: string): void;
+/**
+ * Validate a plugin manifest.
+ * Similar to validateManifest but checks plugin-specific fields (name, version required).
+ */
+export declare function validatePluginManifest(manifest: PluginManifest): void;
+/**
+ * Load all installed plugins and return their manifests.
+ */
+export declare function loadPlugins(pluginsDir?: string, registryPath?: string): {
+    name: string;
+    manifest: PluginManifest;
+}[];
+/**
+ * Merge user manifest + plugin manifests into a composite manifest.
+ * Plugin handler IDs are namespaced as "pluginName/handlerId".
+ * Prefetch keys are unioned.
+ * Settings come from user manifest only.
+ */
+export declare function mergeManifests(userManifest: Manifest, plugins: {
+    name: string;
+    manifest: PluginManifest;
+}[]): Manifest;
+/**
+ * Install a plugin from a local directory path.
+ * 1. Read clooks-plugin.yaml from the path
+ * 2. Validate it
+ * 3. Copy the directory to plugins dir under {name}/
+ * 4. Register in installed.json
+ * 5. Resolve $PLUGIN_DIR in handler commands to the installed path
+ */
+export declare function installPlugin(sourcePath: string, pluginsDir?: string, registryPath?: string): InstalledPlugin;
+/**
+ * Uninstall a plugin by name.
+ * 1. Remove from installed.json
+ * 2. Delete the plugin directory
+ */
+export declare function uninstallPlugin(name: string, pluginsDir?: string, registryPath?: string): void;
+/**
+ * List installed plugins.
+ */
+export declare function listPlugins(registryPath?: string): InstalledPlugin[];

package/dist/plugin.js

@@ -0,0 +1,279 @@
+"use strict";
+// clooks plugin system — load, install, uninstall, merge plugin manifests
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRegistry = loadRegistry;
+exports.saveRegistry = saveRegistry;
+exports.validatePluginManifest = validatePluginManifest;
+exports.loadPlugins = loadPlugins;
+exports.mergeManifests = mergeManifests;
+exports.installPlugin = installPlugin;
+exports.uninstallPlugin = uninstallPlugin;
+exports.listPlugins = listPlugins;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = require("yaml");
+const constants_js_1 = require("./constants.js");
+/**
+ * Load the plugin registry (installed.json).
+ */
+function loadRegistry(registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    if (!(0, fs_1.existsSync)(registryPath)) {
+        return { plugins: [] };
+    }
+    try {
+        const raw = (0, fs_1.readFileSync)(registryPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.plugins)) {
+            return { plugins: [] };
+        }
+        return parsed;
+    }
+    catch {
+        return { plugins: [] };
+    }
+}
+/**
+ * Save the plugin registry.
+ */
+function saveRegistry(registry, registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    const dir = (0, path_1.resolve)(registryPath, '..');
+    if (!(0, fs_1.existsSync)(dir)) {
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    (0, fs_1.writeFileSync)(registryPath, JSON.stringify(registry, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Validate a plugin manifest.
+ * Similar to validateManifest but checks plugin-specific fields (name, version required).
+ */
+function validatePluginManifest(manifest) {
+    if (!manifest.name || typeof manifest.name !== 'string') {
+        throw new Error('Plugin manifest must have a "name" string field');
+    }
+    if (!manifest.version || typeof manifest.version !== 'string') {
+        throw new Error('Plugin manifest must have a "version" string field');
+    }
+    if (!manifest.handlers || typeof manifest.handlers !== 'object') {
+        throw new Error('Plugin 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', 'llm'].includes(handler.type)) {
+                throw new Error(`Handler "${handler.id}" must have type "script", "inline", or "llm"`);
+            }
+            if (handler.type === 'script' && !('command' in handler && handler.command)) {
+                throw new Error(`Script handler "${handler.id}" must have a "command" field`);
+            }
+            if (handler.type === 'inline' && !('module' in handler && handler.module)) {
+                throw new Error(`Inline handler "${handler.id}" must have a "module" field`);
+            }
+            if (handler.type === 'llm') {
+                const llm = handler;
+                if (!llm.model) {
+                    throw new Error(`LLM handler "${handler.id}" must have a "model" field`);
+                }
+                if (!llm.prompt) {
+                    throw new Error(`LLM handler "${handler.id}" must have a "prompt" field`);
+                }
+                const validModels = ['claude-haiku-4-5', 'claude-sonnet-4-6', 'claude-opus-4-6'];
+                if (!validModels.includes(llm.model)) {
+                    throw new Error(`LLM handler "${handler.id}" model must be one of: ${validModels.join(', ')}`);
+                }
+            }
+        }
+    }
+    // Validate prefetch if present
+    if (manifest.prefetch !== undefined) {
+        if (!Array.isArray(manifest.prefetch)) {
+            throw new Error('prefetch must be an array');
+        }
+        const validKeys = ['transcript', 'git_status', 'git_diff'];
+        for (const key of manifest.prefetch) {
+            if (!validKeys.includes(key)) {
+                throw new Error(`Invalid prefetch key: "${key}". Valid keys: ${validKeys.join(', ')}`);
+            }
+        }
+    }
+}
+/**
+ * Load all installed plugins and return their manifests.
+ */
+function loadPlugins(pluginsDir = constants_js_1.PLUGINS_DIR, registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    const registry = loadRegistry(registryPath);
+    const results = [];
+    for (const plugin of registry.plugins) {
+        const manifestPath = (0, path_1.join)(plugin.path, constants_js_1.PLUGIN_MANIFEST_NAME);
+        if (!(0, fs_1.existsSync)(manifestPath)) {
+            // Skip plugins with missing manifests (silently — doctor will catch this)
+            continue;
+        }
+        try {
+            const raw = (0, fs_1.readFileSync)(manifestPath, 'utf-8');
+            const parsed = (0, yaml_1.parse)(raw);
+            validatePluginManifest(parsed);
+            results.push({ name: plugin.name, manifest: parsed });
+        }
+        catch {
+            // Skip plugins with invalid manifests
+            continue;
+        }
+    }
+    return results;
+}
+/**
+ * Namespace a handler ID with a plugin name.
+ */
+function namespaceId(pluginName, handlerId) {
+    return `${pluginName}/${handlerId}`;
+}
+/**
+ * Merge user manifest + plugin manifests into a composite manifest.
+ * Plugin handler IDs are namespaced as "pluginName/handlerId".
+ * Prefetch keys are unioned.
+ * Settings come from user manifest only.
+ */
+function mergeManifests(userManifest, plugins) {
+    // Deep clone user manifest handlers
+    const merged = {
+        handlers: {},
+        prefetch: userManifest.prefetch ? [...userManifest.prefetch] : undefined,
+        settings: userManifest.settings,
+    };
+    // Copy user handlers
+    for (const [event, handlers] of Object.entries(userManifest.handlers)) {
+        if (handlers) {
+            merged.handlers[event] = [...handlers];
+        }
+    }
+    // Merge plugin handlers
+    for (const { name: pluginName, manifest: pluginManifest } of plugins) {
+        // Union prefetch keys
+        if (pluginManifest.prefetch && pluginManifest.prefetch.length > 0) {
+            if (!merged.prefetch) {
+                merged.prefetch = [];
+            }
+            for (const key of pluginManifest.prefetch) {
+                if (!merged.prefetch.includes(key)) {
+                    merged.prefetch.push(key);
+                }
+            }
+        }
+        // Namespace and add handlers
+        for (const [event, handlers] of Object.entries(pluginManifest.handlers)) {
+            if (!handlers)
+                continue;
+            const hookEvent = event;
+            if (!merged.handlers[hookEvent]) {
+                merged.handlers[hookEvent] = [];
+            }
+            for (const handler of handlers) {
+                const namespacedHandler = {
+                    ...handler,
+                    id: namespaceId(pluginName, handler.id),
+                };
+                // Namespace depends references too
+                if (namespacedHandler.depends) {
+                    namespacedHandler.depends = namespacedHandler.depends.map(dep => 
+                    // If the dep already contains a slash, it references another plugin — leave it
+                    dep.includes('/') ? dep : namespaceId(pluginName, dep));
+                }
+                merged.handlers[hookEvent].push(namespacedHandler);
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Install a plugin from a local directory path.
+ * 1. Read clooks-plugin.yaml from the path
+ * 2. Validate it
+ * 3. Copy the directory to plugins dir under {name}/
+ * 4. Register in installed.json
+ * 5. Resolve $PLUGIN_DIR in handler commands to the installed path
+ */
+function installPlugin(sourcePath, pluginsDir = constants_js_1.PLUGINS_DIR, registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    const resolvedSource = (0, path_1.resolve)(sourcePath);
+    const manifestPath = (0, path_1.join)(resolvedSource, constants_js_1.PLUGIN_MANIFEST_NAME);
+    if (!(0, fs_1.existsSync)(manifestPath)) {
+        throw new Error(`No ${constants_js_1.PLUGIN_MANIFEST_NAME} found at ${resolvedSource}`);
+    }
+    const raw = (0, fs_1.readFileSync)(manifestPath, 'utf-8');
+    const pluginManifest = (0, yaml_1.parse)(raw);
+    validatePluginManifest(pluginManifest);
+    const destPath = (0, path_1.join)(pluginsDir, pluginManifest.name);
+    // Ensure plugins dir exists
+    if (!(0, fs_1.existsSync)(pluginsDir)) {
+        (0, fs_1.mkdirSync)(pluginsDir, { recursive: true });
+    }
+    // Remove existing installation if present
+    if ((0, fs_1.existsSync)(destPath)) {
+        (0, fs_1.rmSync)(destPath, { recursive: true, force: true });
+    }
+    // Copy plugin directory to plugins dir
+    (0, fs_1.cpSync)(resolvedSource, destPath, { recursive: true });
+    // Resolve $PLUGIN_DIR in handler commands within the installed copy
+    const installedManifestPath = (0, path_1.join)(destPath, constants_js_1.PLUGIN_MANIFEST_NAME);
+    const installedRaw = (0, fs_1.readFileSync)(installedManifestPath, 'utf-8');
+    const resolved = installedRaw.replace(/\$PLUGIN_DIR/g, destPath);
+    (0, fs_1.writeFileSync)(installedManifestPath, resolved, 'utf-8');
+    // Resolve relative extras.readme to absolute path
+    const resolvedManifest = (0, yaml_1.parse)(resolved);
+    if (resolvedManifest.extras?.readme && !resolvedManifest.extras.readme.startsWith('/')) {
+        resolvedManifest.extras.readme = (0, path_1.join)(destPath, resolvedManifest.extras.readme);
+        (0, fs_1.writeFileSync)(installedManifestPath, (0, yaml_1.stringify)(resolvedManifest), 'utf-8');
+    }
+    // Update registry
+    const registry = loadRegistry(registryPath);
+    // Remove any existing entry for this plugin
+    registry.plugins = registry.plugins.filter(p => p.name !== pluginManifest.name);
+    const entry = {
+        name: pluginManifest.name,
+        version: pluginManifest.version,
+        path: destPath,
+        installedAt: new Date().toISOString(),
+    };
+    registry.plugins.push(entry);
+    saveRegistry(registry, registryPath);
+    return entry;
+}
+/**
+ * Uninstall a plugin by name.
+ * 1. Remove from installed.json
+ * 2. Delete the plugin directory
+ */
+function uninstallPlugin(name, pluginsDir = constants_js_1.PLUGINS_DIR, registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    const registry = loadRegistry(registryPath);
+    const plugin = registry.plugins.find(p => p.name === name);
+    if (!plugin) {
+        throw new Error(`Plugin "${name}" is not installed`);
+    }
+    // Remove from registry
+    registry.plugins = registry.plugins.filter(p => p.name !== name);
+    saveRegistry(registry, registryPath);
+    // Delete plugin directory
+    const pluginPath = (0, path_1.join)(pluginsDir, name);
+    if ((0, fs_1.existsSync)(pluginPath)) {
+        (0, fs_1.rmSync)(pluginPath, { recursive: true, force: true });
+    }
+}
+/**
+ * List installed plugins.
+ */
+function listPlugins(registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    const registry = loadRegistry(registryPath);
+    return registry.plugins;
+}

package/dist/ratelimit.d.ts

@@ -0,0 +1,12 @@
+export declare class RateLimiter {
+    private attempts;
+    private maxAttempts;
+    private windowMs;
+    constructor(maxAttempts?: number, windowMs?: number);
+    /** Check if source is rate-limited. Returns true if allowed. */
+    check(source: string): boolean;
+    /** Record an attempt from source. */
+    record(source: string): void;
+    /** Clean up old entries. */
+    cleanup(): void;
+}

package/dist/ratelimit.js

@@ -0,0 +1,44 @@
+"use strict";
+// clooks rate limiting — protect against auth brute-force
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+class RateLimiter {
+    attempts = new Map(); // source → timestamps
+    maxAttempts;
+    windowMs;
+    constructor(maxAttempts = 10, windowMs = 60_000) {
+        this.maxAttempts = maxAttempts;
+        this.windowMs = windowMs;
+    }
+    /** Check if source is rate-limited. Returns true if allowed. */
+    check(source) {
+        const now = Date.now();
+        const timestamps = this.attempts.get(source);
+        if (!timestamps)
+            return true;
+        // Count recent attempts within window
+        const recent = timestamps.filter(t => now - t <= this.windowMs);
+        return recent.length < this.maxAttempts;
+    }
+    /** Record an attempt from source. */
+    record(source) {
+        const now = Date.now();
+        const timestamps = this.attempts.get(source) ?? [];
+        timestamps.push(now);
+        this.attempts.set(source, timestamps);
+    }
+    /** Clean up old entries. */
+    cleanup() {
+        const now = Date.now();
+        for (const [source, timestamps] of this.attempts) {
+            const recent = timestamps.filter(t => now - t <= this.windowMs);
+            if (recent.length === 0) {
+                this.attempts.delete(source);
+            }
+            else {
+                this.attempts.set(source, recent);
+            }
+        }
+    }
+}
+exports.RateLimiter = RateLimiter;

package/dist/server.d.ts

@@ -1,11 +1,18 @@
 import { type Server } from 'http';
+import type { FSWatcher } from 'fs';
 import { MetricsCollector } from './metrics.js';
+import { DenyCache } from './shortcircuit.js';
+import { RateLimiter } from './ratelimit.js';
 import type { Manifest } from './types.js';
 export interface ServerContext {
     server: Server;
     metrics: MetricsCollector;
     startTime: number;
     manifest: Manifest;
+    watcher?: FSWatcher;
+    denyCache: DenyCache;
+    rateLimiter: RateLimiter;
+    cleanupInterval?: ReturnType<typeof setInterval>;
 }
 /**
  * Create the HTTP server for hook handling.
@@ -14,7 +21,9 @@ export declare function createServer(manifest: Manifest, metrics: MetricsCollect
 /**
  * Start the daemon: bind the server and write PID file.
  */
-export declare function startDaemon(manifest: Manifest, metrics: MetricsCollector): Promise<ServerContext>;
+export declare function startDaemon(manifest: Manifest, metrics: MetricsCollector, options?: {
+    noWatch?: boolean;
+}): Promise<ServerContext>;
 /**
  * Stop a running daemon by reading PID file and sending SIGTERM.
  */
@@ -26,4 +35,6 @@ export declare function isDaemonRunning(): boolean;
 /**
  * Start daemon as a detached background process.
  */
-export declare function startDaemonBackground(): void;
+export declare function startDaemonBackground(options?: {
+    noWatch?: boolean;
+}): void;