chatbase 0.0.1 → 0.1.1

package/bin/run.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { execute } from '@oclif/core'
+
+await execute({ dir: import.meta.url })

package/dist/base/agent-command.js

@@ -0,0 +1,40 @@
+import { Flags } from '@oclif/core';
+import { resolveAgent } from '../config/resolve.js';
+import { UsageError } from '../errors/errors.js';
+import { resolveAgentRef } from './agent-ref.js';
+import { BaseCommand } from './base-command.js';
+export class AgentCommand extends BaseCommand {
+    static baseFlags = {
+        ...BaseCommand.baseFlags,
+        agent: Flags.string({
+            char: 'a',
+            description: 'Agent ID (or set CHATBASE_AGENT_ID)'
+        }),
+        'agent-name': Flags.string({
+            description: 'Agent display name (looked up to an ID)',
+            exclusive: ['agent']
+        })
+    };
+    /**
+     * -a is always an ID (no API call). --agent-name resolves via the
+     * agents list. The two flags are mutually exclusive.
+     */
+    async agentId(flags, client) {
+        if (flags['agent-name']) {
+            const id = await resolveAgentRef(client, flags['agent-name']);
+            this.note(flags, `→ ${id}`);
+            return id;
+        }
+        const resolved = resolveAgent(flags.agent);
+        if (!resolved) {
+            throw new UsageError('No agent specified. Pass -a <agentId>, --agent-name <name>, or set CHATBASE_AGENT_ID.');
+        }
+        return resolved.value;
+    }
+    /** The "resume with: ..." trailer both chat commands print after a turn. */
+    printConversationHint(flags, agentId, conversationId) {
+        if (!conversationId)
+            return;
+        this.note(flags, `Conversation: ${conversationId} — resume with: chatbase chat -a ${agentId} --conversation ${conversationId} --resume`);
+    }
+}

package/dist/base/agent-ref.js

@@ -0,0 +1,16 @@
+import { fetchPages } from '../client/paginate.js';
+import { UsageError } from '../errors/errors.js';
+/** Resolve an --agent-name value to an ID. Fetches all pages to detect ambiguity. */
+export async function resolveAgentRef(client, name) {
+    const { items: agents } = await fetchPages((query) => client.GET('/agents', { params: { query } }), { all: true });
+    const matches = agents.filter((a) => a.name === name);
+    if (matches.length === 1)
+        return matches[0].id;
+    if (matches.length > 1) {
+        const candidates = matches
+            .map((a) => `  ${a.name} (${a.id})`)
+            .join('\n');
+        throw new UsageError(`Multiple agents are named "${name}":\n${candidates}\nUse -a with the agent ID instead.`);
+    }
+    throw new UsageError(`No agent named "${name}". Run \`chatbase agents list\` to see available agents.`);
+}

package/dist/base/assert-file.js

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import { UsageError } from '../errors/errors.js';
+/** Throws a UsageError (no network) unless filePath exists, is a regular file, and is readable. */
+export function assertFileReadable(filePath) {
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        throw new UsageError(`File not found: ${filePath}`);
+    }
+    if (!stat.isFile()) {
+        throw new UsageError(`Not a regular file: ${filePath}`);
+    }
+    try {
+        fs.accessSync(filePath, fs.constants.R_OK);
+    }
+    catch {
+        throw new UsageError(`File is not readable: ${filePath}`);
+    }
+}

package/dist/base/base-command.js

@@ -0,0 +1,203 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Command, Errors, Flags } from '@oclif/core';
+import { createApiClient, DEFAULT_BASE_URL, resolveBaseUrl } from '../client/client.js';
+import { installSigintHandler, wasInterrupted } from '../client/signals.js';
+import { logsDir } from '../config/paths.js';
+import { resolveApiKey, resolveTimeoutMs } from '../config/resolve.js';
+import { ApiError, formatApiError, UsageError } from '../errors/errors.js';
+import { colorEnabled, paint } from '../output/color.js';
+import { selectMode } from '../output/mode.js';
+import { renderPlain, renderTable } from '../output/render.js';
+const ISSUES_URL = 'https://github.com/Chatbase-co/chatbase-cli/issues/new';
+/** True for parser/validation errors oclif itself raises (unknown flag, bad --limit, etc). */
+function isCliError(err) {
+    if (err instanceof Errors.CLIError)
+        return true;
+    const withOclif = err;
+    return typeof withOclif?.oclif?.exit === 'number';
+}
+function isFetchFailure(err) {
+    return err instanceof TypeError && /fetch failed/i.test(err.message);
+}
+function networkErrorCode(err) {
+    const cause = err.cause;
+    return cause?.code ?? cause?.errors?.[0]?.code;
+}
+/** True for fetch's AbortSignal.timeout() firing (a TimeoutError DOMException). */
+function isTimeoutError(err) {
+    const e = err;
+    if (e?.name === 'TimeoutError')
+        return true;
+    if (typeof DOMException !== 'undefined' && err instanceof DOMException) {
+        return /timeout/i.test(e?.message ?? '');
+    }
+    return false;
+}
+export function classifyError(err) {
+    if (err instanceof UsageError)
+        return { kind: 'usage', error: err };
+    if (err instanceof ApiError)
+        return { kind: 'api', error: err };
+    if (isCliError(err))
+        return { kind: 'cli', error: err };
+    if (isTimeoutError(err))
+        return { kind: 'timeout' };
+    if (isFetchFailure(err))
+        return { kind: 'network', code: networkErrorCode(err) };
+    const name = err?.name;
+    if (name === 'AbortError') {
+        return wasInterrupted() ? { kind: 'interrupted' } : { kind: 'timeout' };
+    }
+    return { kind: 'unexpected', error: err };
+}
+/** -f key=value body fields — spread into the flags of commands that send a
+ * JSON request body (not part of baseFlags: advertising -f on body-less
+ * commands like `health` was just noise in --help). */
+export const bodyFieldFlags = {
+    field: Flags.string({
+        char: 'f',
+        multiple: true,
+        description: 'Set a body field: -f key=value (repeatable)'
+    })
+};
+export class BaseCommand extends Command {
+    static baseFlags = {
+        json: Flags.boolean({
+            description: 'Output raw API JSON',
+            helpGroup: 'OUTPUT'
+        }),
+        plain: Flags.boolean({
+            description: 'Tab-separated output for scripts',
+            helpGroup: 'OUTPUT'
+        }),
+        quiet: Flags.boolean({
+            char: 'q',
+            description: 'Suppress non-essential output'
+        }),
+        verbose: Flags.boolean({ description: 'Verbose diagnostics' }),
+        'no-input': Flags.boolean({
+            description: 'Never prompt; fail instead'
+        }),
+        'no-color': Flags.boolean({ description: 'Disable colored output' })
+    };
+    requireAuth = true;
+    async init() {
+        await super.init();
+        installSigintHandler();
+    }
+    mode(flags) {
+        return selectMode(flags, process.stdout);
+    }
+    palette(flags) {
+        return paint(colorEnabled(process.stderr, flags['no-color']));
+    }
+    note(flags, msg) {
+        if (!flags.quiet)
+            process.stderr.write(`${msg}\n`);
+    }
+    success(flags, msg) {
+        this.note(flags, `${this.palette(flags).green('✓')} ${msg}`);
+    }
+    printData(flags, raw, rows, columns) {
+        const mode = this.mode(flags);
+        if (mode === 'json') {
+            process.stdout.write(`${JSON.stringify(raw, null, 2)}\n`);
+            return;
+        }
+        if (rows.length === 0) {
+            this.note(flags, 'No results.');
+            return;
+        }
+        if (mode === 'plain') {
+            process.stdout.write(`${renderPlain(rows, columns)}\n`);
+        }
+        else {
+            process.stdout.write(`${renderTable(rows, columns)}\n`);
+        }
+    }
+    printDetail(flags, raw, row, columns, detail) {
+        if (this.mode(flags) !== 'pretty') {
+            this.printData(flags, raw, [row], columns);
+            return;
+        }
+        const shown = detail.filter(([, value]) => value !== '');
+        const width = Math.max(...shown.map(([label]) => label.length));
+        process.stdout.write(`${shown.map(([label, value]) => `${label.padEnd(width + 2)}${value}`).join('\n')}\n`);
+    }
+    apiClient(flags) {
+        const resolved = resolveApiKey();
+        if (!resolved && this.requireAuth) {
+            throw new UsageError('Not authenticated. Run `chatbase auth login`, or set CHATBASE_API_KEY.');
+        }
+        return createApiClient({
+            apiKey: resolved?.value,
+            verbose: flags.verbose
+        });
+    }
+    async catch(err) {
+        const flags = {
+            'no-color': process.argv.includes('--no-color')
+        };
+        const classified = classifyError(err);
+        if (classified.kind === 'usage') {
+            process.stderr.write(`${classified.error.message}\n`);
+            this.exit(2);
+        }
+        if (classified.kind === 'api') {
+            if (process.argv.includes('--json')) {
+                const { code, message, details, requestId, status } = classified.error;
+                process.stderr.write(`${JSON.stringify({ error: { code, message, details }, requestId, status }, null, 2)}\n`);
+            }
+            else {
+                process.stderr.write(`${formatApiError(classified.error, this.palette(flags))}\n`);
+            }
+            this.exit(1);
+        }
+        if (classified.kind === 'cli') {
+            await super.catch(classified.error);
+            this.exit(classified.error.oclif?.exit ?? 2);
+        }
+        if (classified.kind === 'interrupted') {
+            this.exit(130);
+        }
+        if (classified.kind === 'timeout') {
+            process.stderr.write(`✗ Request timed out after ${resolveTimeoutMs()}ms (set CHATBASE_TIMEOUT to change)\n`);
+            this.exit(1);
+        }
+        if (classified.kind === 'network') {
+            const base = resolveBaseUrl();
+            process.stderr.write(`✗ Network error: could not reach ${base}${classified.code ? ` (${classified.code})` : ''}\n`);
+            process.stderr.write(base === DEFAULT_BASE_URL
+                ? '  Check your internet connection and retry.\n'
+                : '  CHATBASE_API_URL is overriding the API base — check that value first.\n');
+            this.exit(1);
+        }
+        // Server returned HTML instead of JSON — usually a wrong base URL
+        // hitting a web page instead of the API.
+        const msg = err?.message ?? '';
+        if (err instanceof SyntaxError &&
+            (msg.includes('<!DOCTYPE') || msg.includes('is not valid JSON'))) {
+            const base = resolveBaseUrl();
+            process.stderr.write(`✗ The API returned an unexpected response.\n` +
+                `  Current base: ${base}\n` +
+                `  Check that CHATBASE_API_URL is correct and the endpoint exists on this host.\n`);
+            this.exit(1);
+        }
+        // Unexpected: short message + full detail to a log file + pre-filled issue URL.
+        const logFile = path.join(logsDir(), `error-${Date.now()}.log`);
+        try {
+            fs.mkdirSync(logsDir(), { recursive: true });
+            fs.writeFileSync(logFile, String(err?.stack ?? err));
+        }
+        catch {
+            /* logging must never mask the original failure */
+        }
+        const title = encodeURIComponent(`bug: ${err?.message ?? 'unexpected error'}`);
+        const body = encodeURIComponent(`CLI: chatbase ${this.config.version}\nOS: ${process.platform}-${process.arch}\nNode: ${process.versions.node}\nCommand: ${this.id}\n`);
+        process.stderr.write(`✗ Unexpected error: ${err?.message ?? err}\n`);
+        process.stderr.write(`  details: ${logFile}\n`);
+        process.stderr.write(`  report: ${ISSUES_URL}?title=${title}&body=${body}\n`);
+        this.exit(1);
+    }
+}

package/dist/base/body-input.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import { UsageError } from '../errors/errors.js';
+/** Read all of stdin as a UTF-8 string, verbatim — @- must match @file's
+ * fidelity (fs.readFileSync returns exact bytes too). Callers that want
+ * trimmed input (a pasted key, a chat message) trim it themselves. */
+export async function readStdinToEnd() {
+    let raw = '';
+    // setEncoding before iterating makes Node decode UTF-8 across chunk
+    // boundaries; without it each Buffer chunk is coerced to a string
+    // independently, corrupting multi-byte characters split mid-chunk.
+    process.stdin.setEncoding('utf8');
+    for await (const chunk of process.stdin)
+        raw += chunk;
+    return raw;
+}
+/**
+ * Resolve @file, @- (stdin), or a literal string into its text content.
+ * Shared core for both readBodyData (JSON) and readTextInput (free text).
+ */
+async function resolveInput(value, flagName) {
+    if (value === '@-') {
+        if (process.stdin.isTTY)
+            throw new UsageError(`${flagName} @- expects piped stdin.`);
+        return readStdinToEnd();
+    }
+    if (value.startsWith('@')) {
+        const filePath = value.slice(1);
+        if (!filePath) {
+            throw new UsageError(`${flagName} @ requires a filename: ${flagName} @path/to/file`);
+        }
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    return value;
+}
+/** Parse -f key=value pairs into an object. Flat strings only. */
+export function parseFields(fields) {
+    if (!fields?.length)
+        return {};
+    const result = {};
+    for (const pair of fields) {
+        const eq = pair.indexOf('=');
+        if (eq < 1) {
+            throw new UsageError(`-f expects key=value, got "${pair}"`);
+        }
+        result[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return result;
+}
+/** Build the request body: --data (base) → -f fields (override). */
+export async function readBodyData(data, fields) {
+    let base = {};
+    if (data) {
+        const raw = await resolveInput(data, '--data');
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new UsageError('--data must be valid JSON (inline, @file, or @-).');
+        }
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            const extra = parseFields(fields);
+            if (Object.keys(extra).length > 0) {
+                throw new UsageError('-f cannot be combined with a non-object --data value.');
+            }
+            return parsed;
+        }
+        base = parsed;
+    }
+    return { ...base, ...parseFields(fields) };
+}
+/** Resolve a flag value via the same @file/@- indirection, without JSON parsing. */
+export async function readTextInput(value, flagName = '--content') {
+    return resolveInput(value, flagName);
+}

package/dist/base/list-command.js

@@ -0,0 +1,16 @@
+import { Flags } from '@oclif/core';
+import { AgentCommand } from './agent-command.js';
+export class ListCommand extends AgentCommand {
+    static baseFlags = {
+        ...AgentCommand.baseFlags,
+        limit: Flags.integer({
+            description: 'Maximum items per page',
+            min: 1,
+            max: 100
+        }),
+        cursor: Flags.string({
+            description: 'Pagination cursor from a previous page'
+        }),
+        all: Flags.boolean({ description: 'Fetch every page' })
+    };
+}

package/dist/base/sources.js

@@ -0,0 +1,33 @@
+export const SOURCE_COLUMNS = [
+    { key: 'id', header: 'ID' },
+    { key: 'name', header: 'NAME' },
+    { key: 'type', header: 'TYPE' },
+    { key: 'status', header: 'STATUS' },
+    { key: 'size', header: 'SIZE' }
+];
+const READY = new Set(['trained']);
+const PENDING = new Set(['untrained', 'updated', 'toBeDeleted']);
+const REMOVED = new Set(['deleted']);
+/** Pretty-mode glyph: ✓ trained, … in progress, ✗ deleted. */
+export function renderStatus(status, mode) {
+    if (mode !== 'pretty')
+        return status;
+    const key = status.toLowerCase();
+    if (READY.has(key))
+        return `✓ ${status}`;
+    if (PENDING.has(key))
+        return `… ${status}`;
+    if (REMOVED.has(key))
+        return `✗ ${status}`;
+    return status;
+}
+/** Maps one raw API source object to a display row for SOURCE_COLUMNS. */
+export function toSourceRow(s, mode) {
+    return {
+        id: String(s.id ?? ''),
+        name: String(s.name ?? ''),
+        type: String(s.type ?? ''),
+        status: renderStatus(String(s.status ?? ''), mode),
+        size: String(s.size ?? '')
+    };
+}

package/dist/client/chat-helpers.js

@@ -0,0 +1,173 @@
+import { ApiError } from '../errors/errors.js';
+import { maybeSpinner } from '../output/spinner.js';
+import { throwIfError } from './client.js';
+import { parseSseStream } from './stream.js';
+/**
+ * Strips C0/C1 control characters (keeping only \t and \n) from text that
+ * came back from the API. Agent replies and replayed user messages are
+ * attacker-influenceable, and raw ESC/OSC bytes reaching a terminal are an
+ * injection primitive (OSC 52 clipboard writes, cursor/erase spoofing, \r
+ * line overwrites). Safe to apply per streamed chunk: removing the ESC byte
+ * defuses a sequence even when it is split across two deltas — the tail
+ * prints as inert ASCII. `--json` output is unaffected (JSON.stringify
+ * already escapes these), so raw fidelity remains available.
+ */
+export function sanitizeAgentText(text) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control characters is the point
+    return text.replace(/[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g, '');
+}
+/**
+ * Joins every `text` part of a non-streaming ChatResponse into one string.
+ * Tool-call/tool-result parts are skipped.
+ */
+export function extractText(envelope) {
+    return sanitizeAgentText(envelope.data.parts
+        .filter((part) => part.type === 'text')
+        .map((part) => part.text)
+        .join(''));
+}
+/** Shared response handling for both sendChat and retryChat. `emptyMessage`
+ * names the caller in the error for the one failure this function can't
+ * recover from (a 2xx non-streaming response with no body) — thrown once
+ * here instead of every caller re-checking `!result.raw`. */
+async function handleResponse(data, error, response, stream, onText, emptyMessage) {
+    if (!stream) {
+        throwIfError(response, error);
+        const raw = data;
+        if (!raw)
+            throw new Error(emptyMessage);
+        return {
+            stream: false,
+            raw,
+            conversationId: raw.data?.metadata?.conversationId,
+            messageId: raw.data?.id
+        };
+    }
+    // With parseAs: 'stream', openapi-fetch drains the body into `error`
+    // on non-2xx — re-reading response.json() would throw (already consumed).
+    if (!response.ok)
+        throwIfError(response, error);
+    const body = data;
+    if (!body)
+        throw new Error('Stream response had no body');
+    let conversationId;
+    let messageId;
+    let streamError;
+    await parseSseStream(body, (event) => {
+        if (event.type === 'text')
+            onText(sanitizeAgentText(event.text));
+        if (event.type === 'metadata') {
+            conversationId = event.conversationId ?? conversationId;
+            messageId = event.messageId ?? messageId;
+        }
+        if (event.type === 'warning') {
+            process.stderr.write(`! ${event.message} — response may be incomplete\n`);
+        }
+        if (event.type === 'error')
+            streamError = event.message;
+    });
+    // Throwing AFTER the stream drains keeps parseSseStream's reader
+    // cleanup on its normal path and lets text that arrived before the
+    // failure still reach the user. The response was already 200 when the
+    // failure happened, so this mid-stream event is the only error signal.
+    if (streamError) {
+        throw new ApiError({
+            code: 'STREAM_ERROR',
+            message: sanitizeAgentText(streamError),
+            status: 200
+        });
+    }
+    return { stream: true, conversationId, messageId };
+}
+/**
+ * The one-shot chat/retry turn both commands share: spinner for the
+ * non-streaming wait, run `call`, then print the result — streamed tokens
+ * already went to stdout, so finish the line; otherwise print the JSON
+ * envelope or the extracted plain text.
+ */
+export async function runChatTurn(opts) {
+    const stop = maybeSpinner(opts.stream || opts.quiet, 'Thinking…', 300);
+    let result;
+    try {
+        result = await opts.call(opts.stream ? (text) => process.stdout.write(text) : () => { });
+    }
+    finally {
+        stop();
+    }
+    if (result.stream) {
+        process.stdout.write('\n');
+    }
+    else if (opts.json) {
+        process.stdout.write(`${JSON.stringify(result.raw, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(`${extractText(result.raw)}\n`);
+    }
+    return result;
+}
+/** Send a message. Shared by the chat command, the REPL, and chat retry. */
+export async function sendChat(opts) {
+    const { data, error, response } = await opts.client.POST('/agents/{agentId}/chat', {
+        params: { path: { agentId: opts.agentId } },
+        body: {
+            message: opts.message,
+            conversationId: opts.conversationId,
+            stream: opts.stream
+        },
+        parseAs: opts.stream ? 'stream' : 'json',
+        signal: opts.signal
+    });
+    return handleResponse(data, error, response, opts.stream, opts.onText, 'Chat response was empty');
+}
+/** Retry generating a response for a specific message. */
+export async function retryChat(opts) {
+    const { data, error, response } = await opts.client.POST('/agents/{agentId}/conversations/{conversationId}/retry', {
+        params: {
+            path: {
+                agentId: opts.agentId,
+                conversationId: opts.conversationId
+            }
+        },
+        body: {
+            messageId: opts.messageId,
+            stream: opts.stream
+        },
+        parseAs: opts.stream ? 'stream' : 'json',
+        signal: opts.signal
+    });
+    return handleResponse(data, error, response, opts.stream, opts.onText, 'Retry response was empty');
+}
+/**
+ * Fetches the last `count` messages of a conversation, oldest first, for
+ * the --resume banner. Non-text parts are skipped; long messages are
+ * truncated — this is orientation, not a transcript.
+ */
+export async function fetchRecentHistory(opts) {
+    const count = opts.count ?? 6;
+    const maxChars = opts.maxChars ?? 200;
+    const { data, error, response } = await opts.client.GET('/agents/{agentId}/conversations/{conversationId}/messages', {
+        params: {
+            path: {
+                agentId: opts.agentId,
+                conversationId: opts.conversationId
+            },
+            query: {}
+        }
+    });
+    throwIfError(response, error);
+    const items = data?.data ?? [];
+    return items.slice(-count).map((m) => {
+        const msg = m;
+        const text = sanitizeAgentText((msg.parts ?? [])
+            .filter((p) => p.type === 'text' && typeof p.text === 'string')
+            .map((p) => p.text)
+            .join(''))
+            .replace(/\s+/g, ' ')
+            .trim();
+        return {
+            id: msg.id ?? '',
+            role: msg.role ?? 'unknown',
+            text: text.length > maxChars ? `${text.slice(0, maxChars)}…` : text
+        };
+    });
+}