@abide/abide 0.28.0

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,15 @@
+import { binaryDirEnvPath } from '../shared/binaryDirEnvPath.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(binaryDirEnvPath())
+}

package/src/lib/cli/parseArgvForRpc.ts

@@ -0,0 +1,100 @@
+/*
+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 stripped = token.slice('--'.length)
+        const [literalName, eqValue] = stripped.includes('=')
+            ? [stripped.slice(0, stripped.indexOf('=')), stripped.slice(stripped.indexOf('=') + 1)]
+            : [stripped, undefined]
+        /* `--no-x` negates only a known boolean property x; otherwise the literal
+           name wins, so a property legitimately named `no-…` stays reachable. */
+        const negatedName = literalName.startsWith('no-')
+            ? literalName.slice('no-'.length)
+            : undefined
+        const isNegated = negatedName !== undefined && properties[negatedName]?.type === 'boolean'
+        const name = isNegated ? (negatedName as string) : literalName
+        const prop = properties[name]
+        const propType = prop?.type
+        if (propType === 'boolean') {
+            args[name] = !isNegated
+            continue
+        }
+        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(`  ABIDE_APP_URL        default server URL (baked at install; shell-overridable)`)
+    console.log(`  ABIDE_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 { probeAbideServer } from '../bundle/probeAbideServer.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 probeAbideServer(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 { probeAbideServer } from '../bundle/probeAbideServer.ts'
+import { spawnEmbeddedServer } from '../bundle/spawnEmbeddedServer.ts'
+import { abideLog } from '../shared/abideLog.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 ABIDE_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) {
+            abideLog.warn(
+                `could not start local instance: ${error instanceof Error ? error.message : String(error)}`,
+            )
+            return undefined
+        }
+    }
+    if (last?.kind === 'url') {
+        const identity = await probeAbideServer(last.url)
+        if (identity) {
+            return { url: last.url, token: process.env.ABIDE_APP_TOKEN, name: identity.name }
+        }
+        abideLog.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.ABIDE_APP_URL
+    return appUrl ? { url: appUrl, token: process.env.ABIDE_APP_TOKEN } : undefined
+}

package/src/lib/cli/runCli.ts

@@ -0,0 +1,176 @@
+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 { 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'
+
+/*
+Whether a command's argv tail genuinely requests help, i.e. a help flag appears
+at a flag position rather than as the value of a value-expecting flag. Mirrors
+parseArgvForRpc's flag rule: boolean props (and `--name=…`) consume no following
+token, everything else consumes the next token as its value — so `--title --help`
+passes `--help` as the title value, not a help request.
+*/
+function commandArgvRequestsHelp(
+    argvTail: string[],
+    jsonSchema: Record<string, unknown> | undefined,
+): boolean {
+    const properties =
+        (jsonSchema?.properties as Record<string, { type?: string }> | undefined) ?? {}
+    for (let index = 0; index < argvTail.length; index += 1) {
+        const token = argvTail[index] as string
+        if (isHelpFlag(token)) {
+            return true
+        }
+        if (!token.startsWith('--')) {
+            continue
+        }
+        if (token === '--json') {
+            index += 1 // consumes its value
+            continue
+        }
+        const rawName = token.slice('--'.length)
+        if (rawName.includes('=')) {
+            continue // inline value, consumes no following token
+        }
+        const name = rawName.startsWith('no-') ? rawName.slice('no-'.length) : rawName
+        if (properties[name]?.type !== 'boolean') {
+            index += 1 // a value-expecting flag consumes the next token
+        }
+    }
+    return false
+}
+
+/*
+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:
+
+  --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
+
+The connection verbs are `/`-prefixed only — no bare aliases — so a bare word is
+always an RPC command and never collides. Env layers ABIDE_APP_URL/ABIDE_APP_TOKEN (shell >
+data-dir > binary-dir) supply the baked default a fresh download resumes against.
+*/
+export async function runCli({
+    programName,
+    manifest,
+    banner = '',
+    footer = '',
+    argv,
+}: {
+    programName: string
+    manifest: CliManifest
+    banner?: string
+    footer?: string
+    argv: string[]
+}): Promise<number> {
+    await loadEnvFromDataDir(programName)
+    await loadEnvFromBinaryDir()
+
+    const first = argv[0]
+
+    // Explicit help, top-level and per-command.
+    if (first && isHelpFlag(first)) {
+        printTopLevelHelp(programName, manifest, banner, footer)
+        return 0
+    }
+    if (first === '/help') {
+        if (argv[1]) {
+            printCommandHelp(programName, argv[1], manifest)
+        } else {
+            printTopLevelHelp(programName, manifest, banner, footer)
+        }
+        return 0
+    }
+    if (first && commandArgvRequestsHelp(argv.slice(1), manifest[first]?.jsonSchema)) {
+        printCommandHelp(programName, first, manifest)
+        return 0
+    }
+
+    // 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 })
+    }
+
+    // Disconnect (reset): clear the saved connection and exit.
+    if (first === '/disconnect') {
+        await clearLastConnection(programName)
+        console.log('disconnected')
+        return 0
+    }
+
+    // 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 })
+    }
+
+    // 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
+        }
+        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
+}