@huynle/hub 0.0.0-stage → 0.6.1

package/src/spoke/localhub.ts

@@ -0,0 +1,287 @@
+// Auto-start of a local hub for a loopback hub URL. When nothing answers on the configured
+// http://127.0.0.1:<port> (or localhost / [::1]), start `bun <this repo>/bin/hub.ts` as a detached
+// background process bound to that address, with output appended to hub.log. Without a bun install it
+// runs the hub with the current executable (OpenCode is a compiled Bun binary) and BUN_BE_BUN=1. A lockfile (hub.pid)
+// makes sure only one process on the machine starts it. Never used for non-loopback servers.
+import { spawn as nodeSpawn } from "node:child_process"
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { hubEnv } from "../env"
+import { isLoopbackURL } from "../loopback"
+import { APP_DIR, legacyPaths, migrateFirst, stateBase } from "../migrate"
+
+export interface ChildLike {
+  readonly pid?: number
+  unref(): void
+  on(event: "exit", listener: (code: number | null, signal: string | null) => void): unknown
+  on(event: "error", listener: (error: Error) => void): unknown
+}
+
+export type SpawnLike = (command: string, args: readonly string[], options: object) => ChildLike
+
+export interface LocalHubOptions {
+  /**
+   * Where hub.pid and hub.log live (default $HUB_STATE_DIR or ~/.local/state/hub, migrated from
+   * ~/.local/state/opencode-hub or opencode-voice first so the hub does not find a fresh, empty state directory).
+   */
+  readonly stateDir?: string
+  /** Home directory for the default state directory (default os.homedir()). */
+  readonly home?: string
+  /** Where a one-time migration notice goes (default console). */
+  readonly log?: (message: string) => void
+  /** This plugin's repository (default: resolved from this file). */
+  readonly repoRoot?: string
+  /** bun executable; shorthand for `runtime: {command: bun, env: {}}`. */
+  readonly bun?: string
+  /** How to run bin/hub.ts (default: resolveHubRuntime for this process). */
+  readonly runtime?: HubRuntime
+  readonly spawn?: SpawnLike
+  readonly fetch?: typeof globalThis.fetch
+  readonly isAlive?: (pid: number) => boolean
+  readonly now?: () => number
+  readonly sleep?: (ms: number) => Promise<void>
+  /** How long to wait for the started hub to answer (default 15 s). */
+  readonly waitMs?: number
+  readonly env?: Readonly<Record<string, string | undefined>>
+  /** This process's pid (written to the lock while starting). */
+  readonly pid?: number
+  /** Whether the repository has the built web app (default: web/dist/index.html exists). */
+  readonly webBuilt?: (root: string) => boolean
+}
+
+/** Why a local hub is not started from an install without web/dist (e.g. the plugin installed from GitHub). */
+export const WEB_NOT_BUILT =
+  "this Hub install has no built web app (web/dist), so its pages would only show an error. " +
+  "Install the plugin from npm (`opencode plugin add @huynle/hub`) or use a release binary, " +
+  "or in a source checkout run `npm install && npm run build:web` first."
+
+const hasWebBuild = (root: string): boolean => existsSync(path.join(root, "web", "dist", "index.html"))
+
+export type LocalHubResult =
+  | { readonly status: "skipped"; readonly reason: string }
+  | { readonly status: "running" }
+  | { readonly status: "started"; readonly pid: number }
+  | { readonly status: "busy"; readonly pid: number }
+  | { readonly status: "failed"; readonly error: string }
+
+interface Lock {
+  readonly pid: number
+  readonly port: number
+  readonly started: number
+}
+
+/** A lock whose hub has not answered for this long is stale, even if its pid is alive (pid reuse). */
+export const LOCK_STALE_MS = 60_000
+const PROBE_TIMEOUT_MS = 1500
+const POLL_MS = 250
+
+export function repoRoot(): string {
+  return fileURLToPath(new URL("../..", import.meta.url)).replace(/\/+$/, "")
+}
+
+export function hubScript(root: string = repoRoot()): string {
+  return path.join(root, "bin", "hub.ts")
+}
+
+export function defaultStateDir(env: Readonly<Record<string, string | undefined>> = process.env, home: string = homedir()): string {
+  return hubEnv(env).HUB_STATE_DIR || path.join(stateBase(home), APP_DIR)
+}
+
+/** The runtime for this process: probes the real executable, PATH and home directory. */
+export function currentHubRuntime(env: Readonly<Record<string, string | undefined>> = process.env): HubRuntime {
+  const isBun = typeof Bun !== "undefined"
+  return resolveHubRuntime({
+    execPath: process.execPath,
+    home: homedir(),
+    isBun,
+    which: (name) => (isBun ? Bun.which(name, env.PATH ? { PATH: env.PATH } : {}) : null),
+    exists: existsSync,
+  })
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM"
+  }
+}
+
+/** The listen address and port the hub needs to serve `server`. */
+function bindFor(url: URL): { host: string; port: number; probe: string } {
+  const name = url.hostname.replace(/^\[(.*)\]$/, "$1")
+  const host = name === "localhost" ? "127.0.0.1" : name
+  const port = Number(url.port || 80)
+  return { host, port, probe: `http://${host.includes(":") ? `[${host}]` : host}:${port}` }
+}
+
+/**
+ * Makes sure a hub answers on the loopback `server`, starting one if nothing does and no other process
+ * is already starting it. Resolves once the hub answers, or with why it did not.
+ */
+export async function ensureLocalHub(server: string, options: LocalHubOptions = {}): Promise<LocalHubResult> {
+  if (!isLoopbackURL(server)) return { status: "skipped", reason: "not a loopback server" }
+  const url = new URL(server)
+  if (url.protocol !== "http:") return { status: "skipped", reason: "a local hub serves http only" }
+
+  const env = options.env ?? process.env
+  const doFetch = options.fetch ?? globalThis.fetch
+  const now = options.now ?? Date.now
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)))
+  const alive = options.isAlive ?? pidAlive
+  const home = options.home ?? homedir()
+  const stateDir = options.stateDir ?? defaultStateDir(env, home)
+  const lockFile = path.join(stateDir, "hub.pid")
+  const logFile = path.join(stateDir, "hub.log")
+  const bind = bindFor(url)
+
+  const answers = async (origin: string) => {
+    try {
+      await doFetch(`${origin}/healthz`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) })
+      return true // any HTTP answer: something listens there, so never start a second server
+    } catch {
+      return false
+    }
+  }
+
+  if (await answers(url.origin)) return { status: "running" }
+  const root = options.repoRoot ?? repoRoot()
+  if (!(options.webBuilt ?? hasWebBuild)(root)) return { status: "failed", error: WEB_NOT_BUILT }
+
+  if (options.stateDir === undefined && !hubEnv(env).HUB_STATE_DIR) {
+    migrateFirst(legacyPaths(stateBase(home)), stateDir, { skip: ["hub.pid"], ...(options.log ? { log: options.log } : {}) })
+  }
+  mkdirSync(stateDir, { recursive: true, mode: 0o700 })
+
+  // ---- the lock ----
+  const existing = readLock(lockFile)
+  if (existing === "unreadable") {
+    if (now() - statSync(lockFile).mtimeMs < LOCK_STALE_MS) return { status: "busy", pid: 0 }
+    removeLock(lockFile)
+  } else if (existing) {
+    if (alive(existing.pid)) {
+      if (existing.port !== bind.port && (await answers(`http://127.0.0.1:${existing.port}`))) {
+        return {
+          status: "failed",
+          error:
+            `A local hub (pid ${existing.pid}) already runs on port ${existing.port}. ` +
+            `Point /hub → Server at http://127.0.0.1:${existing.port}, or stop that hub first.`,
+        }
+      }
+      if (now() - existing.started < LOCK_STALE_MS) return { status: "busy", pid: existing.pid }
+    }
+    removeLock(lockFile)
+  }
+  const own = options.pid ?? process.pid
+  try {
+    writeFileSync(lockFile, JSON.stringify({ pid: own, port: bind.port, started: now() } satisfies Lock), { flag: "wx", mode: 0o600 })
+  } catch {
+    const holder = readLock(lockFile)
+    return { status: "busy", pid: holder && holder !== "unreadable" ? holder.pid : 0 }
+  }
+
+  // ---- start ----
+  let child: ChildLike
+  let exited: string | undefined
+  let log: number | undefined
+  try {
+    log = openSync(logFile, "a", 0o600)
+    chmodSync(logFile, 0o600)
+    const childEnv: Record<string, string> = {}
+    for (const [key, value] of Object.entries(env)) {
+      // The hub needs none of OpenCode's own settings or credentials.
+      if (value !== undefined && !key.startsWith("OPENCODE_")) childEnv[key] = value
+    }
+    const runtime = options.runtime ?? (options.bun ? { command: options.bun, env: {} } : currentHubRuntime(env))
+    delete childEnv.BUN_BE_BUN // only the runtime decides whether its executable acts as bun
+    // The address this hub must serve; legacy names would only lose to these and warn.
+    for (const legacy of ["VOICE_HOST", "VOICE_PORT", "VOICE_PUBLIC_URL"]) delete childEnv[legacy]
+    Object.assign(childEnv, runtime.env, { HUB_HOST: bind.host, HUB_PORT: String(bind.port), HUB_PUBLIC_URL: url.origin })
+    child = (options.spawn ?? (nodeSpawn as unknown as SpawnLike))(runtime.command, [hubScript(root)], {
+      cwd: root,
+      detached: true,
+      stdio: ["ignore", log, log],
+      env: childEnv,
+    })
+    child.on("error", (error) => {
+      exited = error.message
+    })
+    child.on("exit", (code, signal) => {
+      exited = `exited with ${signal ?? `code ${code}`}`
+    })
+    child.unref()
+  } catch (cause) {
+    removeLock(lockFile)
+    return { status: "failed", error: `Could not start the local hub: ${cause instanceof Error ? cause.message : cause}` }
+  } finally {
+    if (log !== undefined) closeSync(log)
+  }
+  const pid = child.pid ?? own
+  writeFileSync(lockFile, JSON.stringify({ pid, port: bind.port, started: now() } satisfies Lock), { mode: 0o600 })
+
+  // ---- wait until it answers ----
+  const deadline = now() + (options.waitMs ?? 15_000)
+  for (;;) {
+    if (exited !== undefined) {
+      const lock = readLock(lockFile)
+      if (lock && lock !== "unreadable" && lock.pid === pid) removeLock(lockFile)
+      return { status: "failed", error: `The local hub ${exited}; see ${logFile}` }
+    }
+    if (await answers(bind.probe)) return { status: "started", pid }
+    if (now() >= deadline) {
+      return { status: "failed", error: `The local hub (pid ${pid}) did not answer on ${bind.probe} yet; see ${logFile}` }
+    }
+    await sleep(POLL_MS)
+  }
+}
+
+function readLock(file: string): Lock | "unreadable" | undefined {
+  if (!existsSync(file)) return undefined
+  try {
+    const raw = JSON.parse(readFileSync(file, "utf8")) as Partial<Lock>
+    if (Number.isInteger(raw.pid) && Number.isInteger(raw.port) && typeof raw.started === "number") return raw as Lock
+  } catch {
+    // fall through
+  }
+  return "unreadable"
+}
+
+function removeLock(file: string): void {
+  try {
+    unlinkSync(file)
+  } catch {
+    // already gone
+  }
+}
+
+export interface HubRuntime {
+  readonly command: string
+  readonly env: Readonly<Record<string, string>>
+}
+
+export interface RuntimeProbe {
+  readonly execPath: string
+  readonly home: string
+  readonly isBun: boolean
+  readonly which: (name: string) => string | null
+  readonly exists: (file: string) => boolean
+}
+
+/**
+ * How to run bin/hub.ts: this runtime when it is bun, else bun on PATH, else ~/.bun/bin/bun, else this
+ * executable with BUN_BE_BUN=1 when it is a Bun runtime (inside OpenCode, process.execPath is the
+ * compiled `opencode` binary, which then runs scripts as bun), else plain `bun`.
+ */
+export function resolveHubRuntime(probe: RuntimeProbe): HubRuntime {
+  const base = probe.execPath.split(/[\\/]/).pop() ?? ""
+  if (/^bun(\.exe)?$/i.test(base)) return { command: probe.execPath, env: {} }
+  const found = probe.which("bun")
+  if (found) return { command: found, env: {} }
+  const home = path.join(probe.home, ".bun", "bin", "bun")
+  if (probe.exists(home)) return { command: home, env: {} }
+  if (probe.isBun) return { command: probe.execPath, env: { BUN_BE_BUN: "1" } }
+  return { command: "bun", env: {} }
+}

package/src/spoke/locations.ts

@@ -0,0 +1,34 @@
+// OpenCode keeps pending permission requests per location (the directory a session runs in), and the
+// plugin's ctx.permission only sees its own location. One plugin instance per location joins the
+// process (see singleton.ts), but only the first runs the spoke. So a reply has to go through the
+// instance of the location that holds the request.
+import type { PermissionDecision } from "../protocol"
+
+/** ctx.permission of one plugin instance, with its location's directory. */
+export interface PermissionLocation {
+  readonly directory: string
+  get(input: { sessionID: string; requestID: string }): Promise<unknown>
+  reply(input: { sessionID: string; requestID: string; decision: PermissionDecision }): Promise<unknown>
+}
+
+/**
+ * Replies to a pending permission through the location that holds it (the session's directory first).
+ * "gone" when no location has it pending (already answered, expired, or asked in another process).
+ */
+export async function replyPermission(
+  locations: readonly PermissionLocation[],
+  input: { sessionID: string; requestID: string; decision: PermissionDecision },
+  directory?: string,
+): Promise<"replied" | "gone"> {
+  const ordered = [...locations.filter((l) => l.directory === directory), ...locations.filter((l) => l.directory !== directory)]
+  for (const location of ordered) {
+    try {
+      await location.get({ sessionID: input.sessionID, requestID: input.requestID })
+    } catch {
+      continue // not pending in this location
+    }
+    await location.reply(input)
+    return "replied"
+  }
+  return "gone"
+}

package/src/spoke/own-server.ts

@@ -0,0 +1,32 @@
+// Reaching this process's own OpenCode server over HTTP, for what the plugin API does not offer (answering
+// forms). The background service is found with Service.discover; a foreground `opencode serve` from its
+// command line and password variable. A standalone server started by a TUI (`serve --stdio --port 0`)
+// keeps its password to itself: its forms are relayed through the TUI instead (Spoke.formActions).
+
+/** URL and Authorization header of a foreground `opencode serve` this process is, when knowable. */
+export function foregroundEndpoint(
+  argv: readonly string[],
+  env: Readonly<Record<string, string | undefined>>,
+): { url: string; authorization: string } | undefined {
+  if (!argv.includes("serve") || argv.includes("--stdio") || argv.includes("--service")) return undefined
+  const option = (name: string) => {
+    const index = argv.indexOf(name)
+    if (index >= 0) return argv[index + 1]
+    return argv.find((a) => a.startsWith(`${name}=`))?.slice(name.length + 1)
+  }
+  const port = Number(option("--port"))
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return undefined
+  const password = env.OPENCODE_PASSWORD || env.OPENCODE_SERVER_PASSWORD
+  if (!password) return undefined
+  const host = option("--hostname")
+  const reachable = !host || host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host.includes(":") ? `[${host}]` : host
+  return { url: `http://${reachable}:${port}`, authorization: `Basic ${btoa(`opencode:${password}`)}` }
+}
+
+/** "gone" for OpenCode's form-not-found / already-settled errors; undefined for anything else. */
+export function formOutcome(cause: unknown): "gone" | undefined {
+  const tag = (cause as { _tag?: unknown } | null)?._tag
+  if (tag === "FormNotFoundError" || tag === "FormAlreadySettledError") return "gone"
+  const message = cause instanceof Error ? cause.message : String(cause)
+  return /form (not found|already settled)/i.test(message) ? "gone" : undefined
+}

package/src/spoke/presence.ts

@@ -0,0 +1,45 @@
+// TUI presence on the spoke: which sessions an OpenCode TUI shows (its route and open tabs), reported over
+// RPC voice.presence on change and every 15 s. A session is open while some TUI reported it within the
+// window. Each TUI's report replaces its previous one, so a closed tab stops counting at once.
+export const TUI_PRESENCE_WINDOW_MS = 45_000
+/** Sessions taken from one report, and TUIs remembered. */
+const REPORT_MAX = 200
+const REPORTERS_MAX = 100
+const SESSION_ID = /^ses[A-Za-z0-9_-]{1,200}$/
+
+export class PresenceBook {
+  /** reporter → its sessions and when it reported them. Anonymous reports keep a time per session. */
+  private readonly byReporter = new Map<string, { at: number; sessions: Set<string> }>()
+  private readonly anonymous = new Map<string, number>()
+
+  report(sessionIDs: readonly string[], now: number, reporter?: string): void {
+    const ids = [...new Set(sessionIDs.filter((id) => typeof id === "string" && SESSION_ID.test(id)))].slice(0, REPORT_MAX)
+    if (!reporter) {
+      for (const id of ids) this.anonymous.set(id, now)
+      this.prune(now)
+      return
+    }
+    this.byReporter.delete(reporter)
+    this.byReporter.set(reporter, { at: now, sessions: new Set(ids) })
+    this.prune(now)
+  }
+
+  /** Sessions some TUI reported within the window. */
+  open(now: number): Set<string> {
+    const out = new Set<string>()
+    for (const { at, sessions } of this.byReporter.values()) if (now - at < TUI_PRESENCE_WINDOW_MS) for (const id of sessions) out.add(id)
+    for (const [id, at] of this.anonymous) if (now - at < TUI_PRESENCE_WINDOW_MS) out.add(id)
+    return out
+  }
+
+  reporters(): number {
+    return this.byReporter.size
+  }
+
+  private prune(now: number): void {
+    for (const [key, entry] of this.byReporter) if (now - entry.at >= TUI_PRESENCE_WINDOW_MS) this.byReporter.delete(key)
+    while (this.byReporter.size > REPORTERS_MAX) this.byReporter.delete(this.byReporter.keys().next().value!)
+    for (const [id, at] of this.anonymous) if (now - at >= TUI_PRESENCE_WINDOW_MS) this.anonymous.delete(id)
+    while (this.anonymous.size > REPORT_MAX) this.anonymous.delete(this.anonymous.keys().next().value!)
+  }
+}

package/src/spoke/singleton.ts

@@ -0,0 +1,103 @@
+// Exactly one active spoke per OpenCode process. Every plugin instance in the process (one per
+// location, plus reloads) joins a registry on globalThis; the first one creates the spoke, the
+// others stay passive and delegate to it. When the active instance is disposed, the next
+// instance takes over with its own factory, so a reloaded module replaces stale code.
+import { randomBytes } from "node:crypto"
+
+export interface Startable {
+  start(): void
+  stop(): void
+}
+
+interface Instance {
+  readonly id: symbol
+  readonly create: (processID: string) => Startable
+  /** Per-instance value (e.g. the instance's location-scoped API), see Membership.locals. */
+  readonly local?: unknown
+}
+
+interface Registry {
+  pid: number
+  processID: string
+  instances: Instance[]
+  spoke?: Startable
+  owner?: symbol
+}
+
+export interface Membership<S> {
+  readonly processID: string
+  active(): S | undefined
+  isActive(): boolean
+  /** The local values of every instance in the process (the active one first). */
+  locals<L = unknown>(): L[]
+  leave(): void
+}
+
+// Kept from opencode-voice so a process that loads both the old and the renamed package runs one spoke.
+export const SPOKE_KEY = Symbol.for("opencode-voice.spoke")
+
+function registry(key: symbol): Registry {
+  const store = globalThis as Record<symbol, Registry | undefined>
+  let reg = store[key]
+  if (!reg || reg.pid !== process.pid || !Array.isArray(reg.instances)) {
+    reg = { pid: process.pid, processID: `proc_${randomBytes(8).toString("hex")}`, instances: [] }
+    store[key] = reg
+  }
+  return reg
+}
+
+function promote(reg: Registry): void {
+  for (const instance of reg.instances) {
+    try {
+      const spoke = instance.create(reg.processID)
+      spoke.start()
+      reg.spoke = spoke
+      reg.owner = instance.id
+      return
+    } catch (cause) {
+      console.error("[hub] could not start the hub spoke", cause)
+    }
+  }
+  reg.spoke = undefined
+  reg.owner = undefined
+}
+
+/** `create` receives the stable per-process ID; `local` is this instance's value for Membership.locals. */
+export function joinProcess<S extends Startable>(create: (processID: string) => S, key: symbol = SPOKE_KEY, local?: unknown): Membership<S> {
+  const reg = registry(key)
+  const id = Symbol("hub.instance")
+  reg.instances.push({ id, create, ...(local !== undefined ? { local } : {}) })
+  if (!reg.spoke) {
+    try {
+      const spoke = create(reg.processID)
+      spoke.start()
+      reg.spoke = spoke
+      reg.owner = id
+    } catch (cause) {
+      console.error("[hub] could not start the hub spoke", cause)
+    }
+  }
+  return {
+    processID: reg.processID,
+    active: () => registry(key).spoke as S | undefined,
+    isActive: () => registry(key).owner === id,
+    locals: <L>() => {
+      const current = registry(key)
+      const ordered = [...current.instances].sort((a, b) => Number(b.id === current.owner) - Number(a.id === current.owner))
+      return ordered.flatMap((i) => (i.local === undefined ? [] : [i.local as L]))
+    },
+    leave: () => {
+      const current = registry(key)
+      const index = current.instances.findIndex((i) => i.id === id)
+      if (index === -1) return
+      current.instances.splice(index, 1)
+      if (current.owner !== id) return
+      try {
+        current.spoke?.stop()
+      } catch (cause) {
+        console.error("[hub] spoke stop failed", cause)
+      }
+      promote(current)
+    },
+  }
+}