@itpay/cli 2.0.39 → 2.1.0

package/docs/cli-reference/index.md

@@ -89,3 +89,7 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
   - [`itpay services next`](commands/services/next.md)
   - [`itpay services read-result`](commands/services/read-result.md)
   - [`itpay services events`](commands/services/events.md)
+
+- [Sell: create, test and submit services](commands/sell.md)
+
+- [Run a published service](commands/services/run.md)

package/docs/sell.md

@@ -0,0 +1,56 @@
+# Sell Agent guide
+
+`itpay sell` is the Seller command namespace. Buyer `services` commands remain separate. Read `itpay sell guide --json` first, authenticate with `itpay sell auth login` and complete the standard ItPay browser login, then run `itpay sell auth status`, then use `sell status` to select the user's existing merchant. An unverified merchant must finish KYB and payout setup in the dashboard.
+
+## Local-first workflow
+
+1. `sell init --project <directory> --service-id <id> --name <name>` creates a local project. `sell config --file <json>` sets price, policy and explicit test fixtures. Never invent prices or required API inputs.
+2. `sell library search/get` reads platform sources. `sell sources add --file <OpenAPI> --provider-key <key>` compiles local contracts with the platform importer. `sell workflow import --file <workflow.yaml>` preserves the submitted workflow and reports unsupported semantics. Read `sell workflow catalog` for supported node configuration.
+3. Generate or modify `workflow.yaml` in the user's Agent using the exact source contracts. Bind `providerOperationVersionId`, credential profile and input/output mappings explicitly. The first workflow ID must equal the service ID. Missing mappings, incompatible schema, unsupported content types or unsupported workflow semantics block execution. Do not remove unknown fields to conceal a compatibility error.
+4. `sell credentials bind --profile <id> --file <bindings.json>` accepts field-to-environment-variable mappings, never secret values. `sell credentials upload` uploads those environment values directly to the authenticated merchant after approval; values must not appear in chat, workflow files or generated docs. Platform-managed secrets cannot be downloaded.
+5. `sell workflow validate`, then `sell workflow versions save --name <name>`. Runs never create saved versions. `sell test run --confirm` performs actual Provider calls on this machine, with simulated payment/refund/delivery gates. `sell test get --run <id>` reads results. `sell test resume` never blindly replays an unknown request.
+6. `sell workflow preview` serves the existing Builder on loopback only. Review its exact YAML, price and version; then use `sell workflow confirm --confirm` only after user agreement.
+7. `sell push --merchant-id <id> --bindings <profile-map.json> --confirm` uploads the confirmed package. Profile map values are platform profile IDs, not secrets. Optimistic revisions prevent overwriting another editor. An ambiguous write requires explicit pull/reconciliation, never guessed retries.
+8. Inspect platform-imported operations and perform any required `sell sources probe` with explicit test inputs. Follow the backend Guide and the upload's returned version/revision fields to run `sell verify`. Disclose and confirm API side effects, including the exact risk hash if the platform returns an additional confirmation barrier.
+9. `sell submission preview` returns the workflow, price, policy and current agreements. After user approval, `sell submission submit` sends the exact revision, terms version and required confirmations. This requests review; it does not publish or approve.
+10. Use `sell submission get` and `sell services list/get` to follow the actual outcome. Rejected/withdrawn/taken-down services can be edited and resubmitted through the same process. Once published, verify with buyer `catalog list`.
+
+All platform operations accept `--input-json <file>` for their declared fields and `--merchant-id`/`--draft-id` where appropriate. Run each command's `--help`; do not invent options. `sell guide --merchant-id <id> --input-json <file>` with `{"draft_id":"..."}` returns server-derived next actions.
+
+## MCP
+
+`itpay sell mcp --stdio --project <directory>` exposes local creation, import, versioning, testing, preview, sync and platform actions. It reuses the local CLI identity. Remote MCP exposes only platform actions and cannot read paths on the user's machine. Use the local server for real local tests and file access. New remote grants require the appropriate `itpay.seller.read/write/test/submit` scopes; old buyer grants do not gain Seller authority.
+
+## Invariants
+
+- Current public runtime is synchronous, acyclic, single entry, per-call pricing, one payment node, and delivery on success. Quota, prepaid consumption and async workflows are not publishable.
+- Local reports are diagnostics, not platform approval evidence. Platform verification is required; existing valid evidence may be reused. Admin approval never repeats Provider calls.
+- Every visual view reads the same YAML. Layout is presentation only.
+- Disclosure/confirmation binds the version being acted on. Do not turn `--confirm` into blanket permission for later changes.
+- Never approve real submissions or perform real payments in automated development tests.
+
+## Local recovery and packaging
+
+The local `.itpay-sell` directory contains private fixtures, reports and the encrypted run journal's local key. Exclude it from Git and shared artifacts. A terminated process may leave `runner.lock`; inspect the journal and ensure no runner is active before manual recovery. A request with an unknown outcome is never automatically replayed.
+
+Local reports never substitute for the platform verification gate. Repeated upload of an unchanged saved version reuses its cloud version; a changed cloud revision or fixture revision requires explicit pull/review.
+
+For repository builds, run `scripts/v3/build-sell-runtime.sh`, build `apps/web/vite.sell-preview.config.ts`, and then build/package `apps/cli`. Packaging rejects missing native binaries or preview assets. `scripts/v3/sync-sell-contract.mjs --check` verifies that the CLI command contracts match the backend/MCP package.
+
+Example local MCP configuration (use the existing authenticated CLI account):
+
+```json
+{
+  "mcpServers": {
+    "itpay-sell": {
+      "command": "itpay",
+      "args": ["sell", "mcp", "--stdio", "--project", "/absolute/path/to/service"],
+      "env": {"ITPAY_BACKEND_URL": "https://sandbox.itpay.ai"}
+    }
+  }
+}
+```
+
+## Seller login and dev
+
+Use `ITPAY_BACKEND_URL=https://dev.itpay.ai itpay sell auth login --json` to receive the normal ItPay authorization link. After browser login and required email verification, run `ITPAY_BACKEND_URL=https://dev.itpay.ai itpay sell auth status --json`. The CLI claims its own account session through the standard API and stores it in an owner-only file; never copy tokens or browser cookies. `itpay sell auth logout --json` revokes this session. Keep the same backend prefix on subsequent commands; production, dev, and sandbox state are isolated. Agent device enrollment does not grant Seller organization access.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.39",
+  "version": "2.1.0",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
     "docs/",
     "skills/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "assets/"
   ],
   "publishConfig": {
     "access": "public"
@@ -40,8 +41,10 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^12.1.0",
-    "qrcode": "^1.5.4"
+    "qrcode": "^1.5.4",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^22.7.5",
@@ -59,11 +62,12 @@
     "check": "npm run lint && npm run test:coverage && npm run test:package",
     "pack:dry-run": "npm run clean && npm run build && npm pack --dry-run --ignore-scripts",
     "prepare": "node scripts/install-git-hooks.mjs",
-    "test:package": "npm run clean && npm run build && node scripts/package-smoke.mjs",
-    "prepack": "npm run clean && npm run build",
+    "test:package": "node scripts/check-sell-package.mjs && npm run clean && npm run build && node scripts/package-smoke.mjs",
+    "prepack": "node scripts/check-sell-package.mjs && npm run clean && npm run build",
     "prepublishOnly": "npm run check",
     "test": "tsx --test tests/*.test.ts",
     "test:coverage": "c8 --all --src src --extension .ts --exclude=src/client/types.ts --exclude=tests/** --exclude=scripts/** --reporter=text --reporter=lcov --check-coverage --lines 85 --statements 85 --functions 90 --branches 70 npm test",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "precheck": "node scripts/fetch-sell-runtime.mjs"
   }
 }

package/skills/itpay/SKILL.md

@@ -3,8 +3,8 @@ name: itpay
 description: >
   Use ItPay when a human wants to discover or buy a service, view something
   they previously purchased, inspect order or delivery history, or request
-  and track a refund, or rate a purchased service. Seller workflows are not
-  yet available.
+  and track a refund, rate a purchased service, or create, test and submit
+  a Seller service using itpay sell.
 ---
 
 # ItPay
@@ -17,6 +17,7 @@ for the human; never ask them to run commands or learn internal concepts.
 
 | Human intent | First action |
 | --- | --- |
+| Create, sell or publish a service | `itpay sell guide --json`, then `itpay sell status --json` |
 | Discover services or make a new query | `itpay catalog list --json` |
 | View previously purchased content | `itpay vault list --json` |
 | Find a previous result by subject | `itpay vault list --query <subject> --json` |
@@ -106,3 +107,9 @@ a QR code.
   without the corresponding ItPay state.
 - Never infer a rating or upload chat, prompts, raw logs, contact details,
   purchased content, credentials, or internal identifiers as feedback.
+
+## Sell a Service
+
+Use only the `itpay sell` namespace for Seller work. Read its Guide and the packaged `docs/sell.md`. Authenticate with the existing account/device flow; do not create a second merchant. The user's Agent may generate the workflow only from locked API contracts and the exact supported node catalog. Required parameters, Content-Type, method and credentials are not creative choices.
+
+Use local MCP (`itpay sell mcp --stdio --project <directory>`) or the CLI for local files and real local tests. Show the existing Builder when helpful. Ask for explicit confirmation after showing the exact workflow/version, Provider side effects or submission agreements. Never pass secrets through chat or workflow files. Local success does not satisfy platform verification, and submission does not mean approval or publication. Follow the server Guide and keep buyer commands separate.