@phantomcodes/cli 0.0.0-stage → 1.0.0

package/dist/setup/agents.mjs

@@ -0,0 +1,437 @@
+import path from 'node:path';
+import os from 'node:os';
+import { existsSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+import { die } from "../core/errors.mjs";
+import { resolveApiKey } from "../keys/saved.mjs";
+import { SETUP_MODEL, agentBaseUrl, MCP_ARGS, mcpByCli, readText, configHome, onPath, phantomCommand, offResult, unreadable, SETUP_MARK, SETUP_CONTEXT_WINDOW, } from "./shared.mjs";
+import { jsonObject, jsonEdit, tomlSet, tomlRemoveOurs, yamlSetTop, yamlAddModel, yamlRemoveOurs } from "./editors.mjs";
+// ── Manual Provider Helper ───────────────────────────────────────────────────
+/** An agent whose model settings live on its own settings screen: setup prints the steps. */
+export function manualProvider(where, steps) {
+    return (ctx, off) => ({
+        edits: [],
+        result: { settings: where, on: false, warnings: [], manual: off ? [`Remove the Phantom AI settings in ${where}.`] : steps(ctx) },
+    });
+}
+// ── Codex ────────────────────────────────────────────────────────────────────
+/** Codex's folder: `$CODEX_HOME`, else `~/.codex`. */
+export function codexDir(env, home) {
+    return env.CODEX_HOME?.trim() ? env.CODEX_HOME : path.join(home, '.codex');
+}
+/**
+ * Codex: `config.toml` in Codex's folder gets a `phantom` model provider at
+ * `/codex/v1` that reads the key from PHANTOM_API_KEY (as Vercel's writes a
+ * `vercel` provider with `env_key`). phantom also writes the model, and Phantom
+ * AI's model list at `/codex/v1/models`, which Codex 0.156 reads only with
+ * `[features] api_key_model_discovery`.
+ */
+export function codexProvider(ctx, off) {
+    const file = path.join(codexDir(ctx.env, ctx.home), 'config.toml');
+    const text = readText(file);
+    if (off)
+        return offResult('Codex', file, text, text === null ? null : tomlRemoveOurs(file, text));
+    const base = agentBaseUrl(ctx.env, 'codex');
+    const model = ctx.model ?? SETUP_MODEL;
+    let t = tomlSet(file, text ?? '', [], 'model', JSON.stringify(model));
+    t = tomlSet(file, t, [], 'model_provider', '"phantom"');
+    const provider = [
+        ['name', 'Phantom AI'],
+        ['base_url', base],
+        ['wire_api', 'responses'],
+        ['env_key', 'PHANTOM_API_KEY'],
+        ['model_catalog_url', `${base}/models`],
+    ];
+    for (const [k, v] of provider)
+        t = tomlSet(file, t, ['model_providers', 'phantom'], k, JSON.stringify(v));
+    t = tomlSet(file, t, ['features'], 'api_key_model_discovery', 'true');
+    return { edits: [{ file, after: t }], result: { settings: file, on: true, base_url: base, model, warnings: [] } };
+}
+// ── Claude Code ──────────────────────────────────────────────────────────────
+/** Claude Code's folder: `$CLAUDE_CONFIG_DIR`, else `~/.claude`. */
+export function claudeDir(env, home) {
+    return env.CLAUDE_CONFIG_DIR?.trim() ? env.CLAUDE_CONFIG_DIR : path.join(home, '.claude');
+}
+/** The plan behind {@link claudeProvider}. */
+export function claudePlan(env, opts) {
+    const file = path.join(claudeDir(env, env.HOME || os.homedir()), 'settings.json');
+    const text = readText(file);
+    const settings = jsonObject(file, text);
+    const ours = typeof settings.apiKeyHelper === 'string' && /(?:pai|phantom).* key show$/.test(settings.apiKeyHelper);
+    const vars = { ...(settings.env ?? {}) };
+    if (opts.off) {
+        const changes = [];
+        if (ours) {
+            changes.push([['apiKeyHelper'], undefined]);
+            const mine = ['ANTHROPIC_BASE_URL', 'ENABLE_TOOL_SEARCH', 'ANTHROPIC_MODEL', 'CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY', ...(vars.ANTHROPIC_API_KEY === '' ? ['ANTHROPIC_API_KEY'] : [])];
+            if (Object.keys(vars).every((k) => mine.includes(k)))
+                changes.push([['env'], undefined]);
+            else
+                for (const k of mine)
+                    changes.push([['env', k], undefined]);
+        }
+        return {
+            edits: text === null || !ours ? [] : [{ file, after: jsonEdit(file, text, changes) }],
+            result: { settings: file, on: false, warnings: ours ? [] : ['Claude Code was not set to Phantom AI by phantom; nothing changed'] },
+        };
+    }
+    if (!resolveApiKey(env))
+        die('No API key to give Claude Code. Run: phantom login', 'no_key');
+    const baseUrl = agentBaseUrl(env, 'claude-code');
+    // `phantom` if it's installed, else this very phantom by absolute path: Claude Code
+    // runs the helper outside this shell, so a relative or npx path won't do.
+    const set = {
+        ANTHROPIC_BASE_URL: baseUrl,
+        // Empty, as Vercel's setup writes it, so an ANTHROPIC_API_KEY in the shell
+        // can't win over the Phantom key: the settings file outranks the shell.
+        ANTHROPIC_API_KEY: '',
+        ENABLE_TOOL_SEARCH: 'true',
+        CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: '1',
+        ...(opts.model ? { ANTHROPIC_MODEL: opts.model } : {}),
+    };
+    const changes = [[['apiKeyHelper'], `${phantomCommand(opts.onPath ?? onPath)} key show`], ...Object.entries(set).map(([k, v]) => [['env', k], v])];
+    // A token outranks apiKeyHelper, and would send a non-Phantom key.
+    const warnings = env.ANTHROPIC_AUTH_TOKEN ? ['ANTHROPIC_AUTH_TOKEN is set in this shell and overrides the Phantom key; unset it before running claude'] : [];
+    if (opts.model?.replace(/^claude-code\//, '') === 'auto')
+        warnings.push('auto runs what the key\'s route policy picks; set one with: phantom route set --models a,b');
+    return { edits: [{ file, after: jsonEdit(file, text, changes) }], result: { settings: file, on: true, base_url: baseUrl, model: set.ANTHROPIC_MODEL ?? vars.ANTHROPIC_MODEL, warnings } };
+}
+// ── Copilot ──────────────────────────────────────────────────────────────────
+/** GitHub Copilot CLI's folder: `$COPILOT_HOME`, else `~/.copilot`. */
+export function copilotDir(env, home) {
+    return env.COPILOT_HOME?.trim() ? env.COPILOT_HOME : path.join(home, '.copilot');
+}
+/** GitHub Copilot CLI: set up by the shell block alone, as Vercel's setup does. Its variables are in {@link SetupAgentSpec.shellEnv}. */
+export function copilotProvider(ctx, off) {
+    return off
+        ? { edits: [], result: { settings: ctx.shellRc, on: false, warnings: [] } }
+        : {
+            edits: [],
+            result: {
+                settings: ctx.shellRc,
+                on: true,
+                base_url: agentBaseUrl(ctx.env, 'coding-agent'),
+                model: ctx.model ?? SETUP_MODEL,
+                warnings: ['GitHub Copilot CLI reads its settings from the shell; open a new terminal before running it'],
+            },
+        };
+}
+// ── opencode ─────────────────────────────────────────────────────────────────
+/** opencode's config file: `opencode.json` (or `.jsonc`) in `$XDG_CONFIG_HOME/opencode`, else `~/.config/opencode`. */
+export function opencodeFile(env, home) {
+    const dir = path.join(configHome(env, home), 'opencode');
+    return existsSync(path.join(dir, 'opencode.jsonc')) ? path.join(dir, 'opencode.jsonc') : path.join(dir, 'opencode.json');
+}
+/**
+ * opencode: a `phantom` provider at `/coding-agent/v1` whose key is
+ * `{env:PHANTOM_API_KEY}`. Like Vercel's setup, it pins no model unless
+ * `--model` asks; pick `phantom/<model>` in opencode.
+ */
+export function opencodeProvider(ctx, off) {
+    const file = opencodeFile(ctx.env, ctx.home);
+    const text = readText(file);
+    const config = jsonObject(file, text);
+    if (off) {
+        const ours = Boolean(config.provider?.phantom);
+        const changes = [Object.keys(config.provider ?? {}).length === 1 ? [['provider'], undefined] : [['provider', 'phantom'], undefined]];
+        if (typeof config.model === 'string' && config.model.startsWith('phantom/'))
+            changes.push([['model'], undefined]);
+        const left = jsonObject(file, ours ? jsonEdit(file, text, changes) : text);
+        const empty = Object.keys(left).every((k) => k === '$schema');
+        return offResult('opencode', file, text, ours ? (empty ? '' : jsonEdit(file, text, changes)) : text);
+    }
+    const base = agentBaseUrl(ctx.env, 'coding-agent');
+    const model = ctx.model ?? SETUP_MODEL;
+    const changes = [
+        ...(!text?.trim() ? [[['$schema'], 'https://opencode.ai/config.json']] : []),
+        [
+            ['provider', 'phantom'],
+            { npm: '@ai-sdk/openai-compatible', name: 'Phantom AI', options: { baseURL: base, apiKey: '{env:PHANTOM_API_KEY}' }, models: { [model]: { name: model } } },
+        ],
+        ...(ctx.model ? [[['model'], `phantom/${ctx.model}`]] : []),
+    ];
+    return {
+        edits: [{ file, after: jsonEdit(file, text, changes) }],
+        result: { settings: file, on: true, base_url: base, ...(ctx.model ? { model: `phantom/${ctx.model}` } : {}), warnings: ctx.model ? [] : [`Pick phantom/${model} with /models in opencode`] },
+    };
+}
+// ── Continue ─────────────────────────────────────────────────────────────────
+/**
+ * Continue: `~/.continue/config.yaml` gets a model at `/coding-agent/v1`,
+ * first in `models:` so the `cn` CLI starts with it, with the key from
+ * `${{ secrets.PHANTOM_API_KEY }}`. Like Vercel's setup it also writes
+ * `.onboarding_complete` beside it, so `cn`'s first-run questions don't
+ * replace the list.
+ */
+export function continueProvider(ctx, off) {
+    const file = path.join(ctx.home, '.continue', 'config.yaml');
+    const text = readText(file);
+    if (off)
+        return offResult('Continue', file, text, text === null ? null : yamlRemoveOurs(file, text));
+    const base = agentBaseUrl(ctx.env, 'coding-agent');
+    const model = ctx.model ?? SETUP_MODEL;
+    const after = yamlAddModel(file, text, [`- name: Phantom AI ${model}`, 'provider: openai', `model: ${model}`, `apiBase: ${base}`, 'apiKey: ${{ secrets.PHANTOM_API_KEY }}'], ['name: Local Config', 'version: 1.0.0', 'schema: v1']);
+    const marker = path.join(ctx.home, '.continue', '.onboarding_complete');
+    return {
+        edits: [{ file, after }, { file: marker, after: readText(marker) ?? `${new Date().toISOString()}\n` }],
+        result: { settings: file, on: true, base_url: base, model, warnings: [] },
+    };
+}
+// ── Goose ────────────────────────────────────────────────────────────────────
+/**
+ * Goose, as Vercel's setup does it: a custom provider file,
+ * `custom_providers/custom_phantom.json` in Goose's folder, at
+ * `/coding-agent/v1/chat/completions` with the key from PHANTOM_API_KEY, and
+ * GOOSE_PROVIDER and GOOSE_MODEL in Goose's `config.yaml`, which the desktop
+ * app reads too.
+ */
+export function gooseProvider(ctx, off) {
+    const dir = path.join(configHome(ctx.env, ctx.home), 'goose');
+    const config = path.join(dir, 'config.yaml');
+    const file = path.join(dir, 'custom_providers', 'custom_phantom.json');
+    const text = readText(file);
+    const yaml = readText(config);
+    if (off) {
+        const after = yaml === null ? null : yamlRemoveOurs(config, yaml);
+        const edits = [...(text === null ? [] : [{ file, after: null }]), ...(yaml !== null && after !== yaml ? [{ file: config, after: after || null }] : [])];
+        return { edits, result: { settings: config, on: false, warnings: edits.length ? [] : ['Goose was not set to Phantom AI by phantom; nothing changed'] } };
+    }
+    const base = agentBaseUrl(ctx.env, 'coding-agent');
+    const model = ctx.model ?? SETUP_MODEL;
+    const provider = {
+        name: 'custom_phantom',
+        engine: 'openai',
+        display_name: 'Phantom AI',
+        description: 'Phantom AI, set up by phantom',
+        api_key_env: 'PHANTOM_API_KEY',
+        base_url: `${base}/chat/completions`,
+        models: [{ name: model, context_limit: SETUP_CONTEXT_WINDOW }],
+        supports_streaming: true,
+        requires_auth: true,
+    };
+    const yamlAfter = yamlSetTop(config, yamlSetTop(config, yaml, 'GOOSE_PROVIDER', 'custom_phantom'), 'GOOSE_MODEL', model);
+    return {
+        edits: [
+            { file, after: jsonEdit(file, text, Object.entries(provider).map(([k, v]) => [[k], v])) },
+            { file: config, after: yamlAfter },
+        ],
+        result: { settings: config, on: true, base_url: base, model, warnings: [] },
+    };
+}
+// ── Aider ────────────────────────────────────────────────────────────────────
+/**
+ * Aider, as Vercel's setup does it: `~/.aider.conf.yml` gets
+ * `openai-api-base` at `/coding-agent/v1` and the model as `openai/<model>`,
+ * `~/.aider.model.metadata.json` and `~/.aider.model.settings.yml` tell Aider
+ * the model's context window and edit format, and the key comes from
+ * AIDER_OPENAI_API_KEY in the shell block.
+ */
+export function aiderProvider(ctx, off) {
+    const conf = path.join(ctx.home, '.aider.conf.yml');
+    const meta = path.join(ctx.home, '.aider.model.metadata.json');
+    const settingsFile = path.join(ctx.home, '.aider.model.settings.yml');
+    const [confText, metaText, setText] = [readText(conf), readText(meta), readText(settingsFile)];
+    const id = `openai/${ctx.model ?? SETUP_MODEL}`;
+    const metadata = jsonObject(meta, metaText);
+    if (off) {
+        const edits = [];
+        const confAfter = confText === null ? null : yamlRemoveOurs(conf, confText);
+        if (confText !== null && confAfter !== confText)
+            edits.push({ file: conf, after: confAfter || null });
+        const setAfter = setText === null ? null : yamlRemoveOurs(settingsFile, setText);
+        if (setText !== null && setAfter !== setText)
+            edits.push({ file: settingsFile, after: setAfter || null });
+        const ours = Object.keys(metadata).filter((k) => [metadata[k]].some((m) => m?.phantom === true || m?.pai === true));
+        if (ours.length)
+            edits.push({ file: meta, after: ours.length === Object.keys(metadata).length ? null : jsonEdit(meta, metaText, ours.map((k) => [[k], undefined])) });
+        return { edits, result: { settings: conf, on: false, warnings: edits.length ? [] : ['Aider was not set to Phantom AI by phantom; nothing changed'] } };
+    }
+    const base = agentBaseUrl(ctx.env, 'coding-agent');
+    const confAfter = yamlSetTop(conf, yamlSetTop(conf, confText, 'openai-api-base', base), 'model', id);
+    // `phantom: true` marks the entries phantom wrote, so off removes only those.
+    const metaAfter = jsonEdit(meta, metaText, [[[id], { max_input_tokens: SETUP_CONTEXT_WINDOW, litellm_provider: 'openai', mode: 'chat', phantom: true }]]);
+    const setBase = setText === null ? '' : yamlRemoveOurs(settingsFile, setText);
+    const entry = [`- name: ${id}`, '  edit_format: diff', '  use_repo_map: true'].map((l) => `${l}  ${SETUP_MARK}`);
+    const setAfter = (setBase === '' ? [] : [setBase.replace(/\n$/, '')]).concat(entry).join('\n') + '\n';
+    return {
+        edits: [
+            { file: conf, after: confAfter },
+            { file: meta, after: metaAfter },
+            { file: settingsFile, after: setAfter },
+        ],
+        result: { settings: conf, on: true, base_url: base, model: id, warnings: ['Aider reads its key from the shell; open a new terminal before running it'] },
+    };
+}
+/**
+ * Cline, as Vercel's setup does it: `~/.cline/data/settings/providers.json`
+ * (mode 600), which Cline's CLI and editor extension share, gets an OpenAI
+ * Compatible provider at `/coding-agent/v1` and is made the one Cline uses.
+ * Cline reads its key only from this file, with no variable or command to
+ * point it at, so this is the one config phantom writes the key into. After
+ * `phantom rotate`, run setup again to update it.
+ */
+export function clineProvider(ctx, off) {
+    const file = path.join(ctx.home, '.cline', 'data', 'settings', 'providers.json');
+    const text = readText(file);
+    const data = jsonObject(file, text);
+    const base = agentBaseUrl(ctx.env, 'coding-agent');
+    const current = data.providers?.['openai-compatible'];
+    const ours = Boolean(current?.settings?.baseUrl && /\/coding-agent\/v1$/.test(current.settings.baseUrl) && current.settings.baseUrl.startsWith(base.replace(/\/coding-agent\/v1$/, '')));
+    if (off) {
+        const changes = [[['providers', 'openai-compatible'], undefined]];
+        if (data.lastUsedProvider === 'openai-compatible')
+            changes.push([['lastUsedProvider'], undefined]);
+        return offResult('Cline', file, text, ours ? jsonEdit(file, text, changes) : text);
+    }
+    if (current && !ours)
+        unreadable(file, `already has an OpenAI Compatible provider at ${current.settings?.baseUrl ?? 'another address'}, which phantom leaves alone`);
+    const model = ctx.model ?? SETUP_MODEL;
+    const entry = {
+        settings: { provider: 'openai-compatible', apiKey: resolveApiKey(ctx.env), model, baseUrl: base, contextWindow: SETUP_CONTEXT_WINDOW },
+        updatedAt: new Date().toISOString(),
+        tokenSource: 'manual',
+    };
+    // A rerun with the same settings keeps the old timestamp, so nothing changes.
+    if (current && isDeepStrictEqual({ ...current, updatedAt: '' }, { ...entry, updatedAt: '' }))
+        entry.updatedAt = current.updatedAt;
+    const changes = [
+        ...(text === null ? [[['version'], 1]] : []),
+        [['lastUsedProvider'], 'openai-compatible'],
+        [['providers', 'openai-compatible'], entry],
+    ];
+    return {
+        edits: [{ file, after: jsonEdit(file, text, changes), mode: 0o600 }],
+        result: {
+            settings: file,
+            on: true,
+            base_url: base,
+            model,
+            warnings: ['Cline keeps the key in this file (mode 600); run phantom setup --agent cline --provider again after phantom rotate', 'In the editor extension, pick OpenAI Compatible under Settings, API Provider'],
+        },
+    };
+}
+// ── Registry ─────────────────────────────────────────────────────────────────
+/**
+ * The agents `phantom setup` knows, in the order setup runs them. Adding an agent
+ * is one entry here and its name in {@link SetupAgent}: help, errors and
+ * `--agent` read their names from this list.
+ * @deprecated Compatibility export. Use {@link planSetup}, {@link applySetup}, and {@link restoreSetup} for agent setup.
+ */
+export const SETUP_AGENTS = {
+    /** pi. No MCP; it uses the CLI through the skill. */
+    pi: {
+        label: 'pi',
+        /** ~/.pi */
+        home: '.pi',
+        /** ~/.agents/skills */
+        skills: '.agents/skills',
+    },
+    /** Codex. */
+    codex: {
+        label: 'Codex',
+        /** ~/.codex, or $CODEX_HOME */
+        home: '.codex',
+        detect: (env, home) => existsSync(codexDir(env, home)),
+        /** ~/.agents/skills */
+        skills: '.agents/skills',
+        mcp: mcpByCli('codex'),
+        provider: codexProvider,
+        shellEnv: () => ({}),
+    },
+    /** Claude Code. Needs no shell block: it runs `phantom key show` itself. */
+    claude: {
+        label: 'Claude Code',
+        /** ~/.claude, or $CLAUDE_CONFIG_DIR */
+        home: '.claude',
+        detect: (env, home) => existsSync(claudeDir(env, home)),
+        /** ~/.claude/skills */
+        skills: '.claude/skills',
+        mcp: mcpByCli('claude'),
+        provider: (ctx, off) => claudePlan(ctx.env, { off, model: ctx.model, onPath: ctx.onPath }),
+    },
+    /** Cursor. Its models are set on its settings screen; the shell block gives it PHANTOM_API_KEY to copy. */
+    cursor: {
+        label: 'Cursor',
+        /** ~/.cursor */
+        home: '.cursor',
+        /** ~/.cursor/skills */
+        skills: '.cursor/skills',
+        /** Merges the server into ~/.cursor/mcp.json, keeping the others. */
+        mcp: (ctx, add) => {
+            const server = { command: 'npx', args: MCP_ARGS };
+            const mcp = `add to ~/.cursor/mcp.json: ${JSON.stringify({ mcpServers: { phantom: server } })}`;
+            if (!add)
+                return { mcp };
+            const file = path.join(ctx.home, '.cursor', 'mcp.json');
+            return { mcp, edits: [{ file, after: jsonEdit(file, readText(file), [[['mcpServers', 'phantom'], server]]) }] };
+        },
+        provider: manualProvider('Cursor Settings, Models', (ctx) => [
+            'Open Cursor Settings (Cmd+Shift+J on macOS), then Models.',
+            `Under OpenAI API Key, paste your Phantom AI key, then turn on Override OpenAI Base URL and set it to ${agentBaseUrl(ctx.env, 'cursor')}`,
+            'Copy the key without showing it: phantom key show | pbcopy',
+            `Use Add model to add ${ctx.model ?? SETUP_MODEL} and any other Phantom AI model ids you want in the picker.`,
+            'While the override is on, Cursor\'s own non-OpenAI models stop working; turn it off to go back. Tab completions never use your own key.',
+        ]),
+        shellEnv: () => ({}),
+    },
+    /** opencode. */
+    opencode: {
+        label: 'opencode',
+        /** ~/.config/opencode/opencode.json, or under $XDG_CONFIG_HOME */
+        home: '.config/opencode/opencode.json',
+        detect: (env, home) => existsSync(opencodeFile(env, home)),
+        provider: opencodeProvider,
+        shellEnv: () => ({}),
+    },
+    /** Continue, in the `cn` CLI and the editor. */
+    continue: {
+        label: 'Continue',
+        /** ~/.continue */
+        home: '.continue',
+        provider: continueProvider,
+        shellEnv: () => ({}),
+    },
+    /** Goose. */
+    goose: {
+        label: 'Goose',
+        /** ~/.config/goose, or under $XDG_CONFIG_HOME */
+        home: '.config/goose',
+        detect: (env, home) => existsSync(path.join(configHome(env, home), 'goose')),
+        provider: gooseProvider,
+        shellEnv: () => ({}),
+    },
+    /** Aider. */
+    aider: {
+        label: 'Aider',
+        /** ~/.aider, or ~/.aider.conf.yml */
+        home: '.aider',
+        detect: (env, home) => existsSync(path.join(home, '.aider')) || existsSync(path.join(home, '.aider.conf.yml')),
+        provider: aiderProvider,
+        shellEnv: () => ({ AIDER_OPENAI_API_KEY: '$PHANTOM_API_KEY' }),
+    },
+    /** GitHub Copilot CLI. Set up by its COPILOT_PROVIDER_ variables, which make it use a model provider of your own. */
+    copilot: {
+        label: 'GitHub Copilot CLI',
+        /** ~/.copilot, or $COPILOT_HOME */
+        home: '.copilot',
+        detect: (env, home) => existsSync(copilotDir(env, home)),
+        provider: copilotProvider,
+        shellEnv: (ctx) => ({
+            COPILOT_PROVIDER_BASE_URL: agentBaseUrl(ctx.env, 'coding-agent'),
+            COPILOT_PROVIDER_API_KEY: '$PHANTOM_API_KEY',
+            COPILOT_MODEL: ctx.model ?? SETUP_MODEL,
+        }),
+    },
+    /** Cline, in its CLI and editor extension. */
+    cline: {
+        label: 'Cline',
+        /** ~/.cline */
+        home: '.cline',
+        provider: clineProvider,
+    },
+};
+export const SETUP_NAMES = Object.keys(SETUP_AGENTS);
+/** `a, b or c`. */
+export function orList(items) {
+    return items.length < 2 ? items.join('') : `${items.slice(0, -1).join(', ')} or ${items[items.length - 1]}`;
+}

package/dist/setup/apply.mjs

@@ -0,0 +1,218 @@
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { stateDir } from "../core/state.mjs";
+import { readText } from "./shared.mjs";
+import { jsonText } from "./editors.mjs";
+import { claudePlan, SETUP_AGENTS } from "./agents.mjs";
+import { planSetup } from "./plan.mjs";
+/** Hides Phantom AI keys in text that is shown: `sk-phantom-****`. */
+export function maskKeys(text) {
+    return text.replace(/sk-phantom-[A-Za-z0-9_-]+/g, 'sk-phantom-****');
+}
+/**
+ * A line diff of two texts: unchanged lines start with two spaces, removed
+ * lines with `- ` and added lines with `+ `. Unchanged lines more than two
+ * away from a change are left out, and each gap shows as `  ...`.
+ */
+export function lineDiff(before, after) {
+    const split = (t) => (t === null || t === '' ? [] : t.replace(/\n$/, '').split('\n'));
+    const a = split(before);
+    const b = split(after);
+    const rows = [];
+    if (a.length * b.length > 4_000_000) {
+        rows.push(...a.map((l) => '- ' + l), ...b.map((l) => '+ ' + l));
+    }
+    else {
+        // Longest common subsequence, from the end, then walk it from the start.
+        const dp = Array.from({ length: a.length + 1 }, () => new Uint32Array(b.length + 1));
+        for (let i = a.length - 1; i >= 0; i--)
+            for (let j = b.length - 1; j >= 0; j--)
+                dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        let i = 0;
+        let j = 0;
+        while (i < a.length || j < b.length) {
+            if (i < a.length && j < b.length && a[i] === b[j]) {
+                rows.push('  ' + a[i++]);
+                j++;
+            }
+            else if (i < a.length && (j === b.length || dp[i + 1][j] >= dp[i][j + 1]))
+                rows.push('- ' + a[i++]);
+            else
+                rows.push('+ ' + b[j++]);
+        }
+    }
+    const changed = rows.map((r) => !r.startsWith('  '));
+    const out = [];
+    for (let k = 0; k < rows.length; k++) {
+        if (changed.slice(Math.max(0, k - 2), k + 3).some(Boolean))
+            out.push(rows[k]);
+        else if (out[out.length - 1] !== '  ...')
+            out.push('  ...');
+    }
+    return out.join('\n');
+}
+/** A plan as people read it: each file with its diff (keys masked), the skill in one line, then commands, skips and steps to do by hand. */
+export function setupPreview(plan) {
+    const parts = [];
+    for (const f of plan.files) {
+        if (f.skill)
+            parts.push(`${f.action === 'create' ? 'install' : 'update'} skill ${f.file}`);
+        else if (f.action === 'remove')
+            parts.push(`remove ${f.file}`);
+        else
+            parts.push(`${f.action} ${f.file}\n${maskKeys(lineDiff(f.before, f.after))}`);
+    }
+    for (const r of plan.runs)
+        parts.push(`run ${r.cmd} ${r.args.join(' ')}`);
+    for (const s of plan.skipped)
+        parts.push(`skip ${s.agent}: ${s.reason}`);
+    for (const a of plan.agents) {
+        const steps = a.provider?.manual ?? [];
+        if (steps.length)
+            parts.push([`${SETUP_AGENTS[a.agent].label}, by hand:`, ...steps.map((s, k) => `  ${k + 1}. ${s}`)].join('\n'));
+    }
+    for (const n of plan.notes)
+        parts.push(n);
+    return parts.length ? parts.join('\n\n') : 'Nothing to change.';
+}
+function backupsFile(env) {
+    return path.join(stateDir(env), 'setup-backups.json');
+}
+function readBackups(env) {
+    try {
+        return JSON.parse(readFileSync(backupsFile(env), 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeBackups(env, entries) {
+    mkdirSync(stateDir(env), { recursive: true, mode: 0o700 });
+    writeFileSync(backupsFile(env), jsonText(entries), { mode: 0o600 });
+}
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+/**
+ * Writes a plan from {@link planSetup}. Before it edits a file it copies it
+ * to `<file>.phantom.bak`, unless the file is still as phantom last wrote it: then the
+ * copy from before phantom's first change stays. A file that changed after the
+ * plan read it is left alone and listed in `skipped`. Then it runs any MCP
+ * commands.
+ * @param exec Runs an agent's CLI, such as `claude mcp add`.
+ */
+export function applySetup(env, plan, exec = (cmd, args) => execFileSync(cmd, args, { stdio: 'ignore' })) {
+    const backups = readBackups(env);
+    const skipped = [...plan.skipped];
+    const files = [];
+    for (const f of plan.files) {
+        if (readText(f.file) !== f.before) {
+            skipped.push({ agent: f.agent, reason: `${f.file} changed after setup read it; run phantom setup again` });
+            continue;
+        }
+        let backup;
+        if (!f.skill) {
+            const prior = backups[f.file];
+            const keep = Boolean(prior && f.before !== null && prior.sha === sha256(f.before) && (prior.backup === null || existsSync(prior.backup)));
+            let from = keep ? prior.backup : null;
+            if (!keep && f.before !== null) {
+                from = `${f.file}.phantom.bak`;
+                writeFileSync(from, f.before, { mode: 0o600 });
+            }
+            if (from)
+                backup = from;
+            if (f.after === null && from === null)
+                delete backups[f.file];
+            else
+                backups[f.file] = { agent: f.agent, backup: from, sha: sha256(f.after ?? '') };
+        }
+        if (f.after === null)
+            rmSync(f.file, { force: true });
+        else {
+            mkdirSync(path.dirname(f.file), { recursive: true });
+            writeFileSync(f.file, f.after, f.mode ? { mode: f.mode } : {});
+            if (f.mode)
+                chmodSync(f.file, f.mode);
+        }
+        files.push({ agent: f.agent, file: f.file, action: f.action, ...(backup ? { backup } : {}), ...(f.skill ? {} : { diff: maskKeys(lineDiff(f.before, f.after)) }) });
+    }
+    if (plan.files.some((f) => !f.skill))
+        writeBackups(env, backups);
+    for (const r of plan.runs)
+        exec(r.cmd, r.args);
+    const agents = plan.agents.map((a) => ({ ...a, mcp_added: plan.mcp.includes(a.agent) }));
+    return { agents, files, ...(skipped.length ? { skipped } : {}), ...(plan.notes.length ? { notes: plan.notes } : {}) };
+}
+/**
+ * Points Claude Code at Phantom AI, or removes phantom's settings with `off`.
+ * Uses the same backups and restore safeguards as {@link applySetup}.
+ * The return value remains the provider result for existing callers.
+ * @deprecated Use {@link setupAgents} or {@link planSetup} and {@link applySetup}. This helper remains for settings-only callers.
+ */
+export function claudeProvider(env, opts = {}) {
+    const provider = claudePlan(env, opts);
+    const files = provider.edits.map((edit) => {
+        const before = readText(edit.file);
+        return { ...edit, before, agent: 'claude', action: before === null ? 'create' : edit.after === null ? 'remove' : 'update' };
+    });
+    applySetup(env, { agents: [], files, runs: [], mcp: [], skipped: [], notes: [] });
+    return provider.result;
+}
+/** A plan as `--dry-run` reports it: each file that would change, with its diff, and nothing written. */
+export function previewSetup(plan) {
+    return {
+        agents: plan.agents,
+        files: plan.files.map((f) => ({ agent: f.agent, file: f.file, action: f.action, ...(f.skill ? {} : { diff: maskKeys(lineDiff(f.before, f.after)) }) })),
+        ...(plan.skipped.length ? { skipped: plan.skipped } : {}),
+        ...(plan.notes.length ? { notes: plan.notes } : {}),
+        dry_run: true,
+    };
+}
+/**
+ * Installs the phantom-ai skill for one agent, or for every agent found
+ * (see {@link SETUP_AGENTS}), and with `mcp` and `provider` sets those up
+ * too, without asking: {@link planSetup}, then {@link applySetup}.
+ * @throws {@link CliError} when no agent is found, the agent is unknown, or `provider` is set without an agent that supports it.
+ */
+export function setupAgents(env, opts = {}) {
+    return applySetup(env, planSetup(env, opts), opts.exec);
+}
+/**
+ * Puts back the files `phantom setup` changed, from the copies it kept
+ * (`<file>.phantom.bak`), and removes the files it created. Only a file still as
+ * phantom wrote it: one changed since (Codex adds `[projects]` tables to its
+ * config, for example) is left alone and listed, since the copy would undo
+ * that change too. `--provider off` removes phantom's lines from such a file.
+ * @param opts `agent` limits it to one agent's files (`shell` for the startup file).
+ */
+export function restoreSetup(env, opts = {}) {
+    const backups = readBackups(env);
+    const restored = [];
+    const skipped = [];
+    for (const [file, entry] of Object.entries(backups)) {
+        if (opts.agent && opts.agent !== 'all' && entry.agent !== opts.agent)
+            continue;
+        const now = readText(file);
+        if (sha256(now ?? '') !== entry.sha) {
+            skipped.push({ file, reason: `changed since phantom wrote it${entry.backup ? `; the copy from before is ${entry.backup}` : ''}. phantom setup --provider off removes only phantom's lines` });
+            continue;
+        }
+        if (entry.backup !== null && !existsSync(entry.backup)) {
+            skipped.push({ file, reason: `its copy ${entry.backup} is gone` });
+            continue;
+        }
+        if (!opts.dryRun) {
+            if (entry.backup === null)
+                rmSync(file, { force: true });
+            else {
+                writeFileSync(file, readFileSync(entry.backup));
+                rmSync(entry.backup);
+            }
+            delete backups[file];
+        }
+        restored.push({ file, from: entry.backup });
+    }
+    if (!opts.dryRun && restored.length)
+        writeBackups(env, backups);
+    return { restored, skipped, ...(opts.dryRun ? { dry_run: true } : {}) };
+}