@phantomcodes/cli 0.0.0-stage → 1.0.0

package/dist/setup/plan.mjs

@@ -0,0 +1,142 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import os from 'node:os';
+import { existsSync, readFileSync } from 'node:fs';
+import { CliError, die } from "../core/errors.mjs";
+import { resolveApiKey } from "../keys/saved.mjs";
+import { readText } from "./shared.mjs";
+import { shellRcFile, withShellBlock } from "./editors.mjs";
+import { SETUP_AGENTS, SETUP_NAMES, orList } from "./agents.mjs";
+function skillSource() {
+    // The skill is in the package's skills/ folder, two up from this file in
+    // both src/setup/ and dist/setup/.
+    const p = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'skills', 'phantom-ai', 'SKILL.md');
+    if (existsSync(p))
+        return p;
+    die('The phantom-ai skill is missing from this install');
+}
+const isSkip = (err) => err instanceof CliError && err.code === 'setup_unreadable';
+/**
+ * Works out what setup would change, and writes nothing: the skill for each
+ * agent ({@link SETUP_AGENTS}), the MCP server with `mcp`, each agent's model
+ * settings with `provider` ({@link SetupAgentSpec.provider}), and the shell
+ * block ({@link shellBlock}) for agents that read the key from the
+ * environment. A config file setup can't edit safely is left out and listed
+ * in `skipped`.
+ * @throws {@link CliError} when no agent is found, the agent is unknown, the model is not a plain id, `provider` is set without an agent that supports it, or there is no key for `provider`.
+ */
+export function planSetup(env, opts = {}) {
+    const home = env.HOME || os.homedir();
+    const names = SETUP_NAMES;
+    let picked;
+    if (!opts.agent || opts.agent === 'all') {
+        picked = names.filter((a) => SETUP_AGENTS[a].detect?.(env, home) ?? existsSync(path.join(home, SETUP_AGENTS[a].home)));
+        if (picked.length === 0)
+            die(`Found no agent to set up. Pass --agent ${names.join('|')}`);
+    }
+    else if (names.includes(opts.agent)) {
+        picked = [opts.agent];
+    }
+    else {
+        die(`Unknown agent: ${opts.agent}. Use ${names.join(', ')} or all`);
+    }
+    // The model goes into shell and config files, so it must be a plain id.
+    if (opts.model !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._:/@[\]-]*$/.test(opts.model))
+        die(`Not a model id: ${opts.model}`, 'model_invalid');
+    const notes = [];
+    let provider = opts.provider ?? false;
+    if (provider && !picked.some((a) => SETUP_AGENTS[a].provider)) {
+        if (opts.guided)
+            provider = false;
+        else {
+            const able = names.filter((a) => SETUP_AGENTS[a].provider);
+            die(`--provider sets up ${orList(able.map((a) => SETUP_AGENTS[a].label))}; add --agent ${orList(able)}`, 'provider_agent');
+        }
+    }
+    if (provider === true && !resolveApiKey(env)) {
+        if (!opts.guided)
+            die('No API key to give the agents. Run: phantom login', 'no_key');
+        notes.push('No Phantom AI key yet, so only the skills are installed. Run phantom login, then phantom setup again.');
+        provider = false;
+    }
+    const ctx = { env, home, onPath: opts.onPath, model: opts.model, shellRc: shellRcFile(env, home) };
+    const files = [];
+    const runs = [];
+    const mcpAdds = [];
+    const skipped = [];
+    const agents = [];
+    const add = (agent, file, after, skill = false, mode) => {
+        const known = files.find((f) => f.file === file);
+        if (known) {
+            known.after = after;
+            if (mode)
+                known.mode = mode;
+            known.action = known.before === null ? 'create' : after === null ? 'remove' : 'update';
+            return;
+        }
+        const before = readText(file);
+        if (before === after)
+            return;
+        files.push({ agent, file, action: before === null ? 'create' : after === null ? 'remove' : 'update', before, after, ...(skill ? { skill } : {}), ...(mode ? { mode } : {}) });
+    };
+    const skillText = readFileSync(skillSource(), 'utf-8');
+    const shellOn = new Map();
+    const shellOff = [];
+    for (const agent of picked) {
+        const spec = SETUP_AGENTS[agent];
+        const skill = spec.skills ? path.join(home, spec.skills, 'phantom-ai', 'SKILL.md') : null;
+        if (skill)
+            add(agent, skill, skillText, true);
+        let mcp = null;
+        if (spec.mcp) {
+            try {
+                const m = spec.mcp(ctx, Boolean(opts.mcp));
+                mcp = m.mcp;
+                if (opts.mcp) {
+                    if (m.run)
+                        runs.push({ agent, cmd: m.run[0], args: m.run[1] });
+                    for (const e of m.edits ?? [])
+                        add(agent, e.file, e.after);
+                    mcpAdds.push(agent);
+                }
+            }
+            catch (err) {
+                if (!isSkip(err))
+                    throw err;
+                skipped.push({ agent, reason: err.message });
+            }
+        }
+        let result;
+        if (provider && spec.provider) {
+            try {
+                const p = spec.provider(ctx, provider === 'off');
+                for (const e of p.edits)
+                    add(agent, e.file, e.after, false, e.mode);
+                result = p.result;
+                if (spec.shellEnv) {
+                    if (provider === 'off')
+                        shellOff.push(agent);
+                    else
+                        shellOn.set(agent, spec.shellEnv(ctx));
+                }
+            }
+            catch (err) {
+                if (!isSkip(err))
+                    throw err;
+                skipped.push({ agent, reason: err.message });
+            }
+        }
+        agents.push({ agent, skill, mcp, mcp_added: false, ...(result ? { provider: result } : {}) });
+    }
+    if (shellOn.size || shellOff.length) {
+        try {
+            add('shell', ctx.shellRc, withShellBlock(env, ctx.shellRc, readText(ctx.shellRc), shellOn, shellOff, opts.onPath));
+        }
+        catch (err) {
+            if (!isSkip(err))
+                throw err;
+            skipped.push({ agent: 'shell', reason: err.message });
+        }
+    }
+    return { agents, files, runs, mcp: mcpAdds, skipped, notes };
+}

package/dist/setup/shared.mjs

@@ -0,0 +1,89 @@
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { die } from "../core/errors.mjs";
+import { DEFAULT_BASE_URL, httpsOnly } from "../core/request.mjs";
+/** True when `bin` is a program on PATH. */
+export function onPath(bin) {
+    return spawnSync(process.platform === 'win32' ? 'where' : 'which', [bin], { stdio: 'ignore' }).status === 0;
+}
+/** The model setup starts each agent on when `--model` is not given. */
+export const SETUP_MODEL = 'phantom-1';
+/**
+ * The address Phantom AI serves a coding agent at, from PHANTOM_BASE_URL
+ * without its `/v1`: `/claude-code` (Claude Code adds `/v1` itself), or
+ * `/codex/v1`, `/cursor/v1` and `/coding-agent/v1` for the others.
+ * @throws {@link CliError} when PHANTOM_BASE_URL is not https ({@link httpsOnly}).
+ */
+export function agentBaseUrl(env, agent) {
+    const origin = httpsOnly(env.PHANTOM_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, '').replace(/\/v1$/, '');
+    return agent === 'claude-code' ? `${origin}/claude-code` : `${origin}/${agent}/v1`;
+}
+export const MCP_ARGS = ['-y', '@phantomcodes/cli', 'mcp'];
+/** MCP for an agent whose CLI adds servers: `<agent> mcp add phantom -- npx ...`. */
+export function mcpByCli(agent) {
+    return () => ({
+        mcp: `${agent} mcp add phantom -- npx ${MCP_ARGS.join(' ')}`,
+        run: [agent, ['mcp', 'add', 'phantom', '--', 'npx', ...MCP_ARGS]],
+    });
+}
+/** The end of every line phantom adds to a TOML, YAML or shell file. */
+export const SETUP_MARK = '# phantom setup';
+/** The start of a line phantom turned into a comment because it replaced it. `--provider off` puts it back. */
+export const SETUP_WAS = '# phantom setup was: ';
+/** The marks this CLI wrote under its old name, pai. Setup still finds and removes them. */
+const LEGACY_MARK = '# pai setup';
+const LEGACY_WAS = '# pai setup was: ';
+/** True for a line setup added: it ends with {@link SETUP_MARK}, or the mark pai wrote. */
+export function setupMarked(line) {
+    const t = line.trimEnd();
+    return t.endsWith(SETUP_MARK) || t.endsWith(LEGACY_MARK);
+}
+/** The line without the setup mark on its end. */
+export function stripMark(line) {
+    const t = line.trimEnd();
+    const mark = t.endsWith(SETUP_MARK) ? SETUP_MARK : t.endsWith(LEGACY_MARK) ? LEGACY_MARK : '';
+    return t.slice(0, t.length - mark.length).trimEnd();
+}
+/** A line setup turned into a comment, put back as it was. Other lines come back unchanged. */
+export function unwas(line) {
+    for (const was of [SETUP_WAS, LEGACY_WAS])
+        if (line.startsWith(was))
+            return line.slice(was.length);
+    return line;
+}
+/** A file's text, or null when it does not exist. Other read errors pass through. */
+export function readText(file) {
+    try {
+        return readFileSync(file, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+/** Refuses a file setup can't edit safely. Setup skips the agent and says why. */
+export function unreadable(file, why) {
+    die(`${file} ${why}; fix it first so setup doesn't overwrite it`, 'setup_unreadable');
+}
+/** How to run this phantom from outside this shell: `phantom` if it's installed, else this node and script by absolute path. */
+export function phantomCommand(onPathFn) {
+    return onPathFn('phantom')
+        ? 'phantom'
+        : `${onPathFn('node') ? 'node' : JSON.stringify(process.execPath)} ${JSON.stringify(path.resolve(process.argv[1] ?? 'phantom'))}`;
+}
+/** `$XDG_CONFIG_HOME` when it is an absolute path, else `~/.config`. */
+export function configHome(env, home) {
+    return env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(home, '.config');
+}
+/** A writer's `off` result for a file it edits by removing its own lines or entries. */
+export function offResult(label, file, text, after) {
+    const changed = text !== null && after !== text;
+    return {
+        edits: changed ? [{ file, after: after || null }] : [],
+        result: { settings: file, on: false, warnings: changed ? [] : [`${label} was not set to Phantom AI by phantom; nothing changed`] },
+    };
+}
+/** The context window Phantom AI's catalog gives phantom-1. Goose and Aider size requests by it. */
+export const SETUP_CONTEXT_WINDOW = 1_000_000;

package/dist/spend/command.mjs

@@ -0,0 +1,105 @@
+import { readFileSync } from 'node:fs';
+import { die } from "../core/errors.mjs";
+import { flagNum, out } from "../core/helpers.mjs";
+import { getRoute, putRoute, patchRoute, clearRoute, testRoute, parseCondition } from "./routing.mjs";
+/** `--table` output for `route`. */
+export function tableRoute(d) {
+    const p = d.route_policy;
+    if (!p)
+        return 'route           none (model "auto" is refused)';
+    const rules = p.rules ?? [];
+    return [
+        `models          ${p.models.join(', ')}`,
+        `applies_to      ${p.applies_to ?? 'auto'}`,
+        `on_empty        ${p.on_empty ?? 'stop'}`,
+        `fallback        ${p.fallback_on_error ?? false}`,
+        `sticky          ${p.stick_minutes ?? 5} min${(p.stick_by_prompt ?? true) ? '' : ' (x-phantom-session only)'}`,
+        ...(rules.length ? rules.map((r, i) => `rule ${String(i + 1).padEnd(11)}if ${Object.entries(r.if).map(([k, v]) => `${k}=${v}`).join(' ')} use ${r.use}`) : ['rules           none (auto runs the first model)']),
+    ].join('\n');
+}
+/** `--table` output for `route test`. */
+export function tableRouteTest(d) {
+    const t = d;
+    return [`model           ${t.model}`, `reason          ${t.reason}`].join('\n');
+}
+/** `phantom route`: the key's route policy, its rules, and a dry run. Run by `run()`. */
+export async function routeCommand({ argv, io, apiKey, subcommand, flags, table, baseUrl }) {
+    if (!subcommand || subcommand === 'get') {
+        out(await getRoute(apiKey, baseUrl), table, tableRoute, io.stdout);
+    }
+    else if (subcommand === 'set') {
+        const file = flags['file'];
+        if (typeof file === 'string') {
+            let policy;
+            try {
+                policy = JSON.parse(readFileSync(file, 'utf-8'));
+            }
+            catch (e) {
+                die(`Could not read ${file} as JSON: ${e instanceof Error ? e.message : e}`);
+            }
+            out(await putRoute(apiKey, policy, baseUrl), table, tableRoute, io.stdout);
+        }
+        else {
+            const fields = {};
+            if (typeof flags['models'] === 'string')
+                fields.models = flags['models'].split(',').map((m) => m.trim()).filter(Boolean);
+            if (typeof flags['applies-to'] === 'string')
+                fields.applies_to = flags['applies-to'];
+            if (typeof flags['on-empty'] === 'string')
+                fields.on_empty = flags['on-empty'];
+            if (flags['fallback'] !== undefined)
+                fields.fallback_on_error = flags['fallback'] !== 'false';
+            const stick = flagNum(flags, 'stick-minutes');
+            if (stick !== undefined)
+                fields.stick_minutes = stick;
+            if (flags['stick-by-prompt'] !== undefined)
+                fields.stick_by_prompt = flags['stick-by-prompt'] !== 'false';
+            if (Object.keys(fields).length === 0) {
+                die('route set needs --models a,b,c, --applies-to, --on-empty, --fallback, --stick-minutes, --stick-by-prompt, or --file policy.json');
+            }
+            const current = (await getRoute(apiKey, baseUrl)).route_policy;
+            const result = current ? await patchRoute(apiKey, fields, baseUrl) : await putRoute(apiKey, fields, baseUrl);
+            out(result, table, tableRoute, io.stdout);
+        }
+    }
+    else if (subcommand === 'rule') {
+        const action = argv[2];
+        const current = (await getRoute(apiKey, baseUrl)).route_policy;
+        if (!current)
+            die('This key has no route policy. Start with: phantom route set --models a,b');
+        const rules = [...(current.rules ?? [])];
+        if (action === 'add') {
+            const cond = flags['if'];
+            const use = flags['use'];
+            if (typeof cond !== 'string' || typeof use !== 'string')
+                die('route rule add requires --if name=value and --use <model|cheapest|first|next>');
+            const rule = { if: parseCondition(cond), use };
+            const at = flagNum(flags, 'at');
+            if (at !== undefined)
+                rules.splice(Math.max(0, at - 1), 0, rule);
+            else
+                rules.push(rule);
+        }
+        else if (action === 'rm') {
+            const n = Number(argv[3]);
+            if (!Number.isInteger(n) || n < 1 || n > rules.length)
+                die(`route rule rm takes a rule number from 1 to ${rules.length}`);
+            rules.splice(n - 1, 1);
+        }
+        else {
+            die('Use: route rule add --if name=value --use <model> [--at n], or route rule rm <n>');
+        }
+        out(await patchRoute(apiKey, { rules }, baseUrl), table, tableRoute, io.stdout);
+    }
+    else if (subcommand === 'test') {
+        const model = typeof flags['model'] === 'string' ? flags['model'] : 'auto';
+        out(await testRoute(apiKey, { model }, baseUrl), table, tableRouteTest, io.stdout);
+    }
+    else if (subcommand === 'clear') {
+        out(await clearRoute(apiKey, baseUrl), table, tableRoute, io.stdout);
+    }
+    else {
+        die(`Unknown route subcommand: ${subcommand}`);
+    }
+    return 0;
+}

package/dist/spend/routing.mjs

@@ -0,0 +1,32 @@
+import { die } from "../core/errors.mjs";
+import { request } from "../core/request.mjs";
+/** The key's route policy (GET /key/route). */
+export function getRoute(apiKey, baseUrl) {
+    return request('GET', '/key/route', apiKey, undefined, baseUrl);
+}
+/** Replaces the key's route policy (PUT /key/route). The server checks it before saving. */
+export function putRoute(apiKey, policy, baseUrl) {
+    return request('PUT', '/key/route', apiKey, policy, baseUrl);
+}
+/** Changes some top-level fields of the route policy and keeps the rest (PATCH /key/route). A list sent here replaces the whole list. */
+export function patchRoute(apiKey, fields, baseUrl) {
+    return request('PATCH', '/key/route', apiKey, fields, baseUrl);
+}
+/** Removes the key's route policy (DELETE /key/route). */
+export function clearRoute(apiKey, baseUrl) {
+    return request('DELETE', '/key/route', apiKey, undefined, baseUrl);
+}
+/** Which model a request would run on now, and why (POST /key/route/test). Nothing is charged and no model is called. */
+export function testRoute(apiKey, opts, baseUrl) {
+    return request('POST', '/key/route/test', apiKey, opts, baseUrl);
+}
+/** `pace=ahead` or `input_tokens_over=50000` into one rule condition. */
+export function parseCondition(raw) {
+    const eq = raw.indexOf('=');
+    if (eq < 1)
+        die(`Write a condition as name=value, for example pace=ahead`);
+    const name = raw.slice(0, eq);
+    const text = raw.slice(eq + 1);
+    const value = text === 'true' ? true : text === 'false' ? false : text !== '' && Number.isFinite(Number(text)) ? Number(text) : text;
+    return { [name]: value };
+}

package/dist/workspace/command.mjs

@@ -0,0 +1,204 @@
+import { createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+import path from 'node:path';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { DEFAULT_BASE_URL, httpsOnly, apiError } from "../core/request.mjs";
+import { stateDir } from "../core/state.mjs";
+import { writeSecret, readSecret, removeSecret, keychainOn } from "../core/secrets.mjs";
+import { keyCommand } from "../keys/command.mjs";
+import { die } from "../core/errors.mjs";
+import { openUrl } from "../core/helpers.mjs";
+import { keyPath, namedKeyPath, saveApiKey, saveNamedKey } from "../keys/saved.mjs";
+const credentialPath = (env) => path.join(stateDir(env), 'workspace');
+const base = (input) => httpsOnly(input.baseUrl || input.env.PHANTOM_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, '');
+async function wire(url, method, endpoint, body, token) {
+    const response = await fetch(url + endpoint, { method, redirect: 'error', headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) }, body: body === undefined ? undefined : JSON.stringify(body) });
+    const data = await response.json();
+    if (!response.ok)
+        throw apiError(response.status, data);
+    return data;
+}
+function credentials(input) {
+    const file = credentialPath(input.env);
+    if (!existsSync(file))
+        die('No workspace connection. Run phantom login.', 'workspace_missing');
+    const saved = JSON.parse(readSecret(input.env, file));
+    if (saved.base_url !== base(input))
+        die('This workspace belongs to a different API address. Run phantom login for this address.', 'workspace_origin');
+    return saved;
+}
+/** Device authorization for accounts or guests, saving keys locally without copying a secret through the browser. */
+export async function workspaceLogin(input) {
+    const { env, io, flags } = input;
+    if (flags.save === true)
+        die('--save requires a key name.');
+    const name = typeof flags.save === 'string' ? flags.save : 'default';
+    const target = name === 'default' ? keyPath(env) : namedKeyPath(env, name);
+    if (existsSync(target))
+        die(`Saved key ${name} already exists. Use --save <new-name>; no key was overwritten.`, 'key_exists');
+    const url = base(input);
+    const start = await wire(url, 'POST', '/auth/device', { client_name: `phantom on ${hostname()}` });
+    if (new URL(start.verification_uri_complete).origin !== new URL(url).origin)
+        die('The approval URL belongs to another site.', 'device_origin');
+    io.stderr(`Open ${start.verification_uri_complete}\nConfirm code ${start.user_code}\n`);
+    if (!flags['no-browser'])
+        openUrl(start.verification_uri_complete);
+    let interval = Math.max(1, start.interval) * 1000;
+    const deadline = Date.now() + Math.min(600, start.expires_in) * 1000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, interval));
+        let token;
+        try {
+            token = await wire(url, 'POST', '/auth/device/token', { device_code: start.device_code });
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'authorization_pending')
+                continue;
+            if (code === 'slow_down') {
+                interval += 5000;
+                continue;
+            }
+            throw error;
+        }
+        const saved = { version: 1, workspace_id: token.workspace_id, management_credential: token.management_token, base_url: url, recovery: token.recovery };
+        try {
+            writeSecret(env, credentialPath(env), JSON.stringify(saved));
+            if (name === 'default')
+                saveApiKey(env, token.api_key);
+            else
+                saveNamedKey(env, name, token.api_key);
+        }
+        catch (error) {
+            io.stderr('phantom could not save the connection. Sign in or restore your workspace to revoke the device key and reconnect.\n');
+            throw error;
+        }
+        io.stdout(JSON.stringify({ saved_as: name, key_name: token.key_name, workspace_id: token.workspace_id, storage: keychainOn(env) ? 'macOS Keychain' : 'private files' }) + '\n');
+        io.stderr('Ready. Run phantom claude, phantom codex or phantom pi. Guests can export recovery with phantom workspace export --file <path>.\n');
+        return 0;
+    }
+    die('Device code expired. Run phantom login again.', 'login_expired');
+}
+/** Manage a workspace from the terminal: balance, keys, funding, recovery and revocation. */
+export async function workspaceCommand(input) {
+    const { subcommand, flags, io, env, argv } = input;
+    if (argv[0] === 'keys') {
+        if (subcommand === 'saved' || subcommand === 'save' || subcommand === 'show' || subcommand === 'rm') {
+            return keyCommand({ ...input, flags: { ...(flags.balance ? { balance: flags.balance } : {}) }, subcommand: subcommand === 'saved' ? 'list' : subcommand });
+        }
+        const remoteCommands = new Set(['list', 'create', 'rotate', 'revoke', 'set', undefined]);
+        if (!remoteCommands.has(subcommand)) {
+            return keyCommand({ ...input, subcommand });
+        }
+    }
+    const command = subcommand ?? 'status';
+    if (command === 'import' && argv[0] === 'workspace') {
+        if (typeof flags.file !== 'string')
+            die('Use phantom workspace import --file <recovery-file>.');
+        const recovery = JSON.parse(readFileSync(flags.file, 'utf8'));
+        if (!recovery || recovery.version !== 1)
+            die('Invalid recovery file.');
+        await wire(base(input), 'GET', '/workspaces/' + encodeURIComponent(recovery.workspace_id), undefined, recovery.management_credential);
+        writeSecret(env, credentialPath(env), JSON.stringify({ ...recovery, base_url: base(input), recovery }));
+        io.stdout('Workspace restored. Use phantom keys create to save a new API key.\n');
+        return 0;
+    }
+    const saved = credentials(input);
+    const endpoint = '/workspaces/' + encodeURIComponent(saved.workspace_id);
+    if (command === 'export') {
+        if (!saved.recovery)
+            die('This is an account workspace. Sign in to recover it on another computer.');
+        if (typeof flags.file !== 'string')
+            die('Use phantom workspace export --file <path>.');
+        writeFileSync(flags.file, JSON.stringify(saved.recovery, null, 2), { mode: 0o600, flag: 'wx' });
+        io.stdout('Recovery exported. Keep that file private; it grants workspace management.\n');
+        return 0;
+    }
+    if (command === 'create' || command === 'rotate') {
+        if (command === 'rotate' && typeof flags.id !== 'string')
+            die('Use --id <key-id> from phantom keys list.');
+        const name = typeof flags.save === 'string' ? flags.save : 'default';
+        if (flags.save === true)
+            die('--save requires a key name.');
+        const target = name === 'default' ? keyPath(env) : namedKeyPath(env, name);
+        const replacing = existsSync(target);
+        if (replacing && (command !== 'rotate' || createHash('sha256').update(readSecret(env, target).trim()).digest('hex') !== flags.id))
+            die('That saved key already exists. Use --save <new-name>.', 'key_exists');
+        const result = await wire(saved.base_url, 'POST', command === 'create' ? endpoint + '/keys' : endpoint + '/keys/' + String(flags.id), command === 'create' ? { name, limit_usd: flags.limit === undefined ? null : Number(flags.limit) } : { action: 'rotate' }, saved.management_credential);
+        if (name === 'default')
+            saveApiKey(env, result.api_key);
+        else
+            saveNamedKey(env, name, result.api_key, { replace: replacing });
+        io.stdout(JSON.stringify({ saved_as: name }) + '\n');
+        return 0;
+    }
+    if (command === 'revoke') {
+        if (typeof flags.id !== 'string')
+            die('Use phantom keys revoke --id <key-id>.');
+        await wire(saved.base_url, 'DELETE', endpoint + '/keys/' + flags.id, undefined, saved.management_credential);
+        io.stdout('Key revoked.\n');
+        return 0;
+    }
+    if (command === 'set') {
+        if (typeof flags.id !== 'string')
+            die('Use phantom keys set --id <key-id>.');
+        const body = {};
+        const controls = { limit_usd: flags.limit, budget_usd: flags.budget, period_days: flags.period, rate_usd_per_min: flags.rate };
+        for (const [field, value] of Object.entries(controls))
+            if (value !== undefined)
+                body[field] = value === 'none' ? null : Number(value);
+        if (typeof flags.name === 'string')
+            body.name = flags.name;
+        if (typeof flags['policy-file'] === 'string')
+            body.route_policy = JSON.parse(readFileSync(flags['policy-file'], 'utf8'));
+        if (flags['clear-policy'])
+            body.route_policy = null;
+        const result = await wire(saved.base_url, 'PATCH', endpoint + '/keys/' + flags.id, body, saved.management_credential);
+        io.stdout(JSON.stringify(result) + '\n');
+        return 0;
+    }
+    if (command === 'revoke-access') {
+        if (typeof flags.id !== 'string')
+            die('Use --id <management-id> from phantom workspace status.');
+        await wire(saved.base_url, 'DELETE', endpoint + '/access/' + flags.id, undefined, saved.management_credential);
+        io.stdout('Management access revoked.\n');
+        return 0;
+    }
+    if (command === 'payment') {
+        if (typeof flags.id !== 'string')
+            die('Use --id <payment-id> from phantom workspace fund.');
+        io.stdout(JSON.stringify(await wire(saved.base_url, 'GET', endpoint + '/payments/' + flags.id, undefined, saved.management_credential)) + '\n');
+        return 0;
+    }
+    if (command === 'fund') {
+        if (flags.pay)
+            die('--pay has been removed. Use --card or --coin.');
+        if (!flags.card && !flags.coin)
+            die('fund requires --card or --coin.');
+        const result = await wire(saved.base_url, 'POST', endpoint + '/fund', { method: flags.card ? 'card' : 'crypto', amount_usd: Number(flags.amount), coin: flags.coin ?? 'usdc' }, saved.management_credential);
+        io.stdout(JSON.stringify(result) + '\n');
+        if (result.checkout_url && !flags['no-browser'])
+            openUrl(result.checkout_url);
+        return 0;
+    }
+    const view = await wire(saved.base_url, 'GET', endpoint, undefined, saved.management_credential);
+    io.stdout(JSON.stringify(argv[0] === 'keys' ? view.keys : view, null, 2) + '\n');
+    return 0;
+}
+/** Forget local management credentials and revoke server management access, leaving server-side keys and recovery files valid. */
+export async function forgetWorkspace(env, baseUrl) {
+    const file = credentialPath(env);
+    if (existsSync(file)) {
+        try {
+            const saved = JSON.parse(readSecret(env, file));
+            if (saved?.workspace_id && saved?.management_credential) {
+                const url = httpsOnly(baseUrl || env.PHANTOM_BASE_URL || saved.base_url || DEFAULT_BASE_URL).replace(/\/$/, '');
+                await wire(url, 'POST', '/workspaces/' + encodeURIComponent(saved.workspace_id) + '/logout', {}, saved.management_credential).catch(() => { });
+            }
+        }
+        catch {
+            // Ignore read or parse errors during forget
+        }
+        removeSecret(file);
+    }
+}

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "@phantomcodes/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "AI inference for your coding agents. Route models, control spending, and fund your workspace.",
+  "keywords": [
+    "phantom",
+    "api-key",
+    "agent",
+    "llm",
+    "inference",
+    "cli",
+    "mcp",
+    "pi-package",
+    "agent-skill",
+    "claude-code",
+    "codex",
+    "cursor",
+    "model-context-protocol",
+    "ai-agents",
+    "solana",
+    "wallet",
+    "subagents"
+  ],
+  "homepage": "https://phantom.codes/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/connortessaro/phantom.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "phantom": "bin/phantom.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1",
+    "smol-toml": "^1.9.0",
+    "zod": "^4.5.4"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "coverage": "vitest run --coverage",
+    "dev": "node src/phantom.mts",
+    "docs": "node scripts/gen-docs.mjs",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p . --noEmit",
+    "version": "node scripts/sync-version.mjs && git add src/core/version.mts"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "bugs": {
+    "url": "https://github.com/connortessaro/phantom/issues"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Connor Tessaro",
+  "devDependencies": {
+    "@types/node": "^24.19.1",
+    "@vitest/coverage-v8": "^5.0.3",
+    "typedoc": "^0.28.20",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/phantom.d.mts",
+      "import": "./dist/phantom.mjs"
+    }
+  }
+}