lazycodex-ai 5.0.0-beta.9 → 5.0.0

package/packages/shared-skills/skills/debugging/references/tools/playwright-cli.md

@@ -1,194 +0,0 @@
-# Playwright CLI — Browser QA That Actually Drives a Browser
-
-**https://playwright.dev/ · https://github.com/microsoft/playwright**
-
-For any browser-served web UI bug, this is the correct tool. Not curl. Not imagination. Not a headless HTTP library. A real browser with a real rendering engine, real JS execution, real cookies, real service workers, real viewport.
-
-**In Phase 8 Manual QA for browser products, using Playwright is not optional.** Curl cannot catch: CSS that breaks at specific viewport widths, hydration mismatches, client-side router bugs, cookie/session interactions, service-worker caching, JS-triggered navigations. All of those are common bug classes. Drive a browser.
-
-> Note: `microsoft/playwright-cli` is the legacy repo; the current tooling lives in `@playwright/test` (npm) and `playwright` (pip), which include the `playwright` CLI. Use those — the legacy `playwright-cli` package is deprecated.
-
----
-
-## When to reach for Playwright
-
-| Bug symptom | Use Playwright? |
-|---|---|
-| Form submit produces wrong result | ✅ — Playwright drives the form exactly as a user does |
-| Page blank in prod, fine locally | ✅ — hydration/env differences need a real browser |
-| CSS looks wrong at a specific width | ✅ — use `--viewport-size` |
-| Click doesn't fire / wrong handler | ✅ — Playwright fires real DOM events |
-| Flash of unstyled content / loading glitch | ✅ — use trace viewer to see frames |
-| API returns wrong data | ❌ — use curl, this isn't a browser bug |
-| Backend returns wrong status code | ❌ — use curl |
-| Client hits a URL that returns 500 | ✅ but also ❌ — Playwright shows the call + response + failure effect on UI |
-
----
-
-## Install (per-project)
-
-Playwright installs browser binaries separately from the npm package.
-
-```bash
-# In the project
-npm init playwright@latest             # interactive; picks TS/JS + browsers + config
-# Or if Playwright is already a dep:
-npx playwright install                 # downloads browsers
-npx playwright install chromium        # just chromium
-npx playwright install --with-deps     # also installs OS deps (Linux)
-```
-
-Python:
-```bash
-pip install playwright
-playwright install
-```
-
----
-
-## The four things you'll actually use
-
-### 1. `codegen` — record a session, generate the script
-
-The fastest way to create a repro. Opens a real browser; your clicks / typing become a Playwright script you can paste into a test.
-
-```bash
-npx playwright codegen https://your-app.local
-npx playwright codegen --viewport-size=375,667 https://your-app.local    # iPhone SE size
-npx playwright codegen --device="iPhone 14" https://your-app.local
-```
-
-Click / type / navigate in the browser; watch the script build in the side panel. Copy the generated script into your journal as the repro for Phase 8.
-
-### 2. A one-shot Playwright script — reproduce + capture
-
-Usually the Phase 8 QA artifact. Save to `/tmp/debug-repro.spec.ts` (journal it):
-
-```ts
-// /tmp/debug-repro.spec.ts
-import { test, expect } from '@playwright/test';
-
-test('refinement chat shows non-empty response when env var set', async ({ page }) => {
-  await page.goto('http://localhost:3000/chat');
-  await page.fill('textarea[name="message"]', 'Add a logging step');
-  await page.click('button[type=submit]');
-
-  // Wait for the response to appear (not just the spinner to disappear)
-  const response = page.locator('[data-testid="assistant-reply"]');
-  await expect(response).toBeVisible({ timeout: 30_000 });
-  await expect(response).not.toBeEmpty();
-
-  // Capture evidence
-  await page.screenshot({ path: '/tmp/debug-after-fix.png', fullPage: true });
-  console.log(await response.textContent());
-});
-```
-
-Run it with tracing enabled for rich post-mortem:
-
-```bash
-npx playwright test /tmp/debug-repro.spec.ts --trace on --headed
-```
-
-### 3. `PWDEBUG=1` — step through the script with Playwright Inspector
-
-```bash
-PWDEBUG=1 npx playwright test /tmp/debug-repro.spec.ts
-```
-
-Opens the Playwright Inspector alongside the browser. You can step through Playwright actions, see the DOM state at each step, and edit selectors on the fly.
-
-Use this when the script doesn't reproduce cleanly and you need to watch it run.
-
-### 4. `show-trace` — post-mortem on a failed run
-
-```bash
-npx playwright show-trace trace.zip
-# or from the test-results dir:
-npx playwright show-trace test-results/<test-name>/trace.zip
-```
-
-Scrubs through a recorded session: timeline, DOM snapshot at each action, network, console, source. When a test failed on CI but passed locally, this is the single best artifact.
-
----
-
-## Headless vs headed during debugging
-
-Always add `--headed` when debugging. Headless browsers sometimes behave subtly differently (font rendering, viewport, media permissions). For QA evidence, run headed and screenshot.
-
-```bash
-npx playwright test --headed
-npx playwright test --headed --project=chromium     # pin the browser
-```
-
----
-
-## Catching the silent-failure patterns Playwright is good at
-
-```ts
-// Toast that flashes and disappears
-page.on('console', msg => console.log('[browser console]', msg.type(), msg.text()));
-
-// Unhandled page errors (uncaught exceptions in the page JS)
-page.on('pageerror', err => console.error('[page error]', err));
-
-// Network failures — e.g., backend returned 500 but UI shows nothing
-page.on('response', async resp => {
-  if (!resp.ok()) {
-    console.warn(`[network ${resp.status()}] ${resp.url()} — ${await resp.text()}`);
-  }
-});
-
-// Request that never came back
-page.on('requestfailed', req => {
-  console.error('[request failed]', req.url(), req.failure()?.errorText);
-});
-```
-
-Add these listeners to the top of the debug script. They surface a lot of the "UI showed nothing" class of bug.
-
----
-
-## Viewport and device emulation
-
-CSS bugs that only appear at specific sizes, or layout bugs on mobile:
-
-```ts
-// At test level
-test.use({ viewport: { width: 375, height: 667 } });
-
-// Per-page
-await page.setViewportSize({ width: 375, height: 667 });
-
-// Predefined devices
-import { devices } from '@playwright/test';
-test.use({ ...devices['iPhone 14'] });
-```
-
----
-
-## Gotchas
-
-- **Wait for state, not for time.** `await page.waitForTimeout(2000)` is flaky. Use `await expect(locator).toBeVisible()` or `page.waitForResponse(urlPattern)`.
-- **Stale selectors re-resolve.** Playwright's locators re-find the element on each action, unlike Puppeteer's handles. Don't over-think it.
-- **Service workers persist across test runs in headed mode.** If you see cached behavior from a previous run, add `await context.clearCookies()` + clear storage before the test.
-- **Installing on CI requires `--with-deps`** on Linux images that lack the browser's shared-library deps.
-- **Parallel tests share a browser process by default**; if one test polls a debugger port, others may interfere. Use `workers: 1` for debugging.
-
----
-
-## Phase 9 cleanup specifics
-
-```bash
-# Remove trace files from debug runs
-rm -rf playwright-report/ test-results/ trace.zip
-
-# Remove debug spec files from /tmp
-rm -f /tmp/debug-*.spec.ts
-
-# Remove screenshot captures
-rm -f /tmp/debug-*.png
-
-# If you installed browsers just for this session (rare):
-# Don't remove them — they're useful for future sessions. They live in ~/Library/Caches/ms-playwright (macOS) or ~/.cache/ms-playwright (Linux).
-```

package/packages/shared-skills/skills/programming/scripts/rust/check-no-excuse-rules.py

@@ -1,296 +0,0 @@
-#!/usr/bin/env -S uv run --script
-# /// script
-# requires-python = ">=3.11"
-# dependencies = []
-# ///
-#
-# How to run:
-#   uv run --script check-no-excuse-rules.py src/lib.rs src/main.rs
-#   uv run --script check-no-excuse-rules.py src/           # recursively finds .rs files
-#   uv run --script check-no-excuse-rules.py .              # entire tree
-#
-# No-excuse rule checker for Rust files — Python rewrite of check-no-excuse-rules.sh.
-# Only rules enforceable via pure text matching live here.
-# Everything semantic is on clippy + miri + nextest.
-#
-# Rules:
-#   unwrap            .unwrap() outside tests without // SAFE-UNWRAP:
-#   expect            .expect() outside tests without // SAFE-EXPECT:
-#   placeholder-macro todo!/unimplemented!/unreachable!/unreachable_unchecked! in committed code
-#   box-dyn-error     Box<dyn Error> in non-test code
-#   lib-panic         panic!() in library code
-#   unsafe-no-safety  unsafe { without // SAFETY: in preceding 5 lines
-#   unjustified-clippy-allow  #[allow(clippy::...)] without // CLIPPY-ALLOW:
-#   narrowing-as-cast possible narrowing 'as' cast
-#
-# Opt-out: place the appropriate comment on the previous line:
-#   // SAFE-UNWRAP: <reason>
-#   // SAFE-EXPECT: <reason>
-#   // SAFETY: <reason>          (for unsafe blocks, within 5 lines above)
-#   // CLIPPY-ALLOW: <reason>
-#
-# Test paths (exempt from unwrap/expect/placeholder/box-dyn-error/lib-panic):
-#   tests/, benches/, examples/, build.rs, *_test.rs, #[cfg(test)] regions
-
-from __future__ import annotations
-
-import re
-import sys
-from pathlib import Path
-
-# ---------------------------------------------------------------------------
-# Patterns (compiled once)
-# ---------------------------------------------------------------------------
-
-RE_UNWRAP = re.compile(r"\.unwrap\(\)")
-RE_EXPECT = re.compile(r"\.expect\(")
-RE_PLACEHOLDER = re.compile(r"\b(todo!|unimplemented!|unreachable!|unreachable_unchecked!)")
-RE_BOX_DYN_ERROR = re.compile(r"Box<dyn\s+Error")
-RE_PANIC = re.compile(r"\bpanic!\(")
-RE_UNSAFE_BLOCK = re.compile(r"\bunsafe\s*\{")
-RE_CLIPPY_ALLOW = re.compile(r"#\[allow\(clippy::")
-RE_CFG_TEST = re.compile(r"#\[cfg\(test\)\]")
-RE_SAFE_UNWRAP = re.compile(r"//\s*SAFE-UNWRAP:")
-RE_SAFE_EXPECT = re.compile(r"//\s*SAFE-EXPECT:")
-RE_SAFETY = re.compile(r"//\s*SAFETY:")
-RE_CLIPPY_ALLOW_JUST = re.compile(r"//\s*CLIPPY-ALLOW:")
-
-# Narrowing cast: (wider) as (narrower)
-# Wider types that lose bits when cast to narrower targets.
-# No leading \b — must match e.g. `999u64 as u32` where a digit precedes the type.
-_WIDER = r"(?:u16|u32|u64|u128|usize|i16|i32|i64|i128|isize)"
-_NARROWER = r"(?:u8|u16|u32|i8|i16|i32)"
-RE_NARROWING_CAST = re.compile(
-    rf"{_WIDER}\s+as\s+{_NARROWER}"
-)
-
-# Test-path fragments.
-_TEST_PATH_PARTS = {"tests", "benches", "examples"}
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-violations = 0
-
-
-def report(file: str, line: int, rule: str, detail: str) -> None:
-    """Emit a GitHub-Actions-compatible error annotation to stderr."""
-    global violations
-    print(f"::error file={file},line={line}::[{rule}] {detail}", file=sys.stderr)
-    violations += 1
-
-
-def is_test_path(path: Path) -> bool:
-    """Return True if *path* is in a test/bench/example directory or is a test file."""
-    parts = path.parts
-    for part in parts:
-        if part in _TEST_PATH_PARTS:
-            return True
-    if path.name == "build.rs":
-        return True
-    if path.name.endswith("_test.rs"):
-        return True
-    return False
-
-
-def is_lib_path(file: Path) -> bool:
-    """Heuristic: is this file library code (not main.rs, not src/bin/*)."""
-    parts = path_parts_str(file)
-    # Must live under src/
-    if "src" not in parts:
-        return False
-    if file.name == "main.rs":
-        return False
-    # src/bin/* is binary code
-    try:
-        src_idx = parts.index("src")
-        if src_idx + 1 < len(parts) and parts[src_idx + 1] == "bin":
-            return False
-    except ValueError:
-        return False
-    return True
-
-
-def path_parts_str(p: Path) -> list[str]:
-    return list(p.parts)
-
-
-def strip_line_comment(line: str) -> str:
-    """Return the portion of *line* before any ``//`` line comment.
-
-    This is a crude heuristic — it does not handle ``//`` inside string
-    literals, but matches the behaviour of the bash version.
-    """
-    idx = line.find("//")
-    if idx == -1:
-        return line
-    return line[:idx]
-
-
-def collect_rs_files(args: list[str]) -> list[Path]:
-    """Expand CLI arguments: files are kept as-is, directories are walked."""
-    result: list[Path] = []
-    for arg in args:
-        p = Path(arg)
-        if p.is_file():
-            if p.suffix == ".rs":
-                result.append(p)
-        elif p.is_dir():
-            result.extend(sorted(p.rglob("*.rs")))
-        # Ignore non-existent / non-.rs
-    return result
-
-
-# ---------------------------------------------------------------------------
-# Main checker
-# ---------------------------------------------------------------------------
-
-def check_file(file: Path) -> None:
-    in_test_file = is_test_path(file)
-    in_cfg_test = False
-    cfg_test_brace_depth = 0
-
-    try:
-        lines = file.read_text(encoding="utf-8", errors="replace").splitlines()
-    except OSError as exc:
-        print(f"warning: cannot read {file}: {exc}", file=sys.stderr)
-        return
-
-    for line_no_0, raw_line in enumerate(lines):
-        line_no = line_no_0 + 1  # 1-indexed
-
-        # --- #[cfg(test)] region tracker ---
-        if RE_CFG_TEST.search(raw_line):
-            in_cfg_test = True
-            cfg_test_brace_depth = 0
-
-        if in_cfg_test:
-            opens = raw_line.count("{")
-            closes = raw_line.count("}")
-            cfg_test_brace_depth += opens - closes
-            if cfg_test_brace_depth <= 0 and not RE_CFG_TEST.search(raw_line):
-                in_cfg_test = False
-
-        exempt = in_test_file or in_cfg_test
-        code_only = strip_line_comment(raw_line)
-
-        if not exempt:
-            # .unwrap()
-            if RE_UNWRAP.search(code_only):
-                prev = lines[line_no_0 - 1] if line_no_0 > 0 else ""
-                if not RE_SAFE_UNWRAP.search(prev):
-                    report(
-                        str(file), line_no, "unwrap",
-                        ".unwrap() outside tests - use ? / ok_or / pattern match "
-                        "or annotate previous line with // SAFE-UNWRAP: <reason>",
-                    )
-
-            # .expect(...)
-            if RE_EXPECT.search(code_only):
-                prev = lines[line_no_0 - 1] if line_no_0 > 0 else ""
-                if not RE_SAFE_EXPECT.search(prev):
-                    report(
-                        str(file), line_no, "expect",
-                        ".expect() outside tests - use ? or annotate previous "
-                        "line with // SAFE-EXPECT: <reason>",
-                    )
-
-            # todo!/unimplemented!/unreachable!/unreachable_unchecked!
-            if RE_PLACEHOLDER.search(code_only):
-                report(
-                    str(file), line_no, "placeholder-macro",
-                    "todo!/unimplemented!/unreachable! in committed code",
-                )
-
-            # Box<dyn Error>
-            if RE_BOX_DYN_ERROR.search(code_only):
-                report(
-                    str(file), line_no, "box-dyn-error",
-                    "Box<dyn Error> in non-test code - use anyhow::Error (apps) "
-                    "or thiserror enum (libs)",
-                )
-
-            # panic!() in library code
-            if is_lib_path(file) and RE_PANIC.search(code_only):
-                report(
-                    str(file), line_no, "lib-panic",
-                    "panic!() in library code - return Result",
-                )
-
-        # unsafe { without // SAFETY: — always enforced, even in tests
-        if RE_UNSAFE_BLOCK.search(code_only):
-            start = max(0, line_no_0 - 5)
-            window = "\n".join(lines[start : line_no_0 + 1])
-            if not RE_SAFETY.search(window):
-                report(
-                    str(file), line_no, "unsafe-no-safety-comment",
-                    "unsafe block without // SAFETY: comment in preceding 5 lines",
-                )
-
-        # #[allow(clippy::...)] without // CLIPPY-ALLOW: — always enforced
-        if RE_CLIPPY_ALLOW.search(code_only):
-            prev = lines[line_no_0 - 1] if line_no_0 > 0 else ""
-            if not RE_CLIPPY_ALLOW_JUST.search(prev):
-                report(
-                    str(file), line_no, "unjustified-clippy-allow",
-                    "#[allow(clippy::...)] without // CLIPPY-ALLOW: <reason> on "
-                    "previous line",
-                )
-
-        # Narrowing numeric `as` casts
-        if RE_NARROWING_CAST.search(code_only):
-            report(
-                str(file), line_no, "narrowing-as-cast",
-                "possible narrowing 'as' cast - use TryFrom / try_into() for "
-                "fallible conversion",
-            )
-
-
-# ---------------------------------------------------------------------------
-# Entry point
-# ---------------------------------------------------------------------------
-
-def main() -> None:
-    global violations
-
-    if len(sys.argv) < 2:
-        print(f"Usage: {sys.argv[0]} <file.rs|dir> [file.rs|dir ...]", file=sys.stderr)
-        sys.exit(2)
-
-    files = collect_rs_files(sys.argv[1:])
-    if not files:
-        print("warning: no .rs files found in the given arguments", file=sys.stderr)
-        sys.exit(0)
-
-    for f in files:
-        check_file(f)
-
-    if violations > 0:
-        print("", file=sys.stderr)
-        print(
-            f"rust-programmer: {violations} violation(s). Fix before declaring work done.",
-            file=sys.stderr,
-        )
-        print("", file=sys.stderr)
-        print("Then run the full toolchain gate:", file=sys.stderr)
-        print("  cargo +stable fmt --all -- --check", file=sys.stderr)
-        print(
-            "  cargo +stable clippy --all-targets --all-features -- -D warnings",
-            file=sys.stderr,
-        )
-        print("  cargo nextest run --all-targets --all-features", file=sys.stderr)
-        print(
-            "  cargo +nightly miri nextest run --all-features    # if unsafe touched",
-            file=sys.stderr,
-        )
-        print("  cargo machete", file=sys.stderr)
-        print("  cargo deny check", file=sys.stderr)
-        sys.exit(1)
-
-    print(f"rust-programmer: no-excuse rules passed for {len(files)} file(s).")
-
-
-if __name__ == "__main__":
-    main()

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

@@ -1,45 +0,0 @@
-# agent-browser setup (Web capture fallback)
-
-Use this when the project has **no** browser tooling configured or available for the Web
-capture path in Step 2 (no playwright / dev-browser skill, no usable headless browser).
-[agent-browser](https://github.com/vercel-labs/agent-browser) is a standalone CLI that
-drives a real Chromium and can screenshot a page at a fixed viewport — exactly what the
-`image-diff` evidence step needs.
-
-Repo: https://github.com/vercel-labs/agent-browser
-
-## Install
-
-```
-npm install -g agent-browser && agent-browser install
-```
-
-`npm install -g agent-browser` installs the CLI globally; `agent-browser install` downloads the
-managed browser it drives. If Bun is already available, `bun add -g agent-browser && agent-browser install`
-is equivalent, but npm is the default because LazyCodex/Codex installations do not require Bun.
-
-Confirm it is ready and discover the current flags:
-
-```
-agent-browser --help
-```
-
-## Capture a screenshot at a fixed viewport
-
-Set the viewport first, then screenshot — this guarantees the ACTUAL capture matches the
-REFERENCE viewport so `image-diff` compares like-for-like:
-
-```
-agent-browser set viewport 1280 720      # width height (add a third arg, e.g. 2, for retina scale)
-agent-browser screenshot actual.png      # add --full for full-page, --screenshot-dir ./shots for a custom dir
-```
-
-Then feed the PNG into the diff exactly as in Step 2:
-
-```
-node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff <reference.png> actual.png
-```
-
-Match the viewport numbers to whatever the reference/mock was captured at; mismatched
-dimensions make `dimensionsMatch` false and inflate `diffRatio`. Run `agent-browser --help`
-for the full command set (navigation, batch, annotate, format/quality flags).