stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

Finalize UI truthfulness and bootstrap hardening

Browse Source
This commit is contained in:
master
2026-04-16 16:23:54 +03:00
parent 4799aa2402
commit bc6b1c5959
145 changed files with 10503 additions and 9837 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/modules/cli/guides/admin/admin-reference.md
View File

@@ -4,7 +4,7 @@
## Overview
The `stella admin` command group provides administrative operations for platform management. These commands require elevated authentication and are used for policy management, user administration, feed configuration, and system maintenance.
The `stella admin` command group provides administrative operations for platform management. These commands require elevated authentication and are used for policy management, user administration, feed configuration, diagnostics, and system maintenance.
## Authentication
@@ -30,6 +30,7 @@ Admin commands require one of the following authentication methods:
| `stella admin policy` | `admin.policy` | Policy management operations |
| `stella admin users` | `admin.users` | User administration |
| `stella admin feeds` | `admin.feeds` | Feed management |
| `stella admin diagnostics` | `ops.health` / `ops.admin` | Platform readiness and operator diagnostics |
| `stella admin system` | `admin.platform` | System operations |
## Command Reference
@@ -327,6 +328,42 @@ stella admin feeds history --source osv --limit 50
---
### stella admin diagnostics
Readiness and operator diagnostics backed by the Platform service.
#### stella admin diagnostics health
Show the canonical platform readiness summary, including setup-blocking required dependencies and configured optional post-boot services.
**Usage:**
```bash
stella admin diagnostics health [--detail] [--format <format>]
```
**Options:**
- `--detail` - Include endpoint information in the table output
- `--format <format>` - Output format: `table` (default), `json`
**Notes:**
- Required dependencies are the same blockers used by `stella setup status` and setup finalization.
- Optional dependencies are configured post-boot services discovered by the Platform readiness endpoint.
- JSON output is camelCase and intended to stay machine-readable.
**Examples:**
```bash
# Show readiness in the default table view
stella admin diagnostics health
# Include endpoint details for each dependency
stella admin diagnostics health --detail
# Emit the readiness payload for automation
stella admin diagnostics health --format json
```
---
### stella admin system
System management and health commands.
@@ -408,6 +445,7 @@ Admin commands call the following backend APIs:
| `/api/v1/admin/feeds/status` | GET | `stella admin feeds status` |
| `/api/v1/admin/feeds/{id}/refresh` | POST | `stella admin feeds refresh` |
| `/api/v1/admin/feeds/{id}/history` | GET | `stella admin feeds history` |
| `/api/v1/platform/health/readiness` | GET | `stella admin diagnostics health` |
| `/api/v1/admin/system/status` | GET | `stella admin system status` |
| `/api/v1/admin/system/info` | GET | `stella admin system info` |

7
docs/modules/cli/guides/commands/auth.md
View File

@@ -11,11 +11,17 @@ Acquire and cache an access token using the configured Authority credentials.
```bash
stella auth login
stella auth login --force
STELLAOPS_AUTHORITY_CLIENT_ID=stellaops-cli-automation \
STELLAOPS_AUTHORITY_CLIENT_SECRET=stellaops-local-cli-automation-secret \
stella auth login --json
```
Notes:
- `--force` ignores cached tokens and forces re-authentication.
- Credential sources are configuration-driven (profile/env). This command does not accept raw tokens on the command line.
- When no Authority client ID is configured, the CLI defaults to the seeded human client `stellaops-cli`.
- In a fresh interactive local/dev shell, `auth login` prompts for username/password and uses the current password-grant bootstrap path on that human client.
- For non-interactive automation, configure a confidential client such as the seeded local/dev `stellaops-cli-automation`.
### auth status / whoami / logout
@@ -82,4 +88,3 @@ Flags:
## Offline notes
- `auth login` and token mint/delegate require connectivity to Authority.
- `auth revoke verify`, `status`, `whoami`, and `logout` can operate using local cached state.

53
docs/modules/cli/guides/commands/reference.md
View File

@@ -59,6 +59,42 @@ stella config integrations <command> [options]
- `health` - Query connector health
- `impact` - Show workflow impact summary
- `discover` - Discover provider resources such as repositories, projects, jobs, pipelines, or tags
- `bootstrap local` - Bootstrap the Stella-owned local compose fixture catalog end to end
- `secrets targets` / `secrets upsert-bundle` - Stage authref-backed secret bundles against writable secret-authority targets
### stella config integrations bootstrap local
Bootstrap the owned local compose fixture lane without dropping into fixture-native APIs.
**Usage:**
```bash
stella config integrations bootstrap local [--include-gitlab] [--include-gitlab-registry] [--format table|json]
```
**Options:**
| Option | Description |
|--------|-------------|
| `--include-gitlab` | Add the local GitLab Server and GitLab CI fixtures. The CLI mints the owned local PAT and stages it into Vault automatically. |
| `--include-gitlab-registry` | Add the optional local GitLab container registry fixture. Requires the heavy GitLab compose profile with `GITLAB_ENABLE_REGISTRY=true`. |
| `--format <table\|json>` | Output format. `json` is machine-readable and exits non-zero when any selected integration is unhealthy. |
**Examples:**
```bash
# Bootstrap the default 13-entry local compose fixture catalog
stella config integrations bootstrap local
# Add the owned local GitLab SCM and CI fixtures
stella config integrations bootstrap local --include-gitlab
# Add the full 16-entry local fixture catalog including GitLab registry
stella config integrations bootstrap local --include-gitlab --include-gitlab-registry --format json
```
**Contract:**
- This command is only for Stella-owned local compose fixtures.
- Default mode creates or updates 13 deterministic local integrations and runs test plus health verification for each.
- `--include-gitlab` stages the managed local GitLab PAT through Secret Authority and binds the resulting `authref://...` values to GitLab Server and GitLab CI.
- Production and customer-managed third-party systems still use `secrets targets`, `secrets upsert-bundle`, and explicit `create` or `update` operations with operator-provided credentials.
**Examples:**
```bash
@@ -95,6 +131,7 @@ stella config integrations create \
**Notes:**
- `providers` returns `isTestOnly`, `supportsDiscovery`, and `supportedResourceTypes`.
- `bootstrap local` returns exit code `0` only when every selected integration tests healthy and reports healthy runtime status.
- Deprecated `stella integrations *` routes are preserved as aliases and forward to `stella config integrations *`.
- Unsupported discovery requests return a client error instead of silently falling back to sample data.
@@ -605,25 +642,27 @@ Authenticate with platform (interactive).
**Usage:**
```bash
stella auth login [--authority <url>] [--verbose]
stella auth login [--force] [--verbose]
```
**Example:**
```bash
# Interactive login (opens browser)
# Interactive login on the seeded human client
stella auth login
# Specify Authority URL
stella auth login --authority https://auth.stellaops.example.com
# Re-authenticate even when a cached token exists
stella auth login --force
```
**Output:**
```
Opening browser for authentication...
✅ Logged in as alice@example.com
Token saved to ~/.stellaops/tokens.json
Authority username: admin
Authority password for admin:
Login successful. Access token expires at 2026-04-16 12:00:00Z.
```
When no Authority client ID is configured, the CLI defaults to the seeded human client `stellaops-cli` and prompts for username/password in an interactive shell. For automation, configure a confidential client such as `stellaops-cli-automation`.
---
### stella auth logout

88
docs/modules/cli/guides/setup-guide.md
View File

@@ -10,6 +10,22 @@ This guide covers the current `stella setup` command set for installation-scoped
- It uses the Platform setup session APIs as the source of truth. Local files are not the authoritative setup state.
- Tenant onboarding such as integrations, secrets providers, advisory sources, environments, agents, and notifications happens on the authenticated `/setup/*` surfaces and the corresponding CLI command groups.
## Retained Secrets
- Setup session `draftValues` remain sanitized. Passwords and similar secret-bearing fields are not echoed back through normal session reads.
- When the backend needs a secret to survive resume/apply, it retains that value in protected companion storage and exposes only `secretDrafts` metadata in `stella setup status --json`.
- Re-running or resuming setup without re-entering a retained secret keeps the server-retained value for probe/apply.
- Supplying a new secret value replaces the retained one for that setup session.
- Backend protection key precedence is `Platform:Setup:SecretProtectionKey`, `STELLAOPS_SECRETS_ENCRYPTION_KEY`, then `STELLAOPS_BOOTSTRAP_KEY`.
## Operational Readiness
- `stella setup status` reports required control-plane readiness only.
- Text output prints an `Operational readiness` section with the current required counts, blocker summary, and any blocking dependencies.
- `stella setup status --json` includes a `readiness` object for automation. This payload is intentionally required-only; optional post-boot services are not mixed into setup gating.
- `stella setup run` finalization stops with an explicit error if any required readiness dependency is still blocked.
- Optional post-boot services belong to `stella admin diagnostics health`, not to setup completion.
## Quick Start
```bash
@@ -35,6 +51,29 @@ stella setup reset --step cache
stella setup reset --all --force
```
## First Auth After Setup
Fresh local/dev installs seed first-party CLI auth clients through `etc/authority/plugins/standard.yaml`.
Human operators:
```bash
stella auth login
```
- The CLI defaults to the seeded human client `stellaops-cli`.
- In a fresh interactive shell, if no Authority username/password is preconfigured, the CLI prompts and uses the current password-grant bootstrap path.
Automation:
```bash
export STELLAOPS_AUTHORITY_CLIENT_ID=stellaops-cli-automation
export STELLAOPS_AUTHORITY_CLIENT_SECRET=stellaops-local-cli-automation-secret
stella auth login --json
```
Production deployments should replace local/dev secrets and can tighten the allowed grants for these first-party clients.
## Supported Steps
| Step | Purpose | Notes |
@@ -91,7 +130,11 @@ Show the current installation-scoped session.
Options:
- `--session` - explicit setup session ID
- `--json` - machine-readable output
- `--json` - machine-readable output including sanitized `draftValues` and retained-secret `secretDrafts` metadata
Notes:
- The status surface carries required-only readiness because setup is allowed to finish before optional post-boot services come online.
- Use `stella admin diagnostics health` when you need the full required-plus-optional platform readiness view.
### `stella setup reset`
@@ -146,13 +189,34 @@ crypto:
When `stella setup` finishes, the next work is tenant onboarding, not more bootstrap steps.
Typical next commands:
If you are bringing up the Stella-owned local compose fixture lane, authenticate first and use the owned fixture bootstrap command:
```bash
# Authenticate into the target tenant if needed
stella auth login
# Bootstrap the default 13-entry local fixture catalog
stella config integrations bootstrap local
# Add the owned local GitLab SCM and CI fixtures
stella config integrations bootstrap local --include-gitlab
# Also add the optional local GitLab registry fixture
stella config integrations bootstrap local --include-gitlab --include-gitlab-registry
```
The local bootstrap contract is explicit:
- default mode creates or updates the 13 deterministic local compose entries and verifies their health
- `--include-gitlab` mints the owned local GitLab PAT, stages it through Secret Authority into Vault, then binds GitLab Server and GitLab CI with the returned `authref://...` values
- `--include-gitlab-registry` adds the optional GitLab container registry entry for the heavy GitLab compose profile with registry enabled via `GITLAB_ENABLE_REGISTRY=true`
For production or customer-managed third-party systems, use bring-your-own-secret onboarding instead of the local fixture bootstrap:
```bash
# Discover writable secret-authority targets
stella config integrations secrets targets
# Stage a GitLab access token into a secret-authority target
# Stage an operator-provided GitLab access token into a secret-authority target
stella config integrations secrets upsert-bundle \
--bundle gitlab-server \
--target <vault-integration-id> \
@@ -161,10 +225,10 @@ stella config integrations secrets upsert-bundle \
# Create the GitLab server integration with the returned authref
stella config integrations create \
--name local-gitlab \
--name customer-gitlab \
--type scm \
--provider gitlabserver \
--endpoint http://gitlab.stella-ops.local:8929 \
--endpoint https://gitlab.example.com \
--authref authref://vault/gitlab/server#access-token
```
@@ -197,11 +261,24 @@ Check:
- the runtime cache service is reachable
- the host/port/password values are correct
### Setup finalization is blocked by operational readiness
```bash
stella setup status --json
stella admin diagnostics health --detail
```
Check:
- which required dependency is still reported as `blocked` in the setup status `readiness` payload
- whether `frontdoor` or `authority` is failing its live probe
- whether optional post-boot service degradation is being mistaken for a setup blocker
### Setup reports that `vault` or `scm` is no longer a supported step
That is expected. Those flows moved out of installation bootstrap.
Use:
- `stella config integrations bootstrap local` for the Stella-owned local compose fixture lane
- `stella config integrations secrets *`
- `stella config integrations create`
- the authenticated `/setup/integrations/*` UI
@@ -209,6 +286,7 @@ Use:
## Related Commands
- `stella setup status --json`
- `stella config integrations bootstrap local`
- `stella config integrations providers`
- `stella config integrations secrets targets`
- `stella config integrations secrets upsert-bundle`

2
docs/modules/cli/guides/troubleshooting.md
View File

@@ -719,6 +719,8 @@ stella --verbose scan docker://nginx:latest
stella --verbose crypto sign --provider gost --file doc.pdf
```
Startup Authority and crypto diagnostics are emitted only in verbose human-readable flows. Structured output commands such as `--json`, `--raw`, and `--format json` suppress that startup noise so stdout remains parseable.
---
## Getting Help