@itpay/cli 2.1.41 → 2.1.44

package/dist/src/render/checkout_handoff.js

@@ -0,0 +1,101 @@
+import { buildOpenClawTelegramAction } from "./telegram.js";
+export function shouldPrepareLocalCheckoutImage(platform) {
+    return platform === "markdown";
+}
+export function isWorkBuddyPlainChat(agentType, platform) {
+    return agentType?.trim().toLowerCase() === "workbuddy" && platform === "plain_chat";
+}
+export function isZCodePlainChat(agentType, platform) {
+    return agentType?.trim().toLowerCase() === "zcode" && platform === "plain_chat";
+}
+export function isLinkOnlyBrowserAgent(agentType, platform) {
+    return isWorkBuddyPlainChat(agentType, platform) || isZCodePlainChat(agentType, platform);
+}
+export function buildWorkBuddyPresentFilesAction(url) {
+    return {
+        tool: "present_files",
+        arguments: { files: [url] },
+    };
+}
+function hasCompleteCheckoutTokens(url) {
+    if (!url) {
+        return false;
+    }
+    try {
+        const parsed = new URL(url);
+        return Boolean(parsed.searchParams.get("display_token") && parsed.searchParams.get("complete_exchange_token"));
+    }
+    catch {
+        return false;
+    }
+}
+export function buildCheckoutHandoff(input) {
+    const url = input.plan?.localSimulation && input.mobileUrl && hasCompleteCheckoutTokens(input.mobileUrl) ? input.mobileUrl : input.url;
+    const handoff = { url, ...(input.plan?.localSimulation ? { environment: "local_simulation", query: "live", transactions: "simulated" } : {}) };
+    // mobile_url is only emitted when the link carries the complete token pair;
+    // a display-token-only link cannot finish the same-device exchange after payment.
+    const mobileUrl = !input.plan?.localSimulation && hasCompleteCheckoutTokens(input.mobileUrl) ? input.mobileUrl : undefined;
+    if (mobileUrl) {
+        handoff.mobile_url = mobileUrl;
+    }
+    const workBuddyAction = isWorkBuddyPlainChat(input.agentType, input.platform);
+    if (workBuddyAction) {
+        handoff.agent_action = buildWorkBuddyPresentFilesAction(url);
+    }
+    if (input.platform === "markdown") {
+        if (input.localPath)
+            handoff.qr_local_path = input.localPath;
+        if (input.markdown)
+            handoff.markdown = input.markdown;
+    }
+    else if (input.platform === "plain_chat" && input.qrImageURL && !isLinkOnlyBrowserAgent(input.agentType, input.platform)) {
+        handoff.qr_image_url = input.qrImageURL;
+    }
+    else if (input.platform === "telegram" && input.qrImageURL) {
+        handoff.qr_image_url = input.qrImageURL;
+    }
+    if (input.agentType?.trim().toLowerCase() === "openclaw" && input.platform === "telegram" && input.plan && input.target) {
+        handoff.agent_action = buildOpenClawTelegramAction(input.plan, input.target);
+    }
+    return {
+        handoff,
+        instruction: input.plan?.localSimulation
+            ? `本地实验：铁路与地图查询真实，授权、通知和交易模拟，不会扣款。在本机打开 handoff.url 模拟付款入口，金额 ${input.amount}；仅本机桌面可达。${workBuddyAction ? "按 handoff.agent_action 原样打开一次。" : "展示原入口。"}等待用户操作后读取同一 Checkout；不创建替代订单，用户声明不证明模拟付款已确认。`
+            : `先展示官方入口，再做非必要记忆或日志；保留必需安全检查和宿主权限。${checkoutHandoffInstruction(input.agentType, input.platform, input.amount, Boolean(mobileUrl))}`,
+    };
+}
+function checkoutHandoffInstruction(agentType, platform, amount, hasMobileLink) {
+    if (isWorkBuddyPlainChat(agentType, platform)) {
+        const mobileSentence = hasMobileLink
+            ? "，然后把 handoff.mobile_url 作为可点击链接发给用户，说明“手机端点开可直接跳转支付宝或微信支付；小程序内打不开时复制到手机浏览器打开即可”"
+            : "";
+        const failLinks = hasMobileLink ? "发送 handoff.url 与 handoff.mobile_url" : "发送原始 handoff.url";
+        return `Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount}${mobileSentence}，然后停止等待。若工具失败，只${failLinks}，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    if (isZCodePlainChat(agentType, platform)) {
+        const mobileSentence = hasMobileLink
+            ? "，并把 handoff.mobile_url 发给用户备用（手机端点开可直接跳转支付宝或微信支付）"
+            : "";
+        const fallbackLinks = hasMobileLink ? "同一个可点击 handoff.url 与 handoff.mobile_url" : "同一个可点击 handoff.url";
+        return `Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额 ${amount}${mobileSentence}，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示${fallbackLinks}。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    if (agentType?.trim().toLowerCase() === "doubao-work" && platform === "plain_chat") {
+        const directLink = hasMobileLink ? "handoff.mobile_url" : "handoff.url";
+        const directLabel = hasMobileLink ? "手机直接打开收银台（可跳转支付宝/微信）" : "手机直接打开收银台";
+        return `Backend 尚未确认付款。在当前豆包工作对话中展示两个有标签的官方入口：将 ${directLink} 标为“${directLabel}”，将 handoff.qr_image_url 标为“二维码图片（保存或用另一台设备扫码）”。说明金额 ${amount} 后停止等待。不要解析或单独输出 URL credential，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    if (platform === "markdown") {
+        const mobileSentence = hasMobileLink ? "，并附 handoff.mobile_url 供手机端点击直达支付" : "";
+        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见${mobileSentence}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    if (platform === "terminal") {
+        const mobileSentence = hasMobileLink ? "，并展示 handoff.mobile_url 供手机端点击直达支付" : "";
+        return `Backend 尚未确认付款。在用户可见终端展示当前 Checkout 的二维码、handoff.url 和金额 ${amount}${mobileSentence}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    if (agentType?.trim().toLowerCase() === "openclaw" && platform === "telegram") {
+        const failLinks = hasMobileLink ? "handoff.qr_image_url、金额、handoff.url 与 handoff.mobile_url" : "handoff.qr_image_url、金额和 handoff.url";
+        return `Backend 尚未确认付款或授权状态。立即使用 OpenClaw 原生 message tool，严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行；它会发送金额 ${amount}、二维码、📱 手机点这儿支付和 📋 已授权给我读。不得改写 presentation、换用其他消息工具、拆开按钮发送或用普通回复声称按钮已经发送。确认 message tool 调用成功后停止等待。收到 callback_data "itp:grant_confirmed:<checkout_id>" 时，表示用户声明已在收银台授权读取；立即执行 next.command 查询同一 Checkout，再只执行 Backend 返回的 next.command 进入同一 Execution 的 grant 流程。该 callback 不证明付款成功或 grant 已生效；Backend 未返回 grant_active 前不得读取或猜测结果。若原生 message tool 明确失败或当前 Telegram 未启用 inline buttons，只发送现有 ${failLinks}，报告按钮不可用并停止；不要创建新的 Checkout、Payment Intent 或 Execution。`;
+    }
+    const urlList = hasMobileLink ? "handoff.url、handoff.mobile_url（手机端点击直达支付）和可用的 handoff.qr_image_url" : "handoff.url 和可用的 handoff.qr_image_url";
+    return `Backend 尚未确认付款。把 ${urlList} 实际发送到当前会话，说明金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+}

package/dist/src/render/checkout_plan.js

@@ -0,0 +1,47 @@
+import { platformKeyForHost } from "./plan.js";
+import { isLinkOnlyBrowserAgent } from "./checkout_handoff.js";
+import { qualifyItPayCommand } from "../state/agent_type.js";
+// --- checkout QR plan ---
+export function buildCheckoutQRPlan(input) {
+    const summary = input.localSimulation ? "在本机打开模拟付款入口；铁路与地图查询真实，授权、通知和交易模拟，不会扣款。" : `Scan the QR or open ${input.checkoutURL} to start the human checkout flow.`;
+    const isPayment = input.paymentIntentID != null;
+    const afterCommand = qualifyItPayCommand(`itpay checkout --id ${input.checkoutID} --token ${input.displayToken}${input.locale === "en" ? " --locale en" : ""} --json`, input.agentType);
+    const platform = {
+        text: summary,
+        links: [
+            { label: "打开付款页面", url: input.checkoutURL },
+        ],
+        buttons: [
+            { label: "打开收银台", kind: "url", url: input.checkoutURL },
+            ...(input.checkoutID
+                ? [{ label: "查询 Checkout 状态", kind: "callback", intent: "check_checkout_status", ref: input.checkoutID }]
+                : []),
+        ],
+        blocks: [],
+        ...(input.qrPNGURL ? { media: [{ url: input.qrPNGURL, label: "Branded QR", mimeType: "image/png" }] } : {}),
+    };
+    const plan = {
+        kind: isPayment ? "payment_qr" : "checkout_qr",
+        ...(input.localSimulation ? { localSimulation: true } : {}),
+        host: input.host,
+        summary,
+        url: input.qrPayload,
+        ...(isLinkOnlyBrowserAgent(input.agentType, platformKeyForHost(input.host)) && input.cardURL ? { linkOnlyURL: input.cardURL } : {}),
+        preferredQRSources: [input.qrPNGURL ?? input.qrPayload],
+        checkoutID: input.checkoutID,
+        platform,
+        afterActionCommand: afterCommand,
+        afterActionLabel: "扫码或点击链接完成支付后，执行以下命令查询状态：",
+    };
+    if (input.orderItems)
+        plan.orderItems = input.orderItems;
+    if (input.orderCurrency)
+        plan.orderCurrency = input.orderCurrency;
+    if (input.paymentMethod)
+        plan.paymentMethod = input.paymentMethod;
+    if (input.paymentStatus)
+        plan.paymentStatus = input.paymentStatus;
+    if (input.paymentIntentID)
+        plan.paymentIntentID = input.paymentIntentID;
+    return plan;
+}

package/dist/src/render/markdown.js

@@ -24,9 +24,6 @@ export function buildAgentChatHandoff(plan) {
     if (plan.orderItems?.length) {
         lines.push(`项目：${plan.orderItems.map((item) => `${item.title} x${item.quantity}`).join("、")}`);
     }
-    if (plan.afterActionCommand) {
-        lines.push("", `付款后查询：\`${plan.afterActionCommand}\``);
-    }
     return {
         type: "send_payment_handoff",
         must_send_to_user: true,

package/dist/src/render/qr.js

@@ -20,7 +20,7 @@ export async function renderTerminalQR(url, format) {
     });
 }
 export async function writeLocalPNG(url) {
-    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "itpay-v3-"));
+    const dir = await fs.mkdtemp(path.join(process.env.ITPAY_STATE_DIR || os.tmpdir(), "itpay-v3-"));
     const filePath = path.join(dir, `itpay-${randomUUID()}.png`);
     await QRCode.toFile(filePath, url, {
         type: "png",

package/dist/src/sell/commands.js

@@ -0,0 +1,80 @@
+import { sellerAuth } from "../state/account_auth.js";
+import { registerSync } from "./sync.js";
+import { preview } from "./preview.js";
+import { serveSellMCP } from "./mcp.js";
+import { registerLocal } from "./local.js";
+import { readFileSync } from 'node:fs';
+import { loadConfig, newBackendClient } from '../state/config.js';
+import { SELL_GUIDE, SELL_OPERATIONS, sellRequest } from './contract.js';
+export function registerSell(program) {
+    const sell = program.command('sell').description('Create, test and submit your service for review');
+    const auth = sell.command('auth').description('Authorize this CLI using normal ItPay account login');
+    for (const action of ['login', 'status', 'logout'])
+        auth.command(action).action(async () => {
+            process.stdout.write(JSON.stringify(await sellerAuth(action, loadConfig().baseURL)) + '\n');
+        });
+    const groups = new Map([['', sell]]);
+    for (const operation of SELL_OPERATIONS) {
+        const parts = operation.command.split(' ');
+        const leaf = parts.pop();
+        let parent = sell, key = '';
+        for (const part of parts) {
+            key = key ? `${key} ${part}` : part;
+            let group = groups.get(key);
+            if (!group) {
+                group = parent.command(part);
+                groups.set(key, group);
+            }
+            parent = group;
+        }
+        const command = parent.command(leaf).description(operation.description).option('--json', 'Structured output').option('--input-json <file>', 'Request fields as JSON');
+        const required = [...operation.path.matchAll(/\{(\w+)\}/g)].map(m => m[1]);
+        for (const field of required)
+            command.option(`--${field.replaceAll('_', '-')} <value>`, field);
+        if (operation.confirmation)
+            command.option('--confirm', 'User explicitly confirmed the disclosed version/action');
+        command.action(async (options) => {
+            try {
+                if (operation.command === 'guide' && !options.merchantId) {
+                    process.stdout.write(JSON.stringify({ ...SELL_GUIDE, operations: SELL_OPERATIONS }, null, 2) + '\n');
+                    return;
+                }
+                if (operation.confirmation && !options.confirm)
+                    throw new Error('Explicit user confirmation required after reviewing this action; pass --confirm only after user approval');
+                const input = options.inputJson ? JSON.parse(readFileSync(String(options.inputJson), 'utf8')) : {};
+                if (!input || typeof input !== 'object' || Array.isArray(input))
+                    throw new Error('Input JSON must be an object');
+                const params = {};
+                for (const field of required)
+                    params[field] = options[field.replace(/_([a-z])/g, (_, c) => c.toUpperCase())];
+                const request = sellRequest(operation, params, input);
+                const result = await newBackendClient(loadConfig()).sellRequest(request);
+                process.stdout.write(JSON.stringify({ status: 'ok', operation: operation.command, result: result ?? null }, null, 2) + '\n');
+            }
+            catch (error) {
+                process.exitCode = 1;
+                process.stdout.write(JSON.stringify({ status: 'error', operation: operation.command, message: error instanceof Error ? error.message : 'Sell operation failed', next: 'itpay sell guide --json' }, null, 2) + '\n');
+            }
+        });
+    }
+    registerLocal(sell);
+    registerSync(sell);
+    sell.commands.find(command => command.name() === "workflow").command("preview").option("--project <directory>", "Project directory", ".").action(async (options) => { const result = await preview(options.project); process.stdout.write(JSON.stringify({ url: result.url, instruction: "Open this local URL to inspect the saved workflow" }) + "\n"); });
+    sell.command("mcp").description("Serve local Seller MCP over stdio").requiredOption("--stdio").option("--project <directory>", "Project directory", ".").action(async (options) => { await serveSellMCP(options.project); });
+    const submission = sell.commands.find(command => command.name() === "submission");
+    submission.command("watch").requiredOption("--merchant-id <id>").requiredOption("--submission-id <id>").option("--timeout <seconds>", "Maximum wait", "120").option("--json").action(async (options) => {
+        const timeout = Number(options.timeout);
+        if (!Number.isFinite(timeout) || timeout < 0 || timeout > 600)
+            throw new Error("timeout must be between 0 and 600");
+        const backend = newBackendClient(loadConfig()), until = Date.now() + timeout * 1000;
+        for (;;) {
+            const result = await backend.sellRequest({ method: "GET", path: "/v1/seller/organizations/" + encodeURIComponent(options.merchantId) + "/service-submissions/" + encodeURIComponent(options.submissionId) });
+            if (!["submitted", "pending", "under_review"].includes(result.status) || Date.now() >= until) {
+                process.stdout.write(JSON.stringify({ status: result.status, result }) + "\n");
+                break;
+            }
+            await new Promise(resolve => setTimeout(resolve, 2000));
+        }
+    });
+    return sell;
+}

package/dist/src/sell/contract.js

@@ -0,0 +1,86 @@
+const org = "/v1/seller/organizations/{merchant_id}";
+const draft = `${org}/service-drafts/{draft_id}`;
+const read = "itpay.seller.read", write = "itpay.seller.write", test = "itpay.seller.test", submit = "itpay.seller.submit";
+export const SELL_GUIDE = {
+    version: "itpay.sell.v1", command: "itpay sell", truth: "workflow.yaml",
+    steps: ["auth", "setup", "sources", "workflow", "local_test", "confirm", "push", "platform_verification", "pricing", "submission", "publication"],
+    rules: [
+        "Use the authenticated user's existing merchant. KYB and payout changes remain in the dashboard.",
+        "Resolve every API against its declared method, Content-Type, parameters, response schema and locked version. Ask for missing inputs; never guess credentials or change contracts.",
+        "Only saved versions may run. A run is not a saved version. Local evidence cannot grant platform test approval.",
+        "Use the platform node catalog and validator for supported pricing, quotas, confirmation and durable fulfillment. Every paid success path must cross payment and delivery gates.",
+        "Use own credentials for local requests. Platform-managed credentials stay on the platform. Mark execution location honestly.",
+        "Present side effects before live tests. Unknown results stop automatic retries. Local payment/refund/delivery gates are simulated, never real funds.",
+        "Show the exact workflow and version before user confirmation. Preview price, delivery and current terms before explicit submission approval.",
+        "Use platform guide for next actions. Submission is not publication: only an actual admin approval publishes the service."
+    ]
+};
+export const SELL_OPERATIONS = [
+    { command: "status", method: "GET", path: "/v1/seller/organizations", scope: read, fields: {}, description: "List existing merchant memberships" },
+    { command: "guide", method: "GET", path: `${org}/guide`, scope: read, fields: { draft_id: "string" }, optional: ["draft_id"], description: "Read authoritative publication blockers and next actions" },
+    { command: "library search", method: "GET", path: "/v1/library/apis", scope: read, fields: { q: "string" }, optional: ["q"], description: "Search available API contracts" },
+    { command: "library get", method: "GET", path: "/v1/library/apis/{library_api_id}", scope: read, fields: {}, description: "Inspect an API contract" },
+    { command: "sources list", method: "GET", path: `${org}/api-intakes`, scope: read, fields: {}, description: "List imported API sources" },
+    { command: "sources inspect", method: "GET", path: `${org}/api-intakes/{intake_id}`, scope: read, fields: {}, description: "Inspect imported operations and verification results" },
+    { command: "sources import", method: "POST", path: `${org}/api-intakes`, scope: write, fields: { provider_key: "string", source_url: "string", document: "document", media_type: "string" }, optional: ["source_url", "document", "media_type"], description: "Import an OpenAPI source without inventing request contracts" },
+    { command: "sources library", method: "POST", path: `${org}/api-intakes/from-library`, scope: write, fields: { library_api_id: "string" }, description: "Bind a platform library source" },
+    { command: "sources probe", method: "POST", path: `${org}/api-intakes/{intake_id}/probe`, scope: test, fields: { credential_profile_id: "string", operation_inputs: "object" }, description: "Verify selected API requests on the platform", confirmation: true },
+    { command: "credentials status", method: "GET", path: `${org}/provider-credential-profiles`, scope: read, fields: {}, description: "Read credential bindings without secret values" },
+    { command: "services list", method: "GET", path: `${org}/service-drafts`, scope: read, fields: {}, description: "List own service drafts and publication state" },
+    { command: "services create", method: "POST", path: `${org}/service-drafts`, scope: write, fields: { service_id: "string", public_name: "string" }, description: "Create a platform service draft" },
+    { command: "services icon", method: "PUT", path: `${draft}/icon/content`, scope: write, fields: { content_base64: "string" }, description: "Upload a PNG/JPEG service icon, max 512 KiB, as signed JSON" },
+    { command: "services get", method: "GET", path: `${draft}/workflow`, scope: read, fields: {}, description: "Read the current workflow and service settings" },
+    { command: "workflow catalog", method: "GET", path: `${org}/node-catalog`, scope: read, fields: {}, description: "Read exact supported node templates and required configuration" },
+    { command: "workflow plan", method: "POST", path: `${draft}/orchestration-runs`, scope: test, fields: { expected_revision: "number", instruction: "string", api_intake_ids: "array", credential_profile_bindings: "object" }, description: "Explicitly use ItPay AI planning and platform verification", confirmation: true },
+    { command: "workflow plan-get", method: "GET", path: `${draft}/orchestration-runs/{run_id}`, scope: read, fields: {}, description: "Read the AI candidate and diagnostics" },
+    { command: "workflow plan-apply", method: "POST", path: `${draft}/orchestration-runs/{run_id}/apply`, scope: write, fields: { expected_revision: "number" }, description: "Apply a reviewed AI candidate to the draft", confirmation: true },
+    { command: "workflow upload", method: "PUT", path: `${draft}/workflow`, scope: write, fields: { expected_revision: "number", public_name: "string", arazzo: "object" }, optional: ["public_name"], description: "Update the platform workflow with optimistic concurrency" },
+    { command: "workflow validate-platform", method: "POST", path: `${draft}/workflow/validate`, scope: write, fields: {}, description: "Validate using the same public runtime rules as approval" },
+    { command: "workflow versions list-platform", method: "GET", path: `${draft}/workflow/versions`, scope: read, fields: {}, description: "List explicitly saved platform versions" },
+    { command: "workflow versions save-platform", method: "POST", path: `${draft}/workflow/versions`, scope: write, fields: { name: "string", source: "string", arazzo_document: "string", expected_revision: "number" }, description: "Save an explicit immutable platform version" },
+    { command: "workflow versions delete-platform", method: "DELETE", path: `${draft}/workflow/versions/{version_id}`, scope: write, fields: { expected_revision: "number" }, description: "Delete an eligible saved version and its runs", confirmation: true },
+    { command: "fixtures get", method: "GET", path: `${draft}/fixtures`, scope: read, fields: {}, description: "Read test inputs" },
+    { command: "fixtures set", method: "PUT", path: `${draft}/fixtures`, scope: write, fields: { expected_revision: "number", fixtures: "array" }, description: "Save explicit test inputs" },
+    { command: "pricing get", method: "GET", path: `${draft}/workflow`, scope: read, fields: {}, description: "Read the current price and refund policy" },
+    { command: "pricing set", method: "PUT", path: `${draft}/pricing`, scope: write, fields: { expected_revision: "number", pricing: "object", policy: "object" }, description: "Set per-call price and platform refund policy" },
+    { command: "verify", method: "POST", path: `${draft}/validation-runs`, scope: test, fields: { workflow_version_id: "string", expected_semantic_revision: "number", expected_fixture_revision: "number" }, description: "Start platform verification for an explicitly saved version", confirmation: true },
+    { command: "tests start-checkout", method: "POST", path: `${draft}/live-checkout-tests`, scope: test, fields: { expected_revision: "number", agent_instance_id: "string" }, description: "Dev admin only: freeze one success fixture into a private real-checkout test bound to your registered Agent. Payment still requires user confirmation; this does not publish the service.", confirmation: true },
+    { command: "tests accept-checkout", method: "POST", path: `${draft}/live-checkout-tests/{execution_id}/accept`, scope: test, fields: {}, description: "Record server-observed issued tickets and completed delivery as evidence for the exact tested revision. Never synthesizes payment or issuance.", confirmation: true },
+    { command: "runs get", method: "GET", path: `${draft}/validation-runs/{run_id}`, scope: read, fields: {}, description: "Inspect platform test nodes and diagnostics" },
+    { command: "runs confirm", method: "POST", path: `${draft}/validation-runs/{run_id}/confirm`, scope: test, fields: { risk_hash: "string" }, description: "Confirm the exact disclosed platform test side effects", confirmation: true },
+    { command: "submission preview", method: "GET", path: `${org}/guide`, scope: read, fields: { draft_id: "string" }, description: "Read publication readiness and required agreements" },
+    { command: "submission submit", method: "POST", path: `${draft}/submit`, scope: submit, fields: { expected_revision: "number", terms_version: "string", confirmations: "array" }, description: "Submit the confirmed version for review, never approve it", confirmation: true },
+    { command: "submission get", method: "GET", path: `${org}/service-submissions/{submission_id}`, scope: read, fields: {}, description: "Read the actual review/publication result" },
+    { command: "submission withdraw", method: "POST", path: `${org}/service-submissions/{submission_id}/withdraw`, scope: submit, fields: {}, description: "Withdraw own pending submission", confirmation: true },
+];
+export function sellRequest(operation, params, input = {}) {
+    let path = operation.path.replace(/\{(\w+)\}/g, (_, key) => {
+        const value = params[key];
+        if (typeof value !== "string" || !value.trim())
+            throw new Error(`${key} is required`);
+        return encodeURIComponent(value);
+    });
+    for (const key of Object.keys(input))
+        if (!operation.fields[key])
+            throw new Error(`Unsupported field: ${key}`);
+    for (const [key, type] of Object.entries(operation.fields)) {
+        const value = input[key];
+        if (value === undefined && operation.optional?.includes(key))
+            continue;
+        const valid = type === "document" ? (typeof value === "string" || (!!value && typeof value === "object" && !Array.isArray(value))) : type === "array" ? Array.isArray(value) : type === "object" ? !!value && typeof value === "object" && !Array.isArray(value) : typeof value === type;
+        if (!valid)
+            throw new Error(`${key} must be ${type}`);
+        if (type === "number" && (!Number.isSafeInteger(value) || Number(value) < 0))
+            throw new Error(`${key} must be a nonnegative integer`);
+    }
+    if (operation.method === "GET") {
+        const query = [];
+        for (const [key, value] of Object.entries(input))
+            if (value !== undefined)
+                query.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+        if (query.length)
+            path += `?${query.join("&")}`;
+        return { path, method: operation.method };
+    }
+    return { path, method: operation.method, body: input };
+}

package/dist/src/sell/local.js

@@ -0,0 +1,260 @@
+import { newBackendClient, loadConfig } from "../state/config.js";
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, rmSync, readdirSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+const hash = (value) => 'sha256:' + createHash('sha256').update(value).digest('hex');
+function read(path) { return JSON.parse(readFileSync(path, 'utf8')); }
+function save(path, value) { mkdirSync(dirname(path), { recursive: true, mode: 0o700 }); const tmp = path + '.' + randomUUID() + '.tmp'; writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 }); renameSync(tmp, path); }
+export function project(directory) { const root = resolve(directory); return { root, state: join(root, '.itpay-sell'), config: read(join(root, 'service.json')), yaml: readFileSync(join(root, 'workflow.yaml'), 'utf8') }; }
+export function localDependencies(state) {
+    const platformPath = join(state, 'platform-dependencies.json');
+    const dependencies = existsSync(platformPath) ? read(platformPath) : {};
+    const sources = join(state, 'sources');
+    if (existsSync(sources))
+        for (const file of readdirSync(sources)) {
+            const source = read(join(sources, file));
+            for (const operation of source.operations)
+                dependencies[operation.provider_operation_version_id] = {
+                    provider_operation_version_id: operation.provider_operation_version_id,
+                    provider_key: source.provider_key, operation_key: operation.operation_key,
+                    operation_hash: operation.operation_hash, operation: operation.operation,
+                    request_schema: operation.request_schema, response_schema: operation.response_schema,
+                    retry_policy: operation.retry_policy ?? {},
+                };
+        }
+    return dependencies;
+}
+export async function companion(input, onEvent) {
+    const target = `${process.platform === 'win32' ? 'windows' : process.platform}-${process.arch === 'x64' ? 'amd64' : process.arch}/itpay-sell${process.platform === 'win32' ? '.exe' : ''}`;
+    const packaged = fileURLToPath(new URL(`../../../bin/${target}`, import.meta.url));
+    const binary = process.env.ITPAY_SELL_RUNNER ?? (existsSync(packaged) ? packaged : fileURLToPath(new URL(`../../bin/${target}`, import.meta.url)));
+    if (!existsSync(binary))
+        throw new Error(`Local runner missing for ${process.platform}-${process.arch}; install a CLI package including its native runner`);
+    return new Promise((done, fail) => {
+        const child = spawn(binary, [], { stdio: ['pipe', 'pipe', 'pipe'] });
+        let buffer = '', stderr = '';
+        const events = [];
+        child.on('error', fail);
+        child.stderr.on('data', chunk => { stderr += String(chunk).slice(0, 2000); });
+        child.stdout.on('data', chunk => {
+            buffer += String(chunk);
+            let index;
+            while ((index = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, index);
+                buffer = buffer.slice(index + 1);
+                try {
+                    const event = JSON.parse(line);
+                    events.push(event);
+                    onEvent?.(event);
+                }
+                catch {
+                    child.kill();
+                    fail(new Error('Invalid local runner response'));
+                }
+            }
+        });
+        child.on('close', code => {
+            if (code !== 0)
+                fail(new Error(events.find(event => event.type === 'error')?.value?.message ?? stderr ?? 'Local runner failed'));
+            else
+                done(events);
+        });
+        child.stdin.on('error', () => { });
+        child.stdin.end(JSON.stringify(input));
+    });
+}
+function last(events, type) { return [...events].reverse().find(event => event.type === type)?.value; }
+export async function localAction(action, directory, options) {
+    const root = resolve(directory), state = join(root, '.itpay-sell');
+    if (action === 'init') {
+        if (existsSync(join(root, 'service.json')) || existsSync(join(root, 'workflow.yaml')) || existsSync(state))
+            throw new Error('Project already exists; existing files were not replaced');
+        mkdirSync(root, { recursive: true });
+        const config = { format_version: 1, service_id: options.serviceId ?? '', public_name: options.name ?? '', pricing: { billing_mode: 'per_call' }, policy: {}, fixtures: [] };
+        save(join(root, 'service.json'), config);
+        writeFileSync(join(root, 'workflow.yaml'), '# Generate the workflow from locked API contracts using itpay sell guide.\n', { flag: 'wx' });
+        save(join(state, 'versions.json'), { versions: [] });
+        return { root, next: 'itpay sell sources add --file <openapi> --provider-key <key>', missing: ['workflow', 'price', 'fixtures'] };
+    }
+    const p = project(root);
+    if (action === 'workflow import') {
+        if (!options.file)
+            throw new Error('--file is required');
+        const yaml = readFileSync(resolve(options.file), 'utf8');
+        const validation = last(await companion({ action: 'validate', dependencies: localDependencies(state), document: yaml, pricing: p.config.pricing, policy: p.config.policy }), 'validation');
+        const backup = join(state, 'imports', hash(p.yaml).slice(7) + '.yaml');
+        mkdirSync(dirname(backup), { recursive: true, mode: 0o700 });
+        writeFileSync(backup, p.yaml, { mode: 0o600 });
+        writeFileSync(join(root, 'workflow.yaml'), yaml);
+        return { imported: true, validation, next: 'Resolve all imported API references and save a new workflow version' };
+    }
+    if (action === 'config') {
+        if (options.file) {
+            const value = read(resolve(options.file));
+            for (const key of Object.keys(value))
+                if (!['service_id', 'public_name', 'pricing', 'policy', 'fixtures', 'merchant_id', 'draft_id', 'expected_revision'].includes(key))
+                    throw new Error('Unsupported setting: ' + key);
+            save(join(root, 'service.json'), { ...p.config, ...value });
+        }
+        return read(join(root, 'service.json'));
+    }
+    if (action === 'sources add') {
+        if ((!options.file && !options.url) || !options.providerKey)
+            throw new Error('--file or --url, and --provider-key are required');
+        if (options.file && options.url)
+            throw new Error('Choose file or URL, not both');
+        const raw = options.file ? readFileSync(resolve(options.file), 'utf8') : last(await companion({ action: 'fetch', source_url: options.url }), 'source').document;
+        const id = hash(raw).slice(7);
+        const operations = last(await companion({ action: 'compile', document: raw, provider_key: options.providerKey }), 'compiled');
+        const path = join(state, 'sources', id + '.json');
+        save(path, { provider_key: options.providerKey, source_hash: hash(raw), original: raw, operations });
+        return { source_hash: hash(raw), operations, instruction: 'Use these exact contracts when constructing workflow.yaml; bind local credentials by environment reference' };
+    }
+    if (action === 'credentials bind') {
+        if (!options.profile || !options.file)
+            throw new Error('--profile and --file are required; file must map credential fields to environment variable names, not secret values');
+        const bindings = read(resolve(options.file));
+        for (const value of Object.values(bindings))
+            if (typeof value !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value))
+                throw new Error('Credential bindings must be environment variable names');
+        const path = join(state, 'credentials.json');
+        save(path, { ...(existsSync(path) ? read(path) : {}), [options.profile]: bindings });
+        return { profile: options.profile, bound_fields: Object.keys(bindings) };
+    }
+    if (action === 'credentials upload') {
+        if (!options.confirm || !options.profile || !options.providerKey || !options.merchantId)
+            throw new Error('Merchant, provider, local profile and explicit confirmation are required');
+        const bindings = read(join(state, 'credentials.json'))[options.profile];
+        if (!bindings)
+            throw new Error('Local profile not bound');
+        const secrets = {};
+        for (const [field, env] of Object.entries(bindings)) {
+            const value = process.env[String(env)];
+            if (!value)
+                throw new Error('Missing credential environment for ' + field);
+            secrets[field] = value;
+        }
+        const result = await newBackendClient(loadConfig()).sellRequest({ method: 'POST', path: '/v1/seller/organizations/' + encodeURIComponent(options.merchantId) + '/provider-credential-profiles', body: { provider_key: options.providerKey, profile_key: options.profile, display_name: options.name ?? options.profile, environment: options.environment ?? 'sandbox', secrets, metadata: options.file ? read(resolve(options.file)) : {} } });
+        return result;
+    }
+    const versionsPath = join(state, 'versions.json');
+    const versions = read(versionsPath);
+    if (action === 'workflow versions save') {
+        const validation = last(await companion({ action: 'validate', dependencies: localDependencies(state), document: p.yaml, pricing: p.config.pricing, policy: p.config.policy }), 'validation');
+        const version = { version_id: randomUUID(), name: options.name ?? 'Saved version', hash: hash(p.yaml), config_hash: hash(JSON.stringify(p.config)), created_at: new Date().toISOString() };
+        save(join(state, 'versions', version.version_id + '.json'), { ...version, document: p.yaml, config: p.config });
+        versions.versions.push(version);
+        versions.selected = version.version_id;
+        save(versionsPath, versions);
+        return { ...version, validation };
+    }
+    if (action === 'workflow versions list')
+        return versions;
+    if (action === 'workflow versions use' || action === 'workflow versions delete') {
+        const version = versions.versions.find((v) => v.version_id === options.version);
+        if (!version)
+            throw new Error('Saved version not found');
+        if (action.endsWith('use')) {
+            const saved = read(join(state, 'versions', version.version_id + '.json'));
+            writeFileSync(join(root, 'workflow.yaml'), saved.document);
+            save(join(root, 'service.json'), saved.config);
+            versions.selected = version.version_id;
+        }
+        else {
+            if (!options.confirm)
+                throw new Error('Confirm version deletion with --confirm');
+            versions.versions = versions.versions.filter((v) => v.version_id !== version.version_id);
+            if (versions.selected === version.version_id)
+                delete versions.selected;
+            rmSync(join(state, 'versions', version.version_id + '.json'));
+            const runs = join(state, 'runs');
+            if (existsSync(runs))
+                for (const run of readdirSync(runs)) {
+                    const meta = join(runs, run, 'meta.json');
+                    if (existsSync(meta) && read(meta).version_id === version.version_id)
+                        rmSync(join(runs, run), { recursive: true });
+                }
+        }
+        save(versionsPath, versions);
+        return versions;
+    }
+    if (action === 'workflow validate')
+        return last(await companion({ action: 'validate', dependencies: localDependencies(state), document: p.yaml, pricing: p.config.pricing, policy: p.config.policy }), 'validation');
+    if (action === 'test get') {
+        if (!options.run)
+            throw new Error('--run is required');
+        return read(join(state, 'runs', safeID(options.run), 'report.json'));
+    }
+    const selected = versions.versions.find((v) => v.version_id === versions.selected);
+    if (!selected || selected.hash !== hash(p.yaml) || selected.config_hash !== hash(JSON.stringify(p.config)))
+        throw new Error('Save the current workflow and configuration before confirming or running');
+    if (action === 'workflow confirm') {
+        if (!options.confirm)
+            return { version: selected, config: p.config, workflow: p.yaml, instruction: 'Review this exact workflow and service configuration with the user, then confirm' };
+        save(join(state, 'confirmation.json'), { version_id: selected.version_id, hash: selected.hash, config_hash: selected.config_hash, confirmed_at: new Date().toISOString() });
+        return { confirmed: selected };
+    }
+    if (action === 'test run' || action === 'test resume') {
+        if (!options.confirm)
+            throw new Error('Live Provider calls may cost money or change data. Review dependencies and confirm with --confirm');
+        const dependencies = localDependencies(state);
+        const credentials = {};
+        const credentialPath = join(state, 'credentials.json');
+        if (existsSync(credentialPath))
+            for (const [profile, fields] of Object.entries(read(credentialPath))) {
+                const secrets = {};
+                for (const [field, env] of Object.entries(fields)) {
+                    if (!process.env[String(env)])
+                        throw new Error(`Missing local environment variable for credential field ${field}`);
+                    secrets[field] = process.env[String(env)];
+                }
+                credentials[profile] = { ID: profile, Secrets: secrets, Metadata: {} };
+            }
+        if (action === 'test resume' && !options.run)
+            throw new Error('--run is required for resume');
+        const runID = options.run ? safeID(options.run) : randomUUID(), runDirectory = join(state, 'runs', runID);
+        const metaPath = join(runDirectory, 'meta.json');
+        if (action === 'test resume' && !existsSync(metaPath))
+            throw new Error('Run does not exist');
+        if (existsSync(metaPath) && read(metaPath).version_id !== selected.version_id)
+            throw new Error('Run belongs to a different version');
+        save(metaPath, { run_id: runID, version_id: selected.version_id, hash: selected.hash, config_hash: selected.config_hash });
+        save(join(state, "last-run.json"), { run_id: runID });
+        const events = await companion({ action: 'run', document: p.yaml, pricing: p.config.pricing, policy: p.config.policy, fixtures: p.config.fixtures, dependencies, credentials, run_directory: runDirectory, confirmed: true }, event => {
+            if (event.type === 'nodes')
+                save(join(runDirectory, 'nodes.json'), event.value);
+        });
+        const result = last(events, 'result');
+        save(join(runDirectory, 'report.json'), result);
+        return { run_id: runID, ...result };
+    }
+    throw new Error('Unsupported local action: ' + action);
+}
+function safeID(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        throw new Error('Invalid local run ID');
+    return value;
+}
+export const LOCAL_ACTIONS = ['init', 'config', 'workflow import', 'sources add', 'credentials bind', 'credentials upload', 'workflow validate', 'workflow confirm', 'workflow versions save', 'workflow versions list', 'workflow versions use', 'workflow versions delete', 'test run', 'test resume', 'test get'];
+export function registerLocal(sell) {
+    for (const name of LOCAL_ACTIONS) {
+        let parent = sell;
+        const parts = name.split(' ');
+        const leaf = parts.pop();
+        for (const part of parts) {
+            parent = parent.commands.find(cmd => cmd.name() === part) ?? parent.command(part);
+        }
+        parent.command(leaf).description('Local Sell: ' + name).option('--project <directory>', 'Project directory', '.').option('--file <file>').option('--url <https-url>').option('--name <name>').option('--service-id <id>').option('--provider-key <key>').option('--profile <id>').option('--merchant-id <id>').option('--environment <environment>').option('--version-id <id>').option('--run <id>').option('--confirm').option('--json').action(async (options) => {
+            try {
+                const result = await localAction(name.replace('list-local', 'list'), options.project, { ...options, version: options.versionId });
+                process.stdout.write(JSON.stringify({ status: 'ok', result }, null, 2) + '\n');
+            }
+            catch (error) {
+                process.exitCode = 1;
+                process.stdout.write(JSON.stringify({ status: 'error', message: error instanceof Error ? error.message : 'Local action failed' }) + '\n');
+            }
+        });
+    }
+}