Initial server source import
This commit is contained in:
sashatrask
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-30
|
||||
@@ -0,0 +1,54 @@
|
||||
## 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.
|
||||
@@ -0,0 +1,23 @@
|
||||
## Why
|
||||
|
||||
Remote-worker instructions do not provide independently verified copy-paste workflows for Windows, native Linux, and Docker. They also document a nonexistent `watch` command, require a device token in the install command line, claim a native Linux launcher that is not packaged, and recommend server cap `0` for routine local lifecycle operations.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add a bounded `watch` lifecycle command alongside `start`, `stop`, `attach`, and `status`.
|
||||
- Allow first-time installation to read the server origin, device token, and parallelism from a small YAML document instead of process arguments.
|
||||
- Package a native Linux launcher and verify the lifecycle command surface on Windows, native Linux, and Docker.
|
||||
- Keep the complete operator guide concise while adding separate copy-paste cheatsheets for each supported environment.
|
||||
- Remove routine cap `0` instructions; local graceful stop drains the selected worker without changing server scheduling for other devices.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `worker-operator-lifecycle`: Cross-platform worker lifecycle commands, private YAML installation input, and verified platform cheatsheets.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
## Impact
|
||||
|
||||
This affects `worker_cli.py`, worker package launchers, the Linux worker image, CLI/package tests, packaged lifecycle verification, and remote-worker operator documentation. The worker protocol, server API, stored private configuration schema, and assignment capacity model remain unchanged.
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Cross-platform lifecycle command surface
|
||||
The packaged worker SHALL expose start, stop, attach, status, and watch operations with equivalent local-control semantics on Windows, native Linux, and Docker.
|
||||
|
||||
#### Scenario: Operator watches a running worker
|
||||
- **WHEN** an operator runs `watch` for a bounded interval
|
||||
- **THEN** the CLI emits coherent live status and detaches without stopping the worker
|
||||
|
||||
#### Scenario: Operator stops a worker
|
||||
- **WHEN** an operator requests a graceful stop while the worker can complete its local drain
|
||||
- **THEN** the CLI returns a clean shutdown receipt without requiring a server-side assignment-cap change
|
||||
|
||||
### Requirement: Installation credentials can come from YAML
|
||||
The worker SHALL accept a bounded strict YAML installation document containing the HTTPS server origin, device token, and positive local parallelism instead of requiring those values in process arguments.
|
||||
|
||||
#### Scenario: Install from a private YAML file
|
||||
- **WHEN** an operator invokes `install --config` with a private valid YAML file
|
||||
- **THEN** the worker verifies the package and persists the existing private installed configuration without exposing the token in argv
|
||||
|
||||
#### Scenario: Install from redirected standard input
|
||||
- **WHEN** a Docker operator redirects a valid YAML document to `install --config -`
|
||||
- **THEN** the worker performs the same installation without placing the token in the Compose or container command
|
||||
|
||||
#### Scenario: Reject ambiguous installation input
|
||||
- **WHEN** YAML input is malformed, has extra fields, exceeds its byte bound, or is combined with direct server/token arguments
|
||||
- **THEN** installation fails before writing worker configuration
|
||||
|
||||
### Requirement: Native Linux package is directly operable
|
||||
An assembled native Linux worker package SHALL include an executable package-root launcher for the same operator CLI used by Windows and Docker.
|
||||
|
||||
#### Scenario: Linux operator runs from the extracted package root
|
||||
- **WHEN** the operator invokes `./truf-worker status`
|
||||
- **THEN** the integrity-checking bootstrap runs with the package-local application and dependencies
|
||||
|
||||
### Requirement: Platform cheatsheets are executable and capacity-independent
|
||||
The active operator documentation SHALL provide separate Windows, native Linux, and Docker copy-paste cheatsheets whose lifecycle commands are verified against the corresponding packaged artifact and do not instruct routine use of server cap `0`.
|
||||
|
||||
#### Scenario: Operator follows one platform sheet
|
||||
- **WHEN** an operator starts from the documented artifact or Compose root
|
||||
- **THEN** installation, start, status, attach, watch, and clean stop require only the documented local files and commands
|
||||
@@ -0,0 +1,16 @@
|
||||
## 1. Operator CLI
|
||||
|
||||
- [x] 1.1 Add strict private YAML and standard-input configuration to worker installation
|
||||
- [x] 1.2 Add the bounded watch alias over the existing attach control stream
|
||||
- [x] 1.3 Add an executable native Linux package-root launcher
|
||||
|
||||
## 2. Platform Documentation
|
||||
|
||||
- [x] 2.1 Create separate copy-paste cheatsheets for Windows, native Linux, and Docker
|
||||
- [x] 2.2 Update the general quickstart and operations runbook and remove routine cap-zero guidance
|
||||
|
||||
## 3. Verification
|
||||
|
||||
- [x] 3.1 Add focused CLI, package, YAML-security, and documentation tests
|
||||
- [x] 3.2 Build fresh Windows and Linux/Docker artifacts and verify install, start, status, attach, watch, and clean stop
|
||||
- [x] 3.3 Run focused tests and strict OpenSpec validation and record the checked command matrix
|
||||
@@ -0,0 +1,79 @@
|
||||
# Worker Cheatsheet Validation - 2026-09-30
|
||||
|
||||
## Scope
|
||||
|
||||
Validation used isolated fake device tokens, private local state roots, a local
|
||||
TLS no-work fixture, unique Docker names/volumes, and fresh artifacts. It did not
|
||||
contact production, issue assignments, or use production credentials.
|
||||
|
||||
## Initial audit
|
||||
|
||||
- Windows package exposed install, start, stop, status, attach, logs, history,
|
||||
and doctor; `watch` was rejected as an invalid command.
|
||||
- The Linux image exposed the same command set, but an assembled native Linux
|
||||
package had no package-root launcher or preparation workflow.
|
||||
- First installation required token-bearing process arguments. Later lifecycle
|
||||
commands already read the private installed JSON configuration.
|
||||
- Active quickstart and operations instructions recommended server cap zero for
|
||||
routine local maintenance.
|
||||
- An unreachable-server negative check made `stop --timeout 120` return a
|
||||
non-drained receipt with exit code 2 instead of reporting false success.
|
||||
|
||||
## Fresh artifact identities
|
||||
|
||||
| Artifact | Identity |
|
||||
| --- | --- |
|
||||
| Final Windows ZIP SHA-256 | `210eb61e8d6c35b014b39b18b4dd7e28e1e057a11d57790188f7904487bac004` |
|
||||
| Windows package manifest | `4572e349cead890c4efdc113e4d41285981086db7c0783fb67493fdeb6bac04c` |
|
||||
| Linux/Docker image | `sha256:8bc99d9e7e5f5f364de9b7d2b30100942b5ce3d9170a64e5abf0068ffc3d02c4` |
|
||||
| Linux package manifest | `19907f29382bd2b5a1de13fd53a829e97a5626fbacbed8f4286071ba4d5a9bec` |
|
||||
|
||||
The final Windows ZIP was rebuilt after the last documentation correction. Its
|
||||
full lifecycle run used the same package-manifest identity; the rebuild changed
|
||||
only packaged operator-document bytes outside worker code authority.
|
||||
|
||||
## Checked command matrix
|
||||
|
||||
| Environment | YAML install | Doctor | Start | Status | Attach | Watch | Stop |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| Windows package | pass | pass | pass | pass | pass | pass | `drained=true`, `exit_code=0` |
|
||||
| Native Linux package under `/opt` | pass | pass | pass | pass | pass | pass | `drained=true`, `exit_code=0` |
|
||||
| Docker image with persistent volume | stdin pass | pass | pass | pass | pass | pass | `drained=true`, `exit_code=0` |
|
||||
|
||||
The stopped Docker container reported `status=exited`, `exit=0`, and
|
||||
`oom=false`. `attach` and `watch` detached without stopping the verified worker
|
||||
on every environment.
|
||||
|
||||
## Documentation result
|
||||
|
||||
The active general guide and operations runbook contain no cap-zero routine and
|
||||
no token-bearing install command. Separate Windows, native Linux, and Docker
|
||||
cheatsheets contain copy-paste install, start, stop, attach, status, and watch
|
||||
commands. Historical dated validation reports retain factual records of earlier
|
||||
cap-zero experiments and are not active instructions.
|
||||
|
||||
## Final gates
|
||||
|
||||
- Focused worker/package/documentation matrix: `157 passed, 3 skipped`.
|
||||
- Windows packaged `watch --help`: pass.
|
||||
- Linux image launcher, preparation script, packaged cheatsheets, and shell
|
||||
syntax smoke: pass.
|
||||
- Worker Compose rendering: pass.
|
||||
- Python compilation: pass.
|
||||
- Strict OpenSpec validation: pass.
|
||||
|
||||
## Release build
|
||||
|
||||
The final `dist/release-20260930-linux` release includes both native Linux and
|
||||
Docker Linux artifacts plus all platform sheets under `cheatsheets/`. All
|
||||
entries in `SHA256SUMS.txt` passed verification. The Docker bundle also contains
|
||||
the sheets and both `workerctl` helpers, and all eight internal checksums passed.
|
||||
The native archive contained no absolute paths, parent traversal, or links; its
|
||||
launchers retained mode 0755 and passed an extracted `/opt` preparation and CLI
|
||||
smoke test.
|
||||
|
||||
| Release artifact | SHA-256 |
|
||||
| --- | --- |
|
||||
| Native Linux package | `e44717c9e84fc73d1d0734189da5b809c1c2271648868c05caea954bf46f6ebc` |
|
||||
| Docker Linux image archive | `80a59f180e7c1e4e5861427d94b44605a54ba08ed12198c63c3ae98c35678f63` |
|
||||
| Trusted Linux package manifest | `a3e8b73855d3b0854c5891cb5a10ff892aa0929e24046d2ce6fd28a245317e82` |
|
||||
Reference in New Issue
Block a user