@interactive-inc/claude-funnel 0.7.1 → 0.8.1

package/lib/{modules/connectors/funnel-gh-listener.ts → connectors/gh-listener.ts}

@@ -1,20 +1,26 @@
-import {
-  FunnelConnectorListener,
-  type NotifyFn,
-} from "@/modules/connectors/funnel-connector-listener"
-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"
-import type { GhConnectorConfig } from "@/modules/connectors/gh-connector-schema"
-
-type GhNotification = {
-  id: string
-  reason: string
-  subject: { type: string; url: string; title: string }
-  repository: { full_name: string }
-  updated_at: string
-}
+import { z } from "zod"
+import { FunnelConnectorListener, type NotifyFn } from "@/connectors/connector-listener"
+import { FunnelLogger } from "@/engine/logger/logger"
+import { NodeFunnelLogger } from "@/engine/logger/node-logger"
+import { FunnelProcessRunner } from "@/engine/process/process-runner"
+import { NodeFunnelProcessRunner } from "@/engine/process/node-process-runner"
+import type { GhConnectorConfig } from "@/connectors/gh-connector-schema"
+
+const ghNotificationSchema = z.object({
+  id: z.string(),
+  reason: z.string(),
+  subject: z.object({
+    type: z.string(),
+    url: z.string(),
+    title: z.string(),
+  }),
+  repository: z.object({ full_name: z.string() }),
+  updated_at: z.string(),
+})
+
+const ghNotificationsSchema = z.array(ghNotificationSchema)
+
+type GhNotification = z.infer<typeof ghNotificationSchema>
 
 type Deps = {
   config: GhConnectorConfig
@@ -37,6 +43,7 @@ export class FunnelGhListener extends FunnelConnectorListener {
   private readonly seen = new Map<string, string>()
   private bootstrapped = false
   private since: string
+  private timer: ReturnType<typeof setInterval> | null = null
 
   constructor(deps: Deps) {
     super()
@@ -52,7 +59,19 @@ export class FunnelGhListener extends FunnelConnectorListener {
 
     const interval = this.config.pollInterval ?? 60
 
-    setInterval(() => void this.pollOnce(notify), interval * 1000).unref()
+    this.timer = setInterval(() => void this.pollOnce(notify), interval * 1000)
+    this.timer.unref()
+  }
+
+  async stop(): Promise<void> {
+    if (!this.timer) return
+
+    clearInterval(this.timer)
+    this.timer = null
+  }
+
+  override isAlive(): boolean {
+    return this.timer !== null
   }
 
   async pollOnce(notify: NotifyFn): Promise<void> {
@@ -67,7 +86,14 @@ export class FunnelGhListener extends FunnelConnectorListener {
         return
       }
 
-      const items = JSON.parse(result.stdout) as GhNotification[]
+      const parsed = ghNotificationsSchema.safeParse(JSON.parse(result.stdout))
+
+      if (!parsed.success) {
+        this.logger.warn("gh response did not match schema", { error: parsed.error.message })
+        return
+      }
+
+      const items: GhNotification[] = parsed.data
 
       for (const item of items) {
         if (this.seen.get(item.id) === item.updated_at) continue

package/lib/{modules/connectors → connectors}/match-cron.ts

@@ -18,14 +18,16 @@ const parseField = (expr: string, min: number, max: number): Field => {
       lo = min
       hi = max
     } else if (rangePart.includes("-")) {
-      const [a, b] = rangePart.split("-").map(Number)
+      const [aStr, bStr] = rangePart.split("-")
+      const a = Number(aStr)
+      const b = Number(bStr)
 
       if (!Number.isFinite(a) || !Number.isFinite(b)) {
         throw new Error(`invalid cron range: "${rangePart}"`)
       }
 
-      lo = a as number
-      hi = b as number
+      lo = a
+      hi = b
     } else {
       const n = Number(rangePart)
 
@@ -54,7 +56,11 @@ export const matchCron = (expr: string, date: Date): boolean => {
     throw new Error(`cron must have 5 fields (got ${parts.length}): "${expr}"`)
   }
 
-  const [minute, hour, dom, month, dow] = parts as [string, string, string, string, string]
+  const [minute, hour, dom, month, dow] = parts
+
+  if (!minute || !hour || !dom || !month || !dow) {
+    throw new Error(`cron has empty fields: "${expr}"`)
+  }
 
   const fields = [
     { field: parseField(minute, 0, 59), value: date.getMinutes() },

package/lib/connectors/schedule-connector-schema.ts

@@ -0,0 +1,33 @@
+import { z } from "zod"
+
+/**
+ * Catch-up behavior when the daemon was down past one or more matching minutes.
+ *
+ * - `latest`: fire once with the most recent missed match (default; preserves prior behavior).
+ * - `all`: fire once per missed minute, oldest first (capped at 24 h).
+ * - `skip`: never fire missed matches; only fire when the current minute matches.
+ */
+export const scheduleCatchupPolicySchema = z.enum(["latest", "all", "skip"])
+
+export type ScheduleCatchupPolicy = z.infer<typeof scheduleCatchupPolicySchema>
+
+export const scheduleEntrySchema = z.object({
+  id: z.string(),
+  cron: z.string(),
+  prompt: z.string(),
+  enabled: z.boolean().default(true),
+  catchupPolicy: scheduleCatchupPolicySchema.default("latest"),
+})
+
+export type ScheduleEntry = z.infer<typeof scheduleEntrySchema>
+
+export const scheduleConnectorSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.literal("schedule"),
+  entries: z.array(scheduleEntrySchema).default([]),
+  createdAt: z.string().datetime().optional(),
+  updatedAt: z.string().datetime().optional(),
+})
+
+export type ScheduleConnectorConfig = z.infer<typeof scheduleConnectorSchema>

package/lib/connectors/schedule-listener.ts

@@ -0,0 +1,207 @@
+import { FunnelConnectorListener, type NotifyFn } from "@/connectors/connector-listener"
+import { matchCron } from "@/connectors/match-cron"
+import { ScheduleStateStore } from "@/connectors/schedule-state-store"
+import { FunnelLogger } from "@/engine/logger/logger"
+import { NodeFunnelLogger } from "@/engine/logger/node-logger"
+import type { ScheduleConnectorConfig, ScheduleEntry } from "@/connectors/schedule-connector-schema"
+
+type Deps = {
+  config: ScheduleConnectorConfig
+  lastFiredStore: ScheduleStateStore
+  logger?: FunnelLogger
+  now?: () => Date
+}
+
+const defaultLogger = new NodeFunnelLogger()
+
+const MAX_CATCHUP_MINUTES = 60 * 24
+
+export class FunnelScheduleListener extends FunnelConnectorListener {
+  private readonly config: ScheduleConnectorConfig
+  private readonly lastFiredStore: ScheduleStateStore
+  private readonly logger: FunnelLogger
+  private readonly now: () => Date
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private stopped = false
+
+  constructor(deps: Deps) {
+    super()
+    this.config = deps.config
+    this.lastFiredStore = deps.lastFiredStore
+    this.logger = deps.logger ?? defaultLogger
+    this.now = deps.now ?? (() => new Date())
+  }
+
+  async start(notify: NotifyFn): Promise<void> {
+    this.stopped = false
+
+    const scheduleNext = () => {
+      if (this.stopped) return
+
+      const date = this.now()
+      const msUntilNextMinute = 60_000 - (date.getSeconds() * 1000 + date.getMilliseconds())
+      this.timer = setTimeout(async () => {
+        if (this.stopped) return
+        await this.tick(notify)
+        scheduleNext()
+      }, msUntilNextMinute)
+
+      this.timer.unref()
+    }
+
+    await this.tick(notify)
+    scheduleNext()
+  }
+
+  async stop(): Promise<void> {
+    this.stopped = true
+
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+
+  override isAlive(): boolean {
+    return !this.stopped && this.timer !== null
+  }
+
+  async tick(notify: NotifyFn): Promise<void> {
+    const now = this.truncateToMinute(this.now())
+    const state = this.lastFiredStore.load()
+    let changed = false
+
+    for (const entry of this.config.entries) {
+      if (!entry.enabled) continue
+
+      const fired = await this.fireEntry(entry, now, state, notify)
+
+      if (fired) changed = true
+    }
+
+    if (changed) this.lastFiredStore.save(state)
+  }
+
+  private async fireEntry(
+    entry: ScheduleEntry,
+    now: Date,
+    state: Map<string, Date>,
+    notify: NotifyFn,
+  ): Promise<boolean> {
+    const lastFired = state.get(entry.id)
+    const searchFrom = lastFired ? new Date(lastFired.getTime() + 60_000) : now
+
+    if (searchFrom.getTime() > now.getTime()) return false
+
+    if (entry.catchupPolicy === "skip") {
+      try {
+        if (!matchCron(entry.cron, now)) return false
+      } catch (error) {
+        this.logInvalidCron(entry, error)
+        return false
+      }
+
+      await this.notifyOne(entry, now, notify, false)
+      state.set(entry.id, now)
+      return true
+    }
+
+    if (entry.catchupPolicy === "all") {
+      const matches = this.findAllMatches(entry.cron, searchFrom, now, entry.id)
+
+      if (matches.length === 0) return false
+
+      for (const match of matches) {
+        await this.notifyOne(entry, match, notify, match.getTime() !== now.getTime())
+      }
+
+      state.set(entry.id, matches[matches.length - 1] ?? now)
+      return true
+    }
+
+    const match = this.findMostRecentMatch(entry.cron, searchFrom, now, entry.id)
+
+    if (!match) return false
+
+    await this.notifyOne(entry, match, notify, match.getTime() !== now.getTime())
+    state.set(entry.id, match)
+    return true
+  }
+
+  private async notifyOne(
+    entry: ScheduleEntry,
+    firedAt: Date,
+    notify: NotifyFn,
+    catchup: boolean,
+  ): Promise<void> {
+    const meta: Record<string, string> = {
+      event_type: "schedule",
+      schedule_id: entry.id,
+      cron: entry.cron,
+      fired_at: firedAt.toISOString(),
+      catchup_policy: entry.catchupPolicy,
+    }
+
+    if (catchup) meta.catchup = "true"
+
+    await notify(entry.prompt, meta)
+  }
+
+  private findMostRecentMatch(cron: string, from: Date, until: Date, entryId: string): Date | null {
+    const maxIterations = Math.min(
+      MAX_CATCHUP_MINUTES,
+      Math.floor((until.getTime() - from.getTime()) / 60_000) + 1,
+    )
+
+    for (let i = 0; i < maxIterations; i++) {
+      const candidate = new Date(until.getTime() - i * 60_000)
+
+      try {
+        if (matchCron(cron, candidate)) return candidate
+      } catch (error) {
+        this.logInvalidCron({ id: entryId, cron } as ScheduleEntry, error)
+        return null
+      }
+    }
+
+    return null
+  }
+
+  private findAllMatches(cron: string, from: Date, until: Date, entryId: string): Date[] {
+    const maxIterations = Math.min(
+      MAX_CATCHUP_MINUTES,
+      Math.floor((until.getTime() - from.getTime()) / 60_000) + 1,
+    )
+    const matches: Date[] = []
+
+    for (let i = 0; i < maxIterations; i++) {
+      const candidate = new Date(from.getTime() + i * 60_000)
+
+      if (candidate.getTime() > until.getTime()) break
+
+      try {
+        if (matchCron(cron, candidate)) matches.push(candidate)
+      } catch (error) {
+        this.logInvalidCron({ id: entryId, cron } as ScheduleEntry, error)
+        return []
+      }
+    }
+
+    return matches
+  }
+
+  private logInvalidCron(entry: Pick<ScheduleEntry, "id" | "cron">, error: unknown): void {
+    this.logger.error("invalid cron expression in schedule", {
+      connector: this.config.name,
+      id: entry.id,
+      cron: entry.cron,
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+
+  private truncateToMinute(date: Date): Date {
+    const copy = new Date(date.getTime())
+    copy.setSeconds(0, 0)
+    return copy
+  }
+}

package/lib/connectors/schedule-state-store.ts

@@ -0,0 +1,54 @@
+import { dirname } from "node:path"
+import { FunnelFileSystem } from "@/engine/fs/file-system"
+import { NodeFunnelFileSystem } from "@/engine/fs/node-file-system"
+
+type Deps = {
+  path: string
+  fs?: FunnelFileSystem
+}
+
+const defaultFs = new NodeFunnelFileSystem()
+
+/**
+ * Per-connector lastFiredAt persistence for the schedule listener. The path is
+ * passed in by FunnelConnectorFactory so this store does not know about the
+ * funnel directory layout (`channels/<id>/connectors/<id>/state.json` lives
+ * outside this class).
+ */
+export class ScheduleStateStore {
+  private readonly path: string
+  private readonly fs: FunnelFileSystem
+
+  constructor(deps: Deps) {
+    this.path = deps.path
+    this.fs = deps.fs ?? defaultFs
+    Object.freeze(this)
+  }
+
+  load(): Map<string, Date> {
+    const map = new Map<string, Date>()
+
+    if (!this.fs.existsSync(this.path)) return map
+
+    const raw: unknown = JSON.parse(this.fs.readFileSync(this.path))
+
+    if (raw === null || typeof raw !== "object") return map
+
+    for (const [id, iso] of Object.entries(raw)) {
+      if (typeof iso === "string") map.set(id, new Date(iso))
+    }
+
+    return map
+  }
+
+  save(state: Map<string, Date>): void {
+    const obj: Record<string, string> = {}
+
+    for (const [id, date] of state) {
+      obj[id] = date.toISOString()
+    }
+
+    this.fs.mkdirSync(dirname(this.path), { recursive: true })
+    this.fs.writeFileSync(this.path, `${JSON.stringify(obj, null, 2)}\n`)
+  }
+}

package/lib/connectors/slack-adapter.ts

@@ -0,0 +1,36 @@
+import { WebClient } from "@slack/web-api"
+import { FunnelConnectorAdapter, type CallInput } from "@/connectors/connector-adapter"
+import type { SlackConnectorConfig } from "@/connectors/slack-connector-schema"
+
+export type SlackWebClientLike = {
+  apiCall: (method: string, options?: Record<string, unknown>) => Promise<unknown>
+}
+
+const toRecord = (value: object): Record<string, unknown> => {
+  const result: Record<string, unknown> = {}
+
+  for (const [key, val] of Object.entries(value)) result[key] = val
+
+  return result
+}
+
+type Deps = {
+  config: SlackConnectorConfig
+  client?: SlackWebClientLike
+}
+
+export class FunnelSlackAdapter extends FunnelConnectorAdapter {
+  private readonly client: SlackWebClientLike
+
+  constructor(deps: Deps) {
+    super()
+    this.client = deps.client ?? new WebClient(deps.config.botToken)
+    Object.freeze(this)
+  }
+
+  async call(input: CallInput): Promise<unknown> {
+    const body = input.body !== null && typeof input.body === "object" ? toRecord(input.body) : {}
+
+    return await this.client.apiCall(input.path, body)
+  }
+}

package/lib/{modules/connectors → connectors}/slack-connector-schema.ts

@@ -1,10 +1,13 @@
 import { z } from "zod"
 
 export const slackConnectorSchema = z.object({
-  type: z.literal("slack"),
+  id: z.string(),
   name: z.string(),
+  type: z.literal("slack"),
   botToken: z.string().startsWith("xoxb-"),
   appToken: z.string().startsWith("xapp-"),
+  createdAt: z.string().datetime().optional(),
+  updatedAt: z.string().datetime().optional(),
 })
 
 export type SlackConnectorConfig = z.infer<typeof slackConnectorSchema>

package/lib/{modules/connectors/funnel-slack-event-processor.ts → connectors/slack-event-processor.ts}

@@ -29,6 +29,12 @@ type Props = {
   now?: () => number
 }
 
+const getString = (event: SlackRawEvent, key: string): string | undefined => {
+  const value = event[key]
+
+  return typeof value === "string" ? value : undefined
+}
+
 export class FunnelSlackEventProcessor {
   private readonly ownBotUserId: string
   private readonly ownBotId: string
@@ -42,16 +48,16 @@ export class FunnelSlackEventProcessor {
   }
 
   process(event: SlackRawEvent): SlackProcessed {
-    const eventType = event.type as string | undefined
+    const eventType = getString(event, "type")
 
     if (!eventType || !ALLOWED_EVENTS.has(eventType)) return { skip: true }
 
-    const subtype = event.subtype as string | undefined
+    const subtype = getString(event, "subtype")
 
     if (!ALLOWED_SUBTYPES.has(subtype)) return { skip: true }
 
-    const channelId = (event.channel as string) ?? ""
-    const eventTs = (event.event_ts as string) ?? (event.ts as string) ?? ""
+    const channelId = getString(event, "channel") ?? ""
+    const eventTs = getString(event, "event_ts") ?? getString(event, "ts") ?? ""
     const dedupKey = `${channelId}:${eventTs}`
     const now = this.now()
 
@@ -63,15 +69,15 @@ export class FunnelSlackEventProcessor {
       if ((this.dedup.get(key) ?? 0) < now - DEDUP_WINDOW) this.dedup.delete(key)
     }
 
-    const userId = event.user as string | undefined
-    const botId = event.bot_id as string | undefined
+    const userId = getString(event, "user")
+    const botId = getString(event, "bot_id")
 
     if (userId === this.ownBotUserId) return { skip: true }
     if (botId === this.ownBotId) return { skip: true }
 
-    const text = (event.text as string) ?? ""
+    const text = getString(event, "text") ?? ""
     const mentioned = text.includes(`<@${this.ownBotUserId}>`)
-    const threadTs = (event.thread_ts as string) ?? (event.ts as string) ?? ""
+    const threadTs = getString(event, "thread_ts") ?? getString(event, "ts") ?? ""
 
     return {
       skip: false,
@@ -85,7 +91,7 @@ export class FunnelSlackEventProcessor {
       },
       shouldReact: mentioned,
       channel: channelId,
-      timestamp: (event.ts as string) ?? "",
+      timestamp: getString(event, "ts") ?? "",
     }
   }
 }

package/lib/{modules/connectors/funnel-slack-listener.ts → connectors/slack-listener.ts}

@@ -1,12 +1,14 @@
 import { App, LogLevel } from "@slack/bolt"
-import {
-  FunnelConnectorListener,
-  type NotifyFn,
-} from "@/modules/connectors/funnel-connector-listener"
-import { FunnelSlackEventProcessor } from "@/modules/connectors/funnel-slack-event-processor"
-import { FunnelLogger } from "@/modules/logger/funnel-logger"
-import { NodeFunnelLogger } from "@/modules/logger/node-funnel-logger"
-import type { SlackConnectorConfig } from "@/modules/connectors/slack-connector-schema"
+import { z } from "zod"
+import { FunnelConnectorListener, type NotifyFn } from "@/connectors/connector-listener"
+import { FunnelSlackEventProcessor } from "@/connectors/slack-event-processor"
+import { FunnelLogger } from "@/engine/logger/logger"
+import { NodeFunnelLogger } from "@/engine/logger/node-logger"
+import type { SlackConnectorConfig } from "@/connectors/slack-connector-schema"
+
+const middlewareArgsSchema = z.object({
+  event: z.record(z.string(), z.unknown()).optional(),
+})
 
 type Deps = {
   config: SlackConnectorConfig
@@ -18,12 +20,12 @@ const defaultLogger = new NodeFunnelLogger()
 export class FunnelSlackListener extends FunnelConnectorListener {
   private readonly config: SlackConnectorConfig
   private readonly logger: FunnelLogger
+  private app: App | null = null
 
   constructor(deps: Deps) {
     super()
     this.config = deps.config
     this.logger = deps.logger ?? defaultLogger
-    Object.freeze(this)
   }
 
   async start(notify: NotifyFn): Promise<void> {
@@ -41,13 +43,11 @@ export class FunnelSlackListener extends FunnelConnectorListener {
     })
 
     app.use(async (args) => {
-      const event = (args as unknown as Record<string, unknown>).event as
-        | Record<string, unknown>
-        | undefined
+      const parsed = middlewareArgsSchema.safeParse(args)
 
-      if (!event) return
+      if (!parsed.success || !parsed.data.event) return
 
-      const result = processor.process(event)
+      const result = processor.process(parsed.data.event)
 
       if (result.skip) return
 
@@ -74,5 +74,24 @@ export class FunnelSlackListener extends FunnelConnectorListener {
     })
 
     await app.start()
+    this.app = app
+  }
+
+  async stop(): Promise<void> {
+    if (!this.app) return
+
+    try {
+      await this.app.stop()
+    } catch (error) {
+      this.logger.error("Slack stop error", {
+        error: error instanceof Error ? error.message : String(error),
+      })
+    } finally {
+      this.app = null
+    }
+  }
+
+  override isAlive(): boolean {
+    return this.app !== null
   }
 }