@itpay/cli 0.2.17 → 2.0.0-rc.1

package/dist/src/commands/checkout.js

@@ -0,0 +1,106 @@
+// Reads the canonical V3 checkout presentation. Requires both checkout_id
+// and the checkout-scoped display_token. Supports terminal and agent markdown.
+import { formatMoney } from "../render/output.js";
+import { hintFor } from "../render/status.js";
+import { resolveOutput } from "../render/sink.js";
+import { ensureIdeImageAttach, ideImageAttachBlock } from "../render/ide.js";
+import { DEFAULT_BASE_URL } from "../state/config.js";
+export async function runCheckoutPresentation(backend, options) {
+    const out = resolveOutput(options.output);
+    const presentation = await backend.getCheckoutPresentation(options.checkoutID, options.displayToken);
+    const checkoutURL = checkoutPageURL(options.baseURL, options.checkoutID, options.displayToken);
+    const qrPNGURL = presentation.qr_png_url ?? checkoutQRPNGURL(options.baseURL, options.checkoutID, options.displayToken);
+    const plan = {
+        kind: "checkout_qr",
+        host: (options.host ?? "terminal"),
+        summary: "checkout presentation",
+        url: checkoutURL,
+        preferredQRSources: [qrPNGURL],
+        platform: {
+            text: "checkout presentation",
+            links: [{ label: "打开付款页面", url: checkoutURL }],
+            buttons: [],
+            blocks: [],
+        },
+    };
+    await ensureIdeImageAttach(plan, {
+        ...(options.baseURL ? { baseURL: options.baseURL } : {}),
+    });
+    if (options.host === "codex" || options.host === "claude-code" || options.host === "trae") {
+        out(renderCheckoutMarkdown(presentation, plan) + "\n");
+    }
+    else {
+        out(renderCheckoutText(presentation) + "\n");
+        if (plan.ideImageAttach) {
+            out(ideImageAttachBlock(plan.ideImageAttach).filter((l) => l.length > 0).join("\n") + "\n");
+        }
+        out(`hint: ${hintFor("checkout", presentation.checkout.status)}\n`);
+    }
+}
+function renderCheckoutText(presentation) {
+    const lines = [];
+    const c = presentation.checkout;
+    lines.push(`checkout ${c.checkout_id}`);
+    lines.push(`  status:      ${c.status}`);
+    lines.push(`  next_action: ${c.next_action}`);
+    lines.push(`  amount:      ${formatMoney(c.amount_minor, c.currency)}`);
+    lines.push(`  buyer:       ${presentation.buyer_session.state}`);
+    if (presentation.items.length > 0) {
+        lines.push("  items:");
+        for (const item of presentation.items) {
+            lines.push(`    - ${item.title} × ${item.quantity} (${formatMoney(item.amount_minor, item.currency)})`);
+        }
+    }
+    if (presentation.payment_intents.length > 0) {
+        lines.push("  payment_intents:");
+        for (const intent of presentation.payment_intents) {
+            lines.push(`    - ${intent.payment_intent_id} ${intent.status} (${intent.payment_method_type}, ${formatMoney(intent.amount_minor, intent.currency)})`);
+        }
+    }
+    return lines.join("\n");
+}
+function renderCheckoutMarkdown(presentation, plan) {
+    const c = presentation.checkout;
+    const lines = [];
+    lines.push(`## :mag: Checkout ${c.checkout_id}`);
+    lines.push("");
+    lines.push(`| 字段 | 值 |`);
+    lines.push(`|------|-----|`);
+    lines.push(`| 状态 | ${c.status} |`);
+    lines.push(`| 操作 | ${c.next_action} |`);
+    lines.push(`| 金额 | ${formatMoney(c.amount_minor, c.currency)} |`);
+    lines.push(`| 买家 | ${presentation.buyer_session.state} |`);
+    lines.push("");
+    if (presentation.items.length > 0) {
+        lines.push(`| 项目 | 数量 | 单价 |`);
+        lines.push(`|------|:----:|------|`);
+        for (const item of presentation.items) {
+            lines.push(`| ${item.title} | ${item.quantity} | ${formatMoney(item.amount_minor, item.currency)} |`);
+        }
+        lines.push("");
+    }
+    if (presentation.payment_intents.length > 0) {
+        lines.push(`### :credit_card: 支付`);
+        lines.push("");
+        for (const intent of presentation.payment_intents) {
+            lines.push(`- \`${intent.payment_intent_id}\` — ${intent.payment_method_type} — ${intent.status} — ${formatMoney(intent.amount_minor, intent.currency)}`);
+        }
+        lines.push("");
+    }
+    if (plan.ideImageAttach) {
+        lines.push(...ideImageAttachBlock(plan.ideImageAttach));
+    }
+    lines.push(`> :bulb: ${hintFor("checkout", c.status)}`);
+    return lines.join("\n");
+}
+function checkoutPageURL(baseURL, checkoutID, displayToken) {
+    const root = publicRoot(baseURL);
+    return `${root}/checkout/${encodeURIComponent(checkoutID)}?display_token=${encodeURIComponent(displayToken)}`;
+}
+function checkoutQRPNGURL(baseURL, checkoutID, displayToken) {
+    const root = publicRoot(baseURL);
+    return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/qr.png?display_token=${encodeURIComponent(displayToken)}`;
+}
+function publicRoot(baseURL) {
+    return (baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+}

package/dist/src/commands/docs.js

@@ -0,0 +1,61 @@
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function findDocsDir() {
+    if (process.env.ITPAY_CLI_DOCS_DIR) {
+        return process.env.ITPAY_CLI_DOCS_DIR;
+    }
+    // dist/src/commands → ../../../docs/agent/buyer = <pkg>/docs/agent/buyer
+    const pkgPath = resolve(__dirname, "..", "..", "..", "docs", "agent", "buyer");
+    if (existsSync(pkgPath))
+        return pkgPath;
+    // src/commands → ../../docs/agent/buyer = <pkg>/docs/agent/buyer (dev mode)
+    const devPath = resolve(__dirname, "..", "..", "docs", "agent", "buyer");
+    if (existsSync(devPath))
+        return devPath;
+    return pkgPath;
+}
+const DOCS_DIR = findDocsDir();
+function loadDocs() {
+    const files = readdirSync(DOCS_DIR).filter((f) => f.endsWith(".json"));
+    return files.map((file) => {
+        const raw = readFileSync(resolve(DOCS_DIR, file), "utf-8");
+        return JSON.parse(raw);
+    });
+}
+export function runDocsList() {
+    const docs = loadDocs();
+    process.stdout.write(`Agent docs (${docs.length} topics):\n\n`);
+    for (const doc of docs) {
+        process.stdout.write(`  ${doc.topic}\n`);
+        process.stdout.write(`    title:   ${doc.title}\n`);
+        process.stdout.write(`    purpose: ${doc.purpose}\n\n`);
+    }
+}
+export function runDocsShow(topic) {
+    const docs = loadDocs();
+    const doc = docs.find((d) => d.topic === topic);
+    if (!doc) {
+        process.stderr.write(`doc topic "${topic}" not found. Use "itpay docs list" to see available topics.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    process.stdout.write(JSON.stringify(doc, null, 2) + "\n");
+}
+export function runDocsSearch(query) {
+    const docs = loadDocs();
+    const lower = query.toLowerCase();
+    const results = docs.filter((doc) => {
+        const text = [doc.topic, doc.title, doc.purpose, ...(doc.search_terms ?? [])].join(" ").toLowerCase();
+        return text.includes(lower);
+    });
+    if (results.length === 0) {
+        process.stdout.write(`no docs match "${query}"\n`);
+        return;
+    }
+    process.stdout.write(`${results.length} matching docs:\n\n`);
+    for (const doc of results) {
+        process.stdout.write(`  ${doc.topic} — ${doc.title}\n`);
+    }
+}

package/dist/src/commands/guidance.js

@@ -0,0 +1,422 @@
+import { HttpError } from "../client/http.js";
+import { resolveOutput } from "../render/sink.js";
+export function attachAgentGuidance(payload, guidance) {
+    return {
+        ...payload,
+        agent_guidance: guidance,
+    };
+}
+export function printAgentGuidance(guidance, output) {
+    const out = resolveOutput(output);
+    out(`${guidance.summary}\n`);
+    if (guidance.visible_results?.length) {
+        out("results:\n");
+        for (const item of guidance.visible_results)
+            out(`  ${item.rank}. ${item.title}\n`);
+    }
+    if (guidance.next_actions.length === 0) {
+        out("next actions: none\n");
+    }
+    else {
+        out("next actions:\n");
+        for (const action of guidance.next_actions) {
+            out(`  - ${action.label}\n`);
+            out(`    ${action.command}\n`);
+            if (action.requires_human)
+                out("    requires human confirmation\n");
+            if (action.reason)
+                out(`    reason: ${action.reason}\n`);
+        }
+    }
+    if (guidance.recovery.length > 0) {
+        out("recovery:\n");
+        for (const action of guidance.recovery) {
+            out(`  - ${action.label}\n`);
+            out(`    ${action.command}\n`);
+        }
+    }
+}
+export function buildCartGuidance(cart, serviceModel) {
+    const serviceLine = latestServiceLine(cart);
+    if (serviceLine?.service_execution_id) {
+        const serviceGuidance = serviceModel
+            ? buildServiceReadModelGuidance(serviceModel)
+            : buildServiceHandleGuidance(serviceLine.service_execution_id, serviceLine.service_capability_id);
+        return {
+            ...serviceGuidance,
+            kind: "cart_service_execution",
+            summary: `cart ${cart.cart_id}: service-backed line ${lineID(serviceLine)} is ready for Service Execution`,
+            state: {
+                ...serviceGuidance.state,
+                cart_id: cart.cart_id,
+                cart_item_id: lineID(serviceLine),
+                service_capability_id: serviceLine.service_capability_id,
+            },
+        };
+    }
+    if (cart.items.length === 0) {
+        return {
+            kind: "empty_cart",
+            summary: `cart ${cart.cart_id}: empty`,
+            state: { cart_id: cart.cart_id, status: cart.status },
+            next_actions: [
+                {
+                    id: "browse_catalog",
+                    label: "Browse services",
+                    command: "itpay catalog list",
+                },
+            ],
+            recovery: [],
+        };
+    }
+    return {
+        kind: "cart_checkout_ready",
+        summary: `cart ${cart.cart_id}: ready for checkout`,
+        state: { cart_id: cart.cart_id, status: cart.status, amount_minor: cart.amount_minor, currency: cart.currency },
+        next_actions: [
+            {
+                id: "checkout_cart",
+                label: "Create ItPay checkout",
+                command: `itpay buy --cart ${cart.cart_id} --host <client> --contact-email <email>`,
+                requires_human: true,
+                reason: "The human must review and pay on the ItPay checkout page.",
+            },
+        ],
+        recovery: [
+            {
+                id: "show_cart",
+                label: "Inspect current server cart",
+                command: "itpay cart show",
+            },
+        ],
+    };
+}
+export function buildServiceStartedGuidance(response) {
+    return buildServiceGuidance({
+        execution: response.execution,
+        capabilities: response.capabilities,
+    });
+}
+export function buildServiceReadModelGuidance(model) {
+    return buildServiceGuidance({
+        execution: model.execution,
+        capabilities: model.capabilities,
+        resultItems: model.result_items,
+        checkoutBindings: model.checkout_bindings,
+        deliveryBindings: model.delivery_bindings,
+    });
+}
+export function buildServiceInvokedGuidance(response) {
+    return buildServiceGuidance({
+        execution: response.execution,
+        resultItems: response.result_items,
+        ...(response.next_actions ? { backendNextActions: response.next_actions } : {}),
+        ...(response.effective_quota ? { effectiveQuota: response.effective_quota } : {}),
+        providerCalled: response.provider_called,
+    });
+}
+export function buildServiceActionGuidance(action) {
+    const serviceExecutionID = action.service_execution_id;
+    return {
+        kind: "service_action_recorded",
+        summary: `service execution ${serviceExecutionID}: action ${action.action_type} recorded`,
+        state: {
+            service_execution_id: serviceExecutionID,
+            action_type: action.action_type,
+            status: action.status,
+            result_item_id: action.result_item_id,
+            selected_candidate_hash: action.selected_candidate_hash,
+        },
+        next_actions: [
+            {
+                id: "inspect_service_execution",
+                label: "Read updated Service Execution state",
+                command: `itpay services next ${serviceExecutionID} --json`,
+            },
+        ],
+        recovery: [
+            {
+                id: "timeline",
+                label: "Inspect full timeline",
+                command: `itpay services get ${serviceExecutionID}`,
+            },
+        ],
+    };
+}
+export function buildServiceHandleGuidance(serviceExecutionID, checkoutCapabilityID) {
+    const actions = [
+        {
+            id: "inspect_service_execution",
+            label: "Read Service Execution state and capabilities",
+            command: `itpay services next ${serviceExecutionID} --json`,
+        },
+    ];
+    if (checkoutCapabilityID) {
+        actions.push({
+            id: "checkout_service",
+            label: "Create checkout after human confirmation",
+            command: `itpay services checkout ${serviceExecutionID} --capability ${checkoutCapabilityID} --email <email> --json`,
+            requires_human: true,
+            reason: "Only use after the service contract has the required human confirmation or quote lock.",
+        });
+    }
+    return {
+        kind: "service_execution_handle",
+        summary: `service execution ${serviceExecutionID}: inspect before invoking`,
+        state: { service_execution_id: serviceExecutionID },
+        next_actions: actions,
+        recovery: [],
+    };
+}
+export function errorRecoveryActions(error) {
+    if (!(error instanceof HttpError))
+        return [];
+    if (error.code === "agent_identity_required") {
+        return [
+            {
+                id: "set_agent_identity",
+                label: "Set a stable agent device id",
+                command: "export ITPAY_AGENT_DEVICE_ID=<stable_agent_device_id>",
+            },
+        ];
+    }
+    if (error.code === "quota_exhausted" || error.code === "checkout_required") {
+        return [
+            {
+                id: "inspect_service_execution",
+                label: "Inspect Service Execution before checkout",
+                command: "itpay services next <service_execution_id> --json",
+            },
+        ];
+    }
+    if (error.code === "cart_item_locked" || error.status === 409) {
+        return [
+            {
+                id: "show_cart",
+                label: "Inspect the canonical server cart",
+                command: "itpay cart show",
+            },
+            {
+                id: "continue_checkout",
+                label: "Continue the last locally remembered checkout",
+                command: "itpay checkout",
+            },
+            {
+                id: "recover_service_execution",
+                label: "List recoverable Service Executions if the local handoff is missing",
+                command: "itpay services list",
+            },
+        ];
+    }
+    if (error.status === 404) {
+        return [
+            {
+                id: "recover_service_executions",
+                label: "List visible Service Executions and follow their next instruction",
+                command: "itpay services list",
+            },
+        ];
+    }
+    if (error.status === 502 || error.status === 503 || error.status === 504) {
+        return [
+            {
+                id: "retry_after_backend_recovers",
+                label: "Retry after the ItPay backend is reachable",
+                command: "itpay readyz",
+            },
+            {
+                id: "check_backend_url",
+                label: "Check the configured backend URL",
+                command: "echo $ITPAY_BACKEND_URL",
+            },
+        ];
+    }
+    return [];
+}
+export function printErrorRecovery(error, output) {
+    const recovery = errorRecoveryActions(error);
+    if (recovery.length === 0)
+        return;
+    const out = resolveOutput(output);
+    out("recovery:\n");
+    for (const action of recovery) {
+        out(`  - ${action.label}\n`);
+        out(`    ${action.command}\n`);
+    }
+}
+function buildServiceGuidance(input) {
+    const execution = input.execution;
+    const capabilities = input.capabilities ?? [];
+    const prePurchase = firstPrePurchaseCapability(capabilities);
+    const paid = firstPaidCapability(capabilities);
+    const resultItem = input.resultItems?.[0];
+    const checkoutID = input.checkoutBindings?.at(-1)?.checkout_id;
+    const delivery = input.deliveryBindings?.[0];
+    const backendCheckout = input.backendNextActions?.find((action) => action.kind === "create_checkout");
+    const nextActions = [];
+    const recovery = [
+        {
+            id: "timeline",
+            label: "Inspect full timeline",
+            command: `itpay services get ${execution.service_execution_id}`,
+        },
+    ];
+    if (execution.status === "completed" || execution.next_action === "completed") {
+        nextActions.push({
+            id: "inspect_order_or_grant",
+            label: "Inspect order, claim, or grant from the checkout/order owner",
+            command: "itpay orders --limit 20",
+            requires_human: true,
+            reason: "Delivery visibility is controlled by the human account and grant flow.",
+        });
+    }
+    else if (execution.phase === "delivery" || execution.next_action === "view_delivery") {
+        const grantStatus = String(delivery?.grant_status ?? "");
+        if (grantStatus === "active") {
+            nextActions.push({
+                id: "read_granted_result",
+                label: "Read the human-granted service result",
+                command: `itpay services read-result ${execution.service_execution_id}`,
+                reason: "The human granted temporary agent access to this delivery.",
+            });
+        }
+        else {
+            nextActions.push({
+                id: grantStatus === "expired" ? "ask_human_to_reauthorize" : "wait_for_human_agent_grant",
+                label: grantStatus === "expired" ? "Ask the human to authorize AI access again" : "Wait for human AI-access authorization",
+                command: `itpay services get ${execution.service_execution_id}`,
+                requires_human: true,
+                reason: grantStatus === "expired"
+                    ? "The 15 minute human grant expired."
+                    : "The human must approve AI access on the Credential page.",
+            });
+        }
+    }
+    else if (execution.next_action === "pay_checkout" || execution.status === "checkout_pending") {
+        nextActions.push({
+            id: "open_existing_checkout",
+            label: "Open the existing ItPay checkout handoff",
+            command: `itpay services checkout ${execution.service_execution_id} --resume --json`,
+            requires_human: true,
+            reason: checkoutID
+                ? `Checkout ${checkoutID} already exists; reissue a short-lived handoff without creating another checkout.`
+                : "Recover the existing checkout handoff from Service Execution owner facts.",
+        });
+    }
+    else if (execution.checkout_required || execution.next_action === "create_checkout") {
+        const capabilityID = backendCheckout?.capability_id ?? paid?.capability_id ?? input.checkoutCapabilityID ?? execution.current_capability_id;
+        if (capabilityID) {
+            nextActions.push({
+                id: "checkout_service",
+                label: "Create ItPay checkout for the paid service capability",
+                command: `itpay services checkout ${execution.service_execution_id} --capability ${capabilityID} --email <email> --json`,
+                requires_human: true,
+                reason: "The human must provide delivery contact and pay on the ItPay checkout page.",
+            });
+        }
+        else {
+            nextActions.push({
+                id: "inspect_capabilities",
+                label: "Inspect capabilities before checkout",
+                command: `itpay services get ${execution.service_execution_id}`,
+            });
+        }
+    }
+    else if (input.providerCalled && (input.resultItems?.length ?? 0) === 0) {
+        nextActions.push({
+            id: "refine_search",
+            label: "Ask for a more specific company name before another lookup",
+            command: `itpay services invoke ${execution.service_execution_id} --capability ${execution.current_capability_id ?? "<capability_id>"} --input keyword=<more_specific_company_name>`,
+            requires_human: true,
+            reason: "The provider returned no candidates. Do not repeat the same query.",
+        });
+    }
+    else if (needsHumanSelection(execution, resultItem)) {
+        nextActions.push({
+            id: "select_result_item",
+            label: "Ask the human to select a result item, then submit the selection",
+            command: `itpay services action ${execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank>`,
+            requires_human: true,
+            reason: "Do not choose a candidate without explicit human confirmation.",
+        });
+    }
+    else if (prePurchase) {
+        const action = {
+            id: "invoke_capability",
+            label: `Invoke ${prePurchase.capability_id}`,
+            command: `itpay services invoke ${execution.service_execution_id} --capability ${prePurchase.capability_id} --input key=value --json`,
+        };
+        if (prePurchase.free_quota_limit) {
+            action.reason = `Free quota limit: ${prePurchase.free_quota_limit} per ${prePurchase.quota_subject || "subject"}.`;
+        }
+        nextActions.push(action);
+    }
+    else {
+        nextActions.push({
+            id: "inspect_service_execution",
+            label: "Read Service Execution state",
+            command: `itpay services next ${execution.service_execution_id} --json`,
+        });
+    }
+    return {
+        kind: "service_execution",
+        summary: `service execution ${execution.service_execution_id}: ${execution.status}/${execution.phase}${input.effectiveQuota ? `, quota ${input.effectiveQuota.remaining}/${input.effectiveQuota.limit}` : ""}`,
+        state: {
+            service_execution_id: execution.service_execution_id,
+            service_id: execution.service_id,
+            status: execution.status,
+            phase: execution.phase,
+            current_capability_id: execution.current_capability_id,
+            checkout_required: execution.checkout_required,
+            next_action: execution.next_action,
+            delivery: delivery
+                ? {
+                    status: delivery.status,
+                    vault_artifact_id: delivery.vault_artifact_id,
+                    vault_status: delivery.vault_status,
+                    vault_payload_state: delivery.vault_payload_state,
+                    reveal_status: delivery.reveal_status,
+                    grant_status: delivery.grant_status ?? "missing",
+                    grant_expires_at: delivery.grant_expires_at,
+                }
+                : undefined,
+            capabilities: capabilities.map((capability) => ({
+                capability_id: capability.capability_id,
+                agent_visible: capability.agent_visible,
+                requires_payment: capability.requires_payment,
+                free_quota_limit: capability.free_quota_limit,
+            })),
+            result_items: (input.resultItems ?? []).map((item) => ({
+                result_item_id: item.service_capability_result_item_id,
+                stable_hash: item.stable_hash,
+                rank: item.rank,
+                display_title: item.display_title,
+            })),
+            effective_quota: input.effectiveQuota,
+        },
+        next_actions: nextActions,
+        recovery,
+        ...(input.resultItems?.length
+            ? { visible_results: input.resultItems.map((item) => ({ rank: item.rank, title: item.display_title })) }
+            : {}),
+    };
+}
+function firstPrePurchaseCapability(capabilities) {
+    return capabilities.find((capability) => capability.agent_visible && !capability.requires_payment)
+        ?? capabilities.find((capability) => capability.agent_visible);
+}
+function firstPaidCapability(capabilities) {
+    return (capabilities.find((capability) => capability.requires_payment && capability.vault_required) ??
+        capabilities.find((capability) => capability.requires_payment));
+}
+function needsHumanSelection(execution, resultItem) {
+    if (execution.phase !== "pre_purchase")
+        return false;
+    return execution.next_action === "select_candidate" || execution.next_action === "human_action_required" || resultItem !== undefined;
+}
+function latestServiceLine(cart) {
+    return [...cart.items].reverse().find((item) => item.service_execution_id);
+}
+function lineID(line) {
+    return line.cart_item_id ?? line.line_item_id ?? line.checkout_item_id ?? "<unknown_line>";
+}

package/dist/src/commands/install.js

@@ -0,0 +1,95 @@
+import { DEFAULT_BASE_URL } from "../state/config.js";
+const INSTALL_TARGETS = {
+    "claude-code": {
+        name: "Claude Code",
+        configFile: "~/.claude/settings.json",
+        instructions: [
+            "1. Ensure itpay is installed:  npm install -g @itpay/cli",
+            `2. Production API (default):    ${DEFAULT_BASE_URL}`,
+            "3. Use --agent-type claude-code-cli or claude-code-desktop",
+            "4. Use --host claude-code for human-facing output",
+            "5. The CLI renders checkout QR as markdown images and links",
+        ],
+    },
+    codex: {
+        name: "Codex / Trae",
+        configFile: "~/.codex/config.toml",
+        instructions: [
+            "1. Ensure itpay is installed:  npm install -g @itpay/cli",
+            `2. Production API (default):    ${DEFAULT_BASE_URL}`,
+            "3. Use --agent-type codex-cli or codex-desktop",
+            "4. Use --host trae or --host codex for human-facing output",
+            "5. Attach the emitted QR image and show the checkout link",
+            "6. Collect missing contact fields from the user; never invent them",
+        ],
+    },
+    terminal: {
+        name: "Terminal",
+        configFile: "shell profile (~/.zshrc, ~/.bashrc)",
+        instructions: [
+            "1. Install globally:            npm install -g @itpay/cli",
+            `2. Production API (default):    ${DEFAULT_BASE_URL}`,
+            "3. Set the real runtime type with --agent-type <type>",
+            "4. Use --host terminal for text/QR output in terminal",
+            "5. Override ITPAY_BACKEND_URL only for local or test backends",
+        ],
+    },
+    telegram: {
+        name: "Telegram",
+        configFile: "OpenClaw gateway config",
+        instructions: [
+            "1. Install itpay:               npm install -g @itpay/cli",
+            `2. Production API (default):    ${DEFAULT_BASE_URL}`,
+            "3. Set the real OpenClaw runtime with --agent-type <type>",
+            "4. Use --host telegram --target <chat_id> for human-facing output",
+            "5. The CLI emits openclaw_message payloads with buttons and QR images",
+        ],
+    },
+    feishu: {
+        name: "Feishu / Lark",
+        configFile: "Feishu bot config",
+        instructions: [
+            "1. Install itpay:               npm install -g @itpay/cli",
+            `2. Production API (default):    ${DEFAULT_BASE_URL}`,
+            "3. Set the real agent runtime with --agent-type <type>",
+            "4. Use --host feishu --target <open_id> or --host lark --target <open_id>",
+            "5. The CLI emits Interactive Card JSON with buttons and QR images",
+        ],
+    },
+};
+export function runInstall(target) {
+    if (!target || target === "list") {
+        listTargets();
+        return;
+    }
+    const normalized = target.toLowerCase();
+    if (normalized === "trae") {
+        // Trae uses the codex install target
+        printInstall("codex");
+        return;
+    }
+    if (INSTALL_TARGETS[normalized]) {
+        printInstall(normalized);
+    }
+    else {
+        process.stderr.write(`unknown target "${target}". Available: ${Object.keys(INSTALL_TARGETS).join(", ")}\n`);
+        process.exitCode = 1;
+    }
+}
+function printInstall(key) {
+    const target = INSTALL_TARGETS[key];
+    if (!target)
+        return;
+    process.stdout.write(`\n=== ItPay V3 CLI — Install for ${target.name} ===\n`);
+    process.stdout.write(`Config file: ${target.configFile}\n\n`);
+    for (const line of target.instructions) {
+        process.stdout.write(`${line}\n`);
+    }
+    process.stdout.write("\n");
+}
+function listTargets() {
+    process.stdout.write("Available install targets:\n\n");
+    for (const [key, target] of Object.entries(INSTALL_TARGETS)) {
+        process.stdout.write(`  ${key.padEnd(14)} ${target.name.padEnd(18)} ${target.configFile}\n`);
+    }
+}