docs: close remaining spec/implementation documentation gaps - #102
Merged
Conversation
Last item from an internal spec-compliance audit: five places where the spec was silent about or contradicted shipped, tested behavior. - Added a "Computed package fields" section documenting installed, verified, and downloads - real fields the manager/registry compute and attach to package metadata, previously undocumented anywhere. - Noted the two-tier Package Validation (structural errors vs non-fatal recommendations) next to the Scan logic section, since the recommendations system (packageRecommendations()) was implemented but never mentioned in the spec. - Windows App directory table now says %AppData% (matching the actual, platform-idiomatic implementation) instead of the literal $HOME - the code was right and the spec was wrong here, not the other way around. - Install logic: reworded the Admin-privileges step to describe the conditional elevation (skip it when a compatible archive is available) added for issue #83, and reordered it after file filtering to match actual execution order. - Install logic: installer execution is described as "wait for it to complete" rather than "run the process in a separate thread" - fileInstall() is fully synchronous (execFileSync), so "separate thread" was inaccurate in both particulars, not just imprecise. Co-Authored-By: Claude Sonnet 5 <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
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
Last item from an internal spec-compliance audit: five places where the spec was silent about or contradicted shipped, tested behavior.
installed,verified, anddownloads— real fields the manager/registry compute and attach to package metadata, previously undocumented anywhere.packageRecommendations()) was implemented but never mentioned in the spec.%AppData%(matching the actual, platform-idiomatic implementation) instead of the literal$HOME— the code was right and the spec was wrong here, not the other way around.fileInstall()is fully synchronous (execFileSync), so "separate thread" was inaccurate in both particulars, not just imprecise.Docs-only change, no code touched.
Test plan
npm run checkpasses (format, lint, build, tests — 207/207, unchanged since this is documentation-only)🤖 Generated with Claude Code