Skip to content

feat(doctor): Docker environment readiness pre-checks (#28) - #31

Merged
PeterGuy326 merged 3 commits into
mainfrom
fix/doc-28-docker-readiness
Aug 30, 2026
Merged

feat(doctor): Docker environment readiness pre-checks (#28)#31
PeterGuy326 merged 3 commits into
mainfrom
fix/doc-28-docker-readiness

Conversation

@PeterGuy326

Copy link
Copy Markdown
Contributor

Summary

doc#28 — Docker environment readiness pre-checks. doc doctor now reports Docker daemon readiness with a stable code and actionable guidance, and doc up refuses 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)

REQ/AC Change Evidence
REQ-001 / AC-001 docker-readiness.js checkDockerReadiness() returns docker_daemon_unreachable + guidance; surfaced in doc doctor AC-001: daemon down -> docker_daemon_unreachable with actionable guidance test
REQ-002 / AC-002 hasDesktopExeCredsStore() detects credsStore: desktop.exe on a non-Windows host (and exec-format stderr), returns docker_credsstore_desktop_exe + remediation; native Windows not flagged AC-002: credsStore desktop.exe under WSL, AC-002: ... native Windows is not flagged, AC-002: exec-format error ... diagnosed tests
REQ-003 / AC-003 doc up runs the readiness verdict before the first pull/build and returns failure without invoking docker ... up AC-003: doc up fails ... before invoking docker up (no side effects) tests

Files

  • 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.jsdocker-daemon check now reports the readiness verdict with code + guidance; check() carries optional code/guidance.
  • packages/cli/src/cli.jsdoc up pre-effect readiness gate; formatDoctorText renders guidance; runDoctor gains injectable homeDir.
  • packages/cli/test/docker-readiness.test.js — 8 tests (daemon-down, credsStore trap incl. native-Windows negative + exec-format diagnosis, doc up ordering).
  • packages/cli/package.jsoncheck adds src/docker-readiness.js.
  • docs/RUN_LOCAL.md — Docker readiness section; CHANGELOG.md entry.

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.
  • Docker readiness detection itself is read-only and exercised by the fixtures above; live Docker/Desktop behavior is ops-verified input, not re-run here.

Security and compatibility

  • No credential, secret, or personal data touched; detection reads only Docker client state and ~/.docker/config.json.
  • No new dependency. No change to image composition or Compose topology.
  • Detection never starts the daemon or pulls; it only reads.

Known limitations

  • Live Docker Desktop / WSL behavior is evidenced by ops reproduction logs (docker_cfg_fix.log), not re-run in this PR.

Risk and rollback

Additive pre-check; rollback reverts the commit. No data migration, no irreversible effect.

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
PeterGuy326 force-pushed the fix/doc-28-docker-readiness branch from 4b7f675 to 0e82bce Compare August 30, 2026 16:50
@PeterGuy326
PeterGuy326 merged commit 37ebe94 into main Aug 30, 2026
2 checks passed
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.

1 participant