9.1 KiB
Internal web UI — local development (#426)
Read-only MVP skeleton for the MCP Control Plane operator console. Gitea,
MCP capability gates, and skills/llm-project-workflow/ remain the source of
truth; this UI only provides route stubs and layout.
Prerequisites
- Python 3.11+ with project dependencies installed (
pip install -r requirements.txt) - No secrets in repo, config, or client bundle
Start the server
From the repository root (or an issue worktree):
./scripts/run-webui
Or directly:
python3 -m webui
Optional environment variables:
| Variable | Default | Purpose |
|---|---|---|
WEBUI_HOST |
127.0.0.1 |
Bind address (keep local for MVP) |
WEBUI_PORT |
8765 |
Listen port |
WEBUI_REPO_ROOT |
repository root | Prompt library workflow hash root |
WEBUI_PROJECT_REGISTRY |
packaged JSON | Project registry path |
GITEA_MCP_CONFIG |
unset | Server-side MCP profile config (never sent to browser) |
GITEA_MCP_PROFILE |
unset | Active MCP profile name (server-side only) |
See webui-deployment.md for internal-only serving, Cloudflare Access/WARP/VPN guidance, and unsafe bind overrides (#435).
Routes (MVP)
| Path | Description |
|---|---|
/ |
Home / operator overview |
/health |
JSON liveness (status, service, mode, timestamp) |
/queue |
Live PR and issue queue dashboard (#429) |
/api/queue |
JSON queue export with pagination metadata |
/projects |
Project registry list (#427) |
/projects/{id} |
Project detail + onboarding checklist |
/api/projects |
JSON registry export |
/prompts |
Prompt library with per-prompt copy buttons (#428) |
/api/prompts |
JSON prompt export with workflow hashes |
/runtime |
MCP runtime health and stale detection (#430) |
/api/runtime |
JSON runtime health export |
/audit |
Report audit paste + validator preview (#431) |
/api/audit |
JSON validator preview (POST report_text, optional task_kind) |
/worktrees |
Worktree hygiene dashboard (#432) |
/api/worktrees |
JSON worktree scan with classifications and anomalies |
/actions |
Gated write-action registry — all disabled in MVP (#434) |
/api/actions |
JSON action registry with capability metadata |
/api/actions/{id}/preview |
Mutation ledger preview (GET, read-only) |
/leases |
Lease and collision visibility (#433) |
/api/leases |
JSON lease/collision export |
Most routes are GET-only. POST/PUT/PATCH/DELETE return 405 with
read-only-mvp, except /audit and /api/audit which accept POST for
local validator preview only (no Gitea mutations, no server-side storage).
Report audit (#431)
Paste an LLM final report at /audit or POST JSON to /api/audit. The UI
reuses final_report_validator and review schema checks to surface missing
proof fields, wrong validation vocabulary, mutation contradictions, and a
suggested next prompt or issue-comment draft. Task kind can be auto-detected
or selected explicitly.
Project registry (#427)
Versioned registry file: webui/data/projects.registry.json (schema version 1).
Override path with WEBUI_PROJECT_REGISTRY when operators keep a machine-local
copy outside git. The registry stores repo identity, remotes, profile names,
workflow/schema path references, and onboarding checklist steps — never tokens
or credentials.
Seed entry: Gitea-Tools on https://gitea.prgs.cc with prgs-author,
prgs-reviewer, and prgs-reconciler profiles.
Prompt library (#428)
Prompts are generated at load time from canonical workflow files under
skills/llm-project-workflow/workflows/. SHA-256 hashes are computed from
WEBUI_REPO_ROOT (defaults to the repository root). Prompt bodies are short
copy/paste starters; canonical workflow files remain the only full policy
source.
Live queue dashboard (#429)
/queue loads open PRs and issues for the default registry project (seed:
Gitea-Tools on https://gitea.prgs.cc) using existing gitea_auth read
credentials. The UI surfaces pagination proof (returned count, pages fetched,
has_more, inventory_complete) and classification badges (claimed,
blocked, in-review, duplicate) when evidence exists.
If credentials are missing or the fetch fails, the page shows an explicit error instead of an empty queue (fail closed).
Gated actions (#434)
/actions registers future write actions (claim, comment, review, merge,
delete branch, create PR/issue). Each entry declares the MCP tool, required
permission, and profile role from task_capability_map.py — aligned with
gitea_resolve_task_capability. Buttons are disabled; previews always render
a mutation ledger. Direct attempt_action calls fail closed without invoking
MCP tools.
Worktree hygiene (#432)
/worktrees scans local branches/ directories and registered git worktrees.
Each entry is classified (active-pr, active-issue, dirty, stale-clean,
detached-review, unsafe-unknown, orphan). Missing preserved worktrees
referenced by the issue lock file are flagged as anomalies (#404). The page
includes a copy/paste canonical cleanup prompt only — no deletion actions.
Override scan root with WEBUI_REPO_ROOT (defaults to repository root).
Lease visibility (#433)
/leases surfaces read-only lease and collision state: local issue lock file,
in-progress claim inventory (#268), reviewer PR lease comments when present
(<!-- mcp-review-lease:v1 -->, #407), duplicate open PRs per issue (#400),
and duplicate local branches per issue. Links to collision-history backend
issues (#267, #268, #400, #407) are included. No lease acquire/release from UI.
Runtime health (#430)
/runtime surfaces read-only MCP/runtime diagnostics for the default registry
project: active profile and role kind, authenticated identity (when credentials
are available), config model/mode, local vs remote master SHA sync, shell
health, workflow/schema SHA-256 hashes, and stale-runtime warnings when the
checkout is behind merged safety-gate changes. Restart guidance links to #420;
no tokens or MCP restart actions are exposed.
Deployment boundary (#435)
MVP serves on loopback by default. Binding 0.0.0.0 or :: is refused
unless WEBUI_ALLOW_PUBLIC_BIND=1. Non-loopback hosts log a warning unless
WEBUI_ALLOW_REMOTE_BIND=1. GET /health exposes deployment metadata.
Tests
pytest tests/test_webui_skeleton.py tests/test_webui_project_registry.py tests/test_webui_prompt_library.py tests/test_webui_queue_dashboard.py tests/test_webui_gated_actions.py -q
pytest tests/test_webui_skeleton.py tests/test_webui_project_registry.py tests/test_webui_prompt_library.py tests/test_webui_queue_dashboard.py tests/test_webui_audit.py tests/test_webui_worktree_hygiene.py -q
pytest tests/test_webui_skeleton.py tests/test_webui_project_registry.py tests/test_webui_prompt_library.py tests/test_webui_queue_dashboard.py tests/test_webui_lease_visibility.py tests/test_webui_runtime_health.py -q
pytest tests/test_webui_skeleton.py tests/test_webui_project_registry.py tests/test_webui_prompt_library.py tests/test_webui_queue_dashboard.py tests/test_webui_deployment_boundary.py -q
## Tests (#436)
Run the full hermetic web UI suite (all `test_webui_*.py` modules):
```bash
./scripts/test-webui
CI / Jenkins multibranch can call the path-filtered gate (runs only when the
diff touches webui/, tests/test_webui_*, or web UI docs/scripts):
./scripts/ci-webui-check
WEBUI_CI_FORCE=1 ./scripts/ci-webui-check # always run
scripts/test-webui sets WEBUI_TEST_OFFLINE=1 by default. In that mode the
queue, lease, and runtime routes use empty offline snapshots instead of Gitea
credentials, so CI can run without MCP daemon credential access. Set
WEBUI_TEST_OFFLINE=0 only when deliberately validating live fetch behavior.
Or invoke unittest directly:
python3 -m unittest discover -s tests -p 'test_webui_*.py' -q
Lease visibility (#433)
/leases surfaces read-only lease and collision state: local issue lock file,
in-progress claim inventory (#268), reviewer PR lease comments when present
(<!-- mcp-review-lease:v1 -->, #407), duplicate open PRs per issue (#400),
and duplicate local branches per issue. Links to collision-history backend
issues (#267, #268, #400, #407) are included. No lease acquire/release from UI.
Runtime health (#430)
/runtime surfaces read-only MCP/runtime diagnostics for the default registry
project: active profile and role kind, authenticated identity (when credentials
are available), config model/mode, local vs remote master SHA sync, shell
health, workflow/schema SHA-256 hashes, and stale-runtime warnings when the
checkout is behind merged safety-gate changes. Restart guidance links to #420;
no tokens or MCP restart actions are exposed.
Tests
pytest tests/test_webui_skeleton.py tests/test_webui_project_registry.py tests/test_webui_prompt_library.py tests/test_webui_queue_dashboard.py tests/test_webui_audit.py tests/test_webui_worktree_hygiene.py -q
pytest tests/test_webui_skeleton.py tests/test_webui_project_registry.py tests/test_webui_prompt_library.py tests/test_webui_queue_dashboard.py tests/test_webui_lease_visibility.py tests/test_webui_runtime_health.py -q