@interactive-inc/claude-funnel 0.2.0

package/lib/modules/router/validator.ts

@@ -0,0 +1,27 @@
+import { zValidator as zv } from "@hono/zod-validator"
+import { HTTPException } from "hono/http-exception"
+import type { ZodType } from "zod"
+
+export const zValidator = <Target extends "param" | "query" | "json", T extends ZodType>(
+  target: Target,
+  schema: T,
+  helpText?: string,
+) =>
+  zv(target, schema, (result, c) => {
+    if (helpText && c.req.query("help")) {
+      return c.text(helpText)
+    }
+
+    if (result.success) return
+
+    const issue = result.error.issues[0]
+
+    if (!issue) {
+      throw new HTTPException(400, { message: "invalid request" })
+    }
+
+    const path = issue.path.join(".")
+    const message = path ? `${path}: ${issue.message}` : issue.message
+
+    throw new HTTPException(400, { message })
+  })

package/lib/modules/settings/funnel-settings-reader.ts

@@ -0,0 +1,6 @@
+import type { Settings } from "@/modules/settings/settings-schema"
+
+export abstract class FunnelSettingsReader {
+  abstract read(): Settings
+  abstract write(settings: Settings): void
+}

package/lib/modules/settings/funnel-settings-store.ts

@@ -0,0 +1,57 @@
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { FunnelFileSystem } from "@/modules/fs/funnel-file-system"
+import { NodeFunnelFileSystem } from "@/modules/fs/node-funnel-file-system"
+import { FunnelSettingsReader } from "@/modules/settings/funnel-settings-reader"
+import { settingsSchema } from "@/modules/settings/settings-schema"
+import type { Settings } from "@/modules/settings/settings-schema"
+
+export const FUNNEL_DIR = join(homedir(), ".funnel")
+export const SETTINGS_PATH = join(FUNNEL_DIR, "settings.json")
+
+type Deps = {
+  path?: string
+  fs?: FunnelFileSystem
+}
+
+const defaultFs = new NodeFunnelFileSystem()
+
+export class FunnelSettingsStore extends FunnelSettingsReader {
+  private readonly path: string
+  private readonly fs: FunnelFileSystem
+
+  constructor(deps: Deps = {}) {
+    super()
+    this.path = deps.path ?? SETTINGS_PATH
+    this.fs = deps.fs ?? defaultFs
+    Object.freeze(this)
+  }
+
+  read(): Settings {
+    if (!this.fs.existsSync(this.path)) {
+      return {
+        connectors: [],
+        channels: [],
+        repositories: [],
+        agents: [],
+      }
+    }
+
+    const content = this.fs.readFileSync(this.path)
+    const parsed = JSON.parse(content)
+    const result = settingsSchema.safeParse(parsed)
+
+    if (!result.success) {
+      throw new Error(
+        `invalid settings.json (${this.path}): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ")}`,
+      )
+    }
+
+    return result.data
+  }
+
+  write(settings: Settings): void {
+    this.fs.mkdirSync(dirname(this.path), { recursive: true })
+    this.fs.writeFileSync(this.path, `${JSON.stringify(settings, null, 2)}\n`)
+  }
+}

package/lib/modules/settings/mock-funnel-settings-reader.ts

@@ -0,0 +1,27 @@
+import { FunnelSettingsReader } from "@/modules/settings/funnel-settings-reader"
+import type { Settings } from "@/modules/settings/settings-schema"
+
+export const createSettings = (partial: Partial<Settings> = {}): Settings => ({
+  connectors: [],
+  channels: [],
+  repositories: [],
+  agents: [],
+  ...partial,
+})
+
+export class MockFunnelSettingsReader extends FunnelSettingsReader {
+  private state: Settings
+
+  constructor(initial?: Partial<Settings>) {
+    super()
+    this.state = createSettings(initial)
+  }
+
+  read(): Settings {
+    return this.state
+  }
+
+  write(settings: Settings): void {
+    this.state = settings
+  }
+}

package/lib/modules/settings/settings-schema.ts

@@ -0,0 +1,67 @@
+import { z } from "zod"
+
+export const slackConnectorSchema = z.object({
+  type: z.literal("slack"),
+  name: z.string(),
+  botToken: z.string().startsWith("xoxb-"),
+  appToken: z.string().startsWith("xapp-"),
+})
+
+export type SlackConnectorConfig = z.infer<typeof slackConnectorSchema>
+
+export const ghConnectorSchema = z.object({
+  type: z.literal("gh"),
+  name: z.string(),
+  pollInterval: z.number().int().positive().optional(),
+})
+
+export type GhConnectorConfig = z.infer<typeof ghConnectorSchema>
+
+export const discordConnectorSchema = z.object({
+  type: z.literal("discord"),
+  name: z.string(),
+  botToken: z.string().min(10),
+})
+
+export type DiscordConnectorConfig = z.infer<typeof discordConnectorSchema>
+
+export const connectorConfigSchema = z.discriminatedUnion("type", [
+  slackConnectorSchema,
+  ghConnectorSchema,
+  discordConnectorSchema,
+])
+
+export type ConnectorConfig = z.infer<typeof connectorConfigSchema>
+
+export const channelConfigSchema = z.object({
+  name: z.string(),
+  connectors: z.array(z.string()).default([]),
+})
+
+export type ChannelConfig = z.infer<typeof channelConfigSchema>
+
+export const repositoryConfigSchema = z.object({
+  name: z.string(),
+  path: z.string(),
+})
+
+export type RepositoryConfig = z.infer<typeof repositoryConfigSchema>
+
+export const agentConfigSchema = z.object({
+  name: z.string(),
+  channel: z.string(),
+  repo: z.string().optional(),
+  subAgent: z.string().optional(),
+  envFiles: z.array(z.string()).optional(),
+})
+
+export type AgentConfig = z.infer<typeof agentConfigSchema>
+
+export const settingsSchema = z.object({
+  connectors: z.array(connectorConfigSchema).default([]),
+  channels: z.array(channelConfigSchema).default([]),
+  repositories: z.array(repositoryConfigSchema).default([]),
+  agents: z.array(agentConfigSchema).default([]),
+})
+
+export type Settings = z.infer<typeof settingsSchema>

package/lib/modules/tui/app.tsx

@@ -0,0 +1,44 @@
+import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react"
+
+const zinc = {
+  50: "#fafafa",
+  600: "#52525b",
+  950: "#09090b",
+} as const
+
+const LABEL = "funnel"
+
+export function App() {
+  const renderer = useRenderer()
+
+  const dimensions = useTerminalDimensions()
+
+  useKeyboard((key) => {
+    if (key.name === "q" || key.name === "escape" || (key.ctrl && key.name === "c")) {
+      renderer.destroy()
+    }
+  })
+
+  const marginLeft = Math.max(0, Math.floor((dimensions.width - LABEL.length) / 2))
+
+  const marginTop = Math.max(0, Math.floor(dimensions.height / 2) - 1)
+
+  return (
+    <box
+      style={{
+        width: "100%",
+        height: "100%",
+        flexDirection: "column",
+        backgroundColor: zinc[950],
+      }}
+    >
+      <box style={{ height: marginTop, backgroundColor: zinc[950] }} />
+      <text fg={zinc[50]} bg={zinc[950]} style={{ marginLeft }}>
+        {LABEL}
+      </text>
+      <text fg={zinc[600]} bg={zinc[950]} position="absolute" bottom={0}>
+        press q to quit
+      </text>
+    </box>
+  )
+}

package/lib/modules/tui/tui.tsx

@@ -0,0 +1,13 @@
+import { createCliRenderer } from "@opentui/core"
+import { createRoot } from "@opentui/react"
+import { App } from "@/modules/tui/app"
+
+export async function launchTui(): Promise<void> {
+  const renderer = await createCliRenderer()
+
+  createRoot(renderer).render(<App />)
+
+  await new Promise<void>((resolve) => {
+    renderer.once("destroy", () => resolve())
+  })
+}

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

@@ -0,0 +1,3 @@
+export const help = `funnel agents add — add an agent preset
+
+usage: funnel agents add <name> --channel <ch> [--repo <r>] [--sub-agent <s>] [--env-file <f>]`

package/lib/routes/agents/add.ts

@@ -0,0 +1,33 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/agents/add.help"
+
+export const agentsAddHandler = factory.createHandlers(
+  zValidator("param", z.object({ name: z.string() })),
+  zValidator(
+    "query",
+    z.object({
+      channel: z.string(),
+      repo: z.string().optional(),
+      "sub-agent": z.string().optional(),
+      "env-file": z.string().optional(),
+    }),
+    help,
+  ),
+  (c) => {
+    const param = c.req.valid("param")
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+
+    funnel.agents.add({
+      name: param.name,
+      channel: query.channel,
+      repo: query.repo,
+      subAgent: query["sub-agent"],
+      envFiles: query["env-file"] ? [query["env-file"]] : undefined,
+    })
+
+    return c.text(`added agent "${param.name}"`)
+  },
+)

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

@@ -0,0 +1,13 @@
+export const help = `funnel agents — agent presets (extra)
+
+usage: funnel agents [subcommand]
+
+subcommands:
+  (none)                          list
+  add <name> --channel <ch> [--repo <r>] [--sub-agent <s>] [--env-file <f>]
+  remove <name>                   remove
+  <name>                          launch (sugar for fnl claude)
+
+examples:
+  funnel agents add cto --channel prod-inbox --repo myapp --sub-agent cto
+  funnel agents cto`

package/lib/routes/agents/group.ts

@@ -0,0 +1,25 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/agents/group.help"
+
+export const agentsGroupHandler = factory.createHandlers(
+  zValidator("query", z.object({}), help),
+  (c) => {
+    const funnel = c.var.funnel
+    const agents = funnel.agents.list()
+
+    if (agents.length === 0) return c.text("no agents")
+
+    const lines = agents.map((agent) => {
+      const parts = [`channel=${agent.channel}`]
+
+      if (agent.repo) parts.push(`repo=${agent.repo}`)
+      if (agent.subAgent) parts.push(`subAgent=${agent.subAgent}`)
+
+      return `${agent.name}  [${parts.join(", ")}]`
+    })
+
+    return c.text(lines.join("\n"))
+  },
+)

package/lib/routes/agents/launch.help.ts

@@ -0,0 +1,3 @@
+export const help = `funnel agents <name> — launch an agent (sugar for fnl claude)
+
+usage: funnel agents <name> [additional claude args...]`

package/lib/routes/agents/launch.ts

@@ -0,0 +1,35 @@
+import { HTTPException } from "hono/http-exception"
+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/agents/launch.help"
+
+const RESERVED_KEYS = ["channel", "repo", "sub-agent", "env-file"]
+
+export const agentsLaunchHandler = factory.createHandlers(
+  zValidator("param", z.object({ name: z.string() })),
+  zValidator("query", z.object({}).passthrough(), help),
+  async (c) => {
+    const param = c.req.valid("param")
+    const funnel = c.var.funnel
+    const agent = funnel.agents.get(param.name)
+
+    if (!agent) throw new HTTPException(404, { message: `agent "${param.name}" not found` })
+
+    const overrideChannel = c.req.query("channel")
+    const overrideRepo = c.req.query("repo")
+    const overrideSubAgent = c.req.query("sub-agent")
+    const overrideEnvFile = c.req.query("env-file")
+
+    const exitCode = await funnel.claude.launch({
+      channel: overrideChannel ?? agent.channel,
+      repo: overrideRepo ?? agent.repo,
+      subAgent: overrideSubAgent ?? agent.subAgent,
+      envFiles: overrideEnvFile ? [overrideEnvFile] : agent.envFiles,
+      userArgs: queryToCliArgs(c.req.url, RESERVED_KEYS),
+    })
+
+    process.exit(exitCode)
+  },
+)

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

@@ -0,0 +1,3 @@
+export const help = `funnel agents remove — remove an agent preset
+
+usage: funnel agents remove <name>`

package/lib/routes/agents/remove.ts

@@ -0,0 +1,17 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/agents/remove.help"
+
+export const agentsRemoveHandler = 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.agents.remove(param.name)
+
+    return c.text(`removed agent "${param.name}"`)
+  },
+)

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

@@ -0,0 +1,5 @@
+export const help = `funnel agents rename — rename an agent preset
+
+usage:
+  funnel agents rename <old> <new>
+  funnel agents <old> rename <new>`

package/lib/routes/agents/rename.ts

@@ -0,0 +1,17 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/agents/rename.help"
+
+export const agentsRenameHandler = 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.agents.rename(param.name, param["newName"])
+
+    return c.text(`renamed agent "${param.name}" to "${param["newName"]}"`)
+  },
+)

package/lib/routes/agents/routes.ts

@@ -0,0 +1,17 @@
+import { factory } from "@/factory"
+import { agentsAddHandler } from "@/routes/agents/add"
+import { agentsGroupHandler } from "@/routes/agents/group"
+import { agentsLaunchHandler } from "@/routes/agents/launch"
+import { agentsRemoveHandler } from "@/routes/agents/remove"
+import { agentsRenameHandler } from "@/routes/agents/rename"
+import { agentsSetHandler } from "@/routes/agents/set"
+
+export const agentsRoutes = factory
+  .createApp()
+  .get("/", ...agentsGroupHandler)
+  .put("/:name/rename/:newName", ...agentsRenameHandler)
+  .put("/rename/:name/:newName", ...agentsRenameHandler)
+  .post("/:name", ...agentsAddHandler)
+  .put("/:name", ...agentsSetHandler)
+  .delete("/:name", ...agentsRemoveHandler)
+  .get("/:name", ...agentsLaunchHandler)

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

@@ -0,0 +1,5 @@
+export const help = `funnel agents <name> set — update an agent preset
+
+usage: funnel agents <name> set [--channel <ch>] [--repo <r>] [--sub-agent <s>] [--env-file <f>]
+
+pass an empty string to --repo / --sub-agent to unset them.`

package/lib/routes/agents/set.ts

@@ -0,0 +1,32 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/agents/set.help"
+
+export const agentsSetHandler = factory.createHandlers(
+  zValidator("param", z.object({ name: z.string() })),
+  zValidator(
+    "query",
+    z.object({
+      channel: z.string().optional(),
+      repo: z.string().optional(),
+      "sub-agent": z.string().optional(),
+      "env-file": z.string().optional(),
+    }),
+    help,
+  ),
+  (c) => {
+    const param = c.req.valid("param")
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+
+    funnel.agents.update(param.name, {
+      channel: query.channel,
+      repo: query.repo,
+      subAgent: query["sub-agent"],
+      envFiles: query["env-file"] !== undefined ? [query["env-file"]] : undefined,
+    })
+
+    return c.text(`updated agent "${param.name}"`)
+  },
+)

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

@@ -0,0 +1,3 @@
+export const help = `funnel channels add — add a channel
+
+usage: funnel channels add <name> [--connector <c>]...`

package/lib/routes/channels/add.ts

@@ -0,0 +1,21 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/channels/add.help"
+
+export const channelsAddHandler = factory.createHandlers(
+  zValidator("param", z.object({ name: z.string() })),
+  zValidator("query", z.object({ connector: z.string().optional() }), help),
+  (c) => {
+    const param = c.req.valid("param")
+    const query = c.req.valid("query")
+    const funnel = c.var.funnel
+
+    funnel.channels.add({
+      name: param.name,
+      connectors: query.connector ? [query.connector] : [],
+    })
+
+    return c.text(`added channel "${param.name}"`)
+  },
+)

package/lib/routes/channels/connectors-attach.help.ts

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

package/lib/routes/channels/connectors-attach.ts

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

package/lib/routes/channels/connectors-detach.help.ts

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

package/lib/routes/channels/connectors-detach.ts

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

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

@@ -0,0 +1,16 @@
+export const help = `funnel channels — manage subscription boxes
+
+usage: funnel channels [subcommand]
+
+subcommands:
+  (none)                          list
+  add <name>                      add
+  remove <name>                   remove
+  <name>                          show details
+  <name> connectors attach <c>    subscribe to a connector
+  <name> connectors detach <c>    unsubscribe from a connector
+
+examples:
+  funnel channels add prod-inbox
+  funnel channels prod-inbox connectors attach prod-slack
+  funnel channels prod-inbox`

package/lib/routes/channels/group.ts

@@ -0,0 +1,22 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/channels/group.help"
+
+export const channelsGroupHandler = factory.createHandlers(
+  zValidator("query", z.object({}), help),
+  (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 connectors = ch.connectors.length > 0 ? ch.connectors.join(", ") : "(none)"
+
+      return `${ch.name} [${connectors}]`
+    })
+
+    return c.text(lines.join("\n"))
+  },
+)

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

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

package/lib/routes/channels/remove.ts

@@ -0,0 +1,17 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/channels/remove.help"
+
+export const channelsRemoveHandler = 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.channels.remove(param.name)
+
+    return c.text(`removed channel "${param.name}"`)
+  },
+)

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

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

package/lib/routes/channels/rename.ts

@@ -0,0 +1,17 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { zValidator } from "@/modules/router/validator"
+import { help } from "@/routes/channels/rename.help"
+
+export const channelsRenameHandler = 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.channels.rename(param.name, param["newName"])
+
+    return c.text(`renamed channel "${param.name}" to "${param["newName"]}"`)
+  },
+)

package/lib/routes/channels/routes.ts

@@ -0,0 +1,19 @@
+import { factory } from "@/factory"
+import { channelsAddHandler } from "@/routes/channels/add"
+import { channelsConnectorsAttachHandler } from "@/routes/channels/connectors-attach"
+import { channelsConnectorsDetachHandler } from "@/routes/channels/connectors-detach"
+import { channelsGroupHandler } from "@/routes/channels/group"
+import { channelsRemoveHandler } from "@/routes/channels/remove"
+import { channelsRenameHandler } from "@/routes/channels/rename"
+import { channelsShowHandler } from "@/routes/channels/show"
+
+export const channelsRoutes = factory
+  .createApp()
+  .get("/", ...channelsGroupHandler)
+  .put("/:name/rename/:newName", ...channelsRenameHandler)
+  .put("/rename/:name/:newName", ...channelsRenameHandler)
+  .put("/:name/connectors/attach/:connector", ...channelsConnectorsAttachHandler)
+  .delete("/:name/connectors/detach/:connector", ...channelsConnectorsDetachHandler)
+  .post("/:name", ...channelsAddHandler)
+  .delete("/:name", ...channelsRemoveHandler)
+  .get("/:name", ...channelsShowHandler)