@briancray/belte 0.8.1 → 0.9.0

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 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.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.APP_URL
+    return appUrl ? { url: appUrl, token: process.env.APP_TOKEN } : undefined
+}

package/src/lib/cli/runCli.ts

@@ -1,44 +1,37 @@
-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 { clearLastConnection } from '../shared/clearLastConnection.ts'
+import { loadEnvFromDataDir } from '../shared/loadEnvFromDataDir.ts'
+import { connectToServer } from './connectToServer.ts'
+import { dispatchCommand } from './dispatchCommand.ts'
 import { loadEnvFromBinaryDir } from './loadEnvFromBinaryDir.ts'
-import { parseArgvForRpc } from './parseArgvForRpc.ts'
 import { printCommandHelp, printTopLevelHelp } from './printHelp.ts'
+import { printTrimmed } from './printTrimmed.ts'
+import { resolveCliTarget } from './resolveCliTarget.ts'
+import { runSession } from './runSession.ts'
+import { startLocalInstance } from './startLocalInstance.ts'
 import type { CliManifest } from './types/CliManifest.ts'
+import type { CliTarget } from './types/CliTarget.ts'
 
 const isHelpFlag = (arg: string): boolean => arg === '--help' || arg === '-h'
 
-// String results print verbatim (with a trailing newline); everything else as a JSON line.
-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`)
-    }
-}
-
 /*
-Top-level CLI driver. Loaded by the standalone binary's entry; expects
-the bundler-emitted manifest plus the raw argv tail. The binary is a
-thin remote client — it carries no handler code, so it always talks to a
-running server over HTTP and APP_URL must be set. Flow:
+Top-level CLI driver for the standalone binary. The binary is a thin remote client
+— it carries no handler code, so it always talks to a running server over HTTP, but
+it can boot one: the full binary ships the server beside it, so `/start` spawns a
+local instance. One rule governs the first positional — `/` manages the connection,
+a bare word runs a command:
 
-  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. Require APP_URL before dispatching a command.
-  5. Otherwise parse the rest of the argv against the manifest entry's
-     JSON Schema and dispatch via createClient against APP_URL.
+  --help / -h                     → top-level help
+  /help [cmd]                     → help (per-command with an arg)
+  (none) + TTY                    → interactive session, resuming the saved connection
+  (none) + non-TTY                → top-level help (scripts use `<cmd>` one-shot)
+  /connect <url>                  → connect to a remote server, open a session
+  /start                          → boot a local instance, open a session
+  /disconnect                     → forget the saved connection, exit
+  <cmd> [--flags]                 → one-shot RPC against the resumed target
 
-Streaming responses are handled by sniffing the response Content-Type:
-sse/jsonl bodies (a streaming verb, or a socket `tail` command) are
-printed frame-by-frame as NDJSON to stdout; everything else is decoded
-and pretty-printed once.
+The connection verbs are `/`-prefixed only — no bare aliases — so a bare word is
+always an RPC command and never collides. Env layers APP_URL/APP_TOKEN (shell >
+data-dir > binary-dir) supply the baked default a fresh download resumes against.
 */
 export async function runCli({
     programName,
@@ -53,69 +46,94 @@ export async function runCli({
     footer?: string
     argv: string[]
 }): Promise<number> {
+    await loadEnvFromDataDir(programName)
     await loadEnvFromBinaryDir()
 
     const first = argv[0]
-    if (!first || isHelpFlag(first)) {
+
+    // Explicit help, top-level and per-command.
+    if (first && isHelpFlag(first)) {
         printTopLevelHelp(programName, manifest, banner, footer)
         return 0
     }
-
-    if (argv.some(isHelpFlag)) {
+    if (first === '/help') {
+        if (argv[1]) {
+            printCommandHelp(programName, argv[1], manifest)
+        } else {
+            printTopLevelHelp(programName, manifest, banner, footer)
+        }
+        return 0
+    }
+    if (first && argv.some(isHelpFlag)) {
         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
+    // No command: interactive session on a TTY, help otherwise (scripts/pipes).
+    if (!first) {
+        if (!process.stdin.isTTY) {
+            printTopLevelHelp(programName, manifest, banner, footer)
+            return 0
+        }
+        printTrimmed(banner)
+        const target = await resolveCliTarget(programName)
+        return runSession({ programName, manifest, footer, target })
     }
 
-    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
+    // Disconnect (reset): clear the saved connection and exit.
+    if (first === '/disconnect') {
+        await clearLastConnection(programName)
+        console.log('disconnected')
+        return 0
     }
 
-    const appUrl = process.env.APP_URL
-    if (!appUrl) {
-        console.error(
-            `${programName}: APP_URL is not set — the cli talks to a running server, so point it at one (e.g. APP_URL=http://localhost:3000)`,
-        )
-        return 1
+    // Connect to a remote server, then open a session.
+    if (first === '/connect') {
+        const url = argv[1]
+        if (!url) {
+            console.error(`${programName}: /connect requires a url`)
+            return 1
+        }
+        printTrimmed(banner)
+        const target = await connectToServer(programName, url)
+        if (!target) {
+            return 1
+        }
+        return runSession({ programName, manifest, footer, target })
     }
-    const appToken = process.env.APP_TOKEN
-    const client = createClient({ url: appUrl, token: appToken, manifest })
 
-    const fn = client[first]
-    if (!fn) {
-        console.error(`${programName}: command "${first}" not in client`)
-        return 1
-    }
-    try {
-        const response = await fn.raw(args)
-        if (isStreamingResponse(response)) {
-            /*
-            Stream frame-by-frame to stdout as NDJSON. streamResponse
-            throws a clear HttpError on a non-2xx body, caught below.
-            */
-            for await (const frame of streamResponse(response)) {
-                printValue(frame, false)
-            }
-            return 0
-        }
-        if (!response.ok) {
-            throw new Error(await responseErrorText(response))
+    // Start a local instance, then open a session.
+    if (first === '/start') {
+        printTrimmed(banner)
+        let target: CliTarget
+        try {
+            target = await startLocalInstance(programName)
+        } catch (error) {
+            console.error(
+                `${programName}: ${error instanceof Error ? error.message : String(error)}`,
+            )
+            return 1
         }
-        printValue(await decodeResponse(response), true)
-        return 0
-    } catch (error) {
-        console.error(`${programName}: ${error instanceof Error ? error.message : String(error)}`)
+        return runSession({ programName, manifest, footer, target })
+    }
+
+    // One-shot RPC dispatch (scripting): resolve the target without a session.
+    const target = await resolveCliTarget(programName)
+    if (!target) {
+        console.error(
+            `${programName}: not connected — run \`${programName} /connect <url>\` or \`${programName} /start\``,
+        )
         return 1
     }
+    const code = await dispatchCommand({
+        programName,
+        manifest,
+        command: first,
+        argvTail: argv.slice(1),
+        url: target.url,
+        token: target.token,
+    })
+    // Reap any local instance booted just to resolve the target.
+    target.child?.kill()
+    return code
 }

package/src/lib/cli/runSession.ts

@@ -0,0 +1,105 @@
+import { clearLastConnection } from '../shared/clearLastConnection.ts'
+import { connectToServer } from './connectToServer.ts'
+import { dispatchCommand } from './dispatchCommand.ts'
+import { printSessionHelp } from './printSessionHelp.ts'
+import { printSessionStatus } from './printSessionStatus.ts'
+import { printTrimmed } from './printTrimmed.ts'
+import { startLocalInstance } from './startLocalInstance.ts'
+import { tokenizeLine } from './tokenizeLine.ts'
+import type { CliManifest } from './types/CliManifest.ts'
+import type { CliTarget } from './types/CliTarget.ts'
+
+/*
+Interactive session (REPL). The banner is printed once by the caller; this prints
+the status line, then loops reading stdin lines via Bun's async-iterable console:
+  - bare words   → dispatch the RPC against the current target
+  - /connect <url>, /start, /disconnect, /help, /clear, /exit → meta commands
+The session owns the current target's child (a local instance) and reaps it when
+the connection is swapped or the loop ends — including on SIGINT.
+*/
+export async function runSession({
+    programName,
+    manifest,
+    footer,
+    target,
+}: {
+    programName: string
+    manifest: CliManifest
+    footer: string
+    target: CliTarget | undefined
+}): Promise<number> {
+    let current = target
+    // Reap any local instance on Ctrl+C — the closure reads the latest `current`.
+    process.on('SIGINT', () => {
+        current?.child?.kill()
+        process.exit(0)
+    })
+
+    // Swap the active connection: reap the previous local instance (only one runs
+    // at a time), adopt the next target, and reprint the status line.
+    async function swap(next: CliTarget | undefined): Promise<void> {
+        current?.child?.kill()
+        current = next
+        await printSessionStatus(current)
+    }
+
+    await printSessionStatus(current)
+    const promptText = `${programName}> `
+    process.stdout.write(promptText)
+
+    for await (const line of console) {
+        const tokens = tokenizeLine(line.trim())
+        const head = tokens[0]
+        if (head === undefined) {
+            process.stdout.write(promptText)
+            continue
+        }
+        if (head === '/exit' || head === '/quit') {
+            break
+        }
+        if (head === '/clear') {
+            console.clear()
+        } else if (head === '/help') {
+            printSessionHelp(programName, manifest, tokens[1])
+        } else if (head === '/connect') {
+            const url = tokens[1]
+            if (!url) {
+                console.error('/connect requires a url')
+            } else {
+                const next = await connectToServer(programName, url)
+                if (next) {
+                    await swap(next)
+                }
+            }
+        } else if (head === '/start') {
+            try {
+                await swap(await startLocalInstance(programName))
+            } catch (error) {
+                console.error(
+                    `could not start local instance: ${error instanceof Error ? error.message : String(error)}`,
+                )
+            }
+        } else if (head === '/disconnect') {
+            await clearLastConnection(programName)
+            await swap(undefined)
+        } else if (head.startsWith('/')) {
+            console.error(`unknown command "${head}" — /help for the list`)
+        } else if (!current) {
+            console.error('not connected — /connect <url> or /start')
+        } else {
+            await dispatchCommand({
+                programName,
+                manifest,
+                command: head,
+                argvTail: tokens.slice(1),
+                url: current.url,
+                token: current.token,
+            })
+        }
+        process.stdout.write(promptText)
+    }
+
+    current?.child?.kill()
+    printTrimmed(footer)
+    return 0
+}

package/src/lib/cli/startLocalInstance.ts

@@ -0,0 +1,14 @@
+import { spawnEmbeddedServer } from '../bundle/spawnEmbeddedServer.ts'
+import { writeLastConnection } from '../shared/writeLastConnection.ts'
+import type { CliTarget } from './types/CliTarget.ts'
+
+/*
+Boots a local (embedded) instance for this session and records the intent so the
+next bare run resumes a local instance. The caller owns the returned child and
+reaps it on disconnect/exit. Throws if the server crashes before binding.
+*/
+export async function startLocalInstance(programName: string): Promise<CliTarget> {
+    const { url, child } = await spawnEmbeddedServer({ programName })
+    await writeLastConnection(programName, { kind: 'embedded' })
+    return { url, child }
+}

package/src/lib/cli/tokenizeLine.ts

@@ -0,0 +1,51 @@
+/*
+Splits a session input line into argv tokens, honouring single and double quotes
+so values with spaces survive (e.g. `post --title "hello world"`). Quotes group;
+a backslash escapes the next character (outside single quotes). Unterminated
+quotes consume to end of line. Pure; no shell features beyond quoting — no
+globbing, no variable expansion.
+*/
+export function tokenizeLine(line: string): string[] {
+    const tokens: string[] = []
+    let current = ''
+    let hasToken = false
+    let quote: '"' | "'" | undefined
+    for (let index = 0; index < line.length; index++) {
+        const char = line[index]
+        if (char === '\\' && quote !== "'") {
+            const next = line[++index]
+            if (next !== undefined) {
+                current += next
+                hasToken = true
+            }
+            continue
+        }
+        if (quote) {
+            if (char === quote) {
+                quote = undefined
+            } else {
+                current += char
+            }
+            continue
+        }
+        if (char === '"' || char === "'") {
+            quote = char
+            hasToken = true
+            continue
+        }
+        if (char === ' ' || char === '\t') {
+            if (hasToken) {
+                tokens.push(current)
+                current = ''
+                hasToken = false
+            }
+            continue
+        }
+        current += char
+        hasToken = true
+    }
+    if (hasToken) {
+        tokens.push(current)
+    }
+    return tokens
+}

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

@@ -0,0 +1,13 @@
+/*
+A resolved CLI connection: the server URL plus an optional bearer token, and the
+child process when this is a locally-spawned instance — the session owns that
+child and reaps it on disconnect/exit.
+*/
+export type CliTarget = {
+    url: string
+    token?: string
+    child?: ReturnType<typeof Bun.spawn>
+    // The app's name from its identity probe, when already fetched while resolving
+    // the target — lets the status line print it without re-probing.
+    name?: string
+}

package/src/lib/server/cli/handleCliDownload.ts

@@ -1,10 +1,17 @@
 import { NO_STORE } from '../../shared/cacheControlValues.ts'
+import { exeSuffix } from '../../shared/exeSuffix.ts'
 import { log } from '../../shared/log.ts'
 import { normalizeTarget } from '../../shared/normalizeTarget.ts'
 import { buildEnvContent } from './buildEnvContent.ts'
 import { createTarGz } from './createTarGz.ts'
 import { maxSourceMtime } from './maxSourceMtime.ts'
 
+// The sibling server binary's name for a platform — `server` / `server.exe` — must
+// match what resolveServerBinary() looks for next to the unpacked CLI binary.
+function serverBinaryName(platform: string): string {
+    return `server${exeSuffix(normalizeTarget(platform))}`
+}
+
 /*
 Process-wide per-platform build coalescing. Two concurrent curls for
 the same /__belte/cli/<platform> share one promise; the later requests
@@ -46,16 +53,20 @@ async function computeBinary(
     programName: string,
     cwd: string,
 ): Promise<string | undefined> {
-    const binaryPath = `${cwd}/dist/cli-thin/${platform}/${programName}`
+    const dir = `${cwd}/dist/cli-thin/${platform}`
+    const binaryPath = `${dir}/${programName}`
+    const serverPath = `${dir}/${serverBinaryName(platform)}`
     /*
-    On-disk binary is fresh when it exists AND its mtime beats the
-    newest rpc/socket source mtime. The mtime check catches the
-    common dev iteration where the user edits an rpc handler but
-    didn't run `belte cli` again. Other source paths (project lib,
+    On-disk binaries are fresh when both the CLI and its sibling server exist AND
+    the CLI's mtime beats the newest rpc/socket source mtime. The mtime check
+    catches the common dev iteration where the user edits an rpc handler but didn't
+    run `belte cli` again; the server-exists check forces a rebuild for a dist
+    produced before the CLI co-shipped a server. Other source paths (project lib,
     transitive imports) fall back to manual rebuild.
     */
     const binaryFile = Bun.file(binaryPath)
-    if (await binaryFile.exists()) {
+    const serverFile = Bun.file(serverPath)
+    if ((await binaryFile.exists()) && (await serverFile.exists())) {
         const binaryMtime = (await binaryFile.stat()).mtimeMs
         const sourceMtime = await maxSourceMtime(cwd)
         if (binaryMtime >= sourceMtime) {
@@ -64,7 +75,7 @@ async function computeBinary(
         log.info(`thin cli for ${platform} is stale — rebuilding`)
     }
     try {
-        log.info(`lazy-building thin cli for ${platform}…`)
+        log.info(`lazy-building cli + server for ${platform}…`)
         // Lazy-import buildCli so the build pipeline isn't pulled into
         // production processes that never serve a download.
         const { buildCli } = await import('../../../buildCli.ts')
@@ -72,7 +83,7 @@ async function computeBinary(
             cwd,
             platforms: [normalizeTarget(platform)],
         })
-        return (await binaryFile.exists()) ? binaryPath : undefined
+        return (await binaryFile.exists()) && (await serverFile.exists()) ? binaryPath : undefined
     } catch (error) {
         log.error(error)
         return undefined
@@ -107,9 +118,15 @@ export async function handleCliDownload(
         auth && auth.toLowerCase().startsWith('bearer ') ? auth.slice('bearer '.length) : undefined
     const envContent = buildEnvContent(appUrl, bearer)
 
-    const binaryBytes = await Bun.file(binaryPath).bytes()
+    const serverPath = `${cwd}/dist/cli-thin/${platform}/${serverBinaryName(platform)}`
+    const [binaryBytes, serverBytes] = await Promise.all([
+        Bun.file(binaryPath).bytes(),
+        Bun.file(serverPath).bytes(),
+    ])
+    // Ship the server beside the CLI so `/start` can spawn a local instance.
     const archive = createTarGz([
         { name: programName, content: binaryBytes, mode: 0o755 },
+        { name: serverBinaryName(platform), content: serverBytes, mode: 0o755 },
         { name: '.env', content: new TextEncoder().encode(envContent), mode: 0o644 },
     ])
     return new Response(archive, {

package/src/lib/shared/clearLastConnection.ts

@@ -0,0 +1,7 @@
+import { rm } from 'node:fs/promises'
+import { lastConnectionPath } from './lastConnectionPath.ts'
+
+// Forgets the saved connection (the `/disconnect` reset). Missing file is a no-op.
+export async function clearLastConnection(programName: string): Promise<void> {
+    await rm(lastConnectionPath(programName), { force: true })
+}

package/src/lib/shared/lastConnectionPath.ts

@@ -0,0 +1,7 @@
+import { join } from 'node:path'
+import { appDataDir } from './appDataDir.ts'
+
+// Path to the per-program last-connection record, beside the data-dir `.env`.
+export function lastConnectionPath(programName: string): string {
+    return join(appDataDir(programName), 'last-connection.json')
+}

package/src/lib/shared/readLastConnection.ts

@@ -0,0 +1,18 @@
+import { lastConnectionPath } from './lastConnectionPath.ts'
+import type { LastConnection } from './types/LastConnection.ts'
+
+/*
+Reads the saved connection intent, or undefined when none is recorded or the file
+is unreadable/corrupt — callers treat undefined as "nothing to resume".
+*/
+export async function readLastConnection(programName: string): Promise<LastConnection | undefined> {
+    const file = Bun.file(lastConnectionPath(programName))
+    if (!(await file.exists())) {
+        return undefined
+    }
+    try {
+        return (await file.json()) as LastConnection
+    } catch {
+        return undefined
+    }
+}

package/src/lib/shared/runningAsStandaloneBinary.ts

@@ -0,0 +1,13 @@
+/*
+True when this code runs inside a `bun build --compile` standalone executable
+(the bundle's embedded server, or an install-tarball server binary) rather than
+under the `bun` CLI. Bun mounts a compiled binary's embedded modules under a
+synthetic root — `/$bunfs/…` on posix, `…~BUN…` on Windows — so `Bun.main`
+carries that marker only in a standalone binary; under `bun dev`/`bun start`
+it's a real on-disk path. Used to scope the bundle's data-dir/binary-dir `.env`
+loading to the shipped app, so `bun dev`/`bun start` keep to their project-local
+CWD `.env` alone.
+*/
+export function runningAsStandaloneBinary(): boolean {
+    return Bun.main.includes('$bunfs') || Bun.main.includes('~BUN')
+}

package/src/lib/shared/types/LastConnection.ts

@@ -0,0 +1,9 @@
+/*
+The launcher/CLI-owned record of the last connection, kept in the data dir so it
+survives relaunch and is readable before any window or session opens. It records
+the *intent*, not a concrete embedded URL — an embedded server picks a fresh port
+each launch, so only `{ kind: 'embedded' }` is durable; a remote connection keeps
+its url. resolveLaunchTarget / resolveCliTarget read it; /connect and /start write
+it; /disconnect clears it.
+*/
+export type LastConnection = { kind: 'embedded' } | { kind: 'url'; url: string }

package/src/lib/shared/writeLastConnection.ts

@@ -0,0 +1,13 @@
+import { mkdir } from 'node:fs/promises'
+import { appDataDir } from './appDataDir.ts'
+import { lastConnectionPath } from './lastConnectionPath.ts'
+import type { LastConnection } from './types/LastConnection.ts'
+
+// Persists the connection intent, creating the data dir on first write.
+export async function writeLastConnection(
+    programName: string,
+    value: LastConnection,
+): Promise<void> {
+    await mkdir(appDataDir(programName), { recursive: true })
+    await Bun.write(lastConnectionPath(programName), JSON.stringify(value))
+}