@phantomcodes/cli 0.0.0-stage → 1.1.0

package/dist/setup/command.mjs

@@ -0,0 +1,112 @@
+import { createInterface } from 'node:readline/promises';
+import { die } from "../core/errors.mjs";
+import { out } from "../core/helpers.mjs";
+import { SETUP_AGENTS, SETUP_NAMES } from "./agents.mjs";
+import { planSetup } from "./plan.mjs";
+import { setupPreview, applySetup, previewSetup, restoreSetup } from "./apply.mjs";
+/** `--table` output for `setup`. */
+export function tableSetup(d) {
+    const r = d;
+    const pad = ''.padEnd(16);
+    const lines = r.agents.map((a) => {
+        const label = SETUP_AGENTS[a.agent]?.label ?? a.agent;
+        const p = a.provider;
+        return [
+            `${a.agent.padEnd(16)}${a.skill ? `skill ${r.dry_run || r.applied === false ? 'goes' : 'installed'} at ${a.skill}` : 'no skill (this agent does not read skills)'}`,
+            ...(!p
+                ? []
+                : p.manual
+                    ? [`${pad}set up by hand in ${p.settings}:`, ...p.manual.map((step, k) => `${pad}  ${k + 1}. ${step}`)]
+                    : p.on
+                        ? [
+                            `${pad}models via Phantom AI at ${p.base_url}${p.model ? `, model ${p.model}` : ''} (${p.settings})`,
+                            `${pad}restart ${label} to pick it up; undo with: phantom setup --agent ${a.agent} --provider off`,
+                        ]
+                        : [a.agent === 'claude' ? `${pad}models back to Anthropic (${p.settings})` : `${pad}Phantom AI settings removed (${p.settings})`]),
+            ...(p?.warnings ?? []).map((w) => `${pad}warning: ${w}`),
+        ].join('\n');
+    });
+    const files = (r.files ?? []).filter((f) => f.diff !== undefined);
+    if (files.length) {
+        lines.push('');
+        for (const f of files) {
+            lines.push(`${r.dry_run || r.applied === false ? `would ${f.action}` : `${f.action}d`} ${f.file}${f.backup ? ` (copy before: ${f.backup})` : ''}`);
+            if (f.diff && (r.dry_run || r.applied === false))
+                lines.push(f.diff.replace(/^/gm, '    '));
+        }
+    }
+    for (const s of r.skipped ?? [])
+        lines.push(`skipped ${s.agent}: ${s.reason}`);
+    for (const n of r.notes ?? [])
+        lines.push(n);
+    if (r.applied === false)
+        lines.push('Nothing was changed.');
+    return lines.join('\n');
+}
+/** `--table` output for `setup --restore`. */
+export function tableRestore(d) {
+    const r = d;
+    const lines = [
+        ...r.restored.map((x) => `${r.dry_run ? 'would restore' : 'restored'} ${x.file}${x.from ? ` from ${x.from}` : ' (phantom created it, so it is removed)'}`),
+        ...r.skipped.map((x) => `skipped ${x.file}: ${x.reason}`),
+    ];
+    return lines.length ? lines.join('\n') : 'Nothing to restore.';
+}
+/** `phantom setup`: plans, previews, asks, applies or restores agent setup. Run by `run()`. */
+export async function setupCommand({ env, io, flags, table }) {
+    const agent = flags['agent'];
+    if (agent === true)
+        die(`--agent requires ${SETUP_NAMES.join(', ')} or all`);
+    const provider = flags['provider'];
+    if (provider !== undefined && provider !== true && provider !== 'off')
+        die('--provider takes no value, or off');
+    const model = flags['model'];
+    if (model === true)
+        die('--model requires a model id, such as auto or claude-sonnet-5');
+    if (flags['mcp'])
+        die('--mcp has been removed. Phantom inference runs directly through phantom claude, phantom codex, or phantom pi.');
+    const dryRun = Boolean(flags['dry-run']);
+    if (flags['restore']) {
+        const result = restoreSetup(env, { agent, dryRun });
+        out(result, table, tableRestore, io.stdout);
+        return result.skipped.length ? 1 : 0;
+    }
+    // Plain `phantom setup` sets up everything it finds and asks first. Any of
+    // the older flags runs just what they name, without asking.
+    const guided = agent === undefined && provider === undefined;
+    const plan = planSetup(env, {
+        agent,
+        provider: guided || provider === true ? true : provider === 'off' ? 'off' : false,
+        model: typeof model === 'string' ? model : undefined,
+        guided,
+    });
+    if (dryRun) {
+        out(previewSetup(plan), table, tableSetup, io.stdout);
+        return 0;
+    }
+    if (guided && !flags['yes'] && plan.files.length) {
+        io.stderr(setupPreview(plan) + '\n\n');
+        const ask = io.ask ??
+            (process.stdin.isTTY
+                ? async (q) => {
+                    const rl = createInterface({ input: process.stdin, output: process.stderr });
+                    try {
+                        return await rl.question(q);
+                    }
+                    finally {
+                        rl.close();
+                    }
+                }
+                : null);
+        if (!ask)
+            die('phantom setup changes the files above. Run it in a terminal to confirm, or add --yes (or --dry-run to only look)', 'confirm_needed');
+        const answer = await ask('Make these changes? [y/N] ');
+        if (!/^y(es)?$/i.test(answer.trim())) {
+            out({ ...previewSetup(plan), dry_run: undefined, applied: false }, table, tableSetup, io.stdout);
+            return 0;
+        }
+    }
+    const result = applySetup(env, plan);
+    out(result, table, tableSetup, io.stdout);
+    return result.skipped ? 1 : 0;
+}

package/dist/setup/editors.mjs

@@ -0,0 +1,486 @@
+import path from 'node:path';
+import os from 'node:os';
+import { isDeepStrictEqual } from 'node:util';
+import { applyEdits, format as formatJsonc, modify as modifyJsonc, parse as parseJsonc, printParseErrorCode } from 'jsonc-parser';
+import { parse as parseTomlText } from 'smol-toml';
+import { KEYCHAIN_SERVICE, KEYCHAIN_POINTER, keychainOn } from "../core/secrets.mjs";
+import { keyPath } from "../keys/saved.mjs";
+import { SETUP_MARK, SETUP_WAS, setupMarked, stripMark, unwas, unreadable, onPath, phantomCommand, configHome } from "./shared.mjs";
+// ── JSON & JSONC ─────────────────────────────────────────────────────────────
+/**
+ * A JSON or JSONC file's object, `{}` when it does not exist. Comments and
+ * trailing commas are fine: jsonc-parser reads them, as in Vercel's setup.
+ */
+export function jsonObject(file, text) {
+    if (text === null || text.trim() === '')
+        return {};
+    const errors = [];
+    const v = parseJsonc(text, errors, { allowTrailingComma: true });
+    if (errors.length)
+        unreadable(file, `is not valid JSON (${printParseErrorCode(errors[0].error)} at offset ${errors[0].offset})`);
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        unreadable(file, 'does not hold a JSON object');
+    return v;
+}
+export function jsonText(v) {
+    return JSON.stringify(v, null, 2) + '\n';
+}
+const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+function jsonGet(obj, p) {
+    return p.reduce((n, k) => (isPlainObject(n) ? n[k] : undefined), obj);
+}
+function jsonSet(obj, p, value) {
+    let n = obj;
+    for (const k of p.slice(0, -1)) {
+        if (!isPlainObject(n[k]))
+            n[k] = {};
+        n = n[k];
+    }
+    if (value === undefined)
+        delete n[p[p.length - 1]];
+    else
+        n[p[p.length - 1]] = value;
+}
+/** The indent and line ending a JSON file already uses, for the lines an edit adds. */
+function jsonFormatting(text) {
+    const indent = /\n([ \t]+)\S/.exec(text)?.[1] ?? '  ';
+    return { insertSpaces: !indent.startsWith('\t'), tabSize: indent.startsWith('\t') ? 1 : indent.length, eol: text.includes('\r\n') ? '\r\n' : '\n' };
+}
+/**
+ * Applies `changes` to a JSON or JSONC file's text with jsonc-parser's
+ * `modify` and `applyEdits`, as Vercel's setup does, so comments, key order
+ * and formatting stay as they were. Only the text an edit inserts is
+ * formatted, in the file's own indent (none in a one-line file), so removing
+ * what was added gives back the same bytes. A new file is written in full. If
+ * the edited text doesn't read back as expected, the file is written in full
+ * instead, as Vercel's does.
+ * @throws {@link CliError} `setup_unreadable` when the file is not valid JSON or JSONC.
+ * @deprecated Compatibility export. Use {@link planSetup}, {@link applySetup}, and {@link restoreSetup} for agent setup.
+ */
+export function jsonEdit(file, text, changes) {
+    const expected = jsonObject(file, text);
+    const todo = changes.filter(([p, v]) => !isDeepStrictEqual(jsonGet(expected, p), v));
+    for (const [p, v] of todo)
+        jsonSet(expected, p, v);
+    if (text === null || text.trim() === '')
+        return jsonText(expected);
+    if (!todo.length)
+        return text;
+    const formatting = text.trim().includes('\n') ? jsonFormatting(text) : null;
+    let out = text;
+    try {
+        for (const [p, v] of todo) {
+            const edits = modifyJsonc(out, p, v, {});
+            out = applyEdits(out, edits);
+            if (formatting && v !== undefined && edits.length === 1)
+                out = applyEdits(out, formatJsonc(out, { offset: edits[0].offset, length: edits[0].content.length }, formatting));
+        }
+        if (isDeepStrictEqual(jsonObject(file, out), expected))
+            return out;
+    }
+    catch {
+        // Written in full below.
+    }
+    return jsonText(expected);
+}
+// ── YAML ─────────────────────────────────────────────────────────────────────
+// YAML, line by line: one entry at the top of Continue's `models:` list, and
+// top-level keys such as Goose's GOOSE_PROVIDER and Aider's `model`.
+/**
+ * Sets a top-level `key: value` in a YAML file, marked `# phantom setup`. A line
+ * it replaces stays as a comment, so `--provider off` can put it back.
+ * @throws {@link CliError} `setup_unreadable` when the file indents with tabs, or the key holds more than one line.
+ * @deprecated Compatibility export. Use {@link planSetup}, {@link applySetup}, and {@link restoreSetup} for agent setup.
+ */
+export function yamlSetTop(file, text, key, value) {
+    const base = text ?? '';
+    if (/^ *\t/m.test(base))
+        unreadable(file, 'indents with tabs, which YAML does not allow');
+    const lines = base === '' ? [] : base.replace(/\n$/, '').split('\n');
+    const mine = `${key}: ${value}  ${SETUP_MARK}`;
+    const at = lines.findIndex((l) => l.startsWith(`${key}:`));
+    if (at !== -1) {
+        if (lines[at].replace(/\s+#.*$/, '') === `${key}: ${value}`)
+            return base;
+        if (/^\S+:\s*(#.*)?$/.test(lines[at]) || /^\s/.test(lines[at + 1] ?? ''))
+            unreadable(file, `holds ${key} over several lines; set it by hand`);
+        lines.splice(at, 1, ...(setupMarked(lines[at]) ? [] : [SETUP_WAS + lines[at]]), mine);
+    }
+    else
+        lines.push(mine);
+    return lines.join('\n') + '\n';
+}
+/**
+ * Adds `item` (lines, unindented, the first starting with `- `) first in the
+ * top-level `models:` list of a YAML file, each line marked `# phantom setup`.
+ * Starts the list when there is none, and the file with `head` when it is
+ * empty. An entry phantom added before is replaced.
+ * @throws {@link CliError} `setup_unreadable` when the file indents with tabs or writes the list on one line.
+ * @deprecated Compatibility export. Use {@link planSetup}, {@link applySetup}, and {@link restoreSetup} for agent setup.
+ */
+export function yamlAddModel(file, text, item, head = []) {
+    const base = yamlRemoveOurs(file, text ?? '');
+    const lines = base === '' ? [] : base.replace(/\n$/, '').split('\n');
+    const at = lines.findIndex((l) => /^models\s*:/.test(l));
+    if (at !== -1 && !/^models\s*:\s*(#.*)?$/.test(lines[at]))
+        unreadable(file, 'writes models: on one line, which phantom does not edit; add the model by hand');
+    let indent = '  ';
+    for (let n = at + 1; at !== -1 && n < lines.length; n++) {
+        if (lines[n].trim() === '' || lines[n].trim().startsWith('#'))
+            continue;
+        const m = /^(\s*)-/.exec(lines[n]);
+        if (m)
+            indent = m[1];
+        break;
+    }
+    const mark = (l) => `${l}  ${SETUP_MARK}`;
+    const entry = item.map((l, k) => mark(indent + (k === 0 ? l : '  ' + l)));
+    if (at !== -1)
+        lines.splice(at + 1, 0, ...entry);
+    else {
+        if (lines.length === 0)
+            lines.push(...head.map(mark));
+        else if (lines[lines.length - 1].trim() !== '')
+            lines.push('');
+        lines.push('models:', ...entry);
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Removes each YAML line marked `# phantom setup`, and puts back the lines they replaced. Returns '' when that leaves nothing but an empty `models:`, as in a file phantom started.
+ * @deprecated Compatibility export. Use {@link planSetup}, {@link applySetup}, and {@link restoreSetup} for agent setup.
+ */
+export function yamlRemoveOurs(file, text) {
+    if (/^ *\t/m.test(text))
+        unreadable(file, 'indents with tabs, which YAML does not allow');
+    const kept = text
+        .split('\n')
+        .filter((l) => !setupMarked(l))
+        .map(unwas);
+    const left = kept.filter((l) => l.trim() !== '');
+    const empty = left.length === 0 || (left.length === 1 && /^models\s*:\s*$/.test(left[0]));
+    return empty && kept.length < text.split('\n').length ? '' : kept.join('\n');
+}
+// ── TOML ─────────────────────────────────────────────────────────────────────
+// TOML. smol-toml, the parser Vercel's `ai-gateway setup` uses, checks each
+// file before an edit and after it. The edit itself goes line by line, so
+// comments and every table phantom does not touch stay as they were.
+const TOML_HEADER = /^\s*\[(\[)?\s*([^\]]*?)\s*\]\]?\s*(?:#.*)?$/;
+/** Parses TOML text, or refuses the file as one setup can't edit. */
+function readToml(file, text) {
+    try {
+        return parseTomlText(text);
+    }
+    catch (err) {
+        unreadable(file, `is not valid TOML (${err.message.split('\n')[0]})`);
+    }
+}
+/** TOML data as text with sorted keys, to compare two parses. */
+function tomlCanonical(v) {
+    return JSON.stringify(v, (_, x) => x && typeof x === 'object' && !Array.isArray(x) && !(x instanceof Date) ? Object.fromEntries(Object.keys(x).sort().map((k) => [k, x[k]])) : x);
+}
+/** A table name as written in a header, with the spaces around its dots taken out. */
+function tomlHeaderName(name) {
+    return name
+        .split('.')
+        .map((s) => s.trim())
+        .join('.');
+}
+function tomlName(p) {
+    return p.map((k) => (/^[A-Za-z0-9_-]+$/.test(k) ? k : JSON.stringify(k))).join('.');
+}
+/** True when any line has text. */
+function hasText(lines) {
+    return lines.some((l) => l.trim() !== '');
+}
+/** The lines as file text, ending in a newline. */
+function linesText(lines, crlf) {
+    const out = [...lines];
+    if (out.length && out[out.length - 1] !== '')
+        out.push('');
+    return out.join(crlf ? '\r\n' : '\n');
+}
+/**
+ * Sets `key` in `table` ([] is the top of the file) to `value`, written as
+ * TOML, and marks the line with `# phantom setup`. A line it replaces stays as a
+ * comment, so `--provider off` can put it back. A missing table is added at
+ * the end of the file. The result must parse to the old file with this one
+ * key changed.
+ * @throws {@link CliError} `setup_unreadable` when the file is not valid TOML, or sets the key in a way a line edit can't change, such as an inline table or a dotted key.
+ * @deprecated Compatibility export. Use {@link planSetup}, {@link applySetup}, and {@link restoreSetup} for agent setup.
+ */
+export function tomlSet(file, text, table, key, value) {
+    const crlf = text.includes('\r\n');
+    const expected = hasText(text.split('\n')) ? readToml(file, text) : {};
+    let node = expected;
+    for (const part of table) {
+        const next = node[part] ?? (node[part] = {});
+        if (!next || typeof next !== 'object' || Array.isArray(next))
+            unreadable(file, `has ${tomlName(table)} as something other than a table; set it by hand`);
+        node = next;
+    }
+    const parsedValue = parseTomlText(`v = ${value}`).v;
+    if (tomlCanonical(node[key]) === tomlCanonical(parsedValue))
+        return text;
+    node[key] = parsedValue;
+    const lines = hasText(text.split('\n')) ? text.replace(/\r\n/g, '\n').split('\n') : [];
+    const mine = `${tomlName([key])} = ${value}  ${SETUP_MARK}`;
+    const name = tomlName(table);
+    const headers = lines.map((l, i) => ({ i, m: TOML_HEADER.exec(l) })).filter((h) => h.m && !lines[h.i].trim().startsWith('#'));
+    const own = headers.find((h) => !h.m[1] && tomlHeaderName(h.m[2]) === name);
+    let start = -1;
+    let end = lines.length;
+    if (table.length === 0) {
+        start = 0;
+        end = headers[0]?.i ?? lines.length;
+    }
+    else if (own) {
+        start = own.i + 1;
+        end = headers.find((h) => h.i > own.i)?.i ?? lines.length;
+    }
+    if (start === -1) {
+        while (lines.length && lines[lines.length - 1].trim() === '')
+            lines.pop();
+        if (lines.length)
+            lines.push('');
+        lines.push(`[${name}]  ${SETUP_MARK}`, mine);
+    }
+    else {
+        const assignment = new RegExp(`^\\s*${RegExp.escape(key)}\\s*=`);
+        const at = lines.slice(start, end).findIndex((l) => assignment.test(l));
+        if (at !== -1) {
+            const old = lines[start + at];
+            lines.splice(start + at, 1, ...(setupMarked(old) ? [] : [SETUP_WAS + old]), mine);
+        }
+        else {
+            let last = -1;
+            for (let i = start; i < end; i++)
+                if (lines[i].trim() !== '' && !lines[i].trim().startsWith('#'))
+                    last = i;
+            if (last !== -1)
+                lines.splice(last + 1, 0, mine);
+            else if (table.length)
+                lines.splice(start, 0, mine);
+            else if (headers.length) {
+                // Nothing at the top yet: go above the first table and the comments on it.
+                let i = headers[0].i;
+                while (i > 0 && lines[i - 1].trim().startsWith('#'))
+                    i--;
+                lines.splice(i, 0, mine, '');
+            }
+            else {
+                while (lines.length && lines[lines.length - 1].trim() === '')
+                    lines.pop();
+                lines.push(mine);
+            }
+        }
+    }
+    const result = linesText(lines, crlf);
+    let after = '';
+    try {
+        after = tomlCanonical(parseTomlText(result));
+    }
+    catch {
+        // Checked below.
+    }
+    if (after !== tomlCanonical(expected))
+        unreadable(file, `sets ${tomlName([...table, key])} in a way phantom can't edit line by line (an inline table, a dotted key or a value over several lines); set it by hand`);
+    return result;
+}
+/**
+ * Removes what {@link tomlSet} wrote: each line marked `# phantom setup`, and a
+ * table phantom added once nothing else is left in it. Lines it replaced come back.
+ * @throws {@link CliError} `setup_unreadable` when the file is not valid TOML, before or after.
+ * @deprecated Compatibility export. Use {@link planSetup}, {@link applySetup}, and {@link restoreSetup} for agent setup.
+ */
+export function tomlRemoveOurs(file, text) {
+    const crlf = text.includes('\r\n');
+    if (hasText(text.split('\n')))
+        readToml(file, text);
+    const lines = text.replace(/\r\n/g, '\n').split('\n');
+    const marked = (i) => !lines[i].trim().startsWith('#') && setupMarked(lines[i]);
+    const headers = lines.map((l, i) => (TOML_HEADER.test(l) && !l.trim().startsWith('#') ? i : -1)).filter((i) => i !== -1);
+    const drop = new Set();
+    for (let i = 0; i < lines.length; i++)
+        if (marked(i) && !headers.includes(i))
+            drop.add(i);
+    for (const [k, h] of headers.entries()) {
+        if (!marked(h))
+            continue;
+        const next = headers[k + 1] ?? lines.length;
+        let keysLeft = false;
+        for (let i = h + 1; i < next; i++)
+            if (!drop.has(i) && lines[i].trim() !== '' && !lines[i].trim().startsWith('#'))
+                keysLeft = true;
+        if (keysLeft) {
+            lines[h] = stripMark(lines[h]);
+            continue;
+        }
+        drop.add(h);
+        if (h > 0 && lines[h - 1].trim() === '')
+            drop.add(h - 1);
+    }
+    const kept = lines.filter((_, i) => !drop.has(i)).map(unwas);
+    const result = hasText(kept) ? linesText(kept, crlf) : '';
+    if (result)
+        readToml(file, result);
+    return result;
+}
+// ── Shell Block ──────────────────────────────────────────────────────────────
+const BLOCK_BEGIN = '# >>> phantom setup >>>';
+const BLOCK_END = '# <<< phantom setup <<<';
+/** The block markers pai, this CLI's old name, wrote. Setup still finds that block. */
+const LEGACY_BLOCK = ['# >>> pai setup >>>', '# <<< pai setup <<<'];
+/**
+ * The shell startup file the key block goes in, by $SHELL, as Vercel's
+ * `ai-gateway setup` picks it: `~/.zshrc` (or `$ZDOTDIR/.zshrc`),
+ * `~/.bash_profile` on macOS and `~/.bashrc` elsewhere, fish's `config.fish`
+ * (under `$XDG_CONFIG_HOME`), or `~/.profile` for any other shell. With no
+ * $SHELL, zsh on macOS and bash elsewhere.
+ * @deprecated Compatibility export. Use {@link planSetup}, {@link applySetup}, and {@link restoreSetup} for agent setup.
+ */
+export function shellRcFile(env, home = env.HOME || os.homedir()) {
+    const shell = path.basename(env.SHELL || (process.platform === 'darwin' ? 'zsh' : 'bash'));
+    if (shell === 'zsh')
+        return path.join(env.ZDOTDIR || home, '.zshrc');
+    // Terminal windows on macOS start bash as a login shell, which reads ~/.bash_profile.
+    if (shell === 'bash')
+        return path.join(home, process.platform === 'darwin' ? '.bash_profile' : '.bashrc');
+    if (shell === 'fish')
+        return path.join(configHome(env, home), 'fish', 'config.fish');
+    return path.join(home, '.profile');
+}
+/**
+ * The block phantom adds to a shell startup file. When the shell starts it sets
+ * PHANTOM_API_KEY, unless it is set already: on macOS straight from the
+ * Keychain item the login key points to, and otherwise (or with
+ * PHANTOM_KEY_NAME set) by running `phantom key show`. The key itself is never
+ * written here. Each agent's own variables follow, set only when there is a key.
+ * @param fish Fish syntax instead of sh, bash and zsh.
+ * @deprecated Compatibility export. Use {@link planSetup}, {@link applySetup}, and {@link restoreSetup} for agent setup.
+ */
+export function shellBlock(env, fish, state, onPathFn = onPath) {
+    const home = env.HOME || os.homedir();
+    const login = keyPath(env);
+    const pointer = login.startsWith(home + path.sep) ? `$HOME/${path.relative(home, login)}` : login;
+    const show = `${phantomCommand(onPathFn)} key show 2>/dev/null`;
+    const fromKeychain = `/usr/bin/security find-generic-password -s ${KEYCHAIN_SERVICE} -a "$__phantom_id" -w 2>/dev/null | /usr/bin/base64 -D 2>/dev/null`;
+    const pointerId = `sed -n 's/^${KEYCHAIN_POINTER}//p' "${pointer}" 2>/dev/null`;
+    const keychain = keychainOn(env);
+    const own = state.agents.flatMap((a) => state.lines.get(a) ?? []);
+    const head = [
+        BLOCK_BEGIN,
+        '# Written by phantom setup. Sets PHANTOM_API_KEY to the key phantom uses when the',
+        '# shell starts, for coding agents that read it. The key is not stored here.',
+        `# agents: ${state.agents.join(' ')}`,
+        '# Undo: phantom setup --provider off',
+    ];
+    if (fish) {
+        return [
+            ...head,
+            'if test -z "$PHANTOM_API_KEY"',
+            ...(keychain
+                ? [
+                    '  set -l __phantom_id',
+                    `  test -z "$PHANTOM_KEY_NAME"; and set __phantom_id (${pointerId})`,
+                    '  if test -n "$__phantom_id"',
+                    `    set -gx PHANTOM_API_KEY (${fromKeychain})`,
+                    '  else',
+                    `    set -gx PHANTOM_API_KEY (${show})`,
+                    '  end',
+                ]
+                : [`  set -gx PHANTOM_API_KEY (${show})`]),
+            'end',
+            'if test -n "$PHANTOM_API_KEY"',
+            ...own,
+            'else',
+            '  set -e PHANTOM_API_KEY',
+            'end',
+            BLOCK_END,
+        ].join('\n');
+    }
+    return [
+        ...head,
+        'if [ -z "${PHANTOM_API_KEY:-}" ]; then',
+        ...(keychain
+            ? [
+                '  __phantom_id=""',
+                `  if [ -z "\${PHANTOM_KEY_NAME:-}" ]; then __phantom_id=$(${pointerId}); fi`,
+                '  if [ -n "$__phantom_id" ]; then',
+                `    PHANTOM_API_KEY=$(${fromKeychain})`,
+                '  else',
+                `    PHANTOM_API_KEY=$(${show})`,
+                '  fi',
+                '  unset __phantom_id',
+            ]
+            : [`  PHANTOM_API_KEY=$(${show})`]),
+        'fi',
+        'if [ -n "${PHANTOM_API_KEY:-}" ]; then',
+        '  export PHANTOM_API_KEY',
+        ...own,
+        'else',
+        '  unset PHANTOM_API_KEY',
+        'fi',
+        BLOCK_END,
+    ].join('\n');
+}
+/** One agent's variables as block lines, each ending with `# for <agent>`. */
+function shellLines(fish, agent, vars) {
+    return Object.entries(vars).map(([k, v]) => (fish ? `  set -gx ${k} ${JSON.stringify(v)}  # for ${agent}` : `  export ${k}=${JSON.stringify(v)}  # for ${agent}`));
+}
+/** Where the phantom block sits in a startup file, and what it holds. null when there is none. */
+function findBlock(file, lines) {
+    const marks = [[BLOCK_BEGIN, BLOCK_END], LEGACY_BLOCK].find(([b, e]) => lines.includes(b) || lines.includes(e));
+    if (!marks)
+        return null;
+    const [begin, finish] = marks;
+    const start = lines.indexOf(begin);
+    const end = lines.indexOf(finish);
+    if (start === -1 || end < start || lines.indexOf(begin, start + 1) !== -1)
+        unreadable(file, 'has a phantom setup block without its matching end line');
+    const inside = lines.slice(start, end);
+    const agents = (inside.find((l) => l.startsWith('# agents:')) ?? '').slice('# agents:'.length).trim().split(/\s+/).filter(Boolean);
+    const own = new Map();
+    for (const l of inside) {
+        const m = /# for ([a-z]+)$/.exec(l);
+        if (m)
+            own.set(m[1], [...(own.get(m[1]) ?? []), l]);
+    }
+    return { start, end, state: { agents, lines: own } };
+}
+/**
+ * The startup file's text with the phantom block updated: agents in `on` added
+ * with fresh lines, agents in `off` dropped. The block goes away when no agent
+ * is left. Text outside the block stays as it was.
+ */
+export function withShellBlock(env, file, text, on, off, onPathFn) {
+    const fish = file.endsWith('.fish');
+    const lines = text === null ? [] : text.split('\n');
+    const found = findBlock(file, lines);
+    const state = found ? found.state : { agents: [], lines: new Map() };
+    for (const a of off) {
+        state.agents = state.agents.filter((x) => x !== a);
+        state.lines.delete(a);
+    }
+    for (const [a, vars] of on) {
+        if (!state.agents.includes(a))
+            state.agents.push(a);
+        state.lines.set(a, shellLines(fish, a, vars));
+    }
+    const block = state.agents.length ? shellBlock(env, fish, state, onPathFn).split('\n') : [];
+    if (found) {
+        let from = found.start;
+        if (!block.length && from > 0 && lines[from - 1] === '')
+            from--;
+        lines.splice(from, found.end + 1 - from, ...block);
+    }
+    else if (block.length) {
+        while (lines.length && lines[lines.length - 1] === '')
+            lines.pop();
+        if (lines.length)
+            lines.push('');
+        lines.push(...block, '');
+    }
+    const result = lines.join('\n');
+    return text === null && result === '' ? null : result;
+}

package/dist/setup/legacy.mjs

@@ -0,0 +1,36 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readText } from "./shared.mjs";
+import { jsonObject, shellRcFile } from "./editors.mjs";
+import { claudeDir } from "./agents.mjs";
+/**
+ * What phantom prints, once per run in a terminal, while an agent setup that
+ * pai (this CLI's old name) wrote still runs `pai`. Once pai is gone, that
+ * setup can't get a key until `phantom setup` rewrites it.
+ */
+export const LEGACY_SETUP_HINT = 'Your agent setup still runs pai, the old name of this CLI. Run phantom setup to switch it to phantom.';
+/**
+ * True when an agent setup still runs `pai`: Claude Code's `apiKeyHelper`
+ * calls it, or the shell startup file holds the block pai setup wrote.
+ * `phantom setup` finds and rewrites both.
+ */
+export function legacySetupFound(env) {
+    const home = env.HOME || os.homedir();
+    const file = path.join(claudeDir(env, home), 'settings.json');
+    try {
+        // JSONC, as setup reads it: Claude Code allows comments and trailing commas.
+        const helper = jsonObject(file, readText(file)).apiKeyHelper;
+        if (typeof helper === 'string' && /\bpai\b.* key show$/.test(helper))
+            return true;
+    }
+    catch {
+        // Not valid JSON: phantom setup reports that file itself.
+    }
+    try {
+        return readText(shellRcFile(env, home))?.split('\n').includes('# >>> pai setup >>>') ?? false;
+    }
+    catch {
+        // Unreadable (a folder, or no permission): the hint is optional, so skip it.
+        return false;
+    }
+}