docs: add publisher setup and record format documentation - #14
Closed
solnikhil wants to merge 3 commits into
Closed
Conversation
The roadmap still described 0.0.3 as unpublished and named 0.0.2 as the commit main was built from. Verified against npm, git, and the working tree: 0.0.3 has been dist-tags.latest since 2026-07-27 with a SLSA v1 provenance attestation, and tag v0.0.3 is pushed. Split the one stale checklist item, which bundled tagging, publishing, and clean-machine verification into a single box and so hid the part that is genuinely undone. Tagging and publishing are complete; Windows post-publication verification is not, and no GitHub release was cut for v0.0.3, which leaves the releases page advertising v0.0.2 as Latest. Move the completed 0.0.3 checklists under Shipped as Milestone 4 with every item preserved, and renumber product validation to Milestone 5. Re-rank the known gaps by how many users each affects, and record that the growth bets could never start because the validation gate depends on publisher onboarding, which was itself listed as gated by that milestone.
Four user-facing gaps, ordered by how many people each one affects. Tell pnpm, Yarn, and Bun users that --global already works. cmdInstall only calls detectNpmProject on the project path, so a global install has always worked in those projects; the refusal message just never said so and sent the largest excluded group away. Message-only change. Add di setup <domain> <package>[@range], which prints the TXT record a publisher must create in all three shapes registrars ask for, with per-registrar guidance, a propagation note, and a README snippet. A scoped name is percent-encoded, because "@" separates the version in a purl; a test round-trips generated records through parseRecord to prove it. This is the supply-side unlock the validation milestone depends on. Add --json to verify, setup, and trust list. The resolution path already computed the resolver, every attempt, the DNSSEC bit, the raw records, and the pin, then discarded the structure into formatted output. The payload carries a schema version so consumers detect a shape change instead of misreading one. Human output is suppressed so stdout holds one object and nothing else. Add di trust list and di trust forget <domain>. Previously the only way out of an unexpected mapping change was trust reset --all, which discarded trust history for every other domain as collateral. forgetPin reuses savePin's lock and atomic-write path; listPins goes through load, so corrupt state still fails closed. The install path, the DoH resolver, and the trust-store safety machinery are unchanged. Deterministic tests go from 70 to 109.
📝 WalkthroughWalkthroughThe CLI adds publisher setup, trust-pin management, and JSON verification. It adds DNS record generation, package-manager guidance, tests, a DNS record specification, and updated release documentation. ChangesPublisher and verification workflow
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant User
participant CLI
participant Setup
participant DNS
participant PinStore
User->>CLI: Run setup or verify
CLI->>Setup: Build record or parse target
Setup-->>CLI: Validated record data
CLI->>DNS: Resolve TXT records
DNS-->>CLI: DNS answers
CLI->>PinStore: Read or update trust pin
CLI-->>User: Human-readable or JSON output
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 2📝 Generate docstrings 💡
⚔️ Resolve merge conflicts 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Owner
Author
|
Superseded by #15, which preserves the August 3 documentation commit on top of current main without carrying forward stale code changes. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@ROADMAP.md`:
- Around line 64-65: Update the Milestone 4 status statement to distinguish
completed code and npm publication from the still-incomplete release close-out;
do not describe the milestone as delivered in full. Keep the outstanding tasks
documented in the Milestone 4 checklist at the referenced section.
In `@src/cli.ts`:
- Around line 608-612: Update readmeSnippet and its call site in the setup flow
to accept the parsed sub-package from parsed.value.sub, then build generated
README commands from the complete target domain (including the sub-package).
Preserve base-domain behavior when no sub-package is provided, and pass the same
complete target used by verifyDomain.
- Around line 471-480: Update the resolveEffectiveRegistry failure branch in the
supportedRecord validation flow to return refuse(effective.error) immediately
instead of assigning payload.error and continuing. Ensure the resulting payload
never reports valid: true with a non-null error and returns the failure status.
Add a JSON-mode test covering a mismatched scoped registry.
In `@src/setup.ts`:
- Around line 102-104: Update the sub validation in setup.ts to enforce DNS
label rules: require the label to start and end with an alphanumeric character,
allow hyphens only internally, and limit its length to 63 characters. Preserve
the existing invalid-label error path in the sub check before buildRecord is
reached.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 15c15fd8-95a9-470f-80de-fb7357a528c4
📒 Files selected for processing (12)
.gitignoreCHANGELOG.mdREADME.mdROADMAP.mddocs/README.mddocs/RECORD-FORMAT.mdscripts/test.tssrc/args.tssrc/cli.tssrc/install.tssrc/pin.tssrc/setup.ts
Comment on lines
+64
to
+65
| - **Milestone 4 — `0.0.3` hardening and publication.** Delivered in full; the | ||
| original checklists are preserved below. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Do not describe Milestone 4 as delivered in full.
Lines 98-108 identify two outstanding Milestone 4 tasks. This conflicts with Lines 64-65.
State that the code and npm publication are complete, while release close-out remains incomplete.
Also applies to: 98-108
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@ROADMAP.md` around lines 64 - 65, Update the Milestone 4 status statement to
distinguish completed code and npm publication from the still-incomplete release
close-out; do not describe the milestone as delivered in full. Keep the
outstanding tasks documented in the Milestone 4 checklist at the referenced
section.
Comment on lines
471
to
480
| if (npmScopeOf(supportedRecord.package)) { | ||
| const effective = resolveEffectiveRegistry(supportedRecord.package); | ||
| if (effective.ok) { | ||
| info(c.dim(` registry for this package: ${effective.registry}`)); | ||
| payload.registry = effective.registry; | ||
| say(c.dim(` registry for this package: ${effective.registry}`)); | ||
| } else { | ||
| info(""); | ||
| say(""); | ||
| payload.error = effective.error; | ||
| warn(effective.error); | ||
| } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Do not return valid: true with a non-null error.
If resolveEffectiveRegistry fails, Line 478 sets payload.error. Lines 505-507 then mark the payload as valid and return status 0.
Either return refuse(effective.error) or represent this condition with a separate warning field. Add a JSON test for a mismatched scoped registry.
Also applies to: 505-507
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/cli.ts` around lines 471 - 480, Update the resolveEffectiveRegistry
failure branch in the supportedRecord validation flow to return
refuse(effective.error) immediately instead of assigning payload.error and
continuing. Ensure the resulting payload never reports valid: true with a
non-null error and returns the failure status. Add a JSON-mode test covering a
mismatched scoped registry.
Comment on lines
+608
to
+612
| const verifyDomain = parsed.value.sub | ||
| ? `${parsed.value.domain}/${parsed.value.sub}` | ||
| : parsed.value.domain; | ||
|
|
||
| const snippet = readmeSnippet(parsed.value.domain, packageInput); |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Include the sub-package in the generated README snippet.
For di setup example.com/react widget, verifyDomain is example.com/react, but readmeSnippet receives only example.com. The generated README therefore installs and verifies the base mapping.
Extend readmeSnippet to accept the sub-package and generate commands from the complete target.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/cli.ts` around lines 608 - 612, Update readmeSnippet and its call site in
the setup flow to accept the parsed sub-package from parsed.value.sub, then
build generated README commands from the complete target domain (including the
sub-package). Preserve base-domain behavior when no sub-package is provided, and
pass the same complete target used by verifyDomain.
Comment on lines
+102
to
+104
| if (sub !== undefined && !/^[a-z0-9][a-z0-9-]*$/i.test(sub)) { | ||
| return bad(`invalid sub-package label: "${sub}"`); | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Enforce the complete DNS label constraints.
This check accepts react- and labels longer than 63 characters. buildRecord then generates an invalid DNS name.
Require a final alphanumeric character and limit the label to 63 characters.
Proposed fix
- if (sub !== undefined && !/^[a-z0-9][a-z0-9-]*$/i.test(sub)) {
+ if (
+ sub !== undefined &&
+ !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(sub)
+ ) {📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| if (sub !== undefined && !/^[a-z0-9][a-z0-9-]*$/i.test(sub)) { | |
| return bad(`invalid sub-package label: "${sub}"`); | |
| } | |
| if ( | |
| sub !== undefined && | |
| !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(sub) | |
| ) { | |
| return bad(`invalid sub-package label: "${sub}"`); | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/setup.ts` around lines 102 - 104, Update the sub validation in setup.ts
to enforce DNS label rules: require the label to start and end with an
alphanumeric character, allow hyphens only internally, and limit its length to
63 characters. Preserve the existing invalid-label error path in the sub check
before buildRecord is reached.
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
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.
Summary
This preserves the original commits and their authorship.
Summary by CodeRabbit
New Features
Documentation
Tests