sella-cli 0.5.0

package/README.md

@@ -0,0 +1,46 @@
+# sella-cli
+
+Terminal onboarding for [Sella](https://sella.network) — the marketplace where agents buy datasets,
+models, and machine-payable APIs.
+
+```bash
+npx sella-cli init
+```
+
+`init` detects your agent clients (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Cline),
+installs the Sella MCP server into each, and walks you through pairing. Installed users get the
+`sella` binary.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `sella init` | Detect clients → install the Sella MCP server → pair → verify |
+| `sella sandbox <query>` | Try Sella with **no signup** — search the live marketplace (rate-limited) |
+| `sella pair` | Pair this machine only (`--setup-code <code>` / `SELLA_SETUP_CODE`, or `--email` + OTP) |
+| `sella clients` | List detected clients (`--install` to write configs, `--client a,b` to filter, `--dry-run`) |
+| `sella doctor` | Verify the install: endpoint, credentials, auth, wallets, x402 pay-quote — each failure names its fix |
+| `sella status` | Show your API key + AgentWallet funding/balances, with each chain marked **live** vs **deposit-only** |
+| `sella fund` | Per-chain USDC deposit addresses + funding page (QR + fiat on-ramp), labelled live vs deposit-only |
+| `sella mcp` | Run as a local **stdio MCP server** that proxies Sella with your stored key — for clients that can't use a remote MCP endpoint |
+| `sella publish init <file.csv>` | Scaffold `sella-dataset.json` + a structural pre-check of the CSV |
+| `sella publish push` | Publish the dataset via the same route the web dashboard uses — a CSV → live listing without a browser |
+
+`status`/`fund` read the live chain registry (`GET {backend}/api/payments/chains`) to label each
+wallet **live · spendable** vs **deposit-only · settle pending**, so the CLI tracks the multi-chain
+rollout automatically — no per-chain update needed. If the backend is unreachable they still list
+your wallets, just without the label.
+
+## Contract (every command)
+
+- `--json` → exactly one JSON document on stdout; errors on stderr; meaningful exit codes.
+- `--yes` / env vars for every prompt — agents run this CLI too; nothing may hang on a TTY.
+- `NO_COLOR` / `--no-color` honored; no spinner-only feedback; color never carries meaning alone.
+- Config writes are idempotent, preserve other servers, and leave a one-time `.sella-backup`.
+- `SELLA_MCP_URL` overrides the endpoint (self-hosted / staging).
+
+## Security
+
+Install links and configs written before pairing carry **no secrets** — Sella's bootstrap MCP tools
+(`sella_setup_claim`, `sella_auth_*`) are callable without a token, so the agent pairs itself and
+stores its own credentials. Never paste API keys into URLs or shell history.

package/dist/api.js

@@ -0,0 +1,63 @@
+/**
+ * Thin client over Sella's noauth bootstrap MCP tools (CLI sprint C2). No new auth paths:
+ * the CLI speaks the exact same tools/call surface agents use (sella_setup_claim,
+ * sella_auth_start/complete), so CLI, web, and agent onboarding cannot drift.
+ */
+export async function callToolRaw(mcpUrl, name, args, fetchImpl = fetch) {
+    let res;
+    try {
+        res = await fetchImpl(mcpUrl, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', id: name, method: 'tools/call', params: { name, arguments: args } }),
+        });
+    }
+    catch (err) {
+        throw new Error(`Could not reach the Sella endpoint at ${mcpUrl} (${err instanceof Error ? err.message : 'network error'}). ` +
+            'Check your connection, proxy settings, or SELLA_MCP_URL.');
+    }
+    if (res.status === 429) {
+        throw new Error('Sandbox rate limit reached. Run `sella pair` for unmetered access.');
+    }
+    if (!res.ok) {
+        throw new Error(`Sella endpoint at ${mcpUrl} responded ${res.status}. Check SELLA_MCP_URL.`);
+    }
+    const body = (await res.json());
+    const structured = body?.result?.structuredContent;
+    if (structured && typeof structured === 'object')
+        return structured;
+    const text = body?.result?.content?.[0]?.text;
+    if (typeof text === 'string') {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    throw new Error('Unexpected response shape from the Sella MCP endpoint.');
+}
+export const callAuthTool = (mcpUrl, name, args, fetchImpl = fetch) => callToolRaw(mcpUrl, name, args, fetchImpl);
+/** Zero-identity demo: read-only free tools only (list_market_apis + search_datasets). */
+export async function sandboxSearch(mcpUrl, query, fetchImpl = fetch) {
+    // Tolerate a single tool being flaky, but never swallow the rate limit — that's what the user
+    // needs to see (it tells them to pair).
+    const soft = (err) => {
+        if (err instanceof Error && /rate limit/i.test(err.message))
+            throw err;
+        return {};
+    };
+    const [datasets, apis] = await Promise.all([
+        callToolRaw(mcpUrl, 'search_datasets', { query, limit: 5 }, fetchImpl).catch(soft),
+        callToolRaw(mcpUrl, 'list_market_apis', { query, limit: 5 }, fetchImpl).catch(soft),
+    ]);
+    // search_datasets returns the array directly; list_market_apis wraps it in `catalogue`.
+    const asArray = (v, ...keys) => Array.isArray(v) ? v : keys.map((k) => v?.[k]).find(Array.isArray) || [];
+    return {
+        datasets: asArray(datasets, 'datasets', 'results').slice(0, 5),
+        apis: asArray(apis, 'catalogue', 'providers', 'apis', 'results').slice(0, 5),
+    };
+}
+export const claimSetupCode = (mcpUrl, code, fetchImpl) => callAuthTool(mcpUrl, 'sella_setup_claim', { code, client: 'sella-cli' }, fetchImpl);
+export const startEmailOtp = (mcpUrl, email, fetchImpl) => callAuthTool(mcpUrl, 'sella_auth_start', { email }, fetchImpl);
+export const completeEmailOtp = (mcpUrl, email, otpCode, fetchImpl) => callAuthTool(mcpUrl, 'sella_auth_complete', { email, otp_code: otpCode }, fetchImpl);

package/dist/chains.js

@@ -0,0 +1,75 @@
+/**
+ * CLI-side reader for the backend chain registry (CLI sprint — registry binding).
+ *
+ * The registry is OWNED by the backend and served at `GET {apiBase}/api/payments/chains`
+ * (see .tasks/PAYMENTS_CHAIN_REGISTRY_CONTRACT.md). The CLI deliberately holds NO copy of it —
+ * a bundled mirror would be a third source of truth to drift against the backend + Next mirror.
+ * Instead it fetches the live registry (using the `apiBase` already stored in the AgentWallet
+ * config at pairing) and degrades to *no annotation* when the backend is unreachable, so `status`
+ * and `fund` keep working offline. Zero new dependency: built-in fetch + AbortController, and a
+ * hard timeout so a slow backend can never hang a headless run.
+ */
+const REGISTRY_TIMEOUT_MS = 2500;
+/**
+ * Fetch the registry keyed by chain id. Never throws and never hangs — returns an empty map when
+ * `apiBase` is absent, the backend is unreachable/slow, or the shape is unexpected. An empty map
+ * means "don't annotate", which is exactly the pre-registry behaviour.
+ */
+export async function fetchChainRegistry(apiBase, fetchImpl = fetch) {
+    const map = new Map();
+    if (!apiBase)
+        return map;
+    const url = `${apiBase.replace(/\/+$/, '')}/api/payments/chains`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REGISTRY_TIMEOUT_MS);
+    // Don't let the timeout keep a fast-exiting CLI process alive.
+    timer.unref?.();
+    try {
+        const res = await fetchImpl(url, { signal: controller.signal });
+        if (!res.ok)
+            return map;
+        const body = (await res.json());
+        const chains = Array.isArray(body?.chains) ? body.chains : [];
+        for (const c of chains) {
+            if (c && typeof c.id === 'string')
+                map.set(c.id, c);
+        }
+    }
+    catch {
+        /* offline / slow / bad shape — annotation is optional, never blocks the command */
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return map;
+}
+/**
+ * What can the agent actually do with funds on this chain *today*?
+ *  - `live`         — Sella can settle an outbound provider payment from here → spendable now.
+ *  - `deposit-only` — accepts deposits, but outbound settle isn't proven yet (fund it, can't spend).
+ *  - `inbound-only` — settles inbound (agents paying Sella) with no agent-wallet spend, e.g. Stellar.
+ *  - `unknown`      — chain not in the registry (or registry unreachable).
+ */
+export function chainCapability(info) {
+    if (!info)
+        return 'unknown';
+    if (info.settle?.outbound === true)
+        return 'live';
+    if (info.funding?.crypto === true)
+        return 'deposit-only';
+    if (info.settle?.inbound === true)
+        return 'inbound-only';
+    return 'unknown';
+}
+export function capabilityLabel(cap) {
+    switch (cap) {
+        case 'live':
+            return 'live · spendable';
+        case 'deposit-only':
+            return 'deposit-only · settle pending';
+        case 'inbound-only':
+            return 'inbound-only';
+        default:
+            return '';
+    }
+}

package/dist/clients.js

@@ -0,0 +1,140 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export function defaultEnv() {
+    return {
+        platform: process.platform,
+        home: process.env.HOME || process.env.USERPROFILE || '',
+        appData: process.env.APPDATA,
+    };
+}
+function appSupport(env, ...segments) {
+    if (env.platform === 'darwin')
+        return path.join(env.home, 'Library', 'Application Support', ...segments);
+    if (env.platform === 'win32')
+        return path.join(env.appData || path.join(env.home, 'AppData', 'Roaming'), ...segments);
+    return path.join(env.home, '.config', ...segments);
+}
+function httpEntry(mcpUrl, apiKey) {
+    return {
+        url: mcpUrl,
+        ...(apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : {}),
+    };
+}
+/** Claude Desktop and Cline speak stdio only — bridge to the remote endpoint via mcp-remote. */
+function stdioBridgeEntry(mcpUrl, apiKey) {
+    return {
+        command: 'npx',
+        args: ['-y', 'mcp-remote', mcpUrl, ...(apiKey ? ['--header', `Authorization: Bearer ${apiKey}`] : [])],
+    };
+}
+const CLIENTS = [
+    {
+        id: 'claude-code',
+        name: 'Claude Code',
+        marker: (env) => path.join(env.home, '.claude'),
+        configPath: (env) => path.join(env.home, '.claude.json'),
+        apply: (doc, mcpUrl, apiKey) => {
+            doc.mcpServers = doc.mcpServers || {};
+            doc.mcpServers.sella = { type: 'http', ...httpEntry(mcpUrl, apiKey) };
+        },
+    },
+    {
+        id: 'claude-desktop',
+        name: 'Claude Desktop',
+        marker: (env) => appSupport(env, 'Claude'),
+        configPath: (env) => appSupport(env, 'Claude', 'claude_desktop_config.json'),
+        apply: (doc, mcpUrl, apiKey) => {
+            doc.mcpServers = doc.mcpServers || {};
+            doc.mcpServers.sella = stdioBridgeEntry(mcpUrl, apiKey);
+        },
+    },
+    {
+        id: 'cursor',
+        name: 'Cursor',
+        marker: (env) => path.join(env.home, '.cursor'),
+        configPath: (env) => path.join(env.home, '.cursor', 'mcp.json'),
+        apply: (doc, mcpUrl, apiKey) => {
+            doc.mcpServers = doc.mcpServers || {};
+            doc.mcpServers.sella = httpEntry(mcpUrl, apiKey);
+        },
+    },
+    {
+        id: 'windsurf',
+        name: 'Windsurf',
+        marker: (env) => path.join(env.home, '.codeium', 'windsurf'),
+        configPath: (env) => path.join(env.home, '.codeium', 'windsurf', 'mcp_config.json'),
+        apply: (doc, mcpUrl, apiKey) => {
+            doc.mcpServers = doc.mcpServers || {};
+            const entry = { serverUrl: mcpUrl };
+            if (apiKey)
+                entry.headers = { Authorization: `Bearer ${apiKey}` };
+            doc.mcpServers.sella = entry;
+        },
+    },
+    {
+        id: 'vscode',
+        name: 'VS Code',
+        marker: (env) => appSupport(env, 'Code', 'User'),
+        configPath: (env) => appSupport(env, 'Code', 'User', 'mcp.json'),
+        apply: (doc, mcpUrl, apiKey) => {
+            doc.servers = doc.servers || {};
+            doc.servers.sella = { type: 'http', ...httpEntry(mcpUrl, apiKey) };
+        },
+    },
+    {
+        id: 'cline',
+        name: 'Cline',
+        marker: (env) => appSupport(env, 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev'),
+        configPath: (env) => appSupport(env, 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json'),
+        apply: (doc, mcpUrl, apiKey) => {
+            doc.mcpServers = doc.mcpServers || {};
+            doc.mcpServers.sella = stdioBridgeEntry(mcpUrl, apiKey);
+        },
+    },
+];
+export function detectClients(env = defaultEnv()) {
+    return CLIENTS.map((spec) => ({
+        id: spec.id,
+        name: spec.name,
+        installed: fs.existsSync(spec.marker(env)),
+        configPath: spec.configPath(env),
+    }));
+}
+/** Merge the Sella server entry into one client's config. Never touches other entries. */
+export function installSellaIntoClient(id, opts) {
+    const env = opts.env || defaultEnv();
+    const spec = CLIENTS.find((c) => c.id === id);
+    if (!spec)
+        throw new Error(`Unknown client: ${id}`);
+    const configPath = spec.configPath(env);
+    const exists = fs.existsSync(configPath);
+    let doc = {};
+    if (exists) {
+        const raw = fs.readFileSync(configPath, 'utf8').trim();
+        if (raw) {
+            try {
+                doc = JSON.parse(raw);
+            }
+            catch {
+                throw new Error(`${spec.name} config at ${configPath} is not valid JSON — fix or remove it, then re-run.`);
+            }
+        }
+    }
+    const before = JSON.stringify(doc);
+    spec.apply(doc, opts.mcpUrl, opts.apiKey);
+    const after = JSON.stringify(doc, null, 2);
+    if (exists && JSON.stringify(JSON.parse(before)) === JSON.stringify(JSON.parse(after))) {
+        return { id, configPath, action: 'unchanged' };
+    }
+    let backupPath;
+    if (!opts.dryRun) {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        if (exists && before.trim() && before !== '{}') {
+            backupPath = `${configPath}.sella-backup`;
+            if (!fs.existsSync(backupPath))
+                fs.writeFileSync(backupPath, before === '' ? '' : JSON.stringify(JSON.parse(before), null, 2));
+        }
+        fs.writeFileSync(configPath, after + '\n');
+    }
+    return { id, configPath, action: exists ? 'updated' : 'created', backupPath };
+}

package/dist/credentials.js

@@ -0,0 +1,51 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+const KEYCHAIN_SERVICE = 'sella-cli';
+function defaultExec(file, args) {
+    execFileSync(file, args, { stdio: 'ignore' });
+}
+function write600(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+}
+/** macOS keychain via the built-in `security` CLI (no native deps). Other OSes: file fallback. */
+function tryKeychain(apiKey, env, execFile) {
+    if (env.platform !== 'darwin')
+        return false;
+    try {
+        execFile('security', ['add-generic-password', '-U', '-s', KEYCHAIN_SERVICE, '-a', 'default', '-w', apiKey]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function saveCredentials(payload, opts) {
+    const { env } = opts;
+    const files = [];
+    if (payload.walletConfig) {
+        const p = path.join(env.home, '.sella-wallet.json');
+        write600(p, payload.walletConfig);
+        files.push(p);
+    }
+    if (payload.agentWallet?.status === 'provisioned' && payload.agentWallet.config) {
+        const p = path.join(env.home, '.sella-agentwallet', 'config.json');
+        write600(p, payload.agentWallet.config);
+        files.push(p);
+    }
+    const keychainOk = Boolean(payload.apiKey) && opts.allowKeychain && tryKeychain(payload.apiKey, env, opts.execFile || defaultExec);
+    if (!keychainOk && payload.apiKey) {
+        const p = path.join(env.home, '.sella', 'credentials.json');
+        write600(p, {
+            apiKey: payload.apiKey,
+            mcpServerUrl: payload.mcpServerUrl || '',
+            createdAt: new Date().toISOString(),
+        });
+        files.push(p);
+    }
+    const custodyNote = keychainOk
+        ? `API key stored in the macOS keychain (service "${KEYCHAIN_SERVICE}"). Wallet files are owner-read-only; client configs carry the key in plaintext — that is how MCP clients read headers today.`
+        : `Secrets stored as owner-read-only files (0600)${env.platform === 'win32' ? ' — on Windows, protect your user profile' : ''}. Client configs carry the key in plaintext — that is how MCP clients read headers today. Never commit or share these files.`;
+    return { files, keyStorage: keychainOk ? 'keychain' : 'file', custodyNote };
+}

package/dist/doctor.js

@@ -0,0 +1,197 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fetchChainRegistry, chainCapability } from './chains.js';
+const KEYCHAIN_SERVICE = 'sella-cli';
+function defaultExecOut(file, args) {
+    return execFileSync(file, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+/** Stored API key: macOS keychain first, then the 0600 fallback file. */
+export function loadStoredKey(env, execOut = defaultExecOut) {
+    if (env.platform === 'darwin') {
+        try {
+            const key = execOut('security', ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', 'default', '-w']).trim();
+            if (key)
+                return { apiKey: key, source: 'keychain' };
+        }
+        catch {
+            /* not in keychain — fall through */
+        }
+    }
+    try {
+        const raw = fs.readFileSync(path.join(env.home, '.sella', 'credentials.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.apiKey)
+            return { apiKey: parsed.apiKey, source: 'file' };
+    }
+    catch {
+        /* no file */
+    }
+    return null;
+}
+async function rpc(mcpUrl, body, fetchImpl, apiKey) {
+    const res = await fetchImpl(mcpUrl, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+        },
+        body: JSON.stringify({ jsonrpc: '2.0', id: 'doctor', ...body }),
+    });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return res.json();
+}
+export async function runDoctor(opts) {
+    const fetchImpl = opts.fetchImpl || fetch;
+    const checks = [];
+    const origin = opts.mcpUrl.replace(/\/api\/mcp\/?$/, '');
+    // 1. endpoint — server reachable, speaks JSON-RPC
+    let toolNames = [];
+    try {
+        const listed = await rpc(opts.mcpUrl, { method: 'tools/list', params: {} }, fetchImpl);
+        toolNames = (listed?.result?.tools || []).map((t) => String(t.name));
+        checks.push({
+            id: 'endpoint',
+            label: 'Sella MCP endpoint reachable',
+            ok: toolNames.length > 0,
+            detail: `${opts.mcpUrl} — ${toolNames.length} tools advertised`,
+            ...(toolNames.length === 0 ? { fix: 'The server answered but advertised no tools — check SELLA_MCP_URL points at /api/mcp.' } : {}),
+        });
+    }
+    catch (err) {
+        checks.push({
+            id: 'endpoint',
+            label: 'Sella MCP endpoint reachable',
+            ok: false,
+            detail: err instanceof Error ? err.message : 'network error',
+            fix: `Cannot reach ${opts.mcpUrl}. Check your connection/proxy (HTTPS_PROXY) or set SELLA_MCP_URL.`,
+        });
+    }
+    // 2. bootstrap — onboarding tools advertised (pairing possible from this machine)
+    if (toolNames.length) {
+        const hasBootstrap = toolNames.includes('sella_setup_claim') && toolNames.includes('sella_auth_start');
+        checks.push({
+            id: 'bootstrap',
+            label: 'Onboarding tools advertised',
+            ok: hasBootstrap,
+            detail: hasBootstrap ? 'sella_setup_claim + sella_auth_* available' : `advertised: ${toolNames.slice(0, 6).join(', ')}…`,
+            ...(hasBootstrap ? {} : { fix: 'The endpoint is not a Sella MCP server — fix SELLA_MCP_URL.' }),
+        });
+    }
+    // 3. credentials — stored key present
+    const stored = loadStoredKey(opts.env, opts.execOut);
+    checks.push({
+        id: 'credentials',
+        label: 'Stored API key',
+        ok: Boolean(stored),
+        detail: stored ? `found in ${stored.source}` : 'no key in keychain or ~/.sella/credentials.json',
+        ...(stored ? {} : { fix: 'Run `sella pair` (or `sella init`) to pair this machine.' }),
+    });
+    // 4. auth — the stored key actually authenticates a protected call
+    if (stored) {
+        try {
+            const called = await rpc(opts.mcpUrl, { method: 'tools/call', params: { name: 'list_datasets', arguments: { limit: 1 } } }, fetchImpl, stored.apiKey);
+            const isError = Boolean(called?.result?.isError) || Boolean(called?.error);
+            checks.push({
+                id: 'auth',
+                label: 'API key authenticates',
+                ok: !isError,
+                detail: isError ? 'tools/call rejected the key' : 'authenticated tools/call succeeded',
+                ...(isError ? { fix: 'The key was likely rotated or revoked (Settings → Connected agents). Re-run `sella pair`.' } : {}),
+            });
+        }
+        catch (err) {
+            checks.push({
+                id: 'auth',
+                label: 'API key authenticates',
+                ok: false,
+                detail: err instanceof Error ? err.message : 'call failed',
+                fix: 'The key was rejected (401). Re-run `sella pair` to mint a fresh one.',
+            });
+        }
+    }
+    // 5. wallets — local signing config present and parseable
+    const walletPath = path.join(opts.env.home, '.sella-wallet.json');
+    const agentWalletPath = path.join(opts.env.home, '.sella-agentwallet', 'config.json');
+    let walletOk = false;
+    let walletDetail = 'missing ~/.sella-wallet.json';
+    try {
+        JSON.parse(fs.readFileSync(walletPath, 'utf8'));
+        walletOk = true;
+        walletDetail = `${walletPath} ok${fs.existsSync(agentWalletPath) ? ' · AgentWallet config ok' : ' · AgentWallet config absent (proxy payments off — re-run `sella pair` later)'}`;
+    }
+    catch {
+        /* stays missing/corrupt */
+    }
+    checks.push({
+        id: 'wallets',
+        label: 'Wallet config files',
+        ok: walletOk,
+        detail: walletDetail,
+        ...(walletOk ? {} : { fix: 'Run `sella pair` — wallet keys are delivered once at pairing.' }),
+    });
+    // 6. quote — paid-call economics computable (price + platform fee + settleable chains)
+    try {
+        const list = await (await fetchImpl(`${origin}/api/market/catalog?limit=1`)).json();
+        const slug = list?.providers?.[0]?.id;
+        const detail = slug ? (await (await fetchImpl(`${origin}/api/market/catalog/${encodeURIComponent(slug)}`)).json()) : null;
+        const quote = detail?.quote;
+        checks.push({
+            id: 'quote',
+            label: 'x402 pay quote',
+            ok: Boolean(quote),
+            detail: quote
+                ? `${slug}: $${quote.totalUSD} total (${quote.feeBps} bps fee) on ${quote.payChains?.join('/') || 'no chains'}`
+                : 'catalog reachable but no quote returned',
+            ...(quote ? {} : { fix: 'Catalog/quote API unavailable — paid calls may still work; check the server logs.' }),
+        });
+    }
+    catch (err) {
+        checks.push({
+            id: 'quote',
+            label: 'x402 pay quote',
+            ok: false,
+            detail: err instanceof Error ? err.message : 'quote fetch failed',
+            fix: 'Could not fetch a pay quote from the catalog API — check the marketplace is up.',
+        });
+    }
+    return { ok: checks.every((c) => c.ok), checks };
+}
+/** `sella status`: who am I + AgentWallet balances when the proxy config exists. */
+export async function runStatus(opts) {
+    const stored = loadStoredKey(opts.env, opts.execOut);
+    const out = {
+        key: stored ? { present: true, source: stored.source, prefix: stored.apiKey.slice(0, 16) } : { present: false },
+    };
+    const agentWalletPath = path.join(opts.env.home, '.sella-agentwallet', 'config.json');
+    try {
+        const config = JSON.parse(fs.readFileSync(agentWalletPath, 'utf8'));
+        out.agentWallet = { username: config.username, apiBase: config.apiBase };
+        if (config.apiBase && config.username && config.apiToken) {
+            const res = await (opts.fetchImpl || fetch)(`${config.apiBase}/api/wallets/${encodeURIComponent(config.username)}`, {
+                headers: { authorization: `Bearer ${config.apiToken}` },
+            });
+            if (res.ok) {
+                const wallet = (await res.json());
+                // Annotate each wallet with what it can do today (spendable vs deposit-only) from the
+                // live registry. Best-effort: if the registry is unreachable, wallets pass through as-is.
+                const registry = await fetchChainRegistry(config.apiBase, opts.fetchImpl || fetch);
+                const wallets = Array.isArray(wallet.wallets) && registry.size > 0
+                    ? wallet.wallets.map((w) => {
+                        const spec = registry.get(String(w.chain));
+                        return spec ? { ...w, capability: chainCapability(spec) } : w;
+                    })
+                    : wallet.wallets;
+                out.agentWallet = { ...out.agentWallet, fundingStatus: wallet.fundingStatus, wallets };
+            }
+            else {
+                out.agentWallet = { ...out.agentWallet, error: `backend responded ${res.status}` };
+            }
+        }
+    }
+    catch {
+        out.agentWallet = { present: false, hint: 'Re-run `sella pair` to provision the AgentWallet.' };
+    }
+    return out;
+}

package/dist/fund.js

@@ -0,0 +1,54 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fetchChainRegistry, chainCapability } from './chains.js';
+function platformOrigin(mcpUrl) {
+    return mcpUrl.replace(/\/api\/mcp\/?$/, '') || 'https://sella.network';
+}
+export function getFundingInfo(env, mcpUrl = 'https://sella.network/api/mcp') {
+    const fundingUrl = `${platformOrigin(mcpUrl)}/dashboard/funding`;
+    const configPath = path.join(env.home, '.sella-agentwallet', 'config.json');
+    let config = null;
+    try {
+        config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+    catch {
+        config = null;
+    }
+    if (!config?.wallets) {
+        return {
+            paired: false,
+            wallets: [],
+            fundingUrl,
+            note: 'No AgentWallet on this machine yet. Run `sella pair` (or `sella init`) to provision it, then re-run `sella fund`.',
+        };
+    }
+    const wallets = Object.entries(config.wallets)
+        .filter(([, v]) => v && typeof v.address === 'string' && v.address)
+        .map(([chain, v]) => ({ chain, address: v.address }));
+    return {
+        paired: wallets.length > 0,
+        username: typeof config.username === 'string' ? config.username : undefined,
+        apiBase: typeof config.apiBase === 'string' ? config.apiBase : undefined,
+        wallets,
+        fundingUrl,
+    };
+}
+/**
+ * Best-effort annotation of each wallet with its live capability from the backend registry.
+ * When the backend is unreachable the info is returned unchanged (no `capability` field), so
+ * `sella fund` still works fully offline — it just can't say "spendable vs deposit-only".
+ */
+export async function annotateFunding(info, fetchImpl = fetch) {
+    if (!info.paired || !info.apiBase)
+        return info;
+    const registry = await fetchChainRegistry(info.apiBase, fetchImpl);
+    if (registry.size === 0)
+        return info;
+    return {
+        ...info,
+        wallets: info.wallets.map((w) => {
+            const spec = registry.get(w.chain);
+            return spec ? { ...w, capability: chainCapability(spec) } : w;
+        }),
+    };
+}