lazycodex-ai 5.0.0-beta.9 → 5.0.0

package/packages/shared-skills/skills/visual-qa/AGENTS.md

@@ -0,0 +1,58 @@
+# visual-qa — Bundled Visual-Evidence CLI
+
+**Generated:** 2026-08-24 (f3642fcda)
+
+## OVERVIEW
+
+The visual-QA skill's executable core: a zero-dependency Node CLI that produces machine evidence (`image-diff`, `tui-check`) plus the TypeScript sources it is bundled from. Earned this file: the only shared skill shipping a built bundle whose runtime and development sources must be kept in lockstep.
+
+## STRUCTURE
+
+```
+visual-qa/
+├── SKILL.md                      # reviewer workflow (dual oracle, evidence gates) — the prose contract
+├── references/browser-setup.md
+└── scripts/
+    ├── visual-qa.mjs             # SHIPPED RUNTIME: bun-build bundle of cli.ts (+ embedded modules)
+    ├── cli.ts                    # development source; dispatches image-diff / tui-check
+    ├── image-diff.ts             # diffImages — 8x8 grid cells, hotspots, rounded metrics
+    ├── tui-grid.ts               # checkTui — column overflow + border alignment verdicts
+    ├── east-asian-width.ts       # charWidth / stringWidth — CJK-aware width math
+    ├── ansi.ts                   # ANSI escape stripping (width must be escape-aware)
+    ├── png-decode.ts / png-crc.ts / png-synth.ts   # stdlib PNG codec (no deps)
+    ├── types.ts
+    └── *.test.ts                 # co-located bun tests for every module above
+```
+
+## BUNDLE/SOURCE DUALITY
+
+`visual-qa.mjs` is the artifact the skill's commands invoke (`node "$SKILL_DIR/scripts/visual-qa.mjs" …`); the `.ts` files exist for development and tests only. A behavior fix lands in the TS source AND the bundle is regenerated from `cli.ts` — editing one without the other makes tests and runtime disagree. Never hand-edit the `.mjs`.
+
+## SURFACE
+
+- Commands: `image-diff <reference.png> <actual.png>` and `tui-check <capture.txt> --cols <N>`; JSON verdict output (hotspot cells, overflow lines, wide-char columns, border alignment).
+- Module exports: `diffImages`, `checkTui`, `charWidth`/`stringWidth`, ANSI + PNG helpers. `cli.ts` owns `CliError`, `parseColumns`, `run`, `main`.
+
+## CONVENTIONS
+
+- Zero runtime dependencies — PNG decode/synthesis and ANSI handling are hand-rolled in `scripts/`; keep it that way (the bundle must stay require-free apart from `node:` builtins).
+- Width is never `String.length`: CJK wide characters and ANSI escapes are accounted for before any column math.
+- Tests are co-located `bun test scripts/*.test.ts`, given/when/then style per repo convention.
+
+## ANTI-PATTERNS
+
+- NEVER hand-edit `visual-qa.mjs`; regenerate from source.
+- Don't add an npm dependency to make PNG/diff easier — the no-dep bundle is the point.
+- Column math that ignores CJK width or ANSI escapes is wrong by construction; `tui-check` exists because text-diff tools get terminal grids wrong.
+- Skill-level rule worth repeating for code changes: `tmux capture-pane` is forbidden as a capture mechanism.
+
+## COMMANDS
+
+```bash
+# from packages/shared-skills/skills/visual-qa/
+node scripts/visual-qa.mjs image-diff <reference.png> <actual.png>
+node scripts/visual-qa.mjs tui-check <capture.txt> --cols 80
+bun test scripts/*.test.ts
+```
+
+- Parent: [`packages/shared-skills/AGENTS.md`](../../AGENTS.md).

package/packages/shared-skills/skills/visual-qa/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: visual-qa
-description: "MUST USE after building/changing any UI or when asked whether a page, component, or TUI looks right. Rigorous visual QA across web/page and terminal UIs. Prefer browser:control-in-app-browser for unauthenticated browser/page QA in Codex, then Playwright/agent-browser/dev-browser. Captures screenshot/TUI evidence with bundled diff scripts, runs design-system/functional and visual-fidelity/CJK reviewer passes, then synthesizes a good/bad verdict. Triggers: visual QA, screenshot/pixel diff, UI looks wrong, reference fidelity, design system check, responsive check, CJK text clipping, TUI alignment, box-drawing drift."
+description: "Runs rigorous visual QA across web, terminal, and paginated surfaces with screenshot evidence and a verdict. Use for any UI build or change, or when asked whether a page, component, or TUI looks right."
 ---
 
 # Visual QA - Dual-Oracle Web and TUI Verification
@@ -9,7 +9,7 @@ Verify a rendered UI against intent using objective script evidence plus two par
 
 ## Purpose and when to use
 
-- Use after you build or change any UI, before calling it done. Covers web/page UIs and TUI/terminal UIs.
+- Use after you build or change any UI, before calling it done. Covers web/page UIs, TUI/terminal UIs, and paginated documents.
 - Use when output must match a mock, a baseline, or a stated design intent; when you suspect a regression; when CJK (Korean/Japanese/Chinese) text may clip, misalign, or wrap awkwardly; when a claimed design system might actually be a flat image; when a terminal layout may overflow or its borders may break.
 - Skip when there is no rendered surface (pure backend or library logic with no visual or terminal output). For broad post-implementation review use review-work; this skill is the visual specialist.
 
@@ -19,6 +19,7 @@ In the commands below, `$SKILL_DIR` is this skill's own directory (the folder co
 
 - Web/page UI: renders in a browser (HTML/CSS/JS, components, canvas, SVG). Evidence is screenshots.
 - TUI/terminal UI: renders as text in a terminal (box-drawing, panes, status lines, REPL/TUI apps). Evidence is terminal captures.
+- Paginated document: renders as ordered pages (PDF report, printed HTML, exported deck). Evidence is every page rendered to an image - `pdftoppm -png -r 150 <file>.pdf <prefix>` or the pipeline's own renderer. Extracted text is not evidence here: layout is exactly what extraction discards, so a stranded block, a split table, or a near-empty page survives a clean text check.
 - Reference-fidelity UI: any web/page UI built from a concrete reference packet, including screenshots, generated Imagen/Stitch mockups, Figma exports, overview text, annotations, or source-site captures. Evidence is the full reference packet plus same-size actual captures.
 
 If the change touches both, run both capture tracks and feed both into the passes.
@@ -48,7 +49,7 @@ Before any reviewer sees an image, verify each capture yourself: the file signat
 ### Web
 
 1. Capture a REFERENCE image: the user's mock/target, generated page snapshot, Figma export, source-site capture, or known-good baseline. Save as PNG. If the user provided overview text or annotations, save them next to the image and treat them as part of the reference packet.
-2. Capture the ACTUAL rendered screenshot at the same viewport size. In Codex, when `browser:control-in-app-browser` is available and the page does not need an authenticated user browser session, use that Browser plugin first for navigation, page state inspection, and screenshots. If it is unavailable or lacks the needed capture action, use the project's configured browser tooling (the playwright, agent-browser, or dev-browser skill). Save as PNG. If none is configured or available, install [agent-browser](https://github.com/vercel-labs/agent-browser) (`npm install -g agent-browser && agent-browser install`) and capture with it — see `$SKILL_DIR/references/agent-browser-setup.md` for the full setup, including how to shoot a fixed-viewport screenshot.
+2. Capture the ACTUAL rendered screenshot at the reference viewport with omowright from js eval (the library is staged in the `browser` skill): the owned engine (`connectPipe` on a task-owned profile, viewport pinned with `emulate`, then `page.screenshot()`) for anything unauthenticated, or the attached engine (`connectBrowserSkill()` → `session.screenshot()`) when the page needs the user's login — never a clone of, or a launch against, the user's live profile. Save PNG and return its path; close the browser or stop the session. See `$SKILL_DIR/references/browser-setup.md` for fixed-viewport examples and prerequisites.
 3. Run the diff and keep the JSON:
 
 ```

package/packages/shared-skills/skills/visual-qa/references/browser-setup.md

@@ -0,0 +1,77 @@
+# Browser setup (Web capture)
+
+Capture with omowright from the js-eval kernel. The library is staged inside the `browser` skill;
+load it once per session:
+
+```js
+const { loadOmowright } = await import("<browser-skill-root>/scripts/omowright.mjs")
+const { omowright } = await loadOmowright()
+```
+
+## Owned engine (default for QA)
+
+A browser your code launches, with a task-owned profile, pinned viewport and no user state.
+`connectPipe` opens no listening port and reaps the process on `close()`.
+
+```js
+// js-eval cell; url and pngPath belong to this QA run.
+const { mkdtempSync, rmSync } = await import("node:fs")
+const profile = mkdtempSync(`${(await import("node:os")).tmpdir()}/visual-qa-`)
+const browser = await omowright.connectPipe({
+  browserPath: chromeBinary,                      // installed Chrome, Chromium, CloakBrowser or chrome-headless-shell
+  browserArgs: ["--headless", "--no-first-run", `--user-data-dir=${profile}`],
+  storageRoot: profile,
+})
+try {
+  const page = await browser.newTab("about:blank")
+  await omowright.emulate(page, { width: 1280, height: 720, deviceScaleFactor: 1, mobile: false, hasTouch: false })
+  await page.goto(url, { waitUntil: "load" })
+  await Bun.write(pngPath, await page.screenshot())
+  console.log(pngPath)
+} finally {
+  await browser.close()
+  rmSync(profile, { recursive: true, force: true })
+}
+```
+
+Chrome must already be installed; report an absent executable rather than downloading a managed
+browser. For bot-scored or WAF targets use `connectCloakProfile({ profileDir })` (CloakBrowser
+with a pinned fingerprint seed) — the `browser` skill's `references/owned-engine/README.md`
+covers it.
+
+## Attached engine (authenticated pages)
+
+When the capture needs the user's login, drive the browser they are signed into instead of
+cloning its profile:
+
+```js
+const session = await omowright.connectBrowserSkill({ name: "visual-qa capture", focused: false })
+try {
+  await session.navigate(url, { waitUntil: "load" })
+  await session.resize(1280, 720)
+  const shot = await session.screenshot()            // { buffer, width, height }
+  await Bun.write(pngPath, shot.buffer)
+} finally {
+  await session.stop()
+}
+```
+
+NEVER launch anything against, or clear cookies/cache/site data from, the user's live profile;
+the attached engine is the only sanctioned way to a signed-in page. If no extension is connected,
+run the `browser` skill's `scripts/browser-install.mjs` for the browser the user actually uses
+(from memory, or its detection; on `needsChoice` ask them and pass `--browser=<id>`), relay its
+one human step, and wait — do
+not fall back to the owned engine for an authenticated criterion.
+
+## Capture a screenshot at a fixed viewport
+
+Match CSS viewport AND PNG dimensions: pin `deviceScaleFactor` through `emulate` (owned) or
+`resize` (attached) instead of resizing the PNG to force a pass. Wait for the specific page state
+(a locator, a `waitForURL`, a `createNetworkSnoop(page).waitFor(...)`), not a sleep, then compare:
+
+```sh
+node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff reference.png actual.png
+```
+
+Inspect `dimensionsMatch` and `diffRatio`, then inspect the image. Close every browser and session
+and the fixture server, even on a failed capture; remove the owned profile in the same `finally`.

package/script/qa/web-terminal-visual-qa.mjs

@@ -30,6 +30,8 @@ Inputs:
   --from-file <path>     Render an existing raw terminal byte stream through xterm.js (replay; no interaction).
   --input <token>        Scripted interaction, repeatable, applied in order THROUGH the browser terminal.
                          Literal text is typed; {Enter} {Tab} {Escape} {ArrowDown} {Ctrl+C} etc. are pressed as keys.
+                         {WheelUp} and {WheelDown} send real browser mouse-wheel input over the xterm viewport.
+                         {CtrlSlashByte} and {Ctrl7Byte} send their shared exact terminal control byte.
   --cwd <path>           Working directory for --command. Default: current directory.
   --cols <n> / --rows <n>  Terminal geometry. Default: 120 x 32.
   --dwell-ms <n>         Milliseconds to let the TUI settle after input before capture. Default: 1500.

package/script/qa/xterm-live-terminal.mjs

@@ -80,10 +80,26 @@ const NAMED_KEYS = new Set([
 // An `input` token wrapped in {Braces} is pressed as a named key; anything else
 // is typed literally. Both flow through the browser terminal (xterm onData ->
 // pty), so the interaction is genuinely driven in the web terminal.
-async function driveInput(page, inputs, keyDelayMs) {
+export async function driveInput(page, inputs, keyDelayMs) {
   for (const raw of inputs) {
     const match = /^\{(.+)\}$/.exec(raw);
-    if (match && NAMED_KEYS.has(match[1])) {
+    if (
+      match?.[1] === "CtrlSlashByte" ||
+      match?.[1] === "Ctrl7Byte"
+    ) {
+      await page.evaluate((data) => window.__ptyInput(data), "\u001f");
+    } else if (match && /^(WheelUp|WheelDown)$/.test(match[1])) {
+      const terminal = await page.$(".xterm-screen");
+      const bounds = await terminal?.boundingBox();
+      if (!bounds) throw new Error("xterm viewport unavailable for wheel input");
+      await page.mouse.move(
+        bounds.x + bounds.width / 2,
+        bounds.y + bounds.height / 2,
+      );
+      await page.mouse.wheel({
+        deltaY: match[1] === "WheelDown" ? 720 : -720,
+      });
+    } else if (match && NAMED_KEYS.has(match[1])) {
       await page.keyboard.press(match[1] === "Space" ? " " : match[1], { delay: 15 });
     } else if (match && /^Ctrl\+(.)$/i.test(match[1])) {
       const key = /^Ctrl\+(.)$/i.exec(match[1])[1];

package/dist/cli/install-senpi/index.d.ts

@@ -1 +0,0 @@
-export * from "@oh-my-opencode/omo-senpi/install";

package/dist/cli/senpi-platform-flag.d.ts

@@ -1,4 +0,0 @@
-import type { InstallPlatform } from "./types";
-export declare const SENPI_PLATFORM_ENV_FLAG = "OMO_ENABLE_SENPI_PLATFORM";
-export declare function isSenpiPlatformEnabled(env?: NodeJS.ProcessEnv): boolean;
-export declare function availableInstallPlatforms(env?: NodeJS.ProcessEnv): InstallPlatform[];

package/packages/lsp-tools-mcp/dist/lsp/cleanup-errors.d.ts

@@ -1 +0,0 @@
-export * from "@oh-my-opencode/lsp-core/lsp/cleanup-errors";

package/packages/lsp-tools-mcp/dist/lsp/constants.d.ts

@@ -1 +0,0 @@
-export * from "@oh-my-opencode/lsp-core/lsp/constants";

package/packages/lsp-tools-mcp/dist/lsp/language-mappings.d.ts

@@ -1 +0,0 @@
-export * from "@oh-my-opencode/lsp-core/lsp/language-mappings";

package/packages/lsp-tools-mcp/dist/lsp/process-signal-cleanup.d.ts

@@ -1 +0,0 @@
-export * from "@oh-my-opencode/lsp-core/lsp/process-signal-cleanup";

package/packages/lsp-tools-mcp/dist/missing-dependency-result.d.ts

@@ -1 +0,0 @@
-export * from "@oh-my-opencode/lsp-core/missing-dependency-result";

package/packages/omo-codex/plugin/components/codegraph/AGENTS.md

@@ -1,58 +0,0 @@
-# packages/omo-codex/plugin/components/codegraph/ (CodeGraph MCP Wrapper + Bootstrap Hooks)
-
-**Generated:** 2026-07-17 (7d664b96b)
-
-## OVERVIEW
-
-`@sisyphuslabs/codex-codegraph` (private, Node >=20, bin `omo-codegraph`). Wraps the external CodeGraph CLI (`@colbymchenry/codegraph`, pinned `1.5.0` through the shared `CODEGRAPH_PINNED_VERSION` and the component optionalDependency) behind a stdio MCP server plus Codex lifecycle hooks. Two committed dists ship in the published payload; rebuild `dist/` in the same change as `src/` edits.
-
-Codex wiring (all repo-relative to `packages/omo-codex/plugin/`):
-- **MCP:** `.mcp.json` server `codegraph` → `node components/codegraph/dist/serve.js` (`required: false`).
-- **SessionStart hook:** `hooks/session-start-checking-codegraph-bootstrap.json` → `dist/cli.js hook session-start` (timeout 5).
-- **PostToolUse hook:** `hooks/post-tool-use-checking-codegraph-init-guidance.json`, matcher `^(codegraph[._].*|mcp__codegraph__.*)$` → `dist/cli.js hook post-tool-use`.
-- Both hooks registered in `.codex-plugin/plugin.json`; Windows variants dispatch via `components/bootstrap/scripts/node-dispatch.ps1`.
-
-Serve pipeline (`src/serve.ts`): OMO SOT config gate (`[codex].codegraph.enabled=false` → unavailable stub) → resolve binary (`OMO_CODEGRAPH_BIN` env → bundled → provisioned `~/.omo/codegraph/bin` → PATH) → Node support gate (major 20-24; >=25 crashes CodeGraph mid-indexing; `CODEGRAPH_ALLOW_UNSAFE_NODE=1` overrides) → auto-provision into `~/.omo/codegraph` unless `codegraph.auto_provision=false` → bridge JSON-RPC to `codegraph serve --mcp`. Project cwd resolved from `OMO_CODEGRAPH_PROJECT_CWD` → `OMO_CODEGRAPH_SESSION_START_CWD` → `PWD` → wrapper cwd. When the binary is missing/disabled, `mcp-unavailable.ts` still answers `initialize`/`tools/*` with the skip reason so Codex startup never fails.
-
-Hook pipeline (`src/hook.ts` + `src/session-start-*.ts`): `hook session-start` checks only the exact filesystem marker `<projectRoot>/.codegraph/codegraph.db`; it never invokes the upstream CLI for status. An exact database skips as initialized, an ancestor database records `skipped-nested-root`, and only a definitive no-database result may acquire the per-project atomic lock and spawn `hook session-start-worker`. Live locks record `skipped-locked`; stale locks recover into an exponential cooldown instead of spawning immediately. Worker failures and skips persist a cooldown stamp (15 minutes by default, doubling to a 24-hour cap; configurable with Codex-only `codegraph.session_start_cooldown_ms`, minimum 60000), while success clears it. The worker prepares the workspace, invokes only `codegraph init` with a 60-second tree timeout, and records success only after the exact project database appears. Hook suppressions and worker outcomes append to `~/.omo/codegraph/session-start.jsonl`. `hook post-tool-use` emits init guidance when a codegraph tool result indicates an uninitialized project. `cli.js` with no hook subcommand falls through to serve.
-
-## includeCode CONTRACT (commit 4cf383c5b)
-
-`src/mcp-bridge.ts` rewrites the upstream `codegraph_node` contract in-flight: `tools/list` responses get a clarified description + `includeCode` schema description, and `tools/call` results replace "Structural outline only" text. Contract: `includeCode=true` returns leaf-symbol source only; container symbols (classes, interfaces, structs, enums, modules, namespaces) return structural outlines with member lists BY DESIGN: for container source, request a specific member symbol or file mode with `symbolsOnly=false` plus `offset`/`limit`. Pinned by `test/serve-mcp-bridge.test.ts`.
-
-## KEY FILES
-
-| File | Purpose |
-|------|---------|
-| `src/serve.ts` | MCP entry: config/resolution/Node gates, provisioning, bridge or unavailable stub |
-| `src/cli.ts` | Hook CLI router: `hook session-start` / `hook post-tool-use` / `hook session-start-worker` / serve fallback |
-| `src/hook.ts` | SessionStart exact-root decision pipeline + detached worker spawn |
-| `src/post-tool-use-hook.ts` | PostToolUse init guidance emission |
-| `src/session-start-project.ts` | Exact database and ancestor-coverage filesystem probes |
-| `src/session-start-lock.ts` | Atomic per-project worker lock + stale recovery |
-| `src/session-start-cooldown.ts` | Persistent exponential failure cooldown state |
-| `src/session-start-worker.ts` | Background bootstrap orchestration and lock lifecycle |
-| `src/session-start-command.ts` | Provision/resolve + bounded `codegraph init` invocation |
-| `src/session-start-outcome.ts` | `session-start.jsonl` outcome writer |
-| `src/mcp-bridge.ts` | Stdio JSON-RPC forwarder; per-request framed/line response-mode tracking; codegraph_node contract rewrites; awaits stdio writes and SIGKILLs the child on response-forwarding failure |
-| `src/mcp-unavailable.ts` | Reason-bearing stub MCP server for disabled/missing binary |
-| `src/serve-invocation.ts` | win32 invocation shim: `.cmd`/`.bat` via `cmd.exe /d /s /c`, `.js`/`.mjs`/`.cjs` via `process.execPath` (mirrored by `resolveCodegraphCommandInvocation` in session-start-worker) |
-| `src/hook-types.ts` | Shared hook/worker option + outcome types |
-
-## WHERE TO LOOK
-
-| Task | Location |
-|------|----------|
-| Resolution order, provisioning, Node gate, env, gitignore/workspace prep | `packages/utils/src/codegraph/` (`resolve.ts`, `provision.ts`, `node-support.ts`, `env.ts`, `workspace.ts`, `guidance.ts`), bundled at build time |
-| `[codex].codegraph` config keys (`enabled`, `auto_provision`, `trustedCodegraphInstallDir`) | `packages/omo-codex/plugin/shared/src/config-loader.ts` |
-| JSON-RPC framing primitives | `packages/mcp-stdio-core/src/` |
-| Build / test / typecheck | `bun run build` (bun build → `dist/serve.js` + `dist/cli.js`, target node ESM), `bun test ./test`, `tsc --noEmit` |
-
-## NOTES
-
-- This component tests with `bun test` (unlike the vitest-based `lsp` sibling); given/when/then style.
-- `src/` imports reach sibling packages via relative paths (`../../../../../utils/src/...`); they are inlined by `bun build`, so runtime `dist/` has zero deps beyond Node.
-- `serve.ts` and SessionStart command provisioning derive their version from the shared `CODEGRAPH_PINNED_VERSION`; the component optionalDependency must match that pin.
-- `trustedCodegraphInstallDir` overrides the `~/.omo/codegraph` install dir and is forwarded to children as `CODEGRAPH_INSTALL_DIR`.
-- `resolution.source === "env"` is never auto-provisioned over: a user-set `OMO_CODEGRAPH_BIN` pointing at a missing file skips the MCP instead of silently substituting a download.
-- `runBridgedCodegraphProcess` awaits every stdio write and races `childExit` against response forwarding; a forwarding error (e.g. parent stdout `EPIPE`) rejects the serve promise, destroys the child pipes, and `SIGKILL`s the codegraph child if still alive so a held-open child is never orphaned. Pinned by `test/serve-mcp-bridge-lifecycle.test.ts` and the held-open case in `test/serve-mcp-bridge.test.ts`.