chatbase 0.0.1 → 0.1.0

package/dist/commands/tickets/get.js

@@ -0,0 +1,44 @@
+import { Args } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+const COLUMNS = [
+    { key: 'ticketNumber', header: 'TICKET' },
+    { key: 'subject', header: 'SUBJECT' },
+    { key: 'statusCategory', header: 'STATUS' },
+    { key: 'channel', header: 'CHANNEL' },
+    { key: 'createdAt', header: 'CREATED' }
+];
+export default class TicketsGet extends AgentCommand {
+    static description = 'Show one helpdesk ticket';
+    static examples = ['<%= config.bin %> tickets get 42 -a agt_123'];
+    static args = {
+        ticketNumber: Args.integer({
+            required: true,
+            description: 'Ticket number'
+        })
+    };
+    static flags = { ...AgentCommand.baseFlags };
+    async run() {
+        const { args, flags } = await this.parse(TicketsGet);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.GET('/agents/{agentId}/helpdesk/tickets/{ticketNumber}', {
+            params: {
+                path: { agentId, ticketNumber: args.ticketNumber }
+            }
+        });
+        throwIfError(response, error);
+        // GET .../tickets/{ticketNumber} returns the Ticket directly (no
+        // {data, pagination} envelope) — --json prints it as-is.
+        const ticket = data;
+        this.printData(flags, data, [
+            {
+                ticketNumber: String(ticket.ticketNumber ?? ''),
+                subject: String(ticket.subject ?? ''),
+                statusCategory: String(ticket.statusCategory ?? ''),
+                channel: String(ticket.channel ?? ''),
+                createdAt: String(ticket.createdAt ?? '')
+            }
+        ], COLUMNS);
+    }
+}

package/dist/commands/tickets/list.js

@@ -0,0 +1,96 @@
+import { Flags } from '@oclif/core';
+import { ListCommand } from '../../base/list-command.js';
+import { fetchPages } from '../../client/paginate.js';
+const COLUMNS = [
+    { key: 'ticketNumber', header: 'TICKET' },
+    { key: 'subject', header: 'SUBJECT' },
+    { key: 'statusCategory', header: 'STATUS' },
+    { key: 'channel', header: 'CHANNEL' },
+    { key: 'createdAt', header: 'CREATED' }
+];
+export default class TicketsList extends ListCommand {
+    static description = 'List helpdesk tickets for an agent';
+    static examples = [
+        '<%= config.bin %> tickets list -a agt_123',
+        '<%= config.bin %> tickets list -a agt_123 --status new,on_you',
+        '<%= config.bin %> tickets list -a agt_123 --all --json'
+    ];
+    static flags = {
+        ...ListCommand.baseFlags,
+        status: Flags.string({
+            description: 'Filter by status (comma-separated): new, on_you, on_customer, on_hold, closed, cancelled'
+        }),
+        channel: Flags.string({
+            description: 'Filter by channel (comma-separated, e.g. email,api)'
+        }),
+        'assignee-id': Flags.string({
+            description: 'Filter by assignee UUID, or "none" for unassigned'
+        }),
+        'team-id': Flags.string({
+            description: 'Filter by team UUID, or "none" for no team'
+        }),
+        'created-after': Flags.string({
+            description: 'Only tickets created after this ISO 8601 date'
+        }),
+        'created-before': Flags.string({
+            description: 'Only tickets created before this ISO 8601 date'
+        }),
+        'sort-by': Flags.string({
+            description: 'Sort field',
+            options: ['createdAt', 'updatedAt', 'lastMessageAt']
+        }),
+        order: Flags.string({
+            description: 'Sort direction',
+            options: ['asc', 'desc']
+        }),
+        'include-total': Flags.boolean({
+            description: 'Include pagination.total in the response'
+        })
+    };
+    async run() {
+        const { flags } = await this.parse(TicketsList);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const extraQuery = {};
+        if (flags.status)
+            extraQuery.status = flags.status;
+        if (flags.channel)
+            extraQuery.channel = flags.channel;
+        if (flags['assignee-id'])
+            extraQuery.assigneeId = flags['assignee-id'];
+        if (flags['team-id'])
+            extraQuery.teamId = flags['team-id'];
+        if (flags['created-after'])
+            extraQuery.createdAfter = flags['created-after'];
+        if (flags['created-before'])
+            extraQuery.createdBefore = flags['created-before'];
+        if (flags['sort-by'])
+            extraQuery.sortBy = flags['sort-by'];
+        if (flags.order)
+            extraQuery.order = flags.order;
+        if (flags['include-total'])
+            extraQuery.includeTotal = true;
+        const { pages, items } = await fetchPages((query) => client.GET('/agents/{agentId}/helpdesk/tickets', {
+            params: {
+                path: { agentId },
+                query: { ...query, ...extraQuery }
+            }
+        }), { limit: flags.limit, cursor: flags.cursor, all: flags.all });
+        const rows = items.map((t) => ({
+            ticketNumber: String(t.ticketNumber ?? ''),
+            subject: String(t.subject ?? ''),
+            statusCategory: String(t.statusCategory ?? ''),
+            channel: String(t.channel ?? ''),
+            createdAt: String(t.createdAt ?? '')
+        }));
+        const last = pages.at(-1);
+        // --json must stay the raw API shape even when --all merges pages
+        const raw = pages.length === 1
+            ? pages[0]
+            : { data: items, pagination: last?.pagination };
+        this.printData(flags, raw, rows, COLUMNS);
+        if (!flags.all && last?.pagination.hasMore && last.pagination.cursor) {
+            this.note(flags, `More results: rerun with --cursor ${last.pagination.cursor} (or use --all)`);
+        }
+    }
+}

package/dist/commands/tickets/messages.js

@@ -0,0 +1,87 @@
+import { Args, Flags } from '@oclif/core';
+import { ListCommand } from '../../base/list-command.js';
+import { fetchPages } from '../../client/paginate.js';
+import { UsageError } from '../../errors/errors.js';
+const COLUMNS = [
+    { key: 'id', header: 'ID' },
+    { key: 'type', header: 'TYPE' },
+    { key: 'sender', header: 'SENDER' },
+    { key: 'content', header: 'CONTENT' },
+    { key: 'createdAt', header: 'CREATED' }
+];
+function senderLabel(sender) {
+    if (!sender)
+        return '';
+    return sender.name ?? sender.email ?? sender.type ?? '';
+}
+export default class TicketsMessages extends ListCommand {
+    static description = "List a ticket's message thread";
+    static examples = [
+        '<%= config.bin %> tickets messages 42 -a agt_123',
+        '<%= config.bin %> tickets messages 42 -a agt_123 --all --json'
+    ];
+    static args = {
+        ticketNumber: Args.integer({
+            required: false,
+            description: 'Ticket number (alternative to --ticket)'
+        })
+    };
+    static flags = {
+        ...ListCommand.baseFlags,
+        ticket: Flags.integer({
+            description: 'Ticket number'
+        }),
+        types: Flags.string({
+            description: 'Message types to include (comma-separated): reply, note, event (default: reply,note)'
+        }),
+        order: Flags.string({
+            description: 'Sort direction',
+            options: ['asc', 'desc']
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsMessages);
+        // Positional and flag are alternatives — `tickets get <n>` and
+        // `tickets update <n>` set the positional convention, the flag
+        // predates it and stays supported.
+        const ticketNumber = args.ticketNumber ?? flags.ticket;
+        if (ticketNumber === undefined) {
+            throw new UsageError('Missing ticket number. Pass it positionally (`tickets messages <number>`) or via --ticket.');
+        }
+        if (args.ticketNumber !== undefined && flags.ticket !== undefined) {
+            throw new UsageError('Pass the ticket number either positionally or via --ticket, not both.');
+        }
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const extraQuery = {};
+        if (flags.types)
+            extraQuery.types = flags.types;
+        if (flags.order)
+            extraQuery.order = flags.order;
+        const { pages, items } = await fetchPages((query) => client.GET('/agents/{agentId}/helpdesk/tickets/{ticketNumber}/messages', {
+            params: {
+                path: {
+                    agentId,
+                    ticketNumber
+                },
+                query: { ...query, ...extraQuery }
+            }
+        }), { limit: flags.limit, cursor: flags.cursor, all: flags.all });
+        const rows = items.map((m) => ({
+            id: String(m.id ?? ''),
+            type: String(m.type ?? ''),
+            sender: senderLabel(m.sender),
+            content: String(m.contentText ?? m.content ?? ''),
+            createdAt: String(m.createdAt ?? '')
+        }));
+        const last = pages.at(-1);
+        // --json must stay the raw API shape even when --all merges pages
+        const raw = pages.length === 1
+            ? pages[0]
+            : { data: items, pagination: last?.pagination };
+        this.printData(flags, raw, rows, COLUMNS);
+        if (!flags.all && last?.pagination.hasMore && last.pagination.cursor) {
+            this.note(flags, `More results: rerun with --cursor ${last.pagination.cursor} (or use --all)`);
+        }
+    }
+}

package/dist/commands/tickets/reply.js

@@ -0,0 +1,66 @@
+import { Args, Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+import { UsageError } from '../../errors/errors.js';
+export default class TicketsReply extends AgentCommand {
+    static description = "Post an agent reply to a ticket's message thread";
+    static examples = [
+        '<%= config.bin %> tickets reply 42 -m "On it" --author-email sam@example.com -a agt_123'
+    ];
+    static args = {
+        ticketNumber: Args.integer({
+            required: false,
+            description: 'Ticket number (alternative to --ticket)'
+        })
+    };
+    static flags = {
+        ...AgentCommand.baseFlags,
+        ticket: Flags.integer({
+            description: 'Ticket number'
+        }),
+        message: Flags.string({
+            char: 'm',
+            required: true,
+            description: 'Reply body as GitHub-flavored Markdown'
+        }),
+        'author-id': Flags.string({
+            description: 'Platform user id of the team member the reply is attributed to (exactly one of --author-id/--author-email)',
+            exactlyOne: ['author-id', 'author-email']
+        }),
+        'author-email': Flags.string({
+            description: 'Email of the team member the reply is attributed to (exactly one of --author-id/--author-email)',
+            exactlyOne: ['author-id', 'author-email']
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsReply);
+        // Positional and flag are alternatives — `tickets get <n>` and
+        // `tickets update <n>` set the positional convention, the flag
+        // predates it and stays supported.
+        const ticketNumber = args.ticketNumber ?? flags.ticket;
+        if (ticketNumber === undefined) {
+            throw new UsageError('Missing ticket number. Pass it positionally (`tickets reply <number>`) or via --ticket.');
+        }
+        if (args.ticketNumber !== undefined && flags.ticket !== undefined) {
+            throw new UsageError('Pass the ticket number either positionally or via --ticket, not both.');
+        }
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const body = {
+            type: 'reply',
+            content: flags.message,
+            ...(flags['author-id'] ? { authorId: flags['author-id'] } : {}),
+            ...(flags['author-email']
+                ? { authorEmail: flags['author-email'] }
+                : {})
+        };
+        const { error, response } = await client.POST('/agents/{agentId}/helpdesk/tickets/{ticketNumber}/messages', {
+            params: {
+                path: { agentId, ticketNumber }
+            },
+            body
+        });
+        throwIfError(response, error);
+        this.success(flags, `Reply posted to ticket ${ticketNumber}`);
+    }
+}

package/dist/commands/tickets/search.js

@@ -0,0 +1,53 @@
+import { Args, Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+const COLUMNS = [
+    { key: 'ticketNumber', header: 'TICKET' },
+    { key: 'subject', header: 'SUBJECT' },
+    { key: 'statusCategory', header: 'STATUS' },
+    { key: 'channel', header: 'CHANNEL' },
+    { key: 'createdAt', header: 'CREATED' }
+];
+export default class TicketsSearch extends AgentCommand {
+    static description = 'Search tickets by message content';
+    static examples = [
+        '<%= config.bin %> tickets search "refund not received" -a agt_123',
+        '<%= config.bin %> tickets search "refund" -a agt_123 --limit 10 --json'
+    ];
+    static args = {
+        query: Args.string({
+            required: true,
+            description: 'Free-text search terms (matched against ticket messages)'
+        })
+    };
+    static flags = {
+        ...AgentCommand.baseFlags,
+        limit: Flags.integer({
+            description: 'Number of results (1–50, default 20)',
+            min: 1,
+            max: 50
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsSearch);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.POST('/agents/{agentId}/helpdesk/tickets/search', {
+            params: { path: { agentId } },
+            body: {
+                query: args.query,
+                limit: flags.limit ?? 20
+            }
+        });
+        throwIfError(response, error);
+        const result = data;
+        const rows = result.data.map((t) => ({
+            ticketNumber: String(t.ticketNumber ?? ''),
+            subject: String(t.subject ?? ''),
+            statusCategory: String(t.statusCategory ?? ''),
+            channel: String(t.channel ?? ''),
+            createdAt: String(t.createdAt ?? '')
+        }));
+        this.printData(flags, data, rows, COLUMNS);
+    }
+}

package/dist/commands/tickets/update.js

@@ -0,0 +1,38 @@
+import { Args, Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { bodyFieldFlags } from '../../base/base-command.js';
+import { readBodyData } from '../../base/body-input.js';
+import { throwIfError } from '../../client/client.js';
+export default class TicketsUpdate extends AgentCommand {
+    static description = "Update a ticket's status, assignee, and/or team";
+    static examples = [
+        '<%= config.bin %> tickets update 42 --data \'{"statusCategory":"closed"}\' -a agt_123'
+    ];
+    static args = {
+        ticketNumber: Args.integer({
+            required: true,
+            description: 'Ticket number'
+        })
+    };
+    static flags = {
+        ...AgentCommand.baseFlags,
+        ...bodyFieldFlags,
+        data: Flags.string({
+            description: 'JSON body (@file, @-, or inline). Fields: statusId, statusCategory, assigneeId, assigneeEmail, teamId'
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsUpdate);
+        const body = await readBodyData(flags.data, flags.field);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { error, response } = await client.PATCH('/agents/{agentId}/helpdesk/tickets/{ticketNumber}', {
+            params: {
+                path: { agentId, ticketNumber: args.ticketNumber }
+            },
+            body: body
+        });
+        throwIfError(response, error);
+        this.success(flags, `Updated ticket ${args.ticketNumber}`);
+    }
+}

package/dist/config/paths.js

@@ -0,0 +1,22 @@
+/**
+ * Every path the CLI touches on disk, per the XDG Base Directory spec —
+ * config (user-created, not regenerable), state/logs (machine-generated
+ * history), cache (disposable — cleanup tools may purge it anytime).
+ * These three directories are the CLI's ENTIRE disk footprint; the README's
+ * uninstall instructions promise exactly them, so never write anywhere else.
+ *
+ * Deliberate choices: XDG applies on macOS too (matching `gh`, not
+ * ~/Library), and these are functions rather than constants because the
+ * env overrides must be read at call time — tests stub XDG_* per test.
+ */
+import os from 'node:os';
+import path from 'node:path';
+function xdg(envVar, fallback) {
+    const v = process.env[envVar];
+    return v && v.length > 0 ? v : path.join(os.homedir(), fallback);
+}
+export const configDir = () => path.join(xdg('XDG_CONFIG_HOME', '.config'), 'chatbase');
+export const configFile = () => path.join(configDir(), 'config.json');
+export const stateDir = () => path.join(xdg('XDG_STATE_HOME', '.local/state'), 'chatbase');
+export const logsDir = () => path.join(stateDir(), 'logs');
+export const cacheDir = () => path.join(xdg('XDG_CACHE_HOME', '.cache'), 'chatbase');

package/dist/config/resolve.js

@@ -0,0 +1,37 @@
+import { readUserConfig } from './store.js';
+export function resolveApiKey() {
+    const env = process.env.CHATBASE_API_KEY;
+    if (env && env.length > 0)
+        return { value: env, source: 'CHATBASE_API_KEY' };
+    const stored = readUserConfig().apiKey;
+    if (stored)
+        return { value: stored, source: 'user config' };
+    return undefined;
+}
+export function resolveAgent(flag) {
+    if (flag)
+        return { value: flag, source: 'flag' };
+    const env = process.env.CHATBASE_AGENT_ID;
+    if (env && env.length > 0)
+        return { value: env, source: 'CHATBASE_AGENT_ID' };
+    const stored = readUserConfig().agent;
+    if (stored)
+        return { value: stored, source: 'user config' };
+    return undefined;
+}
+export function resolveTimeoutMs() {
+    const env = process.env.CHATBASE_TIMEOUT;
+    if (env && /^\d+$/.test(env))
+        return Number(env);
+    return readUserConfig().timeoutMs ?? 30000;
+}
+/** Where resolveTimeoutMs()'s value came from — split out for `config get/list`,
+ * which need to name the source without duplicating the precedence logic above. */
+export function resolveTimeoutSource() {
+    const env = process.env.CHATBASE_TIMEOUT;
+    if (env && /^\d+$/.test(env))
+        return 'CHATBASE_TIMEOUT';
+    if (readUserConfig().timeoutMs !== undefined)
+        return 'user config';
+    return 'default';
+}

package/dist/config/store.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { configDir, configFile } from './paths.js';
+export function readUserConfig() {
+    let contents;
+    try {
+        contents = fs.readFileSync(configFile(), 'utf8');
+    }
+    catch {
+        return {};
+    }
+    try {
+        return JSON.parse(contents);
+    }
+    catch {
+        fs.rmSync(configFile(), { force: true });
+        return {};
+    }
+}
+/**
+ * Atomic write: full JSON into a temp file, then rename over config.json.
+ * A crash/Ctrl-C at any line leaves either the complete old file or the
+ * complete new one — never a truncated config holding half an API key.
+ *
+ * Load-bearing details: the temp file MUST live in the destination
+ * directory (rename is only atomic within one filesystem — /tmp may be
+ * another); the PID suffix keeps concurrent CLI processes from clobbering
+ * each other's in-flight writes. Modes: dir 0700 / file 0600, since this
+ * file stores the credential.
+ */
+export function writeUserConfig(config) {
+    fs.mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    const tmp = path.join(configDir(), `.config.json.tmp-${process.pid}`);
+    fs.writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, {
+        mode: 0o600
+    });
+    fs.renameSync(tmp, configFile());
+}

package/dist/errors/errors.js

@@ -0,0 +1,81 @@
+export class UsageError extends Error {
+}
+export class ApiError extends Error {
+    code;
+    status;
+    requestId;
+    details;
+    remediation;
+    constructor(opts) {
+        super(opts.message);
+        this.code = opts.code;
+        this.status = opts.status;
+        this.requestId = opts.requestId;
+        this.details = opts.details;
+        this.remediation = opts.remediation;
+    }
+}
+/**
+ * Remediation advice appended to API errors, resolved in two tiers:
+ * exact error code first (this map), HTTP status fallback second
+ * (STATUS_REMEDIATIONS). The server's own message always prints; these
+ * only add "here's what to do about it".
+ */
+const REMEDIATIONS = {
+    AUTH_MISSING_API_KEY: 'Run `chatbase auth login`, or set CHATBASE_API_KEY. Keys live in chatbase.co → Workspace Settings → API Keys.',
+    AUTH_INVALID_API_KEY: 'Your key was rejected. Run `chatbase auth login` with a fresh key, or check CHATBASE_API_KEY.',
+    AUTH_EXPIRED_API_KEY: 'This API key has expired. Run `chatbase auth login` to authenticate again.',
+    AUTH_INSUFFICIENT_PERMISSIONS: 'This API key does not have permission for this operation. Check its scopes with `chatbase auth status`, re-pair with broader access via `chatbase auth login`, or ask a workspace admin.',
+    SUBSCRIPTION_API_RESTRICTED_PLAN: 'API access requires the Standard plan or higher — upgrade at chatbase.co.',
+    VALIDATION_INVALID_BODY: 'Fix the fields above and retry.'
+};
+/**
+ * Fallback tier: best-guess advice for error CODES this CLI version doesn't
+ * know (e.g. the API added one after this release), keyed by HTTP status.
+ * No 403 fallback: the API has many distinct 403 codes (AGENT_LIMIT_REACHED,
+ * HELPDESK_NOT_ENABLED, plan gates, ...) whose server messages are already
+ * self-explanatory — a blanket guess was actively misleading for most.
+ */
+const STATUS_REMEDIATIONS = {
+    404: 'Resource not found — check the ID (agent IDs live in your dashboard).',
+    429: 'Rate limited — the CLI already retried; wait for the reset and try again.'
+};
+function isErrorEnvelope(body) {
+    return (typeof body === 'object' &&
+        body !== null &&
+        typeof body.error === 'object' &&
+        typeof body.error?.code === 'string');
+}
+export function parseErrorResponse(status, body, requestId) {
+    if (isErrorEnvelope(body)) {
+        const { code, message, details } = body.error;
+        return new ApiError({
+            code,
+            message,
+            status,
+            requestId,
+            details,
+            remediation: REMEDIATIONS[code] ?? STATUS_REMEDIATIONS[status]
+        });
+    }
+    return new ApiError({
+        code: `HTTP_${status}`,
+        message: `Request failed with status ${status}`,
+        status,
+        requestId,
+        remediation: STATUS_REMEDIATIONS[status]
+    });
+}
+export function formatApiError(err, color) {
+    const lines = [color.red(`✗ ${err.message} (${err.code})`)];
+    if (err.details && typeof err.details === 'object') {
+        for (const [field, problem] of Object.entries(err.details)) {
+            lines.push(`    ${field}  ${String(problem)}`);
+        }
+    }
+    if (err.requestId)
+        lines.push(color.dim(`  request id: ${err.requestId}`));
+    if (err.remediation)
+        lines.push(`  ${err.remediation}`);
+    return lines.join('\n');
+}

package/dist/hooks/chat-message-hint.js

@@ -0,0 +1,21 @@
+/**
+ * `chat` is both a command and a topic (`chat retry`), so oclif resolves
+ * `chatbase chat "hello"` by looking for a subcommand named "hello" and
+ * lands in command_not_found. Without this hook, plugin-not-found prints
+ * a baffling `"chat hello" is not a chatbase command` — catch that one
+ * miss and point at the real input forms instead.
+ */
+const hook = async function (opts) {
+    // oclif joins the attempted command with its internal ':' separator —
+    // `chatbase chat "what are your hours?"` arrives as
+    // { id: 'chat:what are your hours?', argv: [] }.
+    const argv = opts.argv ?? [];
+    const parts = [...(opts.id ?? '').split(':'), ...argv].filter(Boolean);
+    if (parts[0] !== 'chat' || parts.length < 2)
+        return;
+    const attempted = parts.slice(1).join(' ');
+    this.error(`chat takes its message via -m, not as an argument:\n` +
+        `  chatbase chat -m ${JSON.stringify(attempted)}\n` +
+        `You can also pipe stdin, or run \`chatbase chat\` alone for the interactive REPL.`, { exit: 2 });
+};
+export default hook;

package/dist/output/color.js

@@ -0,0 +1,30 @@
+export function colorEnabled(stream, noColorFlag = false) {
+    const force = process.env.FORCE_COLOR;
+    if (force && force.length > 0 && force !== '0')
+        return true;
+    if (noColorFlag)
+        return false;
+    const no = process.env.NO_COLOR;
+    if (no && no.length > 0)
+        return false;
+    if (process.env.TERM === 'dumb')
+        return false;
+    return stream.isTTY === true;
+}
+const wrap = (open) => (s) => `\x1b[${open}m${s}\x1b[0m`;
+const identity = (s) => s;
+export function paint(enabled) {
+    if (!enabled)
+        return {
+            red: identity,
+            green: identity,
+            yellow: identity,
+            dim: identity
+        };
+    return {
+        red: wrap('31'),
+        green: wrap('32'),
+        yellow: wrap('33'),
+        dim: wrap('2')
+    };
+}

package/dist/output/mode.js

@@ -0,0 +1,7 @@
+export function selectMode(flags, stream = process.stdout) {
+    if (flags.json)
+        return 'json';
+    if (flags.plain)
+        return 'plain';
+    return stream.isTTY ? 'pretty' : 'plain';
+}

package/dist/output/spinner.js

@@ -0,0 +1,37 @@
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const CLEAR_LINE = '\r\x1b[2K';
+/**
+ * Transient stderr spinner for operations with dead air (file uploads,
+ * non-streaming chat). Returns a stop() that erases the line. No-op when
+ * stderr isn't a TTY — CI logs and pipes never see spinner frames.
+ * `delayMs` holds the spinner back so sub-second operations never flicker.
+ */
+/** Convenience for the common `<suppress> ? noop : startSpinner(...)`
+ * guard — --quiet (and streaming, where tokens are their own feedback)
+ * suppress the spinner entirely. */
+export function maybeSpinner(suppress, text, delayMs = 0) {
+    return suppress ? () => { } : startSpinner(text, delayMs);
+}
+export function startSpinner(text, delayMs = 0) {
+    if (!process.stderr.isTTY)
+        return () => { };
+    let i = 0;
+    let timer;
+    const delay = setTimeout(() => {
+        process.stderr.write(HIDE_CURSOR);
+        timer = setInterval(() => {
+            process.stderr.write(`\r${FRAMES[i++ % FRAMES.length]} ${text}`);
+        }, 80);
+        timer.unref();
+    }, delayMs);
+    delay.unref();
+    return () => {
+        clearTimeout(delay);
+        if (timer) {
+            clearInterval(timer);
+            process.stderr.write(CLEAR_LINE + SHOW_CURSOR);
+        }
+    };
+}