45 lines
2.7 KiB
Markdown
45 lines
2.7 KiB
Markdown
# Simplified `thothctl` installation selection and Pi update design
|
|
|
|
## Decision
|
|
|
|
Keep every existing `thothctl pi` subcommand. Make the installation descriptor optional on the command line and resolve it automatically when the operator runs from the project tree. Keep `--installation <path>` as an explicit override for non-standard locations or multiple installations.
|
|
|
|
The normal Pi update becomes:
|
|
|
|
```sh
|
|
thothctl pi update
|
|
```
|
|
|
|
When `--version` is omitted, `thothctl` reads the single default `ARG PI_VERSION=<version>` from `docker/core.Dockerfile` in the selected installation's project directory and uses that pinned version with the existing transactional build/update path. An explicit `--version <version>` remains supported. The command does not fetch an arbitrary npm “latest”; the repository pin, lockfile, image labels, and executable must remain consistent.
|
|
|
|
## Installation resolution
|
|
|
|
Resolution order is:
|
|
|
|
1. an explicit `--installation <absolute-path>/thothii-installation.yaml`;
|
|
2. `THOTHII_INSTALLATION`, when set to an absolute descriptor path;
|
|
3. automatic discovery from the current working directory and its parents.
|
|
|
|
Automatic discovery examines only the exact descriptor at each directory level and the immediate `deploy/*/thothii-installation.yaml` locations. It never recursively scans `.artifacts`, home directories, or unrelated descendants. A candidate must be a regular file and must pass `config.Load`. One valid candidate is selected. No candidates or multiple valid candidates produce an actionable error that names the expected locations and explains how to use `--installation`.
|
|
|
|
The resolver is shared by all existing top-level commands, not only `pi`, so `thothctl status`, `start`, `stop`, `doctor`, `workspace`, and the Pi commands have the same invocation rules. Existing explicit invocations remain valid.
|
|
|
|
## Safety and compatibility
|
|
|
|
- No existing Pi subcommand is removed or renamed.
|
|
- Existing advanced `pi update --source ... --image ... --yes --drain` syntax remains accepted for compatibility.
|
|
- The short update path selects build mode and preserves the existing lifecycle lock, maintenance gate, session handling, candidate verification, image selector promotion, and rollback/recovery behavior.
|
|
- The default update uses the current checkout's declared Pi pin; changing to a newer Pi release still requires updating the repository pin and lockfile in the normal source-update workflow.
|
|
- Errors and automatic-discovery diagnostics never expose secret file contents.
|
|
|
|
## User-facing examples
|
|
|
|
```sh
|
|
thothctl pi update
|
|
thothctl pi update --version 0.81.0
|
|
thothctl pi status
|
|
thothctl pi restart --yes --drain
|
|
thothctl --installation ~/operator/thothii-installation.yaml pi update
|
|
```
|
|
|