Workbench Ops Actions — 100% Implementation Plan (P1.5)

Goal: Deliver production-quality Workbench Ops Actions in the Workbench UI with complete backend support, secure execution, observable run history, and zero gaps. This plan assumes P0.1 auth is active and enforced for privileged actions.

Outcomes (Definition of Done)

Workbench UI exposes Ops Actions as a first-class, discoverable module with clear status, run history, and logs.
Actions run server-side via a strict allowlist (no arbitrary command execution).
All actions are authenticated and authorized (role + scope) with audit logging.
Runs are asynchronous, cancellable, and stream logs to the UI.
API responses are typed, validated, and versioned; UI consumes via a typed client.
Tests cover backend execution, auth rules, and UI flows (unit + integration + e2e).
Documentation and runbooks are updated; no TODOs or placeholders remain.

Scope (P1.5 Actions)

Primary actions (from docs/workdocs/last-mile-plan.md):

Regenerate Code
Validate Specs
Run Gap Report

Simple UX enhancements (high impact, low complexity):

Action presets (per context) with last-run summary
Run history with filters (status, action, context)
Streaming logs + copy/export
Safety confirmations for mutating actions
“Dry run” / “No-online” toggles where supported

Assumptions / Constraints

Must not edit generated code zones.
Server-side actions must be allowlisted and parameterized (no arbitrary shell).
Prefer just recipes for operational tasks; use Nx targets only if required by policy.
Execution needs to respect timeouts and concurrency limits.
A Workbench BFF endpoint is the preferred integration point for /api/*.
Governance audit sink is the primary source of truth for ops audit logs, with local JSONL fallback.

Phase 0 — Alignment and Inventory

Confirm exact action commands + parameters (source of truth).
- Validate Specs: just spec-guard (support --dir for context scope).
- Regenerate Code: just pipeline <ctx> (or nx run specs-<ctx>:all if mandated).
- Gap Report: just gap-report <ctx> --no-online --json for structured results.
Confirm context list source:
- Use manifest registry (same source as Manifest Inspector) for valid context identifiers.
Confirm required scopes and roles for each action.

Phase 1 — Backend API and Execution Engine (Workbench BFF)

1.1 API Models and Routes

Add Ops models to services/workbench-bff/src/models.py:

OpsActionModel (id, name, description, parameters, requiredRole, requiredScopes)
OpsRunRequestModel (actionId, context, options)
OpsRunStatusModel (id, actionId, status, startedAt, finishedAt, exitCode)
OpsRunLogChunkModel (runId, timestamp, stream, line)
OpsRunSummaryModel (stdoutTail, stderrTail, artifacts)

Add routes in services/workbench-bff/src/api/routes.py or new ops_routes.py:

GET /ops/actions (list allowlisted actions + parameters)
POST /ops/runs (create run, return run id)
GET /ops/runs (query by action, status, context)
GET /ops/runs/{run_id} (status + metadata)
GET /ops/runs/{run_id}/logs (SSE or chunked logs)
POST /ops/runs/{run_id}/cancel (cancel run)

1.2 Ops Runner Adapter

Create services/workbench-bff/src/adapters/ops_runner.py:

Allowlist of actions -> command templates
Context parameter validation (from manifest registry)
Safe subprocess execution with:
- fixed working directory
- environment allowlist
- timeouts per action
- capped output sizes
Async job registry with persistence:
- metadata + logs stored in artifacts/workbench/ops-runs/ (run_id/*)
- summary JSON per run for history

1.3 Security and Authorization

Add server-side auth enforcement for ops endpoints:

Validate bearer token (OIDC/JWT) with configurable issuer and JWKS URL.
Map token claims to roles/scopes; reject if missing required access.
Add explicit ops scopes in UI + server. Proposed scopes:
- ops:validate (Validate Specs)
- ops:generate (Regenerate Code)
- ops:gap-report (Gap Report)
- Optional: ops:all for admin override
Add audit log record per run (action, user, context, status).
- primary: governance audit sink; fallback: artifacts/workbench/ops-audit.log (JSONL)

1.4 Observability

Emit structured logs for run lifecycle transitions.
Record runtime metrics (duration, exit code, failure reason).
Add error envelopes for API responses (consistent shape).

1.5 Backend Tests

Unit tests for command allowlist and parameter validation.
Integration tests for run lifecycle (start -> stream -> complete).
Auth tests verifying role/scope enforcement.

Phase 2 — Workbench UI (Operations Page)

Add route to apps/workbench/src/App.tsx (e.g., /operations).
Add nav item and icon; align with existing nav style.

2.2 API Client + Types

Add apps/workbench/src/lib/operations-api.ts:

listOpsActions()
startOpsRun()
getOpsRun()
streamOpsRunLogs()
cancelOpsRun()

Add types in apps/workbench/src/types/operations.ts mirroring BFF models.

2.3 UI Components

Create apps/workbench/src/pages/Operations.tsx with:

Action cards (Validate Specs / Regenerate Code / Gap Report)
Context selector (from /ops/actions + manifest contexts)
Options panel (flags like --no-online, --json)
Run status panel with live logs
Run history table (filter by action/context/status)

Leverage existing UI patterns:

card, glass, skeleton classes
Button, DropdownMenu, Avatar patterns

2.4 UX Enhancements (Simple + Powerful)

Confirm modal for mutating actions (Regenerate Code)
Show “last successful run” summary per action
Export logs / copy command / copy result JSON
Error banners with actionable remediation
Inline link to Manifest Inspector for the selected context

2.5 Frontend Authorization

Gate action buttons by useAuth().hasScope().
Disable and tooltip when insufficient permissions.
Show who is logged in (reuse UserMenu).

2.6 UI Tests

Add Playwright spec apps/workbench/e2e/operations.spec.ts:
- load page, start a run (mock API), show streaming logs
- verify permission gating
- verify error handling

Phase 3 — Wiring, Docs, QA

3.1 Service Wiring

Ensure Workbench BFF exposes ops endpoints under /api.
Validate CORS/proxy behavior in apps/workbench/vite.config.ts if needed.

3.2 Documentation

Update services/workbench-bff/README.md with new endpoints and env vars.
Update docs/workdocs/last-mile-plan.md P1.5 entry to 100% on completion.

3.3 Manual QA Checklist

Validate Specs (global and context-specific) runs and returns result JSON.
Regenerate Code (context) produces output, captures logs, and shows status.
Gap Report returns structured results and renders summary.
Auth enforcement blocks unauthorized users.
Logs and run history persist after refresh.

Detailed Action Definitions (Proposed)

Action ID	Command Template	Parameters	Notes
`validate_specs`	`just spec-guard`	`context?`, `report?`	Use `--dir docs/specs/<ctx>` for scoped runs; allow `--report` for JSON output
`regenerate_code`	`just pipeline <ctx>`	`context`	Preferred per-context; add confirmation; optionally show changed files
`gap_report`	`just gap-report <ctx> --no-online --json`	`context`, `noOnline?`	Parse JSON for UI summary

Risk Controls

Command injection: strict allowlist + no raw shell strings.
Runaway processes: timeouts and max output size.
Concurrent runs: limit concurrency; queue per action if needed.
Permissions: server-side auth required for all ops routes.
Unsafe default: no “run all contexts” without elevated role + confirmation.

Milestones and Sequencing

1) Backend ops API + allowlist runner (Phase 1.1–1.2) 2) Auth enforcement + audit log (Phase 1.3) 3) UI Operations page + typed API (Phase 2.1–2.3) 4) UX enhancements + tests (Phase 2.4–2.6) 5) Documentation + QA sign-off (Phase 3)

Files to Touch (Planned)

Backend:

services/workbench-bff/src/api/routes.py (or add ops_routes.py)
services/workbench-bff/src/models.py
services/workbench-bff/src/adapters/ops_runner.py (new)
services/workbench-bff/src/adapters/ops_auth.py (new)
services/workbench-bff/tests/test_ops_api.py (new)

Frontend:

apps/workbench/src/pages/Operations.tsx (new)
apps/workbench/src/lib/operations-api.ts (new)
apps/workbench/src/types/operations.ts (new)
apps/workbench/src/App.tsx (add route + nav)
apps/workbench/src/types/auth.ts (add ops scopes)
apps/workbench/src/adapters/auth/mock-auth.adapter.ts (add ops scopes)
apps/workbench/src/adapters/auth/zitadel-auth.adapter.ts (map ops scopes)
apps/workbench/e2e/operations.spec.ts (new)

Docs:

docs/workdocs/last-mile-plan.md (mark P1.5 complete)
services/workbench-bff/README.md (document ops endpoints)

Open Questions (Resolve Before Implementation)

Confirm expected auth claim mapping for ops scopes in Zitadel tokens.