Skip to content

docs: align CLI documentation with its PostgreSQL dependency - #170

Open
alejandro-llanes wants to merge 1 commit into
theam:mainfrom
alejandro-llanes:docs/cli-postgres-runtime-dependency
Open

docs: align CLI documentation with its PostgreSQL dependency#170
alejandro-llanes wants to merge 1 commit into
theam:mainfrom
alejandro-llanes:docs/cli-postgres-runtime-dependency

Conversation

@alejandro-llanes

Copy link
Copy Markdown

What changes

Removes the zero-dependency claim from the operator CLI and states the real runtime
contract wherever the CLI is documented.

file change
README.md drops "zero-dependency CLI"; the bootstrap paragraph now says connects directly to PostgreSQL, matching the authentication guide word for word
CONTRIBUTING.md rewrites the "keep the CLI free of runtime dependencies" rule so it is true and still protective
packages/cli/README.md names the dependency and the external tools instead of "one dependency"
apps/docs/docs/reference/cli.md new Runtime requirements section

The behaviour and the dependency are untouched: postgres stays, and
facility instance bootstrap still connects directly to the database.

Why

Closes #45.

packages/cli/package.json declares postgres@^3.4.7, imported in
packages/cli/src/instance.mjs and used by facility instance bootstrap — while
README.md called the same CLI zero-dependency. The package README was already partly
correct ("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 directly
but which its audit clause reaches. It read:

Keep the CLI and everything it vendors into user repositories free of runtime
dependencies.

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
postgres cannot 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:

  • postgres is imported in exactly one file and used by exactly one command
    (instance.mjs:2 and :31) — so "only instance bootstrap uses it" is accurate.
  • The CLI also shells out to git (detect.mjs:16) and, for doctor --github, to the
    GitHub CLI (doctor.mjs:218-344). Neither is an npm dependency, and both degrade rather
    than fail — git errors are caught and return empty, and doctor reports a warning when
    gh is absent or unauthenticated. The new section says so rather than claiming the CLI
    needs nothing but Node.

Verification

Acceptance criteria, checked against the tree:

  • No public documentation calls the whole CLI zero-dependency. Sweeping
    zero.dependenc|dependency-free|no dependencies across README.md, CONTRIBUTING.md,
    packages/cli/README.md and apps/docs/docs/ leaves only two hits, both about the
    vendored guards runner (README.md:79, reference/guards.md:12), which genuinely has no
    dependencies. Those are accurate and were left alone.
  • instance bootstrap is still documented as connecting directly to PostgreSQL
    README.md:215 and self-host/authentication.md:51, now identical in wording.
  • Package metadata and CLI documentation agreeengines.node: ">=20" and
    dependencies: {"postgres":"^3.4.7"} are what both READMEs and the CLI reference now state.

Commands run:

node guards/run.mjs                              # 2 passed, 0 failed
pnpm --filter @facility/docs test                # 12 passed, 0 failed (includes the Pages build)
pnpm --filter @theagilemonkeys/facility test     # 98 passed, 0 failed
pnpm verify                                      # see below

On pnpm verify

It completed Lint, Typecheck, the clean cache-disabled workspace build, both isolated
test-database recreations and the critical integration tests, then exited 1 in the final
stage on one test:

FAIL runner/test/docker-proxy.test.ts > restricted Docker API
     > forwards a Docker exec upgrade body before waiting for 101   15009ms
Tests  1 failed | 168 passed (169)

Pre-existing and unrelated to this pull request. Checking out unmodified main at
ae68401 and 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 exit
is not mistaken for something this branch introduced; nothing here is reachable from
runner/, and the diff is four Markdown files.

  • pnpm verify passes locally — runs green except the pre-existing docker-proxy
    timeout documented above, which also fails on clean main
  • Behaviour verified beyond the test suite (say how)
  • Documentation updated, or no user-facing change

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Align CLI documentation with its PostgreSQL runtime dependency

1 participant