io.github.kvdm-co-pilot/cmp-inspector

The human-approval half of the console (VERIFICATION-LAYER-DESIGN.md §4): every governed artifact's live status (design system, architecture+structure, exemplar feature, exemplar spec, per-feature specs — the same §1 ordered walk the Approvals tab shows), via the PROJECT'S OWN qa/lib/approvals.mjs (never forked here). Structure only — no HTML; the tab is for the human, this tool is for you. Without waitForDecision: the current snapshot {available, statuses:[{id,label,status,hash,storedHash,approvedAt,fileCount,missing,resolvable}]}. With waitForDecision:true: BLOCKS — same shape as preview_status's waitForRender — until ANY governed artifact's status changes (a console Approve click, or `node qa/approve.mjs <artifact>` run in a terminal), then returns {timedOut, available, changed:[artifactIds], statuses}. {available:false} in a project with no approvals library (an older, pre-approvals-wave scaffold) — resolves immediately, there is nothing to wait for. Typical use: propose a change, tell the human to review it in the console, then approval_status{waitForDecision:true} instead of polling. Requires a running preview service (call preview{projectDir} first) — that's where the project root comes from.

Tier 1 handshake, SELF-HEALING: ensures a device/emulator is attached, ensures the `adb forward tcp:<port> tcp:<port>` exists (creating it — the debug-only inspector server binds loopback on the device), then GETs /inspect/health. If health is dead it LAUNCHES the debug app (applicationId parsed from the project — composeApp/build.gradle.kts / create-cmp.json — never hardcoded; pass `projectDir` when the server's cwd is not the app repo, or `appId` to skip resolution) and re-polls with bounded backoff. On a `device offline`-class adb error (a stale adb server transport — the client says offline while `adb devices` says device) it resets the adb server (kill-server / start-server / wait-for-device) once and retries the whole sequence once. {relaunch:true} forces a VERIFIED restart from a known state (adb force-stop → optional `pm clear` via clearState → launch → health's processStartedAtMs proven to move forward). Every failure names the stage that failed and the one command to run next — never a bare timeout. On success, sets the session default source to {kind:'live', port} so subsequent tool calls can omit `source`; the result's `healed` lists what it had to fix (app-launched, adb-transport-reset, relaunched). Requires a create-cmp DEBUG build installed on the device (the inspector is structurally absent from release builds). This tool never starts emulators.

GET /inspect/db?table=<name>&limit=<n> on the running app — assert PERSISTED state in the live tier. `table` must be a real table name (the app's Room schema JSONs and @Entity classes are in-repo) — the device validates it strictly against `sqlite_master` before ever touching a query, so an unknown name 404s rather than running arbitrary SQL. Rows are capped by `limit` (device-side default/max apply regardless of what's requested). Returns { table, columns, rows, rowCount }. Requires connect_live.

Load the enriched Compose semantics tree (hierarchy + geometry + resolved design tokens) as JSON, plus a compact summary { nodeCount, taggedCount, tokenizedCount }. With source {kind:'live'} this reads the RUNNING app's current screen (real data + nav state) on every call. Options: `testTag` returns only that node's subtree; format:'wireframe' returns the (sub)tree as a deterministic SVG wireframe instead of raw JSON (footprint nodes as rects, tokenized nodes highlighted with a resolved-values chip, clickable nodes with a distinct outline, testTags as mono labels — SVG is structured text, safe for model context; a11yOverlay:true marks accessibility violations, `out` also writes the file); includeLayoutGaps:true adds `layoutGaps` — the spacing between each pair of consecutive TAGGED siblings ({parentPath, a, b, gaps:{gapX,gapY,dxLeft,dyTop}}).

Drive the LIVE app one tap at a time, no pixels needed: resolves the tap point from the live tree (center of `testTag`'s bounds — or pass explicit root-relative `x`/`y` read from bounds), delivers it via the inspector's POST /inspect/tap (HTTP, not adb), waits `settleMs` for the UI to settle, then re-fetches the tree. Returns { tapped:{x,y,testTag?}, before:{tags,textSample,nodeCount}, after:{tags,textSample,nodeCount}, changed, route? } — assert the navigation structurally (old screen's tags gone, new content present). `route:{before,after}` (each a currentRoute string) is included ONLY when the running app exposes GET /inspect/nav — omitted entirely for older apps that predate it, never reported as null/failed. Requires connect_live (or a reachable forward).

AI-native previews of a create-cmp app's REAL screens with NO device, emulator, or manual Gradle: starts (or reuses) a resident service that renders every screen in inspector/PreviewRegistry.kt headlessly, serves a LIVE gallery for the human at a local URL (pixels + wireframe + a11y per screen; the page reloads itself via SSE after every re-render), and watches composeApp/src so every save re-renders automatically. Returns { url, screens:[{id, nodes, tokenized, tagged, a11yPass, tree, png}], version, changedLastRender } — give the human the url (open it for them if you can); assert on the returned structure or the per-screen tree paths yourself. After edits use preview_status { waitForRender: true } (blocks until the render/compile outcome) and preview_diff { screen } (one-call verified change). The console runs as a detached RESIDENT process (it survives this session; reconnecting the MCP adopts it), and is auto-ensured at session start inside a create-cmp app; preview_stop stops it only if this session started it. First render includes a Gradle compile (tens of seconds); subsequent saves re-render warm in a few seconds.

The verified dev loop with ZERO bookkeeping: the preview service already retains the previous generation of every screen's tree, so this diffs a screen's LAST render against its CURRENT one — no pre-edit snapshot needed. Returns { changes, regressions:{drift, driftChecked, a11y}, verdict: 'proven-clean' | 'changed-with-regressions' | 'no-change' } (drift is checked against the previews dir's design-system.json when present). Typical loop: edit → preview_status{waitForRender:true} → preview_diff{screen:<a changed id>}. For a baseline that must survive sessions, the lane's golden trees (qa/golden/, UPDATE_GOLDEN=1) are the durable regression layer.

The agent's post-edit feedback call. Without arguments: returns the preview service's current status (mode, version, rendering, lastError/lastErrorSource, lastActivity, changedLastRender, per-screen summaries incl. lastChangedVersion, and `renderer` — the render PIPELINE's own health: {lastOutcome:'ok'|'failed'|'never', lastSuccessAt, lastAttemptAt, consecutiveFailures}, tracked independently of lastError so a later, unrelated compile message can never mask a dead renderer. renderer.lastOutcome:'failed' means every render since lastSuccessAt has failed outright (Gradle/daemon call itself threw) — the screens below are stale pixels, not a fresh 'no changes' result; this is different from lastErrorSource:'compile' (the user's edit didn't build). With waitForRender:true it BLOCKS until the next render cycle completes (success or failure) or a hot-recompile failure is detected, then returns the same status plus `timedOut` — so the edit loop is: edit → preview_status{waitForRender:true} → read changedLastRender (empty = the edit reached no screen) and lastError (source 'compile' = the edit didn't even build). No polling, no sleeps.

Stops the resident preview service started by `preview` (file watcher + gallery server). Returns the final status. The Gradle daemon it used stays warm (that's desirable).

Pixel preview with a PATH-ONLY contract: returns { path, width, height, sizeBytes, displayHint } parsed from the PNG header — NEVER the image bytes/base64 (pixels flow to the human, structure flows to the AI). Sources: `projectDir` (+ optional `screen` id, default 'shell') renders a REAL screen of a create-cmp app headlessly — through the resident preview daemon when one is running (~1s warm) else via its generated `:composeApp:renderScreens` task — no device/emulator — and also returns `treePath` (the structural twin), `previewsDir`, and `via` ('daemon'|'gradle'); `source:{kind:'live',port?}` fetches the RUNNING app's current screen from GET /inspect/screenshot and writes it to `out` (or a temp file); `pngPath` points at a PNG a harness already produced; `harness:true` runs the create-cmp checkout's demo harness (bundled SampleScreen — use `projectDir` for real apps). Pair it with inspect_tree (format:'wireframe') for the structural twin.

Marks a comment resolved via the project's own qa/lib/comments.mjs, recording author 'agent' and `note` (what you actually did about it — update the spec/plan/code FIRST, then resolve; the console never edits code itself, per §4's principle, so this is the only way a comment closes). Returns {ok:true, comment} or {ok:false, reason} — the library's refusal verbatim (unknown id, already resolved). The console's Comments tab then shows the resolution + note. Requires a running preview service (call preview{projectDir} first).

The human-comment half of the console (VERIFICATION-LAYER-DESIGN.md §7.3: 'pixels flow to the human, structure flows to the AI, judgment flows back through comments'): the full comment ledger, via the PROJECT'S OWN qa/lib/comments.mjs (never forked here) — target (screen/element/spec-line/design-system/architecture/general, rendered readably in the console's Comments tab), text, author, createdAt, status, resolution. Without waitForComment: the current snapshot {available, schema, comments}. With waitForComment:true: BLOCKS — same shape as approval_status's waitForDecision — until a NEW comment lands (a 💬 submitted in the console), then returns {timedOut, available, added:[newComments], comments}. A resolve does NOT wake this wait — only a fresh comment does. {available:false} in a project with no comments library (an older, pre-comments-wave scaffold) — resolves immediately, there is nothing to wait for. Loop of record: propose a change, tell the human to review it in the console, review_comments{waitForComment:true} instead of polling, act on `added`, then resolve_comment with what you did. Requires a running preview service (call preview{projectDir} first).

GET /inspect/crashes on the running app (current boot + previous ones; the on-device handler chains to whatever handler was installed before it — it never swallows the crash). Each crash is attributed: its stack frames are intersected with recently-edited files (git status + git diff in `projectDir`, default cwd) to produce a verdict — 'likely-caused-by-recent-edit' (with the matching frame(s) as evidence) or 'no-recent-edit-implicated'. Returns { crashes:[{timestamp,exception,message,frames,attribution}], changedFilesConsidered }. Requires connect_live.

Shells `adb shell pidof <appId>` (appId resolved from the live inspector's GET /inspect/health) then `adb logcat -v threadtime --pid=<pid> -d` and returns STRUCTURED, BOUNDED entries — never a log firehose: default limit 200, max 2000, newest-first tail. Optional `level` keeps that severity and above (adb's own ordering); `since` (ISO timestamp) keeps entries at/after it. No on-device log capture — v1 is adb-only, so it needs a device/emulator attached and adb on PATH; errors are actionable (no device, no process running, adb missing).

GENESIS-FLOW-DESIGN.md §2 'Design-language candidates (variants)': copies the CURRENT preview render (every screen's screen.png from the last completed render) plus design-system.json into composeApp/build/previews/variants/<name>/, REPLACING that variant if one with the same name already exists. Returns { name, screens, designSystemStashed, dir }. `name` must match [a-z0-9-]+ (lowercase letters, digits, hyphens) — anything else is refused, not sanitized. Typical loop: edit Tokens.kt, preview_status{waitForRender:true}, snapshot_variant{name:'warmer'}, repeat per candidate token set, then tell the human to compare them side by side in the Design System tab's candidates strip and click Pick — observed via review_comments{waitForComment:true} as a `pick:<name>` comment targeting design-system; apply the chosen tokens, resolve_comment with a note, then approve. Requires a running preview service (call preview{projectDir} first) with at least one completed render.