128 lines
4.5 KiB
Markdown
128 lines
4.5 KiB
Markdown
# 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):
|
|
|
|
```bash
|
|
./scripts/run-webui
|
|
```
|
|
|
|
Or directly:
|
|
|
|
```bash
|
|
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 |
|
|
|
|
## 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` | Stub — report audit paste (#431) |
|
|
| `/worktrees` | Stub — hygiene dashboard (#432) |
|
|
| `/leases` | Lease and collision visibility (#433) |
|
|
| `/api/leases` | JSON lease/collision export |
|
|
|
|
All routes are GET-only. POST/PUT/PATCH/DELETE return `405` with
|
|
`read-only-mvp`.
|
|
|
|
## 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).
|
|
|
|
## 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):
|
|
|
|
```bash
|
|
./scripts/ci-webui-check
|
|
WEBUI_CI_FORCE=1 ./scripts/ci-webui-check # always run
|
|
```
|
|
|
|
Or invoke unittest directly:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
``` |