@h402/cli 0.1.0

package/dist/config-lock.js

@@ -0,0 +1,241 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { isRecord } from "./utils.js";
+const CONFIG_LOCK_OWNER_FILE = "owner.json";
+const CONFIG_LOCK_GUARD_FILE = ".config.lock.guard";
+const CONFIG_LOCK_WAIT_ATTEMPTS = 200;
+const CONFIG_LOCK_WAIT_MS = 25;
+let nativeLockLoadPromise;
+function errorDescription(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error?.code;
+    return code ? `${code}: ${message}` : message;
+}
+async function loadNativeLockApi() {
+    nativeLockLoadPromise ??= import("fs-native-extensions")
+        .then(({ tryLock, unlock }) => ({ api: { tryLock, unlock } }))
+        .catch((error) => ({ reason: errorDescription(error) }));
+    return nativeLockLoadPromise;
+}
+async function tryAcquireReclamationGuard(dir) {
+    const loaded = await loadNativeLockApi();
+    if (!loaded.api) {
+        return { reason: `config-lock reclamation guard is unavailable (${loaded.reason ?? "native file locking could not be loaded"})` };
+    }
+    const guardPath = path.join(dir, CONFIG_LOCK_GUARD_FILE);
+    let handle;
+    try {
+        handle = await open(guardPath, "a+", 0o600);
+        await chmod(guardPath, 0o600).catch(() => undefined);
+    }
+    catch (error) {
+        return { reason: `config-lock reclamation guard could not be opened (${errorDescription(error)})` };
+    }
+    let acquired = false;
+    try {
+        try {
+            acquired = loaded.api.tryLock(handle.fd);
+        }
+        catch (error) {
+            return { reason: `config-lock reclamation guard failed (${errorDescription(error)})` };
+        }
+        if (!acquired)
+            return {};
+        let released = false;
+        return {
+            release: async () => {
+                if (released)
+                    return;
+                released = true;
+                try {
+                    loaded.api?.unlock(handle.fd);
+                }
+                catch {
+                    // Closing the descriptor releases the kernel lock even if explicit
+                    // unlock is unsupported or fails at runtime.
+                }
+                finally {
+                    await handle.close().catch(() => undefined);
+                }
+            }
+        };
+    }
+    finally {
+        if (!acquired)
+            await handle.close().catch(() => undefined);
+    }
+}
+function isConfigLockOwner(value) {
+    if (!isRecord(value))
+        return false;
+    const owner = value;
+    return (owner.version === 3 &&
+        Number.isSafeInteger(owner.pid) &&
+        owner.pid > 0 &&
+        typeof owner.hostname === "string" &&
+        owner.hostname.length > 0 &&
+        typeof owner.createdAt === "string" &&
+        Number.isFinite(Date.parse(owner.createdAt)) &&
+        typeof owner.token === "string" &&
+        owner.token.length > 0);
+}
+async function readConfigLockOwner(lockDir) {
+    let raw;
+    try {
+        raw = await readFile(path.join(lockDir, CONFIG_LOCK_OWNER_FILE), "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return undefined;
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return isConfigLockOwner(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Signal-0 liveness: ESRCH proves no process with that PID exists now, so a
+// same-host owner reporting ESRCH is definitively dead. A PID that was reused
+// by another process reads as alive — that only degrades to the conservative
+// manual-recovery path, never to deleting a live owner's lock. (A sibling
+// container sharing this config dir AND this hostname across PID namespaces is
+// outside this envelope; hostname is the machine boundary here.)
+function ownerProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return false;
+        if (code === "EPERM")
+            return true;
+        return undefined;
+    }
+}
+async function inspectConfigLock(lockDir) {
+    try {
+        const owner = await readConfigLockOwner(lockDir);
+        if (!owner) {
+            const lockStat = await stat(lockDir);
+            const ageMs = Math.max(0, Date.now() - lockStat.mtimeMs);
+            return {
+                reclaimable: false,
+                reason: `lock has no valid owner metadata; automatic reclamation is unsafe (${Math.round(ageMs)}ms old)`
+            };
+        }
+        if (owner.hostname !== os.hostname()) {
+            return { token: owner.token, reclaimable: false, reason: `owner PID ${owner.pid} on ${owner.hostname} cannot be verified from this host` };
+        }
+        const alive = ownerProcessAlive(owner.pid);
+        if (alive === false) {
+            return { token: owner.token, reclaimable: true, reason: `owner PID ${owner.pid} no longer exists` };
+        }
+        if (alive === true) {
+            return { token: owner.token, reclaimable: false, reason: `live PID ${owner.pid} on ${owner.hostname} since ${owner.createdAt}` };
+        }
+        return { token: owner.token, reclaimable: false, reason: `owner PID ${owner.pid} could not be verified` };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { reclaimable: false, reason: "lock disappeared while being inspected" };
+        return { reclaimable: false, reason: `lock ownership could not be inspected: ${error.message}` };
+    }
+}
+// Reclamation is serialized by a crash-released kernel advisory lock. A stale
+// observer must re-read the canonical owner while holding the guard; it never
+// moves an unverified successor out of the coordination path.
+async function reclaimConfigLockIfUnchanged(lockDir, observed) {
+    if (!observed.reclaimable || !observed.token)
+        return { reclaimed: false };
+    const guard = await tryAcquireReclamationGuard(path.dirname(lockDir));
+    if (!guard.release)
+        return { reclaimed: false, blockedReason: guard.reason };
+    try {
+        const current = await inspectConfigLock(lockDir);
+        if (!current.reclaimable || current.token !== observed.token)
+            return { reclaimed: false };
+        try {
+            await rm(lockDir, { recursive: true });
+            return { reclaimed: true };
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { reclaimed: false };
+            throw error;
+        }
+    }
+    finally {
+        await guard.release();
+    }
+}
+function lockTimeoutError(lockDir, observation) {
+    return new Error(`Timed out waiting for h402 config lock at ${lockDir} (${observation.reason}). ` +
+        `If no h402 process is writing config, remove this lock path and retry; do not remove it while its owner is active.`);
+}
+export async function acquireConfigLock(dir) {
+    const lockDir = path.join(dir, ".config.lock");
+    const token = randomUUID();
+    let lastObservation = { reclaimable: false, reason: "lock is contended" };
+    let waitedAttempts = 0;
+    while (waitedAttempts < CONFIG_LOCK_WAIT_ATTEMPTS) {
+        try {
+            await mkdir(lockDir, { mode: 0o700 });
+            const owner = {
+                version: 3,
+                pid: process.pid,
+                hostname: os.hostname(),
+                createdAt: new Date().toISOString(),
+                token
+            };
+            try {
+                await writeFile(path.join(lockDir, CONFIG_LOCK_OWNER_FILE), JSON.stringify(owner), { mode: 0o600, flag: "wx" });
+            }
+            catch (error) {
+                await rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
+                throw error;
+            }
+            return async () => {
+                const currentOwner = await readConfigLockOwner(lockDir);
+                if (!currentOwner) {
+                    throw new Error(`Refusing to release h402 config lock at ${lockDir}: owner metadata is missing or invalid.`);
+                }
+                if (currentOwner.token !== token) {
+                    throw new Error(`Refusing to release h402 config lock at ${lockDir}: ownership changed to PID ${currentOwner.pid} on ${currentOwner.hostname}.`);
+                }
+                await rm(lockDir, { recursive: true, force: true });
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+            lastObservation = await inspectConfigLock(lockDir);
+            const reclamation = await reclaimConfigLockIfUnchanged(lockDir, lastObservation);
+            if (reclamation.reclaimed) {
+                // Reclamation is not a wait attempt; retry mkdir even at the deadline.
+                continue;
+            }
+            if (reclamation.blockedReason) {
+                lastObservation = {
+                    ...lastObservation,
+                    reclaimable: false,
+                    reason: `${lastObservation.reason}; ${reclamation.blockedReason}`
+                };
+            }
+            waitedAttempts += 1;
+            if (waitedAttempts < CONFIG_LOCK_WAIT_ATTEMPTS) {
+                await delay(CONFIG_LOCK_WAIT_MS);
+            }
+        }
+    }
+    throw lockTimeoutError(lockDir, lastObservation);
+}

package/dist/config.js

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { acquireConfigLock } from "./config-lock.js";
+import { isRecord } from "./utils.js";
+// @h402/cli is an end-user tool: default to the production backend. Override
+// with --api-url or H402_API_URL (e.g. http://localhost:3000 for local dev).
+const DEFAULT_BACKEND_URL = "https://h402.hunt.town";
+function configPath() {
+    return path.join(os.homedir(), ".h402", "config.json");
+}
+function defaultConfig() {
+    return { backendUrl: DEFAULT_BACKEND_URL, sessions: {}, wallets: {} };
+}
+function normalizeConfig(parsed) {
+    const defaults = defaultConfig();
+    const normalized = {
+        backendUrl: typeof parsed.backendUrl === "string" ? parsed.backendUrl : defaults.backendUrl,
+        sessions: isRecord(parsed.sessions) ? parsed.sessions : {},
+        wallets: isRecord(parsed.wallets) ? parsed.wallets : {}
+    };
+    if (typeof parsed.maxUsd === "string") {
+        normalized.maxUsd = parsed.maxUsd;
+    }
+    return normalized;
+}
+async function tightenConfigPermissions(file) {
+    await Promise.all([chmod(path.dirname(file), 0o700).catch(() => undefined), chmod(file, 0o600).catch(() => undefined)]);
+}
+async function readConfigFile(file) {
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+        await tightenConfigPermissions(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw new Error(`Could not read h402 config at ${file}: ${error.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        parsed = undefined;
+    }
+    // Surface malformed config instead of overwriting it and losing the session
+    // tokens and wallet mappings it holds.
+    if (!isRecord(parsed)) {
+        throw new Error(`h402 config at ${file} is not a valid config object. Fix or remove it (it holds your session tokens and known wallets).`);
+    }
+    // Normalize to the CliConfig shape so a sparse or partial file (e.g. `{}` or a
+    // missing/mistyped sessions/wallets key) yields a usable config instead of
+    // crashing later when a command reads config.sessions / config.wallets.
+    return normalizeConfig(parsed);
+}
+export async function loadConfig() {
+    return (await readConfigFile(configPath())) ?? defaultConfig();
+}
+function cloneConfig(config) {
+    const cloned = {
+        backendUrl: config.backendUrl,
+        sessions: { ...config.sessions },
+        wallets: Object.fromEntries(Object.entries(config.wallets).map(([name, wallet]) => [name, { ...wallet }]))
+    };
+    if (config.maxUsd !== undefined) {
+        cloned.maxUsd = config.maxUsd;
+    }
+    return cloned;
+}
+async function atomicWritePrivateJson(file, config) {
+    const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify(config, null, 2), { mode: 0o600, flag: "wx" });
+        await chmod(tmp, 0o600).catch(() => undefined);
+        await rename(tmp, file);
+    }
+    catch (error) {
+        await rm(tmp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+export async function updateConfig(update) {
+    const file = configPath();
+    const dir = path.dirname(file);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const releaseLock = await acquireConfigLock(dir);
+    let next;
+    try {
+        const current = (await readConfigFile(file)) ?? defaultConfig();
+        const draft = cloneConfig(current);
+        next = (await update(draft)) ?? draft;
+        await atomicWritePrivateJson(file, next);
+    }
+    finally {
+        await releaseLock();
+    }
+    await tightenConfigPermissions(file);
+    return next;
+}
+export function backendUrl(config, apiUrlFlag) {
+    return (apiUrlFlag ?? process.env.H402_API_URL ?? config.backendUrl ?? DEFAULT_BACKEND_URL).replace(/\/$/, "");
+}

package/dist/errors.js

@@ -0,0 +1,20 @@
+// A CLI error that can carry structured `detail` (e.g. the backend's parsed JSON error
+// body) so the top-level handler can surface it in the machine-readable stderr envelope.
+export class CliError extends Error {
+    detail;
+    constructor(message, detail) {
+        super(message);
+        this.name = "CliError";
+        this.detail = detail;
+    }
+}
+// Every failure exits non-zero and writes this single shape to stderr as JSON, so an
+// agent can parse one envelope for all error paths (validation, backend, empty-body,
+// non-JSON): `message` is always a human-readable diagnostic; `detail` is present only
+// when there is a structured backend error body to expose.
+export function errorEnvelope(error) {
+    if (error instanceof CliError && error.detail !== undefined) {
+        return { error: { message: error.message, detail: error.detail } };
+    }
+    return { error: { message: error instanceof Error ? error.message : String(error) } };
+}

package/dist/help.js

@@ -0,0 +1,221 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// Reusable flag definitions (DRY: declared once, referenced by each command that
+// accepts them — mirrors the README flags table).
+const FLAGS = {
+    name: { name: "name", value: "<wallet>", desc: "Wallet to use (default h402)" },
+    wallet: { name: "wallet", value: "0x...", desc: "Local wallet that owns this address (must agree with --name)" },
+    apiUrl: { name: "api-url", value: "<url>", desc: "Backend base URL (or H402_API_URL; default https://h402.hunt.town)" },
+    json: { name: "json", value: "'{...}'", desc: "Request body (sets method to POST)" },
+    query: { name: "query", value: "'{...}'", desc: "URL query params; values must be string/number/boolean" },
+    provider: { name: "provider", value: "<name>", desc: "Select a concrete provider (omitted: resolve the catalog default)" },
+    showProvider: { name: "provider", value: "<name>", desc: "Select one concrete provider (omitted: list all enabled providers)" },
+    method: { name: "method", value: "GET|POST", desc: "Override the HTTP method" },
+    passphrase: {
+        name: "passphrase",
+        value: "[<s>]",
+        valueOptional: true,
+        desc: "Passphrase for a passphrase-protected wallet; omit the value to be prompted (or H402_WALLET_PASSPHRASE)"
+    },
+    noPassphrase: { name: "no-passphrase", desc: "Force passphrase-less signing even if H402_WALLET_PASSPHRASE is set (the default needs no flag)" },
+    noCredit: { name: "no-credit", desc: "Ignore bonus credits and pay x402 only" },
+    maxUsd: { name: "max-usd", value: "<usd>", desc: "Refuse to sign if the x402 USDC amount exceeds this cap" },
+    idempotencyKey: { name: "idempotency-key", value: "<uuid>", desc: "Stable key for safe retries (default: random)" },
+    limit: { name: "limit", value: "<n>", desc: "Max results (default 20)" }
+};
+export const COMMANDS = {
+    wallet: {
+        usage: "h402 wallet <create|list|restore|address|balance|fund> [flags]",
+        summary: "Manage local non-custodial wallets",
+        flags: [],
+        subcommands: {
+            create: {
+                usage: "h402 wallet create [flags]",
+                summary: "Create a local OWS signing wallet (no auth session; passphrase-less by default; prints its address)",
+                flags: [FLAGS.name, FLAGS.passphrase, FLAGS.noPassphrase],
+                examples: ["h402 wallet create --name agent"]
+            },
+            list: { usage: "h402 wallet list", summary: "List OWS wallets", flags: [] },
+            restore: { usage: "h402 wallet restore", summary: "Re-adopt OWS wallets into h402 config", flags: [] },
+            address: { usage: "h402 wallet address [flags]", summary: "Print a wallet address", flags: [FLAGS.name, FLAGS.wallet] },
+            balance: {
+                usage: "h402 wallet balance [flags]",
+                summary: "Show a wallet's Base USDC balance",
+                flags: [FLAGS.name, FLAGS.wallet],
+                examples: ["h402 wallet balance --name agent"]
+            },
+            fund: { usage: "h402 wallet fund [flags]", summary: "Print the Base USDC deposit address for a wallet", flags: [FLAGS.name, FLAGS.wallet] }
+        }
+    },
+    auth: {
+        usage: "h402 auth [flags]",
+        summary: "Create a backend bonus-credit session with a wallet signature",
+        flags: [FLAGS.name, FLAGS.wallet, FLAGS.apiUrl, FLAGS.passphrase, FLAGS.noPassphrase]
+    },
+    credits: { usage: "h402 credits [flags]", summary: "Show the bonus-credit balance for the signed-in session", flags: [FLAGS.apiUrl] },
+    search: {
+        usage: "h402 search <query> [flags]",
+        summary: "Search the catalog without a wallet (compact JSON results)",
+        flags: [FLAGS.apiUrl, FLAGS.limit],
+        examples: ['h402 search "web search"']
+    },
+    show: {
+        usage: "h402 show <category/action> [flags]",
+        summary: "Inspect a route and its full provider-native contracts",
+        flags: [FLAGS.apiUrl, FLAGS.showProvider],
+        examples: ["h402 show web/search", "h402 show web/search --provider stableenrich-exa"]
+    },
+    quote: {
+        usage: "h402 quote <category/action> [flags]",
+        summary: "Preview the x402 PAYMENT-REQUIRED envelope without paying or a wallet",
+        flags: [FLAGS.apiUrl, FLAGS.json, FLAGS.query, FLAGS.provider, FLAGS.method],
+        examples: ["h402 quote web/search --provider stableenrich-exa --json '{\"query\":\"agent APIs\"}'"]
+    },
+    call: {
+        usage: "h402 call <category/action> [flags]",
+        summary: "Execute a route and pay if challenged (free routes need no wallet)",
+        flags: [
+            FLAGS.name,
+            FLAGS.wallet,
+            FLAGS.apiUrl,
+            FLAGS.json,
+            FLAGS.query,
+            FLAGS.provider,
+            FLAGS.method,
+            FLAGS.passphrase,
+            FLAGS.noPassphrase,
+            FLAGS.noCredit,
+            FLAGS.maxUsd,
+            FLAGS.idempotencyKey
+        ],
+        examples: ["h402 call ai/news", "h402 call web/search --provider stableenrich-exa --name agent --json '{\"query\":\"agent APIs\"}'"]
+    }
+};
+const ENV_VARS = [
+    ["H402_API_URL", "Backend base URL override (or --api-url)"],
+    ["H402_WALLET_PASSPHRASE", "Passphrase for passphrase-protected wallets (only needed when the wallet was created with one)"]
+];
+export function getVersion() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const manifest = JSON.parse(readFileSync(path.join(here, "..", "package.json"), "utf8"));
+    return manifest.version;
+}
+export function isKnownCommand(command) {
+    return Object.hasOwn(COMMANDS, command);
+}
+function specFor(commandPath) {
+    const [command, subcommand] = commandPath;
+    const top = command ? COMMANDS[command] : undefined;
+    if (!top) {
+        return undefined;
+    }
+    if (subcommand && top.subcommands && Object.hasOwn(top.subcommands, subcommand)) {
+        return top.subcommands[subcommand];
+    }
+    return top;
+}
+// The deepest known command/subcommand the positionals name (e.g. ["wallet",
+// "balance"]); an unknown subcommand falls back to the command itself.
+export function resolveCommandPath(positional) {
+    const [command, maybeSub] = positional;
+    if (!command || !isKnownCommand(command)) {
+        return command ? [command] : [];
+    }
+    const spec = COMMANDS[command];
+    if (spec.subcommands && maybeSub && Object.hasOwn(spec.subcommands, maybeSub)) {
+        return [command, maybeSub];
+    }
+    return [command];
+}
+function renderFlag(flag) {
+    const left = flag.value ? `--${flag.name} ${flag.value}` : `--${flag.name}`;
+    return `  ${left.padEnd(28)} ${flag.desc}`;
+}
+export function topLevelHelp() {
+    const lines = ["h402 — the x402 capability store", "", "Usage: h402 <command> [flags]", "", "Commands:"];
+    for (const [name, spec] of Object.entries(COMMANDS)) {
+        lines.push(`  ${name.padEnd(10)} ${spec.summary}`);
+    }
+    lines.push("", "Run 'h402 <command> --help' for details, 'h402 --version' for the version.", "", "Environment:");
+    for (const [name, desc] of ENV_VARS) {
+        lines.push(`  ${name.padEnd(24)} ${desc}`);
+    }
+    return lines.join("\n");
+}
+export function commandHelp(commandPath) {
+    const spec = specFor(commandPath);
+    if (!spec) {
+        return topLevelHelp();
+    }
+    const lines = [spec.summary, "", `Usage: ${spec.usage}`];
+    if (spec.subcommands) {
+        lines.push("", "Subcommands:");
+        for (const [name, sub] of Object.entries(spec.subcommands)) {
+            lines.push(`  ${name.padEnd(10)} ${sub.summary}`);
+        }
+    }
+    lines.push("", "Flags:");
+    for (const flag of spec.flags) {
+        lines.push(renderFlag(flag));
+    }
+    lines.push(renderFlag({ name: "help", desc: "Print this help" }));
+    if (spec.examples?.length) {
+        lines.push("", "Examples:");
+        for (const example of spec.examples) {
+            lines.push(`  ${example}`);
+        }
+    }
+    return lines.join("\n");
+}
+function unknownFlagsError(names, helpCommand) {
+    const label = names.length > 1 ? "Unknown flags" : "Unknown flag";
+    return new Error(`${label}: ${names.map((name) => `--${name}`).join(", ")}. Run: ${helpCommand}`);
+}
+// Reject flags the resolved command doesn't accept (so a typo like
+// --idempotency-ky fails loudly), and validate value shape: a value flag must
+// carry a value, a boolean flag must not. A bare value flag parses to boolean
+// `true`, which flagString() silently treats as unset — e.g. `--idempotency-key`
+// with no value would fall back to a random key, making a paid retry unsafe.
+export function assertKnownFlags(commandPath, flags) {
+    const spec = specFor(commandPath);
+    if (!spec) {
+        return; // Unknown command/subcommand: the command handler reports it.
+    }
+    // Flag name -> value arity (--help is an always-allowed boolean). "optional"
+    // flags are meaningful both bare and with a value (bare --passphrase = prompt).
+    const valueFlags = new Map([["help", "none"]]);
+    for (const flag of spec.flags) {
+        valueFlags.set(flag.name, flag.value === undefined ? "none" : flag.valueOptional ? "optional" : "required");
+    }
+    const unknown = Object.keys(flags).filter((key) => !valueFlags.has(key));
+    if (unknown.length > 0) {
+        throw unknownFlagsError(unknown, `h402 ${commandPath.join(" ")} --help`);
+    }
+    for (const [name, provided] of Object.entries(flags)) {
+        const arity = valueFlags.get(name);
+        if (arity === "required" && (typeof provided !== "string" || provided === "")) {
+            throw new Error(`Flag --${name} requires a value. Run: h402 ${commandPath.join(" ")} --help`);
+        }
+        // A boolean flag that captured a following token (e.g. `--no-passphrase web/search`,
+        // where the parser greedily consumed the route id) is a mistake; "true" stays
+        // valid since flagBoolean() accepts it.
+        if (arity === "none" && typeof provided === "string" && provided !== "true") {
+            throw new Error(`Flag --${name} does not take a value (got "${provided}"). Run: h402 ${commandPath.join(" ")} --help`);
+        }
+    }
+}
+// Without a command, only --help and --version are valid; reject anything else
+// (e.g. a typo'd --versoin) instead of silently printing help and exiting 0.
+export function assertTopLevelFlags(flags) {
+    const stray = Object.keys(flags).filter((flag) => flag !== "help" && flag !== "version");
+    if (stray.length > 0) {
+        throw unknownFlagsError(stray, "h402 --help");
+    }
+    for (const name of ["help", "version"]) {
+        const provided = flags[name];
+        if (typeof provided === "string" && provided !== "true") {
+            throw new Error(`Flag --${name} does not take a value (got "${provided}"). Run: h402 --help`);
+        }
+    }
+}

package/dist/index.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { authCommand, callCommand, creditsCommand, quoteCommand, searchCommand, showCommand, walletCommand } from "./commands.js";
+import { errorEnvelope } from "./errors.js";
+import { assertKnownFlags, assertTopLevelFlags, commandHelp, getVersion, isKnownCommand, resolveCommandPath, topLevelHelp } from "./help.js";
+import { flagBoolean, parseArgs, writeStderr, writeStdout } from "./utils.js";
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const command = args.positional[0];
+    if (!command) {
+        assertTopLevelFlags(args.flags);
+        if (flagBoolean(args.flags, "version")) {
+            await writeStdout(`${getVersion()}\n`);
+            return;
+        }
+    }
+    else if (command === "version") {
+        assertTopLevelFlags(args.flags);
+        const extra = args.positional.slice(1);
+        if (extra.length > 0) {
+            const label = extra.length === 1 ? "Unexpected positional argument" : "Unexpected positional arguments";
+            throw new Error(`${label}: ${extra.map((value) => JSON.stringify(value)).join(", ")}. Run: h402 --help`);
+        }
+        await writeStdout(`${getVersion()}\n`);
+        return;
+    }
+    if (!command || command === "help") {
+        if (command === "help") {
+            assertTopLevelFlags(args.flags);
+        }
+        await writeStdout(`${topLevelHelp()}\n`);
+        return;
+    }
+    if (!isKnownCommand(command)) {
+        throw new Error(`Unknown command: ${command}. Run: h402 --help`);
+    }
+    const commandPath = resolveCommandPath(args.positional);
+    // Reject typo'd/unsupported flags before doing any work (a silently ignored
+    // --idempotency-key on a paid call could double-charge on retry).
+    assertKnownFlags(commandPath, args.flags);
+    if (flagBoolean(args.flags, "help")) {
+        await writeStdout(`${commandHelp(commandPath)}\n`);
+        return;
+    }
+    if (command === "wallet")
+        return walletCommand(args);
+    if (command === "auth")
+        return authCommand(args);
+    if (command === "credits")
+        return creditsCommand(args);
+    if (command === "search")
+        return searchCommand(args);
+    if (command === "show")
+        return showCommand(args);
+    if (command === "quote")
+        return quoteCommand(args);
+    if (command === "call")
+        return callCommand(args);
+    throw new Error(`Unknown command: ${command}. Run: h402 --help`);
+}
+main()
+    .then(() => {
+    process.exitCode = 0;
+})
+    .catch(async (error) => {
+    // Every failure exits non-zero with one machine-readable stderr shape:
+    // { "error": { "message", "detail"? } } (see errorEnvelope).
+    process.exitCode = 1;
+    await writeStderr(`${JSON.stringify(errorEnvelope(error), null, 2)}\n`);
+});