镜像站点 · 本页由第三方 GitHub 只读镜像提供,非 GitHub 官方站点,不接受任何登录或凭据输入。前往 github.com
Skip to content

docs: add wallet and webhook guides and dry-run every documented change - #26

Merged
thebrandonlucas merged 1 commit into
masterfrom
docs/cli-guides
Oct 20, 2026
Merged

thebrandonlucas merged 1 commit into
masterfrom
docs/cli-guides

Conversation

@thebrandonlucas

@thebrandonlucas thebrandonlucas commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Stack: master ← #26 ← #27 ← #28 ← #29 ← #30 ← #55 ← #60. #20, #22, #57, #24 and #19 are merged.

  • New guides: docs/guides/wallets.md (create, inspect, ledger, policies, delete) and docs/guides/webhooks.md (create with --output-file for the one-time secret, event names from the contract, test, stop/start, key rotation, deliveries). The docs index links both.
  • Offline dry run of every documented change: a new integration test takes each docs example that passes --execute, swaps in --dry-run --json, and requires exit 0 and outcome: dry_run, with no request reaching the mock API. Placeholder IDs become a fixed UUID. Examples that read a --data file get stub bodies (payment.json, policies.json, test-delivery.json), and --data - gets the payment body on stdin. A new @FILE in the docs fails the test until it has a stub.
  • No file created: the test lists the scratch directory before the loop and requires the same entries after it, so no --output-file, journal, or other file appears.
  • Shared extractor: tests/support/examples.rs holds the docs example extractor, included by the parse test in src/cli.rs and by the new integration test.

The new test found a real docs bug while writing these guides: webhooks test needs a --data body (delivery_id and payload), so the guide shows it that way.

Payments, receive/send, prices, checkout, and payment reliability are already covered by payments.md, checkout.md, and the safety model, so this PR does not split or duplicate them.

--dry-run in this layer: #30 removes --dry-run further up the stack and rewrites these lines and this test to run without --execute instead. This layer is accurate for its own head.

Changes after review

  • The --data examples run too, with stub bodies, so the development guide's claim that every documented change runs offline is now true. The minimum number of checked examples rose from 15 to 19.
  • The no-file check covers every new entry, not only webhook.json.

Checks

On 4cfa07d:

  • cargo fmt --check, cargo clippy --locked --all-targets -- -D warnings, cargo machete --with-metadata: pass.
  • cargo test --locked: 98 unit and 86 integration tests pass. VOLTAGE_BLESS=1 cargo test --locked leaves the tree clean.
  • python3 scripts/check-coverage.py: pass.
  • CRAP (scripts/crap-report.sh): no function at or above 20. Highest is api::wait_for_payment at 19.24, unchanged from or lower than master (19.66).
  • Skill review: voltage-pr-review and the voltage-backend-engineering Rust checklist, against the stack base. Findings are fixed in this commit.

Not run: the staging and live tutorials, which need credentials.

@thebrandonlucas
thebrandonlucas added this pull request to stack #25 October 13, 2026 19:00
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-guides branch 3 times, most recently from 9e4753e to bbc4fcc Compare October 19, 2026 18:39
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-guides branch 2 times, most recently from a51c322 to 7d944c2 Compare October 19, 2026 19:19
@thebrandonlucas
thebrandonlucas force-pushed the docs/cli-guides branch 2 times, most recently from 14e95fc to fa99a04 Compare October 20, 2026 11:58
@thebrandonlucas
thebrandonlucas removed this pull request from stack #25 October 20, 2026 11:59
@thebrandonlucas
thebrandonlucas added this pull request to stack #58 October 20, 2026 11:59
Comment thread tests/cli_integration.rs Resolved
@tee8z
tee8z self-requested a review October 20, 2026 14:30
tee8z
tee8z previously approved these changes Oct 20, 2026

@tee8z tee8z left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nothing blocking, just one suggestion, this is ready to go otherwise

@tee8z tee8z left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few small doc notes, none blocking. The robot checked the guides against the code and the contract: the event table, the wallets create flags, ndjson, and the one-time-secret refusal all match. CRAP on d1482ef: no function at or above 20, highest api::wait_for_payment at 19.24. All 98 unit and 86 integration tests pass.

Comment thread docs/guides/wallets.md Resolved
Comment thread docs/guides/webhooks.md Resolved
Comment thread docs/guides/webhooks.md Resolved
@thebrandonlucas
thebrandonlucas dismissed tee8z’s stale review October 20, 2026 15:17

The merge-base changed after approval.

@tee8z
tee8z self-requested a review October 20, 2026 15:44
tee8z
tee8z previously approved these changes Oct 20, 2026

@tee8z tee8z left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nothing blocking, just some suggestions/optional changes

Base automatically changed from feat/cli-ux-followups to master October 20, 2026 16:12
@thebrandonlucas
thebrandonlucas dismissed tee8z’s stale review October 20, 2026 16:12

The merge-base changed after approval.

@tee8z
tee8z self-requested a review October 20, 2026 16:12
tee8z
tee8z previously approved these changes Oct 20, 2026
New guides cover wallets (create, inspect, ledger, policies, delete) and
webhooks (create with a saved secret, events, test, pause, rotation,
deliveries). The docs index links both.

An integration test now runs every change the docs show with --execute as an
offline --dry-run --json and requires exit 0 and outcome dry_run, with no
request reaching the mock API. It caught that webhooks test needs a --data
body. The docs example extractor moves to tests/support/examples.rs so the
parse test and the dry-run test share it.
@thebrandonlucas
thebrandonlucas merged commit 380c008 into master Oct 20, 2026
6 checks passed
@thebrandonlucas
thebrandonlucas deleted the docs/cli-guides branch October 20, 2026 16:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

human review wanted CI passes; ready for a human reviewer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants