git.stella-ops.org/EPIC_12.md

No file to print
Fine. Let’s give the keyboard crowd first‑class citizenship so they stop side‑eyeing the UI. You get a proper CLI and reusable automation packs instead of hand‑rolled bash folklore.

> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

---

# Epic 12: CLI Parity & Task Packs

**Short name:** `CLI Parity & Task Packs`
**Primary components:** `stella` CLI, `task-runner` service, `packs-registry`
**Surfaces:** CLI, Web API, Console (docs, pack browser)
**Touches:** Orchestrator, Policy Engine, Findings Ledger, Export Center, Notifications Studio, Conseiller (Feedser), Excitator (Vexer), VEX Consensus Lens, Authority (authN/Z), Object Storage/KMS, Telemetry

**AOC ground rule reminder:** Conseiller and Excitator aggregate but never merge. CLI commands must show links to the original advisories/VEX/SBOM evidence and must not mutate or “rewrite” those records.

---

## 1) What it is

Two big deliverables:

1. **CLI Parity:** a single, consistent, script‑friendly `stella` command‑line that exposes everything the Web Console can do. Same features, same vocabulary, same policy semantics, same permissions. It supports interactive and non‑interactive modes, offers stable machine outputs (JSON/YAML), and has predictable exit codes for CI.

2. **Task Packs:** declarative, signed, versioned automation bundles that encode multi‑step workflows. Packs stitch together CLI/API actions with variables, conditions, loops, approvals, and policy gates. They’re reusable across tenants and environments, distributable via a small registry or object storage, and executable locally via the CLI or remotely via the Orchestrator.

---

## 2) Why (brief)

Because “click it again but faster” isn’t automation. Teams need repeatable flows they can review, sign, diff, and run without babysitting. Also, if the UI can do something the CLI can’t, engineers will invent three shell scripts and a headache. Let’s not.

---

## 3) How it should work (maximum detail)

### 3.1 CLI design principles

* **Single binary:** `stella` for Linux/macOS/Windows; static builds; no runtime dependencies.
* **Resource model:** nouns match API and Console: `policy`, `sbom`, `advisory`, `vex`, `scan`, `job`, `orchestrator`, `notify`, `export`, `auth`, `pack`.
* **Verb grammar:** `list`, `get`, `create`, `update`, `delete`, `run`, `simulate`, `explain`, `diff`. No cute aliases.
* **Global flags:**
  `--profile`, `--context`, `--tenant`, `--format json|yaml|table`, `--quiet`, `--verbose`, `--trace`, `--color auto|never|always`, `--no-prompt`, `--token`, `--endpoint`, `--namespace`, `--timeout`, `--output file`, `--confirm`.
* **Config precedence:** flags > env vars > profile file (`~/.stella/config`) > system default. Deterministic. Show effective config with `stella config show --resolved`.
* **Profiles & contexts:** named endpoints and tenants; switch like: `stella use profile prod`.
* **Auth:** device code or PAT; tokens cached in OS keychain; short‑lived signed commands supported for headless CI.
* **RBAC surfaced:** commands error with “forbidden” showing the exact missing scope (from Authority).
* **Idempotency:** create/update accept `--idempotency-key`; retries never double‑create.
* **Offline & caching:** `stella cache pull|push|clear`; read‑only operations can target the local cache with `--offline`.
* **STDOUT/STDERR discipline:** machine data goes to STDOUT, human explanations to STDERR unless `--format table`.

### 3.2 Output & UX

* **Stable schemas:** JSON/YAML outputs adhere to published schemas with semantic versioning. Minor changes are additive.
* **Tables:** sensible defaults with `--columns`, `--sort`, `--filter`. Always include a unique ID column.
* **Explainability:** `--explain` appends a section showing policy rationale IDs, matching rule names, and links.
* **Progress:** spinners to STDERR; `--no-progress` for CI.
* **Exit codes:**
  `0` success, `1` generic error, `2` bad input, `3` unauthorized, `4` forbidden, `5` not found, `6` conflict, `7` timeout, `8` dependency failure, `9` partial success (some items failed), `10` validation error.

### 3.3 Parity contract

Every Console action must have a CLI equivalent with the same effect and the same policy evaluation. Release gating includes a **parity matrix** that must be green before shipping. No “UI‑only magic.”

**Coverage buckets:**

* **Policy Studio:** author, version, import/export, simulate, dry‑run, attach to scopes, approval gates.
* **SBOM Graph Explorer:** load, index, query, focus/zoom, graph export, diff two SBOMs, evidence links.
* **Vulnerability Explorer:** list, filter, policy‑aware risk, remediation export, suppressions with rationale.
* **VEX Consensus Lens:** pull sources, compute consensus, view deltas, evidence lineage.
* **Notifications Studio:** rules, templates, simulation, incidents, acks, digests.
* **Orchestrator:** sources, jobs, schedules, runs, logs, artifacts.
* **Export Center:** produce JSON bundles, Trivy‑compatible DBs, mirror bundles, verify signatures.
* **AOC enforcement:** status, evaluate, enforce, exemptions by policy with time‑bound approvals.
* **Admin:** tenants, roles, service health, feature flags.

### 3.4 Task Packs: the spec

* **Format:** YAML or JSON.
* **Signature:** optional but recommended; detached signature stored alongside the pack; Ed25519 default.
* **Top‑level fields:**

  ```yaml
  apiVersion: packs.stella.dev/v1
  kind: TaskPack
  metadata:
    name: sbom-risk-triage
    version: 1.2.0
    description: Triage new high-risk advisories across prod images
    labels: { domain: sbom, criticality: high }
  spec:
    parameters:
      - name: env
        type: string
        required: true
        allowed: [prod, staging]
      - name: risk_min
        type: string
        default: high
      - name: image_selector
        type: string
        default: "env:${{ params.env }} AND type:image"
    approvals:
      - name: security-approve
        role: Policy.Admin
        description: Approve applying suppressions
    steps:
      - id: fetch
        use: cli
        run: stella vuln list --selector "${{ params.image_selector }}" --risk-at-least "${{ params.risk_min }}" --format json --output state/findings.json
      - id: explain
        use: cli
        run: stella vuln explain --input state/findings.json --format table
      - id: simulate
        use: cli
        run: stella policy simulate --input state/findings.json --policy current --format json --output state/sim.json
      - id: gate
        use: policyGate
        when: "${{ steps.simulate.outputs.block_count > 0 }}"
        requireApproval: security-approve
      - id: notify
        use: cli
        run: stella notify digests run --profile weekly-risk --format table
      - id: export
        use: cli
        run: stella export bundle create --source state/findings.json --format json --output out/bundle.json
    finally:
      - id: cleanup
        use: local
        run: rm -rf state
  ```
* **Execution modes:**

  * `local`: CLI executes steps on the caller’s machine.
  * `remote`: Orchestrator runs steps in a controlled worker with the same pack; CLI streams logs.
* **Variables:** `${{ ... }}` templating with safe expression evaluation; supports `params`, `env`, `steps.<id>.outputs`, and helper functions like `now()`, `sha256()`.
* **Conditionals:** `when:` expressions per step; missing vars cause validation errors.
* **Loops:** `foreach:` iterate over arrays; `maxParallel:` controls concurrency.
* **Outputs:** each step can write named outputs from files or command JSON to feed later steps.
* **Approvals:** sign‑off steps requiring a role; audit trail captured; CLI prompts unless `--no-prompt`, in which case the run pauses until approval is granted through the Console or API.
* **Security model:** pack subject to allowlist by tenant; signature verified; forbidden commands blocked by policy; secrets injected via redacted env from KMS; network egress controlled in remote mode.

### 3.5 Explain plan & dry runs

* `stella pack plan <file>` renders an execution graph with resolved parameters, predicted API calls, and policy gates.
* `stella pack simulate <file> --at <timestamp>` replays against historical state (Findings Ledger snapshots).

### 3.6 Distribution & provenance

* **packs-registry:** simple index stored in object storage; supports `push`, `pull`, `list`, `verify`.
* **Provenance:** each run produces a signed run manifest with: pack digest, params, approvals, outputs, linked run IDs, policy snapshot IDs, evidence references. Export Center can bundle it.

### 3.7 Integration points

* **Notifications:** pack start/finish events optionally notify with links to manifests and artifacts.
* **Policy:** gates read current or specified policy version; pack metadata can require minimum policy version.
* **AOC:** packs that touch AOC must append advisory/VEX links instead of mutating base records.

---

## 4) Architecture

### 4.1 Components

* **`cli/`**: the `stella` binary, command registry, output renderers, schema validation, auth, profiles, completion generators.
* **`src/StellaOps.TaskRunner/`**: API to accept, validate, schedule, and execute Task Packs in remote mode; runs in Orchestrator worker pods; streams logs; enforces RBAC/policy gates.
* **`src/StellaOps.PacksRegistry/`**: index and blob storage; signature verification; provenance store.
* **Shared libs:** `sdk/api-client`, `sdk/output`, `sdk/auth`, `sdk/schema`, `sdk/templating`, `sdk/pack-exec`.

### 4.2 Data model (selected tables)

* `cli_profiles` (local file): profiles, tokens metadata, last_used.
* `packs_index`: name, version, digest, tenant visibility, signature_ref, uploaded_by, created_at.
* `pack_runs`: run_id, pack_digest, params_json, mode, state, started_at, finished_at, approvers[], policy_snapshot_id.
* `pack_run_logs`: run_id, seq, ts, level, message, chunk.
* `pack_artifacts`: run_id, name, uri, content_type, hash.
* `parity_matrix`: component, capability, console_version, cli_version, status, notes.

### 4.3 Flow

1. User invokes `stella pack run foo@1.2.0 --param env=prod`.
2. CLI fetches from registry, verifies signature, validates schema and RBAC.
3. Local or remote execution begins; each step writes outputs; policy gates prompt or pause for approval.
4. Run manifest is signed and stored; notifications fire if configured; Export Center can bundle the outcome.

---

## 5) APIs

```
# Packs Registry
POST   /packs
GET    /packs?name=&version=
GET    /packs/{digest}
POST   /packs/{digest}/verify

# Task Runner
POST   /pack-runs               # { pack_ref|inline_pack, params, mode, approvals? }
GET    /pack-runs?state=&name=
GET    /pack-runs/{run_id}
WS     /pack-runs/{run_id}/logs
POST   /pack-runs/{run_id}/approve   # body includes approval name and proof
POST   /pack-runs/{run_id}/cancel

# CLI Profiles (local file; not an API)
```

---

## 6) Commands (non‑exhaustive)

```
stella version
stella login --device
stella use profile <name>
stella config show --resolved
stella whoami

stella policy list|get|create|update|delete
stella policy simulate --input file.json --policy <id|current> --format json --explain

stella sbom load --file sbom.json
stella sbom graph query --selector 'env:prod AND kind:image' --format json
stella sbom diff --left L.json --right R.json --format table

stella advisory list --source feedser --format json
stella vex list --source vexer --format json
stella vex consensus show --format table

stella vuln list --selector 'env:prod' --risk-at-least high --format table
stella vuln explain --input findings.json --format table

stella notify rules list|create|test
stella notify incidents list|ack <id>
stella export bundle create --source findings.json --output out/bundle.json
stella orchestrator jobs run --source <id> --wait
stella aoc status --scope <selector> --format table
stella aoc enforce --scope <selector> --policy <id> --confirm

# Task Packs
stella pack init --name foo
stella pack plan ./pack.yaml
stella pack run ./pack.yaml --param env=prod --no-prompt
stella pack runs list
stella pack push ./pack.yaml
stella pack pull foo@1.2.0
stella pack verify ./pack.yaml
```

---

## 7) Documentation changes

Create/update the following:

1. `/docs/cli/overview.md`
   Philosophy, installation, supported platforms, compatibility, AOC constraint.

2. `/docs/cli/configuration.md`
   Profiles, contexts, auth flows, env vars, precedence, offline mode.

3. `/docs/cli/output-and-exit-codes.md`
   Formats, schemas, tables, filters, exit codes, error handling examples.

4. `/docs/cli/commands/*.md`
   One page per noun: `policy.md`, `sbom.md`, `vuln.md`, `vex.md`, `advisory.md`, `notify.md`, `export.md`, `orchestrator.md`, `aoc.md`, `auth.md`, `pack.md`. Each includes examples and parity references.

5. `/docs/cli/parity-matrix.md`
   The checklist that must be green before release.

6. `/docs/task-packs/spec.md`
   Full schema, examples, security model, signatures, approvals, policy gates.

7. `/docs/task-packs/authoring-guide.md`
   Patterns, variables, loops, outputs, testing, dry‑runs.

8. `/docs/task-packs/registry.md`
   How to host/publish, pulling, verifying, provenance.

9. `/docs/task-packs/runbook.md`
   Troubleshooting runs, retries, remote logs, cleanup.

10. `/docs/security/pack-signing-and-rbac.md`
    Key management, signature verification, tenant allowlists, role requirements.

11. `/docs/operations/cli-release-and-packaging.md`
    Build matrix, checksums, SBOM of the CLI itself, shell completions, distribution.

> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

---

## 8) Implementation plan

### New modules

* `cli/`

  * `cmd/` command groups
  * `internal/api/` generated client
  * `internal/output/` json|yaml|table
  * `internal/config/` profiles, auth
  * `internal/schema/` validation, JSON Schema bundles
  * `internal/pack/` loader, planner, executor
  * `internal/prompt/` approvals and TTY detection

* `src/StellaOps.TaskRunner/`

  * `api/` REST + WS
  * `executor/` step engine (local shell in worker)
  * `policygate/` integration
  * `artifacts/` object storage, manifest signing
  * `audit/metrics/`

* `src/StellaOps.PacksRegistry/`

  * `index/` CRUD
  * `verify/` signature validation
  * `provenance/` run manifests

### Updates to existing services

* **Orchestrator:** add `pack-run` job type; logs streaming; artifact collection.
* **Authority:** new scopes: `Packs.Read`, `Packs.Write`, `Packs.Run`, `Packs.Approve`.
* **Export Center:** pack run manifests as exportable items.
* **Notifications:** emit `pack.run.started|completed|failed` events with links.
* **Findings Ledger:** snapshot APIs for simulation time travel.

### Packaging

* Release tarballs: `{os}-{arch}` with checksums and detached signatures.
* Shell completions: bash/zsh/fish/pwsh generated at build.
* Container image: `stella/cli:<ver>` for ephemeral CI jobs.
* Embed build metadata and SBOM for the CLI binary.

---

## 9) Engineering tasks

### CLI core

* [ ] Implement config loader with precedence and context switching.
* [ ] Device/PAT auth; keychain integration; `whoami`.
* [ ] Output renderer (json|yaml|table) with column selection and filtering.
* [ ] Error/exit code mapping.
* [ ] Global flags and telemetry opt‑in.

### Command groups

* [ ] `policy`, `sbom`, `vuln`, `vex`, `advisory`, `notify`, `export`, `orchestrator`, `aoc`, `auth`, `pack` parity implementations.
* [ ] `--explain` across policy-aware commands.
* [ ] `simulate` and `diff` subcommands where applicable.

### Task Packs

* [ ] JSON Schema v1; validator; templating engine; expression sandbox.
* [ ] Local executor with `when`, `foreach`, `maxParallel`, outputs.
* [ ] Approvals flow with `--no-prompt` pause and resume.
* [ ] Plan/simulate engine with clear diff output.
* [ ] Registry service with push/pull/verify and signatures.
* [ ] Remote mode via Task Runner; logs streaming; artifacts store.

### Security

* [ ] Signature verification; trusted keys store; rotation.
* [ ] RBAC enforcement in Task Runner and Registry.
* [ ] Secrets injection from KMS; env var redaction in logs.

### Docs & DX

* [ ] Author all docs in §7 with runnable examples.
* [ ] Generate completion scripts and man pages from command metadata.
* [ ] Parity matrix auto‑generated from Console routes + CLI commands.

### CI/CD

* [ ] Multi‑platform builds; reproducible; checksums.
* [ ] Golden tests for CLI outputs.
* [ ] E2E pack runs in CI with a tiny test cluster.

> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

---

## 10) Documentation tasks (explicit)

* [ ] `/docs/cli/parity-matrix.md`: enumerate every Console action and its CLI counterpart; mark gaps.
* [ ] `/docs/task-packs/spec.md`: publish schema and examples; include security considerations.
* [ ] `/docs/task-packs/authoring-guide.md`: three end‑to‑end tutorials: “SBOM import & triage,” “Policy promote & simulate,” “Notify storm test.”
* [ ] `/docs/cli/output-and-exit-codes.md`: include a mapping table and sample JSON error payload.
* [ ] Add “Imposed rule” line to every new page.

---

## 11) Feature changes required

* **Console:** add a “Copy CLI” button for each action to show the exact equivalent command; embed parity links.
* **Web API:** ensure all Console workflows map to public endpoints; no UI‑only backdoors.
* **Orchestrator:** treat Task Pack runs as first‑class jobs; unify logs and artifacts.
* **Policy Engine:** provide stable, referenced rationale IDs consumable by `--explain`.
* **Notifications:** pack run events with deep links; ack from CLI.
* **Export Center:** one‑click export of a pack run manifest and artifacts bundle.

---

## 12) Acceptance criteria

* 100% of the parity matrix green for GA scope.
* CLI operations are reproducible and idempotent; retries do not double‑create.
* `stella pack plan` shows an accurate, validated execution plan; `simulate` matches historical state.
* Signed packs verify by default; unsigned packs require `--allow-unsigned` and get flagged in logs.
* CI‑friendly: all actions support `--no-prompt` and stable JSON outputs.
* AOC interactions only append references and never mutate Conseiller/Excitator records.
* Cross‑platform builds ship with checksums and SBOM; shell completions work.

---

## 13) Risks & mitigations

* **CLI drift vs Console.**
  Mitigation: parity matrix gates release; integration tests run both paths and diff results.

* **Task Pack injection or abuse.**
  Mitigation: signature verification, RBAC, command allowlists, sandboxed expressions, secret redaction, remote execution sandbox.

* **Non‑deterministic outputs.**
  Mitigation: stable sorting, consistent time formatting, deterministic pagination.

* **Approval bottlenecks.**
  Mitigation: multi‑approver lists, Notifications Studio integration, timeouts with safe abort.

---

## 14) Test plan

* **Unit:** config precedence, templating, validators, exit code mapping.
* **Contract:** CLI outputs against JSON Schemas; golden test fixtures.
* **Integration:** run each command against a seeded test backend; assert parity with Console responses.
* **Packs:** plan/simulate/run cycles, approvals, loops, parallelism, failure recovery, artifact capture.
* **Security:** signature tamper tests, RBAC denial cases, secret redaction in logs.
* **Load:** parallel Task Pack runs with 1k steps total; log streaming backpressure.
* **Cross‑platform:** run the same pack on Linux/macOS/Windows runners; output diffs must be empty.

---

## 15) Philosophy

* **CLIs are contracts.** If a script breaks because we shuffled fields, we failed.
* **Declarative beats duct tape.** Task Packs should outlive their authors and be auditable.
* **Explain or it didn’t happen.** Every deny, every notification, every pack step must show its why.

> Final reminder: **Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.**