feat: finish Pi and workspace management updates
This commit is contained in:
@@ -0,0 +1,86 @@
|
||||
# Simplified `thothctl` installation selection and Pi update Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Allow all existing `thothctl` commands to discover the installation descriptor automatically and make `thothctl pi update` use the checkout's pinned Pi version by default.
|
||||
|
||||
**Architecture:** Add a small config-level resolver that chooses one validated installation descriptor from an explicit flag, environment variable, or bounded upward search from the working directory. Keep the existing Pi lifecycle transaction intact; resolve only the requested version/source at the CLI boundary so the update engine retains its safety and recovery guarantees.
|
||||
|
||||
**Tech Stack:** Go 1.26, Docker Compose v2, existing `tools/thothctl` config and Pi lifecycle packages, Go tests.
|
||||
|
||||
**Spec:** `docs/superpowers/specs/2026-08-14-thothctl-discovery-and-pi-update-design.md`
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- Preserve every existing `pi` subcommand, alias, safety check, and explicit invocation form.
|
||||
- `--installation` remains an explicit override and accepts only an absolute descriptor path named `thothii-installation.yaml`.
|
||||
- Automatic discovery must not recursively scan `.artifacts`, home directories, or unrelated descendants.
|
||||
- The default Pi version is the single `ARG PI_VERSION=<version>` in the selected project's `docker/core.Dockerfile`.
|
||||
- The default Pi update uses the existing transactional build path and must not install an arbitrary network “latest”.
|
||||
- All failures remain sanitized and must not reveal secret values.
|
||||
|
||||
## File Map
|
||||
|
||||
- Create `tools/thothctl/internal/config/discovery.go` and `discovery_test.go` for bounded descriptor resolution and safe diagnostics.
|
||||
- Modify `tools/thothctl/cmd/thothctl/main.go` and `main_test.go` for optional global selection, `pi update` defaults, help text, and dispatch.
|
||||
- Create `tools/thothctl/internal/pi/version.go` and `version_test.go` for reading the project Pi pin.
|
||||
- Modify `tools/thothctl/internal/pi/update.go` and `update_test.go` only if the default request needs a typed source/confirmation adjustment; keep lifecycle internals unchanged otherwise.
|
||||
- Modify `docs/contracts/thothctl-pi.md`, `docs/install/pi-management.md`, and relevant command-contract verification scripts.
|
||||
|
||||
### Task 1: Add bounded installation descriptor discovery
|
||||
|
||||
**Files:**
|
||||
- Create: `tools/thothctl/internal/config/discovery.go`
|
||||
- Test: `tools/thothctl/internal/config/discovery_test.go`
|
||||
|
||||
**Interface:** `func Resolve(explicit string, environment func(string) string, workingDirectory string) (string, error)`.
|
||||
|
||||
- [x] Write failing tests for explicit-path precedence, `THOTHII_INSTALLATION`, `deploy/*/thothii-installation.yaml` discovery, parent discovery, `.artifacts` exclusion, invalid candidates, ambiguity, and no-candidate errors.
|
||||
- [x] Run `cd tools/thothctl && go test ./internal/config -run 'TestResolve' -count=1`; confirm RED because `Resolve` is absent.
|
||||
- [x] Implement a bounded upward walk. At each level inspect only the exact descriptor and immediate `deploy/*/thothii-installation.yaml` entries; skip `.artifacts`; require regular files; validate candidates through `config.Load`; deduplicate canonical paths; fail clearly on zero or multiple valid candidates.
|
||||
- [x] Re-run the focused tests and confirm GREEN.
|
||||
- [x] Refactor only after green, keeping path collection separate from candidate validation.
|
||||
|
||||
### Task 2: Make the global installation option optional
|
||||
|
||||
**Files:**
|
||||
- Modify: `tools/thothctl/cmd/thothctl/main.go`
|
||||
- Test: `tools/thothctl/cmd/thothctl/main_test.go`
|
||||
|
||||
- [x] Add failing CLI tests proving `thothctl pi status` works from a project tree, the environment variable is used, an explicit flag wins, ambiguity fails before Docker, and all existing commands retain their dispatch.
|
||||
- [x] Run the focused CLI tests and confirm RED because the current parser requires `--installation`.
|
||||
- [x] Parse optional `--installation`, call `config.Resolve` with `THOTHII_INSTALLATION` and the process working directory, and update help to `thothctl [--installation PATH] <command>`.
|
||||
- [x] Run `cd tools/thothctl && go test ./cmd/thothctl -count=1`; confirm GREEN.
|
||||
|
||||
### Task 3: Default `pi update` to the repository Pi pin
|
||||
|
||||
**Files:**
|
||||
- Create: `tools/thothctl/internal/pi/version.go`
|
||||
- Test: `tools/thothctl/internal/pi/version_test.go`
|
||||
- Modify: `tools/thothctl/cmd/thothctl/main.go`
|
||||
- Test: `tools/thothctl/cmd/thothctl/main_test.go`
|
||||
|
||||
**Interface:** `func ReadPinnedVersion(projectDirectory string) (string, error)`.
|
||||
|
||||
- [x] Add failing tests for one valid Dockerfile pin, missing Dockerfile, duplicate default pins, malformed versions, and `pi update` without `--version`; retain explicit version and advanced pull tests.
|
||||
- [x] Run `cd tools/thothctl && go test ./internal/pi ./cmd/thothctl -run 'Test(ReadPinnedVersion|ParsePiUpdate|RunPiUpdate)' -count=1`; confirm RED.
|
||||
- [x] Read only `docker/core.Dockerfile`, require one default `ARG PI_VERSION=...`, validate it with the existing version grammar, and make the short request select build mode while preserving the lifecycle transaction.
|
||||
- [x] Re-run focused tests and confirm GREEN.
|
||||
|
||||
### Task 4: Update contracts without removing commands
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/contracts/thothctl-pi.md`
|
||||
- Modify: `docs/install/pi-management.md`
|
||||
- Modify: the documentation verification script that asserts the old mandatory update invocation.
|
||||
|
||||
- [x] Document automatic descriptor discovery, the explicit override, `thothctl pi update` as the normal path, `--version` as an explicit pin, and the advanced pull/digest form.
|
||||
- [x] Keep status, doctor, test/check, configure, restart, rollback, maintenance, and logs documented.
|
||||
- [x] Run the targeted documentation checks and `git diff --check`.
|
||||
|
||||
### Task 5: Full verification
|
||||
|
||||
- [x] Run `cd tools/thothctl && go test ./... -count=1`.
|
||||
- [x] Run `cd tools/thothctl && go build ./cmd/thothctl`.
|
||||
- [x] Run the relevant documentation contract script and inspect `git status --short`.
|
||||
- [x] Verify the help text contains the optional form and all existing commands; do not mutate the live Docker installation unless separately requested.
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user