@interactive-inc/claude-funnel 0.7.1 → 0.8.0

package/lib/cli/routes/channels.$channel.rename.$newName.ts

@@ -0,0 +1,22 @@
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+
+export const renameHelp = `funnel channels rename — rename a channel
+
+usage:
+  funnel channels rename <old> <new>
+  funnel channels <old> rename <new>`
+
+export const channelsRenameHandler = factory.createHandlers(
+  zValidator("param", z.object({ channel: z.string(), newName: z.string() })),
+  zValidator("query", z.object({}), renameHelp),
+  (c) => {
+    const param = c.req.valid("param")
+    const funnel = c.var.funnel
+
+    funnel.channels.rename(param.channel, param.newName)
+
+    return c.text(`renamed channel "${param.channel}" to "${param.newName}"`)
+  },
+)

package/lib/cli/routes/channels.$channel.set.delivery.$mode.ts

@@ -0,0 +1,34 @@
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+import { channelDeliveryModeSchema } from "@/engine/settings/settings-schema"
+
+export const setDeliveryHelp = `funnel channels <name> set delivery <mode> — change a channel's routing mode
+
+usage: funnel channels <name> set delivery fanout | exclusive
+
+modes:
+  fanout      every connected WS client receives every event (default)
+  exclusive   each event is delivered to exactly one connected client (round-robin)
+
+tap=all clients (TUI dashboard, debugging) always receive regardless of mode.
+`
+
+export const channelsSetDeliveryHandler = factory.createHandlers(
+  zValidator(
+    "param",
+    z.object({
+      channel: z.string(),
+      mode: channelDeliveryModeSchema,
+    }),
+    setDeliveryHelp,
+  ),
+  (c) => {
+    const param = c.req.valid("param")
+    const funnel = c.var.funnel
+
+    funnel.channels.setDelivery(param.channel, param.mode)
+
+    return c.text(`channel "${param.channel}" delivery set to ${param.mode}`)
+  },
+)

package/lib/cli/routes/channels.$channel.ts

@@ -0,0 +1,34 @@
+import { HTTPException } from "hono/http-exception"
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+
+export const showHelp = `funnel channels <name> — show channel details`
+
+export const channelsShowHandler = factory.createHandlers(
+  zValidator("param", z.object({ channel: z.string() })),
+  zValidator("query", z.object({}), showHelp),
+  (c) => {
+    const param = c.req.valid("param")
+    const funnel = c.var.funnel
+    const channel = funnel.channels.get(param.channel)
+
+    if (!channel) {
+      throw new HTTPException(404, { message: `channel "${param.channel}" not found` })
+    }
+
+    const connectorLines = channel.connectors.length
+      ? channel.connectors.map((c) => `  - ${c.name} (${c.type}, id: ${c.id})`)
+      : ["  (none)"]
+
+    const lines = [
+      `id: ${channel.id}`,
+      `name: ${channel.name}`,
+      `delivery: ${channel.delivery}`,
+      `connectors:`,
+      ...connectorLines,
+    ]
+
+    return c.text(lines.join("\n"))
+  },
+)

package/lib/cli/routes/channels.add.$channel.ts

@@ -0,0 +1,33 @@
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+import { channelDeliveryModeSchema } from "@/engine/settings/settings-schema"
+
+export const addHelp = `funnel channels add — add a channel
+
+usage: funnel channels add <name> [--delivery fanout|exclusive]
+
+options:
+  --delivery    routing mode (default fanout):
+                  fanout      every connected client receives every event
+                  exclusive   each event delivered to exactly one client (round-robin)`
+
+export const channelsAddHandler = factory.createHandlers(
+  zValidator("param", z.object({ channel: z.string() })),
+  zValidator(
+    "query",
+    z.object({
+      delivery: channelDeliveryModeSchema.optional(),
+    }),
+    addHelp,
+  ),
+  (c) => {
+    const param = c.req.valid("param")
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+
+    const created = funnel.channels.add({ name: param.channel, delivery: query.delivery })
+
+    return c.text(`added channel "${created.name}" (id: ${created.id})`)
+  },
+)

package/lib/cli/routes/channels.remove.$channel.ts

@@ -0,0 +1,20 @@
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+
+export const removeHelp = `funnel channels remove — remove a channel
+
+usage: funnel channels remove <name>`
+
+export const channelsRemoveHandler = factory.createHandlers(
+  zValidator("param", z.object({ channel: z.string() })),
+  zValidator("query", z.object({}), removeHelp),
+  (c) => {
+    const param = c.req.valid("param")
+    const funnel = c.var.funnel
+
+    funnel.channels.remove(param.channel)
+
+    return c.text(`removed channel "${param.channel}"`)
+  },
+)

package/lib/cli/routes/channels.ts

@@ -0,0 +1,39 @@
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+
+export const groupHelp = `funnel channels — manage subscription boxes
+
+usage: funnel channels [subcommand]
+
+subcommands:
+  (none)                          list
+  add <name>                      add
+  remove <name>                   remove
+  <name>                          show details
+  <name> connectors                       list connectors
+  <name> connectors add <c> --type=...    add a connector
+
+examples:
+  funnel channels add prod-inbox
+  funnel channels prod-inbox connectors add prod-slack --type=slack --bot-token=xoxb-... --app-token=xapp-...
+  funnel channels prod-inbox`
+
+export const channelsGroupHandler = factory.createHandlers(
+  zValidator("query", z.object({}), groupHelp),
+  (c) => {
+    const funnel = c.var.funnel
+    const channels = funnel.channels.list()
+
+    if (channels.length === 0) return c.text("no channels")
+
+    const lines = channels.map((ch) => {
+      const names = ch.connectors.map((c) => c.name)
+      const connectors = names.length > 0 ? names.join(", ") : "(none)"
+
+      return `${ch.name} [${connectors}]`
+    })
+
+    return c.text(lines.join("\n"))
+  },
+)

package/lib/cli/routes/claude.ts

@@ -0,0 +1,69 @@
+import { HTTPException } from "hono/http-exception"
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { queryToCliArgs } from "@/cli/router/query-to-cli-args"
+import { zValidator } from "@/cli/router/validator"
+
+export const claudeHelp = `funnel claude — launch Claude Code
+
+usage:
+  funnel claude                          launch the default profile (first in the list)
+  funnel claude -p <name>                launch a named profile
+  funnel claude --profile <name>         (long form)
+  funnel claude --channel <name>         raw launch (no profile, cwd = current dir)
+
+options:
+  -p, --profile      profile name to launch
+  --channel          channel name (raw launch, ignored when --profile is given)
+
+Any other arguments are forwarded to the claude CLI.
+On launch the FUNNEL_CHANNEL_ID env var is set and MCP connects to the gateway.`
+
+const RESERVED_KEYS = ["profile", "channel"]
+
+export const claudeHandler = factory.createHandlers(
+  zValidator(
+    "query",
+    z
+      .object({
+        profile: z.string().optional(),
+        channel: z.string().optional(),
+      })
+      .passthrough(),
+    claudeHelp,
+  ),
+  async (c) => {
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+
+    if (query.channel && !query.profile) {
+      const exitCode = await funnel.claude.launch({
+        channel: query.channel,
+        userArgs: queryToCliArgs(c.req.url, RESERVED_KEYS),
+      })
+
+      process.exit(exitCode)
+    }
+
+    const profile = query.profile
+      ? funnel.profiles.get(query.profile)
+      : funnel.profiles.getDefault()
+
+    if (!profile) {
+      if (query.profile) {
+        throw new HTTPException(404, { message: `profile "${query.profile}" not found` })
+      }
+      return c.text(claudeHelp)
+    }
+
+    const exitCode = await funnel.claude.launch({
+      channel: profile.channelId,
+      cwd: profile.path,
+      subAgent: profile.subAgent,
+      userArgs: queryToCliArgs(c.req.url, RESERVED_KEYS),
+      profileName: profile.name,
+    })
+
+    process.exit(exitCode)
+  },
+)

package/lib/cli/routes/gateway.listeners.ts

@@ -0,0 +1,41 @@
+import { HTTPException } from "hono/http-exception"
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+
+export const listenersHelp = `funnel gateway listeners — show running connector listeners
+
+usage: funnel gateway listeners
+
+Reads /listeners from the running gateway daemon and prints the live registry.
+
+examples:
+  funnel gateway listeners`
+
+export const gatewayListenersHandler = factory.createHandlers(
+  zValidator("query", z.object({}), listenersHelp),
+  async (c) => {
+    const funnel = c.var.funnel
+    const result = await funnel.listeners.list()
+
+    if (result.state === "offline") {
+      throw new HTTPException(503, { message: "funnel gateway: not running" })
+    }
+
+    if (result.state === "error") {
+      throw new HTTPException(503, { message: `funnel gateway: ${result.reason}` })
+    }
+
+    if (result.listeners.length === 0) {
+      return c.text("funnel gateway: no running listeners")
+    }
+
+    const lines = result.listeners.map((entry) => {
+      const health = entry.alive ? "alive" : "dead"
+
+      return `  [${health.padEnd(5)}] ${entry.type.padEnd(8)} ${entry.name}`
+    })
+
+    return c.text(`funnel gateway: running listeners\n${lines.join("\n")}`)
+  },
+)

package/lib/cli/routes/gateway.logs.ts

@@ -0,0 +1,123 @@
+import { existsSync } from "node:fs"
+import { stringify } from "yaml"
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { NodeFunnelLogger } from "@/engine/logger/node-logger"
+import { zValidator } from "@/cli/router/validator"
+
+export const logsHelp = `funnel gateway logs — tail diagnostic logs
+
+usage: funnel gateway logs [-n <N>]
+
+options:
+  -n <N>                number of trailing lines to show (default: 20)
+
+Tails /tmp/funnel/funnel.log (the daemon's diagnostic stream — gateway
+lifecycle, channel connect/disconnect, listener boot). Exit with SIGINT.
+Output is formatted as YAML.
+
+Domain events fanned out to WebSocket clients live in the SQLite event
+store (<logDir>/events.db); they are not shown here. Subscribe via the
+WS endpoint or query the store directly.
+
+examples:
+  funnel gateway logs
+  funnel gateway logs -n 100`
+
+const logger = new NodeFunnelLogger()
+
+type LogEntry = {
+  time: string
+  level: string
+  message: string
+  meta?: unknown
+}
+
+const tryParseJson = (line: string): unknown => {
+  try {
+    return JSON.parse(line)
+  } catch {
+    return null
+  }
+}
+
+const isLogEntry = (value: unknown): value is LogEntry => {
+  if (value === null || typeof value !== "object") return false
+  if (!("time" in value) || typeof value.time !== "string") return false
+  if (!("level" in value) || typeof value.level !== "string") return false
+  if (!("message" in value) || typeof value.message !== "string") return false
+
+  return true
+}
+
+export const gatewayLogsHandler = factory.createHandlers(
+  zValidator(
+    "query",
+    z.object({
+      n: z.string().optional(),
+    }),
+    logsHelp,
+  ),
+  async (c) => {
+    const query = c.req.valid("query")
+    const path = logger.file
+
+    if (!path || !existsSync(path)) {
+      return c.text("no logs")
+    }
+
+    const lineCount = query.n ? Number(query.n) : 20
+
+    const tail = Bun.spawn(["tail", "-f", "-n", String(lineCount), path], {
+      stdout: "pipe",
+      stderr: "inherit",
+    })
+
+    const forward = (signal: "SIGINT" | "SIGTERM") => {
+      tail.kill(signal)
+    }
+
+    process.on("SIGINT", () => forward("SIGINT"))
+    process.on("SIGTERM", () => forward("SIGTERM"))
+
+    const reader = tail.stdout.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ""
+
+    logger.info("gateway.logs tail start", { file: path })
+
+    while (true) {
+      const result = await reader.read()
+
+      if (result.done) break
+
+      buffer += decoder.decode(result.value, { stream: true })
+
+      const lines = buffer.split("\n")
+      buffer = lines.pop() ?? ""
+
+      for (const line of lines) {
+        if (!line.trim()) continue
+
+        const parsed = tryParseJson(line)
+
+        if (!isLogEntry(parsed)) {
+          process.stdout.write(`${line}\n`)
+          continue
+        }
+
+        const output = {
+          time: parsed.time,
+          level: parsed.level,
+          message: parsed.message,
+          ...(parsed.meta ? { meta: parsed.meta } : {}),
+        }
+
+        process.stdout.write(`---\n${stringify(output)}`)
+      }
+    }
+
+    await tail.exited
+    process.exit(0)
+  },
+)

package/lib/{routes/gateway/restart.ts → cli/routes/gateway.restart.ts}

@@ -1,7 +1,18 @@
+import { HTTPException } from "hono/http-exception"
 import { z } from "zod"
-import { factory } from "@/factory"
-import { zValidator } from "@/modules/router/validator"
-import { help } from "@/routes/gateway/restart.help"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+
+export const restartHelp = `funnel gateway restart — restart the gateway
+
+usage: funnel gateway restart [--no-caffeine]
+
+Stops the running process then starts it again in background.
+On macOS wraps with caffeinate -i by default. Use --no-caffeine to disable.
+
+examples:
+  funnel gateway restart
+  funnel gateway restart --no-caffeine`
 
 export const gatewayRestartHandler = factory.createHandlers(
   zValidator(
@@ -9,7 +20,7 @@ export const gatewayRestartHandler = factory.createHandlers(
     z.object({
       "no-caffeine": z.string().optional(),
     }),
-    help,
+    restartHelp,
   ),
   async (c) => {
     const query = c.req.valid("query")
@@ -30,6 +41,10 @@ export const gatewayRestartHandler = factory.createHandlers(
 
     const body = lines.join("\n")
 
-    return result.ok ? c.text(body) : c.text(body, 500)
+    if (!result.ok) {
+      throw new HTTPException(500, { message: body })
+    }
+
+    return c.text(body)
   },
 )

package/lib/cli/routes/gateway.run.ts

@@ -0,0 +1,41 @@
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+import { resolveDaemonScript } from "@/gateway/resolve-daemon-script"
+
+export const runHelp = `funnel gateway run — run the gateway in foreground
+
+usage: funnel gateway run [--no-caffeine]
+
+For developers. The process is tied to the current terminal and exits on SIGINT / SIGTERM.
+On macOS wraps with caffeinate -i by default. Use --no-caffeine to disable.
+
+For normal usage prefer funnel gateway start.
+
+examples:
+  funnel gateway run
+  funnel gateway run --no-caffeine`
+
+export const gatewayRunHandler = factory.createHandlers(
+  zValidator(
+    "query",
+    z.object({
+      "no-caffeine": z.string().optional(),
+    }),
+    runHelp,
+  ),
+  async (c) => {
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+
+    const gatewayScript = resolveDaemonScript()
+    const useCaffeinate = query["no-caffeine"] !== "true" && process.platform === "darwin"
+    const command = useCaffeinate
+      ? ["caffeinate", "-i", "bun", gatewayScript]
+      : ["bun", gatewayScript]
+
+    const exitCode = await funnel.process.attach(command)
+
+    process.exit(exitCode)
+  },
+)

package/lib/cli/routes/gateway.start.ts

@@ -0,0 +1,50 @@
+import { HTTPException } from "hono/http-exception"
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+
+export const startHelp = `funnel gateway start — start the gateway in background
+
+usage: funnel gateway start [--no-caffeine]
+
+Daemonized with nohup, so it keeps running after the terminal is closed.
+On macOS wraps the process with caffeinate -i by default to prevent idle sleep.
+Use --no-caffeine to disable caffeinate.
+
+port: 9742 (override via FUNNEL_PORT)
+pid:  ~/.funnel/gateway.pid
+log:  /tmp/funnel/gateway.log
+
+examples:
+  funnel gateway start
+  funnel gateway start --no-caffeine`
+
+export const gatewayStartHandler = factory.createHandlers(
+  zValidator(
+    "query",
+    z.object({
+      "no-caffeine": z.string().optional(),
+    }),
+    startHelp,
+  ),
+  async (c) => {
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+
+    if (funnel.gateway.isRunning()) {
+      const status = funnel.gateway.getStatus()
+
+      return c.text(`funnel gateway: already running (pid ${status.pid})`)
+    }
+
+    const started = await funnel.gateway.start({
+      caffeinate: query["no-caffeine"] !== "true",
+    })
+
+    if (!started) {
+      throw new HTTPException(500, { message: "funnel gateway: failed to start" })
+    }
+
+    return c.text("funnel gateway: started")
+  },
+)

package/lib/cli/routes/gateway.status.ts

@@ -0,0 +1,19 @@
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+import { renderGatewayStatus } from "@/cli/routes/gateway"
+
+export const statusHelp = `funnel gateway status — show gateway running status
+
+usage: funnel gateway status
+
+When running, prints PID, port, and connected channel count. When not running, exits with 503.
+
+examples:
+  funnel gateway status
+  funnel gateway`
+
+export const gatewayStatusHandler = factory.createHandlers(
+  zValidator("query", z.object({}), statusHelp),
+  renderGatewayStatus,
+)

package/lib/cli/routes/gateway.stop.ts

@@ -0,0 +1,32 @@
+import { HTTPException } from "hono/http-exception"
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+
+export const stopHelp = `funnel gateway stop — stop the gateway
+
+usage: funnel gateway stop
+
+Terminates the process whose PID is stored in ~/.funnel/gateway.pid.
+
+examples:
+  funnel gateway stop`
+
+export const gatewayStopHandler = factory.createHandlers(
+  zValidator("query", z.object({}), stopHelp),
+  async (c) => {
+    const funnel = c.var.funnel
+
+    if (!funnel.gateway.isRunning()) {
+      return c.text("funnel gateway: no running process")
+    }
+
+    const stopped = await funnel.gateway.stop()
+
+    if (!stopped) {
+      throw new HTTPException(500, { message: "funnel gateway: failed to stop" })
+    }
+
+    return c.text("funnel gateway: stopped")
+  },
+)

package/lib/cli/routes/gateway.ts

@@ -0,0 +1,55 @@
+import { HTTPException } from "hono/http-exception"
+import type { Context } from "hono"
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import type { Env } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+
+export const groupHelp = `funnel gateway — manage the funnel daemon
+
+The gateway daemon hosts the WebSocket /ws (used by Claude MCP), the
+local web UI at /, and the listener supervisor that runs every
+connector. One daemon, one port (9742), one PID file.
+
+usage: funnel gateway [subcommand]
+
+subcommands:
+  status              show running status (default)
+  start               start in background
+  stop                stop
+  restart             stop then start
+  run                 start in foreground (for developers)
+  logs [-n <N>]       show event logs
+  listeners           list running connector listeners (alive / dead)
+
+examples:
+  funnel gateway                check status
+  funnel gateway restart        restart`
+
+export const renderGatewayStatus = async (c: Context<Env>) => {
+  const funnel = c.var.funnel
+  const status = funnel.gateway.getStatus()
+
+  if (!status.running) {
+    throw new HTTPException(503, { message: "funnel gateway: not running" })
+  }
+
+  const res = await fetch(`http://localhost:${status.port}/health`).catch(() => null)
+
+  if (!res) {
+    return c.text(`funnel gateway: running (pid ${status.pid}) — health check failed`)
+  }
+
+  const health: unknown = await res.json()
+  const clients =
+    health !== null && typeof health === "object" && "clients" in health ? health.clients : 0
+
+  return c.text(
+    `funnel gateway: running (pid ${status.pid})\n  port: ${status.port}\n  clients: ${clients ?? 0}`,
+  )
+}
+
+export const gatewayGroupHandler = factory.createHandlers(
+  zValidator("query", z.object({}), groupHelp),
+  renderGatewayStatus,
+)