@h402/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hunt Town
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# @h402/cli
+
+[![npm](https://img.shields.io/npm/v/%40h402%2Fcli?label=%40h402%2Fcli)](https://www.npmjs.com/package/@h402/cli)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+
+Local, non-custodial CLI for [h402](../../README.md) — the x402 capability store for agents. Search compact summaries, inspect provider-native contracts, execute one concrete provider path, and pay from a local wallet only when challenged over x402. **Private keys never leave your machine.**
+
+Building an AI agent? See [`SKILL.md`](../../SKILL.md) for an agent-ready walkthrough.
+
+## Install
+
+```bash
+npm install -g @h402/cli
+```
+
+> The CLI uses [Open Wallet Standard](https://github.com/open-wallet-standard) core, whose wallet and signing methods lazy-load a platform package.
+>
+> OWS wallet creation and signing use native bindings available only on macOS and glibc-based Linux, on x64 or arm64. Windows, musl/Alpine, and other OS/architecture combinations can still run `--help`, `search`, `quote`, and free-route `call`, but cannot create, list, restore, or auto-adopt wallets, run `h402 auth`, or sign a payable call until OWS ships a matching native binding. `wallet address`, `wallet balance`, and `wallet fund` keep working for wallets already mapped in `~/.h402/config.json` — but USDC funded from an unsupported host can only be spent by signing on a supported platform. Before creating or funding a wallet, run `h402 wallet list` as a read-only native-binding preflight.
+
+## Quickstart
+
+```bash
+h402 search "web search"                              # compact wallet-free summaries
+h402 show web/search                                   # full route + provider contracts
+h402 show web/search --provider stableenrich-exa       # one full native contract
+h402 quote web/search --provider stableenrich-exa --json '{"query":"agent APIs"}'
+h402 call ai/news                                      # free; omitted provider resolves defaultProvider
+
+# Only for routes that answer with a payable 402:
+h402 wallet list                                     # read-only native-binding preflight; [] is OK
+h402 wallet create --name agent                      # local signing wallet
+h402 wallet fund --name agent                        # Base USDC address + instructions
+h402 call web/search --provider stableenrich-exa --name agent --json '{"query":"agent APIs"}'
+```
+
+Browsing, quoting, and free-route calls do not require a local wallet. Wallet creation creates a local signing wallet only; `h402 auth` creates the optional bonus-credit session. A funded local wallet is required only if the first response is a payable `402`.
+
+Calls hit the production backend (`https://h402.hunt.town`) by default — override with `--api-url` or `H402_API_URL` (e.g. `http://localhost:3000` for local dev).
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `h402 wallet create --name <n>` | Create a local OWS signing wallet (does not create an auth session; prints its address) |
+| `h402 wallet list` | List OWS wallets |
+| `h402 wallet restore` | Re-adopt OWS wallets into `~/.h402/config.json` |
+| `h402 wallet address --name <n>` | Print the wallet address |
+| `h402 wallet balance --name <n>` | Show the wallet's structured Base USDC balance |
+| `h402 wallet fund --name <n>` | Print the Base USDC deposit address and funding instructions |
+| `h402 auth --name <n>` | Create an optional backend bonus-credit session with a wallet signature |
+| `h402 credits` | Show the bonus-credit balance for the signed-in session |
+| `h402 search <query>` | Search compact route/provider summaries |
+| `h402 show <category/action> [--provider <name>]` | Fetch full route or one provider-native contract |
+| `h402 quote <category/action>` | Preview the x402 `PAYMENT-REQUIRED` envelope without paying |
+| `h402 call <category/action>` | Execute a route and pay if challenged; free routes need no wallet |
+
+Run `h402 --help`, `h402 <command> --help`, or `h402 wallet <subcommand> --help` for usage and flags, and `h402 --version` for the version. Unknown flags and unknown commands fail with a non-zero exit.
+
+## Flags
+
+| Flag | Applies to | Description |
+| --- | --- | --- |
+| `--name <wallet>` | wallet create/address/balance/fund; auth; call | Wallet to use (default `h402`) |
+| `--wallet 0x...` | wallet address/balance/fund; auth; call | Sign with the local wallet that owns this address (must exist locally; must agree with `--name` if both are passed) |
+| `--api-url <url>` | auth, credits, search, show, quote, call | Backend base URL override (or `H402_API_URL`; default `https://h402.hunt.town`) |
+| `--json '{...}'` | quote, call | Request body (sets method to POST) |
+| `--query '{...}'` | quote, call | URL query params (GET); values must be strings/numbers/booleans |
+| `--provider <name>` | show, quote, call | Select a concrete provider; quote/call omission resolves the catalog default, while show omission lists all enabled providers |
+| `--method GET\|POST` | quote, call | Override the method (inferred from `--json` otherwise) |
+| `--passphrase [<s>]` | wallet create, auth, call | Passphrase for a passphrase-protected wallet; omit the value to be prompted (or `H402_WALLET_PASSPHRASE`) |
+| `--no-passphrase` | wallet create, auth, call | Force passphrase-less signing even if `H402_WALLET_PASSPHRASE` is set (the default needs no flag) |
+| `--no-credit` | call | Ignore bonus credits and pay x402 only |
+| `--max-usd <usd>` | call | Optional client-side cap; refuse to sign if the quoted Base USDC amount exceeds it |
+| `--idempotency-key <uuid>` | call | Stable key for safe retries (default: random) |
+| `--limit <n>` | search | Max results (default `20`) |
+
+Route ids are `category/action`, e.g. `web/search`, `maps/place-details`, `finance/stock-quote`. `--query` takes one scalar value per key (string, number, or boolean); pass arrays, nested objects, or request bodies with `--json` instead.
+
+## How a call works
+
+Each call uses one concrete provider. Without `--provider`, the CLI resolves the route's current `defaultProvider` from `/api/catalog/routes/<route>` before any execution request; explicit `--provider` goes straight to that pinned path. Successes include `h402.cliProviderSelection`, and post-resolution failures include the same metadata at `error.detail.h402.cliProviderSelection`. Its `pinnedCommand` is a shell-escaped fresh-call recipe that preserves non-secret request, backend, wallet, and payment-safety flags and omits passphrases and the previous idempotency key. A `410` response is never retried automatically — inspect `error.detail.error.candidates` with `h402 show`, then start a new explicit call. Unknown routes preserve the server's `error.detail.error.recovery.command` search guidance.
+
+```
+h402 call web/search --json '{"query":"..."}'
+   │
+   ├─ resolve defaultProvider from full route detail
+   ├─ request /routes/<provider>/web/search (before wallet resolution)
+   ├─ 2xx → returned directly; h402.paidBy says free or credit
+   └─ payable 402 → resolve wallet, sign Base USDC locally, then retry that same pinned request
+```
+
+If a route returns a payable 402, you're charged the exact per-call price (most paid
+routes are $0.001–$0.05). An initial 2xx is returned directly — `h402.paidBy` says whether it was `free` (no charge) or covered by bonus `credit` from an authenticated session. Run `h402 quote`
+first to see a payable route's price without paying. Pass `--max-usd <amount>` on
+`call` (or store a string `maxUsd`, such as `"0.05"`, in `~/.h402/config.json`)
+to refuse signing a challenge above that USDC cap. Paid call output includes `h402.signedAmount` so agents
+can record the amount they signed. The CLI uses the first 402 response's `Date` header
+when building the EIP-3009 validity window, reducing client clock-skew failures on paid
+calls. If you've run `h402 auth`, bonus credits are drawn before USDC unless you pass
+`--no-credit`.
+
+`--idempotency-key` is double-charge protection, not result replay. If the server reports
+`payment_settlement_pending`, the running CLI resends the exact `PAYMENT-SIGNATURE`, key,
+method, path, provider, and body for bounded reconciliation attempts. One CLI invocation
+creates at most one payment authorization: server-issued replacement challenges are
+refused, and a separate explicit call is required to create a new payment. The CLI does
+not persist payment signatures, so after the process exits it cannot reconstruct the
+original signed request. Pending, reconciled, network, and gateway errors after a signed
+send warn that settlement may still have occurred; only a matching
+`payment_settlement_failed` response with `paid: false` and `safeToStartNewCall: true`
+confirms that the original authorization was not paid.
+
+## Agents & automation
+
+Every command prints JSON to stdout — `search`, `show`, `quote`, `call`, `auth`, `credits`, and `wallet create`/`list`/`restore`/`address`/`balance`/`fund`.
+
+A successful `call` is wrapped as `{ "data": <provider-native body>, "meta"?: <reserved envelope metadata>, "h402": <execution metadata> }` — `data` remains provider-native, optional `meta` remains reserved envelope metadata rather than normalized provider output, and `h402` includes the provider-pinned execution receipt plus CLI-added `cliProviderSelection`. `ledgerEntryId` is present for credit or x402-paid calls; `paymentTransaction` and CLI-added `signedAmount` are x402-payment-only fields; free calls omit all three. Optional `h402.followUp` describes async work. A failed call exits non-zero and writes `{ "error": { "message", "detail"? } }` to stderr; `detail` preserves the backend recovery body unchanged.
+
+Async routes may return a job receipt instead of the final result. Async parent route IDs end in `-async`; a single-parent follow-up is `<parent-route>-status`, while shared multi-parent follow-ups may use a shared `*-status` name. When `h402.followUp` is present, pass its provider-native `params` object according to `method` and preserve the provider segment from `path`. Match `followUp.method` — GET params go via `--query`, POST bodies via `--json`; the CLI rejects `--query` on a POST (`<followUp.params>` means its JSON-encoded object):
+
+```bash
+# followUp.method GET (most status polls):
+h402 call <followUp.routeId> \
+  --provider <provider-from-followUp.path> \
+  --query '<followUp.params>'
+
+# followUp.method POST (e.g. ai/music-generate-async-status):
+h402 call <followUp.routeId> \
+  --provider <provider-from-followUp.path> \
+  --json '<followUp.params>'
+```
+
+`h402 search` intentionally returns compact summaries. Fetch full schemas, request examples, and provider-native samples with `h402 show <route>` before pinning.
+
+```bash
+h402 search "token holders"                        # compact JSON to stdout
+h402 show crypto/token-holders --provider nansen     # full native schema/sample
+h402 call crypto/token-holders --provider nansen --name agent \
+  --json '{"chain":"ethereum","token_address":"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"}' # JSON result, non-zero exit on failure
+```
+
+Signing needs no flags for the default passphrase-less wallets. Only when a wallet was created with an opt-in passphrase, `export H402_WALLET_PASSPHRASE=...` (or pass `--passphrase <s>`) — the CLI tells you exactly this when it hits such a wallet non-interactively.
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `H402_API_URL` | Backend base URL override (or `--api-url`; default `https://h402.hunt.town`) |
+| `H402_WALLET_PASSPHRASE` | Passphrase for passphrase-protected wallets (only needed when the wallet was created with one) |
+
+Passphrases are never stored. Wallets are passphrase-less by default; opt in at create time (`--passphrase <s>`, or bare `--passphrase` to be prompted) when a wallet guards meaningful funds. The CLI persists only the backend URL, session tokens, and known wallet addresses in `~/.h402/config.json`.
+
+## Contributing
+
+```bash
+npm install
+npm run -w @h402/core build
+npm run -w @h402/cli typecheck
+npm run -w @h402/cli lint
+npm run -w @h402/cli test
+```
+
+## License
+
+MIT

package/dist/api.js

@@ -0,0 +1,134 @@
+import { Agent } from "undici";
+import { CliError } from "./errors.js";
+import { getVersion } from "./help.js";
+import { isRecord } from "./utils.js";
+export const H402_HTTP_TIMEOUT_MS = 450_000;
+const h402FetchDispatcher = new Agent({
+    headersTimeout: H402_HTTP_TIMEOUT_MS,
+    bodyTimeout: H402_HTTP_TIMEOUT_MS
+});
+function networkErrorMessage(error) {
+    const cause = isRecord(error) ? error.cause : undefined;
+    if (isRecord(cause)) {
+        const code = cause.code;
+        if (typeof code === "string" && code) {
+            return code;
+        }
+        const message = cause.message;
+        if (typeof message === "string" && message) {
+            return message;
+        }
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+export async function requestJson(backendUrl, path, init = {}) {
+    const headers = new Headers(init.headers);
+    headers.set("accept", "application/json");
+    if (!headers.has("user-agent")) {
+        headers.set("user-agent", `h402-cli/${getVersion()}`);
+    }
+    if (init.body && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+    }
+    if (init.token) {
+        headers.set("authorization", `Bearer ${init.token}`);
+    }
+    const fetchInit = { ...init };
+    delete fetchInit.token;
+    const url = `${backendUrl}${path}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            ...fetchInit,
+            headers,
+            dispatcher: h402FetchDispatcher
+        });
+    }
+    catch (error) {
+        throw new CliError(`Request to ${url} failed: ${networkErrorMessage(error)}`, { backendUrl, url });
+    }
+    const text = await response.text();
+    let body;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        // A non-JSON body (an HTML 502 page, a plain-text gateway error) must not crash the
+        // parse — keep the raw text so assertOk can surface it instead of throwing here.
+        body = text;
+    }
+    return { backendUrl, url, status: response.status, statusText: response.statusText, body, headers: response.headers };
+}
+function responseContext(response) {
+    return { backendUrl: response.backendUrl, url: response.url };
+}
+function responseErrorDetail(response) {
+    const context = responseContext(response);
+    const { body } = response;
+    if (isRecord(body)) {
+        return { ...body, ...context };
+    }
+    return context;
+}
+// Pull a human-readable message out of a backend error body — covering the common
+// { error: { message } }, { error: "..." }, and { message } shapes — so the stderr
+// envelope's `message` is useful even before a caller inspects `detail`.
+function backendMessage(body) {
+    if (!isRecord(body)) {
+        return undefined;
+    }
+    const error = body.error;
+    if (typeof error === "string") {
+        return error;
+    }
+    if (isRecord(error) && typeof error.message === "string") {
+        return error.message;
+    }
+    return typeof body.message === "string" ? body.message : undefined;
+}
+export function backendErrorCode(body) {
+    if (!isRecord(body)) {
+        return undefined;
+    }
+    const error = body.error;
+    if (isRecord(error) && typeof error.code === "string") {
+        return error.code;
+    }
+    return typeof body.code === "string" ? body.code : undefined;
+}
+const MONEY_SENSITIVE_IDEMPOTENCY_CODES = new Set([
+    "idempotency_key_already_used",
+    "idempotency_key_in_progress",
+    "idempotency_key_conflict",
+    "payment_settlement_pending",
+    "payment_settlement_reconciled"
+]);
+export const IDEMPOTENCY_MONEY_GUIDANCE = "The earlier request for this idempotency key may already be completed, charged, or still settling; do NOT sign or pay with a new idempotency key unless you intentionally accept a second charge.";
+function idempotencyGuidance(body) {
+    const code = backendErrorCode(body);
+    if (!code || !MONEY_SENSITIVE_IDEMPOTENCY_CODES.has(code)) {
+        return undefined;
+    }
+    return IDEMPOTENCY_MONEY_GUIDANCE;
+}
+export function assertOk(response) {
+    if (response.status < 200 || response.status >= 300) {
+        const { body } = response;
+        const statusLine = `${response.status}${response.statusText ? ` ${response.statusText}` : ""}`;
+        // Empty body (a framework 405, an infra 502/504): status only — never the literal "null".
+        if (body === null || body === undefined || body === "") {
+            throw new CliError(`Request failed: ${statusLine}`, responseContext(response));
+        }
+        // Non-JSON string body (an HTML 502 page, a plain-text gateway error): show it verbatim.
+        if (typeof body === "string") {
+            throw new CliError(`Request failed: ${statusLine}: ${body}`, responseContext(response));
+        }
+        // Structured JSON error: summarize its message, and carry the full body as `detail`
+        // so the stderr error envelope stays machine-readable.
+        const message = backendMessage(body);
+        const guidance = idempotencyGuidance(body);
+        const summary = message ? `Request failed: ${statusLine}: ${message}` : `Request failed: ${statusLine}`;
+        throw new CliError(guidance ? `${summary}. ${guidance}` : summary, responseErrorDetail(response));
+    }
+    return response.body;
+}

package/dist/base-usdc-balance.js

@@ -0,0 +1,161 @@
+import { BASE_CHAIN_ID, BASE_USDC_ADDRESS, USDC_DECIMALS } from "@h402/core";
+export const BASE_RPC_URLS = [
+    "https://base-rpc.publicnode.com",
+    "https://base.drpc.org",
+    "https://mainnet.base.org",
+    "https://1rpc.io/base"
+];
+const BALANCE_OF_SELECTOR = "70a08231";
+const RPC_TIMEOUT_MS = 5_000;
+const EVM_ADDRESS = /^0[xX][0-9a-fA-F]{40}$/;
+export const BASE_USDC_BALANCE_NETWORK = {
+    name: "base",
+    chainId: BASE_CHAIN_ID
+};
+export const BASE_USDC_BALANCE_ASSET = {
+    symbol: "USDC",
+    address: BASE_USDC_ADDRESS,
+    decimals: USDC_DECIMALS
+};
+function normalizeAddress(address) {
+    if (!EVM_ADDRESS.test(address)) {
+        throw new Error(`Invalid EVM address: ${address}`);
+    }
+    return address.toLowerCase();
+}
+export function balanceOfCalldata(address) {
+    const normalized = normalizeAddress(address);
+    return `0x${BALANCE_OF_SELECTOR}${normalized.slice(2).padStart(64, "0")}`;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function jsonRpcErrorMessage(error) {
+    if (!error || typeof error !== "object") {
+        return String(error);
+    }
+    const record = error;
+    const code = typeof record.code === "number" || typeof record.code === "string" ? `${record.code}: ` : "";
+    const message = typeof record.message === "string" ? record.message : JSON.stringify(error);
+    return `${code}${message}`;
+}
+function parseRpcBalance(body) {
+    if (!body || typeof body !== "object") {
+        throw new Error("RPC returned a non-object response");
+    }
+    const response = body;
+    if (response.error !== undefined) {
+        throw new Error(`RPC error: ${jsonRpcErrorMessage(response.error)}`);
+    }
+    if (typeof response.result !== "string" || !/^0x[0-9a-fA-F]*$/.test(response.result)) {
+        throw new Error("RPC returned an invalid balance result");
+    }
+    return BigInt(response.result === "0x" ? "0x0" : response.result);
+}
+async function rpcBalance(url, calldata, fetchFn, signal) {
+    const response = await fetchFn(url, {
+        method: "POST",
+        headers: {
+            accept: "application/json",
+            "content-type": "application/json"
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "eth_call",
+            params: [
+                {
+                    to: BASE_USDC_ADDRESS,
+                    data: calldata
+                },
+                "latest"
+            ]
+        }),
+        signal
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ""}${text ? `: ${text}` : ""}`);
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new Error("RPC returned non-JSON response");
+    }
+    return parseRpcBalance(body);
+}
+function quorumUnavailableError() {
+    return new Error("Base USDC balance is temporarily unavailable: RPC quorum failed; need two matching Base RPC responses.");
+}
+function firstMatchingQuorum(calls, rpcUrls) {
+    return new Promise((resolve, reject) => {
+        let settled = 0;
+        let finished = false;
+        const values = new Map();
+        for (const call of calls) {
+            call
+                .then((value) => {
+                if (finished)
+                    return;
+                settled += 1;
+                const key = value.toString();
+                const entry = values.get(key) ?? { value, count: 0 };
+                entry.count += 1;
+                values.set(key, entry);
+                if (entry.count >= 2) {
+                    finished = true;
+                    resolve(entry.value);
+                    return;
+                }
+                if (settled === rpcUrls.length) {
+                    finished = true;
+                    reject(quorumUnavailableError());
+                }
+            })
+                .catch(() => {
+                if (finished)
+                    return;
+                settled += 1;
+                if (settled === rpcUrls.length) {
+                    finished = true;
+                    reject(quorumUnavailableError());
+                }
+            });
+        }
+    });
+}
+function formatUsdc(microUsdc) {
+    const scale = 10n ** BigInt(USDC_DECIMALS);
+    const whole = microUsdc / scale;
+    const fraction = (microUsdc % scale).toString().padStart(USDC_DECIMALS, "0");
+    return `${whole}.${fraction}`;
+}
+export async function getBaseUsdcBalance(address, options = {}) {
+    const rpcUrls = options.rpcUrls ?? BASE_RPC_URLS;
+    if (rpcUrls.length < 2) {
+        throw new Error("At least two Base RPC URLs are required for quorum.");
+    }
+    const fetchFn = options.fetchFn ?? fetch;
+    const calldata = balanceOfCalldata(address);
+    const timeoutMs = options.timeoutMs ?? RPC_TIMEOUT_MS;
+    const controllers = rpcUrls.map(() => new AbortController());
+    const timers = controllers.map((controller) => setTimeout(() => controller.abort(), timeoutMs));
+    const calls = rpcUrls.map((url, index) => rpcBalance(url, calldata, fetchFn, controllers[index].signal).catch((error) => {
+        throw new Error(`${url}: ${errorMessage(error)}`);
+    }));
+    try {
+        const microUsdc = await firstMatchingQuorum(calls, rpcUrls);
+        return {
+            microUsdc: microUsdc.toString(),
+            usdc: formatUsdc(microUsdc)
+        };
+    }
+    finally {
+        for (const timer of timers)
+            clearTimeout(timer);
+        for (const controller of controllers)
+            controller.abort();
+    }
+}

package/dist/catalog.js

@@ -0,0 +1,144 @@
+import { assertOk, requestJson } from "./api.js";
+import { CliError } from "./errors.js";
+import { assertConcreteProvider, encodeRouteId, isRecord, mergeH402 } from "./utils.js";
+const PINNED_COMMAND_FLAGS = {
+    call: ["api-url", "json", "query", "method", "name", "wallet", "no-passphrase", "no-credit", "max-usd"],
+    quote: ["api-url", "json", "query", "method"],
+    show: ["api-url"]
+};
+const BOOLEAN_PINNED_COMMAND_FLAGS = new Set(["no-passphrase", "no-credit"]);
+function shellArg(value) {
+    return /^[A-Za-z0-9_./:@+-]+$/.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function pinnedCommand(command, routeId, provider, flags) {
+    const parts = ["h402", command, shellArg(routeId), "--provider", shellArg(provider)];
+    for (const name of PINNED_COMMAND_FLAGS[command]) {
+        const value = flags[name];
+        if (value === undefined)
+            continue;
+        if (BOOLEAN_PINNED_COMMAND_FLAGS.has(name)) {
+            if (value === true || value === "true")
+                parts.push(`--${name}`);
+            continue;
+        }
+        if (typeof value === "string")
+            parts.push(`--${name}`, shellArg(value));
+    }
+    return parts.join(" ");
+}
+function selection(command, routeId, provider, source, flags) {
+    return {
+        source,
+        provider,
+        pinnedCommand: pinnedCommand(command, routeId, provider, flags)
+    };
+}
+function recoveryCandidates(route) {
+    const encodedRoute = encodeRouteId(route.id);
+    return route.candidates.map((candidate) => ({
+        provider: candidate.provider,
+        ...(typeof candidate.candidateKey === "string" ? { candidateKey: candidate.candidateKey } : {}),
+        ...(typeof candidate.status === "string" ? { status: candidate.status } : {}),
+        path: `/routes/${encodeURIComponent(candidate.provider)}/${encodedRoute}`
+    }));
+}
+function invalidCatalogResponse(routeId, message, detail) {
+    throw new CliError(`Catalog detail for ${routeId} is invalid: ${message}`, {
+        error: { code: "invalid_catalog_response", message },
+        routeId,
+        ...(detail === undefined ? {} : { detail })
+    });
+}
+function parseCatalogRoute(routeId, body) {
+    if (!isRecord(body) || !isRecord(body.route)) {
+        return invalidCatalogResponse(routeId, "expected a route object");
+    }
+    const route = body.route;
+    if (typeof route.id !== "string" || route.id !== routeId) {
+        return invalidCatalogResponse(routeId, "id does not match the requested route", { id: route.id });
+    }
+    if (typeof route.defaultProvider !== "string" || !route.defaultProvider) {
+        return invalidCatalogResponse(routeId, "defaultProvider is missing");
+    }
+    try {
+        assertConcreteProvider(route.defaultProvider);
+    }
+    catch (error) {
+        return invalidCatalogResponse(routeId, "defaultProvider is not a concrete provider slug", {
+            defaultProvider: route.defaultProvider,
+            reason: error instanceof Error ? error.message : String(error)
+        });
+    }
+    if (!Array.isArray(route.candidates) || route.candidates.length === 0) {
+        return invalidCatalogResponse(routeId, "enabled candidates are missing");
+    }
+    const candidates = route.candidates.map((candidate, index) => {
+        if (!isRecord(candidate) || typeof candidate.provider !== "string" || !candidate.provider) {
+            return invalidCatalogResponse(routeId, `candidate ${index} lacks provider`);
+        }
+        try {
+            assertConcreteProvider(candidate.provider);
+        }
+        catch (error) {
+            return invalidCatalogResponse(routeId, `candidate ${index} has an invalid provider slug`, {
+                provider: candidate.provider,
+                reason: error instanceof Error ? error.message : String(error)
+            });
+        }
+        return candidate;
+    });
+    if (!candidates.some((candidate) => candidate.provider === route.defaultProvider && candidate.status === "enabled")) {
+        return invalidCatalogResponse(routeId, "defaultProvider is not an enabled candidate", {
+            defaultProvider: route.defaultProvider,
+            candidates: recoveryCandidates({ ...route, candidates })
+        });
+    }
+    return { ...route, candidates };
+}
+export async function fetchCatalogRoute(apiUrl, routeId) {
+    const body = assertOk(await requestJson(apiUrl, `/api/catalog/routes/${encodeRouteId(routeId)}`));
+    return { route: parseCatalogRoute(routeId, body) };
+}
+export async function resolveProvider(apiUrl, routeId, explicitProvider, command, flags, effectiveMaxUsd) {
+    const effectiveFlags = {
+        ...flags,
+        "api-url": apiUrl,
+        ...(effectiveMaxUsd === undefined ? {} : { "max-usd": effectiveMaxUsd })
+    };
+    if (explicitProvider !== undefined) {
+        return selection(command, routeId, assertConcreteProvider(explicitProvider), "explicit", effectiveFlags);
+    }
+    const { route } = await fetchCatalogRoute(apiUrl, routeId);
+    return selection(command, routeId, route.defaultProvider, "catalog-default", effectiveFlags);
+}
+export function selectCatalogCandidate(route, provider) {
+    const candidate = route.candidates.find((item) => item.provider === provider);
+    if (candidate) {
+        return candidate;
+    }
+    const message = `Provider "${provider}" is not enabled for ${route.id}.`;
+    throw new CliError(message, {
+        error: {
+            code: "provider_unavailable",
+            message,
+            routeId: route.id,
+            requestedProvider: provider,
+            defaultProvider: route.defaultProvider,
+            candidates: recoveryCandidates(route)
+        }
+    });
+}
+export function explicitShowSelection(apiUrl, routeId, provider, flags) {
+    return selection("show", routeId, provider, "explicit", { ...flags, "api-url": apiUrl });
+}
+export function withProviderSelection(body, providerSelection) {
+    return mergeH402(body, { cliProviderSelection: providerSelection });
+}
+export function withProviderSelectionError(error, providerSelection) {
+    const existingDetail = error instanceof CliError && isRecord(error.detail) ? error.detail : {};
+    const h402 = isRecord(existingDetail.h402) ? existingDetail.h402 : {};
+    return new CliError(error instanceof Error ? error.message : String(error), {
+        ...existingDetail,
+        h402: { ...h402, cliProviderSelection: providerSelection }
+    });
+}