sashatrask
55 lines
3.8 KiB
Markdown
55 lines
3.8 KiB
Markdown
## Context
|
|
|
|
The packaged CLI persists a private JSON configuration after `install`, but first installation accepts credentials only through `--token`. Windows has a root launcher, the Linux image relies on its entrypoint, and assembled Linux packages have no root launcher. `attach` already provides live coherent status, but operators reasonably look for a `watch` command. Active documentation mixes platform-specific syntax and server-capacity administration with local lifecycle commands.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Make the same lifecycle vocabulary available from the package root on Windows and native Linux and through a short Docker helper.
|
|
- Keep the device token out of command arguments and shell history during installation.
|
|
- Verify start, clean stop, attach, status, and watch behavior before publishing copy-paste cheatsheets.
|
|
- Remove server cap `0` from routine worker maintenance instructions.
|
|
|
|
**Non-Goals:**
|
|
|
|
- Change the worker protocol, server API, assignment cancellation, or capacity semantics.
|
|
- Replace the installed private JSON configuration or expose its token.
|
|
- Add an updater, public artifact registry, or service-manager integration for native Linux.
|
|
|
|
## Decisions
|
|
|
|
### Treat `watch` as the live human status alias
|
|
|
|
`watch` uses the same authenticated local control stream and coherent status refresh as `attach`. It accepts the same optional bounded `--follow-seconds` argument and detaches without stopping the worker. Reusing the control path avoids a second polling implementation and behaves consistently where an OS `watch` utility is absent.
|
|
|
|
### Accept a strict YAML installation document
|
|
|
|
`install --config PATH` reads an exact YAML mapping containing `server`, `token`, and `parallelism`. `PATH=-` reads a bounded document from standard input for Docker. A path must be a private regular file; YAML uses `safe_load`, rejects aliases/extra fields through exact shape validation, and never changes the durable installed JSON schema. Direct `--server` and `--token` remain supported for compatibility but cannot be combined with `--config`.
|
|
|
|
### Add only a Linux package-root launcher
|
|
|
|
Assembled non-Windows packages receive executable `truf-worker` and `run-worker` shell launchers equivalent to the Windows command files. Docker keeps its existing entrypoint; the launcher also enables release tooling to export the assembled package for native Linux without inventing another client implementation.
|
|
|
|
### Separate active instructions from evidence reports
|
|
|
|
The general quickstart links concise Windows, Linux, and Docker cheatsheets and retains conceptual guidance. Each platform sheet starts from its artifact or Compose root and contains installation plus start, stop, attach, status, and watch commands. Historical validation reports remain unchanged even where they record earlier cap-zero experiments.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [A YAML file leaves a plaintext token on disk] -> Require private permissions, label it one-time installation input, and instruct deletion after successful install; the durable token remains in the existing private state.
|
|
- [Standard input cannot prove source-file permissions] -> Bound and validate its content and document `chmod 600` on the redirected host file.
|
|
- [Watch and attach appear redundant] -> Document watch as a discoverable alias rather than maintaining distinct semantics.
|
|
- [Native Linux lacks automatic daemon startup] -> Keep start/stop in the portable CLI and explicitly leave systemd installation out of scope.
|
|
|
|
## Migration Plan
|
|
|
|
1. Add parser, YAML input, launcher, and tests without changing existing command forms.
|
|
2. Build fresh Windows and Linux/Docker artifacts and run isolated lifecycle checks.
|
|
3. Publish the updated general guide and platform sheets only after those checks pass.
|
|
4. Roll back by restoring the previous artifact; installed schema-2 JSON remains compatible.
|
|
|
|
## Open Questions
|
|
|
|
None.
|