@wasit-dev/cli 0.1.1 → 0.2.0

package/README.md

@@ -131,14 +131,15 @@ All keys are **testnet only**. `wasit` also reads a `.env` file in the current w
 
 ## 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/dzakwannajmi/wasit/blob/main/docs/CHECKS.md).
+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/dzakwannajmi/wasit) — CLI guide, MCP guide, configuration, design notes
+- [Full documentation](https://github.com/wasit-dev/wasit) — CLI guide, MCP guide, configuration, design notes
 
 ## License
 
-Apache-2.0 — see [LICENSE](https://github.com/dzakwannajmi/wasit/blob/main/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.1",
+  "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"
   }
 }