@interactive-inc/claude-funnel 0.7.1 → 0.8.1

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,
+)

package/lib/cli/routes/index.ts

@@ -0,0 +1,202 @@
+import { HTTPException } from "hono/http-exception"
+import { factory } from "@/cli/factory"
+import {
+  addHelp as channelsAddHelp,
+  channelsAddHandler,
+} from "@/cli/routes/channels.add.$channel"
+import { channelsConnectorsGroupHandler } from "@/cli/routes/channels.$channel.connectors"
+import {
+  addHelp as channelsConnectorsAddHelp,
+  channelsConnectorsAddHandler,
+} from "@/cli/routes/channels.$channel.connectors.add.$connector"
+import {
+  channelsConnectorsRemoveHandler,
+  removeHelp as channelsConnectorsRemoveHelp,
+} from "@/cli/routes/channels.$channel.connectors.remove.$connector"
+import {
+  channelsConnectorsSetHandler,
+  setHelp as channelsConnectorsSetHelp,
+} from "@/cli/routes/channels.$channel.connectors.set.$connector"
+import { channelsConnectorsShowHandler } from "@/cli/routes/channels.$channel.connectors.$connector"
+import {
+  channelsConnectorsRenameHandler,
+  renameHelp as channelsConnectorsRenameHelp,
+} from "@/cli/routes/channels.$channel.connectors.$connector.rename.$newName"
+import { channelsConnectorsRequestHandler } from "@/cli/routes/channels.$channel.connectors.$connector.request"
+import { channelsConnectorsSchedulesGroupHandler } from "@/cli/routes/channels.$channel.connectors.$connector.schedules"
+import {
+  addHelp as channelsConnectorsSchedulesAddHelp,
+  channelsConnectorsSchedulesAddHandler,
+} from "@/cli/routes/channels.$channel.connectors.$connector.schedules.add.$id"
+import {
+  channelsConnectorsSchedulesRemoveHandler,
+  removeHelp as channelsConnectorsSchedulesRemoveHelp,
+} from "@/cli/routes/channels.$channel.connectors.$connector.schedules.remove.$id"
+import {
+  channelsRemoveHandler,
+  removeHelp as channelsRemoveHelp,
+} from "@/cli/routes/channels.remove.$channel"
+import {
+  channelsRenameHandler,
+  renameHelp as channelsRenameHelp,
+} from "@/cli/routes/channels.$channel.rename.$newName"
+import { channelsSetDeliveryHandler } from "@/cli/routes/channels.$channel.set.delivery.$mode"
+import { channelsShowHandler } from "@/cli/routes/channels.$channel"
+import { channelsGroupHandler } from "@/cli/routes/channels"
+import { claudeHandler } from "@/cli/routes/claude"
+import { gatewayGroupHandler } from "@/cli/routes/gateway"
+import { gatewayListenersHandler } from "@/cli/routes/gateway.listeners"
+import { gatewayLogsHandler } from "@/cli/routes/gateway.logs"
+import { gatewayRestartHandler } from "@/cli/routes/gateway.restart"
+import { gatewayRunHandler } from "@/cli/routes/gateway.run"
+import { gatewayStartHandler } from "@/cli/routes/gateway.start"
+import { gatewayStatusHandler } from "@/cli/routes/gateway.status"
+import { gatewayStopHandler } from "@/cli/routes/gateway.stop"
+import {
+  addHelp as profilesAddHelp,
+  profilesAddHandler,
+} from "@/cli/routes/profiles.add.$profile"
+import { profilesAsDefaultHandler } from "@/cli/routes/profiles.$profile.as-default"
+import {
+  profilesRenameHandler,
+  renameHelp as profilesRenameHelp,
+} from "@/cli/routes/profiles.$profile.rename.$newName"
+import { profilesLaunchHandler } from "@/cli/routes/profiles.$profile.run"
+import {
+  profilesRemoveHandler,
+  removeHelp as profilesRemoveHelp,
+} from "@/cli/routes/profiles.remove.$profile"
+import {
+  profilesSetHandler,
+  setHelp as profilesSetHelp,
+} from "@/cli/routes/profiles.set.$profile"
+import { profilesGroupHandler } from "@/cli/routes/profiles"
+import { statusHandler } from "@/cli/routes/status"
+import { updateHandler } from "@/cli/routes/update"
+import { Funnel } from "@/funnel"
+
+const base = factory.createApp()
+
+base.use((c, next) => {
+  c.set("funnel", new Funnel())
+
+  return next()
+})
+
+base.onError((error, c) => {
+  if (error instanceof HTTPException) {
+    return c.text(`error: ${error.message}`, error.status)
+  }
+
+  return c.text(`error: ${error instanceof Error ? error.message : String(error)}`, 400)
+})
+
+const helpRoute = (text: string) => factory.createHandlers((c) => c.text(text))
+
+// All CLI verbs (`add` / `remove` / `set` / `rename` / `as-default` / `request`) map to POST in
+// to-request.ts and stay in the URL as a literal segment. Read paths (list / show / launch) keep GET.
+// Help shortcuts at parameterless URLs return the help text directly so `funnel <verb>` (no args) is
+// informative instead of 404.
+export const app = base
+  .get("/claude", ...claudeHandler)
+  .get("/channels", ...channelsGroupHandler)
+  .post("/channels/add", ...helpRoute(channelsAddHelp))
+  .post("/channels/add/:channel", ...channelsAddHandler)
+  .post("/channels/remove", ...helpRoute(channelsRemoveHelp))
+  .post("/channels/remove/:channel", ...channelsRemoveHandler)
+  .post("/channels/rename/:channel/:newName", ...channelsRenameHandler)
+  .post("/channels/:channel/rename/:newName", ...channelsRenameHandler)
+  .post("/channels/rename", ...helpRoute(channelsRenameHelp))
+  .post("/channels/:channel/rename", ...helpRoute(channelsRenameHelp))
+  .post("/channels/:channel/set/delivery/:mode", ...channelsSetDeliveryHandler)
+  .get("/channels/:channel", ...channelsShowHandler)
+  .get("/channels/:channel/connectors", ...channelsConnectorsGroupHandler)
+  .post(
+    "/channels/:channel/connectors/add",
+    ...helpRoute(channelsConnectorsAddHelp),
+  )
+  .post(
+    "/channels/:channel/connectors/add/:connector",
+    ...channelsConnectorsAddHandler,
+  )
+  .post(
+    "/channels/:channel/connectors/remove",
+    ...helpRoute(channelsConnectorsRemoveHelp),
+  )
+  .post(
+    "/channels/:channel/connectors/remove/:connector",
+    ...channelsConnectorsRemoveHandler,
+  )
+  .post(
+    "/channels/:channel/connectors/set",
+    ...helpRoute(channelsConnectorsSetHelp),
+  )
+  .post(
+    "/channels/:channel/connectors/set/:connector",
+    ...channelsConnectorsSetHandler,
+  )
+  .post(
+    "/channels/:channel/connectors/rename/:connector/:newName",
+    ...channelsConnectorsRenameHandler,
+  )
+  .post(
+    "/channels/:channel/connectors/:connector/rename/:newName",
+    ...channelsConnectorsRenameHandler,
+  )
+  .post(
+    "/channels/:channel/connectors/rename",
+    ...helpRoute(channelsConnectorsRenameHelp),
+  )
+  .post(
+    "/channels/:channel/connectors/:connector/rename",
+    ...helpRoute(channelsConnectorsRenameHelp),
+  )
+  .post(
+    "/channels/:channel/connectors/:connector/request",
+    ...channelsConnectorsRequestHandler,
+  )
+  .get("/channels/:channel/connectors/:connector", ...channelsConnectorsShowHandler)
+  .get(
+    "/channels/:channel/connectors/:connector/schedules",
+    ...channelsConnectorsSchedulesGroupHandler,
+  )
+  .post(
+    "/channels/:channel/connectors/:connector/schedules/add",
+    ...helpRoute(channelsConnectorsSchedulesAddHelp),
+  )
+  .post(
+    "/channels/:channel/connectors/:connector/schedules/add/:id",
+    ...channelsConnectorsSchedulesAddHandler,
+  )
+  .post(
+    "/channels/:channel/connectors/:connector/schedules/remove",
+    ...helpRoute(channelsConnectorsSchedulesRemoveHelp),
+  )
+  .post(
+    "/channels/:channel/connectors/:connector/schedules/remove/:id",
+    ...channelsConnectorsSchedulesRemoveHandler,
+  )
+  .get("/profiles", ...profilesGroupHandler)
+  .post("/profiles/add", ...helpRoute(profilesAddHelp))
+  .post("/profiles/add/:profile", ...profilesAddHandler)
+  .post("/profiles/set", ...helpRoute(profilesSetHelp))
+  .post("/profiles/set/:profile", ...profilesSetHandler)
+  .post("/profiles/remove", ...helpRoute(profilesRemoveHelp))
+  .post("/profiles/remove/:profile", ...profilesRemoveHandler)
+  .post("/profiles/rename/:profile/:newName", ...profilesRenameHandler)
+  .post("/profiles/:profile/rename/:newName", ...profilesRenameHandler)
+  .post("/profiles/rename", ...helpRoute(profilesRenameHelp))
+  .post("/profiles/:profile/rename", ...helpRoute(profilesRenameHelp))
+  .post("/profiles/:profile/as-default", ...profilesAsDefaultHandler)
+  .get("/profiles/:profile/run", ...profilesLaunchHandler)
+  .get("/profiles/:profile", ...profilesLaunchHandler)
+  .get("/gateway", ...gatewayGroupHandler)
+  .get("/gateway/status", ...gatewayStatusHandler)
+  .get("/gateway/start", ...gatewayStartHandler)
+  .get("/gateway/stop", ...gatewayStopHandler)
+  .get("/gateway/restart", ...gatewayRestartHandler)
+  .get("/gateway/run", ...gatewayRunHandler)
+  .get("/gateway/logs", ...gatewayLogsHandler)
+  .get("/gateway/listeners", ...gatewayListenersHandler)
+  .get("/status", ...statusHandler)
+  .get("/update", ...updateHandler)

package/lib/cli/routes/profiles.$profile.as-default.ts

@@ -0,0 +1,22 @@
+import { z } from "zod"
+import { factory } from "@/cli/factory"
+import { zValidator } from "@/cli/router/validator"
+
+export const asDefaultHelp = `funnel profiles <name> as-default — move profile to the front of the list
+
+usage: funnel profiles <name> as-default
+
+the first profile in the list is treated as the default for fnl claude.`
+
+export const profilesAsDefaultHandler = factory.createHandlers(
+  zValidator("param", z.object({ profile: z.string() })),
+  zValidator("query", z.object({}), asDefaultHelp),
+  (c) => {
+    const param = c.req.valid("param")
+    const funnel = c.var.funnel
+
+    funnel.profiles.asDefault(param.profile)
+
+    return c.text(`profile "${param.profile}" is now the default`)
+  },
+)

package/lib/cli/routes/profiles.$profile.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 profiles rename — rename a profile
+
+usage:
+  funnel profiles rename <old> <new>
+  funnel profiles <old> rename <new>`
+
+export const profilesRenameHandler = factory.createHandlers(
+  zValidator("param", z.object({ profile: z.string(), newName: z.string() })),
+  zValidator("query", z.object({}), renameHelp),
+  (c) => {
+    const param = c.req.valid("param")
+    const funnel = c.var.funnel
+
+    funnel.profiles.rename(param.profile, param.newName)
+
+    return c.text(`renamed profile "${param.profile}" to "${param.newName}"`)
+  },
+)

package/lib/cli/routes/profiles.$profile.run.ts

@@ -0,0 +1,36 @@
+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 launchHelp = `funnel profiles <name> run — launch a profile (sugar for fnl claude)
+
+usage: funnel profiles <name> run [additional claude args...]
+       funnel profiles <name>     (alias)`
+
+const RESERVED_KEYS: string[] = []
+
+export const profilesLaunchHandler = factory.createHandlers(
+  zValidator("param", z.object({ profile: z.string() })),
+  zValidator("query", z.object({}).passthrough(), launchHelp),
+  async (c) => {
+    const param = c.req.valid("param")
+    const funnel = c.var.funnel
+    const profile = funnel.profiles.get(param.profile)
+
+    if (!profile) {
+      throw new HTTPException(404, { message: `profile "${param.profile}" not found` })
+    }
+
+    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)
+  },
+)