@phantomcodes/cli 0.0.0-stage → 1.1.0

package/dist/workspace/command.mjs

@@ -0,0 +1,209 @@
+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;
+}
+/** A read from the saved workspace, such as `/spend`, with its management credential. */
+export async function workspaceGet(input, path) {
+    const saved = credentials(input);
+    return wire(saved.base_url, 'GET', '/workspaces/' + encodeURIComponent(saved.workspace_id) + path, undefined, saved.management_credential);
+}
+/** 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.1.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": "Harbor Financial LLC",
+  "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"
+    }
+  }
+}

package/skills/phantom-ai/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: phantom-ai
+description: Use the phantom CLI to connect and run coding agents through Phantom AI, manage workspace funding and spending controls, and route models. Applies when the user requests Phantom inference or payment workflows.
+---
+
+# Phantom AI
+
+Phantom AI serves model inference at `https://phantom.codes/v1`. The Phantom CLI connects
+existing coding agents to that API, manages model routing to control costs, and
+handles workspace funding and controls. Management commands
+print JSON; add `--table` for supported human-readable output.
+
+## Connect and run
+
+```bash
+phantom login
+phantom workspace status
+phantom codex
+phantom claude --key coding
+phantom pi
+```
+
+Login uses browser device approval and saves a key privately; ask the user to
+complete approval themselves. For an existing key, have them run
+`phantom login --paste` locally, never paste it into chat.
+Agent configuration is temporary. The Phantom CLI flags go before agent arguments, or `--`.
+
+```bash
+phantom codex --key coding -- exec "review this repository"
+```
+
+Named-key selection uses `PHANTOM_KEY_NAME`, then `PHANTOM_API_KEY`, then the
+saved login key. An agent's explicit `--key` selects that local named key.
+
+## Connect existing agents for future runs
+
+Offer saved setup when the user wants their installed agent to use Phantom AI
+without a phantom launcher. Ask whether they want saved setup or a temporary run;
+when their request already specifies one, follow it.
+
+```bash
+phantom setup --dry-run --table
+phantom setup
+phantom setup --restore
+```
+
+Preview and show the configuration changes before applying the setup the user
+approves. Plain setup detects supported agents and asks before writing. Restart
+the agent or open a new terminal afterward. It keeps backups for restore.
+To connect only Codex, preview the targeted setup first:
+
+```bash
+phantom setup --agent codex --provider --dry-run --table
+phantom setup --agent codex --provider
+```
+
+Targeted provider setup applies without its own confirmation; run it only after
+the user approves the preview. Cursor needs manual settings steps; pi receives
+the skill only. Setup wires up a saved key through helpers or environment
+variables where supported; Cline stores it in a private config file.
+If the user requested a budget, verify that the key the configured agent uses
+has that cap. Creating a separate capped key does not change the default key.
+
+## Fund a workspace
+
+```bash
+phantom fund --amount 10 --card
+phantom fund --amount 10 --coin usdc
+phantom workspace payment --id <payment-id>
+```
+
+Card checkout opens the payment URL in your browser. Crypto funding (`--coin usdc|usdt|sol`)
+provides a Solana pay URL. Credit is available once confirmed. Check pending payments with
+`phantom workspace payment --id <id>`. Check balance anytime with `phantom balance`.
+
+## Control spending and keys
+
+```bash
+phantom keys create --save coding --limit 5
+phantom keys list
+phantom keys set --id <key-id> --budget 20 --period 30 --rate 1
+phantom keys revoke --id <key-id>
+phantom keys saved
+phantom keys rm <name>
+phantom balance
+```
+
+Use the full ID from workspace key metadata. Key controls are enforced by the
+server; the rate is dollars per minute. Revocation preserves shared funds.
+`keys saved` lists local metadata; `keys rm` only forgets the local copy.
+
+## Route models
+
+```bash
+phantom route
+phantom route set --models <model-a>,<model-b>
+phantom route rule add --if has_tools=true --use first
+phantom route test --table
+```
+
+Routing affects `auto` requests. Use `PHANTOM_KEY_NAME=coding` to manage the same
+key used by an agent with `--key coding`. Route tests are free.
+
+## Pick phantom-1's models
+
+```bash
+phantom lineup --table
+phantom lineup set --frontier <model> --economy-fallback <model>
+phantom lineup reset
+```
+
+Each tier (economy, standard, frontier) takes a model from its own choices, which
+`phantom lineup` lists. A fallback is the model to try when the tier's model fails.
+`default` in place of a model puts that tier back to its default. `lineup set`
+keeps the tiers you don't name.
+
+## See what was spent
+
+```bash
+phantom spend --table
+phantom spend --workspace --from 2026-09-01 --to 2026-09-30
+```
+
+`spend` shows what the key spent by model and day, and an estimate of what `phantom-1`
+saved against its frontier model. `--workspace` shows every key in the workspace by
+name. Dates are UTC days (`YYYY-MM-DD`); the default is this month.
+
+## Plans
+
+```bash
+phantom plan --table
+phantom plan pro
+phantom plan manage
+```
+
+A Pro or Max plan pays for `phantom-1` calls up to an amount of model cost in any 7 days,
+then the key's credit pays. `plan` shows the plan and the week's use. `plan pro` and
+`plan max` print a Stripe Checkout link (and open it unless `--no-browser`); the user
+pays there. `plan manage` opens Stripe's billing page. Naming a model, not `phantom-1`,
+still spends credit.
+
+## Advanced tasks
+
+Use `phantom --help --all` for receipts, MCP and direct-key purchases.
+Export guest recovery with `phantom workspace export --file
+<path>` only to a private destination. Recovery grants workspace management access.
+
+## Rules
+
+- Never print, log or repeat API keys, wallet secrets, management credentials or recovery files. `phantom keys show` is for shell integration, not model context.
+- Use CLI commands to manage state; do not manually edit or delete its files.
+- Ask before payments the user has not requested. Existing task approval covers only the requested payment and amount.
+- Run permanent `phantom setup` changes only when requested; otherwise preview with `--dry-run`.
+- Use a user's existing subscription agent when they request that workflow. Phantom inference requires their intent.
+- Exit code 2 means a rejected key; report it rather than retrying unchanged credentials.