stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
fac626db8dc0d8143a3f3c92de78bc00f45fc053
git.stella-ops.org/docs/ui/policy-editor.md
master d870da18ce Restructure solution layout by module
2025-10-28 15:10:40 +02:00

9.7 KiB
Raw Blame History

Policy Editor Workspace

Audience: Product/UX, UI engineers, policy authors/reviewers using the Console.
Scope: Layout, features, RBAC, a11y, simulation workflow, approvals, run dashboards, and offline considerations for the Policy Engine v2 editor (“Policy Studio”).

The Policy Editor is the primary Console workspace for composing, simulating, and approving stella-dsl@1 policies. It combines Monaco-based editing, diff visualisations, and governance tools so authors and reviewers can collaborate without leaving the browser.

1 · Access & Prerequisites

  • Routes: /console/policy (list) → /console/policy/:policyId/:version?.
  • Scopes / roles:
    • policy:author (role policy-author) to edit drafts, run lint/compile, and execute quick simulations.
    • policy:review (role policy-reviewer) to review drafts, leave comments, and request changes.
    • policy:approve (role policy-approver) to approve or reject submissions.
    • policy:operate (role policy-operator) to trigger batch simulations, promotions, and canary runs.
    • policy:audit (role policy-auditor) to access immutable history and audit exports.
    • policy:simulate to run simulations from Console; findings:read to open explain drawers.
  • Feature flags: policyStudio.enabled (defaults true once Policy Engine v2 API available).
  • Browser support: Evergreen Chrome, Edge, Firefox, Safari (last two versions). Uses WASM OPA sandbox; ensure COOP/COEP enabled per UI architecture.

2 · Workspace Layout

┌────────────────────────────────────────────────────────────────────────────┐
│ Header: Policy selector • tenant switch • last activation banner           │
├────────────────────────────────────────────────────────────────────────────┤
│ Sidebar (left)      │ Main content (right)                                 │
│ - Revision list      │ ┌───────────── Editor tabs ───────────────┐         │
│ - Checklist status   │ │  DSL  │  Simulation  │  Approvals  │ ... │         │
│ - Pending reviews    │ └─────────────────────────────────────────┘         │
│ - Run backlog        │                                                     │
│                      │ Editor pane / Simulation diff / Run viewer          │
└────────────────────────────────────────────────────────────────────────────┘
  • Sidebar: Revision timeline (draft, submitted, approved), compliance checklist cards, outstanding review requests, run backlog (incremental queue depth and SLA).
  • Editor tabs:
    • DSL (primary Monaco editor)
    • Simulation (pre/post diff charts)
    • Approvals (comments, audit log)
    • Runs (heatmap dashboards)
    • Explain Explorer (optional drawer for findings)
  • Right rail: context cards for VEX providers, policy metadata, quick links to CLI/API docs.

Placeholder screenshot: ![Policy editor workspace](../assets/policy-editor/workspace.png) (add after UI team captures latest build).

3 · Editing Experience

  • Monaco editor configured for stella-dsl@1:
    • Syntax highlighting, IntelliSense for rule/action names, snippets for common patterns.
    • Inline diagnostics sourced from /policies/{id}/lint and /compile.
    • Code actions (“Fix indentation”, “Insert requireVex block”).
    • Mini-map disabled by default to reduce contrast noise; toggle available.
  • Keyboard shortcuts (accessible via ?):
    • Ctrl/Cmd + S – Save draft (uploads to API if changed).
    • Ctrl/Cmd + Shift + Enter – Run lint + compile.
    • Ctrl/Cmd + Shift + D – Open diff view vs baseline.
    • Alt + Shift + F – Format document (canonical ordering).
  • Schema tooltips: Hover on profile, rule, action to view documentation (sourced from DSL doc).
  • Offline warnings: When sealed mode detected, banner reminds authors to validate with offline bundle.

4 · Simulation & Diff Panel

  • Triggered via “Run simulation” (toolbar) or automatically after compile.
  • Displays:
    • Summary cards: total findings added/removed/unchanged; severity up/down counts.
    • Rule hit table: top rules contributing to diffs with percentage change.
    • Component list: virtualised table linking to explain drawer; supports filters (severity, status, VEX outcome).
    • Visualisations: stacked bar chart (severity deltas), sparkline for incremental backlog impact.
  • Supports run presets:
    • Golden SBOM set (default)
    • Custom SBOM selection (via multi-select and search)
    • Import sample JSON from CLI (Upload diff).
  • Diff export options:
    • Download JSON (same schema as CLI output)
    • Copy as Markdown for review comments
  • Simulation results persist per draft version; history accessible via timeline.

5 · Review & Approval Workflow

  • Commenting: Line-level comments anchored to DSL lines; global comments supported. Uses rich text (Markdown subset) with mention support (@group/sec-reviewers).
  • Resolution: Approvers/reviewers can mark comment resolved; history preserved in timeline.
  • Approval pane:
    • Checklist (lint, simulation, determinism CI) with status indicators; links to evidence.
    • Reviewer checklist (quorum, blocking comments).
    • Approval button only enabled when checklist satisfied.
  • Audit log: Chronological view of submit/review/approve/archive events with actor, timestamp, note, attachments.
  • RBAC feedback: When user lacks permission, actions are disabled with tooltip referencing required scope(s).
  • Notifications: Integration with Notifier—subscribe/unsubscribe from review reminders within panel.

6 · Runs & Observability

  • Run tab consumes /policy/runs data:
    • Heatmap of rule hits per run (rows = runs, columns = top rules).
    • VEX override counter, suppressions, quieted findings metrics.
    • Incremental backlog widget (queue depth vs SLA).
    • Export CSV/JSON button.
  • Replay/Download: For each run, actions to download sealed replay bundle or open CLI command snippet.
  • Alert banners:
    • Determinism mismatch (red)
    • SLA breach (amber)
    • Pending replay (info)

7 · Explain & Findings Integration

  • Inline “Open in Findings” button for any diff entry; opens side drawer with explain trace (same schema as /findings/*/explain).
  • Drawer includes:
    • Rule sequence with badges (block/warn/quiet).
    • VEX evidence and justification codes.
    • Links to advisories (Concelier) and SBOM components.
  • Copy-to-clipboard (JSON) and “Share permalink” features (permalinks encode tenant, policy version, component).

8 · Accessibility & i18n

  • WCAG 2.2 AA:
    • Focus order follows logical workflow; skip link available.
    • All actionable icons paired with text or aria-label.
    • Simulation charts include table equivalents for screen readers.
  • Keyboard support:
    • Alt+1/2/3/4 to switch tabs.
    • Shift+? toggles help overlay (with key map).
  • Internationalisation:
    • Translations sourced from /locales/{lang}.json.
    • Date/time displayed using user locale via Intl.DateTimeFormat.
  • Theming:
    • Light/dark CSS tokens; Monaco theme syncs with overall theme.
    • High-contrast mode toggled via user preferences.

9 · Offline & Air-Gap Behaviour

  • When console operates in sealed enclave:
    • Editor displays “Sealed mode” banner with import timestamp.
    • Simulation uses cached SBOM/advisory/VEX data only; results flagged accordingly.
    • “Export bundle” button packages draft + simulations for transfer.
  • Approvals require local Authority; UI blocks actions if policy:approve scope absent due to offline token limitations.
  • Run tab surfaces bundle staleness warnings (policy_runs.inputs.env.sealed=true).

10 · Telemetry & Testing Hooks

  • User actions (simulate, submit, approve, activate) emit telemetry (ui.policy.action spans) with anonymised metadata.
  • Console surfaces correlation IDs for lint/compile errors to ease support triage.
  • Cypress/Playwright fixtures available under ui/policy-editor/examples/; docs should note to re-record after significant UI changes.

11 · Compliance Checklist

  • Lint integration: Editor surfaces diagnostics from API compile endpoint; errors link to DSL documentation.
  • Simulation parity: Diff panel mirrors CLI schema; export button tested.
  • Workflow RBAC: Buttons enable/disable correctly per scope (policy:write/submit/review/approve).
  • A11y verified: Keyboard navigation, focus management, colour contrast (light/dark) pass automated Axe checks.
  • Offline safeguards: Sealed-mode banner and bundle export flows present; no network calls trigger in sealed mode.
  • Telemetry wired: Action spans and error logs include policyId, version, traceId.
  • Docs cross-links: Links to DSL, lifecycle, runs, API, CLI guides validated.
  • Screenshot placeholders updated: Replace TODO images with latest UI captures before GA.

Last updated: 2025-10-26 (Sprint 20).