@chatbridge/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 7milch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @chatbridge/cli
+
+The CLI for [chatbridge](https://github.com/7milch/chatbridge-cli): drive browser-only web chat AI services from the command line.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { createCli } from "./create-cli.js";
+// Set exitCode instead of calling process.exit(): on a pipe, stdout writes are
+// asynchronous and process.exit() would drop pending output.
+process.exitCode = await createCli({ name: "chatbridge" }).run(process.argv);

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+export interface CliConfig {
+    /** Provider spec used when --provider is absent. Relative paths are
+     * already resolved against the config file's directory. */
+    defaultProvider?: string;
+}
+export interface ConfigLocation {
+    /** Directory name under the base dir, e.g. "chatbridge". */
+    configDir: string;
+    /** Base directory; defaults to ~/.config. Overridable for tests. */
+    baseDir?: string;
+}
+export declare function configPath(loc: ConfigLocation): string;
+/** Reads <base>/<configDir>/config.json. Missing file → {}. */
+export declare function loadConfig(loc: ConfigLocation): Promise<CliConfig>;

package/dist/config.js

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { ChatBridgeError } from "@chatbridge/core";
+export function configPath(loc) {
+    const base = loc.baseDir ?? join(homedir(), ".config");
+    return join(base, loc.configDir, "config.json");
+}
+function invalid(file, why, cause) {
+    return new ChatBridgeError("INVALID_CONFIG", `Invalid config ${file}: ${why}`, {
+        cause,
+    });
+}
+/** Reads <base>/<configDir>/config.json. Missing file → {}. */
+export async function loadConfig(loc) {
+    const file = configPath(loc);
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        throw invalid(file, "could not read the file", err);
+    }
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch (err) {
+        throw invalid(file, "not valid JSON", err);
+    }
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+        throw invalid(file, "top level must be a JSON object");
+    }
+    const { defaultProvider } = doc;
+    const cfg = {};
+    if (defaultProvider !== undefined) {
+        if (typeof defaultProvider !== "string") {
+            throw invalid(file, '"defaultProvider" must be a string');
+        }
+        const isRelative = defaultProvider.startsWith("./") || defaultProvider.startsWith("../");
+        cfg.defaultProvider = isRelative
+            ? resolve(dirname(file), defaultProvider)
+            : defaultProvider;
+    }
+    return cfg;
+}

package/dist/create-cli.d.ts

@@ -0,0 +1,14 @@
+import { type Provider } from "@chatbridge/core";
+export interface CreateCliOptions {
+    /** CLI name shown in help and errors, e.g. "chatbridge" or "company-ai-cli". */
+    name: string;
+    /** Pinned provider. When set, --provider is rejected and config is not read. */
+    provider?: Provider;
+    /** Config directory name under ~/.config; defaults to `name`. */
+    configDir?: string;
+    /** Test-only: overrides the config/auth-store base directory. */
+    baseDir?: string;
+}
+export declare function createCli(opts: CreateCliOptions): {
+    run: (argv: string[]) => Promise<number>;
+};

package/dist/create-cli.js

@@ -0,0 +1,160 @@
+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";
+/** Single source of truth for `ChatBridgeError.code` → process exit code. */
+const EXIT_CODES = {
+    INVALID_ARGUMENT: 1,
+    INVALID_CONFIG: 1,
+    AUTH_REQUIRED: 2,
+    AUTH_EXPIRED: 3,
+    RESPONSE_TIMEOUT: 4,
+    PROVIDER_LOAD: 5,
+    INVALID_PROVIDER: 5,
+};
+const DEFAULT_TIMEOUT_SEC = 120;
+/** Validates --timeout before any browser is launched. */
+function parseTimeoutMs(raw) {
+    if (raw === undefined)
+        return DEFAULT_TIMEOUT_SEC * 1000;
+    const seconds = Number(raw);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        throw new ChatBridgeError("INVALID_ARGUMENT", "--timeout must be a positive number of seconds");
+    }
+    return seconds * 1000;
+}
+function isParseArgsError(err) {
+    const code = err?.code;
+    return (err instanceof Error &&
+        typeof code === "string" &&
+        code.startsWith("ERR_PARSE_ARGS_"));
+}
+export function createCli(opts) {
+    const configDir = opts.configDir ?? opts.name;
+    const location = { configDir, baseDir: opts.baseDir };
+    function help() {
+        const providerFlag = opts.provider ? "" : " [--provider <name|path>]";
+        return [
+            "Usage:",
+            `  ${opts.name} -p <prompt>${providerFlag} [--headful] [--timeout <sec>]`,
+            `  ${opts.name} auth login${providerFlag}`,
+            `  ${opts.name} auth logout${providerFlag}`,
+            `  ${opts.name} auth status${providerFlag}`,
+            "",
+            "One-shot mode prints the AI response to stdout.",
+            ...(opts.provider
+                ? []
+                : [
+                    "",
+                    `Without --provider, "defaultProvider" from ${configPath(location)} is used.`,
+                ]),
+        ].join("\n");
+    }
+    // Progress goes to stderr, and only when stderr is a TTY (stdout stays
+    // pipe-safe: response body only).
+    function progress(message) {
+        if (process.stderr.isTTY)
+            process.stderr.write(`${message}\n`);
+    }
+    /** Resolution order: pinned provider → --provider → config defaultProvider. */
+    async function getProvider(flag) {
+        if (opts.provider) {
+            if (flag !== undefined) {
+                throw new ChatBridgeError("INVALID_ARGUMENT", `${opts.name} has a fixed provider; --provider is not accepted`);
+            }
+            return opts.provider;
+        }
+        const spec = flag ?? (await loadConfig(location)).defaultProvider;
+        if (!spec) {
+            throw new ProviderLoadError(`No provider specified. Pass --provider <npm-package|./path> or set "defaultProvider" in ${configPath(location)}.`);
+        }
+        return resolveProvider(spec);
+    }
+    function reportError(err) {
+        if (isParseArgsError(err)) {
+            process.stderr.write(`${opts.name}: ${err.message}\n\n${help()}\n`);
+            return 1;
+        }
+        if (err instanceof ChatBridgeError) {
+            process.stderr.write(`${opts.name}: ${err.message}\n`);
+            if (process.env.CHATBRIDGE_DEBUG === "1" && err.cause !== undefined) {
+                const cause = err.cause;
+                const detail = cause instanceof Error
+                    ? (cause.stack ?? cause.message)
+                    : String(cause);
+                process.stderr.write(`Caused by: ${detail}\n`);
+            }
+            return EXIT_CODES[err.code] ?? 1;
+        }
+        process.stderr.write(`${opts.name}: unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    async function run(argv) {
+        try {
+            const { values, positionals } = parseArgs({
+                args: argv.slice(2),
+                options: {
+                    prompt: { type: "string", short: "p" },
+                    provider: { type: "string" },
+                    headful: { type: "boolean", default: false },
+                    timeout: { type: "string" },
+                    help: { type: "boolean", short: "h", default: false },
+                },
+                allowPositionals: true,
+            });
+            if (values.help) {
+                console.log(help());
+                return 0;
+            }
+            const [cmd, sub] = positionals;
+            if (cmd === "auth" &&
+                (sub === "login" || sub === "logout" || sub === "status")) {
+                const provider = await getProvider(values.provider);
+                const authStore = createAuthStore({
+                    configDir,
+                    providerName: provider.name,
+                    baseDir: opts.baseDir,
+                });
+                if (sub === "login") {
+                    await runLogin({ provider, authStore, onProgress: progress });
+                    return 0;
+                }
+                if (sub === "logout") {
+                    await authStore.clear();
+                    progress("✓ Auth state deleted");
+                    return 0;
+                }
+                console.log(authStore.has()
+                    ? `Auth state present for "${provider.name}" (${authStore.path()})`
+                    : `No auth state for "${provider.name}"`);
+                return 0;
+            }
+            if (typeof values.prompt === "string") {
+                const timeoutMs = parseTimeoutMs(values.timeout);
+                const provider = await getProvider(values.provider);
+                const authStore = createAuthStore({
+                    configDir,
+                    providerName: provider.name,
+                    baseDir: opts.baseDir,
+                });
+                const reply = await runOneShot({
+                    provider,
+                    authStore,
+                    prompt: values.prompt,
+                    headless: !values.headful,
+                    timeoutMs,
+                    onProgress: progress,
+                });
+                // stdout: response body only.
+                process.stdout.write(`${reply}\n`);
+                return 0;
+            }
+            console.log(help());
+            return cmd === undefined ? 0 : 1;
+        }
+        catch (err) {
+            return reportError(err);
+        }
+    }
+    return { run };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createCli, type CreateCliOptions } from "./create-cli.js";
+export { resolveProvider } from "./resolve-provider.js";
+export { type CliConfig, configPath, loadConfig } from "./config.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createCli } from "./create-cli.js";
+export { resolveProvider } from "./resolve-provider.js";
+export { configPath, loadConfig } from "./config.js";

package/dist/resolve-provider.d.ts

@@ -0,0 +1,4 @@
+import { type Provider } from "@chatbridge/core";
+/** Loads a Provider from a local file path or an npm package name.
+ * The module's default export must implement the Provider interface. */
+export declare function resolveProvider(spec: string): Promise<Provider>;

package/dist/resolve-provider.js

@@ -0,0 +1,34 @@
+import { resolve } from "node:path";
+import { ProviderLoadError } from "@chatbridge/core";
+const REQUIRED_METHODS = [
+    "navigateToLogin",
+    "isLoggedIn",
+    "startNewChat",
+    "sendMessage",
+    "waitForResponse",
+];
+function isProvider(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.name === "string" &&
+        typeof v.chatUrl === "string" &&
+        REQUIRED_METHODS.every((m) => typeof v[m] === "function"));
+}
+/** Loads a Provider from a local file path or an npm package name.
+ * The module's default export must implement the Provider interface. */
+export async function resolveProvider(spec) {
+    const isPath = spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/");
+    const target = isPath ? resolve(process.cwd(), spec) : spec;
+    let mod;
+    try {
+        mod = await import(target);
+    }
+    catch (err) {
+        throw new ProviderLoadError(`Could not load provider "${spec}": ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    if (!isProvider(mod.default)) {
+        throw new ProviderLoadError(`Module "${spec}" does not default-export a Provider (name, chatUrl, and the five methods are required).`);
+    }
+    return mod.default;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@chatbridge/cli",
+  "version": "0.1.0",
+  "description": "Drive browser-only web chat AI services from the command line",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/7milch/chatbridge-cli.git",
+    "directory": "packages/cli"
+  },
+  "keywords": ["chatbridge", "cli", "playwright", "chat", "ai"],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "chatbridge": "./dist/bin.js"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@chatbridge/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@chatbridge/example-dummy-chat": "0.0.0"
+  }
+}