beehaven 0.8.16

package/dist/shared/claude-code/daemon-types.js

@@ -0,0 +1,112 @@
+/**
+ * Claude Daemon Types
+ *
+ * Types for the 24/7 Claude daemon service, token management,
+ * and WebSocket gateway communication.
+ */
+export const DEFAULT_DAEMON_CONFIG = {
+    autoStart: true,
+    wsPort: 18790,
+    maxIdleTime: 0, // Never auto-sleep
+    persistContext: true,
+    maxSessionHistory: 100,
+    defaultModel: undefined, // Use Claude's default
+};
+// ============================================
+// IPC CHANNELS
+// ============================================
+/** IPC channel names for daemon communication */
+export const DAEMON_IPC_CHANNELS = {
+    // Token management
+    SETUP_TOKEN: 'daemon:setup-token',
+    VALIDATE_TOKEN: 'daemon:validate-token',
+    TOKEN_STATUS: 'daemon:token-status',
+    CLEAR_TOKEN: 'daemon:clear-token',
+    // Daemon lifecycle
+    START: 'daemon:start',
+    STOP: 'daemon:stop',
+    RESTART: 'daemon:restart',
+    STATUS: 'daemon:status',
+    // WebSocket info
+    WS_URL: 'daemon:ws-url',
+    LOCAL_AUTH: 'daemon:local-auth',
+    // Events (main -> renderer)
+    STATUS_CHANGED: 'daemon:status-changed',
+    TOKEN_EXPIRING: 'daemon:token-expiring',
+    ERROR: 'daemon:error',
+};
+/**
+ * Default values for SMS commands
+ */
+export const DEFAULT_SMS_COMMAND = {
+    status: 'pending',
+    retryCount: 0,
+};
+/**
+ * Parse SMS command intent using simple heuristics
+ * (Used as fallback if Gemini parsing fails)
+ */
+export function parseIntentHeuristic(text) {
+    const lowerText = text.toLowerCase();
+    // Video creation patterns
+    if (lowerText.includes('tiktok') ||
+        lowerText.includes('video') ||
+        lowerText.includes('reel') ||
+        lowerText.includes('short')) {
+        const platformMatch = lowerText.match(/(tiktok|youtube|instagram|reel)/);
+        return {
+            type: 'video-create',
+            confidence: 0.7,
+            entities: {
+                platform: platformMatch?.[1] || 'tiktok',
+                topic: text.replace(/make|create|edit|me|a|about/gi, '').trim(),
+            },
+            rawText: text,
+        };
+    }
+    // Code generation patterns
+    if (lowerText.includes('create') ||
+        lowerText.includes('build') ||
+        lowerText.includes('website') ||
+        lowerText.includes('app') ||
+        lowerText.includes('code')) {
+        return {
+            type: 'code-generate',
+            confidence: 0.6,
+            entities: {
+                topic: text,
+            },
+            rawText: text,
+        };
+    }
+    // Research patterns
+    if (lowerText.includes('research') ||
+        lowerText.includes('find') ||
+        lowerText.includes('search') ||
+        lowerText.includes('look up')) {
+        return {
+            type: 'research',
+            confidence: 0.6,
+            entities: {
+                topic: text,
+            },
+            rawText: text,
+        };
+    }
+    // Query patterns
+    if (lowerText.startsWith('what') || lowerText.startsWith('how') || lowerText.startsWith('why')) {
+        return {
+            type: 'query',
+            confidence: 0.5,
+            entities: {},
+            rawText: text,
+        };
+    }
+    // Default to conversation
+    return {
+        type: 'conversation',
+        confidence: 0.3,
+        entities: {},
+        rawText: text,
+    };
+}

package/dist/shared/claude-code/index.js

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './daemon-types.js';

package/dist/shared/claude-code/types.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/status/schema.js

@@ -0,0 +1,133 @@
+/**
+ * status.json — shared schema between the daemon (writer) and the
+ * Clearly Dev Mac app tray (reader).
+ *
+ * The daemon writes `~/.beehaven/status.json` every 2 seconds with a
+ * snapshot of relay connectivity, pending RPCs, reconnect attempts,
+ * and version info. The tray polls this file on every menu rebuild to
+ * render live status (relay OK, daemon running PID N, etc).
+ *
+ * Without a shared schema, the two sides could drift — the daemon
+ * starts emitting a new field, the tray silently ignores it; the
+ * daemon renames a field, the tray reads `undefined` and shows wrong
+ * status. This file is the contract.
+ *
+ * Design choices:
+ *   - No Zod / io-ts / runtime-type library — CLI keeps a near-zero
+ *     runtime dependency footprint. A hand-written validator is ~80
+ *     lines, as correct as any library for this shape.
+ *   - Explicit schemaVersion so the tray can reject future snapshots
+ *     that use an incompatible version — better than silently showing
+ *     wrong data.
+ *   - Bidirectional: the daemon calls `validateStatusSnapshot()` before
+ *     writing (catches local drift); the tray calls
+ *     `readAndValidateStatusFile()` after reading (catches remote drift).
+ */
+/** Current schema version. Bump when a field changes semantics. */
+export const STATUS_SCHEMA_VERSION = 1;
+/**
+ * Validate an unknown value against the StatusSnapshot schema.
+ *
+ * Returns `{ ok: true, value }` with a typed snapshot on success, or
+ * `{ ok: false, errors: string[] }` with one message per failing field.
+ * Never throws. Rejects extra fields silently (tolerates daemons that
+ * emit extra fields newer than the tray knows about).
+ */
+export function validateStatusSnapshot(v) {
+    const errors = [];
+    if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+        return { ok: false, errors: ['not an object'] };
+    }
+    const o = v;
+    if (o.schemaVersion !== STATUS_SCHEMA_VERSION) {
+        errors.push(`schemaVersion: expected ${STATUS_SCHEMA_VERSION}, got ${JSON.stringify(o.schemaVersion)}`);
+    }
+    if (typeof o.pid !== 'number' || !Number.isFinite(o.pid) || o.pid <= 0) {
+        errors.push(`pid: expected positive number, got ${JSON.stringify(o.pid)}`);
+    }
+    if (typeof o.updatedAt !== 'number' || !Number.isFinite(o.updatedAt) || o.updatedAt <= 0) {
+        errors.push(`updatedAt: expected positive number, got ${JSON.stringify(o.updatedAt)}`);
+    }
+    if (typeof o.relayConnected !== 'boolean') {
+        errors.push(`relayConnected: expected boolean, got ${typeof o.relayConnected}`);
+    }
+    if (typeof o.relayConfigured !== 'boolean') {
+        errors.push(`relayConfigured: expected boolean, got ${typeof o.relayConfigured}`);
+    }
+    if (o.relayEndpoint !== null && typeof o.relayEndpoint !== 'string') {
+        errors.push(`relayEndpoint: expected string or null, got ${typeof o.relayEndpoint}`);
+    }
+    if (typeof o.pendingRequests !== 'number' ||
+        !Number.isFinite(o.pendingRequests) ||
+        o.pendingRequests < 0) {
+        errors.push(`pendingRequests: expected non-negative number, got ${JSON.stringify(o.pendingRequests)}`);
+    }
+    if (typeof o.reconnectAttempts !== 'number' ||
+        !Number.isFinite(o.reconnectAttempts) ||
+        o.reconnectAttempts < 0) {
+        errors.push(`reconnectAttempts: expected non-negative number, got ${JSON.stringify(o.reconnectAttempts)}`);
+    }
+    if (typeof o.version !== 'string' || o.version.length === 0) {
+        errors.push(`version: expected non-empty string, got ${JSON.stringify(o.version)}`);
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, value: o };
+}
+/**
+ * Read + validate the status file. Returns the parsed snapshot on
+ * success, or a structured error discriminator. Handles:
+ *   - missing file              → `{ ok: false, reason: 'not-found' }`
+ *   - unreadable / permissions  → `{ ok: false, reason: 'read-failed', detail }`
+ *   - invalid JSON              → `{ ok: false, reason: 'malformed', detail }`
+ *   - schema-version mismatch   → `{ ok: false, reason: 'version-mismatch', expected, got }`
+ *   - shape validation failure  → `{ ok: false, reason: 'schema', errors }`
+ *   - stale (older than maxAgeMs) → `{ ok: false, reason: 'stale', ageMs }`
+ *
+ * Reader-side helper. Use from the Mac app tray instead of raw
+ * `JSON.parse(readFileSync(path))` to get typed errors.
+ */
+export async function readAndValidateStatusFile(path, opts = {}) {
+    const { readFile } = await import('node:fs/promises');
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return { ok: false, reason: 'not-found' };
+        return { ok: false, reason: 'read-failed', detail: err?.message ?? String(err) };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return { ok: false, reason: 'malformed', detail: err?.message ?? 'JSON parse failed' };
+    }
+    // Fast version check — if the version doesn't match, don't bother
+    // walking fields. The tray can surface "daemon is newer/older, restart"
+    // without a confusing schema-error cascade.
+    if (parsed?.schemaVersion !== STATUS_SCHEMA_VERSION) {
+        return {
+            ok: false,
+            reason: 'version-mismatch',
+            expected: STATUS_SCHEMA_VERSION,
+            got: parsed?.schemaVersion,
+        };
+    }
+    const result = validateStatusSnapshot(parsed);
+    if (!result.ok)
+        return {
+            ok: false,
+            reason: 'schema',
+            errors: result.errors,
+        };
+    if (opts.maxAgeMs !== undefined) {
+        const age = Date.now() - result.value.updatedAt;
+        if (age > opts.maxAgeMs) {
+            return { ok: false, reason: 'stale', ageMs: age };
+        }
+    }
+    return { ok: true, value: result.value };
+}

package/dist/shell-session.js

@@ -0,0 +1,198 @@
+/**
+ * shell-session — the remote shell's working directory, owned by the CLIENT, one per LOGIN.
+ *
+ * ── WHY THIS EXISTS ────────────────────────────────────────────────────────────────────────
+ * The workspace shell kept its cwd server-side in a `WeakMap` keyed on
+ * `input.sessionId || this._activeSessionId || 'default'`. The CLI never sent a `sessionId`, and
+ * `_activeSessionId` exists only on the Shopify store DO — so on a workspace DO the key was the
+ * literal string `'default'` for every caller alive. MEASURED on staging 2026-09-05:
+ *
+ *     jinri-claude      bash 'cd Q1 && pwd'  ->  cwd '~/Q1'
+ *     northwind-scribe  bash 'pwd'           ->  cwd '~/Q1'     <- another agent's directory
+ *
+ * A relative path therefore resolved against whatever a sibling agent last `cd`'d to, and both
+ * sides reported success. (CBH-39.)
+ *
+ * ── WHY THE CLIENT OWNS IT RATHER THAN THE SERVER ──────────────────────────────────────────
+ * Sending a `sessionId` would have been a one-line fix and leaves three properties broken: the map
+ * is per-DO-instance RAM, so an eviction silently resets the directory mid-task; nothing can
+ * INSPECT it without executing a command; and the map grows per session with no eviction policy.
+ * Holding the cwd in a file and sending it makes the transport stateless, survives both DO
+ * eviction and daemon restarts, and lets `pwd` answer with no round trip — the same three
+ * arguments `cli-state.ts` already makes for keeping the target cursor in a file.
+ *
+ * ── ⚠⚠ THE KEY IS THE LOGIN, NOT THE IDENTITY — AND THAT DIFFERS FROM `target.json` ─────────
+ * `cli-state.effectiveScope()` resolves the process scope THROUGH `agentForScope()` to the bound
+ * agent NAME, deliberately: *"A LOGGED-IN AGENT'S CURSOR FOLLOWS THE AGENT, NOT THE PROCESS …
+ * a durable agent would start at home each time and lose the workspace it had chosen."* That is
+ * right for a cursor and wrong for a cwd, and the two are not the same question:
+ *
+ *     WHICH WORKSPACE am I in   -> a standing choice        -> follows the identity  (target.json)
+ *     WHERE am I inside it      -> this shell, right now    -> follows the LOGIN     (this file)
+ *
+ * Two Claude sessions in two terminals, both logged in as `jinri-claude`, are two shells. They
+ * share a workspace and must not share a directory — which is exactly how real terminals behave,
+ * and why resetting to `~` on a new session is correct here rather than a regression.
+ *
+ * So this uses the RAW `deriveAgentScope()` (`claude-<sessionId>`, `codex-…`, `pid-<ppid>`) and
+ * must NOT be "fixed" to use `effectiveScope()`. A guard pins that.
+ *
+ * ⚠ AN EXPLICIT `BEEHAVEN_AGENT=<name>` IN TWO TERMINALS STILL SHARES ONE FILE, because that is
+ * the one handle a person can set identically on purpose. Naming the same scope twice is a
+ * statement that they are the same shell; the automatic handles are all per-session.
+ *
+ * ⚠ A HUMAN (no scope) KEEPS THE UNSCOPED FILE, mirroring `target.json` exactly — nothing about an
+ * existing interactive shell moves.
+ */
+import { deriveAgentScope } from './agent-scope.js';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const STATE_DIR = join(homedir(), '.beehaven');
+/**
+ * The per-login key.
+ *
+ * ⚠ SANITISED, because it lands in a filesystem path — `BEEHAVEN_AGENT=../../..` would otherwise
+ * escape STATE_DIR. Same rule as `cli-state.targetFileFor`; a name that sanitises to nothing falls
+ * back to the shared file rather than writing `cwd-.json`.
+ */
+export function shellSessionKey(env = process.env) {
+    return (deriveAgentScope(env) || '').trim().replace(/[^A-Za-z0-9_-]/g, '');
+}
+function cwdFileFor(key = shellSessionKey()) {
+    return join(STATE_DIR, key ? `cwd-${key}.json` : 'cwd.json');
+}
+/** Exported for the scoping guard — the path rule takes an env var into a path, so it is asserted. */
+export const __cwdFileFor = cwdFileFor;
+/**
+ * ⚠⚠ ONE FUNCTION DECIDES THE TARGET KEY, BECAUSE TWO DOORS REACH THE SHELL AND THEY SPELL IT
+ * DIFFERENTLY.
+ *
+ * `beehaven ls ~` arrives through `execNotesShell` with `buildingType === 'home'`. `beehaven call
+ * bash …` arrives through `cmdCall`, where the address comes from the target cursor — and `cd home`
+ * PERSISTS the canonical `workspace`, not `home` (`CANONICAL_HOME_ADDRESS`). Left to compute their
+ * own keys the two doors would file one shell's cwd under `home` and the other's under `workspace`,
+ * so `cd` through one verb would be invisible to the next — the same shell, two directories,
+ * nothing reporting a problem.
+ *
+ * Every home spelling collapses to `home`; anything else is used as given.
+ */
+export function shellTargetKey(address) {
+    const a = String(address ?? '').trim();
+    if (!a || a === 'home' || a === 'me' || a === 'workspace')
+        return 'home';
+    // `--building type:id` and the address grammar's `type/id` name the same DO — normalise the
+    // separator, or the same workspace gets two entries depending on which flag was used.
+    return a.replace(':', '/');
+}
+function readMap(key = shellSessionKey()) {
+    try {
+        const f = cwdFileFor(key);
+        if (!existsSync(f))
+            return {};
+        const parsed = JSON.parse(readFileSync(f, 'utf-8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        // ⚠ NEVER THROWS. This runs on every shell call; a corrupt file must cost the cwd, not the command.
+        return {};
+    }
+}
+/** The stored cwd for a target, or null when this login has never moved there. */
+export function readShellCwd(target, key = shellSessionKey()) {
+    const v = readMap(key)[target];
+    return typeof v === 'string' && v ? v : null;
+}
+/**
+ * Persist the cwd the server reported.
+ *
+ * ⚠ WRITTEN FROM THE RESPONSE, NEVER PREDICTED FROM THE COMMAND. Guessing that `cd X` lands in `X`
+ * means re-implementing the shell's own resolution in the client, where it would drift; the handler
+ * already returns the directory it actually ran in, so echoing that back is the only value that
+ * cannot disagree with the server.
+ *
+ * ⚠ `~` IS NOT STORED. It is the default, so writing it just grows the file with entries that mean
+ * "nothing" — and an absent entry and an entry saying `~` must not be two ways to say one thing.
+ */
+export function writeShellCwd(target, cwd, key = shellSessionKey()) {
+    try {
+        const clean = String(cwd ?? '').trim();
+        const map = readMap(key);
+        if (!clean || clean === '~' || clean === '/home') {
+            if (!(target in map))
+                return;
+            delete map[target];
+        }
+        else {
+            if (map[target] === clean)
+                return; // no write when nothing moved
+            map[target] = clean;
+        }
+        mkdirSync(STATE_DIR, { recursive: true });
+        const f = cwdFileFor(key);
+        const tmp = `${f}.tmp`;
+        writeFileSync(tmp, JSON.stringify(map, null, 2), { mode: 0o600 });
+        renameSync(tmp, f); // atomic — two shells may write at once
+    }
+    catch {
+        /* a cwd we could not persist is a cwd that resets; never fail the command over it */
+    }
+}
+/**
+ * The actions whose payload carries a shell working directory.
+ *
+ * ⚠ AN ALLOWLIST, NOT A GUESS. Attaching `cwd` to every action would put an unexpected key in
+ * hundreds of payloads; `z.object()` strips unknown keys, so most would ignore it silently and any
+ * that happened to declare a `cwd` would be handed one that means something else entirely.
+ */
+const SHELL_ACTIONS = new Set(['bash', 'notes-bash']);
+export function isShellAction(action) {
+    return SHELL_ACTIONS.has(String(action || '').trim());
+}
+/**
+ * Attach this login's cwd to a shell payload.
+ *
+ * ⚠ AN EXPLICIT `cwd` IN THE CALLER'S OWN INPUT WINS AND IS LEFT ALONE — `beehaven call bash
+ * '{"command":"ls","cwd":"/local/src"}'` is how the LOCAL machine is addressed, and overwriting it
+ * would silently redirect a command from the user's laptop to the workspace.
+ */
+export function attachShellCwd(action, input, target) {
+    if (!isShellAction(action))
+        return input;
+    if (typeof input?.cwd === 'string' && input.cwd.trim())
+        return input;
+    /**
+     * ⚠⚠ ALWAYS ASSERT A cwd — SENDING NOTHING STILL INHERITS ANOTHER LOGIN'S DIRECTORY.
+     *
+     * The first version sent the field only when a directory had been stored, which reads as the
+     * obvious economy and leaves the bug half-open. MEASURED against the deployed fix: login A did
+     * `cd Q1`; login B, having stored nothing, sent no `cwd`, the server fell back to the shared
+     * session map, and B ran in `~/Q1` — the exact leak, surviving the fix for it.
+     *
+     * Absence has to keep meaning "a caller that does not manage its own cwd" (the web client, MCP,
+     * an older CLI), because that is what the session map is still there to serve. So a client that
+     * DOES manage its own must say `~` out loud rather than staying quiet: at root by decision, not
+     * by default.
+     */
+    return { ...input, cwd: readShellCwd(target) ?? '~' };
+}
+/**
+ * Store the cwd a shell response reported.
+ *
+ * ⚠ `cwdReset` MEANS THE STORED PATH IS DEAD — the folder was deleted or renamed since. The server
+ * has already fallen back to the root and said so; clearing the entry is what stops this login
+ * sending the dead path on every subsequent call forever.
+ */
+export function absorbShellCwd(action, result, target) {
+    if (!isShellAction(action))
+        return;
+    const r = result;
+    if (!r || typeof r !== 'object')
+        return;
+    if (typeof r.cwdReset === 'string' && r.cwdReset) {
+        writeShellCwd(target, '~');
+        return;
+    }
+    if (typeof r.cwd === 'string' && r.cwd)
+        writeShellCwd(target, r.cwd);
+}

package/dist/speak-lock.js

@@ -0,0 +1,97 @@
+/**
+ * speak-lock.ts — one voice at a time, machine-wide.
+ *
+ * ⚠⚠ WHY THIS EXISTS: TWO `speak`s AT ONCE SOUND LIKE A BROKEN MODEL, NOT LIKE TWO
+ * MESSAGES. Reported as the voice "spazzing out and stuttering", with the telling
+ * detail that *the start was fine* — which is exactly the shape of overlap: the first
+ * utterance plays alone and is clean, then the second begins on top of it and the two
+ * become an unintelligible smear.
+ *
+ * Reproduced directly: three backgrounded `speak`s fired three seconds apart showed
+ * **two concurrent `afplay` processes**. Nothing in the audio was wrong — the model,
+ * the temperature and the joins all measured clean. The defect was that nobody owned
+ * the speaker.
+ *
+ * ⚠ IT SERIALISES, IT DOES NOT REFUSE. Dropping the second utterance would lose
+ * something the caller wanted said; playing it later is almost always right for
+ * status narration. A caller who genuinely wants to talk over the top can opt out.
+ *
+ * ⚠ THE LOCK IS ADVISORY AND SELF-HEALING. It holds a pid; a lock whose owner is gone
+ * is taken immediately, so a killed `speak` cannot mute the machine until reboot —
+ * which would be a far worse failure than the overlap it prevents.
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const LOCK_DIR = join(homedir(), '.beehaven');
+const LOCK_FILE = join(LOCK_DIR, 'speak.lock');
+/** Longest we will wait for another utterance before speaking anyway. */
+const MAX_WAIT_MS = 5 * 60_000;
+const POLL_MS = 250;
+function ownerAlive() {
+    try {
+        if (!existsSync(LOCK_FILE))
+            return null;
+        const pid = Number(readFileSync(LOCK_FILE, 'utf8').trim());
+        if (!Number.isFinite(pid) || pid <= 0)
+            return null;
+        // Signal 0 tests existence without touching the process.
+        try {
+            process.kill(pid, 0);
+            return pid;
+        }
+        catch {
+            return null; // owner is gone — the lock is stale
+        }
+    }
+    catch {
+        return null;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Wait for the speaker, then hold it. Returns a release function that is safe to
+ * call more than once.
+ */
+export async function acquireSpeakLock(opts = {}) {
+    if (opts.wait === false)
+        return () => { };
+    try {
+        mkdirSync(LOCK_DIR, { recursive: true });
+    }
+    catch { /* the write below will report anything real */ }
+    const deadline = Date.now() + MAX_WAIT_MS;
+    while (ownerAlive() !== null && Date.now() < deadline) {
+        await sleep(POLL_MS);
+    }
+    try {
+        writeFileSync(LOCK_FILE, String(process.pid), { mode: 0o600 });
+    }
+    catch {
+        // ⚠ AN UNWRITABLE LOCK MUST NOT SILENCE THE UTTERANCE. Overlapping audio is a
+        //   worse outcome than no audio only if you value tidiness over being heard.
+        return () => { };
+    }
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        try {
+            // Only remove it if it is still OURS — a lock we waited past the deadline for
+            // may since have been taken by someone else, and deleting theirs would let a
+            // third utterance in on top.
+            if (existsSync(LOCK_FILE) && readFileSync(LOCK_FILE, 'utf8').trim() === String(process.pid)) {
+                unlinkSync(LOCK_FILE);
+            }
+        }
+        catch { /* nothing useful to do */ }
+    };
+    // ⚠ RELEASE ON THE WAYS OUT THAT ARE NOT A NORMAL RETURN. A ^C mid-utterance would
+    //   otherwise leave a lock owned by a dead pid — self-healing, but only on the next
+    //   call, which is one confusing wait too many.
+    process.once('exit', release);
+    process.once('SIGINT', () => { release(); process.exit(130); });
+    process.once('SIGTERM', () => { release(); process.exit(143); });
+    return release;
+}

package/dist/spinner.js

@@ -0,0 +1,57 @@
+/**
+ * Lightweight CLI spinner and color utilities — zero dependencies.
+ */
+const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export class Spinner {
+    timer = null;
+    frameIdx = 0;
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+    start() {
+        this.timer = setInterval(() => {
+            const frame = frames[this.frameIdx % frames.length];
+            process.stderr.write(`\r${color.cyan(frame)} ${this.text}`);
+            this.frameIdx++;
+        }, 80);
+        return this;
+    }
+    update(text) {
+        this.text = text;
+    }
+    succeed(text) {
+        this.stop();
+        console.log(`${color.green('✓')} ${text ?? this.text}`);
+    }
+    fail(text) {
+        this.stop();
+        console.error(`${color.red('✗')} ${text ?? this.text}`);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        process.stderr.write('\r\x1b[K'); // Clear line
+    }
+}
+export const color = {
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    gray: (s) => `\x1b[90m${s}\x1b[0m`,
+};
+export function table(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
+    const sep = widths.map((w) => '─'.repeat(w + 2)).join('┼');
+    const pad = (s, w) => s + ' '.repeat(Math.max(0, w - s.length));
+    const formatRow = (row) => row.map((c, i) => ` ${pad(c, widths[i])} `).join('│');
+    return [formatRow(headers), sep, ...rows.map(formatRow)].join('\n');
+}
+export function spinner(text) {
+    return new Spinner(text);
+}