@paidfor/mcp 0.5.0 → 0.7.0

package/dist/init.js

@@ -0,0 +1,629 @@
+/**
+ * `paidfor-mcp init`: the whole install in one command. It finds the MCP clients on this machine, offers a wallet (never
+ * made unprompted), offers to link that wallet to a paidfor account in the browser, writes the stdio `paidfor` server
+ * into each chosen client, checks the index answers, and says what is left to do. `paidfor-mcp link` is the link,
+ * register and config steps alone. Everything printed is safe for an agent to read and relay: no key, no team key, no
+ * device code. Everything the outside world touches comes in through InitDeps, so the tests drive it with a fake home,
+ * a fake server and fake client CLIs.
+ */
+import { spawn } from "node:child_process";
+import { hostname as osHostname } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { CLIENT_IDS, backupPath, cliCommands, detectClients, existingCliEnv, isClientId, maskedCommand, mergeEntry, pasteBlock, pathWhich, planJson, readIfExists, targetFor, writeConfigAtomic, } from "./clients.js";
+import { pollLink, startLink } from "./link.js";
+import { deletePending, readPending, writePending } from "./pending.js";
+import { DEFAULT_BASE, VERSION } from "./server.js";
+import { DEFAULT_DAILY_CAP_USD, DEFAULT_MAX_PER_CALL_USD, FUND_SENTENCE, RegisterError, defaultKeyFile, loadWallet, newWallet, registerWallet } from "./wallet.js";
+/** The package as the configs pin it: this exact version, never latest. */
+export const PKG = `@paidfor/mcp@${VERSION}`;
+/** What init and link send as X-Paidfor-Client and as the link's `client`, so the funnel can be counted. */
+export const INIT_CLIENT = `mcp-init/${VERSION}`;
+const VERIFY_HOST = "api-xpay.com";
+/** How long `link` in --yes mode checks a resumed link before it exits and leaves the record for the next run. */
+export const RESUME_WINDOW_MS = 20_000;
+/** Printed with any usage error. */
+export const INIT_USAGE = "usage: paidfor-mcp init [--yes] [--client <id>[,<id>]] [--wallet|--no-wallet] [--link|--no-link] [--wait] [--key-file <path>] [--label <name>] [--dry-run]\n" +
+    "       paidfor-mcp link [--yes] [--client <id>[,<id>]] [--wait] [--key-file <path>] [--label <name>] [--dry-run]\n" +
+    `clients: ${CLIENT_IDS.join(", ")}\n`;
+/** A bad command line: exit 2 with the usage text. */
+class UsageError extends Error {
+}
+/** Parses the init or link command line; throws UsageError on an unknown or misused flag. */
+export function parseFlags(argv, mode) {
+    const f = { yes: false, dryRun: false, wait: false, clients: null, wallet: null, link: null, keyFile: null, label: null };
+    /** The value of a flag that takes one, inline (--flag=v) or as the next argument. */
+    const value = (i, name, inline) => {
+        if (inline !== undefined) {
+            if (!inline)
+                throw new UsageError(`${name} needs a value`);
+            return [inline, i];
+        }
+        const v = argv[i + 1];
+        if (v === undefined || v.startsWith("--"))
+            throw new UsageError(`${name} needs a value`);
+        return [v, i + 1];
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const [name, inline] = argv[i].startsWith("--") && argv[i].includes("=") ? [argv[i].slice(0, argv[i].indexOf("=")), argv[i].slice(argv[i].indexOf("=") + 1)] : [argv[i], undefined];
+        /** A switch, which must not be given a value. */
+        const both = (flag) => {
+            if (inline !== undefined)
+                throw new UsageError(`${name} takes no value`);
+            return flag;
+        };
+        switch (name) {
+            case "--yes":
+            case "-y":
+                f.yes = both(true);
+                break;
+            case "--dry-run":
+                f.dryRun = both(true);
+                break;
+            case "--wait":
+                f.wait = both(true);
+                break;
+            case "--wallet":
+            case "--no-wallet":
+                if (mode === "link")
+                    throw new UsageError(`${name} is for init; link always uses the wallet`);
+                f.wallet = both(name === "--wallet");
+                break;
+            case "--link":
+            case "--no-link":
+                if (mode === "link")
+                    throw new UsageError(`${name} is for init`);
+                f.link = both(name === "--link");
+                break;
+            case "--client": {
+                const [v, j] = value(i, name, inline);
+                i = j;
+                const ids = v.split(",").map((s) => s.trim()).filter(Boolean);
+                for (const id of ids)
+                    if (!isClientId(id))
+                        throw new UsageError(`unknown client ${JSON.stringify(id)}; one of ${CLIENT_IDS.join(", ")}`);
+                f.clients = [...new Set([...(f.clients ?? []), ...ids])];
+                break;
+            }
+            case "--key-file": {
+                const [v, j] = value(i, name, inline);
+                i = j;
+                f.keyFile = v;
+                break;
+            }
+            case "--label": {
+                const [v, j] = value(i, name, inline);
+                i = j;
+                f.label = v;
+                break;
+            }
+            default:
+                throw new UsageError(`unknown option ${JSON.stringify(argv[i])}`);
+        }
+    }
+    return f;
+}
+/** A [Y/n] answer: empty means the default. */
+const yesNo = (answer, dflt = true) => {
+    const a = answer.trim().toLowerCase();
+    if (!a)
+        return dflt;
+    return a === "y" || a === "yes";
+};
+/** Dollars as the questions say them: $5, $0.50. */
+const usd = (n) => (Number.isInteger(n) ? `$${n}` : `$${n.toFixed(2)}`);
+/** Runs `paidfor-mcp init` or `paidfor-mcp link`. Returns the exit code. */
+export async function runInit(argv, d, mode = "init") {
+    let flags;
+    try {
+        flags = parseFlags(argv, mode);
+    }
+    catch (e) {
+        if (!(e instanceof UsageError))
+            throw e;
+        d.err(`paidfor-mcp: ${e.message}\n${INIT_USAGE}`);
+        return 2;
+    }
+    const baseUrl = (d.env.PAIDFOR_API_BASE ?? d.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
+    // Without a terminal there is nobody to answer: behave as --yes, never wait on stdin.
+    const ask = !flags.yes && d.interactive;
+    // Nobody can be shown a link while the command blocks in an agent's shell: print it, save it, exit; `link` finishes it.
+    const nonBlocking = !ask && !flags.wait;
+    const dry = flags.dryRun;
+    /** A path as shown: under the home it starts with ~. */
+    const tilde = (p) => (p.startsWith(d.home + "/") ? `~${p.slice(d.home.length)}` : p);
+    /** A path from the command line, made absolute against the working directory. */
+    const absPath = (p) => (isAbsolute(p) ? p : resolve(d.cwd, p));
+    /** One line to stdout, which an agent may relay: never a secret. */
+    const say = (s = "") => d.out(s + "\n");
+    /** One line to stderr: problems, never a secret. */
+    const warn = (s) => d.err(`paidfor-mcp: ${s}\n`);
+    /** Asks a [Y/n] question; yes by default. */
+    const confirm = async (q) => yesNo(await d.prompt(`${q} [Y/n] `));
+    const linkLater = `npx -y ${PKG} link`;
+    let failures = 0;
+    say(`paidfor ${mode === "init" ? "setup" : "link"} (${PKG})${dry ? ", dry run: nothing is written, no wallet is made, no link is started" : ""}`);
+    // 0. A link an earlier run saved, for this server and this wallet: one a --yes run did not wait for (`link` only), or
+    // one approved whose registration failed (`link` and init's link step), which carries the team key.
+    let resume = null;
+    const saved = await readPending(d.home);
+    if (saved && (mode === "link" || saved.team_key)) {
+        const rec = saved;
+        if (rec.base_url !== baseUrl)
+            warn(`not resuming the pending link: it was started with ${rec.base_url}, and this run uses ${baseUrl}`);
+        // The link's code expires; a key handed over on approval does not.
+        else if (!rec.team_key && Date.parse(rec.expires_at) <= d.now()) {
+            say("The link started earlier has expired; starting a new one.");
+            if (!dry)
+                await deletePending(d.home);
+        }
+        else if (flags.keyFile && absPath(flags.keyFile) !== rec.key_file)
+            warn(`not resuming the pending link: it is for the wallet in ${tilde(rec.key_file)}`);
+        else
+            resume = rec;
+    }
+    // 1. Clients.
+    const ctx = { home: d.home, platform: d.platform, env: d.env, which: d.which };
+    const found = await detectClients(ctx);
+    let chosen;
+    const named = flags.clients ?? (resume && mode === "link" ? resume.clients.filter(isClientId) : null);
+    if (named) {
+        chosen = [];
+        for (const id of named) {
+            const known = found.find((t) => t.id === id);
+            chosen.push(known ?? (await targetFor(id, ctx)).target);
+        }
+    }
+    else if (ask && found.length) {
+        say("\nMCP clients on this machine:");
+        found.forEach((t, i) => say(`  ${i + 1}. ${t.name} (${t.id})`));
+        const a = (await d.prompt("Configure which? Numbers or ids, comma-separated; Enter for all, none to skip: ")).trim().toLowerCase();
+        if (!a || a === "all")
+            chosen = found;
+        else if (a === "none")
+            chosen = [];
+        else {
+            chosen = [];
+            for (const part of a.split(",").map((s) => s.trim()).filter(Boolean)) {
+                const t = /^\d+$/.test(part) ? found[Number(part) - 1] : found.find((x) => x.id === part);
+                if (!t) {
+                    warn(`${JSON.stringify(part)} is not one of the clients listed; skipped`);
+                    continue;
+                }
+                if (!chosen.includes(t))
+                    chosen.push(t);
+            }
+        }
+    }
+    else {
+        chosen = found;
+        say(found.length ? `\nMCP clients found: ${found.map((t) => t.name).join(", ")}` : "\nNo MCP client found on this machine.");
+    }
+    // A config that cannot be parsed is dropped now, before any wallet or link, so a team key is never fetched for nowhere.
+    const usable = [];
+    for (const t of chosen) {
+        if (t.kind === "file") {
+            let text;
+            try {
+                text = await readIfExists(t.file);
+            }
+            catch (e) {
+                warn(`${t.name}: cannot read ${tilde(t.file)} (${e.code ?? "error"}); leaving it alone`);
+                failures++;
+                continue;
+            }
+            const p = planJson(text, t.key, { command: "npx", args: [], env: {} });
+            if (!p.ok) {
+                warn(`${t.name}: not touching ${tilde(t.file)}: ${p.reason}. Fix it, or add the paidfor block by hand`);
+                failures++;
+                continue;
+            }
+        }
+        else if (!(await d.which(t.bin))) {
+            warn(`${t.name}: \`${t.bin}\` is not on PATH; skipped`);
+            failures++;
+            continue;
+        }
+        usable.push(t);
+    }
+    chosen = usable;
+    // 2. Wallet. An agent never makes one unprompted: in --yes mode only with --wallet.
+    let keyFile = null;
+    let address = null;
+    const existingFile = flags.keyFile ? absPath(flags.keyFile) : ((mode === "link" ? resume?.key_file : undefined) ?? defaultKeyFile(d.home));
+    const existing = (await readIfExists(existingFile).catch(() => null)) !== null;
+    if (flags.keyFile && !existing) {
+        warn(`--key-file ${existingFile} cannot be read`);
+        return 1;
+    }
+    let wantWallet;
+    if (mode === "link") {
+        if (!existing) {
+            warn(`no wallet at ${tilde(existingFile)}: run \`npx -y ${PKG} init --wallet\` first, or pass --key-file`);
+            return 1;
+        }
+        wantWallet = true;
+    }
+    else if (flags.wallet !== null)
+        wantWallet = flags.wallet;
+    else if (flags.keyFile)
+        wantWallet = true; // naming a key file is asking for that wallet
+    else if (ask) {
+        const caps = `caps of ${usd(DEFAULT_MAX_PER_CALL_USD)} a call and ${usd(DEFAULT_DAILY_CAP_USD)} a day; you fund it`;
+        say("");
+        wantWallet = await confirm(existing ? `Let this agent pay x402 sellers? This uses the wallet at ${tilde(existingFile)} with ${caps}.` : `Let this agent pay x402 sellers? This makes a wallet on this machine with ${caps}.`);
+    }
+    else
+        wantWallet = false;
+    if (wantWallet) {
+        if (existing) {
+            try {
+                const w = await loadWallet({ PAIDFOR_WALLET_KEY_FILE: existingFile });
+                if (!w)
+                    throw new Error("no wallet");
+                address = w.account.address;
+                keyFile = existingFile;
+            }
+            catch (e) {
+                // WalletConfigError messages name the file and the problem, never the key.
+                warn(`the wallet cannot be used: ${e instanceof Error && e.name === "WalletConfigError" ? e.message : "the key could not be loaded"}`);
+                return 1;
+            }
+            say(`\nWallet: ${address} (${tilde(keyFile)})`);
+            if (resume && (resume.address.toLowerCase() !== address.toLowerCase() || resume.key_file !== keyFile)) {
+                warn("not resuming the pending link: it was started for another wallet");
+                resume = null;
+            }
+        }
+        else if (dry) {
+            keyFile = existingFile;
+            resume = null;
+            say(`\nWallet: would make one at ${tilde(keyFile)} (mode 600)`);
+        }
+        else {
+            resume = null; // a record is for the wallet it was made with, never a new one
+            const w = await newWallet(d.home);
+            address = w.address;
+            keyFile = w.file;
+            say(`\nWallet made: ${address} (key in ${tilde(keyFile)}, mode 600; it never leaves this machine)`);
+        }
+    }
+    else if (mode === "init") {
+        say(`\nNo wallet: the agent gets the read tools only. Add one later with \`npx -y ${PKG} init --wallet\`.`);
+    }
+    // 3. Link to a paidfor account (only with a wallet, and only where the key has somewhere to go).
+    let teamKey = null;
+    let teamName = null;
+    let paused = null;
+    let linkWanted = false;
+    let pendingSaved = false;
+    /** Whether the approved key is safely in the pending record, so `link` can finish without a new approval. */
+    let approvalSaved = false;
+    const pendingStep = `1. Open the link above and approve it. 2. Then run: npx -y ${PKG} link`;
+    if (keyFile) {
+        if (mode === "link")
+            linkWanted = true;
+        else if (flags.link !== null)
+            linkWanted = flags.link;
+        else if (ask)
+            linkWanted = await confirm("Link this wallet to a paidfor account, so its spending follows that account's rules? You approve it in the browser.");
+        if (linkWanted && chosen.length === 0) {
+            say(`\nNot linking: no MCP client config was chosen to hold the account's key. Add paidfor to a client, then run \`${linkLater}\`.`);
+            linkWanted = false;
+        }
+        else if (linkWanted && dry) {
+            say(resume?.team_key ? "\nLink: would register the wallet again with the approval saved earlier" : resume ? `\nLink: would resume the link started earlier (code ${resume.user_code})` : `\nLink: would ask ${baseUrl} for a code to approve in the browser, then register ${address ?? "the new wallet"} to that account`);
+        }
+        else if (linkWanted && address) {
+            const label = flags.label ?? resume?.label ?? d.hostname;
+            /** Says the link did not happen and how to try again. */
+            const notLinked = (why) => say(`Not linked: ${why}. Continuing without an account; run \`${linkLater}\` to try again.`);
+            // The verify URL is shown; the device code never is, even if a server put it in the URL.
+            /** The verify URL to print, or a fallback when it would carry the device code. */
+            const shown = (st) => (st.verify_url.includes(st.device_code) ? `${baseUrl}/team/link?code=${encodeURIComponent(st.user_code)}` : st.verify_url);
+            /**
+             * Registers the wallet with a key a person approved, once or again. Success: the key may go into the configs and
+             * the record is spent. Failure: the key is kept in the record (never in a config) so `link` can retry without a
+             * new approval, unless paidfor refused the key itself (401: revoked), which drops it.
+             */
+            const register = async (st, key, name) => {
+                try {
+                    const r = await registerWallet({ baseUrl, teamKey: key, label, env: { PAIDFOR_WALLET_KEY_FILE: keyFile }, fetchFn: d.fetch, link: st.device_code });
+                    teamKey = key;
+                    teamName = name;
+                    paused = r.paused;
+                    // The key is only in memory until the configs are written, so the record keeps it until then: if the
+                    // person declines the write or a config fails, `link` finishes the job without a new approval.
+                    try {
+                        await writePending(d.home, { ...st, base_url: baseUrl, label, key_file: keyFile, address, clients: chosen.map((t) => t.id), team_key: key, team_name: name });
+                        approvalSaved = true;
+                    }
+                    catch (we) {
+                        // A record that already holds this approval (a retry) is still good: keep it. One without the key would be
+                        // polled again and answered 410, so that one is dropped rather than left to mislead.
+                        if (resume?.team_key === key)
+                            approvalSaved = true;
+                        else
+                            await deletePending(d.home);
+                        if (!approvalSaved)
+                            warn(`the approval could not be saved (${we.code ?? "error"}); if the config step below does not finish, a new approval will be needed`);
+                    }
+                    say(`Wallet ${address} registered to ${name}${r.already ? " (it already was)" : ""}: ${r.paused ? "paused" : "live"}.`);
+                }
+                catch (e) {
+                    const why = e instanceof Error ? e.message : String(e);
+                    if (e instanceof RegisterError && e.status === 401) {
+                        await deletePending(d.home);
+                        say(`Not linked: paidfor refused the approved key (HTTP 401; it was revoked), so the saved approval is dropped. Run \`${linkLater}\` to start a new link.`);
+                        return;
+                    }
+                    try {
+                        await writePending(d.home, { ...st, base_url: baseUrl, label, key_file: keyFile, address, clients: chosen.map((t) => t.id), team_key: key, team_name: name });
+                        say(`Not linked yet: registering the wallet failed (${why}). The approval is saved; run \`${linkLater}\` to register again without a new approval.`);
+                    }
+                    catch (we) {
+                        notLinked(`registering the wallet failed (${why}), and the approval could not be saved (${we.code ?? "error"})`);
+                    }
+                }
+            };
+            say("");
+            try {
+                let start;
+                if (resume?.team_key) {
+                    start = { device_code: resume.device_code, user_code: resume.user_code, verify_url: resume.verify_url, expires_at: resume.expires_at, interval: resume.interval };
+                    say("Resuming: the link was approved earlier; registering the wallet again.");
+                    await register(start, resume.team_key, resume.team_name || "your account");
+                }
+                else if (resume) {
+                    start = { device_code: resume.device_code, user_code: resume.user_code, verify_url: resume.verify_url, expires_at: resume.expires_at, interval: resume.interval };
+                    say(`Resuming the link started earlier: ${shown(start)} (code ${start.user_code})`);
+                    say(nonBlocking ? "Checking whether it is approved..." : "Waiting for the approval...");
+                }
+                else {
+                    start = await startLink({ baseUrl, address, label, client: INIT_CLIENT, fetchFn: d.fetch });
+                    say("Open this and approve:");
+                    say(`  ${shown(start)}`);
+                    say(`Check the code matches: ${start.user_code}`);
+                    if (ask && d.stdoutTTY)
+                        d.openBrowser(shown(start));
+                }
+                const mins = Math.max(1, Math.round((Date.parse(start.expires_at) - d.now()) / 60_000));
+                if (resume?.team_key) {
+                    // registered (or not) above; nothing to poll
+                }
+                else if (!resume && nonBlocking) {
+                    try {
+                        await writePending(d.home, { ...start, base_url: baseUrl, label, key_file: keyFile, address, clients: chosen.map((t) => t.id) });
+                        pendingSaved = true;
+                        say(`Not waiting for it here: the link is saved and expires in ${mins} minute${mins === 1 ? "" : "s"}.`);
+                    }
+                    catch (e) {
+                        notLinked(`the link could not be saved (${e.code ?? "error"})`);
+                    }
+                }
+                else {
+                    if (!resume)
+                        say(`Waiting for the approval (the code expires in ${mins} minute${mins === 1 ? "" : "s"})...`);
+                    const end = await pollLink({ baseUrl, start, client: INIT_CLIENT, fetchFn: d.fetch, sleep: d.sleep, now: d.now, immediate: !!resume, ...(resume && nonBlocking ? { stopAt: d.now() + RESUME_WINDOW_MS } : {}) });
+                    if (end.kind === "pending") {
+                        say(`Not approved yet; approve at ${shown(start)} (code ${start.user_code}) and run this again.`);
+                        return 0;
+                    }
+                    // Denied, expired and already used end the link for good. An approval keeps the record until the
+                    // registration succeeds (register() deletes it then, or rewrites it with the key); an unreadable answer keeps it.
+                    if (resume && (end.kind === "denied" || end.kind === "expired" || end.kind === "used"))
+                        await deletePending(d.home);
+                    if (end.kind !== "approved")
+                        notLinked(end.message);
+                    else {
+                        say(`Approved for ${end.team_name}.`);
+                        await register(start, end.team_key, end.team_name);
+                    }
+                }
+            }
+            catch (e) {
+                notLinked(e instanceof Error ? e.message : String(e));
+            }
+            if (pendingSaved && mode === "link") {
+                say(`\nNext:\n  ${pendingStep}`);
+                return 0;
+            }
+        }
+    }
+    // 4. Config.
+    const env = {};
+    if (keyFile) {
+        env.PAIDFOR_WALLET_KEY_FILE = keyFile;
+        env.PAIDFOR_MAX_PER_CALL_USD = DEFAULT_MAX_PER_CALL_USD.toFixed(2);
+        env.PAIDFOR_DAILY_CAP_USD = String(DEFAULT_DAILY_CAP_USD);
+    }
+    if (teamKey)
+        env.PAIDFOR_TEAM_KEY = teamKey;
+    const ours = { command: "npx", args: ["-y", PKG], env };
+    /** The env key names an entry will get, for the summary (never their values). */
+    const keyNames = (e) => {
+        const names = Object.keys(e.env);
+        if (dry && linkWanted)
+            names.push("PAIDFOR_TEAM_KEY (once the link is approved)");
+        return names.length ? `; env ${names.join(", ")}` : "; no env";
+    };
+    const planned = [];
+    for (const t of chosen) {
+        if (t.kind === "file") {
+            const p = planJson(await readIfExists(t.file).catch(() => null), t.key, ours);
+            if (!p.ok) {
+                warn(`${t.name}: not touching ${tilde(t.file)}: ${p.reason}`);
+                failures++;
+                continue;
+            }
+            const what = p.action === "create" ? `create it with` : p.action === "add" ? `add paidfor (keeping the ${p.others} other server${p.others === 1 ? "" : "s"}) as` : `replace the paidfor entry${p.wasHosted ? " (the hosted URL, which cannot pay)" : ""} with`;
+            const bak = p.action !== "create" && (await readIfExists(backupPath(t.file)).catch(() => null)) === null ? `; backup to ${tilde(backupPath(t.file))}` : "";
+            planned.push({ t, text: p.text, summary: `${t.name} (${tilde(t.file)}): ${what} npx -y ${PKG}${keyNames(p.entry)}${bak}` });
+        }
+        else {
+            const entry = mergeEntry({ env: await existingCliEnv(t) }, ours);
+            const how = t.id === "vscode" ? "code --add-mcp (user profile)" : `${t.bin} mcp add${t.id === "claude-code" ? " --scope user" : ""}, replacing any paidfor entry there,`;
+            planned.push({ t, entry, summary: `${t.name}: ${how} with npx -y ${PKG}${keyNames(entry)}` });
+        }
+    }
+    const written = [];
+    /** Whether the config writes were attempted: not a dry run, and not declined. */
+    let go = false;
+    /** What to tell a person whose approved key is not yet in every config. */
+    const finishLater = () => (approvalSaved ? `The approval is saved; run \`${linkLater}\` to finish without a new approval.` : `The approval could not be saved, so run \`${linkLater}\` and approve again.`);
+    if (planned.length) {
+        say(`\n${dry ? "Would change" : "Config changes"}:`);
+        for (const p of planned)
+            say(`  ${p.summary}`);
+        go = !dry;
+        if (go && ask)
+            go = await confirm("Write these changes?");
+        if (!dry && !go) {
+            say("Nothing written.");
+            if (teamKey)
+                say(`The account's key is in no config yet. ${finishLater()}`);
+        }
+        if (go) {
+            for (const p of planned) {
+                try {
+                    if (p.t.kind === "file" && "text" in p) {
+                        const w = await writeConfigAtomic(p.t.file, p.text, { secret: !!teamKey || p.text.includes("PAIDFOR_TEAM_KEY") });
+                        if (w.tightened && process.platform !== "win32")
+                            say(`  ${p.t.name}: the config now holds the account's key, so it was made readable by you only (mode 600).`);
+                    }
+                    else if (p.t.kind === "cli" && "entry" in p) {
+                        const cmds = cliCommands(p.t, p.entry);
+                        if (cmds.remove)
+                            await d.exec(p.t.bin, cmds.remove).catch(() => undefined);
+                        const r = await d.exec(p.t.bin, cmds.add);
+                        // Never echo the command line or the child's output: either can hold the team key.
+                        if (r.code !== 0)
+                            throw new Error(`\`${p.t.bin}\` exited with ${r.code}`);
+                    }
+                    written.push(p.t);
+                    say(`  done: ${p.t.name}`);
+                }
+                catch (e) {
+                    failures++;
+                    warn(`${p.t.name}: could not write the config: ${e instanceof Error ? e.message.split(teamKey ?? "\u0000").join("***") : "error"}`);
+                }
+            }
+        }
+        else if (dry) {
+            for (const p of planned)
+                if (p.t.kind === "cli" && "entry" in p)
+                    say(`  would run: ${maskedCommand(p.t.bin, cliCommands(p.t, p.entry).add)}`);
+        }
+    }
+    // The approval's record is spent only once the key is in every config it was meant for.
+    if (teamKey && !dry) {
+        if (planned.length > 0 && written.length === planned.length)
+            await deletePending(d.home);
+        else if (go && written.length < planned.length)
+            say(`The account's key did not reach every client. ${finishLater()}`);
+    }
+    if (chosen.length === 0) {
+        say(`\nAdd this stdio server to your MCP client's config:`);
+        say(pasteBlock(ours));
+    }
+    // 5. Verify the index answers.
+    if (!dry) {
+        try {
+            const res = await d.fetch(`${baseUrl}/v1/check?url=${encodeURIComponent(VERIFY_HOST)}`, {
+                headers: { Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}`, "X-Paidfor-Client": INIT_CLIENT },
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const j = (await res.json());
+            say(`\nCheck: ${VERIFY_HOST} is rated ${j.verdict ?? "unknown"}${j.verdict === "avoid" ? ", as expected; the index answers" : "; expected avoid"}.`);
+        }
+        catch (e) {
+            warn(`could not check ${VERIFY_HOST} against ${baseUrl} (${e instanceof Error ? e.message : String(e)}); the config is written, the tools may still work`);
+        }
+    }
+    // 6. Next steps.
+    if (!dry) {
+        say("\nNext:");
+        if (pendingSaved)
+            say(`  ${pendingStep}`);
+        for (const t of written)
+            say(`  Restart ${t.name}: ${t.restart}.`);
+        if (address)
+            say(`  Wallet ${address}: ${FUND_SENTENCE}.`);
+        if (teamKey) {
+            say(`  Account: ${baseUrl}/team (${teamName}).`);
+            say(paused ? `  The wallet is paused: open ${baseUrl}/team, check its limits, untick Paused and save.` : "  The wallet is live: it pays within the account's rules and the caps in the config.");
+        }
+        else if (keyFile && mode === "init" && !pendingSaved)
+            say(`  To follow an account's rules later: \`${linkLater}\`.`);
+    }
+    return failures ? 1 : 0;
+}
+/**
+ * One argument for a cmd.exe command line. First quoted the way the Windows C runtime splits arguments (backslashes
+ * before a quote doubled, quotes escaped), then every character cmd.exe gives a meaning to is escaped with ^. The CLIs
+ * are .cmd shims, and a shim passes its arguments through cmd.exe a second time, so the ^ escaping is applied twice.
+ * The same rules as cross-spawn.
+ */
+export function winArg(arg) {
+    let a = arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1");
+    a = `"${a}"`;
+    const meta = /([()\][%!^"`<>&|;, *?])/g;
+    return a.replace(meta, "^$1").replace(meta, "^$1");
+}
+/** What to spawn on Windows for a CLI shim: cmd.exe with one verbatim, fully escaped command line. */
+export function winSpawn(cmd, args, env) {
+    const line = [cmd.replace(/([()\][%!^"`<>&|;, *?])/g, "^$1"), ...args.map(winArg)].join(" ");
+    return { file: env.ComSpec?.trim() || env.COMSPEC?.trim() || "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`] };
+}
+/** The real world: process env, this home, a TTY prompt, node's fetch, child processes. */
+export function realDeps() {
+    const env = process.env;
+    const platform = process.platform;
+    return {
+        env,
+        home: env.HOME?.trim() || env.USERPROFILE?.trim() || process.cwd(),
+        platform,
+        cwd: process.cwd(),
+        interactive: !!process.stdin.isTTY,
+        stdoutTTY: !!process.stdout.isTTY,
+        out: (s) => void process.stdout.write(s),
+        err: (s) => void process.stderr.write(s),
+        prompt: (q) => new Promise((res) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            rl.question(q, (a) => {
+                rl.close();
+                res(a);
+            });
+        }),
+        fetch: globalThis.fetch,
+        exec: (cmd, args) => new Promise((res) => {
+            // Never shell: true, so nothing in args is interpreted. On Windows the CLIs are .cmd shims that only cmd.exe
+            // can run, so the command line is built and escaped here (winSpawn) and passed through verbatim.
+            const win = platform === "win32" ? winSpawn(cmd, args, env) : null;
+            const child = win
+                ? spawn(win.file, win.args, { stdio: ["ignore", "pipe", "pipe"], windowsVerbatimArguments: true })
+                : spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+            let stdout = "";
+            let stderr = "";
+            child.stdout.on("data", (b) => (stdout += b));
+            child.stderr.on("data", (b) => (stderr += b));
+            child.on("error", () => res({ code: 127, stdout, stderr }));
+            child.on("close", (code) => res({ code: code ?? 1, stdout, stderr }));
+        }),
+        which: pathWhich(env, platform),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        now: Date.now,
+        openBrowser: (url) => {
+            const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+            try {
+                spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => undefined).unref();
+            }
+            catch {
+                /* best effort */
+            }
+        },
+        hostname: osHostname().split(".")[0] || "agent",
+    };
+}

package/dist/link.d.ts

@@ -0,0 +1,45 @@
+/** The answer to POST /v1/team/link; the device code is a secret. */
+export type LinkStart = {
+    user_code: string;
+    device_code: string;
+    verify_url: string;
+    expires_at: string;
+    interval: number;
+};
+/** How a link ended. Only "approved" carries a key; every other end leaves the wallet unlinked. */
+export type LinkEnd = {
+    kind: "approved";
+    team_key: string;
+    team_name: string;
+} | {
+    kind: "denied" | "expired" | "used" | "failed";
+    message: string;
+}
+/** Only with `stopAt`: still waiting for the person when the window closed. */
+ | {
+    kind: "pending";
+    message: string;
+};
+/** Starts a link. Throws an Error whose message is safe to show (never a code or a key) when it cannot. */
+export declare function startLink(o: {
+    baseUrl: string;
+    address: string;
+    label: string;
+    client: string;
+    fetchFn?: typeof fetch;
+}): Promise<LinkStart>;
+/**
+ * Polls until the link is approved, denied, expired or already used, or `expires_at` passes. A network error or a 5xx
+ * is tried again on the next tick; a 429 slows the polling down. `immediate` asks once before the first wait (a link
+ * resumed from an earlier run); `stopAt` (epoch ms) gives up with { kind: "pending" } when the next poll would be later.
+ */
+export declare function pollLink(o: {
+    baseUrl: string;
+    start: LinkStart;
+    client: string;
+    fetchFn?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    immediate?: boolean;
+    stopAt?: number;
+}): Promise<LinkEnd>;