docs: align CLI documentation with its PostgreSQL dependency - #170
Open
alejandro-llanes wants to merge 1 commit into
Open
docs: align CLI documentation with its PostgreSQL dependency#170alejandro-llanes wants to merge 1 commit into
alejandro-llanes wants to merge 1 commit into
Conversation
The README described the operator CLI as zero-dependency while the published package declares `postgres`, which `facility instance bootstrap` uses to reach the database directly. The claim misstated the artifact's runtime contract, and CONTRIBUTING told contributors to keep the CLI free of runtime dependencies — a rule a future review could have followed straight into deleting the bootstrap. Drop the zero-dependency claim, and state the real contract where the CLI is documented: Node 20 or newer, exactly one runtime dependency, and the `git` and GitHub CLI invocations that are used where present rather than installed. Keep the bootstrap documented as connecting directly to PostgreSQL, and say the same thing in the README as in the authentication guide. Rewrite the CONTRIBUTING rule so it stays protective while being true: the vendored surface remains dependency-free, and `postgres` cannot be dropped without also removing the command that needs it. Closes theam#45
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.
What changes
Removes the zero-dependency claim from the operator CLI and states the real runtime
contract wherever the CLI is documented.
README.mdCONTRIBUTING.mdpackages/cli/README.mdapps/docs/docs/reference/cli.mdThe behaviour and the dependency are untouched:
postgresstays, andfacility instance bootstrapstill connects directly to the database.Why
Closes #45.
packages/cli/package.jsondeclarespostgres@^3.4.7, imported inpackages/cli/src/instance.mjsand used byfacility instance bootstrap— whileREADME.mdcalled the same CLI zero-dependency. The package README was already partlycorrect ("one dependency"), so the genuinely false claim was in the root README alone.
The more consequential half is
CONTRIBUTING.md, which the issue does not name directlybut which its audit clause reaches. It read:
That is the failure mode the issue warns about — "can send future reviews toward removing
behavior the self-host bootstrap requires" — written down as a rule a reviewer is meant to
follow. It now scopes the dependency-free requirement to the vendored surface, and says
postgrescannot be dropped without also removing the command that needs it.Two claims were verified against the code rather than assumed, because the point of this
change is documentation matching reality:
postgresis imported in exactly one file and used by exactly one command(
instance.mjs:2and:31) — so "onlyinstance bootstrapuses it" is accurate.git(detect.mjs:16) and, fordoctor --github, to theGitHub CLI (
doctor.mjs:218-344). Neither is an npm dependency, and both degrade ratherthan fail —
giterrors are caught and return empty, anddoctorreports a warning whenghis absent or unauthenticated. The new section says so rather than claiming the CLIneeds nothing but Node.
Verification
Acceptance criteria, checked against the tree:
zero.dependenc|dependency-free|no dependenciesacrossREADME.md,CONTRIBUTING.md,packages/cli/README.mdandapps/docs/docs/leaves only two hits, both about thevendored guards runner (
README.md:79,reference/guards.md:12), which genuinely has nodependencies. Those are accurate and were left alone.
instance bootstrapis still documented as connecting directly to PostgreSQL —README.md:215andself-host/authentication.md:51, now identical in wording.engines.node: ">=20"anddependencies: {"postgres":"^3.4.7"}are what both READMEs and the CLI reference now state.Commands run:
On
pnpm verifyIt completed Lint, Typecheck, the clean cache-disabled workspace build, both isolated
test-database recreations and the critical integration tests, then exited
1in the finalstage on one test:
Pre-existing and unrelated to this pull request. Checking out unmodified
mainatae68401and running that file alone reproduces it identically (1 failed | 24 passed,same ~15s timeout). It looks environment-dependent — a Unix-socket upgrade handshake that
never receives its
101— so it may well be green in CI. Flagged only so the non-zero exitis not mistaken for something this branch introduced; nothing here is reachable from
runner/, and the diff is four Markdown files.pnpm verifypasses locally — runs green except the pre-existingdocker-proxytimeout documented above, which also fails on clean
main