claw-tap 0.0.5__tar.gz

claw_tap-0.0.5/.agents/skills/codex-e2e-test/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: codex-e2e-test
+description: Run real E2E tests against Codex CLI (OpenAI Responses API) through claude-tap proxy
+tags: testing, e2e, codex, responses-api
+---
+
+# Codex E2E Test Skill
+
+Run real end-to-end tests that start `claude-tap` from local source, connect to
+the real Codex CLI via OAuth, and verify Responses API trace output.
+
+## Prerequisites
+
+- `codex` CLI installed (`npm install -g @openai/codex`) and authenticated via OAuth
+- Python dev dependencies: `uv sync --extra dev`
+- Playwright installed: `uv run playwright install chromium`
+
+Verify OAuth works:
+
+```bash
+codex exec "say hello" --dangerously-bypass-approvals-and-sandbox
+```
+
+If it fails with token errors, re-authenticate:
+
+```bash
+codex auth login
+```
+
+## Key Difference from Claude E2E
+
+Codex uses the **OpenAI Responses API** (`/v1/responses`) instead of Anthropic Messages API.
+With OAuth authentication, the upstream is `https://chatgpt.com/backend-api/codex`,
+**not** `https://api.openai.com`.
+
+The proxy must be told the correct target with `--tap-target`.
+
+## Run a Real Codex E2E Trace
+
+### Simple (single tool call)
+
+```bash
+claude-tap --tap-client codex \
+  --tap-target https://chatgpt.com/backend-api/codex \
+  --tap-output-dir /tmp/codex-e2e \
+  --tap-no-open --tap-no-update-check \
+  -- exec "say hello" \
+  --dangerously-bypass-approvals-and-sandbox
+```
+
+### Multi-call (triggers multiple API requests)
+
+Use a task that requires shell tool use — this forces the agent to make multiple
+Responses API calls (models lookup + actual responses):
+
+```bash
+claude-tap --tap-client codex \
+  --tap-target https://chatgpt.com/backend-api/codex \
+  --tap-output-dir /tmp/codex-e2e \
+  --tap-no-open --tap-no-update-check \
+  -- exec "Read pyproject.toml and tell me the project name and version" \
+  --dangerously-bypass-approvals-and-sandbox
+```
+
+Expected: 4+ API calls (2x `GET /v1/models` + 2x `POST /v1/responses`).
+
+## Taking Viewer Screenshots with Playwright
+
+```python
+from playwright.sync_api import sync_playwright
+import time, glob
+
+html = glob.glob("/tmp/codex-e2e/trace_*.html")[-1]
+
+with sync_playwright() as p:
+    browser = p.chromium.launch()
+    page = browser.new_page(viewport={"width": 1440, "height": 1000})
+    page.goto(f"file://{html}")
+    page.wait_for_load_state("networkidle")
+    time.sleep(1)
+
+    # Select a Responses call (data-idx matches trace line index)
+    page.click('.sidebar-item[data-idx="1"]')
+    time.sleep(0.5)
+
+    # Collapse System Prompt, keep Messages open
+    page.evaluate("""() => {
+        const h = document.querySelectorAll('.section-header')[1];
+        const next = h.nextElementSibling;
+        if (next && getComputedStyle(next).display !== 'none') h.click();
+    }""")
+
+    # Scroll to Messages section
+    page.evaluate("""() => {
+        document.querySelectorAll('.section-header')[2]
+          .scrollIntoView({behavior: 'instant', block: 'start'});
+    }""")
+    time.sleep(0.3)
+    page.screenshot(path="/tmp/codex-e2e/messages.png")
+
+    browser.close()
+```
+
+## Verification Checklist
+
+- [ ] Trace `.jsonl` has ≥2 `POST /v1/responses` entries
+- [ ] Response status is 200 (not 401/502)
+- [ ] Token counts are non-zero in Responses calls
+- [ ] HTML viewer is generated (`trace_*.html`)
+- [ ] Sidebar shows multiple calls with model name and token counts
+- [ ] Messages section shows `user` message text (verifies #41 fix)
+- [ ] Response section shows assistant reply (verifies #40 fix)
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| WebSocket 502 then HTTP 401 | Default target `api.openai.com` rejects ChatGPT OAuth tokens | Use `--tap-target https://chatgpt.com/backend-api/codex` |
+| `Missing scopes: api.responses.write` | API key lacks Responses API access | Use OAuth (`codex auth login`) instead of `OPENAI_API_KEY` |
+| Only 1 API call | Simple prompt completed in one round | Use a task requiring tool use (file reads, shell commands) |
+| `OPENAI_BASE_URL is deprecated` warning | Codex v0.115+ prefers config.toml | Harmless — proxy still works via env var |
+
+## Notes
+
+- Codex with OAuth uses WebSocket first, then falls back to HTTP/SSE when proxied.
+  The fallback is transparent — traces capture the HTTP/SSE path correctly.
+- Each `codex exec` session also calls `GET /v1/models` for model discovery.
+- The `--dangerously-bypass-approvals-and-sandbox` flag is required for non-interactive exec.

claw_tap-0.0.5/.agents/skills/demo-video/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: demo-video
+description: Generate demo assets (GIF/MP4) from real tmux E2E runs and viewer screenshots using asciinema and Playwright
+user_invocable: true
+---
+
+# Skill: Demo Video Generation
+
+Generate demo assets from a real tmux E2E run and viewer screenshots.
+
+## Proven Workflow
+
+### 1) Record terminal session in tmux with asciinema
+
+```bash
+tmux new-session -d -s demo -x 160 -y 46
+tmux send-keys -t demo "asciinema rec /tmp/claude-tap-recordings/demo.cast" Enter
+tmux send-keys -t demo "cd /path/to/claude-tap && scripts/run_real_e2e_tmux.sh" Enter
+# ... wait until run finishes ...
+tmux send-keys -t demo "exit" Enter
+```
+
+Notes:
+
+- `Enter` is the submit key for Claude Code TUI in tmux.
+- Use tool-triggering first prompt text so trace includes `tool_use`.
+
+### 2) Convert `.cast` to GIF with `agg`
+
+```bash
+agg /tmp/claude-tap-recordings/demo.cast /tmp/claude-tap-recordings/demo.gif
+```
+
+### 3) Convert GIF to MP4 with ffmpeg
+
+```bash
+ffmpeg -y -i /tmp/claude-tap-recordings/demo.gif -movflags +faststart -pix_fmt yuv420p docs/demo.mp4
+```
+
+## Browser Screenshots (HTML Viewer)
+
+Use Playwright CDP to attach to a running Chrome/Chromium instance on port `9222`.
+
+```python
+browser = playwright.chromium.connect_over_cdp("http://127.0.0.1:9222")
+page = browser.contexts[0].pages[0]
+```
+
+### Reliable UI interactions
+
+- Click entries by visible text content, for example:
+
+```python
+page.query_selector('text="轮次 22"').click()
+```
+
+- Open diff view by clicking button text:
+
+```python
+page.query_selector('text="对比上次"').click()
+```
+
+- For SPA/overflow layouts, scroll actual scrollable containers (not `window`):
+
+```python
+page.evaluate("""
+() => {
+  for (const el of document.querySelectorAll('*')) {
+    if (el.scrollHeight > el.clientHeight) {
+      el.scrollTop += 300;
+    }
+  }
+}
+""")
+```
+
+## Output Targets
+
+- `docs/demo.gif`
+- `docs/demo.mp4`
+- Optional localized variants (`docs/demo_zh.gif`, `docs/demo_zh.mp4`)
+
+## Avoid
+
+- Do not reference non-existent scripts such as `cast_to_gif_ultra.py` or `make_final_demo_v2.py`.
+- Do not hardcode selectors like `.detail` unless verified in the current viewer build.

claw_tap-0.0.5/.agents/skills/e2e-test/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: e2e-test
+description: Run claude-tap end-to-end tests with pytest
+user_invocable: true
+---
+
+# claude-tap E2E Test
+
+Run this skill after modifying core logic in claude-tap, especially:
+- Proxy handler / SSE reassembly (`__init__.py`)
+- TraceWriter (JSONL writing, flush behavior)
+- HTML viewer generation (`viewer.html`, `_generate_html_viewer`)
+- LiveViewerServer (SSE streaming)
+- Signal handling / graceful shutdown
+- Smart update check / trace cleanup
+
+## Steps
+
+1. Run the full test suite:
+
+```bash
+uv run pytest tests/test_e2e.py -v --timeout=120
+```
+
+Or run a single test:
+
+```bash
+uv run pytest tests/test_e2e.py::test_e2e -v           # Full E2E pipeline
+uv run pytest tests/test_e2e.py::test_trace_cleanup -v  # Trace cleanup
+uv run pytest tests/test_e2e.py::test_version_check_with_fake_pypi -v  # Update check
+```
+
+2. Read the output. Each test prints `PASSED` or `FAILED`.
+
+3. If tests fail, check:
+   - **test_e2e fails**: Core proxy pipeline issue. Check `proxy_handler`, `_handle_streaming`, `TraceWriter.write`.
+   - **test_trace_cleanup fails**: Session retention issue. Check `_cleanup_traces`, `SessionIndex.delete_oldest_sessions`, and `sessions/` layout.
+   - **test_version_check_* fails**: PyPI check logic. Check `_check_pypi_version`, `CLAUDE_TAP_PYPI_URL` env var.
+   - **test_live_viewer_* fails**: Viewer HTML issues. Check `viewer.html` for `preserveDetail` chain, `updateNavButtons`.
+   - **Timeout**: May be a network/port issue, not a claude-tap bug.

claw_tap-0.0.5/.agents/skills/js-in-html-testing/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: js-in-html-testing
+description: Test JS logic embedded in HTML using two-layer strategy - Python unit tests + Playwright browser integration tests
+user_invocable: false
+---
+
+# JS-in-HTML Two-Layer Testing Strategy
+
+For JavaScript logic embedded in HTML files (e.g., diff navigation in viewer.html), use a two-layer testing approach.
+
+## Layer 1: Python Unit Tests (fast algorithm verification)
+
+Replicate core JS algorithms in Python and verify correctness via pytest.
+
+Best for: pure computation logic, state decisions, matching algorithms — anything that doesn't depend on the DOM.
+
+**Example**: `tests/test_diff_matching.py`
+
+```python
+# Replicate JS findPrevSameModel / findNextSameModel
+def find_diff_parent_by_prefix(entries, idx):
+    ...
+
+def find_next_by_prefix(entries, idx):
+    ...
+
+# Replicate JS updateNavButtons state computation
+def compute_nav_button_states(entries, cur_idx):
+    prev_idx = find_diff_parent_by_prefix(entries, cur_idx)
+    ...
+    return (prev_enabled, next_enabled)
+```
+
+Advantages: fast (0.02s), no browser dependency, integrates with existing pytest setup.
+
+## Layer 2: Playwright Browser Integration Tests (DOM interaction verification)
+
+Generate HTML with test data embedded, open it in real Chromium via Playwright, and verify DOM state and user interactions.
+
+Best for: button disabled states, overlay show/hide, keyboard events, click navigation, etc.
+
+**Example**: `tests/test_nav_browser.py`
+
+### Building test HTML
+
+```python
+def _build_test_html():
+    template = Path("claude_tap/viewer.html").read_text()
+    records = [json.dumps(e) for e in TEST_ENTRIES]
+    data_js = "const EMBEDDED_TRACE_DATA = [\n" + ",\n".join(records) + "\n];\n"
+    # Inject data into template
+    return template.replace(
+        "<script>\nconst $ = s =>",
+        f"<script>\n{data_js}</script>\n<script>\nconst $ = s =>",
+        1,
+    )
+```
+
+### Playwright fixture
+
+```python
+@pytest.fixture(scope="module")
+def browser_page(html_file):
+    from playwright.sync_api import sync_playwright
+    pw = sync_playwright().start()
+    browser = pw.chromium.launch(headless=True)
+    page = browser.new_page()
+    page.goto(f"file://{html_file}")
+    page.wait_for_selector(".sidebar-item", timeout=5000)
+    yield page
+    browser.close()
+    pw.stop()
+```
+
+### Verifying DOM state
+
+```python
+def _get_nav_state(page):
+    return page.evaluate("""() => {
+        const overlay = document.querySelector('.diff-overlay');
+        if (!overlay) return { overlayExists: false };
+        return {
+            overlayExists: true,
+            prevDisabled: overlay.querySelector('.diff-nav-prev')?.disabled,
+            nextDisabled: overlay.querySelector('.diff-nav-next')?.disabled,
+            title: overlay.querySelector('.diff-title')?.textContent,
+        };
+    }""")
+```
+
+### Simulating user interaction
+
+```python
+# Click buttons
+page.click(".diff-nav-next")
+# Keyboard navigation
+page.keyboard.press("ArrowRight")
+# Call internal JS functions
+page.evaluate("selectEntry(2)")
+page.evaluate("showDiff()")
+```
+
+## Notes
+
+- Trace data may contain `</script>` text (e.g., when Claude discusses code), which breaks `<script>` block parsing. Escape it: `line.replace("</script>", '</scr" + "ipt>')`
+- Test data must match the viewer's expected JSONL format (including `turn`, `duration_ms`, `request_id`, `request.path`, etc.)
+- Playwright requires `uv pip install playwright`
+
+## Running
+
+```bash
+# Fast unit tests
+uv run pytest tests/test_diff_matching.py -v
+
+# Browser integration tests
+uv run pytest tests/test_nav_browser.py -v
+
+# All (excluding slow e2e)
+uv run pytest tests/ --ignore=tests/test_e2e.py -v
+```

claw_tap-0.0.5/.agents/skills/legibility-check/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: legibility-check
+description: Validate docs structure, standards freshness, manifest paths, and plan state. Run this after modifying any file under docs/standards/, docs/plans/, docs/architecture/, or AGENTS.md — it catches stale metadata, broken manifest paths, and plan state drift before CI does.
+user_invocable: true
+---
+
+# Legibility Check
+
+Run deterministic legibility checks that mirror what CI enforces via `.github/workflows/legibility.yml`. Catching these locally saves a round-trip to CI.
+
+## What it checks
+
+1. **Standards freshness** — every `docs/standards/*.md` must have frontmatter with `owner`, `last_reviewed` (ISO date), and `source_of_truth`. Files reviewed more than 60 days ago produce a warning.
+2. **Architecture manifest** — every path listed in `docs/architecture/manifest.yaml` under `expected_paths:` must exist in the repo.
+3. **Plan state drift** — every `docs/plans/**/*.md` must have a `status` frontmatter field (`active`, `completed`, or `cancelled`). Completed plans must not contain unchecked `- [ ]` checkboxes (outside fenced code blocks).
+
+## Run
+
+```bash
+uv run python scripts/check_legibility.py
+```
+
+Options:
+- `--freshness-days N` — change the staleness threshold (default: 60)
+- `--strict-freshness` — promote stale warnings to failures
+- `--repo-root PATH` — override repo root (default: cwd)
+
+## Fixing common failures
+
+| Failure | Fix |
+|---------|-----|
+| `missing frontmatter key 'X'` | Add the missing key to the YAML frontmatter block at the top of the file |
+| `last_reviewed must be ISO date` | Use `YYYY-MM-DD` format |
+| `last_reviewed ... is stale` | Update `last_reviewed` to today's date after reviewing the content |
+| `expected path missing: X` | Either create the file or remove the stale entry from `manifest.yaml` |
+| `status must be one of [...]` | Add `status: active` (or `completed`/`cancelled`) to plan frontmatter |
+| `completed plan still contains unchecked TODO` | Check off remaining items or change status back to `active` |
+
+## After fixing
+
+Re-run the check to confirm all issues are resolved before committing:
+
+```bash
+uv run python scripts/check_legibility.py && echo "All clear"
+```

claw_tap-0.0.5/.agents/skills/playwright-screen-recording/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: playwright-screen-recording
+description: Record browser test videos with Playwright for PR review and bug fix verification
+user_invocable: false
+---
+
+# Playwright Screen Recording for Test Verification
+
+Use Playwright's video recording to capture headless browser operations as .webm videos for PR review or bug fix verification.
+
+## Core Usage
+
+```python
+from playwright.sync_api import sync_playwright
+import tempfile
+from pathlib import Path
+
+video_dir = Path(tempfile.mkdtemp())
+
+with sync_playwright() as pw:
+    browser = pw.chromium.launch(headless=True)
+    context = browser.new_context(
+        viewport={"width": 1400, "height": 900},
+        record_video_dir=str(video_dir),
+        record_video_size={"width": 1400, "height": 900},
+    )
+    page = context.new_page()
+    page.goto(f"file:///path/to/test.html")
+
+    # ... perform test actions, add pauses for readability ...
+    page.wait_for_timeout(800)  # pause so viewers can see the current state
+
+    page.close()
+    context.close()  # video is finalized after context.close()
+    browser.close()
+
+# Retrieve the recorded video
+videos = list(video_dir.glob("*.webm"))
+if videos:
+    videos[0].rename("demo.webm")
+```
+
+## Use Cases
+
+- **Bug fix verification**: record before/after comparisons showing button state changes, UI behavior differences
+- **PR Review**: attach .webm video so reviewers can visually understand the change
+- **Regression test evidence**: record critical interaction paths as visual proof of passing tests
+
+## Recording Tips
+
+### Add pauses between actions
+
+```python
+page.click(".some-button")
+page.wait_for_timeout(800)   # let viewers see the click effect
+
+page.keyboard.press("ArrowRight")
+page.wait_for_timeout(600)   # let viewers see the navigation result
+```
+
+### Combine assertions with terminal logging
+
+```python
+state = get_nav_state(page)
+print(f"[1] Title: {state['title']}")
+print(f"    prev disabled: {state['prevDisabled']}  (expected: True)")
+assert state["prevDisabled"] is True
+print("    PASS")
+```
+
+Terminal output paired with the recorded video provides dual verification.
+
+### Prefer real data
+
+Use existing real trace data from the project rather than synthetic data for more convincing demos:
+
+```python
+# Build test HTML from a real trace file
+records = []
+with open(".traces/trace_xxx.jsonl") as f:
+    for line in f:
+        # Escape </script> to prevent breaking the HTML script block
+        records.append(line.strip().replace("</script>", '</scr" + "ipt>'))
+```
+
+## Notes
+
+- Video format is `.webm` (VP8 codec), supported by most players and browsers
+- Each `page` produces a separate video file
+- `record_video_size` controls video resolution — keep it consistent with `viewport`
+- Recording works in headless mode, no display required
+- Video files are typically a few hundred KB, suitable for attaching to PRs or chat

claw_tap-0.0.5/.agents/skills/pr-preflight/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: pr-preflight
+description: Full pre-PR merge-readiness check. Run this before opening or merging a pull request — it validates local gates (lint, format, tests), CI status, screenshot evidence, and PR metadata in one pass. Also useful for reviewing an existing PR's readiness.
+user_invocable: true
+---
+
+# PR Preflight
+
+One-command merge-readiness check that combines local gates, CI status, and PR policy checks. Mirrors what reviewers look for so issues are caught before review, not during.
+
+## Check an existing PR
+
+```bash
+scripts/check_pr.sh <pr_number>
+```
+
+This runs:
+1. **PR metadata** — fetches title, state, draft status, merge state, branch info
+2. **CI checks** — counts pass/fail/pending GitHub Actions checks
+3. **Local gates** — runs lint, format, and tests locally:
+   - `uv run ruff check .`
+   - `uv run ruff format --check .`
+   - `uv run pytest tests/ -x --timeout=60`
+4. **Screenshot evidence** — scans PR body for image links (required by project policy)
+5. **Verdict** — `READY` or `NOT_READY` with specific reasons
+
+### Options
+
+| Flag | Purpose |
+|------|---------|
+| `--repo OWNER/REPO` | Override repository (default: auto-detect via `gh`) |
+| `--no-tests` | Skip local test gates (useful when you just want CI + metadata check) |
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All checks passed — ready to merge |
+| 1 | Script error (missing tool, network failure) |
+| 2 | Not ready — at least one check failed |
+
+## Run local gates only (no PR needed)
+
+If you haven't opened a PR yet and just want to validate locally:
+
+```bash
+uv run ruff check . && uv run ruff format --check . && uv run pytest tests/ -x --timeout=60
+```
+
+Or use the pre-commit hook (auto-runs lint on commit):
+
+```bash
+git config core.hooksPath .githooks
+```
+
+## What blocks merge
+
+The script reports `NOT_READY` if any of these are true:
+- PR is not in OPEN state
+- PR is still a draft
+- Merge state is not CLEAN or HAS_HOOKS
+- Any CI check is failing
+- Any CI check is still pending
+- Local gates (lint/format/tests) fail
+- No screenshot evidence in PR body
+
+## Typical workflow
+
+```bash
+# 1. Make sure local gates pass
+uv run ruff check . && uv run ruff format --check . && uv run pytest tests/ -x --timeout=60
+
+# 2. Push and open PR
+git push origin my-branch
+gh pr create --title "feat: ..." --body "..."
+
+# 3. Wait for CI, then run full preflight
+scripts/check_pr.sh <pr_number>
+```

claw_tap-0.0.5/.agents/skills/push-release/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: push-release
+description: Push to GitHub and optionally bump version to trigger PyPI release
+user_invocable: true
+---
+
+# Push & Release
+
+Push code to GitHub. If the pending commits contain feature changes, bump the version number so CI auto-publishes to PyPI.
+
+## Workflow
+
+1. **Check working tree**: Ensure no uncommitted changes (prompt user to commit first if dirty).
+
+2. **Determine whether a version bump is needed**:
+   - Read current version from `pyproject.toml`
+   - Run `git log origin/main..HEAD --oneline` to inspect pending commits
+   - If commits include feature changes (feat/fix/refactor, not purely docs/chore/test), a bump is needed
+   - If only docs, tests, or CI changes, skip the bump
+
+3. **If bump is needed**:
+   - Choose bump level based on change type:
+     - **patch** (0.1.4 → 0.1.5): bug fixes, minor improvements
+     - **minor** (0.1.4 → 0.2.0): new features
+     - **major** (0.1.4 → 1.0.0): breaking changes
+   - Update the `version` field in `pyproject.toml`
+   - Update `__version__` in `claude_tap/__init__.py`
+   - `git commit --amend` to fold the version bump into the last commit (avoids extra commits)
+
+4. **Push**:
+   ```bash
+   git push origin main
+   ```
+
+5. **Confirm CI status**:
+   - Inform the user that CI will automatically: lint → test → auto-tag → PyPI publish
+   - Provide the GitHub Actions link: https://github.com/liaohch3/claude-tap/actions
+
+## Important: Version Bump = PyPI Release
+
+The CI pipeline works as follows: push to main → auto-tag (only if version changed) → PyPI publish (triggered by new tag).
+
+**A version bump is the ONLY way to trigger a new PyPI release.** If you push without bumping the version, CI will skip tagging and nothing gets published. So whenever commits include meaningful code changes (features, fixes, improvements), you MUST bump the version before pushing.
+
+- Version numbers in `pyproject.toml` and `claude_tap/__init__.py` must stay in sync
+- Only skip the bump for pure docs/test/CI changes that don't affect the published package