HWLAB Code Queue
170 lines
12 KiB
Markdown
170 lines
12 KiB
Markdown
# 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 `/`. |
|
|
| `/gate` | Internal static alias for the read-only gate diagnostics view. | No | Same as `/diagnostics/gate`; source/gate report and same-origin read-only diagnostics only. |
|
|
| `/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.
|
|
- `/gate` is a short internal alias for the same hidden gate view as
|
|
`/diagnostics/gate`; it must not become the default route.
|
|
- `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; its first screen does not show Gate, `BLOCKED`, `M0-M5`, or acceptance-review copy. |
|
|
| 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`, `/gate`, `/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.
|