feat(cli): 'pay' and 'serve' commands for x402 (#44)

[M0nsxx]

CLI: 'pay' and 'serve' commands for x402 (#44)

Overview

This PR extends packages/cli (nirium) with two core x402 developer commands:

1. nirium pay <url>: Terminal payment client for x402 endpoints, automatically signing Stellar authorization entries and completing pay-to-retry cycles.
2. nirium serve: Zero-code local x402-protected HTTP server wrapping the SDK's x402Serve() middleware.
3. nirium config: Secure local configuration store (~/.niriumrc.json) with automatic secret key masking (S***...XXXX).

Deliverables & Features

1. nirium pay <url> [--amount] [--network] [--secret] [--config] [--json] (packages/cli/src/pay.ts):

   • Parses payment challenges (402 Payment Required), signs auth entries using Stellar Ed25519 keypairs, and sends PAYMENT-SIGNATURE headers.
   • Extracts on-chain transaction references and links directly to Stellar Expert transaction pages.
   • Masks secret keys in all console outputs and logs. Supports structured --json output.

2. nirium serve [--price] [--pay-to] [--port] [--route] [--network] (packages/cli/src/serve.ts):

   • Wraps the SDK's x402Serve() middleware over Express to spin up a mock x402-protected endpoint for testing nirium pay.

3. nirium config [set|get|list|delete] (packages/cli/src/configStore.ts & packages/cli/src/config.ts):

   • Manages configuration values (secretKey, payTo, network) with automatic secret masking.

4. Tests & Verification (packages/cli/test/pay-serve.test.js):

   • Automated tests for argument validation, secret key validation, config masking, and error reporting.

Verified Live Testnet Payment & Tx Reference

Executed nirium pay https://nirium-agent.fly.dev/api/v1/premium/signals against Nirium's live testnet endpoint using a real testnet account (GAKBHMZEWVVW6ST7D6GNR3LTDNYTMQT3K64X2D7BN35QWJ2T7IA5AXCI).

• Live Testnet Tx Hash: eb9c7889d9146757bc3038c085c7902db82718813f5ea5a1ce87fc68ac61b267
• Stellar Expert Explorer: https://stellar.expert/explorer/testnet/tx/eb9c7889d9146757bc3038c085c7902db82718813f5ea5a1ce87fc68ac61b267
• HTTP Response Status: 200 OK returning 20 live signals from nirium-agent.fly.dev.

[M0nsxx]

Fix: silent \demo-key\ fallback + world-readable config file

Two issues fixed:

1. serve.ts — silent fake facilitator key
\acilitatorApiKey\ resolved to the literal string 'demo-key'\ when no real key was configured. The server would start, print the \Listening\ banner, and look fully operational — but every request would 503 because the facilitator rejects the fake credential. Removed the fallback entirely; now fails fast at startup with actionable instructions (same pattern as \doctor.ts).

2. configStore.ts — secretKey written world-readable
\writeFileSync\ with no \mode\ option creates files 0644 (after umask) on Linux/Mac. ~/.niriumrc.json\ can hold \secretKey\ — a real Stellar SECRET key. Now writes with \mode: 0o600\ and \chmodSync(0o600)\ afterward to also fix pre-existing files. Best-effort on Windows where POSIX modes don't apply.

Also:

• Wired up the test script in \package.json\ (was a placeholder \echo).
• Added file-permission test asserting 0600 bits after \saveConfig()\ (skipped on Windows).
• All 4 tests pass (3 run + 1 skipped on Windows).

[Eras256]

Pushed a merge-conflict resolution against current main. Along the way I found and fixed two real gaps this PR had beyond the conflict itself:

1. express was never declared as a dependency despite serve.ts importing it directly — added, plus @types/express.
2. bin/nirium.js (the actual published CLI entrypoint per package.json's "bin" field) never got the pay/serve/config commands — they only existed in the unpublished src/index.ts. Added them there too, matching the ../dist/*.js import pattern the existing doctor/verify commands there already use.

One real issue I found but did NOT fix, left for you: npm run build (tsc) currently fails —

src/config.ts(1,66): error TS5097: An import path can only end with a '.ts'
extension when 'allowImportingTsExtensions' is enabled.

pay.ts, serve.ts, and config.ts all import ./configStore.ts with an explicit .ts extension. That's required for npm test to work (it runs the raw .ts sources via node --experimental-strip-types, which needs the literal file to exist at that path) — but it's rejected by tsc's NodeNext module resolution, which is what bin/nirium.js actually depends on (it imports ../dist/pay.js etc., which never gets emitted right now because the build fails before it gets there). I tried the obvious fix (swap to .js) and it just breaks the test runner instead, so this isn't a one-line change — it needs an actual resolution strategy for the package (e.g. building to a temp location before running tests against dist, or restructuring the sibling-file imports) rather than picking one extension and breaking the other consumer.

Also noting, not blocking: test/pay-serve.test.js only imports configStore.ts and pay.ts — serve.ts has zero test coverage despite being half of what this PR is named for.

Once npm run build actually succeeds, this is ready.

[M0nsxx]

Fix: TS5097 NodeNext import extensions, dist testing strategy & \executeServeCommand\ unit tests

1. Resolved TS5097 build error:

   • Replaced ./configStore.ts\ import paths in \src/config.ts, \src/pay.ts, and \src/serve.ts\ with .js\ extensions required by TypeScript under \NodeNext\ module resolution.
     pm run build\ (\ sc) now succeeds with zero errors.

2. Unified test resolution strategy:

   • Restructured the test runner to run \ sc && node --test test/verify.test.js test/doctor.test.js test/pay-serve.test.js\ testing directly against compiled \dist/*.js\ modules. This ensures both
     pm run build\ and
     pm test\ pass harmoniously in the same environment without path extension collisions.

3. Added \executeServeCommand\ unit tests:

   • Added automated test cases in \ est/pay-serve.test.js\ covering startup failure assertions for missing \acilitatorApiKey\ and missing \payTo\ recipient address.

4. Verification:

   • Both
     pm run build\ and
     pm test\ execute cleanly (15 passed, 1 skipped on Windows).

[Eras256]

Verified from a completely clean install (removed node_modules/dist/lockfiles in both packages/sdk and packages/cli, reinstalled from scratch): the TS5097 fix is correct, npm run build succeeds with zero errors, and 15/16 tests passed — the one failure was viem not being resolvable, which turned out to be this branch predating #68 (viem restored as a direct SDK dependency), already merged to main.

Merged main into this branch to pick up that fix and re-verified from another totally clean install: 16/16 tests pass, build clean. Pushed that merge directly to this PR's branch.

Merging. Thanks for chasing the build error all the way through — the dist-testing restructure is the right call.