@bprp/flockcode 0.0.2

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@bprp/flockcode",
+  "version": "0.0.2",
+  "bin": {
+    "flockcode": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts"
+  ],
+  "engines": {
+    "bun": ">=1.2.17"
+  },
+  "scripts": {
+    "dev": "bun --hot src/server.ts",
+    "start": "bun src/server.ts",
+    "test": "bun test",
+    "build:diff-page": "bun build src/diff-page/index.html --outdir=src/diff-page/dist --minify"
+  },
+  "dependencies": {
+    "@crustjs/core": "^0.0.15",
+    "@crustjs/plugins": "^0.0.19",
+    "@crustjs/store": "^0.0.4",
+    "@crustjs/validate": "^0.0.13",
+    "@durable-streams/server": "0.2.1",
+    "@fly/sprites": "^0.0.1",
+    "@opencode-ai/sdk": "^1.2.10",
+    "@orpc/client": "^1.13.10",
+    "@orpc/server": "^1.13.10",
+    "@pierre/diffs": "^1.0.11",
+    "@tanstack/ai": "^0.5.1",
+    "@tanstack/ai-gemini": "^0.5.0",
+    "durable-streams-web-standard": "github:ben-pr-p/durable-streams-web-standard",
+    "envalid": "^8.1.1",
+    "hono": "4.12.5",
+    "nanoid": "^5.1.6",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.2"
+  }
+}

package/src/app.ts

@@ -0,0 +1,153 @@
+import { Hono, type Context } from "hono"
+import { DurableStreamServer } from "durable-streams-web-standard"
+import { FileBackedStreamStore } from "@durable-streams/server"
+import { dataDir } from "@crustjs/store"
+import { customAlphabet } from "nanoid"
+import { RPCHandler } from "@orpc/server/fetch"
+import { onError } from "@orpc/server"
+import { createClient, Opencode, handleOpencodeEvent } from "./opencode"
+import { env } from "./env"
+import { StateStream } from "./state-stream"
+import { router } from "./router"
+import type { RouterContext } from "./router"
+import { logger } from 'hono/logger'
+
+/** Hono handler that strips a prefix from the URL and forwards to a DurableStreamServer. */
+function rewriteToDs(prefix: string, ds: DurableStreamServer) {
+  return (c: Context) => {
+    const url = new URL(c.req.url)
+    url.pathname = url.pathname.slice(prefix.length) || "/"
+    const offset = url.searchParams.get("offset")
+    if (offset && offset !== "-1") {
+      console.log(`[stream-offset] Resuming from offset ${offset} for ${prefix}`)
+    }
+    return ds.fetch(new Request(url.toString(), c.req.raw))
+  }
+}
+
+const generateInstanceId = customAlphabet("abcdefghijklmnopqrstuvwxyz", 12)
+
+export async function createApp(opencodeUrl: string) {
+  const client = createClient(opencodeUrl)
+  const opencode = new Opencode(opencodeUrl)
+
+  // Unique instance ID for this server boot — clients use this to detect restarts
+  const instanceId = generateInstanceId()
+
+  // Persistent app state stream — survives server restarts
+  const appDataDir = dataDir("flockcode")
+  const appStore = new FileBackedStreamStore({ dataDir: appDataDir })
+  const appDs = new DurableStreamServer({ store: appStore })
+  await appDs.createStream("/", { contentType: "application/json" })
+
+  // In-memory index of session→worktree mappings, rebuilt from the persistent
+  // app state stream on startup so worktree cleanup survives server restarts.
+  const sessionWorktrees = new Map<string, { worktreePath: string; projectWorktree: string }>()
+  try {
+    const { messages } = appDs.readStream("/")
+    const decoder = new TextDecoder()
+    for (const msg of messages) {
+      const event = JSON.parse(decoder.decode(msg.data))
+      if (event.type === "sessionWorktree" && event.value) {
+        sessionWorktrees.set(event.key, {
+          worktreePath: event.value.worktreePath,
+          projectWorktree: event.value.projectWorktree,
+        })
+      }
+    }
+  } catch {
+    // Stream may be empty on first boot — that's fine
+  }
+
+  // Instance stream — finalized, replayable state events.
+  // Created after sessionWorktrees so initialization can emit merge status.
+  const instanceDs = new DurableStreamServer()
+
+  // Ephemeral stream — live-only UI state (session status, in-progress messages, worktree status).
+  const ephemeralDs = new DurableStreamServer()
+
+  const stateStream = new StateStream(instanceDs, ephemeralDs, client, sessionWorktrees)
+  stateStream.initialize().catch((err) => {
+    console.error("Failed to initialize state stream:", err)
+  })
+
+  // Subscribe to opencode events and route them to the state stream
+  opencode.spawnListener((event) => handleOpencodeEvent(event, stateStream), opencodeUrl).catch((err) => {
+    console.error("Failed to start opencode event listener:", err)
+  })
+
+  const app = new Hono()
+  app.use(logger())
+
+  // Optional bearer token auth — required when FLOCK_AUTH_TOKEN is set
+  // (e.g., on a publicly accessible Fly Sprite). No-op when running locally.
+  const authToken = env.FLOCK_AUTH_TOKEN
+  if (authToken) {
+    app.use('*', async (c, next) => {
+      const header = c.req.header('Authorization')
+      if (header !== `Bearer ${authToken}`) {
+        return c.json({ error: 'Unauthorized' }, 401)
+      }
+      return next()
+    })
+  }
+
+  // Returns the current instance ID so clients know where to connect
+  app.get("/", (c) => {
+    return c.json({ instanceId, appStreamUrl: "/app" })
+  })
+
+  // Ephemeral stream — live-only state, no catch-up replay
+  // Must be mounted before the instance stream catch-all so it matches first.
+  const ephemeralPrefix = `/${instanceId}/ephemeral`
+  app.all(`${ephemeralPrefix}/*`, rewriteToDs(ephemeralPrefix, ephemeralDs))
+  app.all(ephemeralPrefix, rewriteToDs(ephemeralPrefix, ephemeralDs))
+
+  // Instance stream — finalized, replayable state events
+  const instancePrefix = `/${instanceId}`
+  app.all(`${instancePrefix}/*`, rewriteToDs(instancePrefix, instanceDs))
+  app.all(instancePrefix, rewriteToDs(instancePrefix, instanceDs))
+
+  // Persistent app state stream — fixed path, never resets
+  app.all("/app/*", rewriteToDs("/app", appDs))
+  app.all("/app", rewriteToDs("/app", appDs))
+
+  app.get("/health", async (c) => {
+    return c.json({ healthy: true, opencodeUrl, instanceId })
+  })
+
+  // -----------------------------------------------------------------------
+  // oRPC handler — serves all typed API procedures at /api/*
+  // -----------------------------------------------------------------------
+
+  const routerContext: RouterContext = {
+    client,
+    appDs,
+    ephemeralDs,
+    sessionWorktrees,
+    stateStream,
+  }
+
+  const rpcHandler = new RPCHandler(router, {
+    interceptors: [
+      onError((error) => {
+        console.error("[oRPC]", error)
+      }),
+    ],
+  })
+
+  app.use("/api/*", async (c, next) => {
+    const { matched, response } = await rpcHandler.handle(c.req.raw, {
+      prefix: "/api",
+      context: routerContext,
+    })
+    if (matched) {
+      return c.newResponse(response.body, response)
+    }
+    await next()
+  })
+
+  return { app, instanceDs, ephemeralDs, appDs, stateStream, instanceId }
+}
+
+export type { Router } from "./router"

package/src/diagnose-stream.ts

@@ -0,0 +1,305 @@
+/**
+ * Diagnostic script: fetches all data from the durable stream and reports
+ * which events are largest, helping identify what causes the
+ * "String length exceeds limit" RangeError on the client.
+ *
+ * Usage:
+ *   bun packages/server/src/diagnose-stream.ts [--url http://localhost:3000] [--token TOKEN]
+ */
+
+import { stream } from "@durable-streams/client"
+
+// ---------------------------------------------------------------------------
+// CLI args
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2)
+function getArg(name: string, fallback: string): string {
+  const idx = args.indexOf(name)
+  return idx >= 0 && args[idx + 1] ? args[idx + 1]! : fallback
+}
+
+const BASE_URL = getArg("--url", "http://localhost:3000")
+const AUTH_TOKEN = getArg("--token", process.env.FLOCK_AUTH_TOKEN ?? "")
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface StateEvent {
+  type: string
+  key: string
+  value?: unknown
+  headers: { operation: string }
+}
+
+function byteLen(s: string): number {
+  return new TextEncoder().encode(s).byteLength
+}
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`
+}
+
+/** Summarize the parts of a message value to show which part is large. */
+function summarizeMessageParts(value: any): string[] {
+  if (!value?.parts) return []
+  return (value.parts as any[]).map((p: any, i: number) => {
+    const json = JSON.stringify(p)
+    const size = byteLen(json)
+    let label = `  part[${i}] type=${p.type}`
+    if (p.type === "tool") {
+      label += ` tool=${p.tool}`
+      if (p.state?.status) label += ` status=${p.state.status}`
+      if (p.state?.output) {
+        const outLen = byteLen(p.state.output)
+        label += ` output=${formatBytes(outLen)}`
+      }
+      if (p.state?.input) {
+        const inLen = byteLen(JSON.stringify(p.state.input))
+        label += ` input=${formatBytes(inLen)}`
+      }
+    }
+    if (p.type === "text" && p.text) {
+      label += ` text=${formatBytes(byteLen(p.text))}`
+    }
+    label += ` → total=${formatBytes(size)}`
+    return label
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  console.log(`Connecting to ${BASE_URL} ...`)
+
+  // 1. Discover the instanceId
+  const headers: Record<string, string> = {}
+  if (AUTH_TOKEN) headers["Authorization"] = `Bearer ${AUTH_TOKEN}`
+
+  const rootRes = await fetch(BASE_URL, { headers })
+  if (!rootRes.ok) {
+    console.error(`Failed to reach server: ${rootRes.status} ${rootRes.statusText}`)
+    process.exit(1)
+  }
+  const { instanceId, appStreamUrl } = (await rootRes.json()) as {
+    instanceId: string
+    appStreamUrl: string
+  }
+  console.log(`Instance ID: ${instanceId}`)
+
+  // 2. Fetch the instance state stream (catch-up only, no live)
+  const stateUrl = `${BASE_URL}/${instanceId}/`
+  console.log(`\nFetching instance stream: ${stateUrl}`)
+
+  const stateRes = await stream<StateEvent>({
+    url: stateUrl,
+    offset: "-1",
+    live: false,
+    headers: AUTH_TOKEN ? { Authorization: `Bearer ${AUTH_TOKEN}` } : undefined,
+  })
+
+  const events = await stateRes.json()
+  console.log(`Total events: ${events.length}`)
+
+  // 3. Compute sizes
+  type SizedEvent = {
+    index: number
+    type: string
+    key: string
+    operation: string
+    jsonSize: number
+    json: string
+    event: StateEvent
+  }
+
+  const sized: SizedEvent[] = events.map((e, i) => {
+    const json = JSON.stringify(e)
+    return {
+      index: i,
+      type: e.type,
+      key: e.key,
+      operation: e.headers.operation,
+      jsonSize: byteLen(json),
+      json,
+      event: e,
+    }
+  })
+
+  // 4. Overall stats
+  const totalBytes = sized.reduce((s, e) => s + e.jsonSize, 0)
+  console.log(`Total payload size: ${formatBytes(totalBytes)}`)
+
+  // Size by type
+  const byType = new Map<string, { count: number; bytes: number }>()
+  for (const e of sized) {
+    const entry = byType.get(e.type) ?? { count: 0, bytes: 0 }
+    entry.count++
+    entry.bytes += e.jsonSize
+    byType.set(e.type, entry)
+  }
+
+  console.log(`\n--- Breakdown by event type ---`)
+  for (const [type, { count, bytes }] of [...byType.entries()].sort(
+    (a, b) => b[1].bytes - a[1].bytes,
+  )) {
+    console.log(`  ${type}: ${count} events, ${formatBytes(bytes)} total, ${formatBytes(bytes / count)} avg`)
+  }
+
+  // 5. Top 20 largest events
+  const sorted = [...sized].sort((a, b) => b.jsonSize - a.jsonSize)
+  console.log(`\n--- Top 20 largest events ---`)
+  for (const e of sorted.slice(0, 20)) {
+    console.log(
+      `#${e.index} type=${e.type} key=${e.key} op=${e.operation} size=${formatBytes(e.jsonSize)}`,
+    )
+    if (e.type === "message") {
+      const parts = summarizeMessageParts(e.event.value)
+      for (const line of parts) console.log(line)
+    }
+  }
+
+  // 6. Identify sessions with the most data
+  const bySession = new Map<string, { messageCount: number; totalBytes: number; largestMessage: number }>()
+  for (const e of sized) {
+    if (e.type !== "message") continue
+    const sessionId = (e.event.value as any)?.sessionId
+    if (!sessionId) continue
+    const entry = bySession.get(sessionId) ?? { messageCount: 0, totalBytes: 0, largestMessage: 0 }
+    entry.messageCount++
+    entry.totalBytes += e.jsonSize
+    entry.largestMessage = Math.max(entry.largestMessage, e.jsonSize)
+    bySession.set(sessionId, entry)
+  }
+
+  console.log(`\n--- Sessions by total message data ---`)
+  const sessionsSorted = [...bySession.entries()].sort(
+    (a, b) => b[1].totalBytes - a[1].totalBytes,
+  )
+  for (const [sessionId, { messageCount, totalBytes, largestMessage }] of sessionsSorted.slice(0, 10)) {
+    console.log(
+      `  session=${sessionId}  messages=${messageCount}  total=${formatBytes(totalBytes)}  largest=${formatBytes(largestMessage)}`,
+    )
+  }
+
+  // 7. Check the full serialized stream size (what the client receives on initial load)
+  // The server wraps all events in a single JSON array for the initial GET
+  const fullPayload = JSON.stringify(events)
+  const fullPayloadSize = byteLen(fullPayload)
+  console.log(`\n--- Initial load payload ---`)
+  console.log(`Full JSON array size: ${formatBytes(fullPayloadSize)}`)
+  console.log(`String length (chars): ${fullPayload.length.toLocaleString()}`)
+
+  // JS string length limit is ~512MB on V8 / ~1GB on JSC but some RN
+  // implementations may have lower limits. Flag if over 100MB.
+  if (fullPayload.length > 100_000_000) {
+    console.log(`⚠️  WARNING: Payload string length exceeds 100M chars — likely cause of RangeError!`)
+  } else if (fullPayload.length > 50_000_000) {
+    console.log(`⚠️  WARNING: Payload string length exceeds 50M chars — may cause issues on mobile`)
+  } else if (fullPayload.length > 10_000_000) {
+    console.log(`⚠️  CAUTION: Payload string length exceeds 10M chars — large for mobile`)
+  }
+
+  // 8. Also check the ephemeral stream
+  console.log(`\n--- Ephemeral stream ---`)
+  const ephemeralUrl = `${BASE_URL}/${instanceId}/ephemeral/`
+  console.log(`Fetching: ${ephemeralUrl}`)
+  try {
+    const ephRes = await stream<StateEvent>({
+      url: ephemeralUrl,
+      offset: "-1",
+      live: false,
+      headers: AUTH_TOKEN ? { Authorization: `Bearer ${AUTH_TOKEN}` } : undefined,
+    })
+    const ephEvents = await ephRes.json()
+    const ephPayload = JSON.stringify(ephEvents)
+    console.log(`Ephemeral events: ${ephEvents.length}`)
+    console.log(`Ephemeral payload size: ${formatBytes(byteLen(ephPayload))}`)
+    console.log(`Ephemeral string length: ${ephPayload.length.toLocaleString()}`)
+
+    // Breakdown by type
+    const ephByType = new Map<string, { count: number; bytes: number }>()
+    for (const e of ephEvents) {
+      const json = JSON.stringify(e)
+      const entry = ephByType.get(e.type) ?? { count: 0, bytes: 0 }
+      entry.count++
+      entry.bytes += byteLen(json)
+      ephByType.set(e.type, entry)
+    }
+    for (const [type, { count, bytes }] of [...ephByType.entries()].sort(
+      (a, b) => b[1].bytes - a[1].bytes,
+    )) {
+      console.log(`  ${type}: ${count} events, ${formatBytes(bytes)} total`)
+    }
+  } catch (err) {
+    console.log(`Could not fetch ephemeral stream: ${err}`)
+  }
+
+  // 9. Also check the app stream
+  console.log(`\n--- App state stream ---`)
+  const appUrl = `${BASE_URL}${appStreamUrl}/`
+  console.log(`Fetching: ${appUrl}`)
+  try {
+    const appRes = await stream<StateEvent>({
+      url: appUrl,
+      offset: "-1",
+      live: false,
+      headers: AUTH_TOKEN ? { Authorization: `Bearer ${AUTH_TOKEN}` } : undefined,
+    })
+    const appEvents = await appRes.json()
+    const appPayload = JSON.stringify(appEvents)
+    console.log(`App events: ${appEvents.length}`)
+    console.log(`App payload size: ${formatBytes(byteLen(appPayload))}`)
+    console.log(`App string length: ${appPayload.length.toLocaleString()}`)
+  } catch (err) {
+    console.log(`Could not fetch app stream: ${err}`)
+  }
+
+  // 10. Check for duplicate message events (same key emitted many times)
+  // The stream is append-only: every messagePartDelta and update re-emits
+  // the full message, so the same message key appears many times.
+  const keyCounts = new Map<string, { count: number; totalBytes: number; lastSize: number }>()
+  for (const e of sized) {
+    const compoundKey = `${e.type}:${e.key}`
+    const entry = keyCounts.get(compoundKey) ?? { count: 0, totalBytes: 0, lastSize: 0 }
+    entry.count++
+    entry.totalBytes += e.jsonSize
+    entry.lastSize = e.jsonSize
+    keyCounts.set(compoundKey, entry)
+  }
+
+  const duplicates = [...keyCounts.entries()]
+    .filter(([, v]) => v.count > 1)
+    .sort((a, b) => b[1].totalBytes - a[1].totalBytes)
+
+  console.log(`\n--- Most-duplicated keys (events re-emitted as stream appends) ---`)
+  console.log(`(Each update re-appends the full object. These accumulate in the stream.)`)
+  for (const [key, { count, totalBytes, lastSize }] of duplicates.slice(0, 15)) {
+    console.log(
+      `  ${key}: emitted ${count}x, accumulated ${formatBytes(totalBytes)}, final size ${formatBytes(lastSize)}`,
+    )
+  }
+
+  // 11. Estimate the "effective" payload — only last version of each key matters
+  // for state, but ALL versions are in the stream and sent to the client.
+  const lastVersion = new Map<string, number>()
+  for (const e of sized) {
+    lastVersion.set(`${e.type}:${e.key}`, e.jsonSize)
+  }
+  const effectiveBytes = [...lastVersion.values()].reduce((s, v) => s + v, 0)
+  console.log(`\n--- Stream efficiency ---`)
+  console.log(`Total stream bytes (all appends): ${formatBytes(totalBytes)}`)
+  console.log(`Effective state bytes (latest per key): ${formatBytes(effectiveBytes)}`)
+  console.log(`Overhead from duplicates: ${formatBytes(totalBytes - effectiveBytes)} (${((1 - effectiveBytes / totalBytes) * 100).toFixed(1)}%)`)
+
+  console.log(`\nDone.`)
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/src/env.ts

@@ -0,0 +1,35 @@
+/**
+ * Validated environment variables for the server.
+ *
+ * Import `env` from this module instead of reading `process.env` directly.
+ * Validation runs once on first import — missing required variables cause an
+ * immediate, descriptive error.
+ */
+
+import { cleanEnv, str, port, url } from "envalid"
+
+export const env = cleanEnv(process.env, {
+  // --- Server ---
+  /** Port for the Hono HTTP server. */
+  PORT: port({ default: 3000 }),
+  /** URL of the OpenCode server to bridge. Empty string means "spawn one automatically". */
+  OPENCODE_URL: str({ default: "" }),
+
+  // --- Auth ---
+  /** Bearer token for authenticating mobile clients. Optional when running locally. */
+  FLOCK_AUTH_TOKEN: str({ default: "" }),
+
+  // --- Gemini (transcription) ---
+  /** Google / Gemini API key for audio transcription. Read by @tanstack/ai-gemini. */
+  GEMINI_API_KEY: str({ default: "" }),
+  /** Gemini model for audio transcription. Either "gemini-3-flash-preview" or "gemini-3.1-flash-lite-preview". */
+  TRANSCRIPTION_MODEL: str({ default: "gemini-3.1-flash-lite-preview" }),
+
+  // --- Fly Sprites ---
+  /** Name of the Fly Sprite to sync projects to. Required for `sync` command. */
+  SPRITE_NAME: str({ default: "" }),
+  /** Sprites API authentication token. Required for `sync` command. */
+  SPRITES_TOKEN: str({ default: "" }),
+  /** Sprites API base URL override. */
+  SPRITES_API_URL: url({ default: "https://api.sprites.dev" }),
+})