@interactive-inc/claude-funnel 0.2.0

package/lib/routes/channels/show.help.ts

@@ -0,0 +1 @@
+export const help = `funnel channels <name> — show channel details`

package/lib/routes/channels/show.ts

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

package/lib/routes/claude/claude.help.ts

@@ -0,0 +1,11 @@
+export const help = `funnel claude — launch Claude Code
+
+usage: funnel claude --channel <name> [--repo <name>] [--sub-agent <name>] [--env-file <file>] [additional claude args...]
+
+options:
+  --channel        channel name to subscribe to (required)
+  --repo           switch working directory to the named repo (extra)
+  --sub-agent      sub-agent name (passed to claude --agent)
+  --env-file       additional env file to load (relative path)
+
+On launch the FUNNEL_CHANNEL_ID env var is set and MCP connects to the gateway.`

package/lib/routes/claude/claude.ts

@@ -0,0 +1,39 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { queryToCliArgs } from "@/modules/router/query-to-cli-args"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/claude/claude.help"
+
+const RESERVED_KEYS = ["channel", "repo", "sub-agent", "env-file"]
+
+export const claudeHandler = factory.createHandlers(
+  zValidator(
+    "query",
+    z
+      .object({
+        channel: z.string().optional(),
+        repo: z.string().optional(),
+        "sub-agent": z.string().optional(),
+        "env-file": z.string().optional(),
+      })
+      .passthrough(),
+    help,
+  ),
+  async (c) => {
+    const query = c.req.valid("query")
+
+    if (!query.channel) return c.text(help)
+
+    const funnel = c.var.funnel
+
+    const exitCode = await funnel.claude.launch({
+      channel: query.channel,
+      repo: query.repo,
+      subAgent: query["sub-agent"],
+      envFiles: query["env-file"] ? [query["env-file"]] : undefined,
+      userArgs: queryToCliArgs(c.req.url, RESERVED_KEYS),
+    })
+
+    process.exit(exitCode)
+  },
+)

package/lib/routes/claude/routes.ts

@@ -0,0 +1,4 @@
+import { factory } from "@/factory"
+import { claudeHandler } from "@/routes/claude/claude"
+
+export const claudeRoutes = factory.createApp().get("/", ...claudeHandler)

package/lib/routes/connectors/add.help.ts

@@ -0,0 +1,22 @@
+export const help = `funnel connectors add — add a connector
+
+usage:
+  funnel connectors add <name> --type slack   --bot-token xoxb-... --app-token xapp-...
+  funnel connectors add <name> --type gh      [--poll-interval <seconds>]
+  funnel connectors add <name> --type discord --bot-token <discord-bot-token>
+
+slack (Socket Mode):
+  --bot-token             Slack Bot Token (starts with xoxb-)
+  --app-token             Slack App Token (starts with xapp-)
+
+gh (GitHub, gh CLI):
+  --poll-interval         polling interval for /notifications (seconds, default 60)
+  note: uses the gh CLI (must be authenticated via gh auth login); no token required
+
+discord (Discord Gateway):
+  --bot-token             Discord Bot Token
+
+examples:
+  funnel connectors add prod-slack --type slack --bot-token xoxb-... --app-token xapp-...
+  funnel connectors add my-gh --type gh --poll-interval 30
+  funnel connectors add my-discord --type discord --bot-token MTI...`

package/lib/routes/connectors/add.ts

@@ -0,0 +1,55 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/connectors/add.help"
+
+export const connectorsAddHandler = factory.createHandlers(
+  zValidator("param", z.object({ name: z.string() })),
+  zValidator(
+    "query",
+    z.discriminatedUnion("type", [
+      z.object({
+        type: z.literal("slack"),
+        "bot-token": z.string().startsWith("xoxb-"),
+        "app-token": z.string().startsWith("xapp-"),
+      }),
+      z.object({
+        type: z.literal("gh"),
+        "poll-interval": z.string().optional(),
+      }),
+      z.object({
+        type: z.literal("discord"),
+        "bot-token": z.string().min(10),
+      }),
+    ]),
+    help,
+  ),
+  (c) => {
+    const param = c.req.valid("param")
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+
+    if (query.type === "slack") {
+      funnel.connectors.add({
+        type: "slack",
+        name: param.name,
+        botToken: query["bot-token"],
+        appToken: query["app-token"],
+      })
+    } else if (query.type === "gh") {
+      funnel.connectors.add({
+        type: "gh",
+        name: param.name,
+        pollInterval: query["poll-interval"] ? Number(query["poll-interval"]) : undefined,
+      })
+    } else {
+      funnel.connectors.add({
+        type: "discord",
+        name: param.name,
+        botToken: query["bot-token"],
+      })
+    }
+
+    return c.text(`added connector "${param.name}"`)
+  },
+)

package/lib/routes/connectors/call.help.ts

@@ -0,0 +1,17 @@
+export const help = `funnel connectors <name> <method> <path> [body] — call a connector API
+
+usage:
+  funnel connectors <name> <method> <path> [<json-body>]
+
+<method>:
+  get / post / put / patch / delete / head / options
+
+Slack examples (every API is posted via POST internally):
+  funnel connectors my-slack post chat.postMessage '{"channel":"D...","text":"hi"}'
+  funnel connectors my-slack post chat.update      '{"channel":"D...","ts":"...","text":"edit"}'
+  funnel connectors my-slack post chat.delete      '{"channel":"D...","ts":"..."}'
+  funnel connectors my-slack post users.info       '{"user":"U..."}'
+
+Discord examples (per HTTP method):
+  funnel connectors my-discord post   channels/C/messages   '{"content":"hi"}'
+  funnel connectors my-discord delete channels/C/messages/M`

package/lib/routes/connectors/call.ts

@@ -0,0 +1,43 @@
+import { HTTPException } from "hono/http-exception"
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/connectors/call.help"
+
+const parseBody = (raw: string | undefined): unknown => {
+  if (!raw) return {}
+
+  try {
+    return JSON.parse(raw)
+  } catch (error) {
+    throw new HTTPException(400, {
+      message: `body is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    })
+  }
+}
+
+export const connectorsCallHandler = factory.createHandlers(
+  zValidator("param", z.object({ name: z.string() })),
+  zValidator(
+    "query",
+    z.object({
+      method: z.string(),
+      path: z.string(),
+      body: z.string().optional(),
+    }),
+    help,
+  ),
+  async (c) => {
+    const param = c.req.valid("param")
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+
+    const result = await funnel.connectors.call(param.name, {
+      method: query.method,
+      path: query.path,
+      body: parseBody(query.body),
+    })
+
+    return c.text(JSON.stringify(result, null, 2))
+  },
+)

package/lib/routes/connectors/group.help.ts

@@ -0,0 +1,14 @@
+export const help = `funnel connectors — manage external connections (Slack, etc.)
+
+usage: funnel connectors [subcommand]
+
+subcommands:
+  (none)                       list
+  add <name> --type slack --bot-token <t> --app-token <t>
+  remove <name>
+  <name>                       show details
+
+examples:
+  funnel connectors add prod-slack --type slack --bot-token xoxb-... --app-token xapp-...
+  funnel connectors
+  funnel connectors remove prod-slack`

package/lib/routes/connectors/group.ts

@@ -0,0 +1,18 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/connectors/group.help"
+
+export const connectorsGroupHandler = factory.createHandlers(
+  zValidator("query", z.object({}), help),
+  (c) => {
+    const funnel = c.var.funnel
+    const connectors = funnel.connectors.list()
+
+    if (connectors.length === 0) return c.text("no connectors")
+
+    const lines = connectors.map((con) => `${con.name} (${con.type})`)
+
+    return c.text(lines.join("\n"))
+  },
+)

package/lib/routes/connectors/remove.help.ts

@@ -0,0 +1,3 @@
+export const help = `funnel connectors remove — remove a connector
+
+usage: funnel connectors remove <name>`

package/lib/routes/connectors/remove.ts

@@ -0,0 +1,17 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/connectors/remove.help"
+
+export const connectorsRemoveHandler = factory.createHandlers(
+  zValidator("param", z.object({ name: z.string() })),
+  zValidator("query", z.object({}), help),
+  (c) => {
+    const param = c.req.valid("param")
+    const funnel = c.var.funnel
+
+    funnel.connectors.remove(param.name)
+
+    return c.text(`removed connector "${param.name}"`)
+  },
+)

package/lib/routes/connectors/rename.help.ts

@@ -0,0 +1,5 @@
+export const help = `funnel connectors rename — rename a connector
+
+usage:
+  funnel connectors rename <old> <new>
+  funnel connectors <old> rename <new>`

package/lib/routes/connectors/rename.ts

@@ -0,0 +1,17 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/connectors/rename.help"
+
+export const connectorsRenameHandler = factory.createHandlers(
+  zValidator("param", z.object({ name: z.string(), newName: z.string() })),
+  zValidator("query", z.object({}), help),
+  (c) => {
+    const param = c.req.valid("param")
+    const funnel = c.var.funnel
+
+    funnel.connectors.rename(param.name, param["newName"])
+
+    return c.text(`renamed connector "${param.name}" to "${param["newName"]}"`)
+  },
+)

package/lib/routes/connectors/routes.ts

@@ -0,0 +1,19 @@
+import { factory } from "@/factory"
+import { connectorsAddHandler } from "@/routes/connectors/add"
+import { connectorsCallHandler } from "@/routes/connectors/call"
+import { connectorsGroupHandler } from "@/routes/connectors/group"
+import { connectorsRemoveHandler } from "@/routes/connectors/remove"
+import { connectorsRenameHandler } from "@/routes/connectors/rename"
+import { connectorsSetHandler } from "@/routes/connectors/set"
+import { connectorsShowHandler } from "@/routes/connectors/show"
+
+export const connectorsRoutes = factory
+  .createApp()
+  .get("/", ...connectorsGroupHandler)
+  .get("/:name/call", ...connectorsCallHandler)
+  .put("/:name/rename/:newName", ...connectorsRenameHandler)
+  .put("/rename/:name/:newName", ...connectorsRenameHandler)
+  .post("/:name", ...connectorsAddHandler)
+  .put("/:name", ...connectorsSetHandler)
+  .delete("/:name", ...connectorsRemoveHandler)
+  .get("/:name", ...connectorsShowHandler)

package/lib/routes/connectors/set.help.ts

@@ -0,0 +1,8 @@
+export const help = `funnel connectors <name> set — update a connector
+
+usage: funnel connectors <name> set [--bot-token ...] [--app-token ...] [--poll-interval ...]
+
+fields available per type:
+  slack   : --bot-token / --app-token
+  gh      : --poll-interval
+  discord : --bot-token`

package/lib/routes/connectors/set.ts

@@ -0,0 +1,30 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/connectors/set.help"
+
+export const connectorsSetHandler = factory.createHandlers(
+  zValidator("param", z.object({ name: z.string() })),
+  zValidator(
+    "query",
+    z.object({
+      "bot-token": z.string().optional(),
+      "app-token": z.string().optional(),
+      "poll-interval": z.string().optional(),
+    }),
+    help,
+  ),
+  (c) => {
+    const param = c.req.valid("param")
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+
+    funnel.connectors.update(param.name, {
+      botToken: query["bot-token"],
+      appToken: query["app-token"],
+      pollInterval: query["poll-interval"] ? Number(query["poll-interval"]) : undefined,
+    })
+
+    return c.text(`updated connector "${param.name}"`)
+  },
+)

package/lib/routes/connectors/show.help.ts

@@ -0,0 +1 @@
+export const help = `funnel connectors <name> — show connector details`

package/lib/routes/connectors/show.ts

@@ -0,0 +1,32 @@
+import { HTTPException } from "hono/http-exception"
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/connectors/show.help"
+
+export const connectorsShowHandler = factory.createHandlers(
+  zValidator("param", z.object({ name: z.string() })),
+  zValidator("query", z.object({}), help),
+  (c) => {
+    const param = c.req.valid("param")
+    const funnel = c.var.funnel
+    const connector = funnel.connectors.get(param.name)
+
+    if (!connector) {
+      throw new HTTPException(404, { message: `connector "${param.name}" not found` })
+    }
+
+    const lines: string[] = [`name: ${connector.name}`, `type: ${connector.type}`]
+
+    if (connector.type === "slack") {
+      lines.push(`botToken: ${connector.botToken.slice(0, 8)}...`)
+      lines.push(`appToken: ${connector.appToken.slice(0, 8)}...`)
+    } else if (connector.type === "gh") {
+      lines.push(`pollInterval: ${connector.pollInterval ?? 60}s`)
+    } else if (connector.type === "discord") {
+      lines.push(`botToken: ${connector.botToken.slice(0, 8)}...`)
+    }
+
+    return c.text(lines.join("\n"))
+  },
+)

package/lib/routes/gateway/group.help.ts

@@ -0,0 +1,15 @@
+export const help = `funnel gateway — manage the gateway
+
+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
+
+examples:
+  funnel gateway                check status
+  funnel gateway restart        restart`

package/lib/routes/gateway/group.ts

@@ -0,0 +1,28 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/gateway/group.help"
+
+export const gatewayGroupHandler = factory.createHandlers(
+  zValidator("query", z.object({}), help),
+  async (c) => {
+    const funnel = c.var.funnel
+    const status = funnel.gateway.getStatus()
+
+    if (!status.running) {
+      return c.text("funnel gateway: not running", 503)
+    }
+
+    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 = (await res.json()) as Record<string, unknown>
+
+    return c.text(
+      `funnel gateway: running (pid ${status.pid})\n  port: ${status.port}\n  clients: ${health.clients ?? 0}`,
+    )
+  },
+)

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

@@ -0,0 +1,13 @@
+export const help = `funnel gateway logs — tail event logs
+
+usage: funnel gateway logs [-n <N>]
+
+options:
+  -n <N>                number of trailing lines to show (default: 20)
+
+Tails the latest /tmp/funnel/events/*.jsonl file. Exit with SIGINT.
+Output is formatted as YAML.
+
+examples:
+  funnel gateway logs
+  funnel gateway logs -n 100`

package/lib/routes/gateway/logs.ts

@@ -0,0 +1,100 @@
+import { readdirSync } from "node:fs"
+import { join } from "node:path"
+import { stringify } from "yaml"
+import { z } from "zod"
+import { factory } from "@/factory"
+import { logger } from "@/modules/logger"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/gateway/logs.help"
+
+const tryParseJson = (s: string): unknown => {
+  try {
+    return JSON.parse(s)
+  } catch {
+    return null
+  }
+}
+
+export const gatewayLogsHandler = factory.createHandlers(
+  zValidator(
+    "query",
+    z.object({
+      n: z.string().optional(),
+    }),
+    help,
+  ),
+  async (c) => {
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+    const logDir = funnel.gateway.getLogDir()
+
+    const files = readdirSync(logDir)
+      .filter((name) => name.endsWith(".jsonl"))
+      .sort()
+
+    if (files.length === 0) {
+      return c.text("no logs")
+    }
+
+    const latestFile = join(logDir, files[files.length - 1]!)
+    const lineCount = query.n ? Number(query.n) : 20
+
+    const tail = Bun.spawn(["tail", "-f", "-n", String(lineCount), latestFile], {
+      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: latestFile })
+
+    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 entry = tryParseJson(line) as {
+          timestamp: string
+          eventType: string
+          meta?: unknown
+          content: string
+        } | null
+
+        if (!entry) {
+          process.stdout.write(`${line}\n`)
+          continue
+        }
+
+        const parsedContent = tryParseJson(entry.content) ?? entry.content
+        const output = {
+          time: entry.timestamp,
+          type: entry.eventType,
+          ...(entry.meta ? { meta: entry.meta } : {}),
+          content: parsedContent,
+        }
+
+        process.stdout.write(`---\n${stringify(output)}`)
+      }
+    }
+
+    await tail.exited
+    process.exit(0)
+  },
+)

package/lib/routes/gateway/restart.help.ts

@@ -0,0 +1,10 @@
+export const help = `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`

package/lib/routes/gateway/restart.ts

@@ -0,0 +1,35 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/gateway/restart.help"
+
+export const gatewayRestartHandler = factory.createHandlers(
+  zValidator(
+    "query",
+    z.object({
+      "no-caffeine": z.string().optional(),
+    }),
+    help,
+  ),
+  async (c) => {
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+
+    const result = await funnel.gateway.restart({
+      caffeinate: query["no-caffeine"] !== "true",
+    })
+    const lines: string[] = []
+
+    if (result.wasRunning) {
+      lines.push(result.stopped ? "funnel gateway: stopped" : "funnel gateway: failed to stop")
+    }
+
+    if (result.stopped) {
+      lines.push(result.started ? "funnel gateway: started" : "funnel gateway: failed to start")
+    }
+
+    const body = lines.join("\n")
+
+    return result.ok ? c.text(body) : c.text(body, 500)
+  },
+)

package/lib/routes/gateway/routes.ts

@@ -0,0 +1,18 @@
+import { factory } from "@/factory"
+import { gatewayGroupHandler } from "@/routes/gateway/group"
+import { gatewayLogsHandler } from "@/routes/gateway/logs"
+import { gatewayRestartHandler } from "@/routes/gateway/restart"
+import { gatewayRunHandler } from "@/routes/gateway/run"
+import { gatewayStartHandler } from "@/routes/gateway/start"
+import { gatewayStatusHandler } from "@/routes/gateway/status"
+import { gatewayStopHandler } from "@/routes/gateway/stop"
+
+export const gatewayRoutes = factory
+  .createApp()
+  .get("/", ...gatewayGroupHandler)
+  .get("/status", ...gatewayStatusHandler)
+  .get("/start", ...gatewayStartHandler)
+  .get("/stop", ...gatewayStopHandler)
+  .get("/restart", ...gatewayRestartHandler)
+  .get("/run", ...gatewayRunHandler)
+  .get("/logs", ...gatewayLogsHandler)

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

@@ -0,0 +1,12 @@
+export const help = `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`