Skip to content

feat(lab): CL-04 CLI and management read surfaces #1378

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Wibias merged 2 commits into from
Aug 9, 2026
Merged

feat(lab): CL-04 CLI and management read surfaces #1378

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1907b90
feat(lab): CL-04 CLI and management read surfaces
Wibias Aug 9, 2026
1450238
fix(lab): address PR review findings
Wibias Aug 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 21 additions & 8 deletions devlog/_plan/260807_compatibility_lab/001_pr_stack_status.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@ independent review, blockers, and whether a later phase is authorized.
| CL-00 | `feat/cl-00-compatibility-contracts` | `3ad5bb6bd3f76f6879d84b78ea39edd3e01ec296` | `c014464237fd3c95bda08bc18bfab8ba8f532308` | [#1286](https://github.com/lidge-jun/opencodex/pull/1286) | ACCEPTED AFTER CODERABBIT REMEDIATION (merged to `dev` at `243c3f4905797aa11c62ba933bb03d6d721266fd`) |
| CL-01 | `feat/cl-01-conformance-harness` | `c2113ca47b8a05c5a5f90679e4eaa640ca2c6a66` | `22d608c82d82e2746c0cef9cd761db19a8e465ee` | [#1320](https://github.com/lidge-jun/opencodex/pull/1320) | MERGED TO `dev` at `4bb249b756abd468c675d2d92fffe4da95ad3e2a` |
| CL-02 | `feat/cl-02-evidence-ledger` | `4bb249b756abd468c675d2d92fffe4da95ad3e2a` | NOT RECORDED | [#1333](https://github.com/lidge-jun/opencodex/pull/1333) | MERGED TO `dev` at `025c37916225dd685d9217e5b40190600f06d278`; POST-MERGE HARDENING [#1343](https://github.com/lidge-jun/opencodex/pull/1343) MERGED at `eee2dab4d1bbacefce56057adad51d734f346702`; FINAL CLOSURE GATE [#1348](https://github.com/lidge-jun/opencodex/pull/1348) |
| CL-03 | `feat/cl-03-live-route-probes` | `4f746d13799888ea0a8c7a111aa2ad61c2126ea0` | `003f7402f49bfe8dd710a7beba52f717051bfadf` | [#1352](https://github.com/lidge-jun/opencodex/pull/1352) | DRAFT PR OPEN (implementation; not accepted) |
| CL-03 | `feat/cl-03-live-route-probes` | `4f746d13799888ea0a8c7a111aa2ad61c2126ea0` | `003f7402f49bfe8dd710a7beba52f717051bfadf` | [#1352](https://github.com/lidge-jun/opencodex/pull/1352) | MERGED TO `dev` at `68c71a4e9cdf882d812f09fd94783a28749db629`; ACCEPTED/CLOSED |
| CL-04 | `feat/cl-04-lab-read-surfaces` | `68c71a4e9cdf882d812f09fd94783a28749db629` | NOT RECORDED | DRAFT PENDING | IMPLEMENTATION IN PROGRESS (not accepted) |

The CL-01 starting SHA is the exact CL-00 tip recorded when CL-01 began. Its
moving base-ref name is not a substitute for that historical SHA.
Expand Down Expand Up @@ -156,10 +157,8 @@ Claims cannot produce `PROBED`/`VERIFIED`.
- CL-00: **ACCEPTED** (merged #1286).
- CL-01: **MERGED** via #1320 at `4bb249b756abd468c675d2d92fffe4da95ad3e2a`.
- CL-02: **MERGED** via #1333 at `025c37916225dd685d9217e5b40190600f06d278`; post-merge hardening #1343 is also **MERGED** at `eee2dab4d1bbacefce56057adad51d734f346702`; final closure is tracked in #1348.
- CL-03: **DRAFT PR OPEN** ([#1352](https://github.com/lidge-jun/opencodex/pull/1352)) on
`feat/cl-03-live-route-probes` from `4f746d13799888ea0a8c7a111aa2ad61c2126ea0`;
implementation head `003f7402f49bfe8dd710a7beba52f717051bfadf`. Not accepted.
- CL-04: **NOT STARTED** (blocked until CL-03 independent acceptance and review reconciliation).
- CL-03: **ACCEPTED/CLOSED** via [#1352](https://github.com/lidge-jun/opencodex/pull/1352), merged to `dev` at `68c71a4e9cdf882d812f09fd94783a28749db629`.
- CL-04: **IMPLEMENTATION IN PROGRESS**, authorized from accepted CL-03 merge `68c71a4e9cdf882d812f09fd94783a28749db629`.

## CL-03 implementation log (2026-08-09)

Expand Down Expand Up @@ -187,6 +186,20 @@ Claims cannot produce `PROBED`/`VERIFIED`.

### CL-03 blockers

- Independent acceptance review not performed
- Draft PR review findings not yet reconciled
- Full local ledger suite not green on Windows host (pre-existing SQLite EPERM)
- ~~Independent acceptance review not performed~~ — reconciled at merge #1352
- ~~Draft PR review findings not yet reconciled~~ — CodeRabbit/review findings addressed pre-merge
- Full local ledger suite may show pre-existing Windows SQLite `EPERM` flakes (`rebuild.ts` unchanged vs base)

## CL-03 merge log (2026-08-09)

- **Merged to `dev`:** `68c71a4e9cdf882d812f09fd94783a28749db629` via upstream [#1352](https://github.com/lidge-jun/opencodex/pull/1352)
- **Final required CI:** green at merge (cross-platform)
- **CodeRabbit/review:** findings reconciled pre-merge
- **CL-03 state:** accepted/closed; CL-04 authorized from current `dev`

## CL-04 start log (2026-08-09)

- **Starting `upstream/dev` SHA:** `68c71a4e9cdf882d812f09fd94783a28749db629`
- **Branch:** `feat/cl-04-lab-read-surfaces`
- **Scope:** read-only CLI (`ocx lab`), authenticated `GET /api/lab/*`, shared `src/lab/query/` layer
- **CL-05:** not started
Comment thread
coderabbitai[bot] marked this conversation as resolved.
56 changes: 56 additions & 0 deletions devlog/_plan/260807_compatibility_lab/004_cl04_read_surfaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# CL-04 implementation record — Lab CLI and management read surfaces

## Programme position

- **Phase:** CL-04 (read-surface only)
- **Starting `upstream/dev` SHA:** `68c71a4e9cdf882d812f09fd94783a28749db629` (merge #1352)
- **Branch:** `feat/cl-04-lab-read-surfaces`
- **PR:** [#1378](https://github.com/lidge-jun/opencodex/pull/1378) → `lidge-jun/opencodex:dev`
- **CL-05:** not started

## Scope delivered

### Shared query layer (`src/lab/query/`)

- Read-only SQLite open via `openLabReadConnection()`; never creates DB or rebuilds projection
- Schema/spec validation (`LAB_SQLITE_SCHEMA_VERSION`, `LAB_PROJECTION_SPEC_VERSION`)
- Explicit `lab_projection_unavailable` / `lab_projection_incompatible` errors
- Parameterized SQL, deterministic keyset cursors, bounded pagination (default 50, max 100)
- Privacy-safe DTO mapping (`dto-map.ts`) — no raw `payload_json` or artifact bytes
- Catalogue from packaged CL-01/CL-03 authorities (`catalog.ts`)

### Management API (`src/server/management/lab-routes.ts`)

- `GET /api/lab/status`
- `GET /api/lab/verdicts`
- `GET /api/lab/subjects`, `GET /api/lab/subjects/:subjectId`
- `GET /api/lab/observations`
- `GET /api/lab/events`, `GET /api/lab/events/:eventId`
- `GET /api/lab/artifacts`, `GET /api/lab/artifacts/:digest`
- `GET /api/lab/catalog`

### CLI (`src/cli/lab.ts`)

- `ocx lab status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog`
- `--json` machine output; skips Codex shim autorestore; no daemon/network

## Validation (local)

- `bun x tsc --noEmit` — passed
- `bun test tests/lab-read-surfaces.test.ts` — 17/17 passed
- `bun test tests/lab-conformance-harness.test.ts` — 17/17 passed
- `bun test tests/lab-evidence-ledger.test.ts` — 37/41 passed; 4 pre-existing Windows SQLite `EPERM`/file-lock flakes in `wipeSqlite` during repeated `rebuildLabProjection` (same failures on base `68c71a4` without CL-04)
- `bun test tests/lab-live-probe.test.ts` — 19/19 passed
- `bun test tests/lab-live-sandbox.test.ts` — 17/17 passed
- `bun run privacy:scan` — passed

## Acceptance blockers

- PR #1378 requires final CI after review remediation
- Independent acceptance review not performed
- Reviewer findings must be reconciled before CL-04 acceptance

## Out of scope (confirmed)

- CL-05 GUI, CL-06 routing profile fields, CL-07 fabric, CL-08 probes/public publish
- Automatic projection rebuilds, probe execution, raw artifact download APIs
2 changes: 2 additions & 0 deletions src/cli/codex-shim-autorestore.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ const DEFAULT_DEPS: CodexShimAutoRestoreCliDeps = {

export function skipsCodexShimAutoRestore(command: string | undefined, args: string[]): boolean {
if (command === "uninstall" || command === "remove") return true;
// `lab` is read-only inspection; it must not trigger shim side effects.
if (command === "lab") return true;
Comment thread
coderabbitai[bot] marked this conversation as resolved.
return command === "codex-shim" && ["install", "uninstall", "remove"].includes(args[1] ?? "");
}

Expand Down
15 changes: 15 additions & 0 deletions src/cli/help.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,20 @@ const helpEntries: Record<string, HelpEntry> = {
"Invalid or unknown arguments exit 64. Not-ready, pending, failed, timeout, and unreachable exit 1.",
],
},
lab: {
usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog> [options] [--json]",
summary: "Read-only Compatibility Lab projection inspection (local SQLite; no daemon).",
details: [
"status Projection availability, schema versions, and row counts.",
"verdicts Paginated derived compatibility verdicts with filters.",
"subjects List subjects; subject <id> returns one typed subject.",
"observations Paginated observation rows from the projection.",
"events Event history; event <id> returns one safe typed event.",
"artifacts Artifact metadata only (no content download).",
"catalog Packaged protocol/live scenario catalog metadata.",
"Reads never rebuild the projection, trigger probes, or require the proxy.",
],
},
Comment on lines +267 to +280

@coderabbitai coderabbitai Bot Aug 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use one spelling of "catalog" in the user-facing text.

Line 268 names the subcommand catalog. Line 277 describes it as "catalogue". src/cli/lab.ts line 119 also prints "No catalogue scenarios" as the empty-state message.

The subcommand name is catalog, so the prose should match it. Mixed spelling in help text makes the feature harder to search for in the help output and in documentation.

✏️ Proposed fix 
-      "catalog               Packaged protocol/live scenario catalogue metadata.",
+      "catalog               Packaged protocol/live scenario catalog metadata.",

Apply the same change in src/cli/lab.ts line 119:

-  return lines.length > 0 ? lines : ["No catalogue scenarios"];
+  return lines.length > 0 ? lines : ["No catalog scenarios"];
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli/help.ts` around lines 267 - 280, Use the “catalog” spelling
consistently in the lab help text and the empty-state message in the lab CLI
flow, including the visible `lab.details` catalog entry and the `src/cli/lab.ts`
message currently using “catalogue”.

};

function packageVersion(): string {
Expand Down Expand Up @@ -318,6 +332,7 @@ Usage:
ocx grok <sub> Grok Build model selection and apply
ocx system <sub> Runtime settings, startup, sync, and updates
ocx config <sub> Validated configuration show/get/set/import/export
ocx lab <sub> Read-only Compatibility Lab projection inspection
ocx claude [args...] Launch Claude Code wired to the proxy (model discovery on)
ocx claude desktop [sub] Manage and apply Claude Desktop's four-family profile
ocx opencode [args...] Launch opencode wired to the proxy (runtime provider config)
Expand Down
5 changes: 5 additions & 0 deletions src/cli/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1367,6 +1367,11 @@ switch (command) {
process.exitCode = await handleConfigCommand(args.slice(1));
break;
}
case "lab": {
const { handleLabCommand } = await import("./lab");
process.exitCode = await handleLabCommand(args.slice(1));
break;
}
case "claude": {
const { cmdClaude } = await import("./claude");
// "ocx claude desktop" → write Desktop 3P config
Expand Down
Loading
Loading