84 lines
3.9 KiB
Markdown
84 lines
3.9 KiB
Markdown
# 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.
|
|
|
|
## Fix round 1
|
|
|
|
The independent review identified three gaps. All were reproduced with RED tests before the
|
|
production change:
|
|
|
|
- A rendered Compose document containing any one volume was accepted. `requireVolumes` now
|
|
requires `settings`, `pi-state`, `workspace-registry`, `workspace-secrets`, `sessions`,
|
|
`qdrant-data`, and `embedding-models`; tests reject each individual omission and an
|
|
unrelated-only volume set.
|
|
- Failures after `compose up` could return without recovery instructions. A single recovery
|
|
wrapper now preserves the underlying error while adding the retained-container, `tht logs
|
|
<service>`, and `tht status` guidance for failed `up`, health, aggregate doctor, and Pi doctor
|
|
phases. Focused tests also prove build failure stops before attempting startup.
|
|
- LF inspection previously walked the full checkout. It now inspects only `compose.yaml`,
|
|
`deploy/`, and `docker/`; a test proves CRLF content under `node_modules/` is ignored.
|
|
|
|
Verification added for this round:
|
|
|
|
```bash
|
|
go test ./internal/setup -run 'TestRequireVolumes|TestRun(BuildFailure|UpFailure|AggregateDoctorFailure|PiDoctorFailure|IgnoresIrrelevant|TimesOut)' -count=1
|
|
go test ./internal/setup -count=1
|
|
```
|
|
|
|
Both passed before the final full-suite verification. No Docker or live operation was run.
|
|
|
|
Implementation commit evidence: `ea70cc95b04532043744a9de6c5912e30a214595` —
|
|
`fix(setup): harden verification and recovery`.
|