@debugai/mcp 2.0.0 → 2.1.0

package/dist/cli/commands.js

@@ -0,0 +1,360 @@
+// The subcommands. Every one of these exists to delete a step a human used
+// to do by hand:
+//
+//   setup      login + install, the only command the README leads with
+//   login      device link — replaces "copy your key out of the dashboard"
+//   install    writes client configs — replaces "paste this JSON blob"
+//   doctor     one command that answers "why isn't it working"
+//   status     what account/key is active right now
+//   logout     removes the stored key
+//   uninstall  removes the server entry from client configs
+//
+// Each returns a process exit code. Nothing here ever writes to stdout while
+// the MCP transport is live — subcommands exit before a server is created.
+import { statSync } from 'node:fs';
+import { hostname, platform } from 'node:os';
+import { clearStoredKey, configPath, loadFileConfig, maskKey, resolveSettings, writeFileConfig, } from '../config.js';
+import { DeviceLinkError, startDeviceLink, waitForDeviceLink } from '../deviceLink.js';
+import { DEFAULT_API_BASE } from '../constants.js';
+import { detectedClients, findClient, isDetected, knownClients, } from './clients.js';
+import { applyToClient, isInstalled } from './install.js';
+import { FAIL, INFO, OK, WARN, bold, codeBox, dim, heading, openBrowser, say, yellow } from './ui.js';
+// ── shared helpers ───────────────────────────────────────────────────────────
+function flag(argv, name) {
+    return argv.includes(`--${name}`);
+}
+function flagValue(argv, name) {
+    const eq = argv.find((a) => a.startsWith(`--${name}=`));
+    if (eq)
+        return eq.slice(name.length + 3);
+    const idx = argv.indexOf(`--${name}`);
+    if (idx >= 0 && argv[idx + 1] && !argv[idx + 1].startsWith('-'))
+        return argv[idx + 1];
+    return undefined;
+}
+/** Confirms a key actually works against the live API. Null = could not verify. */
+async function verifyKey(apiBase, apiKey) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 12_000);
+    try {
+        const res = await fetch(`${apiBase}/user/me`, {
+            headers: { 'x-api-key': apiKey },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        const body = await res.json();
+        const user = body?.user ?? body ?? {};
+        return {
+            email: user.email,
+            tier: user.tier,
+            usedToday: user.usage_today ?? user.used_today ?? user.daily_usage,
+            dailyLimit: user.daily_limit ?? user.limit,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function clientLabel() {
+    return `${hostname()} (${platform()})`;
+}
+function describeResult(r) {
+    const name = bold(r.client.label);
+    switch (r.action) {
+        case 'wrote':
+        case 'updated':
+            say(`  ${OK()} ${name} — ${r.action === 'wrote' ? 'added to' : 'updated in'} ${dim(r.path ?? '')}`);
+            if (r.backupPath)
+                say(`      ${dim(`backup: ${r.backupPath}`)}`);
+            if (r.warning)
+                say(`      ${WARN()} ${yellow(r.warning)}`);
+            say(`      ${dim(`next: ${r.client.afterInstall}`)}`);
+            break;
+        case 'unchanged':
+            say(`  ${OK()} ${name} — already configured, nothing to change`);
+            break;
+        case 'removed':
+            say(`  ${OK()} ${name} — entry removed from ${dim(r.path ?? '')}`);
+            if (r.backupPath)
+                say(`      ${dim(`backup: ${r.backupPath}`)}`);
+            break;
+        case 'skipped':
+            say(`  ${INFO()} ${name} — skipped${r.warning ? `: ${r.warning}` : ''}`);
+            break;
+        case 'failed':
+            say(`  ${FAIL()} ${name} — ${r.error ?? 'failed'}`);
+            say(`      ${dim(`file: ${r.path ?? '(unknown)'}`)}`);
+            if (r.preview) {
+                say(`      ${dim('merge this in by hand:')}`);
+                r.preview.split('\n').forEach((l) => say(`      ${dim(l)}`));
+            }
+            break;
+    }
+}
+// ── login ────────────────────────────────────────────────────────────────────
+export async function cmdLogin(argv, env = process.env) {
+    const { apiBase } = resolveSettings(DEFAULT_API_BASE, env, () => { });
+    const manualKey = flagValue(argv, 'key');
+    // Escape hatch for CI, air-gapped machines, and anyone who would rather
+    // paste. Same storage path, so everything downstream behaves identically.
+    if (manualKey) {
+        if (!manualKey.startsWith('dbg_')) {
+            say(`${FAIL()} That does not look like a DebugAI key. They start with ${bold('dbg_')}.`);
+            return 1;
+        }
+        const path = writeFileConfig({ apiKey: manualKey }, env);
+        const info = await verifyKey(apiBase, manualKey);
+        say(`${OK()} Key stored in ${path}${info?.email ? ` for ${bold(info.email)}` : ''}.`);
+        if (!info)
+            say(`${WARN()} ${yellow('Could not verify it against the API just now. Run "debugai-mcp doctor" later.')}`);
+        return 0;
+    }
+    const existing = loadFileConfig(env, () => { }).apiKey;
+    if (existing && !flag(argv, 'force')) {
+        const info = await verifyKey(apiBase, existing);
+        if (info) {
+            say(`${OK()} Already signed in as ${bold(info.email ?? 'this account')} (${info.tier ?? 'free'} tier).`);
+            say(`  ${dim(`Key ${maskKey(existing)} in ${configPath(env)}. Re-link with "debugai-mcp login --force".`)}`);
+            return 0;
+        }
+        say(`${WARN()} A stored key exists but the API rejected it. Re-linking.`);
+    }
+    let start;
+    try {
+        start = await startDeviceLink({ apiBase, clientLabel: clientLabel() });
+    }
+    catch (err) {
+        const detail = err instanceof DeviceLinkError ? err.message : String(err);
+        say(`${FAIL()} Could not start the sign-in link: ${detail}`);
+        say(`  ${dim('Fallback: grab a key at https://debugai.io/dashboard and run')}`);
+        say(`  ${dim('debugai-mcp login --key dbg_your_key')}`);
+        return 1;
+    }
+    say();
+    say(bold('Sign in to DebugAI'));
+    say(codeBox(start.userCode));
+    say(`  Confirm that code at ${bold(start.verificationUriComplete)}`);
+    const opened = openBrowser(start.verificationUriComplete);
+    say(opened
+        ? dim('  (opening your browser. free account, 10 debugs/day, no card)')
+        : dim('  (open that link on any device. free account, 10 debugs/day, no card)'));
+    say();
+    say(dim(`  Waiting… the code expires in ${Math.round(start.expiresIn / 60)} minutes. Ctrl-C to cancel.`));
+    const result = await waitForDeviceLink(start, { apiBase });
+    if (result.status === 'linked') {
+        const path = writeFileConfig({ apiKey: result.apiKey }, env);
+        say();
+        say(`${OK()} Signed in${result.email ? ` as ${bold(result.email)}` : ''}${result.tier ? ` (${result.tier} tier)` : ''}.`);
+        say(`  ${dim(`Key saved to ${path}. Every MCP client on this machine reads it.`)}`);
+        say();
+        say(`  Next: ${bold('npx -y @debugai/mcp install')} ${dim('(wires up the MCP clients you have)')}`);
+        return 0;
+    }
+    say();
+    if (result.status === 'denied')
+        say(`${FAIL()} Sign-in was declined in the browser.`);
+    else if (result.status === 'expired')
+        say(`${FAIL()} The code expired. Run "debugai-mcp login" again.`);
+    else
+        say(`${FAIL()} Sign-in did not complete.`);
+    return 1;
+}
+// ── logout / status ──────────────────────────────────────────────────────────
+export function cmdLogout(_argv, env = process.env) {
+    const removed = clearStoredKey(env);
+    say(removed
+        ? `${OK()} Stored key removed from ${configPath(env)}.`
+        : `${INFO()} No stored key to remove (${configPath(env)}).`);
+    if ((env.DEBUGAI_API_KEY ?? '').trim()) {
+        say(`${WARN()} ${yellow('DEBUGAI_API_KEY is still set in this environment and takes priority over the file.')}`);
+    }
+    return 0;
+}
+export async function cmdStatus(_argv, env = process.env) {
+    const { apiKey, apiBase, keySource } = resolveSettings(DEFAULT_API_BASE, env, () => { });
+    say(`${bold('DebugAI MCP status')}`);
+    say(`  API base   ${apiBase}`);
+    say(`  Key        ${apiKey ? `${maskKey(apiKey)} (from ${keySource === 'env' ? 'DEBUGAI_API_KEY' : configPath(env)})` : dim('none')}`);
+    if (!apiKey) {
+        say();
+        say(`  Run ${bold('npx -y @debugai/mcp login')} to sign in.`);
+        return 1;
+    }
+    const info = await verifyKey(apiBase, apiKey);
+    if (!info) {
+        say(`  Account    ${FAIL()} key rejected or API unreachable`);
+        return 1;
+    }
+    say(`  Account    ${info.email ?? '(unknown)'} · ${info.tier ?? 'free'} tier`);
+    return 0;
+}
+// ── install / uninstall ──────────────────────────────────────────────────────
+function selectClients(argv, env) {
+    const raw = flagValue(argv, 'client');
+    if (raw) {
+        const ids = raw.split(',').map((s) => s.trim()).filter(Boolean);
+        const clients = [];
+        for (const id of ids) {
+            const found = findClient(id, env);
+            if (found)
+                clients.push(found);
+            else
+                say(`${WARN()} Unknown client "${id}". Run "debugai-mcp install --list" to see the names.`);
+        }
+        return { clients, explicit: true };
+    }
+    if (flag(argv, 'all'))
+        return { clients: knownClients(env).filter((c) => !c.optIn), explicit: false };
+    return { clients: detectedClients(env).filter((c) => !c.optIn), explicit: false };
+}
+function listClients(env) {
+    heading('Known MCP clients');
+    for (const c of knownClients(env)) {
+        const mark = isDetected(c) ? OK() : INFO();
+        const state = isDetected(c) ? (isInstalled(c) ? 'detected · debugai configured' : 'detected') : 'not found';
+        say(`  ${mark} ${bold(c.id.padEnd(15))} ${c.label.padEnd(22)} ${dim(state)}`);
+        say(`      ${dim(c.configPath ?? 'no config path on this OS')}`);
+        if (c.note)
+            say(`      ${dim(c.note)}`);
+    }
+    say();
+    say(dim('  Install one explicitly: debugai-mcp install --client=cursor'));
+}
+export function cmdInstall(argv, env = process.env) {
+    if (flag(argv, 'list')) {
+        listClients(env);
+        return 0;
+    }
+    const dryRun = flag(argv, 'dry-run') || flag(argv, 'print');
+    const remove = flag(argv, 'remove');
+    const { clients, explicit } = selectClients(argv, env);
+    if (!clients.length) {
+        say(`${WARN()} No MCP clients detected on this machine.`);
+        say();
+        listClients(env);
+        return 1;
+    }
+    heading(remove ? 'Removing DebugAI from MCP clients' : 'Installing DebugAI into MCP clients');
+    const results = clients.map((c) => applyToClient(c, { dryRun, remove }));
+    results.forEach(describeResult);
+    if (dryRun) {
+        for (const r of results.filter((x) => x.preview)) {
+            heading(`${r.client.label} — ${r.path}`);
+            say(r.preview.trimEnd());
+        }
+        say();
+        say(dim('  Dry run — nothing was written.'));
+        return 0;
+    }
+    const failed = results.filter((r) => r.action === 'failed').length;
+    const changed = results.filter((r) => r.action === 'wrote' || r.action === 'updated' || r.action === 'removed').length;
+    say();
+    if (!remove) {
+        const { apiKey } = resolveSettings(DEFAULT_API_BASE, env, () => { });
+        if (!apiKey) {
+            say(`${WARN()} ${yellow('No API key stored yet — run')} ${bold('npx -y @debugai/mcp login')} ${yellow('to finish.')}`);
+        }
+        else {
+            say(`${OK()} Key already stored — ${changed ? 'restart the clients above and you are done.' : 'nothing left to do.'}`);
+        }
+        if (!explicit)
+            say(dim('  Missing a client? "debugai-mcp install --list" shows every name.'));
+    }
+    return failed ? 1 : 0;
+}
+export function cmdUninstall(argv, env = process.env) {
+    return cmdInstall([...argv, '--remove', '--all'], env);
+}
+// ── doctor ───────────────────────────────────────────────────────────────────
+export async function cmdDoctor(_argv, env = process.env) {
+    let hardFailures = 0;
+    const fail = (msg, hint) => {
+        hardFailures++;
+        say(`  ${FAIL()} ${msg}`);
+        if (hint)
+            say(`      ${dim(hint)}`);
+    };
+    const pass = (msg, detail) => {
+        say(`  ${OK()} ${msg}`);
+        if (detail)
+            say(`      ${dim(detail)}`);
+    };
+    heading('Runtime');
+    const major = Number(process.versions.node.split('.')[0]);
+    if (major >= 18)
+        pass(`Node ${process.versions.node}`);
+    else
+        fail(`Node ${process.versions.node} is too old`, 'DebugAI MCP needs Node 18 or newer (it uses global fetch).');
+    heading('Account');
+    const { apiKey, apiBase, keySource } = resolveSettings(DEFAULT_API_BASE, env, () => { });
+    if (!apiKey) {
+        fail('No API key found', 'Run: npx -y @debugai/mcp login');
+    }
+    else if (!apiKey.startsWith('dbg_')) {
+        fail(`Key does not look like a DebugAI key (${maskKey(apiKey)})`, 'DebugAI keys start with dbg_.');
+    }
+    else {
+        pass(`Key ${maskKey(apiKey)}`, `source: ${keySource === 'env' ? 'DEBUGAI_API_KEY env var' : configPath(env)}`);
+    }
+    if (keySource === 'file') {
+        try {
+            const mode = statSync(configPath(env)).mode & 0o777;
+            if (platform() !== 'win32' && (mode & 0o077) !== 0) {
+                say(`  ${WARN()} ${yellow(`Config file is readable by other users (mode ${mode.toString(8)})`)}`);
+                say(`      ${dim(`fix: chmod 600 ${configPath(env)}`)}`);
+            }
+        }
+        catch { /* file vanished between calls — the key check above already covered it */ }
+    }
+    heading('API');
+    if (!apiKey) {
+        say(`  ${INFO()} Skipped — no key to test with.`);
+    }
+    else {
+        const info = await verifyKey(apiBase, apiKey);
+        if (info) {
+            pass(`${apiBase} reachable`, `${info.email ?? 'account'} · ${info.tier ?? 'free'} tier`);
+        }
+        else {
+            fail(`Could not authenticate against ${apiBase}`, 'Either the key was rotated (run: debugai-mcp login --force) or the API is unreachable from here.');
+        }
+    }
+    heading('MCP clients');
+    const detected = detectedClients(env);
+    if (!detected.length) {
+        say(`  ${INFO()} None detected. "debugai-mcp install --list" shows every supported client.`);
+    }
+    for (const c of detected) {
+        if (isInstalled(c))
+            pass(`${c.label} — debugai configured`, c.configPath ?? undefined);
+        else
+            say(`  ${WARN()} ${yellow(`${c.label} — installed but DebugAI is not in its config`)}\n      ${dim(`fix: debugai-mcp install --client=${c.id}`)}`);
+    }
+    say();
+    if (hardFailures) {
+        say(`${FAIL()} ${hardFailures} problem${hardFailures === 1 ? '' : 's'} to fix.`);
+        return 1;
+    }
+    say(`${OK()} Everything checks out.`);
+    return 0;
+}
+// ── setup (the headline command) ─────────────────────────────────────────────
+export async function cmdSetup(argv, env = process.env) {
+    const { apiKey } = resolveSettings(DEFAULT_API_BASE, env, () => { });
+    if (!apiKey || flag(argv, 'force')) {
+        const code = await cmdLogin(argv, env);
+        if (code !== 0)
+            return code;
+    }
+    else {
+        say(`${OK()} Already signed in — skipping login (use --force to re-link).`);
+    }
+    const installCode = cmdInstall(argv.filter((a) => a !== '--force'), env);
+    if (installCode !== 0)
+        return installCode;
+    return cmdDoctor([], env);
+}

package/dist/cli/install.d.ts

@@ -0,0 +1,21 @@
+import { type McpClient } from './clients.js';
+export type InstallAction = 'wrote' | 'updated' | 'unchanged' | 'removed' | 'skipped' | 'failed';
+export interface InstallResult {
+    client: McpClient;
+    action: InstallAction;
+    path: string | null;
+    backupPath?: string;
+    /** Non-fatal thing the user must know (dropped comments, unsupported OS). */
+    warning?: string;
+    error?: string;
+    /** The exact JSON we would write — used by --dry-run and by failure output. */
+    preview?: string;
+}
+export interface InstallOptions {
+    dryRun?: boolean;
+    /** Remove the debugai entry instead of adding it. */
+    remove?: boolean;
+}
+export declare function applyToClient(client: McpClient, opts?: InstallOptions): InstallResult;
+/** True when the client's config already points at this server. */
+export declare function isInstalled(client: McpClient): boolean;

package/dist/cli/install.js

@@ -0,0 +1,150 @@
+// Writes the DebugAI server into MCP client config files.
+//
+// Rules this code refuses to break, because it is editing files a user's
+// whole editor setup depends on:
+//   - never overwrite the file wholesale — parse, touch only our own key,
+//     write everything else back untouched
+//   - back up before the first modification, always, with the path printed
+//   - write to a temp file in the same directory and rename over the target,
+//     so a crash mid-write cannot leave a truncated config behind
+//   - a file we cannot parse is left ALONE and reported, never "fixed"
+//   - running twice is a no-op ("unchanged"), never a duplicate entry
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { parseJsonc } from './jsonc.js';
+import { SERVER_NAME, serverEntry, serversKey } from './clients.js';
+function backupPath(path) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return `${path}.debugai-backup-${stamp}`;
+}
+function writeAtomic(path, contents) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, contents, 'utf8');
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+function sameEntry(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+export function applyToClient(client, opts = {}) {
+    const path = client.configPath;
+    if (!path) {
+        return {
+            client,
+            action: 'skipped',
+            path: null,
+            warning: `${client.label} has no known config location on this operating system.`,
+        };
+    }
+    const key = serversKey(client.shape);
+    const desired = serverEntry(client);
+    let root = {};
+    let hadComments = false;
+    const existed = existsSync(path);
+    if (existed) {
+        let raw;
+        try {
+            raw = readFileSync(path, 'utf8');
+        }
+        catch (err) {
+            return { client, action: 'failed', path, error: `could not read: ${err.message}` };
+        }
+        try {
+            const parsed = parseJsonc(raw);
+            hadComments = parsed.hadComments;
+            if (typeof parsed.value !== 'object' || parsed.value === null || Array.isArray(parsed.value)) {
+                throw new Error('top level is not a JSON object');
+            }
+            root = parsed.value;
+        }
+        catch (err) {
+            // Do NOT rewrite a file we failed to understand — that is how people
+            // lose their editor settings. Report it and hand back the snippet.
+            return {
+                client,
+                action: 'failed',
+                path,
+                error: `could not parse (${err.message}) — left untouched`,
+                preview: JSON.stringify({ [key]: { [SERVER_NAME]: desired } }, null, 2),
+            };
+        }
+    }
+    else if (opts.remove) {
+        return { client, action: 'unchanged', path };
+    }
+    const existingServers = root[key];
+    const servers = typeof existingServers === 'object' && existingServers !== null && !Array.isArray(existingServers)
+        ? { ...existingServers }
+        : {};
+    if (opts.remove) {
+        if (!(SERVER_NAME in servers))
+            return { client, action: 'unchanged', path };
+        delete servers[SERVER_NAME];
+    }
+    else {
+        if (sameEntry(servers[SERVER_NAME], desired))
+            return { client, action: 'unchanged', path };
+        servers[SERVER_NAME] = desired;
+    }
+    const nextRoot = { ...root, [key]: servers };
+    const contents = `${JSON.stringify(nextRoot, null, 2)}\n`;
+    const warning = hadComments && !opts.dryRun
+        ? 'this file had comments; JSON does not keep them, so they were dropped (the backup above still has them)'
+        : undefined;
+    if (opts.dryRun) {
+        return {
+            client,
+            action: opts.remove ? 'removed' : existed ? 'updated' : 'wrote',
+            path,
+            preview: contents,
+            warning: hadComments ? 'this file has comments; installing would drop them (a backup is written first)' : undefined,
+        };
+    }
+    let backup;
+    try {
+        if (existed) {
+            backup = backupPath(path);
+            copyFileSync(path, backup);
+        }
+        writeAtomic(path, contents);
+    }
+    catch (err) {
+        return {
+            client,
+            action: 'failed',
+            path,
+            backupPath: backup,
+            error: err.message,
+            preview: JSON.stringify({ [key]: { [SERVER_NAME]: desired } }, null, 2),
+        };
+    }
+    return {
+        client,
+        action: opts.remove ? 'removed' : existed ? 'updated' : 'wrote',
+        path,
+        backupPath: backup,
+        warning,
+    };
+}
+/** True when the client's config already points at this server. */
+export function isInstalled(client) {
+    if (!client.configPath || !existsSync(client.configPath))
+        return false;
+    try {
+        const parsed = parseJsonc(readFileSync(client.configPath, 'utf8'));
+        const servers = parsed.value?.[serversKey(client.shape)];
+        return Boolean(servers && typeof servers === 'object' && SERVER_NAME in servers);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli/jsonc.d.ts

@@ -0,0 +1,12 @@
+export interface ParsedJsonc {
+    value: unknown;
+    hadComments: boolean;
+}
+export declare function stripJsonComments(text: string): {
+    out: string;
+    hadComments: boolean;
+};
+/** Removes trailing commas before } or ] — legal in JSONC, fatal to JSON.parse. */
+export declare function stripTrailingCommas(text: string): string;
+/** Parses JSON or JSONC. Throws the underlying SyntaxError on real malformed input. */
+export declare function parseJsonc(text: string): ParsedJsonc;

package/dist/cli/jsonc.js

@@ -0,0 +1,115 @@
+// Minimal JSONC tolerance for editor config files.
+//
+// Zed's settings.json and VS Code's mcp.json ship WITH comments and often
+// carry trailing commas. `JSON.parse` throws on both, and a naive regex
+// stripper corrupts any string containing "//" — e.g. every URL in the file.
+// So this walks the text character by character with a string-state machine.
+//
+// Round-tripping comments is out of scope: we detect them (`hadComments`) so
+// the caller can warn the user and back the file up before rewriting.
+export function stripJsonComments(text) {
+    let out = '';
+    let hadComments = false;
+    let i = 0;
+    let inString = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    while (i < text.length) {
+        const ch = text[i];
+        const next = text[i + 1];
+        if (inLineComment) {
+            if (ch === '\n') {
+                inLineComment = false;
+                out += ch;
+            }
+            i++;
+            continue;
+        }
+        if (inBlockComment) {
+            if (ch === '*' && next === '/') {
+                inBlockComment = false;
+                i += 2;
+                continue;
+            }
+            if (ch === '\n')
+                out += ch; // keep line numbers honest for error messages
+            i++;
+            continue;
+        }
+        if (inString) {
+            out += ch;
+            if (ch === '\\') {
+                out += next ?? '';
+                i += 2;
+                continue;
+            }
+            if (ch === '"')
+                inString = false;
+            i++;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            i++;
+            continue;
+        }
+        if (ch === '/' && next === '/') {
+            inLineComment = true;
+            hadComments = true;
+            i += 2;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            inBlockComment = true;
+            hadComments = true;
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return { out, hadComments };
+}
+/** Removes trailing commas before } or ] — legal in JSONC, fatal to JSON.parse. */
+export function stripTrailingCommas(text) {
+    let out = '';
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            out += ch;
+            if (ch === '\\') {
+                out += text[i + 1] ?? '';
+                i++;
+                continue;
+            }
+            if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === ',') {
+            // Look ahead past whitespace for a closer.
+            let j = i + 1;
+            while (j < text.length && /\s/.test(text[j]))
+                j++;
+            if (text[j] === '}' || text[j] === ']')
+                continue; // drop this comma
+        }
+        out += ch;
+    }
+    return out;
+}
+/** Parses JSON or JSONC. Throws the underlying SyntaxError on real malformed input. */
+export function parseJsonc(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return { value: {}, hadComments: false };
+    const { out, hadComments } = stripJsonComments(text);
+    return { value: JSON.parse(stripTrailingCommas(out)), hadComments };
+}

package/dist/cli/ui.d.ts

@@ -0,0 +1,19 @@
+export declare const bold: (s: string) => string;
+export declare const dim: (s: string) => string;
+export declare const red: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const yellow: (s: string) => string;
+export declare const OK: () => string;
+export declare const FAIL: () => string;
+export declare const WARN: () => string;
+export declare const INFO: () => string;
+export declare function say(line?: string): void;
+export declare function heading(text: string): void;
+/**
+ * Opens a URL in the user's browser, best effort. Returns false when there is
+ * clearly no browser to open (headless Linux, CI) so the caller prints the URL
+ * instead of pretending something happened.
+ */
+export declare function openBrowser(url: string): boolean;
+/** Big enough to read across a room, small enough to fit a narrow terminal. */
+export declare function codeBox(code: string): string;