feat(doctor): Docker environment readiness pre-checks (#28) - #31
Merged
Conversation
PeterGuy326
force-pushed
the
fix/doc-28-docker-readiness
branch
from
August 30, 2026 16:42
dc29ff8 to
4b7f675
Compare
Add a Docker readiness verdict that runs before `doc up` performs its first image pull/build side effect, and surface it in `doc doctor` with stable codes and actionable guidance. Detects the two known Windows/WSL traps: daemon not running (docker_daemon_unreachable) and credsStore: desktop.exe under WSL (docker_credsstore_desktop_exe), the latter of which breaks even public image pulls with an exec-format error. Detection is read-only (no daemon start, no pull). - packages/cli/src/docker-readiness.js: checkDockerReadiness() returns a stable code + guidance; hasDesktopExeCredsStore() inspects ~/.docker/config.json for a Windows credential helper on a non-Windows host. - doctor.js: docker-daemon check now reports the readiness verdict with code + guidance; check() carries optional code/guidance. - cli.js: `doc up` refuses to start the stack when the readiness verdict fails (pre-effect ordering); formatDoctorText renders guidance. - Tests: daemon-down, credsStore trap (WSL + native-Windows negative + exec-format stderr diagnosis), and `doc up` ordering fixtures. - Docs: RUN_LOCAL.md Docker readiness section; CHANGELOG entry.
PeterGuy326
force-pushed
the
fix/doc-28-docker-readiness
branch
from
August 30, 2026 16:50
4b7f675 to
0e82bce
Compare
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
doc#28 — Docker environment readiness pre-checks.
doc doctornow reports Docker daemon readiness with a stable code and actionable guidance, anddoc uprefuses to start the stack before that verdict passes (pre-effect ordering). Detects the two known Windows/WSL traps surfaced by ops dogfood (2026-08-29), so a broken Docker environment fails with an actionable message instead of dying mid-up.Requirement trace (doc#28)
docker-readiness.jscheckDockerReadiness()returnsdocker_daemon_unreachable+ guidance; surfaced indoc doctorAC-001: daemon down -> docker_daemon_unreachable with actionable guidancetesthasDesktopExeCredsStore()detectscredsStore: desktop.exeon a non-Windows host (and exec-format stderr), returnsdocker_credsstore_desktop_exe+ remediation; native Windows not flaggedAC-002: credsStore desktop.exe under WSL,AC-002: ... native Windows is not flagged,AC-002: exec-format error ... diagnosedtestsdoc upruns the readiness verdict before the first pull/build and returns failure without invokingdocker ... upAC-003: doc up fails ... before invoking docker up (no side effects)testsFiles
packages/cli/src/docker-readiness.js— new module:checkDockerReadiness()(stable code + guidance),hasDesktopExeCredsStore(),DOCKER_READINESS_CODES. Read-only (no daemon start, no pull).packages/cli/src/doctor.js—docker-daemoncheck now reports the readiness verdict with code + guidance;check()carries optional code/guidance.packages/cli/src/cli.js—doc uppre-effect readiness gate;formatDoctorTextrenders guidance;runDoctorgains injectablehomeDir.packages/cli/test/docker-readiness.test.js— 8 tests (daemon-down, credsStore trap incl. native-Windows negative + exec-format diagnosis,doc upordering).packages/cli/package.json—checkaddssrc/docker-readiness.js.docs/RUN_LOCAL.md— Docker readiness section;CHANGELOG.mdentry.Validation
node --test(packages/cli): PASS 58/58 (incl. 8 new doc#28 tests).npm run check(packages/cli, syntax across all CLI sources incl. new module): PASS.Security and compatibility
~/.docker/config.json.Known limitations
Risk and rollback
Additive pre-check; rollback reverts the commit. No data migration, no irreversible effect.