@chatbridge/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,3 +1,9 @@
 # @chatbridge/cli
 
 The CLI for [chatbridge](https://github.com/7milch/chatbridge-cli): drive browser-only web chat AI services from the command line.
+
+## Modes
+
+- `chatbridge -p "<prompt>"` — one-shot, response on stdout. Node >= 20 or Bun.
+- `chatbridge` — interactive chat in the terminal. Bun >= 1.3 or Node >= 26.4.
+- `chatbridge auth login|logout|status` — manage the saved browser auth state.

package/dist/create-cli.d.ts

@@ -8,6 +8,8 @@ export interface CreateCliOptions {
     configDir?: string;
     /** Test-only: overrides the config/auth-store base directory. */
     baseDir?: string;
+    /** Test-only: overrides "stdin and stdout are a TTY". */
+    isTerminal?: boolean;
 }
 export declare function createCli(opts: CreateCliOptions): {
     run: (argv: string[]) => Promise<number>;

package/dist/create-cli.js

@@ -2,6 +2,7 @@ import { parseArgs } from "node:util";
 import { ChatBridgeError, ProviderLoadError, createAuthStore, runLogin, runOneShot, } from "@chatbridge/core";
 import { configPath, loadConfig } from "./config.js";
 import { resolveProvider } from "./resolve-provider.js";
+import { supportsInteractive } from "./tui/runtime-check.js";
 /** Single source of truth for `ChatBridgeError.code` → process exit code. */
 const EXIT_CODES = {
     INVALID_ARGUMENT: 1,
@@ -11,6 +12,7 @@ const EXIT_CODES = {
     RESPONSE_TIMEOUT: 4,
     PROVIDER_LOAD: 5,
     INVALID_PROVIDER: 5,
+    INVALID_STATE: 1,
 };
 const DEFAULT_TIMEOUT_SEC = 120;
 /** Validates --timeout before any browser is launched. */
@@ -36,11 +38,13 @@ export function createCli(opts) {
         const providerFlag = opts.provider ? "" : " [--provider <name|path>]";
         return [
             "Usage:",
+            `  ${opts.name}${providerFlag} [--headful] [--timeout <sec>]`,
             `  ${opts.name} -p <prompt>${providerFlag} [--headful] [--timeout <sec>]`,
             `  ${opts.name} auth login${providerFlag}`,
             `  ${opts.name} auth logout${providerFlag}`,
             `  ${opts.name} auth status${providerFlag}`,
             "",
+            "Without -p, an interactive chat opens (needs a terminal and Bun >= 1.3 or Node >= 26.4).",
             "One-shot mode prints the AI response to stdout.",
             ...(opts.provider
                 ? []
@@ -129,6 +133,37 @@ export function createCli(opts) {
                     : `No auth state for "${provider.name}"`);
                 return 0;
             }
+            if (cmd === undefined && values.prompt === undefined) {
+                const isTerminal = opts.isTerminal ??
+                    (process.stdin.isTTY === true && process.stdout.isTTY === true);
+                if (!isTerminal) {
+                    throw new ChatBridgeError("INVALID_ARGUMENT", "interactive mode needs a terminal; use -p <prompt> for one-shot");
+                }
+                if (!supportsInteractive({
+                    bun: process.versions.bun,
+                    node: process.versions.node,
+                })) {
+                    throw new ChatBridgeError("INVALID_ARGUMENT", "interactive mode needs Bun >= 1.3 or Node >= 26.4; use -p <prompt> on this runtime");
+                }
+                const timeoutMs = parseTimeoutMs(values.timeout);
+                const provider = await getProvider(values.provider);
+                const authStore = createAuthStore({
+                    configDir,
+                    providerName: provider.name,
+                    baseDir: opts.baseDir,
+                });
+                // Loaded lazily so one-shot and auth never evaluate @opentui/core.
+                const { runInteractive } = await import("./tui/run-interactive.js");
+                const result = await runInteractive({
+                    title: opts.name,
+                    provider,
+                    authStore,
+                    headless: !values.headful,
+                    timeoutMs,
+                    onProgress: progress,
+                });
+                return result.fatal === undefined ? 0 : reportError(result.fatal);
+            }
             if (typeof values.prompt === "string") {
                 const timeoutMs = parseTimeoutMs(values.timeout);
                 const provider = await getProvider(values.provider);
@@ -150,7 +185,7 @@ export function createCli(opts) {
                 return 0;
             }
             console.log(help());
-            return cmd === undefined ? 0 : 1;
+            return 1;
         }
         catch (err) {
             return reportError(err);

package/dist/tui/chat-model.d.ts

@@ -0,0 +1,25 @@
+/** What the model needs from a ChatSession; lets tests inject a fake. */
+export interface ChatSessionLike {
+    send(prompt: string): Promise<string>;
+    close(): Promise<void>;
+}
+export type Role = "user" | "assistant" | "error";
+export interface Message {
+    role: Role;
+    text: string;
+}
+export type Status = "idle" | "busy";
+/** Conversation state for the interactive UI. No OpenTUI dependency. */
+export declare class ChatModel {
+    private readonly session;
+    readonly messages: Message[];
+    status: Status;
+    /** Set when submit hit an unrecoverable error; the app must exit. */
+    fatal: unknown;
+    /** Called after every state change. */
+    onChange: () => void;
+    constructor(session: ChatSessionLike);
+    /** Sends one turn. Blank input, input while busy, and input after a
+     * fatal error are ignored. */
+    submit(text: string): Promise<void>;
+}

package/dist/tui/chat-model.js

@@ -0,0 +1,39 @@
+import { ResponseTimeoutError } from "@chatbridge/core";
+/** Conversation state for the interactive UI. No OpenTUI dependency. */
+export class ChatModel {
+    session;
+    messages = [];
+    status = "idle";
+    /** Set when submit hit an unrecoverable error; the app must exit. */
+    fatal = undefined;
+    /** Called after every state change. */
+    onChange = () => { };
+    constructor(session) {
+        this.session = session;
+    }
+    /** Sends one turn. Blank input, input while busy, and input after a
+     * fatal error are ignored. */
+    async submit(text) {
+        const prompt = text.trim();
+        if (!prompt || this.status === "busy" || this.fatal !== undefined)
+            return;
+        this.messages.push({ role: "user", text: prompt });
+        this.status = "busy";
+        this.onChange();
+        try {
+            const reply = await this.session.send(prompt);
+            this.messages.push({ role: "assistant", text: reply });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.messages.push({ role: "error", text: message });
+            // A timeout leaves the browser usable; anything else ends the session.
+            if (!(err instanceof ResponseTimeoutError))
+                this.fatal = err;
+        }
+        finally {
+            this.status = "idle";
+            this.onChange();
+        }
+    }
+}

package/dist/tui/chat-view.d.ts

@@ -0,0 +1,31 @@
+import { type CliRenderer } from "@opentui/core";
+import type { ChatModel } from "./chat-model.js";
+export declare const GUIDE = "Enter send \u00B7 Shift+Enter (or Ctrl+J) newline \u00B7 Ctrl+C quit";
+export interface ChatViewOptions {
+    title: string;
+    providerName: string;
+}
+/** Builds the OpenTUI tree for one ChatModel and mirrors its state.
+ * Layout: header / scrolling history / 4-line textarea / status line. */
+export declare class ChatView {
+    private readonly renderer;
+    private readonly model;
+    private readonly history;
+    private readonly input;
+    private readonly status;
+    private rendered;
+    private spinner;
+    private frame;
+    private destroyed;
+    private statusPinned;
+    constructor(renderer: CliRenderer, model: ChatModel, opts: ChatViewOptions);
+    /** Appends messages not yet drawn and syncs the status line. */
+    update(): void;
+    /** Pins a message on the status line (e.g. "Closing browser...") so the
+     * user sees that teardown started. Later model changes leave it alone. */
+    setStatus(text: string): void;
+    destroy(): void;
+    private messageBox;
+    private startSpinner;
+    private stopSpinner;
+}

package/dist/tui/chat-view.js

@@ -0,0 +1,152 @@
+import { BoxRenderable, ScrollBoxRenderable, TextRenderable, TextareaRenderable, } from "@opentui/core";
+export const GUIDE = "Enter send · Shift+Enter (or Ctrl+J) newline · Ctrl+C quit";
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 80;
+const LABELS = {
+    user: "You",
+    assistant: "Assistant",
+    error: "Error",
+};
+/** Builds the OpenTUI tree for one ChatModel and mirrors its state.
+ * Layout: header / scrolling history / 4-line textarea / status line. */
+export class ChatView {
+    renderer;
+    model;
+    history;
+    input;
+    status;
+    rendered = 0;
+    spinner;
+    frame = 0;
+    destroyed = false;
+    statusPinned = false;
+    constructor(renderer, model, opts) {
+        this.renderer = renderer;
+        this.model = model;
+        const root = new BoxRenderable(renderer, {
+            id: "root",
+            flexDirection: "column",
+            width: "100%",
+            height: "100%",
+        });
+        root.add(new TextRenderable(renderer, {
+            id: "header",
+            content: `${opts.title} · ${opts.providerName}`,
+            marginBottom: 1,
+        }));
+        this.history = new ScrollBoxRenderable(renderer, {
+            id: "history",
+            flexGrow: 1,
+            stickyScroll: true,
+            stickyStart: "bottom",
+        });
+        root.add(this.history);
+        const inputBox = new BoxRenderable(renderer, {
+            id: "input-box",
+            border: true,
+            height: 6,
+        });
+        this.input = new TextareaRenderable(renderer, {
+            id: "input",
+            height: 4,
+            placeholder: "Type a message",
+            keyBindings: [
+                { name: "return", action: "submit" },
+                { name: "kpenter", action: "submit" },
+                // Shift+Enter needs the kitty keyboard protocol. Ctrl+J arrives as
+                // a linefeed byte on legacy terminals and as ctrl+j under kitty.
+                { name: "return", shift: true, action: "newline" },
+                { name: "linefeed", action: "newline" },
+                { name: "j", ctrl: true, action: "newline" },
+            ],
+        });
+        inputBox.add(this.input);
+        root.add(inputBox);
+        this.status = new TextRenderable(renderer, {
+            id: "status",
+            content: GUIDE,
+        });
+        root.add(this.status);
+        renderer.root.add(root);
+        this.input.onSubmit = () => {
+            const text = this.input.plainText;
+            // Mirrors every case ChatModel.submit drops, so the textarea is never
+            // cleared for input the model is going to ignore.
+            if (!text.trim() ||
+                this.model.status === "busy" ||
+                this.model.fatal !== undefined) {
+                return;
+            }
+            this.input.clear();
+            void this.model.submit(text);
+        };
+        this.model.onChange = () => this.update();
+        this.input.focus();
+        this.update();
+    }
+    /** Appends messages not yet drawn and syncs the status line. */
+    update() {
+        // A turn still in flight when the view is destroyed would otherwise
+        // write to renderables the renderer has already torn down.
+        if (this.destroyed)
+            return;
+        for (; this.rendered < this.model.messages.length; this.rendered++) {
+            const message = this.model.messages[this.rendered];
+            if (message)
+                this.history.add(this.messageBox(message));
+        }
+        if (this.statusPinned)
+            return;
+        if (this.model.status === "busy") {
+            this.startSpinner();
+        }
+        else {
+            this.stopSpinner();
+            this.status.content = GUIDE;
+        }
+    }
+    /** Pins a message on the status line (e.g. "Closing browser...") so the
+     * user sees that teardown started. Later model changes leave it alone. */
+    setStatus(text) {
+        if (this.destroyed)
+            return;
+        this.statusPinned = true;
+        this.stopSpinner();
+        this.status.content = text;
+    }
+    destroy() {
+        this.destroyed = true;
+        // Deliberately severs the model→view link: a turn still in flight must
+        // not reach renderables the renderer is about to tear down.
+        this.model.onChange = () => { };
+        this.stopSpinner();
+    }
+    messageBox(message) {
+        const box = new BoxRenderable(this.renderer, {
+            flexDirection: "column",
+            marginBottom: 1,
+        });
+        box.add(new TextRenderable(this.renderer, { content: LABELS[message.role] }));
+        box.add(new TextRenderable(this.renderer, {
+            content: message.text,
+            wrapMode: "word",
+        }));
+        return box;
+    }
+    startSpinner() {
+        if (this.spinner)
+            return;
+        const tick = () => {
+            this.frame = (this.frame + 1) % SPINNER.length;
+            this.status.content = `${SPINNER[this.frame]} Waiting for response...`;
+        };
+        tick();
+        this.spinner = setInterval(tick, SPINNER_INTERVAL_MS);
+    }
+    stopSpinner() {
+        if (!this.spinner)
+            return;
+        clearInterval(this.spinner);
+        this.spinner = undefined;
+    }
+}

package/dist/tui/run-interactive.d.ts

@@ -0,0 +1,35 @@
+import { type ChatSessionOptions } from "@chatbridge/core";
+import { type CliRenderer } from "@opentui/core";
+import { ChatModel } from "./chat-model.js";
+export interface InteractiveOptions extends ChatSessionOptions {
+    /** Shown in the header, e.g. the CLI name. */
+    title: string;
+    /** Test-only: replaces createCliRenderer. */
+    createRenderer?: () => Promise<CliRenderer>;
+}
+/** What the bounded close needs from a session; lets tests inject a fake. */
+export interface ClosableSession {
+    close(): Promise<void>;
+}
+/**
+ * Resolves when the user asks to quit: Ctrl+C, a fatal model error (the
+ * error is the resolved value), or the renderer being destroyed from
+ * outside — OpenTUI installs its own SIGINT/SIGTERM/SIGHUP handlers that
+ * destroy the renderer without exiting the process, so without this the
+ * caller's promise would stay pending and the browser would keep the
+ * process alive.
+ *
+ * Must be called after the ChatView is built: it chains onto the view's
+ * `onChange` handler rather than replacing it.
+ */
+export declare function waitForQuit(renderer: CliRenderer, model: ChatModel): Promise<unknown>;
+/** Opens a ChatSession (errors propagate before any UI exists), runs the
+ * TUI until Ctrl+C or a fatal error, then restores the terminal.
+ * Resolves with the fatal error, if any, for the caller to report. */
+export declare function runInteractive(opts: InteractiveOptions): Promise<{
+    fatal?: unknown;
+}>;
+/** Playwright close can hang on a wedged browser; never block exit on it.
+ * Returns true when the session closed within `ms`. Close errors are
+ * swallowed: teardown must not mask the result the caller is returning. */
+export declare function closeWithTimeout(session: ClosableSession, ms: number): Promise<boolean>;

package/dist/tui/run-interactive.js

@@ -0,0 +1,89 @@
+import { ChatSession } from "@chatbridge/core";
+import { createCliRenderer, } from "@opentui/core";
+import { ChatModel } from "./chat-model.js";
+import { ChatView } from "./chat-view.js";
+const CLOSE_TIMEOUT_MS = 5_000;
+const CLOSING_STATUS = "Closing browser...";
+/**
+ * Resolves when the user asks to quit: Ctrl+C, a fatal model error (the
+ * error is the resolved value), or the renderer being destroyed from
+ * outside — OpenTUI installs its own SIGINT/SIGTERM/SIGHUP handlers that
+ * destroy the renderer without exiting the process, so without this the
+ * caller's promise would stay pending and the browser would keep the
+ * process alive.
+ *
+ * Must be called after the ChatView is built: it chains onto the view's
+ * `onChange` handler rather than replacing it.
+ */
+export function waitForQuit(renderer, model) {
+    return new Promise((resolve) => {
+        const notify = model.onChange;
+        model.onChange = () => {
+            notify();
+            if (model.fatal !== undefined)
+                resolve(model.fatal);
+        };
+        renderer.keyInput.on("keypress", (key) => {
+            if (key.ctrl && key.name === "c")
+                resolve(undefined);
+        });
+        renderer.on("destroy", () => resolve(undefined));
+    });
+}
+/** Opens a ChatSession (errors propagate before any UI exists), runs the
+ * TUI until Ctrl+C or a fatal error, then restores the terminal.
+ * Resolves with the fatal error, if any, for the caller to report. */
+export async function runInteractive(opts) {
+    const session = await ChatSession.open(opts);
+    let renderer;
+    try {
+        renderer = await (opts.createRenderer ?? (() => createCliRenderer({ exitOnCtrlC: false })))();
+    }
+    catch (err) {
+        // The session is already open; nothing else would ever close it.
+        await closeWithTimeout(session, CLOSE_TIMEOUT_MS);
+        throw err;
+    }
+    let view;
+    try {
+        const model = new ChatModel(session);
+        view = new ChatView(renderer, model, {
+            title: opts.title,
+            providerName: opts.provider.name,
+        });
+        const quit = waitForQuit(renderer, model);
+        renderer.start();
+        const fatal = await quit;
+        return fatal === undefined ? {} : { fatal };
+    }
+    finally {
+        view?.setStatus(CLOSING_STATUS);
+        const closed = await closeWithTimeout(session, CLOSE_TIMEOUT_MS);
+        view?.destroy();
+        renderer.destroy();
+        if (!closed) {
+            // The Playwright connection would keep the event loop alive forever;
+            // the terminal is restored by now, so exiting hard is safe here.
+            process.stderr.write("browser did not close within 5 s; exiting\n");
+            process.exit(1);
+        }
+    }
+}
+/** Playwright close can hang on a wedged browser; never block exit on it.
+ * Returns true when the session closed within `ms`. Close errors are
+ * swallowed: teardown must not mask the result the caller is returning. */
+export async function closeWithTimeout(session, ms) {
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), ms);
+    });
+    try {
+        return await Promise.race([
+            session.close().then(() => true, () => true),
+            deadline,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/tui/runtime-check.d.ts

@@ -0,0 +1,5 @@
+/** @opentui/core needs Bun >= 1.3 or Node >= 26.4. Bun wins when present. */
+export declare function supportsInteractive(versions: {
+    bun?: string;
+    node?: string;
+}): boolean;

package/dist/tui/runtime-check.js

@@ -0,0 +1,12 @@
+/** @opentui/core needs Bun >= 1.3 or Node >= 26.4. Bun wins when present. */
+export function supportsInteractive(versions) {
+    if (versions.bun)
+        return atLeast(versions.bun, 1, 3);
+    if (versions.node)
+        return atLeast(versions.node, 26, 4);
+    return false;
+}
+function atLeast(version, major, minor) {
+    const [a = 0, b = 0] = version.split(".").map((n) => Number.parseInt(n, 10));
+    return a > major || (a === major && b >= minor);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatbridge/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Drive browser-only web chat AI services from the command line",
   "license": "MIT",
   "repository": {
@@ -11,7 +11,8 @@
   "keywords": ["chatbridge", "cli", "playwright", "chat", "ai"],
   "type": "module",
   "engines": {
-    "node": ">=20"
+    "node": ">=20",
+    "bun": ">=1.3"
   },
   "exports": {
     ".": {
@@ -27,7 +28,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@chatbridge/core": "0.1.0"
+    "@chatbridge/core": "0.2.0",
+    "@opentui/core": "0.5.10"
   },
   "devDependencies": {
     "@chatbridge/example-dummy-chat": "0.0.0"