@wasit-dev/cli 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,145 @@
+# @wasit-dev/cli
+
+Protocol-compliance testing for **x402** and **MPP** on Stellar, from your terminal.
+
+`wasit` runs the real payment flow against a live service and verifies the settlement independently — via Stellar RPC and the token contract's own on-chain transfer event, not by trusting the response the service returns. It is not a schema validator: a response can have every field in the right place and still take money without settling it.
+
+**Testnet only.** Several checks settle real transactions — do not point this at pubnet or use production keys.
+
+## Install
+
+```bash
+# run once, no install
+npx @wasit-dev/cli test --target <your-service-url>
+
+# or install globally
+npm install -g @wasit-dev/cli
+wasit test --target <your-service-url>
+```
+
+Requires Node.js `>=24`.
+
+## Quick start
+
+The default posture costs nothing — no keys required:
+
+```bash
+wasit test --target https://your-service.example.com/paid --read-only
+```
+
+That runs the read-only x402 checks (`X402-01`–`05`): whether the service issues a well-formed 402 challenge. Drop `--read-only` and set `STELLAR_PRIVATE_KEY` to also exercise the payment flow — `X402-06`/`07` settle a real testnet payment.
+
+## Commands
+
+### `wasit test` — x402
+
+```bash
+wasit test --target <url> [options]
+```
+
+| Option | Default | Notes |
+|---|---|---|
+| `--target <url>` | required | Must include the scheme |
+| `--network <id>` | `stellar:testnet` | CAIP-2 network id |
+| `--payer-key <key>` | `STELLAR_PRIVATE_KEY` | Testnet secret key, `S...` |
+| `--method <verb>` | `GET` | HTTP method the paid endpoint uses |
+| `--body <json>` | — | Request body; implies `Content-Type: application/json` |
+| `--header <name:value>` | — | Extra request header, repeatable |
+| `--read-only` | off | Restricts the run to `X402-01`–`05` (no payment) |
+
+Without a payer key, the payment checks are skipped automatically. When they run: **`X402-06` settles a real payment, `X402-07` attempts one with a corrupted signature** — testnet funds move on every call.
+
+### `wasit mpp-charge` — MPP, charge mode
+
+```bash
+wasit mpp-charge --target <url> [options]
+```
+
+| Option | Default | Notes |
+|---|---|---|
+| `--target <url>` | required | The paid resource |
+| `--payer-key <key>` | `MPP_PAYER_SECRET` | Secret key, `S...` |
+| `--network <id>` | `MPP_STELLAR_NETWORK` | CAIP-2 |
+| `--rpc-url <url>` | testnet default | Required for pubnet |
+
+**Every run settles a real payment.** Charge mode has no dry run — a settlement that never happened cannot be verified on-chain.
+
+### `wasit mpp-channel` — MPP, channel mode
+
+```bash
+wasit mpp-channel --target <url> [options]
+```
+
+| Option | Default | Notes |
+|---|---|---|
+| `--target <url>` | required | The paid resource |
+| `--commitment-key <hex>` | `COMMITMENT_SECRET_HEX` | Raw ed25519 seed, hex — not an `S...` key |
+| `--network <id>` | `MPP_STELLAR_NETWORK` | CAIP-2 |
+| `--rpc-url <url>` | testnet default | Soroban RPC |
+| `--channel <address>` | `CHANNEL_CONTRACT` | Asserts the expected channel; a mismatch fails `MPP-10` |
+| `--expect-token <address>` | — | `MPP-10` parameter check |
+| `--expect-from <address>` | — | `MPP-10` parameter check |
+| `--expect-to <address>` | — | `MPP-10` parameter check |
+| `--expect-refund-period <ledgers>` | — | `MPP-10` parameter check |
+| `--allow-destructive` | off | Enables `MPP-13` (closes the channel — permanent) |
+| `--destructive-channel <address>` | `CHANNEL_CONTRACT_DISPOSABLE` | Channel `MPP-13` is permitted to close |
+
+`MPP-10`–`12` and `MPP-14` cost nothing. `MPP-13` is skipped unless `--allow-destructive` and a named disposable channel are both given — it permanently ends a channel and cannot be undone.
+
+`--channel` **asserts**, it does not select: the channel under test is resolved from the target's own 402 challenge, so every check in a run reports on the same contract. When `--channel` differs from what the target advertises, `MPP-10` fails and inspects nothing.
+
+## Reading output
+
+```
+PASS  X402-01  402 Response Status
+      Server responded with 402 as required.
+
+FAIL  X402-01  402 Response Status
+      Expected status 402, got 404.
+
+SKIP  X402-02  Payment Header Present
+      Skipped: the target answered 404 rather than 402, so it issued no
+      payment challenge to inspect.
+
+7 passed.
+```
+
+`PREFLIGHT` appears in place of the checks when the target URL or network identifier itself is invalid — both are wrong for every check in the suite, so it's reported once rather than repeated identically.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Every check that ran conformed |
+| `1` | At least one conformance failure |
+| `2` | At least one check produced no verdict (unreachable target, bad config) |
+
+A run with both a failure and an error exits `1` — a real finding outranks a missing one. Skipped checks never affect the exit code.
+
+## Configuration
+
+| Env var | Used by |
+|---|---|
+| `STELLAR_PRIVATE_KEY` | `test` (x402 payment checks) |
+| `MPP_PAYER_SECRET` | `mpp-charge` |
+| `MPP_STELLAR_NETWORK` | `mpp-charge`, `mpp-channel` |
+| `COMMITMENT_SECRET_HEX` | `mpp-channel` |
+| `CHANNEL_CONTRACT` | `mpp-channel` (optional assertion) |
+| `CHANNEL_CONTRACT_DISPOSABLE` | `mpp-channel --allow-destructive` |
+
+All keys are **testnet only**. `wasit` also reads a `.env` file in the current working directory — pass `--payer-key` / `--commitment-key` directly to override it for a single run.
+
+## What's checked
+
+Thirteen checks across x402 and MPP, each traced to a written spec clause — the full catalogue, with pass criteria and spec references, is in [`docs/CHECKS.md`](https://github.com/wasit-dev/wasit/blob/main/docs/CHECKS.md).
+
+## Related
+
+- [Website](https://usewasit.dev)
+- [`@wasit-dev/core`](https://www.npmjs.com/package/@wasit-dev/core) — the check suite this CLI runs, if you're building your own tooling on top
+- [`@wasit-dev/server`](https://www.npmjs.com/package/@wasit-dev/server) — the same checks as MCP tools, for Claude Code and other agents
+- [Full documentation](https://github.com/wasit-dev/wasit) — CLI guide, MCP guide, configuration, design notes
+
+## License
+
+Apache-2.0 — see [LICENSE](https://github.com/wasit-dev/wasit/blob/main/LICENSE).

package/dist/index.js

@@ -1,7 +1,13 @@
 #!/usr/bin/env node
 import "dotenv/config";
 import { Command } from "commander";
-import { checkStatus, runMppChannelSuite, runMppChargeSuite, runX402PaymentChecks, runX402ReadChecks, summarize, } from "@wasit-dev/core";
+import { CHECK_CATALOGUE, PROTOCOL_IDS, checkStatus, runMppChannelSuite, runMppChargeSuite, runX402PaymentChecks, runX402ReadChecks, summarize, toStructuredRun, } from "@wasit-dev/core";
+/** Which wasit subcommand runs each protocol's checks — for `wasit checks` output. */
+const COMMAND_BY_PROTOCOL = {
+    x402: "test",
+    "mpp-charge": "mpp-charge",
+    "mpp-channel": "mpp-channel",
+};
 /**
  * Accumulates repeated --header flags into one object.
  *
@@ -23,21 +29,54 @@ const program = new Command();
 program
     .name("wasit")
     .description("Protocol-compliance testing for x402 / MPP on Stellar")
-    .version("0.1.0");
+    .version("0.1.0")
+    .addHelpText("after", `
+Examples:
+  $ wasit checks
+  $ wasit test --target https://api.example.com/paid-endpoint --read-only
+  $ wasit mpp-charge --target https://api.example.com/paid-endpoint --payer-key S...
+  $ wasit mpp-channel --target https://api.example.com/paid-endpoint
+
+Run "wasit <command> --help" for that command's own options and cost notes.
+Add --json to test/mpp-charge/mpp-channel for machine-readable output.
+Full check catalogue (every check ID, spec reference, pass criteria):
+  https://github.com/wasit-dev/wasit/blob/main/docs/CHECKS.md`);
+/**
+ * Prints an advisory/status line meant for a human watching the terminal —
+ * never part of the run's actual result. Routed to stderr when --json is
+ * set, so stdout stays parseable JSON and a script piping it (jq, etc.)
+ * never has to skip past prose first.
+ */
+function note(json, message) {
+    if (json) {
+        console.error(message);
+    }
+    else {
+        console.log(message);
+    }
+}
 /**
  * Prints results and returns the process exit code.
  *
  * A skipped check carries `pass: false` so it can never be counted as
  * conformance, but it is not a failure and must not fail the run. An errored
  * check produced no verdict at all and is reported separately again.
+ *
+ * `--json` reuses `toStructuredRun()` from core — the same reshape the MCP
+ * server calls for its own structured output — rather than defining a
+ * second JSON shape here that could drift from it.
  */
-function report(results) {
+function report(results, json) {
+    const counts = summarize(results);
+    if (json) {
+        console.log(JSON.stringify(toStructuredRun(results), null, 2));
+        return counts.exitCode;
+    }
     for (const result of results) {
         const flag = result.destructive ? "  [destructive]" : "";
         console.log(`${checkStatus(result)}  ${result.id}  ${result.name}${flag}`);
         console.log(`      ${result.detail}\n`);
     }
-    const counts = summarize(results);
     const line = [`${counts.passed} passed`];
     if (counts.failed > 0)
         line.push(`${counts.failed} failed`);
@@ -52,6 +91,48 @@ function report(results) {
     }
     return counts.exitCode;
 }
+program
+    .command("checks")
+    .description("List the check catalogue: every check wasit can run, by ID")
+    .option("--protocol <name>", `Filter to one protocol (${PROTOCOL_IDS.join(", ")}) — matches the wasit subcommand that runs it`)
+    .option("--json", "Print as JSON instead of a formatted list", false)
+    .addHelpText("after", `
+Examples:
+  $ wasit checks
+  $ wasit checks --protocol mpp-channel
+  $ wasit checks --json
+
+Full pass-criteria prose, spec citations, and revision notes for every check
+live in docs/CHECKS.md — this command is a quick reference, not a
+replacement for it.`)
+    .action((opts) => {
+    const protocol = opts.protocol;
+    if (protocol !== undefined && !PROTOCOL_IDS.includes(protocol)) {
+        console.error(`Unknown --protocol "${protocol}". Expected one of: ${PROTOCOL_IDS.join(", ")}.`);
+        process.exit(2);
+    }
+    const entries = CHECK_CATALOGUE.filter((entry) => protocol === undefined || entry.protocol === protocol);
+    if (opts.json === true) {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+    }
+    let currentProtocol;
+    for (const entry of entries) {
+        if (entry.protocol !== currentProtocol) {
+            currentProtocol = entry.protocol;
+            console.log(`\n${currentProtocol}  (wasit ${COMMAND_BY_PROTOCOL[currentProtocol]})`);
+        }
+        const flags = [
+            entry.negative ? "negative" : null,
+            entry.destructive ? "destructive" : null,
+            entry.costsFunds ? "costs funds" : null,
+        ].filter((flag) => flag !== null);
+        const flagText = flags.length > 0 ? `  [${flags.join(", ")}]` : "";
+        console.log(`  ${entry.id}  ${entry.name}${flagText}`);
+        console.log(`      ${entry.summary}`);
+    }
+    console.log(`\n${entries.length} check${entries.length === 1 ? "" : "s"}.`);
+});
 program
     .command("test")
     .description("Run x402 compliance checks against a target service")
@@ -63,7 +144,19 @@ program
     .option("--body <json>", "Request body, sent verbatim. Implies Content-Type: application/json.")
     .option("--header <name:value>", "Extra request header the endpoint needs before it will issue a challenge. Repeatable.", collectHeader)
     .option("--read-only", "Skip payment checks (X402-06/07)", false)
+    .option("--json", "Print results as JSON instead of formatted text", false)
+    .addHelpText("after", `
+Examples:
+  $ wasit test --target https://api.example.com/paid-endpoint --read-only
+  $ wasit test --target https://api.example.com/paid-endpoint --payer-key S...
+  $ wasit test --target https://api.example.com/paid-endpoint --read-only --json
+
+X402-01..05 (challenge/header checks) always run and cost nothing. X402-06/07
+(real payment checks) run only when a payer key is available and --read-only
+is not set: X402-06 settles a payment, X402-07 attempts one with a corrupted
+signature. See docs/CHECKS.md for what each check ID verifies.`)
     .action(async (opts) => {
+    const jsonMode = opts.json === true;
     const shape = {
         ...(opts.method ? { method: opts.method } : {}),
         ...(opts.body !== undefined ? { body: opts.body } : {}),
@@ -72,13 +165,13 @@ program
     const results = await runX402ReadChecks({ target: opts.target, ...shape });
     const payerKey = opts.payerKey ?? process.env.STELLAR_PRIVATE_KEY;
     if (opts.readOnly) {
-        console.log("(--read-only set: skipping payment checks)\n");
+        note(jsonMode, "(--read-only set: skipping payment checks)\n");
     }
     else if (!payerKey) {
-        console.log("(no payer key: set STELLAR_PRIVATE_KEY in .env or pass --payer-key — skipping payment checks)\n");
+        note(jsonMode, "(no payer key: set STELLAR_PRIVATE_KEY in .env or pass --payer-key — skipping payment checks)\n");
     }
     else {
-        console.log("X402-06 settles a real payment and X402-07 attempts one. Testnet funds will move.\n");
+        note(jsonMode, "X402-06 settles a real payment and X402-07 attempts one. Testnet funds will move.\n");
         results.push(...(await runX402PaymentChecks({
             target: opts.target,
             network: opts.network,
@@ -86,7 +179,7 @@ program
             ...shape,
         })));
     }
-    process.exit(report(results));
+    process.exit(report(results, jsonMode));
 });
 program
     .command("mpp-channel")
@@ -103,7 +196,19 @@ program
     .option("--expect-refund-period <ledgers>", "MPP-10: expected refund waiting period")
     .option("--allow-destructive", "Enable MPP-13. Closing settles on-chain and permanently ends the channel.", false)
     .option("--destructive-channel <address>", "Channel MPP-13 is permitted to close (default: CHANNEL_CONTRACT_DISPOSABLE)")
+    .option("--json", "Print results as JSON instead of formatted text", false)
+    .addHelpText("after", `
+Examples:
+  $ wasit mpp-channel --target https://api.example.com/paid-endpoint
+  $ wasit mpp-channel --target https://api.example.com/paid-endpoint --allow-destructive --destructive-channel C...
+  $ wasit mpp-channel --target https://api.example.com/paid-endpoint --json
+
+MPP-10, MPP-11, MPP-12, MPP-14 run by default and are non-destructive.
+MPP-13 (channel close) only runs with --allow-destructive, and only against
+the channel named by --destructive-channel — running it permanently ends
+that channel.`)
     .action(async (opts) => {
+    const jsonMode = opts.json === true;
     const commitmentSecretHex = opts.commitmentKey ?? process.env.COMMITMENT_SECRET_HEX;
     if (!commitmentSecretHex) {
         console.error("No commitment key. Pass --commitment-key or set COMMITMENT_SECRET_HEX in .env.");
@@ -128,7 +233,7 @@ program
             ...(Number.isInteger(refundWaitingPeriod) ? { refundWaitingPeriod } : {}),
         },
     });
-    process.exit(report(results));
+    process.exit(report(results, jsonMode));
 });
 program
     .command("mpp-charge")
@@ -137,19 +242,28 @@ program
     .option("--payer-key <key>", "Payer secret key, S... (default: MPP_PAYER_SECRET)")
     .option("--network <network>", "CAIP-2 network id (default: MPP_STELLAR_NETWORK)")
     .option("--rpc-url <url>", "Override the default Soroban RPC endpoint")
+    .option("--json", "Print results as JSON instead of formatted text", false)
+    .addHelpText("after", `
+Examples:
+  $ wasit mpp-charge --target https://api.example.com/paid-endpoint --payer-key S...
+  $ wasit mpp-charge --target https://api.example.com/paid-endpoint --payer-key S... --json
+
+Runs MPP-01 only. Not idempotent and has no read-only mode: every run settles
+a real payment and moves testnet funds, because charge mode has no dry run.`)
     .action(async (opts) => {
+    const jsonMode = opts.json === true;
     const payerSecretKey = opts.payerKey ?? process.env.MPP_PAYER_SECRET;
     if (!payerSecretKey) {
         console.error("No payer key. Pass --payer-key or set MPP_PAYER_SECRET in .env.");
         process.exit(2);
     }
-    console.log("MPP-01 settles a real payment. If the target is reachable, testnet funds will move.\n");
+    note(jsonMode, "MPP-01 settles a real payment. If the target is reachable, testnet funds will move.\n");
     const results = await runMppChargeSuite({
         target: opts.target,
         network: opts.network ?? process.env.MPP_STELLAR_NETWORK ?? "stellar:testnet",
         payerSecretKey,
         ...(opts.rpcUrl ? { rpcUrl: opts.rpcUrl } : {}),
     });
-    process.exit(report(results));
+    process.exit(report(results, jsonMode));
 });
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wasit-dev/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI for x402/MPP protocol-conformance testing on Stellar \u2014 verifies a service's payment flow settles on-chain per spec.",
   "type": "module",
   "bin": {
@@ -11,12 +11,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/dzakwannajmi/wasit.git",
+    "url": "git+https://github.com/wasit-dev/wasit.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/dzakwannajmi/wasit#readme",
+  "homepage": "https://github.com/wasit-dev/wasit#readme",
   "bugs": {
-    "url": "https://github.com/dzakwannajmi/wasit/issues"
+    "url": "https://github.com/wasit-dev/wasit/issues"
   },
   "keywords": [
     "stellar",
@@ -39,11 +39,8 @@
     "build": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@stellar/mpp": "^0.7.1",
-    "@stellar/stellar-sdk": "^16.1.0",
-    "@wasit-dev/core": "^0.1.0",
-    "commander": "^12.0.0",
-    "dotenv": "^16.0.0",
-    "mppx": "^0.8.14"
+    "@wasit-dev/core": "^0.2.0",
+    "commander": "^15.0.0",
+    "dotenv": "^17.4.2"
   }
 }