docs(lanes): document proof gallery (C)
This commit is contained in:
+81
@@ -467,6 +467,87 @@ Response: `{ "lane": <same shape GET /api/lanes/:id returns>, "feature": <same s
|
||||
- **404** `{ "error": { "code": "ENOLANE", "message": "lane not found" } }`.
|
||||
|
||||
|
||||
#### Lane proof gallery
|
||||
|
||||
Proof gallery (QC screenshots) captured at `<lane.cwd>/.playwright-mcp/proof/<slug>/<phase-group>/` and grouped by feature slug (the same slug from per-feature state). Read-only access and deletion are path-contained: every proof file is resolved, realpath'd, and checked to be inside the lane's proof root before serving or deleting.
|
||||
|
||||
```http
|
||||
GET /api/lanes/:id/proof
|
||||
```
|
||||
|
||||
List every feature with proof (or an activated-but-not-yet-shot feature from `lane_features`), most recently touched first:
|
||||
|
||||
```json
|
||||
{
|
||||
"features": [
|
||||
{
|
||||
"slug": "auth-redesign",
|
||||
"groups": {
|
||||
"desktop": ["01-login.png", "02-signup.png"],
|
||||
"mobile": ["01-login.png"]
|
||||
},
|
||||
"ticket_report": "auth-redesign/ticket/REPORT.html",
|
||||
"mtime": 1722755400
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Each feature has:
|
||||
- **`slug`** (string) — canonicalized feature slug
|
||||
- **`groups`** (object) — `{ "phase": ["image1.png", "image2.png"] }` — phase-groups with their images
|
||||
- **`ticket_report`** (string) — relative path to ticket report HTML, or empty if none exists
|
||||
- **`mtime`** (number) — Unix seconds of the most recent file touched in this feature's proof tree (0 if the feature has no proof yet)
|
||||
|
||||
**Status codes:**
|
||||
- **200** — success
|
||||
- **404** `{ "error": { "code": "ENOLANE", "message": "lane not found" } }` — lane doesn't exist
|
||||
|
||||
```http
|
||||
GET /api/lanes/:id/proof/:slug/:group/:file
|
||||
```
|
||||
|
||||
Fetch a single proof file (PNG, JPG, or HTML). The file is resolved with path containment checks before serving:
|
||||
|
||||
**Status codes:**
|
||||
- **200** — file content, `Content-Type` set to `image/png`, `image/jpeg`, or `text/html`
|
||||
- **404** — lane, slug, group, or file not found, or path escapes containment
|
||||
|
||||
```http
|
||||
DELETE /api/lanes/:id/proof/:slug
|
||||
```
|
||||
|
||||
Delete proof at one of three granularities: request body `{ "group": "phase-name", "images": ["file1.png"] }` deletes specific images from a phase, `{ "group": "phase-name" }` deletes an entire phase, or empty `{}` deletes all phases **except** `ticket/`.
|
||||
|
||||
```json
|
||||
{ "deleted": 3 }
|
||||
```
|
||||
|
||||
**Status codes:**
|
||||
- **200** — success, returns count of deleted files
|
||||
- **400** `{ "error": { "code": "EBADPATH", "message": "…" } }` — invalid slug, group, or image name; or attempt to delete `ticket/`
|
||||
- **404** `{ "error": { "code": "ENOLANE", "message": "lane not found" } }` — lane doesn't exist
|
||||
- **404** `{ "error": { "code": "ENOFEATURE", "message": "…" } }` — slug doesn't exist
|
||||
|
||||
```http
|
||||
POST /api/lanes/:id/proof-link
|
||||
```
|
||||
|
||||
Converge the clone-root `proof/` directory (if it exists at `<lane.cwd>/proof`) onto the canonical `.playwright-mcp/proof`. This is an explicit operation, never automatic — exposed only as `ccam lanes proof-link`. Idempotent.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{ "linked": true }
|
||||
```
|
||||
|
||||
- **`linked`** (boolean) — `true` if the link was created or fixed, `false` if the symlink already pointed to the right place or a collision was avoided
|
||||
|
||||
**Status codes:**
|
||||
- **200** — success
|
||||
- **404** `{ "error": { "code": "ENOLANE", "message": "lane not found" } }` — lane doesn't exist
|
||||
|
||||
|
||||
### Locks
|
||||
|
||||
Cross-lane named locks (`server/lib/named-lock.js`) — the OTHER axis from a
|
||||
|
||||
@@ -244,6 +244,7 @@ A lane is a durable unit of parallel agent work — one working directory, many
|
||||
| `ccam lanes runtime [<id>]` | Slot, ports (flagging any that stepped aside from its base), the lane's database name and Redis index when its profile declares them (see [Data isolation](LANES.md#data-isolation-database-redis-and-env-a2)), per-service liveness, log paths, and the last boot error |
|
||||
| `ccam lanes logs [<id>] <service> [--tail N]` | Tail one service or hook log (`--tail` in bytes, default 64 KiB) |
|
||||
| `ccam lanes hook [<id>] <name> [args…]` | Run one of the profile's hooks: `bootstrap`, `boot`, `health`, `migrate`, `seed`, `ci-gate`, `e2e`, `regen`, `db-create`, `db-drop` |
|
||||
| `ccam lanes proof-link [<id>]` | Converge clone-root `proof/` onto `.playwright-mcp/proof` (idempotent, never run automatically) |
|
||||
| `ccam lock status [<name>]` | Show one lock's holder, or every currently-held lock |
|
||||
| `ccam lock acquire <name> [--holder X] [--timeout N]` | Acquire a cross-lane named lock, polling until free (or `--timeout` seconds elapse). Holder defaults to the calling lane (`lane<slot>`) |
|
||||
| `ccam lock release <name> [--holder X]` | Release a lock. Refused (409) when `--holder` doesn't match the current owner |
|
||||
|
||||
@@ -877,6 +877,53 @@ curl -X POST http://localhost:4820/api/lanes/5/remove \
|
||||
|
||||
**Actions gated behind confirmation:** `remove` requires the `confirm` flag to prevent accidental deletion.
|
||||
|
||||
## Proof gallery
|
||||
|
||||
A lane's proof gallery is a collection of QC screenshots captured during active work, grouped by feature (the same slug from **Per-feature state and archive** above) and phase (e.g. desktop, mobile, e2e, visual). A QC agent running an MCP server like `playwright-mcp` captures screenshots to disk at `<lane.cwd>/.playwright-mcp/proof/<slug>/<phase-group>/` and generates an optional ticket report at `<slug>/ticket/REPORT.html`. The Workspace gallery panel displays these files grouped by feature, using the same feature picker as the per-feature state section.
|
||||
|
||||
### Storage
|
||||
|
||||
Proof files live inside the lane's own `cwd`, not under `LANES_ROOT`:
|
||||
|
||||
```
|
||||
<lane.cwd>/.playwright-mcp/proof/
|
||||
├── auth-redesign/
|
||||
│ ├── desktop/
|
||||
│ │ ├── 01-login.png
|
||||
│ │ └── 02-signup.png
|
||||
│ ├── mobile/
|
||||
│ │ ├── 01-login.png
|
||||
│ │ └── 02-signup.png
|
||||
│ └── ticket/
|
||||
│ └── REPORT.html
|
||||
├── another-feature/
|
||||
│ ├── e2e/
|
||||
│ │ └── 01-user-flow.png
|
||||
│ └── ticket/
|
||||
│ └── REPORT.html
|
||||
└── …
|
||||
```
|
||||
|
||||
### Linking proof directories (the `ensure_proof_link` primitive)
|
||||
|
||||
An MCP server's `--output-dir` flag may point to different locations across runs. To converge all proof onto one canonical path regardless, CCAM provides the `ensure_proof_link` operation, exposed only as the explicit `ccam lanes proof-link` CLI command — it is **never automatic**. This matches the "CCAM does not orchestrate" rule: a session decides when to link, not the dashboard.
|
||||
|
||||
`ensure_proof_link` works as follows:
|
||||
|
||||
1. If a stray `proof/` directory exists at `<lane.cwd>/proof`, merge its contents into the canonical `.playwright-mcp/proof` (no-clobber — existing files are never overwritten) and replace it with a symlink.
|
||||
2. If a `proof/` symlink already points to `.playwright-mcp/proof`, the operation is a no-op.
|
||||
3. If a file named `proof` exists (neither directory nor symlink), it is left untouched to avoid clobbering a user's file.
|
||||
|
||||
The operation is idempotent and always safe — running it multiple times on the same lane has no side effects.
|
||||
|
||||
### Security
|
||||
|
||||
Every path the proof module touches — reading, serving, or deleting files — is resolved, realpath'd, and checked to be inside the lane's proof root before any filesystem operation. Symlink escapes, path traversal (`../`), and bad characters (`/`, `\`, `..` in segment names) are all rejected with `EBADPATH` errors. `deleteProof` never removes the `ticket/` directory, only the phase-group subdirectories and their images, so a lane's ticket report persists even when phase proofs are pruned.
|
||||
|
||||
### Gallery panel and feature selection
|
||||
|
||||
The Workspace page's gallery panel reuses the feature picker from **Per-feature state and archive** — there is only one selector, not a separate one for proofs. Selecting a feature displays that feature's saved pipeline (from per-feature state) and its proof gallery (if any proofs exist for that feature).
|
||||
|
||||
## Cross-lane named locks
|
||||
|
||||
Cross-lane named locks serialize work that thrashes a shared machine — builds, e2e runs, database migrations — across all lanes, not just within one lane. This is a separate axis from `withLaneLock`, the in-process per-lane lock in `server/lib/lane-lock.js`: `lane-lock` is about _when_ a lane runs internal operations; `named-lock` is about which _other lanes_ must wait.
|
||||
|
||||
@@ -24,7 +24,7 @@ stronger is a separate design (§ Future).
|
||||
| **A2** | Data isolation: `.env`, database, Redis index | A1 | ✅ **done** 2026-08-03 |
|
||||
| **A3** | Stack detection + profile scaffolding | A2 | ✅ **done** 2026-08-04 |
|
||||
| **B** | Per-feature state + archive | — | ✅ **done** 2026-08-04 |
|
||||
| **C** | Proof gallery | B | planned |
|
||||
| **C** | Proof gallery | B | ✅ **done** 2026-08-04 |
|
||||
| **D** | Cross-lane named locks | — | ✅ **done** 2026-08-04 |
|
||||
| **E** | `ship-feature` skill + QC agents | A2·B·C·D | planned |
|
||||
| **F** | Integrations (tracker / dev-QC / CI) | E | planned |
|
||||
|
||||
Reference in New Issue
Block a user