@mauribadnights/clooks 0.2.0 → 0.3.0

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
 
@@ -97,6 +102,7 @@ settings:
 **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 overhead.
+- `llm` -- calls Anthropic Messages API. Supports prompt templates, batching, and cost tracking. *(v0.2+)*
 
 ## Observability
 
@@ -171,11 +177,54 @@ handlers:
       batchGroup: analysis    # batched with code-review into one API call
 ```
 
-Requires `@anthropic-ai/sdk` as a peer dependency and `ANTHROPIC_API_KEY` env var.
+**Setup:**
+
+```bash
+npm install @anthropic-ai/sdk    # peer dependency, only needed for llm handlers
+export ANTHROPIC_API_KEY=sk-...  # or set in manifest: settings.anthropicApiKey
+```
+
+**Prompt template variables:**
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `$TRANSCRIPT` | Pre-fetched transcript file | Last 50KB of session transcript |
+| `$GIT_STATUS` | `git status --porcelain` | Current working tree status |
+| `$GIT_DIFF` | `git diff --stat` | Changed files summary (max 20KB) |
+| `$ARGUMENTS` | `hook_input.tool_input` | JSON-stringified tool arguments |
+| `$TOOL_NAME` | `hook_input.tool_name` | Name of the tool being called |
+| `$PROMPT` | `hook_input.prompt` | User's prompt (UserPromptSubmit only) |
+| `$CWD` | `hook_input.cwd` | Current working directory |
+
+**LLM handler options:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | required | `claude-haiku-4-5`, `claude-sonnet-4-6`, or `claude-opus-4-6` |
+| `prompt` | string | required | Prompt template with `$VARIABLE` interpolation |
+| `batchGroup` | string | optional | Group ID -- handlers with same group make one API call |
+| `maxTokens` | number | `1024` | Maximum output tokens |
+| `temperature` | number | `1.0` | Sampling temperature |
+| `filter` | string | optional | Keyword filter (see Filtering) |
+| `timeout` | number | `30000` | Timeout in milliseconds |
+
+**How batching works:**
+
+When multiple LLM handlers share a `batchGroup` on the same event, clooks combines their prompts into a single multi-task API call and splits the structured response back to each handler. This means 3 Haiku calls become 1, saving ~2/3 of the input token cost and eliminating 2 round-trips.
 
 ### Intelligent Filtering
 
-Skip handlers based on keywords. Supports OR (`|`) and NOT (`!`) operators. Matching is case-insensitive against the full hook input JSON.
+Skip handlers based on keywords. The `filter` field works on **all handler types** -- script, inline, and llm.
+
+**Filter syntax:**
+
+```
+filter: "word1|word2"      # run if input contains word1 OR word2
+filter: "!word"            # run unless input contains word
+filter: "word1|!word2"     # run if word1 present AND word2 absent
+```
+
+Matching is case-insensitive against the full JSON-serialized hook input.
 
 ```yaml
 handlers:
@@ -204,9 +253,19 @@ handlers:
       prompt: "Summarize this session:\n$TRANSCRIPT\n\nGit changes:\n$GIT_DIFF"
 ```
 
+**Available prefetch keys:**
+
+| Key | Source | Max size | Description |
+|-----|--------|----------|-------------|
+| `transcript` | `transcript_path` file | 50KB (tail) | Session conversation history |
+| `git_status` | `git status --porcelain` | unbounded | Working tree status |
+| `git_diff` | `git diff --stat` | 20KB | Changed files summary |
+
+Pre-fetched data is cached for the duration of a single event dispatch. Errors on individual keys are silently caught -- a failed `git_status` won't prevent `transcript` from loading.
+
 ### Cost Tracking
 
-Track LLM token usage and costs per handler and model. Pricing is built-in for Haiku 4.5, Sonnet 4.6, and Opus 4.6.
+Track LLM token usage and costs per handler and model.
 
 ```
 $ clooks costs
@@ -222,11 +281,80 @@ LLM Cost Summary
     security-check         $0.0053 (12 calls, avg 178 tokens)
 ```
 
-Cost data also appears in `clooks stats` when LLM handlers have been used.
+- Costs are persisted to `~/.clooks/costs.jsonl`
+- Built-in pricing (per million tokens): Haiku ($0.80 / $4.00), Sonnet ($3.00 / $15.00), Opus ($15.00 / $75.00)
+- 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

@@ -0,0 +1,17 @@
+/** Generate a random auth token (32 hex chars). */
+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

@@ -0,0 +1,109 @@
+"use strict";
+// clooks auth — token-based request authentication
+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');
+}
+/** Validate an auth token from request headers. */
+function validateAuth(authHeader, expectedToken) {
+    if (!expectedToken)
+        return true; // No token configured = no auth required
+    if (!authHeader)
+        return false;
+    // Support "Bearer <token>" format
+    const token = authHeader.startsWith('Bearer ')
+        ? authHeader.slice(7)
+        : authHeader;
+    // Constant-time comparison to prevent timing attacks
+    if (token.length !== expectedToken.length)
+        return false;
+    const bufA = Buffer.from(token);
+    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

@@ -8,19 +8,24 @@ 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 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.0');
+    .version('0.3.0');
 // --- start ---
 program
     .command('start')
     .description('Start the clooks daemon')
     .option('-f, --foreground', 'Run in foreground (default: background/detached)')
+    .option('--no-watch', 'Disable file watching for manifest changes')
     .action(async (opts) => {
+    const noWatch = opts.watch === false;
     if (!opts.foreground) {
         // Background mode: check if already running, then spawn detached
         if ((0, server_js_1.isDaemonRunning)()) {
@@ -32,7 +37,7 @@ program
             (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
         }
         console.log('Starting clooks daemon in background...');
-        (0, server_js_1.startDaemonBackground)();
+        (0, server_js_1.startDaemonBackground)({ noWatch });
         // Give it a moment to start
         await new Promise((r) => setTimeout(r, 500));
         if ((0, server_js_1.isDaemonRunning)()) {
@@ -46,12 +51,12 @@ 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)
             .reduce((sum, arr) => sum + (arr?.length ?? 0), 0);
-        await (0, server_js_1.startDaemon)(manifest, metrics);
+        await (0, server_js_1.startDaemon)(manifest, metrics, { noWatch });
         console.log(`clooks daemon running on 127.0.0.1:${port} (${handlerCount} handler${handlerCount !== 1 ? 's' : ''})`);
     }
     catch (err) {
@@ -95,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})`);
@@ -206,10 +213,134 @@ program
     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)();
+    const token = (0, auth_js_1.generateAuthToken)();
+    const path = (0, manifest_js_1.createDefaultManifest)(token);
     console.log(`Created: ${path}`);
+    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[][];