@liquiditytech/rapidx-cli 1.0.26

package/README.md

@@ -0,0 +1,81 @@
+# RapidX CLI
+
+RapidX CLI provides a local command-line entrypoint and MCP server mode for RapidX account, market, order, position, and portfolio workflows.
+
+The package is distributed as `@liquiditytech/rapidx-cli`.
+
+## Install
+
+```bash
+npm install -g @liquiditytech/rapidx-cli
+```
+
+## Configure
+
+Provide credentials through the agent host secret mechanism or environment variables:
+
+```bash
+LTP_ACCESS_KEY=<your-access-key>
+LTP_SECRET_KEY=<your-secret-key>
+LTP_API_HOST=<provided-api-host>
+```
+
+Do not commit credentials into project files.
+
+## Use As CLI
+
+```bash
+rapidx schema --json
+rapidx self-check --read-only --json
+rapidx market get-ticker --input '{"symbol":"BINANCE_PERP_BTC_USDT"}' --json
+```
+
+Trade writes use a preview-first flow:
+
+```bash
+rapidx order place-preview --input '{"symbol":"BINANCE_PERP_BTC_USDT","side":"BUY","orderType":"LIMIT","price":"65000","quantity":"0.001","maxNotional":"10","clientOrderId":"example-001"}' --json
+```
+
+Submit write operations only after reviewing the preview result and providing the returned `previewId` plus `confirmation.submitToken` as `continueConsentId`.
+
+## Use As MCP
+
+Configure the agent host to start the MCP server with:
+
+```json
+{
+  "command": "rapidx",
+  "args": ["mcp", "serve"],
+  "env": {
+    "LTP_ACCESS_KEY": "<your-access-key>",
+    "LTP_SECRET_KEY": "<your-secret-key>",
+        "LTP_API_HOST": "<provided-api-host>"
+  }
+}
+```
+
+MCP tools expose the same capabilities as the CLI through structured tool schemas. Trade-write tools require preview and consent fields.
+
+## Skills
+
+RapidX skills are distributed separately through GitHub. Use the config skill to guide installation, credential configuration, MCP registration, access review, and read-only self-check. Use the trading skill for normal query and preview-first trading workflows.
+
+```bash
+npx skills add git@github.com:LiquidityTech/ltp-rapidx-skill.git \
+  --skill ltp-rapidx-config \
+  --skill ltp-rapidx-trading \
+  -a codex -y
+```
+
+If the skills repository is public and the agent host has HTTPS GitHub access, `LiquidityTech/ltp-rapidx-skill` may be used instead of the SSH URL. Private repositories should use the SSH URL so Git can use the configured deploy key or user key.
+
+## Verification
+
+After installation:
+
+```bash
+rapidx schema --json
+rapidx self-check --read-only --json
+```
+
+Do not treat missing real API evidence as success. If RapidX cannot be called, the expected status is `NOT_VERIFIED`.

package/dist/cli/audit.js

@@ -0,0 +1,10 @@
+import { AuditWriter } from "../core/index.js";
+const writer = new AuditWriter(process.stderr);
+export function writeCliAudit(type, status, payload) {
+    const result = writer.write({
+        type,
+        status,
+        payload
+    });
+    return result.auditId;
+}

package/dist/cli/bin.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { stdin as input, stdout, stderr } from "node:process";
+import { dispatchCli } from "./commands/index.js";
+import { parseArgv } from "./parser.js";
+import { startMcpServer } from "./mcp-entry.js";
+import { formatCliHelp, formatCliVersion, isHelpArg, isVersionArg } from "./help.js";
+async function readStdinIfPiped() {
+    if (input.isTTY) {
+        return "";
+    }
+    const chunks = [];
+    for await (const chunk of input) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.some(isHelpArg)) {
+        stdout.write(`${formatCliHelp()}\n`);
+        return;
+    }
+    if (argv.some(isVersionArg)) {
+        stdout.write(`${formatCliVersion()}\n`);
+        return;
+    }
+    if (argv[0] === "mcp" && argv[1] === "serve") {
+        await startMcpServer();
+        return;
+    }
+    const parsed = parseArgv(argv, { stdin: await readStdinIfPiped() });
+    const result = await dispatchCli(parsed);
+    stdout.write(`${JSON.stringify(result)}\n`);
+    if (!result.ok) {
+        process.exitCode = 1;
+    }
+}
+main().catch((error) => {
+    stderr.write(`${JSON.stringify({ ok: false, status: "FAIL", code: "RCLI00001", message: error instanceof Error ? error.message : String(error) })}\n`);
+    process.exitCode = 1;
+});

package/dist/cli/commands/account.js

@@ -0,0 +1,34 @@
+import { executeRapidXCapability, findCapabilityById, normalizeUnknownError } from "../../core/index.js";
+import { writeCliAudit } from "../audit.js";
+import { fail, ok } from "../envelope.js";
+import { enforceCliPreviewGate } from "./trade-gate.js";
+const ACCOUNT_CAPABILITY_BY_ACTION = {
+    overview: "account.overview",
+    balance: "account.balance",
+    "set-position-mode": "account.set-position-mode"
+};
+export async function runAccountCommand(action, input) {
+    const capabilityId = ACCOUNT_CAPABILITY_BY_ACTION[action];
+    if (!capabilityId) {
+        return fail("RCLI12001", `Unknown account command: ${action}`, "FAIL", `rapidx account ${action}`);
+    }
+    const capability = findCapabilityById(capabilityId);
+    if (!capability) {
+        return fail("RCLI30002", `Missing capability: ${capabilityId}`, "FAIL", `rapidx account ${action}`);
+    }
+    const blocked = enforceCliPreviewGate(capability, input, `rapidx account ${action}`);
+    if (blocked) {
+        return blocked;
+    }
+    try {
+        const data = await executeRapidXCapability(capabilityId, input);
+        const auditId = capability.operationType === "TRADE_WRITE"
+            ? writeCliAudit("trade-write", "PASS", { command: `rapidx account ${action}`, capabilityId })
+            : undefined;
+        return ok(data, `rapidx account ${action}`, "PASS", "real_tool_call", auditId);
+    }
+    catch (error) {
+        const productError = normalizeUnknownError(error, "RCLI01001");
+        return fail(productError.code.replace(/^RCORE/, "RCLI"), productError.message, productError.status, `rapidx account ${action}`);
+    }
+}

package/dist/cli/commands/algo.js

@@ -0,0 +1,35 @@
+import { executeRapidXCapability, findCapabilityById, normalizeUnknownError } from "../../core/index.js";
+import { writeCliAudit } from "../audit.js";
+import { fail, ok } from "../envelope.js";
+import { enforceCliPreviewGate } from "./trade-gate.js";
+const ALGO_CAPABILITY_BY_ACTION = {
+    place: "algo.place",
+    amend: "algo.amend",
+    cancel: "algo.cancel",
+    list: "algo.list"
+};
+export async function runAlgoCommand(action, input) {
+    const capabilityId = ALGO_CAPABILITY_BY_ACTION[action];
+    if (!capabilityId) {
+        return fail("RCLI12001", `Unknown algo command: ${action}`, "FAIL", `rapidx algo ${action}`);
+    }
+    const capability = findCapabilityById(capabilityId);
+    if (!capability) {
+        return fail("RCLI30002", `Missing capability: ${capabilityId}`, "FAIL", `rapidx algo ${action}`);
+    }
+    const blocked = enforceCliPreviewGate(capability, input, `rapidx algo ${action}`);
+    if (blocked) {
+        return blocked;
+    }
+    try {
+        const data = await executeRapidXCapability(capabilityId, input);
+        const auditId = capability.operationType === "TRADE_WRITE"
+            ? writeCliAudit("trade-write", "PASS", { command: `rapidx algo ${action}`, capabilityId })
+            : undefined;
+        return ok(data, `rapidx algo ${action}`, "PASS", "real_tool_call", auditId);
+    }
+    catch (error) {
+        const productError = normalizeUnknownError(error, "RCLI12001");
+        return fail(productError.code.replace(/^RCORE/, "RCLI"), productError.message, productError.status, `rapidx algo ${action}`);
+    }
+}

package/dist/cli/commands/auth.js

@@ -0,0 +1,22 @@
+import { makeCredentialRef, resolveCredential } from "../../core/index.js";
+import { fail, ok } from "../envelope.js";
+export function runAuthCheck(input) {
+    try {
+        const source = typeof input.source === "string" ? input.source : "env";
+        const material = {};
+        if (typeof input.accessKey === "string") {
+            material.accessKey = input.accessKey;
+        }
+        if (typeof input.secretKey === "string") {
+            material.secretKey = input.secretKey;
+        }
+        const credential = resolveCredential({
+            ref: makeCredentialRef(source),
+            material
+        });
+        return ok({ status: "PASS", maskedAccessKey: credential.maskedAccessKey }, "rapidx auth check");
+    }
+    catch (error) {
+        return fail("RCLI01001", error instanceof Error ? error.message : String(error), "NOT_VERIFIED", "rapidx auth check");
+    }
+}

package/dist/cli/commands/config.js

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { makeCredentialRef } from "../../core/index.js";
+import { ok } from "../envelope.js";
+export function runConfigCommand(action, input) {
+    const filePath = resolveConfigFile();
+    const config = loadConfig(filePath);
+    if (action === "set") {
+        const key = String(input.key ?? "");
+        config[key] = shouldRedactConfigKey(key) ? "[REDACTED]" : input.value;
+        saveConfig(filePath, config);
+        return ok({ updated: [key], credentialRef: makeCredentialRef("chat-secret") }, "rapidx config set");
+    }
+    if (action === "unset") {
+        const key = String(input.key ?? "");
+        delete config[key];
+        saveConfig(filePath, config);
+        return ok({ unset: key }, "rapidx config unset");
+    }
+    if (action === "get") {
+        const key = String(input.key ?? "");
+        return ok({ key, value: config[key] ?? null }, "rapidx config get");
+    }
+    return ok({ entries: config }, "rapidx config list");
+}
+function resolveConfigFile(env = process.env, cwd = process.cwd()) {
+    const stateDir = env.RAPIDX_STATE_DIR ? resolve(env.RAPIDX_STATE_DIR) : resolve(cwd, ".rapidx");
+    return join(stateDir, "config.json");
+}
+function loadConfig(filePath) {
+    if (!existsSync(filePath)) {
+        return {};
+    }
+    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {};
+    }
+    return parsed;
+}
+function saveConfig(filePath, config) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+function shouldRedactConfigKey(key) {
+    return /secret|token|password|credential|access[_-]?key|api[_-]?key/i.test(key);
+}

package/dist/cli/commands/doctor.js

@@ -0,0 +1,42 @@
+import { buildCompatibilityReport, getSchemaResult } from "../../core/index.js";
+import { checkInvocationMode } from "../invocation-checker.js";
+import { ok } from "../envelope.js";
+export function runDoctorCommand(input) {
+    const invocationInput = {
+        commandLine: typeof input.commandLine === "string" ? input.commandLine : "rapidx doctor --json"
+    };
+    if (typeof input.preflightError === "string") {
+        invocationInput.preflightError = input.preflightError;
+    }
+    const invocation = checkInvocationMode(invocationInput);
+    const compatibilityInput = {};
+    if (typeof input.mcpSchemaVersion === "string") {
+        compatibilityInput.mcpSchemaVersion = input.mcpSchemaVersion;
+    }
+    if (typeof input.skillsVersion === "string") {
+        compatibilityInput.skillsVersion = input.skillsVersion;
+    }
+    if (typeof input.skillsSchemaVersion === "string") {
+        compatibilityInput.skillsSchemaVersion = input.skillsSchemaVersion;
+    }
+    const compatibility = buildCompatibilityReport(compatibilityInput);
+    const credentialSource = {
+        LTP_ACCESS_KEY: Boolean(process.env.LTP_ACCESS_KEY),
+        LTP_SECRET_KEY: Boolean(process.env.LTP_SECRET_KEY),
+        LTP_API_HOST: Boolean(process.env.LTP_API_HOST)
+    };
+    const doctorStatus = !invocation.compliant || compatibility.status === "BLOCKED" ? "FAIL" : "PASS";
+    return ok({
+        schemaVersion: getSchemaResult().schemaVersion,
+        invocation,
+        compatibility,
+        credentialSource,
+        checks: [
+            { name: "node", status: "PASS" },
+            { name: "canonical-schema", status: "PASS" },
+            { name: "version-compatibility", status: compatibility.status },
+            { name: "credential-source", status: credentialSource.LTP_ACCESS_KEY && credentialSource.LTP_SECRET_KEY && credentialSource.LTP_API_HOST ? "PASS" : "NOT_VERIFIED" },
+            { name: "invocation", status: invocation.compliant ? "PASS" : "FAIL" }
+        ]
+    }, "rapidx doctor --json", doctorStatus);
+}

package/dist/cli/commands/index.js

@@ -0,0 +1,73 @@
+import { checkInvocationMode } from "../invocation-checker.js";
+import { fail, ok } from "../envelope.js";
+import { runAccountCommand } from "./account.js";
+import { runAlgoCommand } from "./algo.js";
+import { runAuthCheck } from "./auth.js";
+import { runConfigCommand } from "./config.js";
+import { runDoctorCommand } from "./doctor.js";
+import { runMarketCommand } from "./market.js";
+import { runOrderCommand } from "./order.js";
+import { runPositionCommand } from "./position.js";
+import { runSchemaCommand } from "./schema.js";
+import { runSelfCheckCommand, runTradingVerificationCommand } from "./self-check.js";
+import { runTradeCommand } from "./trade.js";
+import { runUpdateCommand } from "./update.js";
+export async function dispatchCli(parsed) {
+    const [domain, action, subAction] = parsed.commandParts;
+    if (!domain) {
+        return fail("RCLI00001", "Command is required.");
+    }
+    if (domain === "schema") {
+        return runSchemaCommand();
+    }
+    if (domain === "doctor") {
+        return runDoctorCommand(parsed.input);
+    }
+    if (domain === "auth" && action === "check") {
+        return runAuthCheck(parsed.input);
+    }
+    if (domain === "config") {
+        return runConfigCommand(action ?? "list", parsed.input);
+    }
+    if (domain === "self-check" && action === "trade-verify") {
+        return runTradingVerificationCommand(parsed.input);
+    }
+    if (domain === "trade" && action === "verify-live") {
+        return runTradingVerificationCommand(parsed.input, "rapidx trade verify-live --json");
+    }
+    if (domain === "self-check") {
+        return runSelfCheckCommand(parsed.input);
+    }
+    if (domain === "update") {
+        return runUpdateCommand(action ?? "check", parsed.input);
+    }
+    if (domain === "invocation" && action === "check") {
+        const invocationInput = {};
+        if (typeof parsed.input.commandLine === "string") {
+            invocationInput.commandLine = parsed.input.commandLine;
+        }
+        if (typeof parsed.input.preflightError === "string") {
+            invocationInput.preflightError = parsed.input.preflightError;
+        }
+        return ok(checkInvocationMode(invocationInput), "rapidx invocation check");
+    }
+    if (domain === "market") {
+        return runMarketCommand(action ?? "get-ticker", parsed.input);
+    }
+    if (domain === "account") {
+        return runAccountCommand(action ?? "overview", parsed.input);
+    }
+    if (domain === "order") {
+        return runOrderCommand(action ?? "list", parsed.input);
+    }
+    if (domain === "trade") {
+        return runTradeCommand(action ?? "preview", parsed.input);
+    }
+    if (domain === "position") {
+        return runPositionCommand(action ?? "list", parsed.input);
+    }
+    if (domain === "algo") {
+        return runAlgoCommand(subAction ?? action ?? "list", parsed.input);
+    }
+    return fail("RCLI12001", `Unknown command: ${parsed.command}`);
+}

package/dist/cli/commands/market.js

@@ -0,0 +1,26 @@
+import { executeRapidXCapability, normalizeUnknownError } from "../../core/index.js";
+import { ok } from "../envelope.js";
+import { fail } from "../envelope.js";
+const MARKET_CAPABILITY_BY_ACTION = {
+    "get-ticker": "market.ticker",
+    "get-orderbook": "market.orderbook",
+    "get-klines": "market.klines",
+    "get-funding-rate": "market.funding-rate",
+    "get-mark-price": "market.mark-price",
+    "get-symbol-info": "market.symbol-info",
+    "get-open-interest": "market.open-interest"
+};
+export async function runMarketCommand(action, input) {
+    const capabilityId = MARKET_CAPABILITY_BY_ACTION[action];
+    if (!capabilityId) {
+        return fail("RCLI12001", `Unknown market command: ${action}`, "FAIL", `rapidx market ${action}`);
+    }
+    try {
+        const data = await executeRapidXCapability(capabilityId, input);
+        return ok(data, `rapidx market ${action}`, "PASS", "real_tool_call");
+    }
+    catch (error) {
+        const productError = normalizeUnknownError(error, "RCLI12001");
+        return fail(productError.code.replace(/^RCORE/, "RCLI"), productError.message, productError.status, `rapidx market ${action}`);
+    }
+}

package/dist/cli/commands/order.js

@@ -0,0 +1,81 @@
+import { consumePreview, createTargetedTradePreview, createTradePreview, defaultSafetyPolicy, executeRapidXCapability, findCapabilityById, loadPreviewStoreFromFile, makeSafetyState, normalizeUnknownError, resolvePreviewStoreFile, savePreviewStoreToFile, verifyPreview } from "../../core/index.js";
+import { fail, ok } from "../envelope.js";
+import { writeCliAudit } from "../audit.js";
+const safetyState = makeSafetyState();
+export async function runOrderCommand(action, input) {
+    const previewStoreFile = resolvePreviewStoreFile();
+    const previewStore = loadPreviewStoreFromFile(previewStoreFile);
+    if (action === "preview" || action === "place-preview") {
+        const capability = findCapabilityById("order.preview");
+        if (!capability) {
+            return fail("RCLI30001", "order.preview capability missing.");
+        }
+        try {
+            const preview = createTradePreview(capability, input, { ...defaultSafetyPolicy(), tradingEnabled: true, readOnly: false }, safetyState, previewStore);
+            savePreviewStoreToFile(previewStoreFile, previewStore);
+            return ok(preview, `rapidx order ${action}`);
+        }
+        catch (error) {
+            const productError = normalizeUnknownError(error, "RCLI20002");
+            return fail(productError.code.replace(/^RCORE/, "RCLI"), productError.message, productError.status, `rapidx order ${action}`);
+        }
+    }
+    const previewTarget = previewTargetForAction(action);
+    if (previewTarget) {
+        const targetCapability = findCapabilityById(previewTarget);
+        if (!targetCapability) {
+            return fail("RCLI30001", `${previewTarget} capability missing.`);
+        }
+        try {
+            const preview = createTargetedTradePreview(targetCapability, input, { ...defaultSafetyPolicy(), tradingEnabled: true, readOnly: false }, safetyState, previewStore);
+            savePreviewStoreToFile(previewStoreFile, previewStore);
+            return ok(preview, `rapidx order ${action}`);
+        }
+        catch (error) {
+            const productError = normalizeUnknownError(error, "RCLI20002");
+            return fail(productError.code.replace(/^RCORE/, "RCLI"), productError.message, productError.status, `rapidx order ${action}`);
+        }
+    }
+    const capability = findCapabilityById(`order.${action}`);
+    if (!capability) {
+        return fail("RCLI12001", `Unknown order command: ${action}`);
+    }
+    if (capability.previewRequired) {
+        try {
+            verifyPreview(previewStore, typeof input.previewId === "string" ? input.previewId : undefined, capability, input);
+        }
+        catch (error) {
+            return fail("RCLI20002", error instanceof Error ? error.message : String(error), "BLOCKED", `rapidx order ${action}`);
+        }
+        if (typeof input.continueConsentId !== "string" || input.continueConsentId.length === 0) {
+            return fail("RCLI20001", "continueConsentId is required for trade writes.", "BLOCKED", `rapidx order ${action}`);
+        }
+        try {
+            consumePreview(previewStore, typeof input.previewId === "string" ? input.previewId : undefined, capability, input);
+            savePreviewStoreToFile(previewStoreFile, previewStore);
+        }
+        catch (error) {
+            return fail("RCLI20002", error instanceof Error ? error.message : String(error), "BLOCKED", `rapidx order ${action}`);
+        }
+    }
+    try {
+        const data = await executeRapidXCapability(capability.capabilityId, input);
+        const auditId = capability.operationType === "TRADE_WRITE"
+            ? writeCliAudit("trade-write", "PASS", { command: `rapidx order ${action}`, capabilityId: capability.capabilityId, clientOrderId: input.clientOrderId })
+            : undefined;
+        return ok(data, `rapidx order ${action}`, "PASS", "real_tool_call", auditId);
+    }
+    catch (error) {
+        const productError = normalizeUnknownError(error, "RCLI12001");
+        return fail(productError.code.replace(/^RCORE/, "RCLI"), productError.message, productError.status, `rapidx order ${action}`);
+    }
+}
+function previewTargetForAction(action) {
+    if (action === "amend-preview") {
+        return "order.amend";
+    }
+    if (action === "cancel-preview") {
+        return "order.cancel";
+    }
+    return undefined;
+}

package/dist/cli/commands/position.js

@@ -0,0 +1,35 @@
+import { executeRapidXCapability, findCapabilityById, normalizeUnknownError } from "../../core/index.js";
+import { writeCliAudit } from "../audit.js";
+import { fail, ok } from "../envelope.js";
+import { enforceCliPreviewGate } from "./trade-gate.js";
+const POSITION_CAPABILITY_BY_ACTION = {
+    list: "position.list",
+    history: "position.history",
+    close: "position.close",
+    "set-leverage": "position.set-leverage"
+};
+export async function runPositionCommand(action, input) {
+    const capabilityId = POSITION_CAPABILITY_BY_ACTION[action];
+    if (!capabilityId) {
+        return fail("RCLI12001", `Unknown position command: ${action}`, "FAIL", `rapidx position ${action}`);
+    }
+    const capability = findCapabilityById(capabilityId);
+    if (!capability) {
+        return fail("RCLI30002", `Missing capability: ${capabilityId}`, "FAIL", `rapidx position ${action}`);
+    }
+    const blocked = enforceCliPreviewGate(capability, input, `rapidx position ${action}`);
+    if (blocked) {
+        return blocked;
+    }
+    try {
+        const data = await executeRapidXCapability(capabilityId, input);
+        const auditId = capability.operationType === "TRADE_WRITE"
+            ? writeCliAudit("trade-write", "PASS", { command: `rapidx position ${action}`, capabilityId })
+            : undefined;
+        return ok(data, `rapidx position ${action}`, "PASS", "real_tool_call", auditId);
+    }
+    catch (error) {
+        const productError = normalizeUnknownError(error, "RCLI12001");
+        return fail(productError.code.replace(/^RCORE/, "RCLI"), productError.message, productError.status, `rapidx position ${action}`);
+    }
+}

package/dist/cli/commands/schema.js

@@ -0,0 +1,5 @@
+import { getSchemaResult } from "../../core/index.js";
+import { ok } from "../envelope.js";
+export function runSchemaCommand() {
+    return ok(getSchemaResult(), "rapidx schema --json");
+}

package/dist/cli/commands/self-check.js

@@ -0,0 +1,24 @@
+import { buildLiveTradingVerificationProbes, buildLiveReadOnlySelfCheck, runSelfCheck, runTradingVerification } from "../../core/index.js";
+import { failWithData, ok } from "../envelope.js";
+export async function runSelfCheckCommand(input) {
+    const options = {
+        input: {
+            scope: input.scope === "deep" ? "deep" : "quick",
+            readOnly: input.readOnly !== false,
+            checkUpdates: input.checkUpdates === true
+        },
+        ...buildLiveReadOnlySelfCheck(input)
+    };
+    const report = await runSelfCheck(options);
+    return ok(report, "rapidx self-check --read-only --json", report.status);
+}
+export async function runTradingVerificationCommand(input, evidenceText = "rapidx self-check trade-verify --json") {
+    const report = await runTradingVerification(input, buildLiveTradingVerificationProbes(input));
+    if (report.status === "PASS") {
+        return ok(report, evidenceText, report.status);
+    }
+    return failWithData(tradingVerificationCliCode(report), report.errorMessage ?? `Trading verification failed: ${report.errorCode ?? report.status}.`, report, report.status, evidenceText);
+}
+function tradingVerificationCliCode(report) {
+    return (report.errorCode ?? "RCORE10002").replace(/^RCORE/, "RCLI");
+}

package/dist/cli/commands/trade-gate.js

@@ -0,0 +1,26 @@
+import { consumePreview, loadPreviewStoreFromFile, resolvePreviewStoreFile, savePreviewStoreToFile, verifyPreview } from "../../core/index.js";
+import { fail } from "../envelope.js";
+export function enforceCliPreviewGate(capability, input, evidenceText) {
+    if (!capability.previewRequired) {
+        return undefined;
+    }
+    const previewStoreFile = resolvePreviewStoreFile();
+    const previewStore = loadPreviewStoreFromFile(previewStoreFile);
+    try {
+        verifyPreview(previewStore, typeof input.previewId === "string" ? input.previewId : undefined, capability, input);
+    }
+    catch (error) {
+        return fail("RCLI20002", error instanceof Error ? error.message : String(error), "BLOCKED", evidenceText);
+    }
+    if (typeof input.continueConsentId !== "string" || input.continueConsentId.length === 0) {
+        return fail("RCLI20001", "continueConsentId is required for trade writes.", "BLOCKED", evidenceText);
+    }
+    try {
+        consumePreview(previewStore, typeof input.previewId === "string" ? input.previewId : undefined, capability, input);
+        savePreviewStoreToFile(previewStoreFile, previewStore);
+    }
+    catch (error) {
+        return fail("RCLI20002", error instanceof Error ? error.message : String(error), "BLOCKED", evidenceText);
+    }
+    return undefined;
+}

package/dist/cli/commands/trade.js

@@ -0,0 +1,30 @@
+import { createTargetedTradePreview, defaultSafetyPolicy, findCapabilityById, loadPreviewStoreFromFile, makeSafetyState, normalizeUnknownError, resolvePreviewStoreFile, savePreviewStoreToFile } from "../../core/index.js";
+import { fail, ok } from "../envelope.js";
+const safetyState = makeSafetyState();
+export async function runTradeCommand(action, input) {
+    if (action !== "preview") {
+        return fail("RCLI12001", `Unknown trade command: ${action}`, "FAIL", `rapidx trade ${action}`);
+    }
+    const targetCapabilityId = typeof input.targetCapabilityId === "string" ? input.targetCapabilityId : "";
+    const targetCapability = targetCapabilityId ? findCapabilityById(targetCapabilityId) : undefined;
+    if (!targetCapability) {
+        return fail("RCLI12001", `Unknown trade preview target: ${targetCapabilityId || "<missing>"}`, "FAIL", "rapidx trade preview");
+    }
+    if (targetCapability.operationType !== "TRADE_WRITE" || isPreviewCapability(targetCapability.capabilityId)) {
+        return fail("RCLI20002", "trade preview target must be a non-preview trade write capability.", "BLOCKED", "rapidx trade preview");
+    }
+    const previewStoreFile = resolvePreviewStoreFile();
+    const previewStore = loadPreviewStoreFromFile(previewStoreFile);
+    try {
+        const preview = createTargetedTradePreview(targetCapability, input, { ...defaultSafetyPolicy(), tradingEnabled: true, readOnly: false }, safetyState, previewStore);
+        savePreviewStoreToFile(previewStoreFile, previewStore);
+        return ok(preview, "rapidx trade preview");
+    }
+    catch (error) {
+        const productError = normalizeUnknownError(error, "RCLI20002");
+        return fail(productError.code.replace(/^RCORE/, "RCLI"), productError.message, productError.status, "rapidx trade preview");
+    }
+}
+function isPreviewCapability(capabilityId) {
+    return capabilityId.endsWith(".preview") || capabilityId.endsWith("-preview");
+}

package/dist/cli/commands/update.js

@@ -0,0 +1,27 @@
+import { checkForUpdate } from "../../core/index.js";
+import { fail, ok } from "../envelope.js";
+export async function runUpdateCommand(action, input) {
+    if (action !== "check") {
+        return fail("RCLI12001", `Unknown update command: ${action}`, "FAIL", "rapidx update");
+    }
+    const updateInput = {
+        force: input.force === true
+    };
+    if (typeof input.manifestUrl === "string") {
+        updateInput.manifestUrl = input.manifestUrl;
+    }
+    if (typeof input.maxCacheAgeSeconds === "number") {
+        updateInput.maxCacheAgeSeconds = input.maxCacheAgeSeconds;
+    }
+    const result = await checkForUpdate(updateInput);
+    return ok(result, "rapidx update check --json", envelopeStatusForUpdate(result.status));
+}
+function envelopeStatusForUpdate(status) {
+    if (status === "WRITE_BLOCKED" || status === "UPGRADE_REQUIRED") {
+        return "BLOCKED";
+    }
+    if (status === "UNKNOWN") {
+        return "NOT_VERIFIED";
+    }
+    return "PASS";
+}