docs consolidation
This commit is contained in:
master
155
docs/modules/cli/cli-vs-ui-parity.md
Normal file
155
docs/modules/cli/cli-vs-ui-parity.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# Console CLI ↔ UI Parity Matrix
|
||||
|
||||
> **Audience:** Docs Guild, Console Guild, CLI Guild, DevOps automation.
|
||||
> **Scope:** Track feature-level parity between the StellaOps Console and the `stella` CLI, surface pending work, and describe the parity CI check owned by CONSOLE-DOC-23-502.
|
||||
|
||||
Status key:
|
||||
|
||||
- **✅ Available** – command exists in `StellaOps.Cli` and is documented.
|
||||
- **🟡 In progress** – command implemented but still under active delivery (task status `DOING`).
|
||||
- **🟩 Planned** – command spec’d but not yet implemented (task `TODO`).
|
||||
- **⚪ UI-only** – no CLI equivalent required.
|
||||
- **🔴 Gap** – CLI feature missing with no active task; file a task before sprint exit.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Navigation & Tenancy
|
||||
|
||||
| UI capability | CLI command(s) | Status | Notes / Tasks |
|
||||
|---------------|----------------|--------|---------------|
|
||||
| Login / token cache status (`/console/profile`) | `stella auth login`, `stella auth status`, `stella auth whoami` | ✅ Available | Command definitions in `CommandFactory.BuildAuthCommand`. |
|
||||
| Fresh-auth challenge for sensitive actions | `stella auth fresh-auth` | ✅ Available | Referenced in `docs/UI_GUIDE.md` (Admin). |
|
||||
| Tenant switcher (UI shell) | `--tenant` flag across CLI commands | ✅ Available | All multi-tenant commands require explicit `--tenant`. |
|
||||
| Tenant creation / suspension | *(pending CLI)* | 🟩 Planned | No `stella auth tenant *` commands yet – track via `CLI-TEN-47-001` (scopes & tenancy). |
|
||||
|
||||
---
|
||||
|
||||
## 2 · Policies & Findings
|
||||
|
||||
| UI capability | CLI command(s) | Status | Notes / Tasks |
|
||||
|---------------|----------------|--------|---------------|
|
||||
| Policy simulation diff, explain | `stella policy simulate` | 🟡 In progress | Implementation present; task `CLI-POLICY-20-002` marked DOING. |
|
||||
| Promote / activate policy | `stella policy promote`, `stella policy activate` | 🟩 Planned | Spec tracked under `CLI-POLICY-23-005`. |
|
||||
| History & explain trees | `stella policy history`, `stella policy explain` | 🟩 Planned | `CLI-POLICY-23-006`. |
|
||||
| Findings explorer export | `stella findings get`, `stella findings export` | 🟩 Planned | Part of `CLI-POLICY-20-003`. |
|
||||
| Explain drawer JSON | `stella policy simulate --format json` | 🟡 In progress | Same command; JSON output flagged for CLI tests. |
|
||||
|
||||
---
|
||||
|
||||
## 3 · Runs & Evidence
|
||||
|
||||
| UI capability | CLI command(s) | Status | Notes / Tasks |
|
||||
|---------------|----------------|--------|---------------|
|
||||
| Run retry / cancel | `stella runs retry`, `stella runs cancel` | 🟩 Planned | Included in export suite task `CLI-EXPORT-35-001`. |
|
||||
| Manual run submit / preview | `stella runs submit`, `stella runs preview` | 🟩 Planned | `CLI-EXPORT-35-001`. |
|
||||
| Evidence bundle export | `stella runs export --run <id> --bundle` | 🟩 Planned | `CLI-EXPORT-35-001`. |
|
||||
| Run status polling | `stella runs status` | 🟩 Planned | Same task. |
|
||||
|
||||
---
|
||||
|
||||
## 4 · Advisories, VEX, SBOM
|
||||
|
||||
| UI capability | CLI command(s) | Status | Notes / Tasks |
|
||||
|---------------|----------------|--------|---------------|
|
||||
| Advisory observations search | `stella vuln observations` | ✅ Available | Implemented via `BuildVulnCommand`. |
|
||||
| Advisory linkset export | `stella advisory linkset show/export` | 🟩 Planned | `CLI-LNM-22-001`. |
|
||||
| VEX observations / linksets | `stella vex obs get/linkset show` | 🟩 Planned | `CLI-LNM-22-002`. |
|
||||
| SBOM overlay export | `stella sbom overlay apply/export` | 🟩 Planned | Scoped to upcoming SBOM CLI sprint (`SBOM-CONSOLE-23-001/002` + CLI backlog). |
|
||||
|
||||
---
|
||||
|
||||
## 5 · Downloads & Offline Kit
|
||||
|
||||
| UI capability | CLI command(s) | Status | Notes / Tasks |
|
||||
|---------------|----------------|--------|---------------|
|
||||
| Manifest lookup (Console Downloads) | `stella downloads manifest show --artifact <id>` | 🟩 Planned | Delivered with `CONSOLE-DOC-23-502` + CLI parity commands. |
|
||||
| Mirror digest to OCI archive | `stella downloads mirror --artifact <id> --to <target>` | 🟩 Planned | Same task bundle (`CONSOLE-DOC-23-502`). |
|
||||
| Console health check | `stella console status --endpoint <url>` | 🟩 Planned | Tracked in `CONSOLE-DOC-23-502`; interim use `curl` as documented. |
|
||||
| Offline kit import/export | `stella offline kit import`, `stella offline kit export` | ✅ Available | Implemented (see `CommandHandlers.HandleOfflineKitImportAsync/HandleOfflineKitPullAsync`). |
|
||||
|
||||
---
|
||||
|
||||
## 6 · Admin & Security
|
||||
|
||||
| UI capability | CLI command(s) | Status | Notes / Tasks |
|
||||
|---------------|----------------|--------|---------------|
|
||||
| Client creation / rotation | `stella auth client create` *(planned)* | 🟩 Planned | Pending tenancy backlog `CLI-TEN-47-001`. |
|
||||
| Token revoke | `stella auth revoke export/verify` | ✅ Available | Already implemented. |
|
||||
| Audit export | `stella auth audit export` | 🟩 Planned | Needs CLI work item (Authority guild). |
|
||||
| Signing key rotation | `stella auth signing rotate` | 🟩 Planned | To be added with AUTH-CONSOLE-23-003 follow-up. |
|
||||
|
||||
---
|
||||
|
||||
## 7 · Telemetry & Observability
|
||||
|
||||
| UI capability | CLI command(s) | Status | Notes / Tasks |
|
||||
|---------------|----------------|--------|---------------|
|
||||
| Telemetry dashboard parity | `stella obs top`, `stella obs trace`, `stella obs logs` | 🟩 Planned | CLI observability epic (`CLI-OBS-51-001`, `CLI-OBS-52-001`). |
|
||||
| Incident mode toggle | `stella obs incident-mode enable|disable|status` | 🟩 Planned | CLI task `CLI-OBS-55-001`. |
|
||||
| Verify console telemetry health | `stella console status --telemetry` | 🟩 Planned | Part of `CONSOLE-DOC-23-502`. |
|
||||
|
||||
---
|
||||
|
||||
## 8 · Parity Gaps & Follow-up
|
||||
|
||||
- **Tenant and client lifecycle CLI**: create/suspend tenants, manage clients. Coordinate with Authority CLI epic (`CLI-TEN-47-001`, `CLI-TEN-49-001`).
|
||||
- **Downloads parity commands**: blocked on `CONSOLE-DOC-23-502` and DevOps pipeline `DOWNLOADS-CONSOLE-23-001`.
|
||||
- **Policy promotion/history**: requires completion of CLI policy epic (`CLI-POLICY-23-005`/`23-006`).
|
||||
- **Runs/evidence exports**: waiting on `CLI-EXPORT-35-001`.
|
||||
- **Observability tooling**: deliver `stella obs` commands before enabling parity CI checks for telemetry.
|
||||
|
||||
Document updates should occur whenever a row changes status. When promoting a command from Planned → Available, ensure:
|
||||
|
||||
1. CLI command merged with help text.
|
||||
2. Relevant UI doc references updated to remove “pending” callouts.
|
||||
3. This matrix row status updated to ✅ and task IDs moved to release notes.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Parity CI Check (CONSOLE-DOC-23-502)
|
||||
|
||||
- **Owner:** Docs Guild + DevEx/CLI Guild.
|
||||
- **Artefact:** Planned `.gitea/workflows/cli-parity-console.yml`.
|
||||
- **What it does:** Runs `scripts/check-console-cli-parity.sh` (to be committed with the workflow) which:
|
||||
1. Parses this matrix (YAML view exported from Markdown) to identify rows marked ✅.
|
||||
2. Executes `stella --help` to confirm listed commands exist.
|
||||
3. Optionally triggers smoke commands in sandbox mode (e.g., `stella policy simulate --help`).
|
||||
- **Failure action:** Workflow fails when a listed command is missing or when a row marked ✅ still contains “pending” notes. Update the matrix or fix CLI implementation before merging.
|
||||
|
||||
Until the workflow lands, run the checker locally:
|
||||
|
||||
```bash
|
||||
# Pending CONSOLE-DOC-23-502 – placeholder command
|
||||
./scripts/check-console-cli-parity.sh
|
||||
```
|
||||
|
||||
The script should emit a parity report that feeds into the Downloads workspace (`kind = "parity.report"`).
|
||||
|
||||
---
|
||||
|
||||
## 10 · Compliance checklist
|
||||
|
||||
- [ ] Matrix reflects latest command availability (statuses accurate, task IDs linked).
|
||||
- [ ] Notes include owning backlog items for every 🟩 / 🟡 row.
|
||||
- [ ] CLI commands marked ✅ have corresponding entries in `/docs/modules/cli/guides/*.md` or module-specific docs.
|
||||
- [ ] CI parity workflow description kept in sync with CONSOLE-DOC-23-502 implementation.
|
||||
- [ ] Downloads workspace links to latest parity report.
|
||||
- [ ] Install / observability guides reference this matrix for pending CLI parity.
|
||||
- [ ] Offline workflows capture CLI fallbacks when commands are pending.
|
||||
- [ ] Docs Guild review recorded in sprint log once parity CI lands.
|
||||
|
||||
---
|
||||
|
||||
## 11 · References
|
||||
|
||||
- `docs/UI_GUIDE.md` – console workflow overview for parity context.
|
||||
- `/docs/operations/console-docker-install.md` – CLI parity section for deployments.
|
||||
- `/docs/observability/ui-telemetry.md` – telemetry metrics referencing CLI checks.
|
||||
- `/docs/security/console-security.md` – security metrics & CLI parity expectations.
|
||||
- `src/Cli/StellaOps.Cli/TASKS.md` – authoritative status for CLI backlog.
|
||||
- `/docs/implplan/archived/updates/2025-10-28-docs-guild.md` – coordination note for Authority/Security follow-up.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-28 (Sprint 23).*
|
||||
|
||||
@@ -90,4 +90,4 @@ Options:
|
||||
## Related Docs
|
||||
|
||||
- Exceptions API entry point: `docs/api/exceptions.md`
|
||||
- Exception governance migration guide: `docs/migration/exception-governance.md`
|
||||
- Exception governance migration guide: `docs/technical/migration/exception-governance.md`
|
||||
|
||||
@@ -53,4 +53,4 @@ StellaOps:
|
||||
|
||||
The CLI reads the profile, applies the Authority configuration, and requests the listed scopes so the resulting tokens satisfy Task Runner and Packs Registry expectations.
|
||||
|
||||
> **Pack approval tip** – `stella pack approve` now relays `--pack-run-id`, `--pack-gate-id`, and `--pack-plan-hash` to Authority whenever it asks for `packs.approve`. Profiles don’t store these values (they change per run), but keeping the approver profile loaded ensures the CLI can prompt for the metadata, validate it against the plan hash, and satisfy the Authority procedure documented in `docs/task-packs/runbook.md#4-approvals-workflow`.
|
||||
> **Pack approval tip** – `stella pack approve` now relays `--pack-run-id`, `--pack-gate-id`, and `--pack-plan-hash` to Authority whenever it asks for `packs.approve`. Profiles don’t store these values (they change per run), but keeping the approver profile loaded ensures the CLI can prompt for the metadata, validate it against the plan hash, and satisfy the Authority procedure documented in `docs/modules/packs-registry/guides/runbook.md#4-approvals-workflow`.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Stella CLI — Policy Commands
|
||||
|
||||
> **Audience:** Policy authors, reviewers, operators, and CI engineers using the `stella` CLI to interact with Policy Engine.
|
||||
> **Imposed rule:** Submit/approve/publish flows must include lint, simulate, coverage, and shadow evidence; CLI blocks if required attachments are missing.
|
||||
# Stella CLI — Policy Commands
|
||||
|
||||
> **Audience:** Policy authors, reviewers, operators, and CI engineers using the `stella` CLI to interact with Policy Engine.
|
||||
> **Imposed rule:** Submit/approve/publish flows must include lint, simulate, coverage, and shadow evidence; CLI blocks if required attachments are missing.
|
||||
> **Supported from:** `stella` CLI ≥ 0.20.0 (Policy Engine v2 sprint line).
|
||||
> **Prerequisites:** Authority-issued bearer token with the scopes noted per command (export `STELLA_TOKEN` or pass `--token`).
|
||||
> **2025-10-27 scope update:** CLI/CI tokens issued prior to Sprint 23 (AUTH-POLICY-23-001) must drop `policy:write`/`policy:submit`/`policy:edit` and instead request `policy:read`, `policy:author`, `policy:review`, and `policy:simulate` (plus `policy:approve`/`policy:operate`/`policy:activate` for promotion pipelines).
|
||||
@@ -219,15 +219,15 @@ Options:
|
||||
`stella policy run status <runId>` retrieves run metadata.
|
||||
`stella policy run list --status failed --limit 20` returns recent runs.
|
||||
|
||||
### 4.3 History
|
||||
|
||||
```
|
||||
stella policy history P-7 --limit 20 --format table
|
||||
```
|
||||
|
||||
Shows version list with status, shadow flag, IR hash, attestation, submission/approval timestamps. Add `--runs` to include last run status per version. Exit code `0` success; `12` on RBAC error.
|
||||
|
||||
### 4.4 Replay & Cancel
|
||||
### 4.3 History
|
||||
|
||||
```
|
||||
stella policy history P-7 --limit 20 --format table
|
||||
```
|
||||
|
||||
Shows version list with status, shadow flag, IR hash, attestation, submission/approval timestamps. Add `--runs` to include last run status per version. Exit code `0` success; `12` on RBAC error.
|
||||
|
||||
### 4.4 Replay & Cancel
|
||||
|
||||
```
|
||||
stella policy run replay run:P-7:2025-10-26:auto --output bundles/replay.tgz
|
||||
@@ -239,7 +239,7 @@ Replay downloads sealed bundle for deterministic verification.
|
||||
### 4.4 Schema artefacts for CLI validation
|
||||
|
||||
- CI publishes canonical JSON Schema exports for `PolicyRunRequest`, `PolicyRunStatus`, `PolicyDiffSummary`, and `PolicyExplainTrace` as the `policy-schema-exports` artifact (see `.gitea/workflows/build-test-deploy.yml`).
|
||||
- Each run writes the files to `artifacts/policy-schemas/<commit>/` and stores a unified diff (`policy-schema-diff.patch`) comparing them with the tracked baseline in `docs/schemas/`.
|
||||
- Each run writes the files to `artifacts/policy-schemas/<commit>/` and stores a unified diff (`policy-schema-diff.patch`) comparing them with the tracked baseline in `docs/modules/policy/schemas/`.
|
||||
- Schema changes trigger an alert in Slack `#policy-engine` via the `POLICY_ENGINE_SCHEMA_WEBHOOK` secret so CLI maintainers know to refresh fixtures or validation rules.
|
||||
- Consume these artefacts in CLI tests to keep payload validation aligned without committing generated files into the repo.
|
||||
|
||||
@@ -324,4 +324,4 @@ All non-zero exits emit structured error envelope on stderr when `--format json`
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-11-26 (Sprint 307).*
|
||||
*Last updated: 2025-11-26 (Sprint 307).*
|
||||
|
||||
Reference in New Issue
Block a user