@belte/belte 0.19.0

package/src/lib/cli/createClient.ts

@@ -0,0 +1,170 @@
+import { dispatchVerbInProcess } from '../server/rpc/dispatchVerbInProcess.ts'
+import { findVerbByCommandName } from '../server/rpc/findVerbByCommandName.ts'
+import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
+import { decodeResponse } from '../shared/decodeResponse.ts'
+import type { HttpVerb } from '../shared/types/HttpVerb.ts'
+import type { CliManifest } from './types/CliManifest.ts'
+
+/*
+Each property of the client is a callable: invoking it decodes the body
+(plain call), while `.raw(args)` returns the underlying Response without
+decoding or throwing on non-2xx — the escape hatch the CLI uses to sniff
+the Content-Type and stream sse/jsonl bodies frame-by-frame instead of
+buffering through decodeResponse.
+*/
+type ClientInvoker = ((args?: unknown) => Promise<unknown>) & {
+    raw: (args?: unknown) => Promise<Response>
+}
+
+type AnyApi = Record<string, ClientInvoker>
+
+/*
+A command resolved to its raw-dispatch closure. `method`/`url` label the
+command for error messages; `send` issues one call — over the network in
+remote mode, through dispatchVerbInProcess in in-process mode.
+*/
+type ResolvedSend = {
+    method: HttpVerb
+    url: string
+    send: (args: unknown) => Promise<Response>
+}
+
+/*
+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); in remote mode it supplies the method + url per command without
+needing the rpc modules loaded. The mode is chosen solely by whether
+`url` is set — the shipped CLI binary (see runCli) always passes `url`,
+so it runs remote-only; in-process mode is for same-project scripts and
+tests that import this directly without a `url`.
+*/
+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
+
+    // Auth + content-negotiation headers both dispatch modes attach.
+    function requestHeaders(accept?: string): Headers {
+        const headers = new Headers()
+        if (token) {
+            headers.set('authorization', `Bearer ${token}`)
+        }
+        if (accept) {
+            headers.set('accept', accept)
+        }
+        return headers
+    }
+
+    /*
+    Resolves a command name to its dispatch closure, or undefined when the
+    name is unknown in the active mode. Remote mode (url set) resolves
+    method + url from the baked manifest — registry fallback for same-project
+    callers — and sends the synthesized Request over the network. In-process
+    mode resolves the verb from the registry and routes through
+    dispatchVerbInProcess, the same synthesize-and-fetch the MCP dispatcher
+    uses, so the two consumer surfaces can't drift on how a verb is invoked.
+    */
+    function resolve(name: string): ResolvedSend | undefined {
+        if (url) {
+            const command = manifest?.[name] ?? registryCommand(name)
+            if (!command) {
+                return undefined
+            }
+            return {
+                method: command.method,
+                url: command.url,
+                send: (args) =>
+                    fetch(
+                        buildRpcRequest({
+                            method: command.method,
+                            url: command.url,
+                            args,
+                            baseUrl: url,
+                            headers: requestHeaders(command.accept),
+                        }),
+                    ),
+            }
+        }
+        const entry = findVerbByCommandName(name)
+        if (!entry) {
+            return undefined
+        }
+        return {
+            method: entry.remote.method,
+            url: entry.remote.url,
+            send: (args) =>
+                dispatchVerbInProcess({
+                    entry,
+                    args,
+                    baseUrl: 'http://localhost/',
+                    headers: requestHeaders(),
+                }),
+        }
+    }
+
+    // Remote-mode registry fallback for callers passing a url but no manifest.
+    function registryCommand(
+        name: string,
+    ): { method: HttpVerb; url: string; accept?: string } | undefined {
+        const found = findVerbByCommandName(name)
+        return found ? { method: found.remote.method, url: found.remote.url } : undefined
+    }
+
+    /*
+    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, ClientInvoker | undefined>()
+
+    /*
+    Build a memoised invoker for a resolved command. The plain call and
+    `.raw` share one `send`, so they can't diverge on URL/headers — the
+    plain call just decodes the body and throws on non-2xx on the way out.
+    */
+    function buildInvoker(resolved: ResolvedSend): ClientInvoker {
+        const invoker = (async (args?: unknown) => {
+            const response = await resolved.send(args)
+            if (!response.ok) {
+                throw new Error(
+                    `${resolved.method} ${resolved.url} failed: ${response.status} ${response.statusText}`,
+                )
+            }
+            return decodeResponse(response)
+        }) as ClientInvoker
+        invoker.raw = (args?: unknown) => resolved.send(args)
+        return invoker
+    }
+
+    return new Proxy({} as Api, {
+        get(_target, prop): ClientInvoker | undefined {
+            if (typeof prop !== 'string') {
+                return undefined
+            }
+            if (invokerCache.has(prop)) {
+                return invokerCache.get(prop)
+            }
+            const resolved = resolve(prop)
+            const invoker = resolved ? buildInvoker(resolved) : undefined
+            invokerCache.set(prop, invoker)
+            return invoker
+        },
+    })
+}

package/src/lib/cli/dispatchCommand.ts

@@ -0,0 +1,71 @@
+import { decodeResponse } from '../shared/decodeResponse.ts'
+import { isStreamingResponse } from '../shared/isStreamingResponse.ts'
+import { responseErrorText } from '../shared/responseErrorText.ts'
+import { streamResponse } from '../shared/streamResponse.ts'
+import { createClient } from './createClient.ts'
+import { parseArgvForRpc } from './parseArgvForRpc.ts'
+import { printValue } from './printValue.ts'
+import type { CliManifest } from './types/CliManifest.ts'
+
+/*
+Runs one RPC command against a target server and prints the result, returning a
+process exit code. Shared by the one-shot path (runCli) and the interactive
+session (runSession) so a command behaves identically typed at the shell or at
+the session prompt. Streaming responses (sse/jsonl — a streaming verb or a socket
+`tail`) print frame-by-frame as NDJSON; everything else decodes and prints once.
+*/
+export async function dispatchCommand({
+    programName,
+    manifest,
+    command,
+    argvTail,
+    url,
+    token,
+}: {
+    programName: string
+    manifest: CliManifest
+    command: string
+    argvTail: string[]
+    url: string
+    token?: string
+}): Promise<number> {
+    const entry = manifest[command]
+    if (!entry) {
+        console.error(
+            `${programName}: unknown command "${command}" — run \`${programName} --help\` for the list`,
+        )
+        return 1
+    }
+
+    let args: Record<string, unknown> | undefined
+    try {
+        args = await parseArgvForRpc(argvTail, entry.jsonSchema)
+    } catch (error) {
+        console.error(`${programName}: ${error instanceof Error ? error.message : String(error)}`)
+        return 1
+    }
+
+    const client = createClient({ url, token, manifest })
+    const fn = client[command]
+    if (!fn) {
+        console.error(`${programName}: command "${command}" not in client`)
+        return 1
+    }
+    try {
+        const response = await fn.raw(args)
+        if (isStreamingResponse(response)) {
+            for await (const frame of streamResponse(response)) {
+                printValue(frame, false)
+            }
+            return 0
+        }
+        if (!response.ok) {
+            throw new Error(await responseErrorText(response))
+        }
+        printValue(await decodeResponse(response), true)
+        return 0
+    } catch (error) {
+        console.error(`${programName}: ${error instanceof Error ? error.message : String(error)}`)
+        return 1
+    }
+}

package/src/lib/cli/loadEnvFromBinaryDir.ts

@@ -0,0 +1,16 @@
+import { dirname } from 'node:path'
+import { bundleLayout } from '../shared/bundleLayout.ts'
+import { loadEnvFile } from '../shared/loadEnvFile.ts'
+
+/*
+Loads the bundle's shipped `.env` into `process.env`, resolved from the running
+binary's directory (`process.execPath`) via bundleLayout — beside the binary in
+the flat layout, under `Contents/Resources` in a macOS `.app`. This is the file the
+install tarball ships beside the executable — and, for a bundle, the one `bundleApp`
+copies from the project's `bundle.env`. It carries the app's shipped defaults; the
+fill-when-unset merge (see loadEnvFile) lets per-shell exports, Bun's CWD
+`.env`, and the user's data-dir config all override it.
+*/
+export async function loadEnvFromBinaryDir(): Promise<void> {
+    await loadEnvFile(bundleLayout(dirname(process.execPath)).envPath)
+}

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,119 @@
+import { printTrimmed } from './printTrimmed.ts'
+import type { CliManifest } from './types/CliManifest.ts'
+import type { CliManifestEntry } from './types/CliManifestEntry.ts'
+
+/*
+Compact one-line flag signature for the top-level listing: required
+flags are shown bare, optional flags wrapped in `[ ]`. Booleans drop the
+value placeholder; arrays show `<value...>` to hint repetition. Full
+per-flag types + descriptions live in `<cmd> --help`.
+*/
+function flagSignature(jsonSchema: CliManifestEntry['jsonSchema']): string {
+    const properties =
+        (jsonSchema?.properties as Record<string, { type?: string }> | undefined) ?? {}
+    const required = new Set((jsonSchema?.required as string[] | undefined) ?? [])
+    return Object.entries(properties)
+        .map(([key, value]) => {
+            const placeholder =
+                value.type === 'boolean'
+                    ? `--${key}`
+                    : value.type === 'array'
+                      ? `--${key} <value...>`
+                      : `--${key} <${value.type ?? 'value'}>`
+            return required.has(key) ? placeholder : `[${placeholder}]`
+        })
+        .join(' ')
+}
+
+/*
+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()) {
+        printTrimmed(banner)
+        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
+        }
+        /*
+        Summary line favours the schema's top-level description (carried
+        through by the vendor's JSON Schema conversion); falls back to
+        `method url` when the schema has none. The detail line below
+        always shows the args, plus method/url when it isn't already the
+        summary.
+        */
+        const description = entry.jsonSchema?.description as string | undefined
+        console.log(`  ${name.padEnd(20)} ${description ?? `${entry.method} ${entry.url}`}`)
+        const signature = flagSignature(entry.jsonSchema)
+        const detail = [description && `${entry.method} ${entry.url}`, signature]
+            .filter(Boolean)
+            .join('  ')
+        if (detail) {
+            console.log(`  ${' '.repeat(20)} ${detail}`)
+        }
+    }
+    console.log(`\nconnection (\`/\` manages the connection, a bare word runs a command):`)
+    console.log(`  ${programName} /connect <url>   connect to a remote server`)
+    console.log(`  ${programName} /start           start a local instance`)
+    console.log(`  ${programName} /disconnect      forget the saved connection`)
+    console.log(`  ${programName}                  resume the saved connection (session)`)
+    console.log(`\n  --help, -h           show this help`)
+    console.log(`  <command> --help     show help for a specific command`)
+    console.log(`\nenv:`)
+    console.log(`  BELTE_APP_URL        default server URL (baked at install; shell-overridable)`)
+    console.log(`  BELTE_APP_TOKEN      sent as Authorization: Bearer <value>`)
+    if (footer.trim()) {
+        console.log('')
+        printTrimmed(footer)
+    }
+}
+
+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 commandDescription = schema?.description as string | undefined
+    if (commandDescription) {
+        console.log(`${commandDescription}\n`)
+    }
+    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/printSessionHelp.ts

@@ -0,0 +1,27 @@
+import { printCommandHelp, printTopLevelHelp } from './printHelp.ts'
+import type { CliManifest } from './types/CliManifest.ts'
+
+/*
+Session `/help`: with a command name, the per-command flag help; otherwise the
+meta-command list followed by the RPC command listing (no banner — already shown
+at session start).
+*/
+export function printSessionHelp(
+    programName: string,
+    manifest: CliManifest,
+    command?: string,
+): void {
+    if (command) {
+        printCommandHelp(programName, command, manifest)
+        return
+    }
+    console.log('session commands:')
+    console.log('  /connect <url>       connect to a remote server')
+    console.log('  /start               start a local instance')
+    console.log('  /disconnect          disconnect and forget the saved connection')
+    console.log('  /help [command]      show this help, or help for one command')
+    console.log('  /clear               clear the screen')
+    console.log('  /exit                leave the session')
+    console.log('')
+    printTopLevelHelp(programName, manifest)
+}

package/src/lib/cli/printSessionStatus.ts

@@ -0,0 +1,21 @@
+import { probeBelteServer } from '../bundle/probeBelteServer.ts'
+import type { CliTarget } from './types/CliTarget.ts'
+
+/*
+Prints the session's connection line. A local instance (spawned child) reads as
+"running a local instance"; a remote one reads as "connected to <name>", using the
+name the target already carries from its resolve-time probe and only re-probing
+when it doesn't. No target → the not-connected hint listing the verbs.
+*/
+export async function printSessionStatus(target: CliTarget | undefined): Promise<void> {
+    if (!target) {
+        console.log('(not connected — /connect <url> or /start)')
+        return
+    }
+    if (target.child) {
+        console.log(`running a local instance at ${target.url}`)
+        return
+    }
+    const name = target.name ?? (await probeBelteServer(target.url))?.name ?? target.url
+    console.log(`connected to ${name} at ${target.url}`)
+}

package/src/lib/cli/printTrimmed.ts

@@ -0,0 +1,8 @@
+// Prints a block of chrome (banner/footer) with its trailing newline stripped,
+// or nothing when the text is blank. Shared by the help, banner, and session
+// footer so the trim-and-skip idiom lives in one place.
+export function printTrimmed(text: string): void {
+    if (text.trim()) {
+        console.log(text.replace(/\n$/, ''))
+    }
+}

package/src/lib/cli/printValue.ts

@@ -0,0 +1,10 @@
+// String results print verbatim (with a trailing newline); everything else as a JSON line.
+export function printValue(value: unknown, pretty: boolean): void {
+    if (typeof value === 'string') {
+        process.stdout.write(value.endsWith('\n') ? value : `${value}\n`)
+        return
+    }
+    if (value !== undefined) {
+        process.stdout.write(`${JSON.stringify(value, null, pretty ? 2 : undefined)}\n`)
+    }
+}

package/src/lib/cli/resolveCliTarget.ts

@@ -0,0 +1,48 @@
+import { probeBelteServer } from '../bundle/probeBelteServer.ts'
+import { spawnEmbeddedServer } from '../bundle/spawnEmbeddedServer.ts'
+import { log } from '../shared/log.ts'
+import { readLastConnection } from '../shared/readLastConnection.ts'
+import type { CliTarget } from './types/CliTarget.ts'
+
+// Bound a resume boot so a slow/failed local start falls back to not-connected
+// rather than hanging the CLI before the prompt appears.
+const AUTO_START_CEILING_MS = 3000
+
+/*
+Resolves the connection to resume when the CLI runs without an explicit
+connection verb — the terminal analogue of the bundle's resolveLaunchTarget.
+Reads the saved intent:
+  - embedded         → boot a fresh local instance (bounded; undefined on failure)
+  - url, still alive → connect to it
+  - url, now dead    → warn, undefined (caller shows the not-connected prompt)
+  - nothing recorded → the baked/shell BELTE_APP_URL default, else undefined
+Returns undefined when there's nothing live to talk to.
+*/
+export async function resolveCliTarget(programName: string): Promise<CliTarget | undefined> {
+    const last = await readLastConnection(programName)
+    if (last?.kind === 'embedded') {
+        try {
+            const { url, child } = await spawnEmbeddedServer({
+                programName,
+                timeoutMs: AUTO_START_CEILING_MS,
+            })
+            return { url, child }
+        } catch (error) {
+            log.warn(
+                `could not start local instance: ${error instanceof Error ? error.message : String(error)}`,
+            )
+            return undefined
+        }
+    }
+    if (last?.kind === 'url') {
+        const identity = await probeBelteServer(last.url)
+        if (identity) {
+            return { url: last.url, token: process.env.BELTE_APP_TOKEN, name: identity.name }
+        }
+        log.warn(`last server at ${last.url} is not responding`)
+        return undefined
+    }
+    // Nothing recorded — fall back to the baked default / shell override.
+    const appUrl = process.env.BELTE_APP_URL
+    return appUrl ? { url: appUrl, token: process.env.BELTE_APP_TOKEN } : undefined
+}