feat(setup): build start and verify ThothII

2026-08-15 23:09:10 +02:00
parent 2856964654
commit 47e0b2a385
7 changed files with 719 additions and 31 deletions
@@ -0,0 +1,55 @@
+# Task 5 Report — `tht setup` lifecycle orchestration
+
+## Status
+
+Completed. `tht setup` now validates the checkout and host prerequisites, creates or validates
+the non-secret installation files, validates Compose, and by default builds, starts, health-checks,
+and verifies the installation. `tht setup --configure-only` stops immediately after successful
+Compose rendering.
+
+## Implementation
+
+- Added `setup.Run`, with an ordered host preflight: project/worktree discovery, Docker Engine,
+  Docker Compose, supported architecture, and LF line-ending checks.
+- Reused `config.Installation.ComposeArgs` for all Compose calls and added a narrow
+  `compose.InstallationRunner` adapter for Pi diagnostics; no shell command construction was added
+  to the top-level CLI parser.
+- Default setup performs `compose build`, `compose up --detach --remove-orphans`, bounded polling
+  for `core`, `frontend`, `qdrant`, `embedding`, and `embedding-model-init`, then aggregate volume
+  diagnostics and `pi.Doctor`.
+- Health timeout errors identify the last failing service and preserve containers for diagnosis,
+  with `tht logs <service>` and `tht status` guidance.
+- Completion output includes the frontend URL, selected descriptor, and next action.
+
+## TDD evidence
+
+The initial focused test run failed because `setup.Run` did not exist. Tests were then written
+against a fake Compose runner before the orchestration was implemented. They cover the complete
+ordered flow, configure-only stop, preflight failure before writing configuration, health retry,
+timeout guidance, and CLI default versus `--configure-only` dispatch.
+
+## Verification
+
+Executed from `tools/tht`:
+
+```bash
+go test ./internal/setup ./internal/compose ./cmd/tht -run 'TestRun|TestSetupCommand|TestInstallationRunner' -count=1
+go test ./internal/setup ./internal/compose ./cmd/tht -count=1
+go test ./...
+git diff --check
+```
+
+All commands passed. No actual Docker build, container start, live-stack restart, system
+installation, Pi configuration edit, or documentation rewrite was performed.
+
+## Commit
+
+`feat(setup): build start and verify ThothII` (this report is included in that commit).
+
+## Concerns
+
+- The bounded health wait is verified with fakes only, as required for this task. Real Docker
+  lifecycle verification belongs to the later live acceptance task.
+- The existing aggregate `tht doctor` command remains a separate implementation; Task 5 performs
+  its equivalent setup-time prerequisite checks plus `pi.Doctor` without invoking a nested CLI
+  process.