@phantomcodes/cli 0.0.0-stage → 1.1.0

package/dist/cli/commands.mjs

@@ -0,0 +1,154 @@
+import { workspaceCommand, workspaceLogin, forgetWorkspace } from "../workspace/command.mjs";
+import { agentCommand } from "../agents/command.mjs";
+import { balanceCommand, keyCommand, loginCommand, logoutCommand } from "../keys/command.mjs";
+import { lineupCommand, routeCommand } from "../spend/command.mjs";
+import { spendCommand } from "../spend/report.mjs";
+import { planCommand } from "../plan/command.mjs";
+import { verifyCommand } from "../receipts/command.mjs";
+import { setupCommand } from "../setup/command.mjs";
+import { SETUP_MODEL } from "../setup/shared.mjs";
+import { SETUP_NAMES, orList } from "../setup/agents.mjs";
+async function loginDispatch(input) {
+    const { subcommand, flags } = input;
+    return subcommand || flags.paste ? loginCommand(input) : workspaceLogin(input);
+}
+async function logoutDispatch(input) {
+    await forgetWorkspace(input.env, input.baseUrl);
+    return logoutCommand(input);
+}
+async function fundDispatch(input) {
+    const { flags } = input;
+    void flags.amount;
+    void flags.card;
+    void flags.coin;
+    void flags['no-browser'];
+    return workspaceCommand({ ...input, subcommand: 'fund' });
+}
+/** The definitions used by CLI dispatch, help, and generated documentation. */
+export const COMMANDS = [
+    {
+        name: 'login', handler: loginDispatch, keyless: true,
+        help: `  login [--save <name>] [--no-browser]  connect an account or guest workspace by device code
+  login --paste                       validate and save an existing key
+  login [key]                       save your key so you don't need PHANTOM_API_KEY
+                                    (use --paste to prompt for an existing key)`,
+    },
+    {
+        name: 'workspace', handler: workspaceCommand, keyless: true,
+        help: `  workspace [status]                  shared balance, keys, recent usage and management access
+  workspace fund --amount <USD> [--card | --coin usdc|usdt|sol] [--no-browser]
+  workspace payment --id <payment-id>  check verified funding status
+  workspace export --file <path>       export private guest recovery; refuses overwrites
+  workspace import --file <path>       restore a guest, then issue replacement keys
+  workspace revoke-access --id <id>    revoke a browser, device or recovery credential`,
+    },
+    {
+        name: 'fund', handler: fundDispatch, keyless: true,
+        help: `  fund --amount <USD> [--card | --coin usdc|usdt|sol] [--no-browser]
+                                    fund your workspace balance with card (plus Stripe's fee) or crypto`,
+    },
+    {
+        name: 'keys', handler: workspaceCommand, keyless: true,
+        help: `  keys [list]                         remote workspace key metadata, never secrets
+  keys create [--save <name>] [--limit <USD>]
+  keys set --id <id> [--limit <USD|none>] [--budget <USD|none>]
+           [--period <days|none>] [--rate <USD|none>] [--name <name>]
+           [--policy-file <path> | --clear-policy]
+  keys rotate --id <id> [--save <name>] replace only the corresponding saved key
+  keys revoke --id <id>                revoke access, keeping workspace credit
+  keys saved [--balance]               local saved key metadata
+  keys save <name> [key]               validate and save an existing key (prompts if omitted)
+  keys show [name]                     print a secret for shell integration only
+  keys rm <name>                       forget a local copy; remote key keeps working`,
+    },
+    {
+        name: 'claude', handler: agentCommand, keyless: true,
+        help: `  claude [--key <name>] [--no-browser] -- <agent arguments>`,
+    },
+    {
+        name: 'codex', handler: agentCommand, keyless: true,
+        help: `  codex [--key <name>] [--no-browser] -- <agent arguments>`,
+    },
+    {
+        name: 'pi', handler: agentCommand, keyless: true,
+        help: `  pi [--key <name>] [--no-browser] -- <agent arguments>
+                                    run with a saved key`,
+    },
+    {
+        name: 'balance', handler: balanceCommand,
+        help: `  balance                           show credit balance and expiry`,
+    },
+    {
+        name: 'spend', handler: spendCommand, keyless: ['--workspace'],
+        help: `  spend [--from <date>] [--to <date>]  what this key spent, by model and day, and what phantom-1
+                                    saved; dates are UTC days as YYYY-MM-DD, default this month
+  spend --workspace                 every key in the workspace by name (needs phantom login)`,
+    },
+    {
+        name: 'plan', handler: planCommand,
+        help: `  plan [status]                     this key's Pro or Max plan and how much of the week is used
+  plan pro | max [--no-browser]     print a Stripe Checkout link that puts the plan on this key
+                                    and open it
+  plan manage [--no-browser]        the same for Stripe's billing page: card, switch plan, cancel`,
+    },
+    {
+        name: 'key', advanced: true, handler: keyCommand, keyless: true,
+        help: `  key list [--balance]              saved keys, by name and id
+  key save <name> [key]             save a key by name (prompts if no key is given)
+  key show [name]                   print a saved key, for PHANTOM_API_KEY=$(...);
+                                    no name prints the key phantom is using
+  key rm <name>                     forget a saved key (the key keeps working)`,
+    },
+    {
+        name: 'route', handler: routeCommand,
+        help: `  route [get]                       show which model "auto" runs, and why
+  route set --models a,b,c          models for "auto", first is the default
+            [--applies-to auto|all] [--on-empty stop|cheapest] [--fallback]
+            [--stick-minutes n]  keep a conversation's model this long (default 5)
+            [--stick-by-prompt false]  only x-phantom-session marks a conversation
+  route set --file policy.json      replace the whole policy
+  route rule add --if <name=value> --use <model|cheapest|first|next> [--at n]
+                                    conditions: pace, budget_left_pct_below,
+                                    days_left_below, has_tools, input_tokens_over,
+                                    reasoning_requested
+  route rule rm <n>                 remove rule n
+  route test [--model auto]         which model a request would get now (free)
+  route clear                       remove the policy`,
+    },
+    {
+        name: 'lineup', handler: lineupCommand,
+        help: `  lineup [get]                      show the model phantom-1 runs in each tier, and the choices
+  lineup set --economy <model>      pick the model for a tier; "default" goes back to the default
+             [--standard <model>] [--frontier <model>]
+             [--economy-fallback <model>] [--standard-fallback <model>]
+             [--frontier-fallback <model>]
+                                    the model to try when a tier's model fails
+  lineup reset                      every tier back to its default`,
+    },
+    {
+        name: 'logout', handler: logoutDispatch, keyless: true,
+        help: `  logout                            forget workspace access and the default saved key`,
+    },
+    {
+        name: 'setup', handler: setupCommand, keyless: true,
+        help: `  setup                             set up every agent found: install the skill and
+                                    point its model calls at Phantom AI; shows each
+                                    file's changes and asks first
+        [--yes]                     don't ask
+        [--dry-run]                 show the changes, write nothing
+        [--model <id>]              the model each agent starts on (default ${SETUP_MODEL})
+  setup --agent <name>              install the skill for one agent, without asking:
+                                    ${orList(SETUP_NAMES)}
+                                    or all
+  setup [--agent <name>] --provider point that agent's model calls at Phantom AI;
+                                    --provider off removes only what phantom wrote
+  setup --restore [--agent <name>]  put back the files setup changed, from the
+                                    .phantom.bak copies it kept`,
+    },
+    {
+        name: 'verify', advanced: true, handler: verifyCommand, keyless: ['--receipt'],
+        help: `  verify --model <id>               make one tiny call and check its signed receipt
+                                    names the model you asked for (costs a fraction of a cent)
+  verify --receipt <receipt>        check a receipt you already have`,
+    },
+];

package/dist/cli/help.mjs

@@ -0,0 +1,38 @@
+import { DEFAULT_BASE_URL } from "../core/request.mjs";
+import { COMMANDS } from "./commands.mjs";
+/**
+ * Every environment variable phantom reads. The Environment sections of HELP and
+ * docs/reference.md are built from this list, and `npm run docs` fails if the
+ * code reads a variable that is not here.
+ */
+export const ENV_VARS = [
+    { name: 'PHANTOM_API_KEY', about: 'your Phantom AI API key (or save one with login)', secret: true },
+    { name: 'PHANTOM_KEY_NAME', about: 'run as a key saved with keys save; wins over PHANTOM_API_KEY' },
+    { name: 'PHANTOM_BASE_URL', about: `API base, https:// only (default ${DEFAULT_BASE_URL})` },
+    { name: 'PHANTOM_STATE_DIR', about: 'where phantom keeps keys (default ~/.config/phantom-key)' },
+    { name: 'PHANTOM_KEYCHAIN', about: '0 saves keys to files instead of the macOS Keychain; 1 uses the Keychain on any system, which fails where /usr/bin/security is missing' },
+    { name: 'PAI_KEYCHAIN', about: 'The old name of PHANTOM_KEYCHAIN, read when PHANTOM_KEYCHAIN is unset' },
+];
+function envHelp() {
+    const width = Math.max(...ENV_VARS.map((v) => v.name.length)) + 2;
+    const lines = ENV_VARS.map((v) => `  ${v.name.padEnd(width)}${v.about}${v.envOnly ? ' (environment only)' : ''}`);
+    return ['Environment:', ...lines].join('\n');
+}
+/** Full command reference, printed by `phantom --help --all`. */
+export const HELP = `
+phantom — AI inference for your coding agents
+
+Commands:
+${COMMANDS.map((command) => command.help).join('\n')}
+
+Flags:
+  --table          human-readable output instead of JSON
+  --help, -h       print help and run nothing
+  --all            include advanced commands in help
+  --version, -v    print the version
+
+${envHelp()}
+`.trim();
+/** Workflow help printed by default; command definitions remain the source of usage. */
+export const PRIMARY_HELP = HELP.replace(COMMANDS.map((command) => command.help).join('\n'), COMMANDS.filter((command) => !command.advanced).map((command) => command.help).join('\n') +
+    '\n\nAdvanced: phantom --help --all (receipts and verification)');

package/dist/cli/run.mjs

@@ -0,0 +1,79 @@
+import { VERSION } from "../core/version.mjs";
+import { die } from "../core/errors.mjs";
+import { handleError, parseFlags } from "../core/helpers.mjs";
+import { resolveApiKey } from "../keys/saved.mjs";
+import { COMMANDS } from "./commands.mjs";
+import { HELP, PRIMARY_HELP } from "./help.mjs";
+import { LEGACY_SETUP_HINT, legacySetupFound } from "../setup/legacy.mjs";
+/**
+ * Runs one CLI command and returns its exit code: 0 on success, 2 when the
+ * API rejected the key, 1 for other errors. `verify` returns 1 when the check
+ * fails. Errors go to `io.stderr` as JSON. It never calls `process.exit`.
+ * @param argv The arguments after `phantom`.
+ * @param env The environment to read settings from.
+ * @param io Where output goes, and whether stderr is a terminal (for progress lines).
+ */
+export async function run(argv = process.argv.slice(2), env = process.env, io = {
+    stdout: (s) => process.stdout.write(s),
+    stderr: (s) => process.stderr.write(s),
+    isTTY: Boolean(process.stderr.isTTY),
+}) {
+    if (argv[0] === '--version' || argv[0] === '-v') {
+        io.stdout(VERSION + '\n');
+        return 0;
+    }
+    const THREE_STEPS_GUIDE = `
+phantom — prepaid AI inference for coding agents
+
+Get started in three steps:
+  1. Connect your account:
+     phantom login
+
+  2. Fund your balance:
+     phantom fund --amount 10 --card
+     (or phantom fund --amount 10 --coin usdc)
+
+  3. Run your coding agent:
+     phantom claude
+     (or phantom codex, phantom pi)
+
+Run phantom --help for all commands.
+`.trim();
+    // `--help` anywhere before a `--` asks for help, so `phantom setup --help`
+    // prints it rather than running setup.
+    const own = argv.includes('--') ? argv.slice(0, argv.indexOf('--')) : argv;
+    // Only a person at a terminal sees the hint: scripts and agents read stderr
+    // as JSON errors, and the MCP server and setup itself have no use for it.
+    if (io.isTTY && !['setup', 'mcp', 'key', 'keys'].includes(own[0] ?? '') && legacySetupFound(env)) {
+        io.stderr(LEGACY_SETUP_HINT + '\n');
+    }
+    if (argv.length === 0) {
+        io.stdout(THREE_STEPS_GUIDE + '\n');
+        return 0;
+    }
+    if (own.includes('--help') || own.includes('-h')) {
+        const commandHelp = COMMANDS.find((entry) => entry.name === own[0])?.help;
+        io.stdout((own.includes('--all') ? HELP : commandHelp?.trim() ?? PRIMARY_HELP) + '\n');
+        return 0;
+    }
+    try {
+        const command = COMMANDS.find((entry) => entry.name === argv[0]);
+        if (!command)
+            die(`Unknown command: ${argv[0]}. Run with --help for usage.`);
+        const keyless = command.keyless === true ||
+            (command.keyless?.some((flag) => own.slice(1).some((arg) => arg === flag || arg.startsWith(flag + '='))) ?? false);
+        const apiKey = keyless ? '' : resolveApiKey(env);
+        if (!apiKey && !keyless)
+            die('No API key. Set PHANTOM_API_KEY or run: phantom login');
+        const subcommand = argv[1] && !argv[1].startsWith('--') ? argv[1] : undefined;
+        const flagArgs = subcommand ? argv.slice(2) : argv.slice(1);
+        const flags = parseFlags(flagArgs);
+        const table = Boolean(flags['table']);
+        const baseUrl = env.PHANTOM_BASE_URL;
+        const input = { argv, env, io, apiKey, subcommand, flags, table, baseUrl };
+        return await command.handler(input);
+    }
+    catch (err) {
+        return handleError(err, io.stderr);
+    }
+}

package/dist/core/errors.mjs

@@ -0,0 +1,39 @@
+/** An error answer from the Phantom AI API: 401 or 403 maps to exit code 2. */
+export class PhantomApiError extends Error {
+    /** The HTTP status code of the answer. */
+    status;
+    /** The API's error code, or the status code as text when the answer carries none. */
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = 'PhantomApiError';
+        this.status = status;
+        this.code = code;
+    }
+}
+/** An error phantom raises itself, such as a missing flag or a refused payment. */
+export class CliError extends Error {
+    /** A short code for the error, such as `keychain_failed`. `cli_error` when none is given. */
+    code;
+    /** The process exit code {@link run} returns for it. 1 unless given. */
+    exitCode;
+    constructor(message, code = 'cli_error', exitCode = 1) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}
+/**
+ * Throws a {@link CliError}. Every refusal in phantom goes through here.
+ * @param msg The message the user sees.
+ * @param code The error code, printed in the JSON error.
+ * @param exitCode The process exit code.
+ */
+export function die(msg, code = 'cli_error', exitCode = 1) {
+    throw new CliError(msg, code, exitCode);
+}
+/** How to get a key, for every message about a missing one. */
+export const GET_A_KEY = 'Set PHANTOM_API_KEY, or run: phantom login to connect a workspace';
+/** The message for a command that needs a key and has none. */
+export const NO_KEY = `No API key. ${GET_A_KEY}`;

package/dist/core/helpers.mjs

@@ -0,0 +1,85 @@
+import { spawn } from 'node:child_process';
+import { PhantomApiError, CliError, die } from "./errors.mjs";
+/**
+ * Prints an error to stderr as one line of JSON, `{"error":{...}}`, and
+ * returns the exit code: 2 for a key the API rejected (401 or 403), the
+ * {@link CliError}'s own code, or 1 for anything else.
+ */
+export function handleError(err, stderr = (s) => process.stderr.write(s)) {
+    if (err instanceof PhantomApiError) {
+        stderr(JSON.stringify({
+            error: { status: err.status, code: err.code, message: err.message },
+        }) + '\n');
+        return err.status === 401 || err.status === 403 ? 2 : 1;
+    }
+    if (err instanceof CliError) {
+        stderr(JSON.stringify({
+            error: { code: err.code, message: err.message },
+        }) + '\n');
+        return err.exitCode;
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    stderr(JSON.stringify({ error: { code: 'unknown', message: msg } }) + '\n');
+    return 1;
+}
+/**
+ * Reads `--name value`, `--name=value` and bare `--name` (true) from the
+ * arguments. A value that starts with `--` counts as the next flag. Anything
+ * not after a `--name` is skipped.
+ */
+export function parseFlags(args) {
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const eq = arg.indexOf('=');
+            if (eq !== -1) {
+                flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+            }
+            else if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+                flags[arg.slice(2)] = args[++i];
+            }
+            else {
+                flags[arg.slice(2)] = true;
+            }
+        }
+    }
+    return flags;
+}
+/**
+ * A flag's value as a number, or undefined when the flag is absent.
+ * @throws {@link CliError} when the flag has no value or the value is not a number.
+ */
+export function flagNum(flags, name) {
+    const v = flags[name];
+    if (v === undefined)
+        return undefined;
+    if (v === true || (typeof v === 'string' && v.trim() === '')) {
+        die(`--${name} requires a number`);
+    }
+    const n = Number(v);
+    if (!Number.isFinite(n))
+        die(`--${name} must be a number`);
+    return n;
+}
+/** Opens a URL in the user's default browser. */
+export function openUrl(url) {
+    try {
+        if (new URL(url).protocol !== 'https:')
+            return;
+        const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', new URL(url).href]] : ['xdg-open', [url]];
+        spawn(cmd, args, { detached: true, stdio: 'ignore' }).on('error', () => { }).unref();
+    }
+    catch {
+        // The address is on stderr already.
+    }
+}
+/** Prints a result: JSON by default, or `render(data)` with `--table`. */
+export function out(data, table, render, stdout = (s) => process.stdout.write(s)) {
+    if (table) {
+        stdout(render(data) + '\n');
+    }
+    else {
+        stdout(JSON.stringify(data, null, 2) + '\n');
+    }
+}

package/dist/core/request.mjs

@@ -0,0 +1,108 @@
+import { PhantomApiError, die } from "./errors.mjs";
+/** The Phantom AI API address phantom calls when PHANTOM_BASE_URL is unset. */
+export const DEFAULT_BASE_URL = 'https://phantom.codes/v1';
+/** How long {@link request} waits for the whole answer, in milliseconds, before it gives up. */
+export const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Calls the Phantom AI API with the key as a Bearer token and returns the
+ * JSON answer. Every client function in phantom goes through it.
+ * @param method The HTTP method.
+ * @param path The path after the base URL, such as `/key/balance`.
+ * @param apiKey The key sent in the Authorization header.
+ * @param body Sent as JSON when given.
+ * @param baseUrl The API base. Defaults to PHANTOM_BASE_URL, then {@link DEFAULT_BASE_URL}. Must be https ({@link httpsOnly}).
+ * @param headers Extra headers to send.
+ * @param timeoutMs How long to wait for the answer. Defaults to {@link REQUEST_TIMEOUT_MS}.
+ * @throws {@link PhantomApiError} when the API answers with an error status.
+ * @throws {@link CliError} with code `request_timeout` when no answer arrives in time.
+ */
+export async function request(method, path, apiKey, body, baseUrl, headers = {}, timeoutMs = REQUEST_TIMEOUT_MS) {
+    const url = `${apiBase(baseUrl)}${path}`;
+    const signal = AbortSignal.timeout(timeoutMs);
+    let res;
+    let json;
+    try {
+        res = await fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                ...headers,
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+            signal,
+        });
+        // The deadline covers the body too: a server can send headers and then stall.
+        json = await res.json().catch((err) => {
+            if (signal.aborted)
+                throw err;
+            return {};
+        });
+    }
+    catch (err) {
+        if (signal.aborted)
+            die(`Phantom AI did not answer ${method} ${path} within ${Math.round(timeoutMs / 1000)} seconds. Check your connection and try again.`, 'request_timeout');
+        throw err;
+    }
+    if (!res.ok)
+        throw apiError(res.status, json);
+    return json;
+}
+export function apiBase(baseUrl) {
+    return httpsOnly(baseUrl ||
+        (typeof process !== 'undefined' && process.env.PHANTOM_BASE_URL) ||
+        DEFAULT_BASE_URL);
+}
+/**
+ * The API base must be https. The key goes to it on every call, so plain http
+ * is refused, localhost included.
+ */
+export function httpsOnly(baseUrl) {
+    let protocol = '';
+    try {
+        protocol = new URL(baseUrl).protocol;
+    }
+    catch {
+        die(`PHANTOM_BASE_URL is not a web address: ${baseUrl}`, 'base_url_invalid');
+    }
+    if (protocol !== 'https:') {
+        die(`PHANTOM_BASE_URL must start with https://, not ${baseUrl}. phantom sends your API key there, so it refuses plain http, even on localhost.`, 'base_url_insecure');
+    }
+    return baseUrl;
+}
+export function apiError(status, json) {
+    json = json && typeof json === 'object' ? json : {};
+    const err = json.error;
+    let code = String(status);
+    let msg = `HTTP ${status}`;
+    if (err && typeof err === 'object' && !Array.isArray(err)) {
+        const e = err;
+        code = typeof e.code === 'string' ? e.code : code;
+        msg = typeof e.message === 'string' ? e.message : msg;
+    }
+    else if (typeof err === 'string') {
+        // The plan routes answer { error: <code>, detail: <words> }.
+        const detail = json.detail;
+        msg = typeof detail === 'string' && detail ? detail : err;
+        code = err;
+    }
+    else if (typeof json.detail === 'string') {
+        // The purchase routes answer errors as { detail }, some with a { code }.
+        msg = json.detail;
+        const c = json.code;
+        if (typeof c === 'string' && c)
+            code = c;
+    }
+    return new PhantomApiError(status, code, msg);
+}
+/**
+ * Credit left, credit spent and expiry of a key (GET /key/balance).
+ * @throws {@link CliError} with code `balance_unreadable` when the answer has no numbers, such as a sign-in page that came back with status 200.
+ */
+export async function getBalance(apiKey, baseUrl) {
+    const balance = await request('GET', '/key/balance', apiKey, undefined, baseUrl);
+    if (!balance || !Number.isFinite(balance.credit_balance_usd) || !Number.isFinite(balance.credit_spent_usd)) {
+        die('The balance answer had no credit numbers. Check PHANTOM_BASE_URL, and that the address answers with the Phantom AI API.', 'balance_unreadable');
+    }
+    return balance;
+}

package/dist/core/secrets.mjs

@@ -0,0 +1,94 @@
+import path from 'node:path';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { die } from "./errors.mjs";
+import { stateDir } from "./state.mjs";
+/**
+ * On macOS, saved keys and wallets live in the login Keychain rather than in
+ * files. The file stays, holding only a pointer (`pai-keychain:<id>`), so
+ * listing and existence checks work the same on every system. Elsewhere, or with PHANTOM_KEYCHAIN=0, the file holds the secret,
+ * readable by this user only.
+ *
+ * Items are written through /usr/bin/security, which the Keychain then trusts
+ * to read them back, so there is no prompt. That also means any program
+ * running as this user can read them the same way: the Keychain keeps secrets
+ * out of files, backups and sync folders, not away from local programs.
+ *
+ * A secret file written before this is moved into the Keychain the first time
+ * it is read, and replaced with a pointer only after the Keychain returns it
+ * intact.
+ */
+// The Keychain service and pointer keep pai, the CLI's old name, so keys saved
+// before the rename still read.
+export const KEYCHAIN_SERVICE = 'pai';
+export const KEYCHAIN_POINTER = 'pai-keychain:';
+/** Reads and writes phantom's items in the macOS login Keychain through /usr/bin/security, under the service name `pai`, the CLI's old name. */
+export const keychain = {
+    /** The secret saved under `id`, or null when there is none or the Keychain can't be read. */
+    get(id) {
+        const r = spawnSync('/usr/bin/security', ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', id, '-w'], { encoding: 'utf-8' });
+        return r.status === 0 ? Buffer.from(r.stdout.trim(), 'base64').toString('utf-8') : null;
+    },
+    /** Saves `value` under `id`, replacing what was there. Returns false when the Keychain refuses, as it does when locked. */
+    set(id, label, value) {
+        // Sent on stdin rather than as an argument, so the secret never shows in
+        // the process list. Base64 keeps it one unquoted word.
+        const cmd = `add-generic-password -U -s ${KEYCHAIN_SERVICE} -a ${id} -l "phantom ${label}" -w ${Buffer.from(value, 'utf-8').toString('base64')}\n`;
+        return spawnSync('/usr/bin/security', ['-i'], { input: cmd, stdio: ['pipe', 'ignore', 'ignore'] }).status === 0;
+    },
+    /** Removes the item saved under `id`, if any. */
+    delete(id) {
+        spawnSync('/usr/bin/security', ['delete-generic-password', '-s', KEYCHAIN_SERVICE, '-a', id], { stdio: 'ignore' });
+    },
+};
+export function keychainOn(env) {
+    // PAI_KEYCHAIN is the old name, from when this CLI was pai.
+    const flag = env.PHANTOM_KEYCHAIN ?? env.PAI_KEYCHAIN ?? process.env.PHANTOM_KEYCHAIN ?? process.env.PAI_KEYCHAIN;
+    return flag === '1' || (process.platform === 'darwin' && flag !== '0');
+}
+function keychainId(file) {
+    if (!existsSync(file))
+        return null;
+    const raw = readFileSync(file, 'utf-8').trim();
+    return raw.startsWith(KEYCHAIN_POINTER) ? raw.slice(KEYCHAIN_POINTER.length) : null;
+}
+export function writeSecret(env, file, value, opts = {}) {
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    let contents = value;
+    if (keychainOn(env)) {
+        const id = keychainId(file) ?? randomBytes(12).toString('hex');
+        if (!keychain.set(id, path.relative(stateDir(env), file), value)) {
+            die('Could not save to the macOS Keychain. If it is locked (common over SSH), run: security unlock-keychain. Or set PHANTOM_KEYCHAIN=0 to save to a file.', 'keychain_failed');
+        }
+        contents = KEYCHAIN_POINTER + id + '\n';
+    }
+    writeFileSync(file, contents, { mode: 0o600, flag: opts.flag });
+    // `mode` applies only when the file is created; tighten one that was already there.
+    chmodSync(file, 0o600);
+}
+export function readSecret(env, file) {
+    const raw = readFileSync(file, 'utf-8');
+    if (raw.trim().startsWith(KEYCHAIN_POINTER)) {
+        const value = keychain.get(raw.trim().slice(KEYCHAIN_POINTER.length));
+        if (value === null)
+            die(`${file} points to a macOS Keychain item that could not be read. If the Keychain is locked (common over SSH), run: security unlock-keychain`, 'keychain_failed');
+        return value;
+    }
+    if (keychainOn(env)) {
+        const id = randomBytes(12).toString('hex');
+        if (keychain.set(id, path.relative(stateDir(env), file), raw)) {
+            if (keychain.get(id) === raw)
+                writeFileSync(file, KEYCHAIN_POINTER + id + '\n', { mode: 0o600 });
+            else
+                keychain.delete(id);
+        }
+    }
+    return raw;
+}
+export function removeSecret(file) {
+    const id = keychainId(file);
+    if (id)
+        keychain.delete(id);
+    rmSync(file);
+}

package/dist/core/shapes.mjs

@@ -0,0 +1 @@
+export {};

package/dist/core/state.mjs

@@ -0,0 +1,7 @@
+import path from 'node:path';
+import os from 'node:os';
+// Kept at the name the CLI was first published under, so saved keys and
+// wallets survive the rename.
+export function stateDir(env) {
+    return env.PHANTOM_STATE_DIR || path.join(os.homedir(), '.config', 'phantom-key');
+}

package/dist/core/version.mjs

@@ -0,0 +1,2 @@
+/** This release of phantom. `npm version` keeps it equal to the version in package.json. */
+export const VERSION = '1.1.0';