hookherald 0.4.0 → 0.5.0

package/bin/hh

@@ -7,4 +7,8 @@ while [ -L "$SELF" ]; do
   case "$SELF" in /*) ;; *) SELF="$DIR/$SELF" ;; esac
 done
 SCRIPT_DIR="$(cd "$(dirname "$SELF")" && pwd)"
-exec npx tsx "$SCRIPT_DIR/../src/cli.ts" "$@"
+PKG_DIR="$SCRIPT_DIR/.."
+
+# Use node --import directly instead of npx tsx for faster startup
+TSX_LOADER="$PKG_DIR/node_modules/tsx/dist/esm/index.mjs"
+exec node --import "$TSX_LOADER" "$PKG_DIR/src/cli.ts" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookherald",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Webhook relay for Claude Code — push notifications from any HTTP POST into running sessions",
   "type": "module",
   "license": "MIT",

package/src/observability.ts

@@ -38,6 +38,7 @@ export interface WatcherConfig {
 export interface RouteInfo {
   port: number;
   registeredAt: string;
+  lastHeartbeatAt: number;
   lastEventAt: string | null;
   eventCount: number;
   errorCount: number;

package/src/webhook-channel.ts

@@ -2,7 +2,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "node:http";
 import { readFileSync, watch as fsWatch, type FSWatcher } from "node:fs";
-import { execSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createLogger, type WatcherConfig } from "./observability.js";
@@ -146,16 +146,16 @@ function readConfig(): { slug: string; router_url: string; watchers: WatcherConf
   }
 }
 
-function executeCommand(cmd: string): string {
-  try {
-    return execSync(cmd, { encoding: "utf-8", shell: true, stdio: ["pipe", "pipe", "pipe"], timeout: 60000 }).trim();
-  } catch (err: any) {
-    return (err.stdout || "").trim();
-  }
+function executeCommand(cmd: string): Promise<string> {
+  return new Promise((resolve) => {
+    execFile("sh", ["-c", cmd], { encoding: "utf-8", timeout: 60000 }, (err, stdout) => {
+      resolve((stdout || "").trim());
+    });
+  });
 }
 
 async function runWatcher(watcher: WatcherConfig) {
-  const output = executeCommand(watcher.command);
+  const output = await executeCommand(watcher.command);
   if (!output) return;
 
   let parsed: any;
@@ -206,8 +206,8 @@ function startWatchers(watchers: WatcherConfig[]) {
     const key = watcherKey(w);
     if (watcherIntervals.has(key)) continue;
 
-    // Run immediately, then on interval
-    runWatcher(w);
+    // Run immediately (if registered), then on interval
+    if (registered) runWatcher(w);
     const timer = setInterval(() => runWatcher(w), w.interval * 1000);
     timer.unref();
     watcherIntervals.set(key, timer);
@@ -217,10 +217,12 @@ function startWatchers(watchers: WatcherConfig[]) {
   currentWatcherConfigs = watchers;
 }
 
-function loadAndStartWatchers() {
+async function loadAndStartWatchers() {
   const config = readConfig();
   const watchers = config?.watchers || [];
   startWatchers(watchers);
+  // Re-register so the router sees the updated watcher list
+  if (registered) await register();
 }
 
 function startConfigWatcher() {
@@ -259,6 +261,8 @@ httpServer.listen(0, "127.0.0.1", async () => {
   loadAndStartWatchers();
   startConfigWatcher();
   await register();
+  // Run watchers that were deferred during startup (before registration)
+  for (const w of currentWatcherConfigs) runWatcher(w);
   startHeartbeat();
 });
 

package/src/webhook-router.ts

@@ -24,8 +24,14 @@ const HOST = process.env.ROUTER_HOST || "127.0.0.1";
 const SECRET = process.env.WEBHOOK_SECRET || "";
 
 function safeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) {
+    // Compare against self to burn constant time, then return false
+    timingSafeEqual(bufA, bufA);
+    return false;
+  }
+  return timingSafeEqual(bufA, bufB);
 }
 
 const log = createLogger("router");
@@ -85,6 +91,7 @@ async function handleRegister(req: IncomingMessage, res: ServerResponse) {
   // Heartbeat: if same slug and same port, treat as keepalive
   const existing = routes.get(project_slug);
   if (existing && existing.port === port) {
+    existing.lastHeartbeatAt = Date.now();
     // Update watchers on heartbeat (supports hot reload)
     if (watchers && JSON.stringify(watchers) !== JSON.stringify(existing.watchers)) {
       existing.watchers = watchers;
@@ -98,6 +105,7 @@ async function handleRegister(req: IncomingMessage, res: ServerResponse) {
   const info: RouteInfo = {
     port,
     registeredAt: new Date().toISOString(),
+    lastHeartbeatAt: Date.now(),
     lastEventAt: null,
     eventCount: 0,
     errorCount: 0,
@@ -435,6 +443,34 @@ const statsInterval = setInterval(() => {
 }, 5000);
 statsInterval.unref();
 
+// Stale route cleanup: remove routes that missed 3 heartbeat intervals
+const HEARTBEAT_MS = parseInt(process.env.HH_HEARTBEAT_MS || "30000", 10);
+const STALE_THRESHOLD_MS = HEARTBEAT_MS * 3;
+
+const staleInterval = setInterval(() => {
+  const now = Date.now();
+  let changed = false;
+  for (const [slug, info] of routes) {
+    if (now - info.lastHeartbeatAt > STALE_THRESHOLD_MS) {
+      routes.delete(slug);
+      metrics.unregistrations++;
+      log.warn("reaped stale route", { slug, lastHeartbeatAgoMs: now - info.lastHeartbeatAt });
+      events.push({
+        id: newEventId(),
+        timestamp: new Date().toISOString(),
+        type: "unregister",
+        slug,
+        routingDecision: null,
+        durationMs: 0,
+        responseStatus: 200,
+      });
+      changed = true;
+    }
+  }
+  if (changed) broadcast("session", { sessions: getSessionsData() });
+}, STALE_THRESHOLD_MS);
+staleInterval.unref();
+
 function handleApiHealth(_req: IncomingMessage, res: ServerResponse) {
   res.writeHead(200, { "Content-Type": "application/json" });
   res.end(JSON.stringify({