@interactive-inc/claude-funnel 0.4.0 → 0.7.1

package/lib/modules/gateway/funnel-gateway-server.ts

@@ -0,0 +1,241 @@
+import type { Server, ServerWebSocket } from "bun"
+import { Hono } from "hono"
+import type { FunnelConnectors } from "@/modules/connectors/funnel-connectors"
+import type { FunnelFileSystem } from "@/modules/fs/funnel-file-system"
+import { FunnelBroadcaster } from "@/modules/gateway/funnel-broadcaster"
+import { FunnelEventLogger } from "@/modules/gateway/funnel-event-logger"
+import { killCompetingSlackGateways } from "@/modules/gateway/kill-competing-slack-gateways"
+import { FunnelLogger } from "@/modules/logger/funnel-logger"
+import { NodeFunnelLogger } from "@/modules/logger/node-funnel-logger"
+import type { FunnelProcessRunner } from "@/modules/process/funnel-process-runner"
+import type { FunnelSettingsReader } from "@/modules/settings/funnel-settings-reader"
+import type { FunnelClock } from "@/modules/time/funnel-clock"
+
+const DEFAULT_PORT = 9742
+const DEFAULT_LOG_DIR = "/tmp/funnel/events"
+
+type Deps = {
+  connectors: FunnelConnectors
+  settings: FunnelSettingsReader
+  port?: number
+  logDir?: string
+  fs?: FunnelFileSystem
+  process?: FunnelProcessRunner
+  clock?: FunnelClock
+  logger?: FunnelLogger
+  selfPid?: number
+  killCompetingSlack?: boolean
+}
+
+type WsData = { channel: string; connectors: string[] }
+
+const defaultLogger = new NodeFunnelLogger()
+
+/**
+ * In-process gateway: runs `Bun.serve` (HTTP + WebSocket /ws), boots all
+ * connector listeners, fans events out via FunnelBroadcaster, and persists
+ * them via FunnelEventLogger. Useful for embedding the gateway in a custom
+ * host or driving it from tests.
+ */
+export class FunnelGatewayServer {
+  private readonly connectors: FunnelConnectors
+  private readonly settings: FunnelSettingsReader
+  private readonly port: number
+  private readonly logDir: string
+  private readonly fs?: FunnelFileSystem
+  private readonly process?: FunnelProcessRunner
+  private readonly logger: FunnelLogger
+  private readonly selfPid: number
+  private readonly killCompetingSlack: boolean
+  private readonly broadcaster: FunnelBroadcaster
+  private readonly eventLogger: FunnelEventLogger
+  private server: Server<WsData> | null = null
+
+  constructor(deps: Deps) {
+    this.connectors = deps.connectors
+    this.settings = deps.settings
+    this.port = deps.port ?? DEFAULT_PORT
+    this.logDir = deps.logDir ?? DEFAULT_LOG_DIR
+    this.fs = deps.fs
+    this.process = deps.process
+    this.logger = deps.logger ?? defaultLogger
+    this.selfPid = deps.selfPid ?? globalThis.process.pid
+    this.killCompetingSlack = deps.killCompetingSlack ?? true
+    this.broadcaster = new FunnelBroadcaster()
+    this.eventLogger = new FunnelEventLogger({
+      logDir: this.logDir,
+      fs: this.fs,
+      now: deps.clock ? () => deps.clock!.millis() : undefined,
+    })
+  }
+
+  async start(): Promise<Server<WsData>> {
+    if (this.server) return this.server
+
+    const app = this.buildApp()
+
+    this.server = Bun.serve<WsData>({
+      port: this.port,
+      fetch: (request, server) => {
+        const url = new URL(request.url)
+
+        if (url.pathname === "/ws" && request.headers.get("upgrade") === "websocket") {
+          const channelName = url.searchParams.get("channel") ?? ""
+          const connectors = channelName ? this.resolveConnectors(channelName) : []
+          const data: WsData = { channel: channelName, connectors }
+          const upgraded = server.upgrade(request, { data })
+
+          if (upgraded) return undefined
+
+          return new Response("WebSocket upgrade failed", { status: 400 })
+        }
+
+        return app.fetch(request)
+      },
+      websocket: {
+        open: (ws: ServerWebSocket<WsData>) => {
+          const data = ws.data
+
+          this.broadcaster.addClient(ws, data)
+          this.eventLogger.log("channel connected", {
+            event_type: "system",
+            action: "channel_connect",
+            channel: data.channel,
+            connectors: data.connectors.join(","),
+            total: String(this.broadcaster.getClientCount()),
+          })
+        },
+        close: (ws: ServerWebSocket<WsData>) => {
+          this.broadcaster.removeClient(ws)
+          this.eventLogger.log("channel disconnected", {
+            event_type: "system",
+            action: "channel_disconnect",
+            total: String(this.broadcaster.getClientCount()),
+          })
+        },
+        message() {
+          // future: client → gateway messages
+        },
+      },
+    })
+
+    this.eventLogger.log("gateway started", {
+      event_type: "system",
+      action: "gateway_start",
+      port: String(this.port),
+      pid: String(this.selfPid),
+    })
+
+    this.logger.info("funnel gateway listening", {
+      url: `http://localhost:${this.port}`,
+      websocket: `ws://localhost:${this.port}/ws`,
+      health: `http://localhost:${this.port}/health`,
+    })
+
+    await this.bootListeners()
+
+    return this.server
+  }
+
+  stop(): void {
+    if (!this.server) return
+
+    this.server.stop()
+    this.server = null
+  }
+
+  getStatus(): { clients: number; channels: { channel: string; connectors: string[] }[] } {
+    return {
+      clients: this.broadcaster.getClientCount(),
+      channels: this.broadcaster.listChannels(),
+    }
+  }
+
+  getBroadcaster(): FunnelBroadcaster {
+    return this.broadcaster
+  }
+
+  private buildApp(): Hono {
+    const app = new Hono()
+
+    app.get("/health", (c) =>
+      c.json({
+        ok: true,
+        pid: this.selfPid,
+        clients: this.broadcaster.getClientCount(),
+      }),
+    )
+
+    app.get("/status", (c) =>
+      c.json({
+        ok: true,
+        clients: this.broadcaster.listChannels(),
+      }),
+    )
+
+    return app
+  }
+
+  private resolveConnectors(channelName: string): string[] {
+    const settings = this.settings.read()
+    const channel = settings?.channels.find((c) => c.name === channelName)
+
+    return channel?.connectors ?? []
+  }
+
+  private async bootListeners(): Promise<void> {
+    const allConnectors = this.connectors.list()
+
+    if (this.killCompetingSlack && allConnectors.some((c) => c.type === "slack")) {
+      const killed = await killCompetingSlackGateways({
+        selfPid: this.selfPid,
+        process: this.process,
+        logger: this.logger,
+      })
+
+      if (killed.length > 0) {
+        this.eventLogger.log("killed competing Slack gateway processes", {
+          event_type: "system",
+          action: "kill_competing",
+          pids: killed.join(","),
+        })
+      }
+    }
+
+    for (const { config, listener } of this.connectors.createListeners()) {
+      const bind = (content: string, meta?: Record<string, string>) =>
+        this.notify(config.name, content, meta)
+
+      try {
+        await listener.start(bind)
+
+        this.eventLogger.log(`${config.type} listener started: ${config.name}`, {
+          event_type: "system",
+          action: `${config.type}_connect`,
+          connector: config.name,
+        })
+
+        this.logger.info(`${config.type} listener started`, { connector: config.name })
+      } catch (error) {
+        this.logger.error(`${config.type} listener failed`, {
+          connector: config.name,
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
+
+    this.logger.info(`event logs: ${this.logDir}`)
+    this.logger.info("funnel gateway running")
+  }
+
+  private async notify(
+    connectorName: string,
+    content: string,
+    meta?: Record<string, string>,
+  ): Promise<void> {
+    const withConnector: Record<string, string> = { ...meta, connector: connectorName }
+
+    this.eventLogger.log(content, withConnector)
+    this.broadcaster.broadcast(content, withConnector)
+  }
+}

package/lib/modules/gateway/funnel-gateway.ts

@@ -4,28 +4,57 @@ import { NodeFunnelFileSystem } from "@/modules/fs/node-funnel-file-system"
 import { FunnelProcessRunner } from "@/modules/process/funnel-process-runner"
 import { NodeFunnelProcessRunner } from "@/modules/process/node-funnel-process-runner"
 import { FUNNEL_DIR } from "@/modules/settings/funnel-settings-store"
+import { FunnelClock } from "@/modules/time/funnel-clock"
+import { NodeFunnelClock } from "@/modules/time/node-funnel-clock"
 
 const DEFAULT_PORT = 9742
-const PID_FILE = join(FUNNEL_DIR, "gateway.pid")
-const LOG_DIR = "/tmp/funnel/events"
-const GATEWAY_LOG = "/tmp/funnel/gateway.log"
-const TMP_DIR = "/tmp/funnel"
+const DEFAULT_TMP_DIR = "/tmp/funnel"
 
 type Deps = {
   process?: FunnelProcessRunner
   fs?: FunnelFileSystem
+  clock?: FunnelClock
+  dir?: string
+  tmpDir?: string
+  port?: number
+  sleep?: (ms: number) => Promise<void>
 }
 
 const defaultProcess = new NodeFunnelProcessRunner()
 const defaultFs = new NodeFunnelFileSystem()
-
+const defaultClock = new NodeFunnelClock()
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((r) => {
+    setTimeout(r, ms)
+  })
+
+/**
+ * Manages the gateway daemon as a separate process via PID file.
+ * Use `start()` to spawn `bun daemon.ts` in the background and `stop()` to
+ * terminate it. For an in-process gateway, use `Funnel.gatewayServer` instead.
+ */
 export class FunnelGateway {
   private readonly process: FunnelProcessRunner
   private readonly fs: FunnelFileSystem
+  private readonly clock: FunnelClock
+  private readonly pidFile: string
+  private readonly logDir: string
+  private readonly gatewayLog: string
+  private readonly tmpDir: string
+  private readonly port: number
+  private readonly sleep: (ms: number) => Promise<void>
 
   constructor(deps: Deps = {}) {
     this.process = deps.process ?? defaultProcess
     this.fs = deps.fs ?? defaultFs
+    this.clock = deps.clock ?? defaultClock
+    const baseDir = deps.dir ?? FUNNEL_DIR
+    this.tmpDir = deps.tmpDir ?? DEFAULT_TMP_DIR
+    this.pidFile = join(baseDir, "gateway.pid")
+    this.logDir = join(this.tmpDir, "events")
+    this.gatewayLog = join(this.tmpDir, "gateway.log")
+    this.port = deps.port ?? DEFAULT_PORT
+    this.sleep = deps.sleep ?? defaultSleep
     Object.freeze(this)
   }
 
@@ -41,20 +70,20 @@ export class FunnelGateway {
     const pid = this.readPid()
     const running = pid !== null && this.isProcessAlive(pid)
 
-    return { running, pid: running ? pid : null, port: DEFAULT_PORT }
+    return { running, pid: running ? pid : null, port: this.port }
   }
 
   async start(options: { caffeinate?: boolean } = {}): Promise<boolean> {
     if (this.isRunning()) return true
 
-    this.fs.mkdirSync(TMP_DIR, { recursive: true })
+    this.fs.mkdirSync(this.tmpDir, { recursive: true })
 
     const gatewayScript = resolve(import.meta.dir, "./daemon.ts")
     const command = this.buildStartCommand(gatewayScript, options)
 
     this.process.detach(["bash", "-c", command])
 
-    await Bun.sleep(800)
+    await this.sleep(800)
 
     return this.isRunning()
   }
@@ -63,7 +92,7 @@ export class FunnelGateway {
     const useCaffeinate = options.caffeinate !== false && globalThis.process.platform === "darwin"
     const prefix = useCaffeinate ? "caffeinate -i " : ""
 
-    return `nohup ${prefix}bun ${gatewayScript} >> ${GATEWAY_LOG} 2>&1 &`
+    return `nohup ${prefix}bun ${gatewayScript} >> ${this.gatewayLog} 2>&1 &`
   }
 
   async stop(): Promise<boolean> {
@@ -77,29 +106,29 @@ export class FunnelGateway {
     }
 
     try {
-      globalThis.process.kill(pid, "SIGTERM")
+      this.process.kill(pid, "SIGTERM")
     } catch {
       return false
     }
 
-    const deadline = Date.now() + 2000
+    const deadline = this.clock.millis() + 2000
 
-    while (Date.now() < deadline) {
+    while (this.clock.millis() < deadline) {
       if (!this.isProcessAlive(pid)) {
         this.removePid()
         return true
       }
 
-      await Bun.sleep(100)
+      await this.sleep(100)
     }
 
     try {
-      globalThis.process.kill(pid, "SIGKILL")
+      this.process.kill(pid, "SIGKILL")
     } catch {
       // ignore
     }
 
-    await Bun.sleep(200)
+    await this.sleep(200)
     this.removePid()
 
     return !this.isProcessAlive(pid)
@@ -126,18 +155,18 @@ export class FunnelGateway {
   }
 
   getLogDir(): string {
-    return LOG_DIR
+    return this.logDir
   }
 
   getGatewayLog(): string {
-    return GATEWAY_LOG
+    return this.gatewayLog
   }
 
   private readPid(): number | null {
-    if (!this.fs.existsSync(PID_FILE)) return null
+    if (!this.fs.existsSync(this.pidFile)) return null
 
     try {
-      const content = this.fs.readFileSync(PID_FILE).trim()
+      const content = this.fs.readFileSync(this.pidFile).trim()
       const pid = Number(content)
 
       if (!pid || pid <= 0) return null
@@ -149,7 +178,7 @@ export class FunnelGateway {
   }
 
   private removePid(): void {
-    this.fs.unlink(PID_FILE)
+    this.fs.unlink(this.pidFile)
   }
 
   private isProcessAlive(pid: number): boolean {

package/lib/modules/gateway/kill-competing-slack-gateways.ts

@@ -1,13 +1,16 @@
-import { logger } from "@/modules/logger"
+import { FunnelLogger } from "@/modules/logger/funnel-logger"
+import { NodeFunnelLogger } from "@/modules/logger/node-funnel-logger"
 import { FunnelProcessRunner } from "@/modules/process/funnel-process-runner"
 import { NodeFunnelProcessRunner } from "@/modules/process/node-funnel-process-runner"
 
 type Props = {
   selfPid: number
   process?: FunnelProcessRunner
+  logger?: FunnelLogger
 }
 
 const defaultProcess = new NodeFunnelProcessRunner()
+const defaultLogger = new NodeFunnelLogger()
 
 const isBun = (args: string): boolean => {
   return args.includes("bun ") || /\/bun(\s|$)/.test(args)
@@ -19,6 +22,7 @@ const looksLikeSlackGateway = (args: string): boolean => {
 
 export const killCompetingSlackGateways = async (props: Props): Promise<number[]> => {
   const runner = props.process ?? defaultProcess
+  const logger = props.logger ?? defaultLogger
   const result = await runner.run(["ps", "-e", "-o", "pid=,args="])
 
   if (result.exitCode !== 0) return []

package/lib/modules/id/funnel-id-generator.ts

@@ -0,0 +1,7 @@
+/**
+ * ID generator boundary. Default NodeFunnelIdGenerator wraps `crypto.randomUUID()`;
+ * MemoryFunnelIdGenerator emits `<prefix>-1, <prefix>-2, ...` for deterministic tests.
+ */
+export abstract class FunnelIdGenerator {
+  abstract generate(): string
+}

package/lib/modules/id/memory-funnel-id-generator.ts

@@ -0,0 +1,20 @@
+import { FunnelIdGenerator } from "@/modules/id/funnel-id-generator"
+
+type Props = {
+  prefix?: string
+}
+
+export class MemoryFunnelIdGenerator extends FunnelIdGenerator {
+  private counter = 0
+  private readonly prefix: string
+
+  constructor(props: Props = {}) {
+    super()
+    this.prefix = props.prefix ?? "id"
+  }
+
+  generate(): string {
+    this.counter++
+    return `${this.prefix}-${this.counter}`
+  }
+}

package/lib/modules/id/node-funnel-id-generator.ts

@@ -0,0 +1,7 @@
+import { FunnelIdGenerator } from "@/modules/id/funnel-id-generator"
+
+export class NodeFunnelIdGenerator extends FunnelIdGenerator {
+  generate(): string {
+    return crypto.randomUUID()
+  }
+}

package/lib/modules/logger/funnel-logger.ts

@@ -0,0 +1,11 @@
+/**
+ * Structured logger with three levels and an optional log-file path.
+ * Defaults to NodeFunnelLogger (appends to /tmp/funnel/funnel.log);
+ * MemoryFunnelLogger captures entries in memory and NoopFunnelLogger silences output.
+ */
+export abstract class FunnelLogger {
+  abstract info(message: string, meta?: Record<string, unknown>): void
+  abstract warn(message: string, meta?: Record<string, unknown>): void
+  abstract error(message: string, meta?: Record<string, unknown>): void
+  abstract readonly file: string | null
+}

package/lib/modules/logger/memory-funnel-logger.ts

@@ -0,0 +1,28 @@
+import { FunnelLogger } from "@/modules/logger/funnel-logger"
+
+export type LogEntry = {
+  level: "info" | "warn" | "error"
+  message: string
+  meta?: Record<string, unknown>
+}
+
+export class MemoryFunnelLogger extends FunnelLogger {
+  readonly file = null
+  readonly entries: LogEntry[] = []
+
+  info(message: string, meta?: Record<string, unknown>): void {
+    this.entries.push({ level: "info", message, meta })
+  }
+
+  warn(message: string, meta?: Record<string, unknown>): void {
+    this.entries.push({ level: "warn", message, meta })
+  }
+
+  error(message: string, meta?: Record<string, unknown>): void {
+    this.entries.push({ level: "error", message, meta })
+  }
+
+  clear(): void {
+    this.entries.length = 0
+  }
+}

package/lib/modules/logger/node-funnel-logger.ts

@@ -0,0 +1,49 @@
+import { appendFileSync, mkdirSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { FunnelLogger } from "@/modules/logger/funnel-logger"
+
+const DEFAULT_LOG_FILE = join("/tmp/funnel", "funnel.log")
+
+type Level = "info" | "warn" | "error"
+
+type Props = {
+  file?: string
+  now?: () => Date
+}
+
+export class NodeFunnelLogger extends FunnelLogger {
+  readonly file: string
+  private readonly now: () => Date
+
+  constructor(props: Props = {}) {
+    super()
+    this.file = props.file ?? DEFAULT_LOG_FILE
+    this.now = props.now ?? (() => new Date())
+    Object.freeze(this)
+  }
+
+  info(message: string, meta?: Record<string, unknown>): void {
+    this.write("info", message, meta)
+  }
+
+  warn(message: string, meta?: Record<string, unknown>): void {
+    this.write("warn", message, meta)
+  }
+
+  error(message: string, meta?: Record<string, unknown>): void {
+    this.write("error", message, meta)
+  }
+
+  private write(level: Level, message: string, meta?: Record<string, unknown>): void {
+    mkdirSync(dirname(this.file), { recursive: true })
+
+    const entry = {
+      time: this.now().toISOString(),
+      level,
+      message,
+      ...(meta ? { meta } : {}),
+    }
+
+    appendFileSync(this.file, `${JSON.stringify(entry)}\n`)
+  }
+}

package/lib/modules/logger/noop-funnel-logger.ts

@@ -0,0 +1,9 @@
+import { FunnelLogger } from "@/modules/logger/funnel-logger"
+
+export class NoopFunnelLogger extends FunnelLogger {
+  readonly file = null
+
+  info(): void {}
+  warn(): void {}
+  error(): void {}
+}

package/lib/modules/mcp/funnel-mcp.ts

@@ -20,6 +20,11 @@ type Deps = {
 
 const defaultFs = new NodeFunnelFileSystem()
 
+/**
+ * Installs/uninstalls the funnel MCP entry into a target repository's
+ * `.mcp.json`. Detects an existing entry by command match so renaming is
+ * preserved across re-installs.
+ */
 export class FunnelMcp {
   private readonly fs: FunnelFileSystem
 

package/lib/modules/process/funnel-process-runner.ts

@@ -19,6 +19,11 @@ export type DetachOptions = {
   env?: Record<string, string>
 }
 
+/**
+ * Process boundary covering one-shot runs, sync runs, foreground attach, and
+ * detached background spawns. Default is NodeFunnelProcessRunner (Bun.spawn);
+ * MemoryFunnelProcessRunner records calls and lets tests stub responses.
+ */
 export abstract class FunnelProcessRunner {
   abstract run(command: string[], options?: RunOptions): Promise<RunResult>
   abstract runSync(command: string[]): RunResult

package/lib/modules/profiles/funnel-profiles.ts

@@ -5,6 +5,11 @@ type Deps = {
   store: FunnelSettingsReader
 }
 
+/**
+ * Named launch presets for `fnl claude` (channel + repo + sub-agent + env files).
+ * Implements ProfileChannelChecker / ProfileChannelRefUpdater so FunnelChannels
+ * can validate references without depending on the FunnelProfiles concrete type.
+ */
 export class FunnelProfiles {
   private readonly store: FunnelSettingsReader
 

package/lib/modules/repos/funnel-repositories.ts

@@ -7,6 +7,11 @@ type Deps = {
   mcp: FunnelMcp
 }
 
+/**
+ * Repository registry. Each entry has a name + filesystem path; add/remove
+ * also writes/removes the funnel MCP entry in `<path>/.mcp.json` so Claude Code
+ * picks it up automatically when launched in that directory.
+ */
 export class FunnelRepositories {
   private readonly store: FunnelSettingsReader
   private readonly mcp: FunnelMcp

package/lib/modules/schedule/funnel-schedule.ts

@@ -5,6 +5,11 @@ type Deps = {
   store: FunnelScheduleStore
 }
 
+/**
+ * Cron entry CRUD for a schedule connector. The schedule connector itself
+ * is created via `connectors.add({ type: "schedule", ... })`; this class
+ * manages the JSONL entries inside it.
+ */
 export class FunnelSchedule {
   private readonly store: FunnelScheduleStore
 

package/lib/modules/time/funnel-clock.ts

@@ -0,0 +1,15 @@
+/**
+ * Time boundary. Default NodeFunnelClock returns `new Date()`; MemoryFunnelClock
+ * is settable and `advance(ms)`-able for deterministic schedule / timeout tests.
+ */
+export abstract class FunnelClock {
+  abstract now(): Date
+
+  millis(): number {
+    return this.now().getTime()
+  }
+
+  iso(): string {
+    return this.now().toISOString()
+  }
+}

package/lib/modules/time/memory-funnel-clock.ts

@@ -0,0 +1,26 @@
+import { FunnelClock } from "@/modules/time/funnel-clock"
+
+type Props = {
+  start?: Date
+}
+
+export class MemoryFunnelClock extends FunnelClock {
+  private current: Date
+
+  constructor(props: Props = {}) {
+    super()
+    this.current = props.start ?? new Date(0)
+  }
+
+  now(): Date {
+    return new Date(this.current.getTime())
+  }
+
+  set(date: Date): void {
+    this.current = date
+  }
+
+  advance(ms: number): void {
+    this.current = new Date(this.current.getTime() + ms)
+  }
+}

package/lib/modules/time/node-funnel-clock.ts

@@ -0,0 +1,7 @@
+import { FunnelClock } from "@/modules/time/funnel-clock"
+
+export class NodeFunnelClock extends FunnelClock {
+  now(): Date {
+    return new Date()
+  }
+}