fix(docs): documented npx command broken on Windows — cmd owns 'verify' - #7
Merged
Merged
Conversation
…s 'verify' npx invokes the selected bin as a bare name through the platform shell. On Windows, cmd.exe built-ins shadow bare names before PATH is consulted — and 'verify' IS a cmd.exe built-in. So the short form npx github:certifieddata/verify <id> --type receipt silently died on every Windows machine: cmd's built-in swallowed the name and exited 1 with no output. Reproduced in the user's own PowerShell; the control (npx cowsay) worked, the cached package was complete and correct, and invoking the shim by full path worked — only the bare name failed. Why six green CI legs, two of them Windows, shipped this: every bin test spawns the shim by PATH, and built-ins only shadow BARE names. The new test does what npx does — bare name, through the shell — and pins the bin the docs now rely on. The 'verify' alias itself is unfixable on Windows (nothing beats a cmd built-in) and stays for POSIX convenience. The documented cross-platform command is now: npx --package github:certifieddata/verify cd-verify <id> --type receipt verified working in Windows PowerShell (VALID, exit 0). Windows note added to the spec explaining the mechanism. 71 tests pass, up from 70. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
dkitchell
added a commit
that referenced
this pull request
Sep 15, 2026
…he hero command actually run (#10) 0.1.0 is on npm now, so the docs no longer need the pre-publish workaround. Every install instruction pointed at `github:certifieddata/verify` — five in RECEIPT-VERIFICATION.md and the receipt example in the README. That form still works, but it clones and builds rather than fetching 35 kB from the registry, and it is not the command anyone would paste into a terminal on a call. The bigger problem was the hero. It read: npm install -g @certifieddata/verify certifieddata-verify ce_01HXYZ123abc... --dataset path/to/data.csv `ce_01HXYZ123abc...` is not a certificate. Anyone following the README literally — which is the stated bar for this repo — got a failure on the first command they ran, after installing globally to get there. The hero now leads with the zero-install path and two REAL production artifacts, both confirmed working against the published package before being written down: npx --package @certifieddata/verify cd-verify d6da041f-… --type certificate → VALID, signed by ed25519-prod-2025-02 npx --package @certifieddata/verify cd-verify 2492a060-… --type receipt → VALID, settlement succeeded_live Global install is kept, demoted below it, and now shows `cd-verify` with an explicit Windows warning: `verify` is a cmd.exe built-in that shadows the bin and fails silently with exit 1. That is the same trap #7 fixed for the npx form, and the global-install line still had it. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
See commit message. Key facts:
verifyis a cmd.exe built-in; bare-name invocation through the shell (which is what npx does) is swallowed by it on Windows — silent exit 1npx cowsaycontrol passed; shim-by-path passed; only bare-name failedcd-verifyas a bare shell name, pinning the documented commandnpx --package github:certifieddata/verify cd-verify <id> --type receipt— verified VALID/exit 0 in Windows PowerShell71 tests pass.
🤖 Generated with Claude Code