Baseline: distribution workspace before observability redesign

2026-06-02 16:08:17 +03:00
commit 055c8ced15
38 changed files with 6001 additions and 0 deletions
--- a/.agents/subplans/03-cli-and-ci.md
+++ b/.agents/subplans/03-cli-and-ci.md
@@ -0,0 +1,125 @@
+# Subplan 03 - CLI And CI Integration
+
+## Goal
+
+Make `dist` useful from CI before the admin UI exists.
+
+## Commands
+
+`dist server`:
+
+- starts `distd`
+- accepts config file and env overrides
+
+`dist doctor`:
+
+- checks config, database, storage directory, HTTPS base URL, and platform tools
+
+`dist app create`:
+
+- creates an app
+- accepts slug, display name, owner, platform ids
+
+`dist token create`:
+
+- creates scoped CI tokens
+- prints raw token once
+
+`dist ci publish`:
+
+- validates manifest
+- creates/fetches app
+- creates draft release
+- uploads artifacts
+- validates artifacts
+- publishes release
+- optionally promotes a channel
+- prints JSON output
+
+`dist release promote`:
+
+- promotes a release to a channel
+- checks policy gates
+
+`dist release rollback`:
+
+- moves a channel pointer to the previous valid release
+
+## Manifest Shape
+
+Required fields:
+
+- app slug
+- version
+- channel
+- artifacts list
+
+Artifact fields:
+
+- platform
+- path
+- filename override
+- content type override
+- metadata
+
+## Slice 1 - Parser And Help
+
+Deliver:
+
+- Top-level parser.
+- Subcommand parser.
+- Help text.
+- Exit code contract.
+
+Acceptance:
+
+- Unknown commands produce readable errors.
+- `--json` never emits human-only text on stdout.
+
+## Slice 2 - Local Publish
+
+Deliver:
+
+- `dist ci publish --manifest dist.json --local-store .dist`
+- In-memory or file-backed local mode for early testing.
+
+Acceptance:
+
+- CI flow can be dogfooded without a running HTTP server.
+
+## Slice 3 - Remote Publish
+
+Deliver:
+
+- HTTP client integration.
+- Token auth.
+- Streaming uploads with SHA-256.
+- Retry policy for safe requests.
+
+Acceptance:
+
+- Upload output includes release id, artifact ids, digests, and URLs.
+
+## Slice 4 - CI Templates
+
+Deliver:
+
+- GitHub Actions example.
+- GitLab CI example.
+- Generic shell example.
+
+Acceptance:
+
+- Users can copy the command and only set server, token, and manifest path.
+
+## Slice 5 - Observability
+
+Deliver:
+
+- Structured logs.
+- `--verbose`.
+- Machine-readable errors under `--json`.
+
+Acceptance:
+
+- CI logs explain what failed without leaking tokens.