@briancray/belte 0.1.0

package/src/lib/browser/subscribe.ts

@@ -0,0 +1,131 @@
+import { createSubscriber } from 'svelte/reactivity'
+import type { Subscribable } from '../shared/types/Subscribable.ts'
+
+type SubscriptionStatus = 'pending' | 'open' | 'done' | 'error'
+
+type Entry<T> = {
+    latest: T | undefined
+    error: Error | undefined
+    status: SubscriptionStatus
+    tap: () => void
+}
+
+const registry = new Map<string, Entry<unknown>>()
+
+/*
+Reactive consumer for streaming sources. Takes a Subscribable<T> — the
+shape both `Socket<T>` (declared under src/server/sockets/) and the result of
+`fn.stream(args)` satisfy:
+
+  const latest = $derived(subscribe(chat))                  // socket
+  const latest = $derived(subscribe(tickFeed.stream()))     // rpc stream (no args)
+  const latest = $derived(subscribe(countLog.stream({ to: 5 })))  // rpc stream
+
+Lifecycle mirrors cache(): the entry's tracker is a Svelte
+createSubscriber, so the first $derived read in a tracking scope opens
+the underlying iterator (with history replay on a Socket, or a fresh
+fetch on an rpc stream), and the last $derived to stop reading closes
+it. Many $deriveds reading the same source share one underlying
+subscription — the registry dedupes by `subscribable.name`, which is
+the socket name for declared sockets and `keyForRemoteCall(method, url,
+args)` for rpc streams. So passing fresh `fn.stream(args)` Subscribables
+across re-renders is safe: same args → same key → shared subscription.
+
+Subscribe is a no-op on the server (returns undefined) — SSR can't
+keep a stream open across the request boundary. Pages that want a
+seeded value in the initial HTML should fetch via cache() against an
+HTTP rpc handler and layer subscribe() on top for live updates after
+hydration.
+
+Errors are surfaced through subscribe.error(x) rather than thrown, so
+reading `latest` from a $derived can't crash the component. Status
+distinguishes "haven't received the first frame" (pending) from
+"stream ended cleanly" (done) and "wire layer surfaced an error"
+(error).
+*/
+export function subscribe<T>(subscribable: Subscribable<T>): T | undefined {
+    return readField(subscribable, 'latest') as T | undefined
+}
+
+subscribe.error = function subscribeError<T>(subscribable: Subscribable<T>): Error | undefined {
+    return readField(subscribable, 'error') as Error | undefined
+}
+
+subscribe.status = function subscribeStatus<T>(subscribable: Subscribable<T>): SubscriptionStatus {
+    return (readField(subscribable, 'status') as SubscriptionStatus | undefined) ?? 'pending'
+}
+
+function readField<T, K extends keyof Entry<T>>(
+    subscribable: Subscribable<T>,
+    field: K,
+): Entry<T>[K] | undefined {
+    if (typeof window === 'undefined') {
+        if (field === 'status') {
+            return 'pending' as Entry<T>[K]
+        }
+        return undefined
+    }
+    const entry = getOrCreateEntry(subscribable) as Entry<T>
+    entry.tap()
+    return entry[field]
+}
+
+function getOrCreateEntry<T>(subscribable: Subscribable<T>): Entry<T> {
+    const key = subscribable.name
+    const cached = registry.get(key) as Entry<T> | undefined
+    if (cached) {
+        return cached
+    }
+    const entry: Entry<T> = {
+        latest: undefined,
+        error: undefined,
+        status: 'pending',
+        tap: () => undefined,
+    }
+    entry.tap = createSubscriber((update) => {
+        entry.latest = undefined
+        entry.error = undefined
+        entry.status = 'pending'
+        const iterator = subscribable[Symbol.asyncIterator]()
+        let cancelled = false
+        ;(async () => {
+            try {
+                while (!cancelled) {
+                    const next = await iterator.next()
+                    if (next.done) {
+                        if (!cancelled) {
+                            if (entry.status !== 'error') {
+                                entry.status = 'done'
+                            }
+                            update()
+                        }
+                        return
+                    }
+                    entry.latest = next.value
+                    entry.status = 'open'
+                    update()
+                }
+            } catch (error) {
+                if (!cancelled) {
+                    entry.error = error instanceof Error ? error : new Error(String(error))
+                    entry.status = 'error'
+                    update()
+                }
+            }
+        })()
+        return () => {
+            cancelled = true
+            iterator.return?.(undefined)?.catch(() => undefined)
+            /*
+            Identity-guard the eviction: if a fresh Subscribable with the
+            same name has already replaced us in the registry, this stale
+            cleanup must not nuke the new entry.
+            */
+            if (registry.get(key) === (entry as Entry<unknown>)) {
+                registry.delete(key)
+            }
+        }
+    })
+    registry.set(key, entry as Entry<unknown>)
+    return entry
+}

package/src/lib/browser/types/Layouts.ts

@@ -0,0 +1,7 @@
+import type { Component } from 'svelte'
+
+/*
+Manifest of directory prefix → layout.svelte module loader. The deepest
+prefix that is an ancestor of a route wins (no stacking).
+*/
+export type Layouts = Record<string, () => Promise<{ default: Component }>>

package/src/lib/browser/types/Pages.ts

@@ -0,0 +1,7 @@
+import type { Component } from 'svelte'
+
+/*
+Manifest of route URL → page.svelte module loader. Produced by the resolver
+plugin from `page.svelte` files anywhere under src/routes.
+*/
+export type Pages = Record<string, () => Promise<{ default: Component }>>

package/src/lib/cli/createClient.ts

@@ -0,0 +1,126 @@
+import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+import { verbRegistry } from '../server/rpc/verbRegistry.ts'
+import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
+import { commandNameForUrl } from '../shared/commandNameForUrl.ts'
+import { decodeResponse } from '../shared/decodeResponse.ts'
+import type { CliManifest } from './types/CliManifest.ts'
+import type { CliManifestEntry } from './types/CliManifestEntry.ts'
+
+type AnyApi = Record<string, (args?: unknown) => Promise<unknown>>
+
+/*
+Builds a typed proxy over the project's RPCs for use in scripts, tests,
+server-to-server calls, and the standalone CLI binary. Modes are
+decided at construction:
+
+  - With `url`: remote-mode. Each property access becomes an HTTP call
+    against `<url>/<manifest[name].url>` using the manifest's method.
+    Auth header is set from `token` when provided.
+  - Without `url`: in-process mode. Each property access looks up the
+    verb in the registry (populated by importing the project's rpc
+    modules) and calls `verb.fetch(synthesizedRequest)` — same code
+    path the HTTP router uses, no network hop.
+
+The `manifest` is the bundler-emitted CLI manifest baked into the thin
+binary. In in-process mode it's optional (registry is the source of
+truth). Both can be supplied to support a binary that talks remote by
+default but falls back to in-process when APP_URL is unset.
+*/
+export function createClient<Api extends AnyApi = AnyApi>(opts?: {
+    url?: string
+    token?: string
+    manifest?: CliManifest
+}): Api {
+    const url = opts?.url
+    const token = opts?.token
+    const manifest = opts?.manifest
+
+    /*
+    Look up method + url for a given name. Manifest wins (the binary's
+    baked-in source of truth); registry is the in-process fallback for
+    use in same-project code where defineVerb has run.
+    */
+    function resolve(name: string): { method: HttpVerb; url: string } | undefined {
+        const entry = manifest?.[name]
+        if (entry) {
+            return { method: entry.method, url: entry.url }
+        }
+        for (const value of verbRegistry.values()) {
+            if (commandNameForUrl(value.remote.url) === name) {
+                return { method: value.remote.method, url: value.remote.url }
+            }
+        }
+        return undefined
+    }
+
+    async function callRemote(
+        method: HttpVerb,
+        path: string,
+        args: unknown,
+        baseUrl: string,
+    ): Promise<unknown> {
+        const headers = new Headers()
+        if (token) {
+            headers.set('authorization', `Bearer ${token}`)
+        }
+        const request = buildRpcRequest({ method, url: path, args, baseUrl, headers })
+        const response = await fetch(request)
+        if (!response.ok) {
+            throw new Error(`${method} ${path} failed: ${response.status} ${response.statusText}`)
+        }
+        return decodeResponse(response)
+    }
+
+    async function callInProcess(method: HttpVerb, path: string, args: unknown): Promise<unknown> {
+        const entry = verbRegistry.get(path)
+        if (!entry) {
+            throw new Error(
+                `RPC ${path} not loaded — import the module first or set APP_URL to use remote mode`,
+            )
+        }
+        const headers = new Headers()
+        if (token) {
+            headers.set('authorization', `Bearer ${token}`)
+        }
+        const request = buildRpcRequest({
+            method,
+            url: path,
+            args,
+            baseUrl: 'http://localhost/',
+            headers,
+        })
+        const response = await entry.remote.fetch(request)
+        if (!response.ok) {
+            throw new Error(`${method} ${path} failed: ${response.status} ${response.statusText}`)
+        }
+        return decodeResponse(response)
+    }
+
+    /*
+    Memoise per-name so repeated `client.foo` accesses skip both the
+    registry scan in resolve() and a fresh closure allocation. The
+    manifest + registry are fixed for a client's lifetime, so a resolved
+    invoker (or its absence) never changes.
+    */
+    const invokerCache = new Map<string, ((args?: unknown) => Promise<unknown>) | undefined>()
+
+    return new Proxy({} as Api, {
+        get(_target, prop): ((args?: unknown) => Promise<unknown>) | undefined {
+            if (typeof prop !== 'string') {
+                return undefined
+            }
+            if (invokerCache.has(prop)) {
+                return invokerCache.get(prop)
+            }
+            const resolved = resolve(prop)
+            const invoker = resolved
+                ? (args?: unknown) =>
+                      url
+                          ? callRemote(resolved.method, resolved.url, args, url)
+                          : callInProcess(resolved.method, resolved.url, args)
+                : undefined
+            invokerCache.set(prop, invoker)
+            return invoker
+        },
+    })
+}

package/src/lib/cli/loadEnvFromBinaryDir.ts

@@ -0,0 +1,44 @@
+import { existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const ENV_LINE = /^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/
+
+/*
+Reads a `.env` next to the running binary (resolved via
+`process.execPath`) and merges each declared var into `process.env`
+only when not already set. The binary-dir `.env` is the file the
+install tarball ships next to the executable; per-shell exports and
+Bun's automatic CWD `.env` loading both naturally override it.
+
+Strips surrounding single or double quotes off values; otherwise the
+parser is intentionally minimal — no variable expansion, no escape
+handling, no multi-line. Matches what the install tarball writes.
+*/
+export async function loadEnvFromBinaryDir(): Promise<void> {
+    const binDir = dirname(process.execPath)
+    const envPath = `${binDir}/.env`
+    if (!existsSync(envPath)) {
+        return
+    }
+    const text = await Bun.file(envPath).text()
+    for (const line of text.split('\n')) {
+        if (!line || line.startsWith('#')) {
+            continue
+        }
+        const match = ENV_LINE.exec(line)
+        if (!match) {
+            continue
+        }
+        const [, key, rawValue] = match
+        if (process.env[key as string] !== undefined) {
+            continue
+        }
+        const trimmed = rawValue?.trim() ?? ''
+        const unquoted =
+            (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'"))
+                ? trimmed.slice(1, -1)
+                : trimmed
+        process.env[key as string] = unquoted
+    }
+}

package/src/lib/cli/parseArgvForRpc.ts

@@ -0,0 +1,97 @@
+/*
+Parses an argv tail into the JSON args bag for an RPC. The JSON Schema
+on the manifest entry (when present) drives flag typing:
+  - properties whose type is "boolean" accept `--name` / `--no-name`
+  - properties whose type is "number" / "integer" accept `--name <n>` and
+    coerce with Number()
+  - properties whose type is "array" accept repeated `--name <v>`
+  - anything else accepts `--name <value>` as a string
+
+For complex shapes (nested objects, unions, anyOf) the CLI exposes
+`--json <stringified-args>` as an escape hatch that supplies the whole
+args bag verbatim. Stdin: if a JSON object arrives piped in, it's used
+as the full args bag (flags layer on top).
+
+Unrecognised flags throw — early loud feedback is more useful than
+silent drops.
+*/
+export async function parseArgvForRpc(
+    argv: string[],
+    jsonSchema: Record<string, unknown> | undefined,
+): Promise<Record<string, unknown> | undefined> {
+    const properties =
+        (jsonSchema?.properties as Record<string, { type?: string }> | undefined) ?? {}
+    const args: Record<string, unknown> = {}
+
+    /*
+    Stdin override: if a JSON object is piped in, treat it as the
+    starting args bag. `Bun.stdin.text()` reads the whole pipe; if
+    nothing was piped, the read resolves with an empty string.
+    */
+    if (!process.stdin.isTTY) {
+        const text = await Bun.stdin.text()
+        if (text.trim()) {
+            try {
+                const piped = JSON.parse(text)
+                if (piped && typeof piped === 'object' && !Array.isArray(piped)) {
+                    Object.assign(args, piped)
+                }
+            } catch {
+                throw new Error(`stdin is not a valid JSON object: ${text.slice(0, 80)}…`)
+            }
+        }
+    }
+
+    for (let index = 0; index < argv.length; index++) {
+        const token = argv[index] as string
+        if (token === '--json') {
+            const next = argv[++index]
+            if (!next) {
+                throw new Error('--json requires a value')
+            }
+            const parsed = JSON.parse(next)
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                throw new Error('--json value must be a JSON object')
+            }
+            Object.assign(args, parsed)
+            continue
+        }
+        if (!token.startsWith('--')) {
+            throw new Error(`unexpected positional argument: ${token}`)
+        }
+        const isNegated = token.startsWith('--no-')
+        const rawName = isNegated ? token.slice('--no-'.length) : token.slice('--'.length)
+        const [name, eqValue] = rawName.includes('=')
+            ? [rawName.slice(0, rawName.indexOf('=')), rawName.slice(rawName.indexOf('=') + 1)]
+            : [rawName, undefined]
+        const prop = properties[name]
+        const propType = prop?.type
+        if (propType === 'boolean') {
+            args[name] = !isNegated
+            continue
+        }
+        if (isNegated) {
+            throw new Error(`--no-${name} is only valid on boolean flags`)
+        }
+        const value = eqValue ?? argv[++index]
+        if (value === undefined) {
+            throw new Error(`--${name} requires a value`)
+        }
+        if (propType === 'number' || propType === 'integer') {
+            const n = Number(value)
+            if (Number.isNaN(n)) {
+                throw new Error(`--${name} expects a number, got ${value}`)
+            }
+            args[name] = n
+            continue
+        }
+        if (propType === 'array') {
+            const existing = args[name]
+            args[name] = Array.isArray(existing) ? [...existing, value] : [value]
+            continue
+        }
+        args[name] = value
+    }
+
+    return Object.keys(args).length === 0 ? undefined : args
+}

package/src/lib/cli/printHelp.ts

@@ -0,0 +1,70 @@
+import type { CliManifest } from './types/CliManifest.ts'
+
+/*
+Top-level help (no subcommand) lists every available command with a
+one-line summary. Per-command help (`<cmd> --help`) prints the flags
+derived from the command's JSON Schema. Output goes to stdout in both
+cases; the caller exits zero after printing.
+*/
+export function printTopLevelHelp(
+    programName: string,
+    manifest: CliManifest,
+    banner = '',
+    footer = '',
+): void {
+    if (banner.trim()) {
+        console.log(banner.replace(/\n$/, ''))
+        console.log('')
+    }
+    const names = Object.keys(manifest).toSorted()
+    console.log(`usage: ${programName} <command> [--flags]\n`)
+    console.log('commands:')
+    for (const name of names) {
+        const entry = manifest[name]
+        if (!entry) {
+            continue
+        }
+        console.log(`  ${name.padEnd(20)} ${entry.method} ${entry.url}`)
+    }
+    console.log(`\n  --help, -h           show this help`)
+    console.log(`  <command> --help     show help for a specific command`)
+    console.log(`\nenv:`)
+    console.log(`  APP_URL              remote server URL (unset → in-process)`)
+    console.log(`  APP_TOKEN            sent as Authorization: Bearer <value>`)
+    if (footer.trim()) {
+        console.log('')
+        console.log(footer.replace(/\n$/, ''))
+    }
+}
+
+export function printCommandHelp(programName: string, name: string, manifest: CliManifest): void {
+    const entry = manifest[name]
+    if (!entry) {
+        console.log(`unknown command: ${name}`)
+        return
+    }
+    console.log(`usage: ${programName} ${name} [--flags]\n`)
+    console.log(`  ${entry.method} ${entry.url}\n`)
+    const schema = entry.jsonSchema
+    const properties =
+        (schema?.properties as
+            | Record<string, { type?: string; description?: string }>
+            | undefined) ?? {}
+    const required = new Set((schema?.required as string[] | undefined) ?? [])
+    if (Object.keys(properties).length === 0) {
+        console.log('flags: (none)')
+    } else {
+        console.log('flags:')
+        for (const [key, value] of Object.entries(properties)) {
+            const tag =
+                value.type === 'boolean'
+                    ? `--${key} / --no-${key}`
+                    : `--${key} <${value.type ?? 'value'}>`
+            const requiredTag = required.has(key) ? ' (required)' : ''
+            const description = value.description ? ` — ${value.description}` : ''
+            console.log(`  ${tag.padEnd(28)}${requiredTag}${description}`)
+        }
+    }
+    console.log('\n  --json <object>          full args bag as JSON (overrides flags)')
+    console.log('  (stdin)                  pipe a JSON object as the args bag')
+}

package/src/lib/cli/runCli.ts

@@ -0,0 +1,88 @@
+import { createClient } from './createClient.ts'
+import { loadEnvFromBinaryDir } from './loadEnvFromBinaryDir.ts'
+import { parseArgvForRpc } from './parseArgvForRpc.ts'
+import { printCommandHelp, printTopLevelHelp } from './printHelp.ts'
+import type { CliManifest } from './types/CliManifest.ts'
+
+/*
+Top-level CLI driver. Loaded by the standalone binary's entry; expects
+the bundler-emitted manifest plus the raw argv tail. Flow:
+
+  1. Read .env next to the binary so APP_URL / APP_TOKEN are picked up
+     for the common install-tarball case.
+  2. Pull the first positional as the subcommand.
+  3. --help and `<cmd> --help` print and exit zero.
+  4. Otherwise parse the rest of the argv against the manifest entry's
+     JSON Schema and dispatch via createClient.
+
+Streaming responses aren't a thing at this layer yet — every RPC tool
+goes through decodeResponse (text/JSON). Streaming verbs (jsonl/sse)
+will be added when the CLI grows watch/publish subcommands for sockets.
+*/
+export async function runCli({
+    programName,
+    manifest,
+    banner = '',
+    footer = '',
+    argv,
+}: {
+    programName: string
+    manifest: CliManifest
+    banner?: string
+    footer?: string
+    argv: string[]
+}): Promise<number> {
+    await loadEnvFromBinaryDir()
+
+    const first = argv[0]
+    if (!first || first === '--help' || first === '-h') {
+        printTopLevelHelp(programName, manifest, banner, footer)
+        return 0
+    }
+
+    if (argv.includes('--help') || argv.includes('-h')) {
+        printCommandHelp(programName, first, manifest)
+        return 0
+    }
+
+    const entry = manifest[first]
+    if (!entry) {
+        console.error(
+            `${programName}: unknown command "${first}" — run \`${programName} --help\` for the list`,
+        )
+        return 1
+    }
+
+    let args: Record<string, unknown> | undefined
+    try {
+        args = await parseArgvForRpc(argv.slice(1), entry.jsonSchema)
+    } catch (error) {
+        console.error(`${programName}: ${error instanceof Error ? error.message : String(error)}`)
+        return 1
+    }
+
+    const appUrl = process.env.APP_URL
+    const appToken = process.env.APP_TOKEN
+    const client = createClient({ url: appUrl, token: appToken, manifest })
+
+    try {
+        const fn = (client as Record<string, (args?: unknown) => Promise<unknown>>)[first]
+        if (!fn) {
+            console.error(`${programName}: command "${first}" not in client`)
+            return 1
+        }
+        const result = await fn(args)
+        if (typeof result === 'string') {
+            process.stdout.write(result)
+            if (!result.endsWith('\n')) {
+                process.stdout.write('\n')
+            }
+        } else if (result !== undefined) {
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+        }
+        return 0
+    } catch (error) {
+        console.error(`${programName}: ${error instanceof Error ? error.message : String(error)}`)
+        return 1
+    }
+}

package/src/lib/cli/types/CliManifest.ts

@@ -0,0 +1,9 @@
+import type { CliManifestEntry } from './CliManifestEntry.ts'
+
+/*
+Map from rpc export-name (e.g. "getReport") to its manifest entry. Built
+by the bundler from the same verbRegistry MCP consumes; entries are
+emitted only for rpcs with `clients.cli: true`. The CLI binary and any
+programmatic createClient caller read this to dispatch calls.
+*/
+export type CliManifest = Record<string, CliManifestEntry>

package/src/lib/cli/types/CliManifestEntry.ts

@@ -0,0 +1,12 @@
+import type { HttpVerb } from '../../server/rpc/types/HttpVerb.ts'
+
+/*
+Per-RPC manifest entry baked into the standalone CLI binary by the
+bundler. Carries enough info to make the right HTTP request without
+importing the handler module (which the thin build doesn't ship).
+*/
+export type CliManifestEntry = {
+    method: HttpVerb
+    url: string
+    jsonSchema?: Record<string, unknown>
+}