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:

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:

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.

3.9 KiB Raw Blame History

Task 5 Report — tht setup lifecycle orchestration