126 lines
2.0 KiB
Markdown
126 lines
2.0 KiB
Markdown
# 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.
|