@phantomcodes/cli 1.2.3 → 1.2.4

package/dist/cli/screens.mjs

@@ -0,0 +1,330 @@
+import { paint } from "../core/style.mjs";
+/** The window's width: given, or the terminal's, or 100 for a pipe. */
+const widthOf = (style) => style.columns ?? process.stdout.columns ?? 100;
+/** How long a caption's rule is: 66, or less in a narrow window. */
+const ruleWidth = (style) => Math.max(20, Math.min(66, widthOf(style) - 4));
+/** Dollars as people read them: two decimals, or four under a cent so small spend doesn't read as $0.00. */
+export function usd(n) {
+    const abs = Math.abs(n);
+    return `${n < 0 ? '-' : ''}$${abs > 0 && abs < 0.01 ? abs.toFixed(4) : abs.toFixed(2)}`;
+}
+const plural = (n, one) => `${n} ${one}${n === 1 ? '' : 's'}`;
+/** Spend rows line up: a label column, then a bar, then the dollars; both shrink to fit a narrow window. */
+const spendColumns = (style) => (widthOf(style) < 80 ? { LABEL: 22, BAR: 10 } : { LABEL: 30, BAR: 20 });
+/** An uppercase caption, an optional detail beside it, and a thin rule under both. */
+function caption(p, w, text, detail = '') {
+    const width = w;
+    // The heading in bold, so it's the easiest thing to find, not the quietest.
+    return [`  ${p.bold(text)}${detail ? `  ${detail}` : ''}`, `  ${p.dim('─'.repeat(width))}`];
+}
+/** True inside the app (phantom alone), which offers next steps as choices, so the typed hint isn't needed. */
+let hintsHidden = false;
+/** True while the app runs, so a screen can point at a menu item instead of a command. */
+export const inApp = () => hintsHidden;
+/** Hides or shows every screen's "→ type this next" line, and returns what it was, to put back after. The app hides them while it runs. */
+export function hideHints(hidden) {
+    const was = hintsHidden;
+    hintsHidden = hidden;
+    return was;
+}
+/** The last line of a screen: the one command to type next, in cyan. Not shown inside the app. */
+function next(p, words, command) {
+    return hintsHidden ? [] : ['', `  ${p.lime('→')} ${words} ${p.cyan(command)}`];
+}
+/** A thin bar `width` cells long at `share` of full (0 to 1), in `fill`, on a dimmed track: the site's cost bars. */
+export function bar(p, share, width, fill) {
+    const cells = Math.max(0, Math.min(width, Math.round(share * width)));
+    // A share above zero always shows at least a sliver, so a small spender isn't drawn as nothing.
+    const shown = share > 0 && cells === 0 ? 1 : cells;
+    return fill('━'.repeat(shown)) + p.dim('─'.repeat(width - shown));
+}
+/** A date as `Nov 1, 2026`, read as UTC, or the text as given when it isn't one. */
+function day(iso) {
+    const d = new Date(iso.length === 10 ? `${iso}T00:00:00Z` : iso);
+    return Number.isNaN(d.getTime()) ? iso : d.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric', timeZone: 'UTC' });
+}
+/** `phantom balance`: the credit in bold, then what it spent and when the key stops working. */
+export function balanceScreen(b, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const lines = ['', ...caption(p, w, 'BALANCE'), `  ${p.bold(usd(b.credit_balance_usd))}  ${p.dim('this key can spend')}`, `  ${p.dim('the workspace balance, or less when the key has a limit')}`, ''];
+    lines.push(`  ${p.dim('spent'.padEnd(10))}${usd(b.credit_spent_usd)}`);
+    lines.push(`  ${p.dim('expires'.padEnd(10))}${day(b.expires_at)}`);
+    if (!b.active)
+        lines.push('', `  ${p.red('✗')} This key is switched off or past its expiry.`);
+    if (b.credit_balance_usd <= 0) {
+        lines.push('', `  ${p.lime('✓')} phantom-1 still runs on free models while you have no credit.`);
+        lines.push(...next(p, 'Add credit:', 'phantom fund --amount 10 --card'));
+    }
+    else {
+        lines.push(...next(p, 'See what it went on:', 'phantom spend'));
+    }
+    return lines.join('\n');
+}
+/**
+ * `phantom spend`: the total, what phantom-1 saved, the site's two bars (what
+ * the calls cost against what the same calls cost on the frontier model), then
+ * each model and each key with a bar for its share.
+ */
+export function spendScreen(s, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const { LABEL, BAR } = spendColumns(style);
+    const range = `${day(s.from)} to ${day(s.to)}, UTC`;
+    const lines = ['', ...caption(p, w, s.scope === 'workspace' ? 'WORKSPACE SPEND' : 'SPEND', p.dim(range))];
+    lines.push(`  ${p.bold(usd(s.total.spent_usd))}  ${p.dim(`spent on ${plural(s.total.calls, 'call')}`)}`);
+    if (s.total.plan_usd > 0)
+        lines.push(`  ${p.dim(`${usd(s.total.plan_usd)} of it paid by your plan`)}`);
+    const r = s.routing;
+    if (r.available && r.calls > 0) {
+        // The site's comparison: what phantom-1 cost, in lime, against the same calls on the frontier model.
+        const most = Math.max(r.spent_usd, r.baseline_usd) || 1;
+        lines.push('', `  ${p.lime(p.bold(`phantom-1 saved ${usd(r.saved_usd)}`))}  ${p.dim(`on ${plural(r.calls, 'call')}`)}`);
+        // Labelled by what they mean, with the model the comparison uses said once underneath.
+        lines.push(`  ${'You paid'.padEnd(LABEL)}${bar(p, r.spent_usd / most, BAR, p.lime)}  ${usd(r.spent_usd).padStart(8)}`);
+        lines.push(`  ${'Without phantom-1'.padEnd(LABEL)}${bar(p, r.baseline_usd / most, BAR, p.white)}  ${usd(r.baseline_usd).padStart(8)}`);
+        lines.push(`  ${p.dim(`without phantom-1: the same calls, all on ${r.baseline_model}`)}`);
+    }
+    else if (!r.available) {
+        lines.push('', `  ${p.dim(`phantom-1 savings not shown: ${r.reason}`)}`);
+    }
+    if (s.models.length) {
+        const top = s.models[0].spent_usd || 1;
+        lines.push('', ...caption(p, w, 'BY MODEL'));
+        for (const m of s.models.slice(0, 8)) {
+            lines.push(`  ${m.model.slice(0, LABEL - 1).padEnd(LABEL)}${bar(p, m.spent_usd / top, BAR, p.cyan)}  ${usd(m.spent_usd).padStart(8)}  ${p.dim(plural(m.calls, 'call'))}`);
+        }
+        if (s.models.length > 8)
+            lines.push(`  ${p.dim(`and ${plural(s.models.length - 8, 'more model')}`)}`);
+    }
+    if (s.keys.length > 1) {
+        lines.push('', ...caption(p, w, 'BY KEY'));
+        for (const k of s.keys) {
+            const saved = k.saved_usd ? p.lime(`  saved ${usd(k.saved_usd)}`) : '';
+            lines.push(`  ${k.name.slice(0, LABEL - 1).padEnd(LABEL + BAR + 2)}${usd(k.spent_usd).padStart(8)}  ${p.dim(plural(k.calls, 'call'))}${saved}${k.active ? '' : p.dim('  revoked or rotated')}`);
+        }
+    }
+    if (!s.total.calls)
+        lines.push('', `  ${p.dim('No calls in this range yet.')}`);
+    lines.push(...(s.scope === 'workspace' ? next(p, 'Pick the models phantom-1 runs:', 'phantom lineup') : next(p, 'Every key in the workspace:', 'phantom spend --workspace')));
+    return lines.join('\n');
+}
+/** The keys, one row each: name, the start of the key, what it spent, and its limit. */
+function keyRows(p, keys) {
+    if (!keys.length)
+        return [`  ${p.dim('No keys yet.')}`];
+    return keys.map((k) => {
+        const limit = k.limit_usd != null ? `limit ${usd(k.limit_usd)}` : k.budget_usd != null ? `${usd(k.budget_usd)} every ${plural(k.period_days ?? 30, 'day')}` : 'no limit';
+        const mark = k.is_active === false ? p.dim('off') : p.lime('●');
+        // The id's first 8 characters: enough for --id, which also takes the name.
+        return `  ${mark} ${(k.name ?? 'Key').slice(0, 15).padEnd(16)}${p.dim((k.id ?? '').slice(0, 8).padEnd(10))}${p.dim((k.prefix ?? '').slice(0, 18).padEnd(20))}${usd(k.spent_usd ?? 0).padStart(8)}  ${p.dim(limit)}`;
+    });
+}
+/** `phantom workspace`: the shared balance, each key, and the last few charges. */
+export function workspaceScreen(view, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const lines = ['', ...caption(p, w, 'WORKSPACE', p.dim(`${view.name ?? ''}${view.account_linked ? ' · signed-in account' : ' · guest'}`))];
+    lines.push(`  ${p.bold(usd(view.balance_usd))}  ${p.dim('shared balance')}${view.held_usd ? p.dim(`  ${usd(view.held_usd)} held for requests running now`) : ''}`);
+    lines.push('', ...caption(p, w, 'KEYS', p.dim(String(view.keys.length))), ...keyRows(p, view.keys));
+    const charges = (view.charges ?? []).slice(0, 5);
+    if (charges.length) {
+        lines.push('', ...caption(p, w, 'LATEST CALLS'));
+        // Single calls cost fractions of a cent, so this column always shows four places and lines up.
+        for (const c of charges)
+            lines.push(`  ${(c.model ?? '').slice(0, 33).padEnd(34)}${`$${(c.cost_usd ?? 0).toFixed(4)}`.padStart(8)}  ${p.dim(c.why ?? '')}`.trimEnd());
+    }
+    lines.push(...next(p, 'Make a key for another agent:', 'phantom keys create --save <name>'));
+    return lines.join('\n');
+}
+/** `phantom keys`: the workspace's keys alone. */
+export function keysScreen(keys, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    return ['', ...caption(p, w, 'KEYS', p.dim(String(keys.length))), ...keyRows(p, keys), ...next(p, 'Set a spending limit:', 'phantom keys set --id <name or id> --limit <USD>')].join('\n');
+}
+/** After `phantom login`: signed in, where the key is kept, and the next step. */
+export function signedInScreen(saved, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const where = saved.saved_as === 'default' ? 'Your key is' : `Key "${saved.saved_as}" is`;
+    return ['', `  ${p.lime('✓')} ${p.bold('Signed in.')} ${p.dim(`${where} saved in your ${saved.storage}.`)}`, ...next(p, 'Connect your coding agents:', 'phantom setup')].join('\n');
+}
+/** A ✓ line with an optional dim detail, for a change that worked. */
+function done(p, words, detail = '') {
+    return `  ${p.lime('✓')} ${words}${detail ? `  ${p.dim(detail)}` : ''}`;
+}
+/** `phantom route`: which models "auto" picks from, what it does at the edges, and its rules, in sentences. */
+export function routeScreen(r, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const lines = ['', ...caption(p, w, 'ROUTING', p.dim('how model "auto" picks for this key'))];
+    const policy = r.route_policy;
+    if (!policy) {
+        lines.push('  No route policy, so requests for model "auto" are refused.', `  ${p.dim('phantom-1 picks a model for you without one.')}`);
+        lines.push(...next(p, 'Make one:', 'phantom route set --models a,b,c'));
+        return lines.join('\n');
+    }
+    const row = (label, value) => `  ${p.dim(label.padEnd(14))}${value}`;
+    // One model a line, in the order "auto" tries them, so a long list doesn't wrap.
+    policy.models.forEach((m, k) => lines.push(row(k === 0 ? 'models' : '', `${p.dim(`${k + 1}.`)} ${k === 0 ? `${p.bold(m)}  ${p.dim('the default')}` : m}`)));
+    lines.push(row('applies to', policy.applies_to === 'all' ? 'every request' : 'requests for model "auto"'));
+    lines.push(row('cap used up', policy.on_empty === 'cheapest' ? 'keep going on the cheapest model' : 'stop and refuse requests'));
+    lines.push(row('a model fails', policy.fallback_on_error ? 'try the next one' : 'stop there'));
+    const stick = policy.stick_minutes ?? 5;
+    lines.push(row('conversations', stick ? `stay on their model for ${plural(stick, 'minute')}${policy.stick_by_prompt === false ? ' (by x-phantom-session only)' : ''}` : 'can change model every request'));
+    const rules = policy.rules ?? [];
+    lines.push('', ...caption(p, w, 'RULES', p.dim(rules.length ? 'checked in order; the first that matches picks' : '')));
+    if (!rules.length)
+        lines.push(`  ${p.dim('None: "auto" runs the first model.')}`);
+    rules.forEach((rule, k) => {
+        const when = Object.entries(rule.if).map(([name, value]) => `${name} = ${value}`).join(' and ');
+        lines.push(`  ${p.dim(`${k + 1}.`)} if ${when}, use ${p.bold(rule.use)}`);
+    });
+    lines.push(...next(p, 'See what a request would get now:', 'phantom route test'));
+    return lines.join('\n');
+}
+/** `phantom route test`: the model a request would run on right now, and why. */
+export function routeTestScreen(t, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const lines = [''];
+    if (!t.model)
+        lines.push(`  ${p.red('✗')} A request now would be refused: this key's cap is used up.`);
+    else
+        lines.push(`  ${p.lime('→')} A request now would run on ${p.bold(t.model)}`, `  ${p.dim(t.routed === false ? 'it names its own model, so the route policy is not used' : `because: ${t.reason ?? 'default'}`)}`);
+    if (t.fallbacks?.length)
+        lines.push(`  ${p.dim(`then, if it fails: ${t.fallbacks.join(', ')}`)}`);
+    return lines.join('\n');
+}
+/** What each tier is for, in a few words. */
+export const TIER_ABOUT = { economy: 'short, easy requests', standard: 'everyday coding', frontier: 'the hardest work' };
+/** `phantom lineup`: the model phantom-1 runs in each tier, whether it's the default or your pick, and its fallback. */
+export function lineupScreen(l, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const lines = ['', ...caption(p, w, 'LINEUP', p.dim('the model phantom-1 runs in each tier'))];
+    for (const tier of ['economy', 'standard', 'frontier']) {
+        const mine = Boolean(l.lineup?.[tier]);
+        const fallback = l.lineup?.fallbacks?.[tier];
+        lines.push(`  ${p.bold(tier.toUpperCase().padEnd(10))}${l.tiers[tier].model.padEnd(36)}${mine ? p.lime('your pick') : p.dim('default')}`);
+        lines.push(`  ${' '.repeat(10)}${p.dim(TIER_ABOUT[tier])}${fallback ? p.dim(`  ·  falls back to ${fallback}`) : ''}`);
+    }
+    lines.push(...next(p, 'Pick a model for a tier:', 'phantom lineup set'));
+    return lines.join('\n');
+}
+/** A model's price per million tokens, in and out, for a picker's hint. */
+export function priceHint(c) {
+    const price = c.input_per_m === null || c.output_per_m === null ? 'price not listed now' : `$${c.input_per_m.toFixed(2)} in · $${c.output_per_m.toFixed(2)} out per 1M`;
+    const context = c.context ? ` · ${Math.round(c.context / 1000)}k context` : '';
+    return `${price}${context}${c.default ? ' · default' : ''}`;
+}
+/** `phantom plan`: the plan, as a lime pill, and how much of this week it has used, as a bar. */
+export function planScreen(pl, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const lines = ['', ...caption(p, w, 'PLAN')];
+    if (!pl.plan) {
+        if (!pl.available)
+            return [...lines, '  No plan, and plans are not open right now.'].join('\n');
+        lines.push('  No plan. A plan pays for phantom-1 each week, in place of credit, for every key in this workspace.');
+        if (pl.prices) {
+            lines.push('');
+            for (const name of ['pro', 'max']) {
+                const o = pl.prices[name];
+                lines.push(`  ${p.bold((name === 'max' ? 'Max' : 'Pro').padEnd(6))}$${o.usd_per_month} a month  ${p.dim(`pays for $${o.week_limit_usd} of model cost a week; past that, credit`)}`);
+            }
+        }
+        lines.push(...next(p, 'Start one:', 'phantom plan pro'), ...(hintsHidden ? [] : [`  ${p.dim('  or')} ${p.cyan('phantom plan max')}`]));
+        return lines.join('\n');
+    }
+    const share = pl.week_limit_usd ? pl.week_used_usd / pl.week_limit_usd : 0;
+    lines.push(`  ${p.pill(` ${pl.plan === 'max' ? 'Max' : 'Pro'} `)}  ${pl.status === 'active' ? p.lime('active') : p.yellow(pl.status ?? '')}`, '');
+    lines.push(`  ${p.dim('this week'.padEnd(12))}${bar(p, share, 24, share > 0.9 ? p.yellow : p.lime)}  ${usd(pl.week_used_usd)} of ${usd(pl.week_limit_usd)}`);
+    if (pl.resets_at)
+        lines.push(`  ${p.dim('room frees'.padEnd(12))}from ${day(pl.resets_at)}`);
+    if (pl.renews_at)
+        lines.push(`  ${p.dim('renews'.padEnd(12))}${day(pl.renews_at)}`);
+    lines.push(...next(p, 'Card, switch or cancel:', 'phantom plan manage'));
+    return lines.join('\n');
+}
+/** A link to open in the browser (Stripe Checkout, billing, a wallet), with what it's for and the next step. */
+export function linkScreen(words, url, after, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    return ['', `  ${p.lime('◆')} ${p.bold(words)}`, `    ${p.dim(style.opened ? 'Opened in your browser:' : 'Open:')} ${url}`, ...(after ? next(p, after[0], after[1]) : [])].join('\n');
+}
+/** `phantom fund`: the card checkout link, or the wallet payment link with its id to check on. */
+export function fundScreen(f, style = {}) {
+    if (f.checkout_url) {
+        const total = f.amount_cents ? ` (${usd(f.amount_cents / 100)} with the card fee)` : '';
+        return linkScreen(`Pay by card on Stripe${total}`, f.checkout_url, ['Once it goes through:', 'phantom balance'], style);
+    }
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    return [
+        linkScreen(`Pay ${f.amount ?? ''} ${(f.coin ?? '').toUpperCase()} from your wallet`.replace(/\s+/g, ' '), f.solana_pay_url ?? '', null, style),
+        `    ${p.dim('payment')} ${f.payment_id ?? ''}${f.expires_at ? p.dim(`  ·  good until ${day(f.expires_at)}`) : ''}`,
+        ...next(p, 'Check it landed:', `phantom workspace payment --id ${f.payment_id ?? '<id>'}`),
+    ].join('\n');
+}
+/** `phantom workspace payment`: whether a payment has come in. */
+export function paymentScreen(pay, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const landed = pay.status === 'completed';
+    return ['', landed ? done(p, `Paid. ${usd(pay.credit_usd ?? 0)} of credit is in your workspace.`) : `  ${p.yellow('…')} Not in yet ${p.dim(`(${pay.status})`)}. Payments can take a minute.`, ...(landed ? next(p, 'See it:', 'phantom balance') : [])].join('\n');
+}
+/** What a key change did: created, rotated, revoked or updated, and what to do next. */
+export function keyChangeScreen(change, name, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const named = name && name !== 'default' ? `"${name}"` : 'your default key';
+    const lines = [''];
+    if (change === 'created') {
+        lines.push(done(p, `Key ${named} created${style.limit != null ? ` with a ${usd(style.limit)} limit` : ''}.`, `saved in your ${style.storage ?? 'macOS Keychain'}`));
+        lines.push(...next(p, 'Run an agent on it:', `phantom codex --key ${name ?? 'default'}`));
+    }
+    else if (change === 'rotated') {
+        lines.push(done(p, `Key rotated. ${named} is the new one; the old one stops working.`));
+    }
+    else if (change === 'revoked') {
+        lines.push(done(p, 'Key revoked. Its credit stays in the workspace.'), ...next(p, 'See your keys:', 'phantom keys'));
+    }
+    else {
+        lines.push(done(p, 'Key updated.'), ...next(p, 'See it:', 'phantom keys'));
+    }
+    return lines.join('\n');
+}
+/** `phantom logout`: signed out on this computer, or nothing to sign out of. */
+export function logoutScreen(removed, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const lines = ['', removed ? done(p, 'Signed out on this computer.', 'your workspace, keys and credit are unchanged') : `  ${p.dim('Not signed in on this computer, so nothing changed.')}`];
+    if (style.removedNamed?.length)
+        lines.push(`  ${p.lime('✓')} Forgot the keys saved here: ${style.removedNamed.join(', ')}. ${p.dim('They still work wherever else they are.')}`);
+    if (style.kept?.length)
+        lines.push(`  ${p.dim(`Still saved here: ${plural(style.kept.length, 'key')} by name (${style.kept.join(', ')}). To forget them too:`)} ${p.cyan('phantom logout --all')}`);
+    lines.push(...next(p, 'Sign in again:', 'phantom login'));
+    return lines.join('\n');
+}
+/** `phantom keys saved`: the keys saved on this computer, by name. */
+export function savedKeysScreen(keys, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    const lines = ['', ...caption(p, w, 'KEYS ON THIS COMPUTER', p.dim(String(keys.length)))];
+    if (!keys.length)
+        lines.push(`  ${p.dim('None saved yet.')}`);
+    for (const k of keys) {
+        const credit = k.credit_balance_usd === undefined ? '' : usd(k.credit_balance_usd).padStart(10);
+        lines.push(`  ${k.active === false ? p.dim('off') : p.lime('●')} ${k.name.slice(0, 19).padEnd(20)}${p.dim(k.id.slice(0, 12).padEnd(14))}${credit}`);
+    }
+    lines.push(...next(p, 'Save another:', 'phantom keys save <name>'));
+    return lines.join('\n');
+}
+/** `phantom keys save <name>`: the key is saved under its name, and how to run an agent on it. */
+export function keySavedScreen(name, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    const w = ruleWidth(style);
+    return ['', done(p, `Key "${name}" saved on this computer.`), ...next(p, 'Run an agent on it:', `phantom codex --key ${name}`)].join('\n');
+}

package/dist/cli/start.mjs

@@ -0,0 +1,142 @@
+// What `phantom` alone prints: the way in. With no key yet, one command to
+// start, `phantom setup`. Once signed in, the handful of commands people use
+// day to day. It reads no network, so it prints at once, even offline.
+import { brandHeader } from "../core/brand.mjs";
+import { paint } from "../core/style.mjs";
+/** One row: a command in cyan, padded, then what it does. */
+const row = (p, command, about) => `  ${p.cyan(command.padEnd(18))}${about}`;
+/** An uppercase caption over a thin rule, like the site's section labels. */
+const caption = (p, text) => [`  ${p.bold(text)}`, `  ${p.dim('─'.repeat(56))}`];
+/**
+ * The start screen. `signedIn` is whether a key is saved or set, so it shows
+ * the first step or the everyday commands.
+ */
+export function startScreen(env, color, signedIn) {
+    const p = paint(env, color);
+    const lines = ['', ...brandHeader(p, color, '')];
+    if (!signedIn) {
+        lines.push(...caption(p, 'START HERE'), row(p, 'phantom setup', 'signs you in and connects your coding agents'), `  ${' '.repeat(18)}${p.dim('phantom-1 is free to start: no credit needed')}`, '', `  Then use your agent as usual, or start it with ${p.cyan('phantom claude')}, ${p.cyan('phantom codex')} or ${p.cyan('phantom pi')}.`);
+    }
+    else {
+        lines.push(`  ${p.lime('✓')} Signed in.`, '', ...caption(p, 'EVERYDAY'), row(p, 'phantom claude', 'run Claude Code on Phantom AI (also codex, pi)'), row(p, 'phantom balance', 'your credit'), row(p, 'phantom spend', 'what you spent, and what phantom-1 saved'), row(p, 'phantom setup', 'connect more agents, or change how they run'));
+    }
+    lines.push('', `  All commands: ${p.cyan('phantom --help')}`, '');
+    return lines.join('\n');
+}
+/**
+ * How many single-letter edits turn `a` into `b`: a letter added, removed or
+ * changed, or two neighbours swapped ("yse" is one edit from "yes").
+ */
+export function editDistance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+        }
+    }
+    return d[a.length][b.length];
+}
+/**
+ * The command `typed` was most likely meant to be: the nearest name at most
+ * two edits away, or null. On a tie, the one that starts with the same letter.
+ */
+export function closestCommand(typed, names) {
+    const t = typed.toLowerCase();
+    let best = null;
+    let bestScore = 3;
+    for (const name of names) {
+        // A different first letter counts a little against a guess, so "yse" means "yes", not "use".
+        const score = editDistance(t, name) + (name[0] === t[0] ? 0 : 0.5);
+        if (score < bestScore)
+            [best, bestScore] = [name, score];
+    }
+    return best;
+}
+/** The title block over the start menu: the ghost and PHANTOM. */
+export function startHeader(env, color) {
+    return ['', ...brandHeader(paint(env, color), color, '')].join('\n');
+}
+/**
+ * The start menu's choices, each the command it runs. Without a key, setup
+ * comes first. Signed in but never set up, finishing setup comes first.
+ * Once set up, the agents and the money do, with undo near the end.
+ */
+export function startChoices(signedIn, setUp = signedIn) {
+    const quit = { label: 'Quit', value: [] };
+    if (!signedIn) {
+        return [
+            { label: 'Set up my coding agents', hint: 'sign in and connect them (phantom-1 is free to start)', value: ['setup'] },
+            { label: 'Sign in only', hint: 'or save a Phantom key you already have', value: ['login'] },
+            { label: 'See every command', value: ['--help'] },
+            quit,
+        ];
+    }
+    const finish = setUp ? [] : [{ label: 'Finish setting up my agents', hint: "you're signed in, but no agent uses Phantom yet", value: ['setup'] }];
+    return [
+        ...finish,
+        { label: 'Start Claude Code', hint: 'on Phantom AI', value: ['claude'] },
+        { label: 'Start Codex', hint: 'on Phantom AI', value: ['codex'] },
+        { label: 'Start pi', hint: 'on Phantom AI', value: ['pi'] },
+        { label: 'Balance', hint: 'your credit', value: ['balance'] },
+        { label: 'Spend', hint: 'what you spent, and what phantom-1 saved', value: ['spend'] },
+        { label: 'Add credit', hint: 'by card or crypto', value: ['fund'] },
+        ...(setUp ? [{ label: 'Set up more agents', hint: 'or change how they run', value: ['setup'] }] : []),
+        ...(setUp ? [{ label: 'Undo setup', hint: 'put your agents back how they were', value: ['setup', '--restore'] }] : []),
+        { label: 'See every command', value: ['--help'] },
+        quit,
+    ];
+}
+/** "Unknown <command> subcommand" with the nearest real one, or the list when nothing is close. */
+export function unknownSub(command, typed, subs) {
+    const guess = closestCommand(typed, subs);
+    return guess
+        ? `Unknown phantom ${command} subcommand "${typed}". Did you mean phantom ${command} ${guess}?`
+        : `Unknown phantom ${command} subcommand "${typed}". It takes: ${subs.join(', ')}.`;
+}
+/**
+ * Words people type instead of a command, and the command they mean. These
+ * run as that command, and stay out of --help.
+ */
+export const ALIASES = {
+    help: ['--help'],
+    undo: ['setup', '--restore'],
+    uninstall: ['setup', '--restore'],
+    signin: ['login'],
+    'sign-in': ['login'],
+    signout: ['logout'],
+    'sign-out': ['logout'],
+    add: ['fund'],
+    topup: ['fund'],
+    'top-up': ['fund'],
+    credit: ['fund'],
+    savings: ['spend'],
+    usage: ['spend'],
+    costs: ['spend'],
+    status: ['workspace'],
+    start: [],
+    menu: [],
+};
+/** Words in a sentence typed as a command ("how do i add money"), and the command they point at. */
+const HINTS = [
+    [/^(money|credit|fund|pay|topup|top-up|card)$/, 'fund'],
+    [/^(charged|charge|cost|costs|spent|spend|saving|savings|bill|billing)$/, 'spend'],
+    [/^(undo|uninstall|remove|revert|reset)$/, 'setup --restore'],
+    [/^(setup|connect|install|configure)$/, 'setup'],
+    [/^(balance|left)$/, 'balance'],
+    [/^(key|keys)$/, 'keys'],
+    [/^(claude|codex)$/, 'claude'],
+    [/^(plan|subscription|subscribe)$/, 'plan'],
+    [/^(login|signin|sign)$/, 'login'],
+];
+/** The command a sentence most likely means, from the first word in it that points at one, or null. */
+export function commandFromWords(words) {
+    for (const word of words) {
+        const w = word.toLowerCase().replace(/[^a-z-]/g, '');
+        const hit = HINTS.find(([re]) => re.test(w));
+        if (hit)
+            return hit[1];
+    }
+    return null;
+}

package/dist/core/brand.mjs

@@ -0,0 +1,31 @@
+/** The ghost in block characters: white, eyes set to the right, a wavy hem, and a thin mint edge on its right side. */
+export const GHOST = [
+    [' ▄████▄', ''],
+    ['████ █ ', '▌'],
+    ['███████', '▌'],
+    ['▀█▀█▀█▀', ''],
+];
+/** PHANTOM in three rows of half blocks. Each letter is its three rows, top to bottom. */
+const LETTERS = {
+    P: ['█▀▀▄', '█▀▀ ', '▀   '],
+    H: ['█  █', '█▀▀█', '▀  ▀'],
+    A: ['▄▀▀▄', '█▀▀█', '▀  ▀'],
+    N: ['█▄ █', '█ ▀█', '▀  ▀'],
+    T: ['▀█▀', ' █ ', ' ▀ '],
+    O: ['▄▀▀▄', '█  █', ' ▀▀ '],
+    M: ['█▄ ▄█', '█ ▀ █', '▀   ▀'],
+};
+export const WORDMARK = [0, 1, 2].map((row) => [...'PHANTOM'].map((c) => LETTERS[c][row]).join(' '));
+/** The one line that says what phantom does, everywhere the CLI describes itself. */
+export const TAGLINE = 'Points your coding agents at Phantom AI.';
+/**
+ * A screen's title block: the ghost, PHANTOM beside it, and `label` in lime
+ * with `line` along the ghost's hem. For example `setup  Points your coding
+ * agents at Phantom AI.` Without color, a plain one-line title instead.
+ */
+export function brandHeader(p, color, label, line = TAGLINE) {
+    if (!color)
+        return [`  ${p.bold(`phantom ${label}`.trim())}  ${line}`, ''];
+    const side = [...WORDMARK.map((w) => p.white(w)), `${label ? `${p.bold(p.lime(label))}  ` : ''}${line}`];
+    return [...GHOST.map(([body, rim], k) => `  ${p.white(body)}${p.lime(rim)}${rim ? '' : ' '}   ${side[k]}`.trimEnd()), ''];
+}

package/dist/core/errors.mjs

@@ -34,6 +34,6 @@ export function die(msg, code = 'cli_error', exitCode = 1) {
     throw new CliError(msg, code, exitCode);
 }
 /** How to get a key, for every message about a missing one. */
-export const GET_A_KEY = 'Set PHANTOM_API_KEY, or run: phantom login to connect a workspace';
+export const GET_A_KEY = 'Run phantom login to sign in, or set PHANTOM_API_KEY.';
 /** The message for a command that needs a key and has none. */
-export const NO_KEY = `No API key. ${GET_A_KEY}`;
+export const NO_KEY = `No Phantom key yet. ${GET_A_KEY}`;

package/dist/core/helpers.mjs

@@ -1,26 +1,59 @@
 import { spawn } from 'node:child_process';
 import { PhantomApiError, CliError, die } from "./errors.mjs";
+import { colorOn, paint } from "./style.mjs";
+import { Cancelled, canPick } from "./pick.mjs";
+/**
+ * Where a picker draws and reads, when this run can show one: a person at a
+ * terminal (or keys a test scripted), not CI. Null means use flags and the
+ * plain prompts instead.
+ */
+export function pickIo(input) {
+    const { io, env } = input;
+    if (!(io.keys ? io.isTTY : canPick(env, io.isTTY)))
+        return null;
+    // A command started from the menu goes back to it on Esc; one typed on its own quits.
+    return { write: io.stderr, env, keys: io.keys, esc: io.fromMenu ? 'back' : 'quit', columns: process.stderr.columns };
+}
+/**
+ * Whether a command should draw its screen rather than print JSON: with
+ * `--table`, or when stdout is a terminal, unless `--json` asks for JSON.
+ * Scripts and agents read stdout through a pipe, so they keep getting JSON.
+ */
+export function showsScreen(input) {
+    return input.table || (Boolean(input.io.stdoutIsTTY) && !input.flags['json']);
+}
+/**
+ * A phantom command inside a sentence: `phantom`, its name, a second word for
+ * the commands that take one (`phantom key show`), then any flags. For
+ * example "Run phantom setup to sign in" matches `phantom setup` only.
+ */
+const COMMAND_IN_TEXT = /\bphantom [a-z][a-z-]*(?:(?<=(?:key|keys|workspace|plan|route|route rule)) [a-z][a-z-]*)?(?: --?[a-z][a-z-]*(?: <[^>]+>)?)*/g;
 /**
  * Prints an error to stderr as one line of JSON, `{"error":{...}}`, and
  * returns the exit code: 2 for a key the API rejected (401 or 403), the
  * {@link CliError}'s own code, or 1 for anything else.
  */
-export function handleError(err, stderr = (s) => process.stderr.write(s)) {
-    if (err instanceof PhantomApiError) {
-        stderr(JSON.stringify({
-            error: { status: err.status, code: err.code, message: err.message },
-        }) + '\n');
-        return err.status === 401 || err.status === 403 ? 2 : 1;
+export function handleError(err, stderr = (s) => process.stderr.write(s), opts = {}) {
+    // Ctrl+C in a picker: stop, with the code shells use for it (128 + SIGINT), and no error to read.
+    if (err instanceof Cancelled)
+        return 130;
+    const api = err instanceof PhantomApiError ? err : null;
+    const code = api ? api.code : err instanceof CliError ? err.code : 'unknown';
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.human) {
+        // A person at a terminal reads a sentence; the code stays for support, dimmed.
+        const p = paint(opts.env ?? {}, colorOn(opts.env ?? {}, true));
+        const lit = message.replace(COMMAND_IN_TEXT, (cmd) => p.cyan(cmd));
+        // The code only when it says more than "an error": HTTP 401, invalid_key helps support; cli_error doesn't.
+        const detail = api ? `HTTP ${api.status}, ${code}` : code === 'cli_error' || code === 'unknown' ? '' : code;
+        stderr(`\n  ${p.red('✗')} ${lit}\n${detail ? p.dim(`    ${detail}`) + '\n' : ''}\n`);
     }
-    if (err instanceof CliError) {
-        stderr(JSON.stringify({
-            error: { code: err.code, message: err.message },
-        }) + '\n');
-        return err.exitCode;
+    else {
+        stderr(JSON.stringify({ error: { ...(api ? { status: api.status } : {}), code, message } }) + '\n');
     }
-    const msg = err instanceof Error ? err.message : String(err);
-    stderr(JSON.stringify({ error: { code: 'unknown', message: msg } }) + '\n');
-    return 1;
+    if (api)
+        return api.status === 401 || api.status === 403 ? 2 : 1;
+    return err instanceof CliError ? err.exitCode : 1;
 }
 /**
  * Reads `--name value`, `--name=value` and bare `--name` (true) from the