From 0d5af3404c847cc2fcb3961c4b851b6c1489be65 Mon Sep 17 00:00:00 2001 From: Lyon <88232613+pikasTech@users.noreply.github.com> Date: Fri, 22 May 2026 17:27:05 +0800 Subject: [PATCH] docs: define Cloud Workbench frontend design Refs #99 #78 --- docs/cloud-web-workbench.md | 166 ++++++++++++++++++++++++++++++++++ docs/dev-acceptance-matrix.md | 4 +- docs/operator-runbook.md | 32 +++++-- 3 files changed, 191 insertions(+), 11 deletions(-) create mode 100644 docs/cloud-web-workbench.md diff --git a/docs/cloud-web-workbench.md b/docs/cloud-web-workbench.md new file mode 100644 index 00000000..00307010 --- /dev/null +++ b/docs/cloud-web-workbench.md @@ -0,0 +1,166 @@ +# HWLAB Cloud Workbench Frontend Contract + +This document is the review contract for +`DC-DCSN-P0-2026-003`, `pikasTech/HWLAB#99`, and +`pikasTech/HWLAB#78`. It defines the Cloud Workbench frontend design and +acceptance surface for later implementation. It is documentation-only: it does +not authorize deployment, service restart, PROD access, heavyweight browser +automation, or hardware mutation. + +The default Cloud Web experience may be rebuilt from scratch to satisfy this +contract. Existing Gate or M3 diagnostics screens from `#59` are not the +default homepage contract. + +## Product Position + +Cloud Workbench is the default browser entry at +`http://74.48.78.17:16666`. It should feel like a VS Code-style operator +workbench for HWLAB DEV: resources on the left, agent conversation and trace in +the center, evidence and hardware context on the right, and commands at the +bottom. + +The workbench is a read-only or dry-run coordination surface until a later +contract explicitly enables a narrow write path. It must not become a generic +hardware control panel. + +## Route Structure + +The frontend route model must keep the workbench as the default route and move +diagnostics under secondary routes: + +| Route | Purpose | Default | Source boundary | +| --- | --- | --- | --- | +| `/` | Cloud Workbench default. Shows agent conversation, trace, selected resource context, hardware/evidence side panel, and command input. | Yes | Same-origin `/v1`, read-only `/json-rpc`, source/gate report, blocked report. | +| `/workbench` | Explicit alias for the default workbench. | Yes, alias | Same as `/`. | +| `/diagnostics` | Secondary diagnostics hub that links to status and gate views. | No | Same-origin `/v1` and report fixtures only. | +| `/diagnostics/status` | Read-only DEV status: edge, router, API, web, DB readiness, agent service health, and artifact identity. | No | Same-origin `/v1/status` or equivalent read-only status endpoint. | +| `/diagnostics/gate` | Read-only gate and M3 diagnostics inherited from `#59`: topology, route, health, blockers, and evidence summary. | No | Gate report and blocked report; read-only `/json-rpc` only when already defined. | +| `/agents` | Agent sessions, workers, skills, trace timeline, and cleanup status. Can be a focused view or a left-rail activity inside `/`. | No | Same-origin `/v1` agent summaries and source report. | +| `/hardware` | Hardware resources, gateway sessions, patch-panel topology, box simulators, capabilities, and blockers. | No | Read-only `/json-rpc` status/list methods and same-origin `/v1` summaries. | +| `/records` | Trusted records: evidence, audit, trace, operation IDs, artifact tag/commit/digest, and report links. | No | Gate report, source report, blocked report, and same-origin `/v1` summaries. | + +The route relationship is: + +- `/` and `/workbench` are the primary product surface. +- `diagnostics/status` and `diagnostics/gate` are auxiliary views for + troubleshooting and acceptance review. +- Agent, hardware resources, and trusted records are first-class workbench + domains. They may be implemented as routes, tabs, or focused activity-rail + modes, but the default route must show how they relate to each other. +- `#59` diagnostics remain available under `/diagnostics/gate`; they must not + define the default homepage. + +## Layout Structure + +The default workbench layout must use four stable regions: + +| Region | Required content | Required behavior | `sourceKind` labels | +| --- | --- | --- | --- | +| Left activity rail and resource tree | Activity icons for Workbench, Agent, Hardware, Records, Diagnostics; resource tree for project, gateway sessions, patch-panel, box resources, capabilities, agent sessions, workers, and reports. | Selecting an item changes the center and right-panel context without implying mutation. Unknown or blocked items remain visible with disabled actions. | `SOURCE`, `DRY-RUN`, `DEV-LIVE`, `BLOCKED`. | +| Center agent conversation and trace | Agent conversation stream, plan/trace events, selected operation timeline, agent/worker/session IDs, and blocker messages. | Conversation input defaults to no-mutation guidance. Any future action that could mutate hardware is disabled unless a later contract explicitly enables it. Trace rows are clickable and open evidence context. | `SOURCE`, `LOCAL`, `DRY-RUN`, `DEV-LIVE`, `BLOCKED`. | +| Right hardware/evidence side panel | Selected hardware resource, patch-panel wiring, gateway/box status, evidence record, audit record, operation ID, artifact commit/tag/digest, and report provenance. | Panel is read-only. It explains why an item is blocked, dry-run, source-only, or live. It must not expose generic hardware write controls. | `SOURCE`, `DRY-RUN`, `DEV-LIVE`, `BLOCKED`. | +| Bottom command/input area | Command composer, dry-run preview, selected scope, source boundary, and disabled live controls. | Default mode is read-only or dry-run. Live hardware execution controls are disabled with an explicit blocker reason until a separate acceptance contract permits them. | `DRY-RUN`, `BLOCKED`, optionally `DEV-LIVE` for read-only observations only. | + +The UI may use a full rewrite of `web/hwlab-cloud-web`. It should preserve +the public `:16666` entrypoint and same-origin API assumptions rather than the +old diagnostics-first component structure. + +## Data Sources + +Every visible panel must display or carry a `sourceKind` value. The frontend +must keep these data sources separate: + +| Source | Use | Allowed calls | `sourceKind` | +| --- | --- | --- | --- | +| Same-origin `/v1` | Cloud API summaries for status, agents, records, health, artifact identity, and read-only workbench aggregation. | `GET` or documented read-only RPC wrappers through the same origin as the web bundle. | `DEV-LIVE` only when observed from the real DEV route; otherwise `BLOCKED` or `SOURCE`. | +| Read-only `/json-rpc` | Hardware/gateway/patch-panel status, capabilities, topology, and evidence lookups already defined as safe reads. | Only list/status/get/describe methods. No generic write, no direct box mutation, no bypass of patch-panel ownership. | `DEV-LIVE` for read-only real DEV observations; `DRY-RUN` for fixture-backed previews. | +| Source report | Checked-in contracts, manifests, schemas, service IDs, and documentation. | Static fetch or bundled build asset only. | `SOURCE`. | +| Gate report | `reports/dev-gate` gate summaries, DEV layer status, artifact identity, and M3/M4/M5 readiness. | Read-only local report content or same-origin report endpoint. | `SOURCE`, `DRY-RUN`, `DEV-LIVE`, or `BLOCKED` exactly as reported. | +| Blocked report | Open blockers for DB, M3, M4, edge/route, artifacts, registry, and evidence gaps. | Read-only report content or same-origin summary endpoint. | `BLOCKED`. | + +The frontend must not infer `DEV-LIVE` from successful page load on `:16666`. +`DEV-LIVE` requires an observation from the real DEV route for the specific +thing being displayed. + +## Status Labels + +Use these labels consistently: + +| Label | Meaning | UI rule | +| --- | --- | --- | +| `SOURCE` | Repository documentation, schemas, source fixtures, manifests, or checked-in reports. | May be shown as design/contract readiness only. Never claim live state. | +| `LOCAL` | Localhost or in-process smoke result. | May appear in trace or acceptance summaries, but not as live DEV evidence. | +| `DRY-RUN` | Fixture-backed or no-mutation preview. | Command previews and agent plans default here. Must state that no DEV/PROD state changed. | +| `DEV-LIVE` | Read-only observation from the real DEV route for the exact component, record, or route shown. | May mark edge, API, DB, artifact, agent, or hardware status only when supported by specific evidence. | +| `BLOCKED` | Missing, stale, unsafe, or not-yet-authorized evidence or action. | Must show blocker reason and keep unsafe or unproven controls disabled. | + +The UI must never upgrade `SOURCE`, `LOCAL`, `DRY-RUN`, edge-only, or +front-end-only observations into M3 or M4 `DEV-LIVE`. + +## Interaction Boundaries + +Allowed interactions for this contract: + +- Navigate routes and activity rail modes. +- Select project, gateway, box, patch-panel, capability, agent, worker, + evidence, audit, trace, operation, and report records. +- Refresh read-only `/v1` status, read-only `/json-rpc` status/list/get + methods, source reports, gate reports, and blocked reports. +- Compose a command and view a dry-run preview with selected scope, expected + evidence, and blocker reasons. +- Copy IDs, links, commands, and report references. + +Disabled in the first workbench implementation: + +- Run live agent hardware operations. +- Change patch-panel wiring. +- Write box, gateway, simulator, or hardware state. +- Start or stop gateway, worker, tunnel, edge, router, API, web, DB, or PROD + services. +- Deploy images, apply manifests, restart services, read secrets, or run + heavyweight e2e/Playwright flows. +- Mark M3, M4, or M5 accepted from the browser. + +Future buttons may be visible only if they are disabled and explain the +required contract, for example `BLOCKED: live command requires M0-M5 gate, +DEV-only authorization, and patch-panel-owned operation evidence`. + +Do not add a generic hardware command form. Any future write path must be +narrow, named, patch-panel owned, audited, evidenced, DEV-only, and covered by +a new acceptance contract. + +## Relationship To `#59` + +`#59` defined a read-only diagnostics console for M3 topology, route, health, +blockers, and evidence summary. For `#99`, that surface is retained as +`/diagnostics/gate` and may also appear as a Diagnostics activity in the left +rail. + +`#59` must not define `/`, `/workbench`, product navigation, or the default +homepage. The default homepage is the Cloud Workbench described here. + +The `npm run web:m3-readonly` guard remains useful as a safety check for the +diagnostics route and same-origin read-only boundary. A later implementation +may update the script to reflect the new workbench route model, but it must +continue to fail on hardware write APIs, public endpoint drift, and evidence +misclassification. + +## DEV Acceptance Contract + +Acceptance for the frontend design and later implementation is: + +| Area | Acceptance | +| --- | --- | +| Default page | `http://74.48.78.17:16666/` opens the Cloud Workbench, not the Gate/M3 Diagnostics dashboard. | +| API status | `http://74.48.78.17:16667` remains the DEV API/edge/status boundary; browser code uses same-origin `/v1` for workbench data and only read-only `/json-rpc` methods for diagnostics/hardware status. | +| Routes | `/`, `/workbench`, `/diagnostics`, `/diagnostics/status`, `/diagnostics/gate`, Agent, hardware resources, and trusted records are represented in navigation or route aliases. | +| Layout | Left activity rail/resource tree, center agent conversation/trace, right hardware/evidence side panel, and bottom command/input area are present on the default workbench. | +| Labels | `SOURCE`, `LOCAL`, `DRY-RUN`, `DEV-LIVE`, and `BLOCKED` labels are visible where evidence state is shown and follow the rules above. | +| Read-only boundary | Hardware resources and diagnostics are read-only. Live controls are disabled with blocker reasons. | +| Browser smoke | A lightweight screenshot/manual browser smoke may verify that the default page loads, the workbench regions are visible, diagnostics is secondary, and no text or controls imply generic hardware writes. | +| Artifact identity | Acceptance notes must include web image tag, commit, digest or `not_applicable` reason, build source, deploy environment, and health timestamp when runtime evidence is claimed. | +| Blocker display | DB, M3, and M4 blockers must be displayed separately when present. DB readiness cannot green M3/M4; edge route live cannot green DB, M3, or M4. | + +This document does not require a heavy check or browser e2e run. For the +documentation PR, the minimum validation is `git diff --check` and an `rg` +scan for the task terms and frozen labels. diff --git a/docs/dev-acceptance-matrix.md b/docs/dev-acceptance-matrix.md index 50447628..c816cc3c 100644 --- a/docs/dev-acceptance-matrix.md +++ b/docs/dev-acceptance-matrix.md @@ -74,7 +74,7 @@ provide a current health timestamp. Existing skeleton services may expose | frp tunnel | `hwlab-tunnel-client` | Tunnel session/status observation | Tunnel for DEV route is established to D601 router and identifies commit/image | Tunnel down, wrong target, ambiguous service identity | | D601 router | `hwlab-router` | `hwlab-dev/hwlab-router` health/status | Router is live, environment is `dev`, route target is cloud API/web or runtime service | Namespace mismatch, route missing, stale health timestamp | | Cloud API | `hwlab-cloud-api` | `GET /health`, `GET /live`, optional JSON-RPC `/rpc` probe | Returns service ID, `dev`, healthy/live status, redacted DB env readiness, and accepts a harmless protocol probe | HTTP error, unknown service ID, wrong environment, invalid JSON-RPC envelope, missing DB env readiness | -| Cloud Web | `hwlab-cloud-web` | `GET http://74.48.78.17:16666/` plus `npm run web:m3-readonly` / static asset check | Public browser entry serves the web bundle on `:16666`; API/edge diagnostics use `http://74.48.78.17:16667` or same-origin/internal k3s API service; the visible surface is M3 diagnostics for topology, route, health, blockers, and evidence summary only | Endpoint drift, public web served from `:6667`, direct write/control endpoint text or calls, edge-only evidence presented as M3 `DEV-LIVE`, missing asset | +| Cloud Web | `hwlab-cloud-web` | `GET http://74.48.78.17:16666/`, static asset check, and the workbench contract in `docs/cloud-web-workbench.md` | Public browser entry serves the Cloud Workbench on `:16666`; default page is a VS Code-style workbench with left activity rail/resource tree, center Agent conversation/trace, right hardware/evidence side panel, and bottom command/input area; API/edge status remains on `http://74.48.78.17:16667`; browser data uses same-origin `/v1`, read-only `/json-rpc`, source/gate report, and blocked report with explicit `sourceKind` labels | Endpoint drift, public web served from `:6667`, Gate/M3 Diagnostics used as default homepage, direct write/control endpoint text or calls, missing `SOURCE`/`DRY-RUN`/`DEV-LIVE`/`BLOCKED` labeling, edge-only evidence presented as M3 `DEV-LIVE`, missing asset | | Agent manager | `hwlab-agent-mgr` | Agent scheduling health/status | Reports live manager, commit/image, and DEV environment; no worker leak after smoke | Scheduler unavailable, wrong environment, unbounded worker session | | Agent worker | `hwlab-agent-worker` | Worker health/status during dry-run or scoped smoke | Worker session is scoped to DEV project and emits trace/audit identifiers | Missing session identity, unsafe mutation, cleanup failure | | Agent skills | `hwlab-agent-skills` | Skill bundle version/status | Skill artifact is traceable to commit/build source and compatible with worker | Unversioned skill bundle, missing build source | @@ -99,7 +99,7 @@ listed above. | 4 | Observe master edge proxy route. | Edge route maps DEV endpoint to `frp` and records artifact identity. | Missing route, stale route, missing artifact identity. | `network_blocker` | | 5 | Observe `frp` tunnel. | Tunnel links master edge to D601 router for DEV. | Tunnel down or target mismatch. | `network_blocker` | | 6 | Observe D601 `hwlab-dev/hwlab-router`. | Router is live and forwards only to HWLAB DEV services. | Namespace mismatch or route bypass. | `runtime_blocker` | -| 7 | Check cloud API/web surface. | Cloud API health is valid on public `:16667`; web assets are served on public `:16666`; Cloud Web exposes only M3 diagnostics for route, health, topology, blockers, and evidence summary; `npm run web:m3-readonly` passes. | Bad health, endpoint drift, direct hardware write/control surface from web, or edge-only evidence promoted to M3 `DEV-LIVE`. | `runtime_blocker` | +| 7 | Check cloud API/web surface. | Cloud API health is valid on public `:16667`; web assets are served on public `:16666`; Cloud Web default route is the Cloud Workbench defined in `docs/cloud-web-workbench.md`; diagnostics/status/gate are secondary; data sources are same-origin `/v1`, read-only `/json-rpc`, source/gate report, and blocked report; `npm run web:m3-readonly` or its workbench-aware successor passes. | Bad health, endpoint drift, Gate/M3 Diagnostics used as default homepage, direct hardware write/control surface from web, missing source labels, or edge-only evidence promoted to M3 `DEV-LIVE`. | `runtime_blocker` | | 8 | Check gateway, simulator, box simulator, and patch-panel contracts. | Health/status JSON is parseable and topology keeps routing under patch-panel ownership; for M3 live, a traced `DO1 -> patch-panel -> DI1` operation exists. | Missing health, invalid topology, bypass path, or any attempt to promote support/fixture evidence to M3 live. | `runtime_blocker` | | 9 | Check agent manager, worker, and skills contracts. | Agent artifacts are traceable; dry-run/scoped smoke emits session, trace, audit, and cleanup evidence. | Missing traceability, unsafe mutation, cleanup leak. | `agent_blocker` | | 10 | Verify evidence and artifact observability. | Every accepted artifact has service ID, commit, image/tag/digest or reason, build source, env, and health timestamp. | Missing required observability field. | `observability_blocker` | diff --git a/docs/operator-runbook.md b/docs/operator-runbook.md index 6b3dcbe0..75794ab5 100644 --- a/docs/operator-runbook.md +++ b/docs/operator-runbook.md @@ -35,9 +35,10 @@ trusted loop. It requires: - no box loopback substitution, no front-end direct state edit, and no UniDesk runtime or proxy substitution. -Cloud Web, generic console work, artifact report generation, and desired-state -planning are support surfaces only. They may help operators, but they do not -count as M3 PASS on their own and cannot replace the loop evidence above. +Cloud Workbench, generic console work, artifact report generation, and +desired-state planning are support surfaces only. They may help operators, but +they do not count as M3 PASS on their own and cannot replace the loop evidence +above. The detailed step order and misclassification bans live in `docs/reference/m3-loop-rollout-runbook.md`; this runbook and the acceptance @@ -67,8 +68,8 @@ operator, script, or agent attempts one of these actions: runtime instead of `hwlab-cloud-api`, `hwlab-router`, `hwlab-gateway`, `hwlab-patch-panel`, agent services, and the other frozen HWLAB services. - Promote SOURCE, LOCAL, DRY-RUN, or edge-only result as real DEV evidence. -- Treat Cloud Web polish, generic console work, artifact reports, or desired - state plans as M3 PASS evidence. +- Treat Cloud Workbench polish, generic console work, artifact reports, or + desired state plans as M3 PASS evidence. ## Evidence Log @@ -159,10 +160,23 @@ npm run cli:dry-run node tools/hwlab-cli/bin/hwlab-cli.mjs test e2e --env dev --mvp ``` -For Cloud Web #59, `npm run web:m3-readonly` is the review contract. It keeps -the browser endpoint at public `:16666`, API/edge diagnostics at public -`:16667`, allows only read-only topology/route/health/evidence diagnostics, -and fails if edge-only observations are presented as M3 `DEV-LIVE`. +For Cloud Web #99, `docs/cloud-web-workbench.md` is the frontend design and +acceptance contract. The browser endpoint remains public `:16666`, while +API/edge status remains public `:16667`. The default page must be the Cloud +Workbench: left activity rail/resource tree, center Agent conversation/trace, +right hardware/evidence side panel, and bottom command/input area. + +Cloud Web #59 diagnostics move under the secondary diagnostics route. Keep +`diagnostics/status` and `diagnostics/gate` available for read-only +topology/route/health/evidence review, but do not use Gate or M3 Diagnostics +as the default homepage. + +`npm run web:m3-readonly` remains the current safety guard until replaced by a +workbench-aware equivalent. It must keep same-origin `/v1`, read-only +`/json-rpc`, source/gate report, and blocked report boundaries; it must fail +on hardware write APIs, endpoint drift, missing `SOURCE`/`DRY-RUN`/`DEV-LIVE` +or `BLOCKED` source labels, and edge-only observations presented as M3 +`DEV-LIVE`. The default CLI MVP command is a JSON dry-run plan even when `--dry-run` is not provided. It must include the DEV endpoint, artifact/health counts, two