@phantomcodes/cli 0.0.0-stage → 1.1.0

package/dist/setup/plan.mjs

@@ -0,0 +1,121 @@
+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}), 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 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 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, ...(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, skipped, notes };
+}

package/dist/setup/shared.mjs

@@ -0,0 +1,81 @@
+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`;
+}
+/** 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,172 @@
+import { readFileSync } from 'node:fs';
+import { die } from "../core/errors.mjs";
+import { flagNum, out } from "../core/helpers.mjs";
+import { getLineup, putLineup, resetLineup, LINEUP_TIERS } from "./lineup.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;
+}
+/** `--table` output for `lineup`. */
+export function tableLineup(d) {
+    const { lineup, tiers, choices } = d;
+    return LINEUP_TIERS.flatMap((tier) => {
+        const pick = lineup?.[tier];
+        const fallback = lineup?.fallbacks?.[tier];
+        return [
+            `${tier.padEnd(15)} ${tiers[tier].model}  ${pick ? '(your pick)' : '(default)'}`,
+            ...(fallback ? [`${''.padEnd(15)} falls back to ${fallback}`] : []),
+            ...(choices ? choices[tier].map((c) => `${''.padEnd(15)} - ${c.model}${c.default ? ' (default)' : ''}`) : []),
+        ];
+    }).join('\n');
+}
+/**
+ * Changes one tier's entry in `into` from a flag value: a model id sets it,
+ * and `default` clears it so the tier runs its default again.
+ */
+function applyPick(into, tier, flag, value) {
+    if (value === undefined)
+        return;
+    if (value === true || !value)
+        die(`--${flag} needs a model id, or "default" to clear it`);
+    if (value === 'default')
+        delete into[tier];
+    else
+        into[tier] = value;
+}
+/** `phantom lineup`: the model phantom-1 runs in each tier, and a fallback for each. Run by `run()`. */
+export async function lineupCommand({ io, apiKey, subcommand, flags, table, baseUrl }) {
+    if (!subcommand || subcommand === 'get') {
+        out(await getLineup(apiKey, baseUrl), table, tableLineup, io.stdout);
+    }
+    else if (subcommand === 'set') {
+        // PUT replaces the whole lineup, so start from what the key has now.
+        const read = await getLineup(apiKey, baseUrl);
+        const current = read.lineup ?? {};
+        const { fallbacks: currentFallbacks, ...picks } = current;
+        const fallbacks = { ...currentFallbacks };
+        const model = { economy: flags['economy'], standard: flags['standard'], frontier: flags['frontier'] };
+        const fallback = {
+            economy: flags['economy-fallback'],
+            standard: flags['standard-fallback'],
+            frontier: flags['frontier-fallback'],
+        };
+        for (const tier of LINEUP_TIERS) {
+            applyPick(picks, tier, tier, model[tier]);
+            applyPick(fallbacks, tier, `${tier}-fallback`, fallback[tier]);
+            // A fallback the key already had can't be its tier's own model, which the server refuses. Drop it when this change makes it so.
+            const runs = picks[tier] ?? read.choices?.[tier].find((c) => c.default)?.model;
+            if (fallback[tier] === undefined && fallbacks[tier] === runs)
+                delete fallbacks[tier];
+        }
+        if (LINEUP_TIERS.every((tier) => model[tier] === undefined && fallback[tier] === undefined)) {
+            die('lineup set needs --economy, --standard or --frontier, or --economy-fallback, --standard-fallback or --frontier-fallback, each with a model id or "default"');
+        }
+        const next = Object.keys(fallbacks).length ? { ...picks, fallbacks } : picks;
+        out(await putLineup(apiKey, next, baseUrl), table, tableLineup, io.stdout);
+    }
+    else if (subcommand === 'reset') {
+        out(await resetLineup(apiKey, baseUrl), table, tableLineup, io.stdout);
+    }
+    else {
+        die(`Unknown lineup subcommand: ${subcommand}`);
+    }
+    return 0;
+}

package/dist/spend/lineup.mjs

@@ -0,0 +1,20 @@
+import { request } from "../core/request.mjs";
+/**
+ * A key's lineup decides which model `phantom-1` runs in each tier. The server
+ * checks every pick against the tier's choices (lib/lineup.ts in the Phantom
+ * repo), so the CLI passes model ids through.
+ */
+/** The three tiers `phantom-1` picks between, cheapest first. */
+export const LINEUP_TIERS = ['economy', 'standard', 'frontier'];
+/** The key's lineup, the model each tier runs, and each tier's choices (GET /key/lineup). */
+export function getLineup(apiKey, baseUrl) {
+    return request('GET', '/key/lineup', apiKey, undefined, baseUrl);
+}
+/** Replaces the key's whole lineup (PUT /key/lineup). The server checks it before saving. */
+export function putLineup(apiKey, lineup, baseUrl) {
+    return request('PUT', '/key/lineup', apiKey, lineup, baseUrl);
+}
+/** Puts every tier back to its default (DELETE /key/lineup). */
+export function resetLineup(apiKey, baseUrl) {
+    return request('DELETE', '/key/lineup', apiKey, undefined, baseUrl);
+}

package/dist/spend/report.mjs

@@ -0,0 +1,61 @@
+import { die } from "../core/errors.mjs";
+import { out } from "../core/helpers.mjs";
+import { request } from "../core/request.mjs";
+import { workspaceGet } from "../workspace/command.mjs";
+/** The dates `--from` and `--to` ask for, as a query string. The server checks them. */
+function query(dates) {
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(dates)) {
+        if (value === true)
+            die(`--${name} requires a date as YYYY-MM-DD`);
+        if (value !== undefined)
+            params.set(name, value);
+    }
+    const text = params.toString();
+    return text ? `?${text}` : '';
+}
+/** What the key spent (GET /key/spend). */
+export function getSpend(apiKey, dates = {}, baseUrl) {
+    return request('GET', `/key/spend${query(dates)}`, apiKey, undefined, baseUrl);
+}
+const dollars = (n) => `$${n.toFixed(4)}`;
+const calls = (n) => `${n} ${n === 1 ? 'call' : 'calls'}`;
+/** `--table` output for `spend`. */
+export function tableSpend(d) {
+    const s = d;
+    const lines = [
+        `range           ${s.from} to ${s.to} (UTC)`,
+        `spent           ${dollars(s.total.spent_usd)} (${calls(s.total.calls)})`,
+    ];
+    if (s.total.plan_usd > 0)
+        lines.push(`paid by plan    ${dollars(s.total.plan_usd)}`);
+    if (!s.routing.available)
+        lines.push(`phantom-1 saved not available: ${s.routing.reason}`);
+    else if (s.routing.calls === 0)
+        lines.push('phantom-1 saved no calls went to phantom-1');
+    else
+        lines.push(`phantom-1 saved ${dollars(s.routing.saved_usd)} (${calls(s.routing.calls)} cost ${dollars(s.routing.spent_usd)}; on ${s.routing.baseline_model} they would cost ${dollars(s.routing.baseline_usd)})`);
+    lines.push('', 'by key');
+    for (const k of s.keys) {
+        const saved = k.saved_usd === null ? '' : `  saved ${dollars(k.saved_usd)}`;
+        lines.push(`  ${k.name.padEnd(16)}${dollars(k.spent_usd)}  ${calls(k.calls)}${saved}${k.active ? '' : '  (revoked or rotated)'}`);
+    }
+    lines.push('', 'by model');
+    for (const m of s.models)
+        lines.push(`  ${m.model.padEnd(40)}${dollars(m.spent_usd)}  ${calls(m.calls)}`);
+    return lines.join('\n');
+}
+/**
+ * `phantom spend`: what the key spent, by model and day, and what phantom-1
+ * saved. `--workspace` shows every key in the workspace by name, with the
+ * workspace connection `phantom login` saved. Run by `run()`.
+ */
+export async function spendCommand(input) {
+    const { io, apiKey, table, baseUrl, flags } = input;
+    const dates = { from: flags['from'], to: flags['to'] };
+    const result = flags['workspace']
+        ? (await workspaceGet(input, `/spend${query(dates)}`))
+        : await getSpend(apiKey, dates, baseUrl);
+    out(result, table, tableSpend, io.stdout);
+    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. A route policy picks without calling a model; `phantom-1`, `phantom-1:zdr`, or `auto` on a key with no policy can call the model that picks the tier. `phantom-1:free` never does. */
+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 };
+}