@mauribadnights/clooks 0.3.0 → 0.3.1

package/dist/cli.js

@@ -17,7 +17,7 @@ const program = new commander_1.Command();
 program
     .name('clooks')
     .description('Persistent hook runtime for Claude Code')
-    .version('0.3.0');
+    .version('0.3.1');
 // --- start ---
 program
     .command('start')
@@ -120,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) {

package/dist/metrics.d.ts

@@ -7,6 +7,16 @@ interface AggregatedStats {
     minDuration: number;
     maxDuration: number;
 }
+export interface HandlerStats {
+    handler: string;
+    event: string;
+    fires: number;
+    errors: number;
+    filtered: number;
+    avgDuration: number;
+    minDuration: number;
+    maxDuration: number;
+}
 export declare class MetricsCollector {
     private static readonly MAX_ENTRIES;
     private entries;
@@ -22,6 +32,10 @@ export declare class MetricsCollector {
     getStats(): AggregatedStats[];
     /** Get stats for a specific session. */
     getSessionStats(sessionId: string): AggregatedStats[];
+    /** Get per-handler stats (not just per-event). */
+    getHandlerStats(): HandlerStats[];
+    /** Format per-handler stats as a CLI-friendly table. */
+    formatHandlerStatsTable(): string;
     /** Flush is a no-op since we append on every record, but provided for API completeness. */
     flush(): void;
     /** Format stats as a CLI-friendly table. */

package/dist/metrics.js

@@ -95,6 +95,53 @@ class MetricsCollector {
         }
         return stats.sort((a, b) => b.fires - a.fires);
     }
+    /** Get per-handler stats (not just per-event). */
+    getHandlerStats() {
+        const all = this.loadAll();
+        const byHandler = new Map();
+        for (const entry of all) {
+            const existing = byHandler.get(entry.handler) ?? [];
+            existing.push(entry);
+            byHandler.set(entry.handler, existing);
+        }
+        const stats = [];
+        for (const [handler, entries] of byHandler) {
+            const durations = entries.map((e) => e.duration_ms);
+            stats.push({
+                handler,
+                event: entries[0].event,
+                fires: entries.length,
+                errors: entries.filter((e) => !e.ok).length,
+                filtered: entries.filter((e) => e.filtered).length,
+                avgDuration: durations.reduce((a, b) => a + b, 0) / durations.length,
+                minDuration: Math.min(...durations),
+                maxDuration: Math.max(...durations),
+            });
+        }
+        return stats.sort((a, b) => {
+            if (b.fires !== a.fires)
+                return b.fires - a.fires;
+            return b.avgDuration - a.avgDuration;
+        });
+    }
+    /** Format per-handler stats as a CLI-friendly table. */
+    formatHandlerStatsTable() {
+        const stats = this.getHandlerStats();
+        if (stats.length === 0) {
+            return 'No per-handler metrics recorded yet.';
+        }
+        const header = padHandlerRow(['Handler', 'Event', 'Fires', 'Errors', 'Avg ms', 'Max ms']);
+        const separator = '-'.repeat(header.length);
+        const rows = stats.map((s) => padHandlerRow([
+            s.handler,
+            s.event,
+            String(s.fires),
+            String(s.errors),
+            s.avgDuration.toFixed(1),
+            s.maxDuration.toFixed(1),
+        ]));
+        return [header, separator, ...rows].join('\n');
+    }
     /** Flush is a no-op since we append on every record, but provided for API completeness. */
     flush() {
         // Already written on each record()
@@ -249,3 +296,7 @@ function padRow(cols) {
     const widths = [20, 8, 8, 10, 10, 10];
     return cols.map((col, i) => col.padEnd(widths[i])).join('  ');
 }
+function padHandlerRow(cols) {
+    const widths = [35, 20, 7, 7, 8, 8];
+    return cols.map((col, i) => col.padEnd(widths[i])).join('  ');
+}

package/dist/migrate.d.ts

@@ -11,6 +11,15 @@ export interface MigratePathOptions {
  * Find the Claude Code settings.json path.
  */
 export declare function getSettingsPath(options?: MigratePathOptions): string | null;
+/**
+ * Derive a readable handler ID from a hook command.
+ *
+ * "node /path/to/gsd-check-update.js" -> "gsd-check-update"
+ * "node /path/to/hooks/post-action.js" -> "post-action"
+ * "python3 -m almicio.hooks.session_context" -> "almicio-session-context"
+ * "bash -c 'source ~/.zshrc; python3 /path/to/tts-summary.py'" -> "tts-summary"
+ */
+export declare function deriveHandlerId(command: string, event: string, index: number): string;
 /**
  * Migrate Claude Code settings.json command hooks to clooks HTTP hooks.
  *

package/dist/migrate.js

@@ -2,6 +2,7 @@
 // clooks migration utilities — convert shell hooks to HTTP hooks
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSettingsPath = getSettingsPath;
+exports.deriveHandlerId = deriveHandlerId;
 exports.migrate = migrate;
 exports.restore = restore;
 const fs_1 = require("fs");
@@ -26,6 +27,46 @@ function getSettingsPath(options) {
     }
     return null;
 }
+/**
+ * Derive a readable handler ID from a hook command.
+ *
+ * "node /path/to/gsd-check-update.js" -> "gsd-check-update"
+ * "node /path/to/hooks/post-action.js" -> "post-action"
+ * "python3 -m almicio.hooks.session_context" -> "almicio-session-context"
+ * "bash -c 'source ~/.zshrc; python3 /path/to/tts-summary.py'" -> "tts-summary"
+ */
+function deriveHandlerId(command, event, index) {
+    let basename = null;
+    // Try python3 -m module.name pattern
+    const moduleMatch = command.match(/python3?\s+-m\s+([\w.]+)/);
+    if (moduleMatch) {
+        const modulePath = moduleMatch[1];
+        const lastSegment = modulePath.split('.').pop() ?? '';
+        if (lastSegment)
+            basename = lastSegment;
+    }
+    // Try to find the last .js or .py file in the command
+    if (!basename) {
+        // Match quoted or unquoted file paths ending in .js or .py
+        const fileMatches = [...command.matchAll(/(?:["'])?([^\s"']+\.(?:js|py))(?:["'])?/g)];
+        if (fileMatches.length > 0) {
+            const lastFile = fileMatches[fileMatches.length - 1][1];
+            // Extract basename without extension
+            const parts = lastFile.split('/');
+            const filename = parts[parts.length - 1];
+            basename = filename.replace(/\.(js|py)$/, '');
+        }
+    }
+    if (!basename) {
+        return `migrated-${event.toLowerCase()}-${index}`;
+    }
+    // Sanitize: replace non-alphanumeric chars with hyphens, lowercase
+    let id = basename.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    if (!id) {
+        return `migrated-${event.toLowerCase()}-${index}`;
+    }
+    return id;
+}
 /**
  * Migrate Claude Code settings.json command hooks to clooks HTTP hooks.
  *
@@ -61,6 +102,7 @@ function migrate(options) {
     // Extract command hooks and build manifest
     const manifestHandlers = {};
     let handlerIndex = 0;
+    const usedIds = new Set();
     // NOTE: In v0.1, matchers from the original rule groups are not preserved in the
     // migrated HTTP hooks — all command hooks are consolidated into matcher-less rule groups.
     // This is acceptable because clooks dispatches based on event type, not matchers.
@@ -83,8 +125,14 @@ function migrate(options) {
             continue;
         manifestHandlers[event] = commandHooks.map((hook) => {
             handlerIndex++;
+            let id = deriveHandlerId(hook.command, event, handlerIndex);
+            // Ensure uniqueness: if ID already used, append index
+            if (usedIds.has(id)) {
+                id = `${id}-${handlerIndex}`;
+            }
+            usedIds.add(id);
             return {
-                id: `migrated-${event.toLowerCase()}-${handlerIndex}`,
+                id,
                 type: 'script',
                 command: hook.command,
                 timeout: hook.timeout ? hook.timeout * 1000 : 5000, // Claude uses seconds, we use ms

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mauribadnights/clooks",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Persistent hook runtime for Claude Code — eliminates process spawning overhead and gives you observability",
   "bin": {
     "clooks": "./dist/cli.js"