@mauribadnights/clooks 0.2.2 → 0.3.1

package/README.md

@@ -65,6 +65,11 @@ After `clooks migrate`, your `settings.json` is rewritten so that `SessionStart`
 | `clooks doctor` | Run diagnostic health checks |
 | `clooks init` | Create default config directory and example manifest |
 | `clooks ensure-running` | Start daemon if not already running (used by SessionStart hook) |
+| `clooks add <path>` | Install a plugin from a local directory |
+| `clooks remove <name>` | Uninstall a plugin and its contributed handlers |
+| `clooks plugins` | List installed plugins and their handlers |
+| `clooks rotate-token` | Generate a new auth token, update manifest + settings.json, hot-reload daemon |
+| `clooks costs` | Show LLM token usage and cost breakdown |
 
 ## Manifest Format
 
@@ -281,9 +286,75 @@ LLM Cost Summary
 - Batching savings are estimated based on shared input tokens
 - Cost data also appears in `clooks stats` when LLM handlers have been used
 
+## v0.3 Features
+
+### Plugin System
+
+Plugins let you package and share sets of handlers. A plugin is any directory with a `clooks-plugin.yaml` spec:
+
+```yaml
+# clooks-plugin.yaml
+name: my-security-suite
+version: 1.0.0
+description: Security guards for tool calls
+handlers:
+  PreToolUse:
+    - id: bash-guard
+      type: inline
+      module: ./handlers/bash-guard.js
+      timeout: 3000
+    - id: file-guard
+      type: inline
+      module: ./handlers/file-guard.js
+      timeout: 2000
+```
+
+Install, remove, and list plugins:
+
+```bash
+clooks add ./my-security-suite     # install from local path
+clooks remove my-security-suite    # uninstall
+clooks plugins                     # list installed plugins + handlers
+```
+
+Handler IDs are namespaced to the plugin (`my-security-suite:bash-guard`) to avoid collisions with user-defined handlers or other plugins.
+
+### Dependency Resolution
+
+Handlers can declare dependencies on other handlers using the `depends` field. clooks resolves dependencies into topological execution waves -- handlers in the same wave run in parallel, waves execute sequentially.
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: context-loader
+      type: inline
+      module: ~/hooks/context.js
+
+    - id: security-check
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Check $TOOL_NAME for issues given context: $CONTEXT"
+      depends: [context-loader]    # waits for context-loader to finish first
+```
+
+In this example, `context-loader` runs in wave 1, and `security-check` runs in wave 2 after it completes. Handlers with no dependencies (or whose dependencies are already satisfied) run in parallel within the same wave.
+
+### Short-Circuit Chains
+
+When a `PreToolUse` handler returns a deny decision, clooks automatically skips the corresponding `PostToolUse` handlers for that tool call. This avoids wasted work (and wasted LLM calls) on tool invocations that were blocked.
+
+Deny results are cached with a 30-second TTL, so repeated calls to the same tool with the same arguments short-circuit without re-evaluating handlers.
+
+### Other v0.3 Improvements
+
+- **Auth token rotation:** `clooks rotate-token` generates a new token, updates manifest and settings.json, and hot-reloads the daemon -- no restart required.
+- **Health endpoint split:** `/health` is now public (returns `{ status: "ok" }` only). `/health/detail` requires auth and returns uptime, handler count, and plugin list.
+- **Rate limiting on auth failures:** In-memory rate limiter rejects with 429 after repeated failed auth attempts within a time window. Resets on successful auth.
+- **Session-scoped LLM batch groups:** Batch groups are now scoped to `{batchGroup}:{session_id}`, preventing cross-session batching violations.
+- **Manifest reload resets handler state:** Reloading the manifest now diffs old vs new handlers and resets session-isolated state for changed or new handlers.
+
 ## Roadmap
 
-- **v0.3:** Plugin ecosystem, dependency resolution between handlers
 - **v0.4:** Visual dashboard for hook management and metrics
 
 ## Contributing

package/dist/auth.d.ts

@@ -2,3 +2,16 @@
 export declare function generateAuthToken(): string;
 /** Validate an auth token from request headers. */
 export declare function validateAuth(authHeader: string | undefined, expectedToken: string): boolean;
+/** Options for overriding default paths (used by tests). */
+export interface RotateTokenOptions {
+    manifestPath?: string;
+    settingsDir?: string;
+}
+/**
+ * Rotate the auth token:
+ * 1. Generate new token
+ * 2. Update manifest.yaml settings.authToken
+ * 3. Update settings.json Authorization headers in HTTP hooks
+ * Returns the new token.
+ */
+export declare function rotateToken(options?: RotateTokenOptions): string;

package/dist/auth.js

@@ -3,7 +3,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateAuthToken = generateAuthToken;
 exports.validateAuth = validateAuth;
+exports.rotateToken = rotateToken;
 const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const yaml_1 = require("yaml");
+const path_1 = require("path");
+const os_1 = require("os");
+const constants_js_1 = require("./constants.js");
 /** Generate a random auth token (32 hex chars). */
 function generateAuthToken() {
     return (0, crypto_1.randomBytes)(16).toString('hex');
@@ -25,3 +31,79 @@ function validateAuth(authHeader, expectedToken) {
     const bufB = Buffer.from(expectedToken);
     return (0, crypto_1.timingSafeEqual)(bufA, bufB);
 }
+/**
+ * Rotate the auth token:
+ * 1. Generate new token
+ * 2. Update manifest.yaml settings.authToken
+ * 3. Update settings.json Authorization headers in HTTP hooks
+ * Returns the new token.
+ */
+function rotateToken(options) {
+    const manifestPath = options?.manifestPath ?? constants_js_1.MANIFEST_PATH;
+    const home = options?.settingsDir ?? (0, path_1.join)((0, os_1.homedir)(), '.claude');
+    if (!(0, fs_1.existsSync)(manifestPath)) {
+        throw new Error(`Manifest not found at ${manifestPath}`);
+    }
+    const newToken = generateAuthToken();
+    // Update manifest
+    const manifestRaw = (0, fs_1.readFileSync)(manifestPath, 'utf-8');
+    const manifest = (0, yaml_1.parse)(manifestRaw);
+    if (!manifest.settings) {
+        manifest.settings = {};
+    }
+    manifest.settings.authToken = newToken;
+    // Preserve comments at the top by only replacing the YAML body portion
+    const yamlBody = (0, yaml_1.stringify)(manifest);
+    // Check if there's a comment header to preserve
+    const lines = manifestRaw.split('\n');
+    const commentLines = [];
+    for (const line of lines) {
+        if (line.startsWith('#') || line.trim() === '') {
+            commentLines.push(line);
+        }
+        else {
+            break;
+        }
+    }
+    const header = commentLines.length > 0 ? commentLines.join('\n') + '\n' : '';
+    (0, fs_1.writeFileSync)(manifestPath, header + yamlBody, 'utf-8');
+    // Update settings.json Authorization headers
+    const settingsCandidates = [
+        (0, path_1.join)(home, 'settings.local.json'),
+        (0, path_1.join)(home, 'settings.json'),
+    ];
+    for (const settingsPath of settingsCandidates) {
+        if (!(0, fs_1.existsSync)(settingsPath))
+            continue;
+        try {
+            const raw = (0, fs_1.readFileSync)(settingsPath, 'utf-8');
+            const settings = JSON.parse(raw);
+            if (!settings.hooks || typeof settings.hooks !== 'object')
+                continue;
+            let updated = false;
+            for (const ruleGroups of Object.values(settings.hooks)) {
+                if (!Array.isArray(ruleGroups))
+                    continue;
+                for (const rule of ruleGroups) {
+                    if (!Array.isArray(rule.hooks))
+                        continue;
+                    for (const hook of rule.hooks) {
+                        if (hook.type === 'http' && hook.url?.includes(`localhost:`)) {
+                            if (!hook.headers)
+                                hook.headers = {};
+                            hook.headers['Authorization'] = `Bearer ${newToken}`;
+                            updated = true;
+                        }
+                    }
+                }
+            }
+            if (updated) {
+                (0, fs_1.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+            }
+        }
+        catch {
+            // Skip files that can't be parsed
+        }
+    }
+    return newToken;
+}

package/dist/builtin-hooks.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Content of the check-update.js hook script.
+ * Kept as a constant so it can be written to disk during init/migrate
+ * without depending on the npm package install path.
+ */
+export declare const CHECK_UPDATE_SCRIPT = "#!/usr/bin/env node\n\n// clooks built-in: check for updates on session start\n// Runs in background, non-blocking. Injects a notice if update available.\n\nconst { execSync } = require('child_process');\n\ntry {\n  // Get installed version\n  const pkgPath = require.resolve('@mauribadnights/clooks/package.json');\n  const pkg = JSON.parse(require('fs').readFileSync(pkgPath, 'utf-8'));\n  const current = pkg.version;\n\n  // Check npm (with short timeout to not block session start)\n  const latest = execSync('npm view @mauribadnights/clooks version 2>/dev/null', {\n    encoding: 'utf-8',\n    timeout: 5000,\n  }).trim();\n\n  if (latest && latest !== current && isNewer(latest, current)) {\n    const msg = `[clooks] Update available: ${current} \\u2192 ${latest}. Run: clooks update`;\n    process.stdout.write(JSON.stringify({ additionalContext: msg }));\n  }\n} catch {\n  // Silently fail \u2014 update checks should never block sessions\n}\n\nfunction isNewer(a, b) {\n  const pa = a.split('.').map(Number);\n  const pb = b.split('.').map(Number);\n  for (let i = 0; i < 3; i++) {\n    if ((pa[i] || 0) > (pb[i] || 0)) return true;\n    if ((pa[i] || 0) < (pb[i] || 0)) return false;\n  }\n  return false;\n}\n";
+/**
+ * Ensure the built-in hooks directory exists and write/update the check-update script.
+ * Safe to call multiple times — overwrites with the latest version.
+ */
+export declare function installBuiltinHooks(): void;

package/dist/builtin-hooks.js

@@ -0,0 +1,67 @@
+"use strict";
+// clooks built-in hook scripts — written to CONFIG_DIR/hooks/ during init/migrate
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHECK_UPDATE_SCRIPT = void 0;
+exports.installBuiltinHooks = installBuiltinHooks;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const constants_js_1 = require("./constants.js");
+/**
+ * Content of the check-update.js hook script.
+ * Kept as a constant so it can be written to disk during init/migrate
+ * without depending on the npm package install path.
+ */
+exports.CHECK_UPDATE_SCRIPT = `#!/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)) {
+    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;
+}
+`;
+/**
+ * Ensure the built-in hooks directory exists and write/update the check-update script.
+ * Safe to call multiple times — overwrites with the latest version.
+ */
+function installBuiltinHooks() {
+    if (!(0, fs_1.existsSync)(constants_js_1.HOOKS_DIR)) {
+        (0, fs_1.mkdirSync)(constants_js_1.HOOKS_DIR, { recursive: true });
+    }
+    const checkUpdatePath = (0, path_1.join)(constants_js_1.HOOKS_DIR, 'check-update.js');
+    // Only overwrite if content differs (avoids unnecessary writes)
+    if ((0, fs_1.existsSync)(checkUpdatePath)) {
+        const existing = (0, fs_1.readFileSync)(checkUpdatePath, 'utf-8');
+        if (existing === exports.CHECK_UPDATE_SCRIPT)
+            return;
+    }
+    (0, fs_1.writeFileSync)(checkUpdatePath, exports.CHECK_UPDATE_SCRIPT, { mode: 0o755 });
+}

package/dist/cli.js

@@ -9,13 +9,15 @@ const server_js_1 = require("./server.js");
 const migrate_js_1 = require("./migrate.js");
 const doctor_js_1 = require("./doctor.js");
 const auth_js_1 = require("./auth.js");
+const plugin_js_1 = require("./plugin.js");
 const constants_js_1 = require("./constants.js");
 const fs_1 = require("fs");
+const path_1 = require("path");
 const program = new commander_1.Command();
 program
     .name('clooks')
     .description('Persistent hook runtime for Claude Code')
-    .version('0.2.2');
+    .version('0.3.1');
 // --- start ---
 program
     .command('start')
@@ -49,7 +51,7 @@ program
     }
     // Foreground mode: run the actual server
     try {
-        const manifest = (0, manifest_js_1.loadManifest)();
+        const manifest = (0, manifest_js_1.loadCompositeManifest)();
         const metrics = new metrics_js_1.MetricsCollector();
         const port = manifest.settings?.port ?? constants_js_1.DEFAULT_PORT;
         const handlerCount = Object.values(manifest.handlers)
@@ -98,11 +100,13 @@ program
             req.setTimeout(3000, () => { req.destroy(); reject(new Error('timeout')); });
         });
         const health = JSON.parse(data);
+        const pluginCount = (0, plugin_js_1.listPlugins)().length;
         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}`);
+        console.log(`Plugins: ${pluginCount}`);
     }
     catch {
         console.log(`Status: running (pid ${pid})`);
@@ -116,6 +120,9 @@ program
     .action(() => {
     const metrics = new metrics_js_1.MetricsCollector();
     console.log(metrics.formatStatsTable());
+    console.log('');
+    console.log('Per Handler:');
+    console.log(metrics.formatHandlerStatsTable());
     // Append cost summary if LLM data exists
     const costStats = metrics.getCostStats();
     if (costStats.totalCost > 0) {
@@ -215,6 +222,128 @@ program
     console.log(`Auth token: ${token}`);
     console.log('Edit this file to configure your hook handlers.');
 });
+// --- rotate-token ---
+program
+    .command('rotate-token')
+    .description('Generate new auth token, update manifest and settings.json')
+    .action(() => {
+    try {
+        const newToken = (0, auth_js_1.rotateToken)();
+        console.log(`Auth token rotated successfully.`);
+        console.log(`New token: ${newToken}`);
+        console.log('If daemon is running, the file watcher will pick up the manifest change.');
+    }
+    catch (err) {
+        console.error('Token rotation failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+// --- update ---
+program
+    .command('update')
+    .description('Update clooks to the latest version')
+    .action(async () => {
+    console.log('Checking for updates...');
+    const currentVersion = program.version();
+    try {
+        const { execSync } = await import('child_process');
+        const latest = execSync('npm view @mauribadnights/clooks version', { encoding: 'utf-8' }).trim();
+        if (latest === currentVersion) {
+            console.log(`Already on latest version (${currentVersion}).`);
+            return;
+        }
+        console.log(`Updating: ${currentVersion} \u2192 ${latest}`);
+        execSync('npm install -g @mauribadnights/clooks@latest', { stdio: 'inherit' });
+        console.log(`Updated to ${latest}.`);
+        // Restart daemon if running
+        if ((0, server_js_1.isDaemonRunning)()) {
+            console.log('Restarting daemon...');
+            (0, server_js_1.stopDaemon)();
+            await new Promise(r => setTimeout(r, 1000));
+            (0, server_js_1.startDaemonBackground)();
+            await new Promise(r => setTimeout(r, 500));
+            console.log('Daemon restarted.');
+        }
+    }
+    catch (err) {
+        console.error('Update failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+// --- add (install plugin) ---
+program
+    .command('add <path>')
+    .description('Install a plugin from a local directory')
+    .action((pluginPath) => {
+    try {
+        const resolvedPath = (0, path_1.resolve)(pluginPath);
+        if (!(0, fs_1.existsSync)(resolvedPath)) {
+            console.error(`Path does not exist: ${resolvedPath}`);
+            process.exit(1);
+        }
+        const manifestFile = (0, path_1.resolve)(resolvedPath, constants_js_1.PLUGIN_MANIFEST_NAME);
+        if (!(0, fs_1.existsSync)(manifestFile)) {
+            console.error(`No ${constants_js_1.PLUGIN_MANIFEST_NAME} found at ${resolvedPath}`);
+            process.exit(1);
+        }
+        const plugin = (0, plugin_js_1.installPlugin)(resolvedPath);
+        // Count handlers in the installed plugin
+        const plugins = (0, plugin_js_1.loadPlugins)();
+        const installed = plugins.find(p => p.name === plugin.name);
+        const handlerCount = installed
+            ? Object.values(installed.manifest.handlers).reduce((sum, arr) => sum + (arr?.length ?? 0), 0)
+            : 0;
+        console.log(`Installed plugin ${plugin.name} v${plugin.version} (${handlerCount} handlers)`);
+    }
+    catch (err) {
+        console.error('Plugin install failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+// --- remove (uninstall plugin) ---
+program
+    .command('remove <name>')
+    .description('Uninstall a plugin')
+    .action((name) => {
+    try {
+        (0, plugin_js_1.uninstallPlugin)(name);
+        console.log(`Removed plugin ${name}`);
+    }
+    catch (err) {
+        console.error('Plugin removal failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+// --- plugins (list installed plugins) ---
+program
+    .command('plugins')
+    .description('List installed plugins')
+    .action(() => {
+    const plugins = (0, plugin_js_1.listPlugins)();
+    if (plugins.length === 0) {
+        console.log('No plugins installed.');
+        return;
+    }
+    // Load full manifests to access extras and handler counts
+    const loaded = (0, plugin_js_1.loadPlugins)();
+    const manifestMap = new Map(loaded.map(l => [l.name, l.manifest]));
+    console.log('Installed Plugins:');
+    for (const p of plugins) {
+        const manifest = manifestMap.get(p.name);
+        const handlerCount = manifest
+            ? Object.values(manifest.handlers).reduce((sum, arr) => sum + (arr?.length ?? 0), 0)
+            : 0;
+        console.log(`  ${p.name} v${p.version} (${handlerCount} handler${handlerCount !== 1 ? 's' : ''})`);
+        if (manifest?.extras) {
+            if (manifest.extras.skills && manifest.extras.skills.length > 0) {
+                console.log(`    Skills: ${manifest.extras.skills.join(', ')}`);
+            }
+            if (manifest.extras.agents && manifest.extras.agents.length > 0) {
+                console.log(`    Agents: ${manifest.extras.agents.join(', ')}`);
+            }
+        }
+    }
+});
 program.parse();
 function formatUptime(seconds) {
     if (seconds < 60)

package/dist/constants.d.ts

@@ -15,4 +15,8 @@ export declare const LLM_PRICING: Record<string, {
     input: number;
     output: number;
 }>;
+export declare const HOOKS_DIR: string;
+export declare const PLUGINS_DIR: string;
+export declare const PLUGIN_REGISTRY: string;
+export declare const PLUGIN_MANIFEST_NAME = "clooks-plugin.yaml";
 export declare const HOOK_EVENTS: string[];

package/dist/constants.js

@@ -1,7 +1,7 @@
 "use strict";
 // clooks constants
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HOOK_EVENTS = exports.LLM_PRICING = exports.DEFAULT_LLM_MAX_TOKENS = exports.DEFAULT_LLM_TIMEOUT = exports.COSTS_FILE = 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;
+exports.HOOK_EVENTS = exports.PLUGIN_MANIFEST_NAME = exports.PLUGIN_REGISTRY = exports.PLUGINS_DIR = exports.HOOKS_DIR = exports.LLM_PRICING = exports.DEFAULT_LLM_MAX_TOKENS = exports.DEFAULT_LLM_TIMEOUT = exports.COSTS_FILE = 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;
@@ -22,6 +22,10 @@ exports.LLM_PRICING = {
     'claude-sonnet-4-6': { input: 3.00, output: 15.00 },
     'claude-opus-4-6': { input: 15.00, output: 75.00 },
 };
+exports.HOOKS_DIR = (0, path_1.join)(exports.CONFIG_DIR, 'hooks');
+exports.PLUGINS_DIR = (0, path_1.join)(exports.CONFIG_DIR, 'plugins');
+exports.PLUGIN_REGISTRY = (0, path_1.join)(exports.PLUGINS_DIR, 'installed.json');
+exports.PLUGIN_MANIFEST_NAME = 'clooks-plugin.yaml';
 exports.HOOK_EVENTS = [
     'SessionStart',
     'UserPromptSubmit',

package/dist/deps.d.ts

@@ -0,0 +1,13 @@
+import type { HandlerConfig } from './types.js';
+/**
+ * Build a directed acyclic graph from handler dependencies.
+ * Returns handlers grouped into "waves" — each wave contains handlers
+ * that can execute in parallel (all their deps are in previous waves).
+ *
+ * Wave 0: handlers with no deps
+ * Wave 1: handlers whose deps are all in wave 0
+ * etc.
+ *
+ * Uses Kahn's algorithm. Throws on cycles.
+ */
+export declare function resolveExecutionOrder(handlers: HandlerConfig[]): HandlerConfig[][];

package/dist/deps.js

@@ -0,0 +1,83 @@
+"use strict";
+// clooks dependency resolution — topological ordering of handler execution
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveExecutionOrder = resolveExecutionOrder;
+/**
+ * Build a directed acyclic graph from handler dependencies.
+ * Returns handlers grouped into "waves" — each wave contains handlers
+ * that can execute in parallel (all their deps are in previous waves).
+ *
+ * Wave 0: handlers with no deps
+ * Wave 1: handlers whose deps are all in wave 0
+ * etc.
+ *
+ * Uses Kahn's algorithm. Throws on cycles.
+ */
+function resolveExecutionOrder(handlers) {
+    if (handlers.length === 0)
+        return [];
+    // Build lookup and adjacency
+    const handlerMap = new Map();
+    const inDegree = new Map();
+    const dependents = new Map(); // depId → [handlers that depend on it]
+    for (const h of handlers) {
+        handlerMap.set(h.id, h);
+        inDegree.set(h.id, 0);
+        if (!dependents.has(h.id)) {
+            dependents.set(h.id, []);
+        }
+    }
+    // Only consider deps that reference handlers in this set
+    const handlerIds = new Set(handlers.map(h => h.id));
+    for (const h of handlers) {
+        if (!h.depends || h.depends.length === 0)
+            continue;
+        for (const dep of h.depends) {
+            if (!handlerIds.has(dep)) {
+                // Dependency references a handler not in this event's set — skip silently
+                // (cross-event deps are not supported within a single executeHandlers call)
+                continue;
+            }
+            inDegree.set(h.id, (inDegree.get(h.id) ?? 0) + 1);
+            const existing = dependents.get(dep) ?? [];
+            existing.push(h.id);
+            dependents.set(dep, existing);
+        }
+    }
+    // BFS — Kahn's algorithm, collecting waves
+    const waves = [];
+    let queue = [];
+    // Wave 0: all handlers with in-degree 0
+    for (const [id, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(id);
+        }
+    }
+    let processedCount = 0;
+    while (queue.length > 0) {
+        const wave = [];
+        const nextQueue = [];
+        for (const id of queue) {
+            wave.push(handlerMap.get(id));
+            processedCount++;
+            // Decrement in-degree of dependents
+            for (const depId of dependents.get(id) ?? []) {
+                const newDegree = (inDegree.get(depId) ?? 1) - 1;
+                inDegree.set(depId, newDegree);
+                if (newDegree === 0) {
+                    nextQueue.push(depId);
+                }
+            }
+        }
+        waves.push(wave);
+        queue = nextQueue;
+    }
+    // Cycle detection: if not all handlers were processed, there's a cycle
+    if (processedCount < handlers.length) {
+        const cycleIds = handlers
+            .filter(h => (inDegree.get(h.id) ?? 0) > 0)
+            .map(h => h.id);
+        throw new Error(`Dependency cycle detected among handlers: ${cycleIds.join(', ')}`);
+    }
+    return waves;
+}

package/dist/doctor.js

@@ -10,6 +10,8 @@ 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");
+const plugin_js_1 = require("./plugin.js");
+const yaml_1 = require("yaml");
 /**
  * Run all diagnostic checks and return results.
  */
@@ -31,6 +33,8 @@ async function runDoctor() {
     results.push(checkStalePid());
     // 8. Auth token consistency (if configured)
     results.push(checkAuthToken());
+    // 9. Plugin health checks
+    results.push(...checkPluginHealth());
     return results;
 }
 function checkConfigDir() {
@@ -220,3 +224,55 @@ function checkAuthToken() {
         return { check: 'Auth token', status: 'ok', message: 'Could not load manifest for auth check' };
     }
 }
+function checkPluginHealth() {
+    const results = [];
+    try {
+        const registry = (0, plugin_js_1.loadRegistry)();
+        if (registry.plugins.length === 0) {
+            results.push({ check: 'Plugins', status: 'ok', message: 'No plugins installed' });
+            return results;
+        }
+        for (const plugin of registry.plugins) {
+            // Check directory exists
+            if (!(0, fs_1.existsSync)(plugin.path)) {
+                results.push({
+                    check: `Plugin "${plugin.name}"`,
+                    status: 'error',
+                    message: `Plugin directory missing: ${plugin.path}`,
+                });
+                continue;
+            }
+            // Check manifest exists and is valid
+            const manifestPath = (0, path_1.join)(plugin.path, constants_js_1.PLUGIN_MANIFEST_NAME);
+            if (!(0, fs_1.existsSync)(manifestPath)) {
+                results.push({
+                    check: `Plugin "${plugin.name}"`,
+                    status: 'error',
+                    message: `Plugin manifest missing: ${manifestPath}`,
+                });
+                continue;
+            }
+            try {
+                const raw = (0, fs_1.readFileSync)(manifestPath, 'utf-8');
+                const parsed = (0, yaml_1.parse)(raw);
+                (0, plugin_js_1.validatePluginManifest)(parsed);
+                results.push({
+                    check: `Plugin "${plugin.name}"`,
+                    status: 'ok',
+                    message: `v${plugin.version} — manifest valid`,
+                });
+            }
+            catch (err) {
+                results.push({
+                    check: `Plugin "${plugin.name}"`,
+                    status: 'error',
+                    message: `Invalid manifest: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        }
+    }
+    catch {
+        results.push({ check: 'Plugins', status: 'ok', message: 'Could not load plugin registry' });
+    }
+    return results;
+}