test: add QA regression test for PR #9430

- Enforce requestTimeoutMs via Gemini SDK requestOptions
- Add 100MB video size check before base64 encoding
- Sanitize screenshot filenames to prevent path traversal
- Sort video files by mtime for reliable rename
- Validate --mode arg against allowed values
- Add Content-Length pre-check in downloadMedia
- Add GitHub domain allowlist for media downloads (SSRF mitigation)
- Add contents:write permission and git config for report job
- Update Node.js requirement in SKILL.md from 18+ to 22+

.claude/skills/comfy-qa/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: comfy-qa
+description: 'Comprehensive QA of ComfyUI frontend. Navigates all routes, tests all interactive features using playwright-cli, generates a report, and submits a draft PR. Works in CI and local environments, cross-platform.'
+---
+
+# ComfyUI Frontend QA Skill
+
+Perform comprehensive quality assurance of the ComfyUI frontend application by navigating all routes, clicking interactive elements, and testing features. Generate a structured report and submit it as a draft PR.
+
+## Prerequisites
+
+- Node.js 22+
+- `pnpm` package manager
+- `gh` CLI (authenticated)
+- `playwright-cli` (browser automation): `npm install -g @playwright/cli@latest`
+
+## Step 1: Environment Detection & Setup
+
+Detect the runtime environment and ensure the app is accessible.
+
+### CI Environment
+
+If `CI=true` is set:
+
+1. The ComfyUI backend is pre-configured in the CI container (`ghcr.io/comfy-org/comfyui-ci-container`)
+2. Frontend dist is already built and served by the backend
+3. Server runs at `http://127.0.0.1:8188`
+4. Skip user prompts — run fully automated
+
+### Local Environment
+
+If `CI` is not set:
+
+1. **Ask the user**: "Is a ComfyUI server already running? If so, what URL? (default: http://127.0.0.1:8188)"
+   - If yes: use the provided URL
+   - If no: offer to start one:
+
+     ```bash
+     # Option A: Use existing ComfyUI installation
+     # Ask for the path to ComfyUI, then:
+     cd <comfyui_path>
+     python main.py --cpu --multi-user --front-end-root <frontend_dist_path> &
+
+     # Option B: Build frontend and use preview server (no backend features)
+     pnpm build && pnpm preview &
+     ```
+
+2. Wait for server readiness by polling the URL (retry with 2s intervals, 60s timeout)
+
+### Browser Automation Setup
+
+Use **playwright-cli** for browser interaction via Bash commands:
+
+```bash
+playwright-cli open http://127.0.0.1:8188   # open browser and navigate
+playwright-cli snapshot                      # capture snapshot with element refs
+playwright-cli click e1                      # click by element ref from snapshot
+playwright-cli press Tab                     # keyboard shortcuts
+playwright-cli screenshot --filename=f.png  # save screenshot
+```
+
+playwright-cli is headless by default (CI-friendly). Each command outputs the current page snapshot with element references (`e1`, `e2`, …) that you use for subsequent `click`, `fill`, `hover` commands. Always run `snapshot` before interacting to get fresh refs.
+
+For local dev servers behind proxies, adjust the URL accordingly (e.g., `https://[port].stukivx.xyz` pattern if configured).
+
+## Step 2: QA Test Plan
+
+Navigate to the application URL and systematically test each area below. For each test, record:
+
+- **Status**: pass / fail / skip (with reason)
+- **Notes**: any issues, unexpected behavior, or visual glitches
+- **Screenshots**: take screenshots of failures or notable states
+
+### 2.1 Application Load & Routes
+
+| Test              | Steps                                                        |
+| ----------------- | ------------------------------------------------------------ |
+| Root route loads  | Navigate to `/` — GraphView should render with canvas        |
+| User select route | Navigate to `/user-select` — user selection UI should appear |
+| Default redirect  | If multi-user mode, `/` redirects to `/user-select` first    |
+| 404 handling      | Navigate to `/nonexistent` — should handle gracefully        |
+
+### 2.2 Canvas & Graph View
+
+| Test                      | Steps                                                          |
+| ------------------------- | -------------------------------------------------------------- |
+| Canvas renders            | The LiteGraph canvas is visible and interactive                |
+| Pan canvas                | Click and drag on empty canvas area                            |
+| Zoom in/out               | Use scroll wheel or Alt+=/Alt+-                                |
+| Fit view                  | Press `.` key — canvas fits to content                         |
+| Add node via double-click | Double-click canvas to open search, type "KSampler", select it |
+| Add node via search       | Open search box, find and add a node                           |
+| Delete node               | Select a node, press Delete key                                |
+| Connect nodes             | Drag from output slot to input slot                            |
+| Disconnect nodes          | Right-click a link and remove, or drag from connected slot     |
+| Multi-select              | Shift+click or drag-select multiple nodes                      |
+| Copy/Paste                | Select nodes, Ctrl+C then Ctrl+V                               |
+| Undo/Redo                 | Make changes, Ctrl+Z to undo, Ctrl+Y to redo                   |
+| Node context menu         | Right-click a node — menu appears with all expected options    |
+| Canvas context menu       | Right-click empty canvas — menu appears                        |
+
+### 2.3 Node Operations
+
+| Test                | Steps                                                      |
+| ------------------- | ---------------------------------------------------------- |
+| Bypass node         | Select node, Ctrl+B — node shows bypass state              |
+| Mute node           | Select node, Ctrl+M — node shows muted state               |
+| Collapse node       | Select node, Alt+C — node collapses                        |
+| Pin node            | Select node, press P — node becomes pinned                 |
+| Rename node         | Double-click node title — edit mode activates              |
+| Node color          | Right-click > Color — color picker works                   |
+| Group nodes         | Select multiple nodes, Ctrl+G — group created              |
+| Ungroup             | Right-click group > Ungroup                                |
+| Widget interactions | Toggle checkboxes, adjust sliders, type in text fields     |
+| Combo widget        | Click dropdown widgets — options appear and are selectable |
+
+### 2.4 Sidebar Tabs
+
+| Test                   | Steps                                                  |
+| ---------------------- | ------------------------------------------------------ |
+| Workflows tab          | Press W — workflows sidebar opens with saved workflows |
+| Node Library tab       | Press N — node library opens with categories           |
+| Model Library tab      | Press M — model library opens                          |
+| Assets tab             | Press A — assets browser opens                         |
+| Tab toggle             | Press same key again — sidebar closes                  |
+| Search in sidebar      | Type in search box — results filter                    |
+| Drag node from library | Drag a node from library onto canvas                   |
+
+### 2.5 Topbar & Workflow Tabs
+
+| Test                 | Steps                                                  |
+| -------------------- | ------------------------------------------------------ |
+| Workflow tab display | Current workflow name shown in tab bar                 |
+| New workflow         | Ctrl+N — new blank workflow created                    |
+| Rename workflow      | Double-click workflow tab                              |
+| Tab context menu     | Right-click workflow tab — menu with Close/Rename/etc. |
+| Multiple tabs        | Open multiple workflows, switch between them           |
+| Queue button         | Click Queue/Run button — prompt queues                 |
+| Batch count          | Click batch count editor, change value                 |
+| Menu hamburger       | Click hamburger menu — options appear                  |
+
+### 2.6 Settings Dialog
+
+| Test             | Steps                                                |
+| ---------------- | ---------------------------------------------------- |
+| Open settings    | Press Ctrl+, or click settings button                |
+| Settings tabs    | Navigate through all setting categories              |
+| Change a setting | Toggle a boolean setting — it persists after closing |
+| Search settings  | Type in settings search box — results filter         |
+| Keybindings tab  | Navigate to keybindings panel                        |
+| About tab        | Navigate to about panel — version info shown         |
+| Close settings   | Press Escape or click close button                   |
+
+### 2.7 Bottom Panel
+
+| Test                | Steps                                  |
+| ------------------- | -------------------------------------- |
+| Toggle panel        | Press Ctrl+` — bottom panel opens      |
+| Logs tab            | Logs/terminal tab shows server output  |
+| Shortcuts tab       | Shortcuts reference is displayed       |
+| Keybindings display | Press Ctrl+Shift+K — keybindings panel |
+
+### 2.8 Execution & Queue
+
+| Test           | Steps                                                 |
+| -------------- | ----------------------------------------------------- |
+| Queue prompt   | Load default workflow, click Queue — execution starts |
+| Queue progress | Progress indicator shows during execution             |
+| Interrupt      | Press Ctrl+Alt+Enter during execution — interrupts    |
+| Job history    | Open job history sidebar — past executions listed     |
+| Clear history  | Clear execution history via menu                      |
+
+### 2.9 Workflow File Operations
+
+| Test            | Steps                                             |
+| --------------- | ------------------------------------------------- |
+| Save workflow   | Ctrl+S — workflow saves (check for prompt if new) |
+| Open workflow   | Ctrl+O — file picker or workflow browser opens    |
+| Export JSON     | Menu > Export — workflow JSON downloads           |
+| Import workflow | Drag a .json workflow file onto canvas            |
+| Load default    | Menu > Load Default — default workflow loads      |
+| Clear workflow  | Menu > Clear — canvas clears (after confirmation) |
+
+### 2.10 Advanced Features
+
+| Test            | Steps                                             |
+| --------------- | ------------------------------------------------- |
+| Minimap         | Alt+M — minimap toggle                            |
+| Focus mode      | Toggle focus mode                                 |
+| Canvas lock     | Press H to lock, V to unlock                      |
+| Link visibility | Ctrl+Shift+L — toggle links                       |
+| Subgraph        | Select nodes > Ctrl+Shift+E — convert to subgraph |
+
+### 2.11 Error Handling
+
+| Test                  | Steps                                        |
+| --------------------- | -------------------------------------------- |
+| Missing nodes dialog  | Load workflow with non-existent node types   |
+| Missing models dialog | Trigger missing model warning                |
+| Network error         | Disconnect backend, verify graceful handling |
+| Invalid workflow      | Try loading malformed JSON                   |
+
+### 2.12 Responsive & Accessibility
+
+| Test                | Steps                                 |
+| ------------------- | ------------------------------------- |
+| Window resize       | Resize browser window — layout adapts |
+| Keyboard navigation | Tab through interactive elements      |
+| Sidebar resize      | Drag sidebar edge to resize           |
+
+## Step 3: Generate Report
+
+After completing all tests, generate a markdown report file.
+
+### Report Location
+
+```
+docs/qa/YYYY-MM-DD-NNN-report.md
+```
+
+Where:
+
+- `YYYY-MM-DD` is today's date
+- `NNN` is a zero-padded increment index (001, 002, etc.)
+
+To determine the increment, check existing files:
+
+```bash
+ls docs/qa/ | grep "$(date +%Y-%m-%d)" | wc -l
+```
+
+### Report Template
+
+```markdown
+# QA Report: ComfyUI Frontend
+
+**Date**: YYYY-MM-DD
+**Environment**: CI / Local (OS, Browser)
+**Frontend Version**: (git sha or version)
+**Agent**: Claude / Codex / Other
+**Server URL**: http://...
+
+## Summary
+
+| Category        | Pass | Fail | Skip | Total |
+| --------------- | ---- | ---- | ---- | ----- |
+| Routes & Load   |      |      |      |       |
+| Canvas          |      |      |      |       |
+| Node Operations |      |      |      |       |
+| Sidebar         |      |      |      |       |
+| Topbar          |      |      |      |       |
+| Settings        |      |      |      |       |
+| Bottom Panel    |      |      |      |       |
+| Execution       |      |      |      |       |
+| File Operations |      |      |      |       |
+| Advanced        |      |      |      |       |
+| Error Handling  |      |      |      |       |
+| Responsive      |      |      |      |       |
+| **Total**       |      |      |      |       |
+
+## Results
+
+### Routes & Load
+
+- [x] Root route loads — pass
+- [ ] ...
+
+### Canvas & Graph View
+
+- [x] Canvas renders — pass
+- [ ] ...
+
+(repeat for each category)
+
+## Issues Found
+
+### Issue 1: [Title]
+
+- **Severity**: critical / major / minor / cosmetic
+- **Steps to reproduce**: ...
+- **Expected**: ...
+- **Actual**: ...
+- **Screenshot**: (if available)
+
+## Notes
+
+Any additional observations, performance notes, or suggestions.
+```
+
+## Step 4: Commit and Push Report
+
+### In CI (when `CI=true`)
+
+Save the report directly to `$QA_ARTIFACTS` (the CI workflow uploads this as
+an artifact and posts results as a PR comment). Do **not** commit, push, or
+create a new PR.
+
+### Local / interactive use
+
+When running locally, create a draft PR after committing:
+
+```bash
+# Ensure on a feature branch
+BRANCH_NAME="qa/$(date +%Y-%m-%d)-$(git rev-parse --short HEAD)"
+git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+
+git add docs/qa/
+git commit -m "docs: add QA report $(date +%Y-%m-%d)
+
+Automated QA report covering all frontend routes and features."
+git push -u origin "$BRANCH_NAME"
+
+# Create draft PR assigned to comfy-pr-bot
+gh pr create \
+  --draft \
+  --title "QA Report: $(date +%Y-%m-%d)" \
+  --body "## QA Report
+
+Automated frontend QA run covering all routes and interactive features.
+
+See \`docs/qa/\` for the full report.
+
+/cc @comfy-pr-bot" \
+  --assignee comfy-pr-bot
+```
+
+## Execution Notes
+
+### Cross-Platform Considerations
+
+- **Windows**: Use `pwsh` or `cmd` equivalents for shell commands. `gh` CLI works on all platforms.
+- **macOS**: Keyboard shortcuts use Cmd instead of Ctrl in the actual app, but Playwright sends OS-appropriate keys.
+- **Linux**: Primary CI platform. Screenshot baselines are Linux-only.
+
+### Agent Compatibility
+
+This skill uses **playwright-cli** (`@playwright/cli`) — a token-efficient CLI designed for coding agents. Install it once with `npm install -g @playwright/cli@latest`, then use `Bash` to run commands.
+
+The key operations and their playwright-cli equivalents:
+
+| Action           | Command                                  |
+| ---------------- | ---------------------------------------- |
+| Navigate to URL  | `playwright-cli goto <url>`              |
+| Get element refs | `playwright-cli snapshot`                |
+| Click element    | `playwright-cli click <ref>`             |
+| Type text        | `playwright-cli fill <ref> <text>`       |
+| Press shortcut   | `playwright-cli press <key>`             |
+| Take screenshot  | `playwright-cli screenshot --filename=f` |
+| Hover element    | `playwright-cli hover <ref>`             |
+| Select dropdown  | `playwright-cli select <ref> <value>`    |
+
+Snapshots return element references (`e1`, `e2`, …). Always run `snapshot` after navigation or major interactions to refresh refs before acting.
+
+### Tips for Reliable QA
+
+1. **Wait for page stability** before interacting — check that elements are visible and enabled
+2. **Take a snapshot after each major navigation** to verify state
+3. **Don't use fixed timeouts** — poll for expected conditions
+4. **Record the full page snapshot** at the start for baseline comparison
+5. **If a test fails**, document it and continue — don't abort the entire QA run
+6. **Group related tests** — complete one category before moving to the next

.github/actions/setup-comfyui-server/action.yaml

@@ -44,12 +44,17 @@ runs:
         python -m pip install --upgrade pip
         pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
         pip install -r requirements.txt
-        pip install wait-for-it
 
     - name: Start ComfyUI server
       if: ${{ inputs.launch_server == 'true' }}
       shell: bash
       working-directory: ComfyUI
+      env:
+        EXTRA_SERVER_PARAMS: ${{ inputs.extra_server_params }}
       run: |
-        python main.py --cpu --multi-user --front-end-root ../dist ${{ inputs.extra_server_params }} &
-        wait-for-it --service 127.0.0.1:8188 -t 600
+        python main.py --cpu --multi-user --front-end-root ../dist $EXTRA_SERVER_PARAMS &
+        for i in $(seq 1 300); do
+          curl -sf http://127.0.0.1:8188/api/system_stats >/dev/null 2>&1 && echo "Server ready" && exit 0
+          sleep 2
+        done
+        echo "::error::ComfyUI server did not start within 600s" && exit 1

.github/workflows/pr-report.yaml

@@ -0,0 +1,233 @@
+name: 'PR: Unified Report'
+
+on:
+  workflow_run:
+    workflows: ['CI: Size Data', 'CI: Performance Report']
+    types:
+      - completed
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  actions: read
+
+concurrency:
+  group: pr-report-${{ github.event.workflow_run.head_sha }}
+  cancel-in-progress: true
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    if: >
+      github.repository == 'Comfy-Org/ComfyUI_frontend' &&
+      github.event.workflow_run.event == 'pull_request'
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup frontend
+        uses: ./.github/actions/setup-frontend
+
+      - name: Resolve PR from workflow_run context
+        id: pr-meta
+        uses: actions/github-script@v8
+        with:
+          script: |
+            let pr = context.payload.workflow_run.pull_requests?.[0];
+            if (!pr) {
+              const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                commit_sha: context.payload.workflow_run.head_sha,
+              });
+              pr = prs.find(p => p.state === 'open');
+            }
+
+            if (!pr) {
+              core.info('No open PR found for this workflow run — skipping.');
+              core.setOutput('skip', 'true');
+              return;
+            }
+
+            // Verify the workflow_run head SHA matches the current PR head
+            const { data: livePr } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pr.number,
+            });
+
+            if (livePr.head.sha !== context.payload.workflow_run.head_sha) {
+              core.info(`Stale run: workflow SHA ${context.payload.workflow_run.head_sha} != PR head ${livePr.head.sha}`);
+              core.setOutput('skip', 'true');
+              return;
+            }
+
+            core.setOutput('skip', 'false');
+            core.setOutput('number', String(pr.number));
+            core.setOutput('base', livePr.base.ref);
+            core.setOutput('head-sha', livePr.head.sha);
+
+      - name: Find size workflow run for this commit
+        if: steps.pr-meta.outputs.skip != 'true'
+        id: find-size
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const headSha = '${{ steps.pr-meta.outputs.head-sha }}';
+            const { data: runs } = await github.rest.actions.listWorkflowRuns({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'ci-size-data.yaml',
+              head_sha: headSha,
+              per_page: 1,
+            });
+
+            const run = runs.workflow_runs[0];
+            if (!run) {
+              core.setOutput('status', 'pending');
+              return;
+            }
+
+            if (run.status !== 'completed') {
+              core.setOutput('status', 'pending');
+              return;
+            }
+
+            if (run.conclusion !== 'success') {
+              core.setOutput('status', 'failed');
+              return;
+            }
+
+            core.setOutput('status', 'ready');
+            core.setOutput('run-id', String(run.id));
+
+      - name: Find perf workflow run for this commit
+        if: steps.pr-meta.outputs.skip != 'true'
+        id: find-perf
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const headSha = '${{ steps.pr-meta.outputs.head-sha }}';
+            const { data: runs } = await github.rest.actions.listWorkflowRuns({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'ci-perf-report.yaml',
+              head_sha: headSha,
+              per_page: 1,
+            });
+
+            const run = runs.workflow_runs[0];
+            if (!run) {
+              core.setOutput('status', 'pending');
+              return;
+            }
+
+            if (run.status !== 'completed') {
+              core.setOutput('status', 'pending');
+              return;
+            }
+
+            if (run.conclusion !== 'success') {
+              core.setOutput('status', 'failed');
+              return;
+            }
+
+            core.setOutput('status', 'ready');
+            core.setOutput('run-id', String(run.id));
+
+      - name: Download size data (current)
+        if: steps.pr-meta.outputs.skip != 'true' && steps.find-size.outputs.status == 'ready'
+        uses: dawidd6/action-download-artifact@0bd50d53a6d7fb5cb921e607957e9cc12b4ce392 # v12
+        with:
+          name: size-data
+          run_id: ${{ steps.find-size.outputs.run-id }}
+          path: temp/size
+
+      - name: Download size baseline
+        if: steps.pr-meta.outputs.skip != 'true' && steps.find-size.outputs.status == 'ready'
+        uses: dawidd6/action-download-artifact@0bd50d53a6d7fb5cb921e607957e9cc12b4ce392 # v12
+        with:
+          branch: ${{ steps.pr-meta.outputs.base }}
+          workflow: ci-size-data.yaml
+          event: push
+          name: size-data
+          path: temp/size-prev
+          if_no_artifact_found: warn
+
+      - name: Download perf metrics (current)
+        if: steps.pr-meta.outputs.skip != 'true' && steps.find-perf.outputs.status == 'ready'
+        uses: dawidd6/action-download-artifact@0bd50d53a6d7fb5cb921e607957e9cc12b4ce392 # v12
+        with:
+          name: perf-metrics
+          run_id: ${{ steps.find-perf.outputs.run-id }}
+          path: test-results/
+
+      - name: Download perf baseline
+        if: steps.pr-meta.outputs.skip != 'true' && steps.find-perf.outputs.status == 'ready'
+        uses: dawidd6/action-download-artifact@0bd50d53a6d7fb5cb921e607957e9cc12b4ce392 # v12
+        with:
+          branch: ${{ steps.pr-meta.outputs.base }}
+          workflow: ci-perf-report.yaml
+          event: push
+          name: perf-metrics
+          path: temp/perf-baseline/
+          if_no_artifact_found: warn
+
+      - name: Download perf history from perf-data branch
+        if: steps.pr-meta.outputs.skip != 'true' && steps.find-perf.outputs.status == 'ready'
+        continue-on-error: true
+        run: |
+          if git ls-remote --exit-code origin perf-data >/dev/null 2>&1; then
+            git fetch origin perf-data --depth=1
+            mkdir -p temp/perf-history
+            for file in $(git ls-tree --name-only origin/perf-data baselines/ 2>/dev/null | sort -r | head -10); do
+              git show "origin/perf-data:${file}" > "temp/perf-history/$(basename "$file")" 2>/dev/null || true
+            done
+            echo "Loaded $(ls temp/perf-history/*.json 2>/dev/null | wc -l) historical baselines"
+          fi
+
+      - name: Generate unified report
+        if: steps.pr-meta.outputs.skip != 'true'
+        run: >
+          node scripts/unified-report.js
+          --size-status=${{ steps.find-size.outputs.status }}
+          --perf-status=${{ steps.find-perf.outputs.status }}
+          > pr-report.md
+
+      - name: Remove legacy separate comments
+        if: steps.pr-meta.outputs.skip != 'true'
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const prNumber = Number('${{ steps.pr-meta.outputs.number }}');
+            const legacyMarkers = [
+              '<!-- COMFYUI_FRONTEND_SIZE -->',
+              '<!-- COMFYUI_FRONTEND_PERF -->',
+            ];
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+              per_page: 100,
+            });
+
+            for (const comment of comments) {
+              if (legacyMarkers.some(m => comment.body?.includes(m))) {
+                await github.rest.issues.deleteComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: comment.id,
+                });
+                core.info(`Deleted legacy comment ${comment.id}`);
+              }
+            }
+
+      - name: Post PR comment
+        if: steps.pr-meta.outputs.skip != 'true'
+        uses: ./.github/actions/post-pr-report-comment
+        with:
+          pr-number: ${{ steps.pr-meta.outputs.number }}
+          report-file: ./pr-report.md
+          comment-marker: '<!-- COMFYUI_FRONTEND_PR_REPORT -->'
+          token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -99,4 +99,6 @@ vitest.config.*.timestamp*
 # Weekly docs check output
 /output.txt
 
-.amp
+.amp
+.playwright-cli/
+.playwright/

browser_tests/tests/qa-pr9430.spec.ts

@@ -0,0 +1,71 @@
+import { expect } from '@playwright/test'
+import { comfyPageFixture as test } from '../fixtures/ComfyPage'
+
+test.describe('Workflow Management UI', { tag: '@ui' }, () => {
+  test.beforeEach(async ({ comfyPage }) => {
+    // Ensure a clean state for workflows and settings
+    await comfyPage.workflow.setupWorkflowsDirectory({})
+    await comfyPage.page.goto('/')
+    await comfyPage.page.waitForLoadState('domcontentloaded')
+  })
+
+  test('Templates sidebar displays preview images for Getting Started cards', async ({
+    comfyPage
+  }) => {
+    // Open the Workflows/Templates sidebar
+    await comfyPage.menu.workflowsTab.open()
+
+    // Locate the "Getting Started" section within the templates sidebar
+    // We find the text "Getting Started" and then its parent element to scope the search for cards
+    const gettingStartedSection = comfyPage.page
+      .locator('.workflow-templates-sidebar-panel')
+      .getByText('Getting Started', { exact: true })
+      .locator('..')
+
+    // Expect the section to be visible
+    await expect(gettingStartedSection).toBeVisible()
+
+    // Take a screenshot of the first template card in the "Getting Started" section.
+    // This will visually assert if the preview image is present or if it's an empty placeholder.
+    const firstTemplateCard = gettingStartedSection
+      .locator('.workflow-template-card')
+      .first()
+    await expect(firstTemplateCard).toBeVisible()
+    await expect(firstTemplateCard).toHaveScreenshot(
+      'getting-started-template-card-with-image.png'
+    )
+
+    // Close the sidebar for cleanup
+    await comfyPage.menu.workflowsTab.close()
+  })
+
+  test('User can successfully save a workflow via the File > Save menu', async ({
+    comfyPage
+  }) => {
+    const workflowName = 'test-save-workflow-interaction'
+
+    // Load a simple workflow to have content to save.
+    // This also ensures the workflow is considered "modified" or savable.
+    await comfyPage.workflow.loadWorkflow('empty_workflow')
+
+    // Trigger the save action using the topbar helper.
+    // This helper interacts with the save dialog, types the name, and confirms.
+    await comfyPage.menu.topbar.saveWorkflow(workflowName)
+
+    // Assert that the active tab name updates to the newly saved workflow name,
+    // indicating the save operation was successful from a UI perspective.
+    await expect(comfyPage.menu.topbar.getActiveTabName()).resolves.toBe(
+      workflowName
+    )
+
+    // Verify the saved workflow appears in the Workflows sidebar.
+    await comfyPage.menu.workflowsTab.open()
+    await expect(
+      comfyPage.menu.workflowsTab.getPersistedItem(workflowName)
+    ).toBeVisible()
+    await comfyPage.menu.workflowsTab.close()
+
+    // Clean up the created workflow
+    await comfyPage.workflow.deleteWorkflow(workflowName)
+  })
+})

knip.config.ts

@@ -29,10 +29,12 @@ const config: KnipConfig = {
     },
     'packages/ingest-types': {
       project: ['src/**/*.{js,ts}'],
-      entry: ['src/index.ts']
+      entry: ['src/index.ts', 'openapi-ts.config.ts'],
+      // openapi-ts binary is provided by @hey-api/openapi-ts devDependency
+      ignoreBinaries: ['openapi-ts']
     }
   },
-  ignoreBinaries: ['python3', 'gh', 'generate'],
+  ignoreBinaries: ['python3', 'gh'],
   ignoreDependencies: [
     // Weird importmap things
     '@iconify-json/lucide',
@@ -40,9 +42,7 @@ const config: KnipConfig = {
     '@primeuix/forms',
     '@primeuix/styled',
     '@primeuix/utils',
-    '@primevue/icons',
-    // Used by lucideStrokePlugin.js (CSS @plugin)
-    '@iconify/utils'
+    '@primevue/icons'
   ],
   ignore: [
     // Auto generated API types
@@ -50,7 +50,6 @@ const config: KnipConfig = {
     'packages/registry-types/src/comfyRegistryTypes.ts',
     'packages/ingest-types/src/types.gen.ts',
     'packages/ingest-types/src/zod.gen.ts',
-    'packages/ingest-types/openapi-ts.config.ts',
     // Used by a custom node (that should move off of this)
     'src/scripts/ui/components/splitButton.ts',
     // Used by stacked PR (feat/glsl-live-preview)

package.json

@@ -39,6 +39,7 @@
     "preinstall": "pnpm dlx only-allow pnpm",
     "prepare": "husky || true && git config blame.ignoreRevsFile .git-blame-ignore-revs || true",
     "preview": "nx preview",
+    "qa:video-review": "tsx scripts/qa-video-review.ts",
     "storybook": "nx storybook",
     "storybook:desktop": "nx run @comfyorg/desktop-ui:storybook",
     "stylelint:fix": "stylelint --cache --fix '{apps,packages,src}/**/*.{css,vue}'",
@@ -120,6 +121,7 @@
   },
   "devDependencies": {
     "@eslint/js": "catalog:",
+    "@google/generative-ai": "catalog:",
     "@intlify/eslint-plugin-vue-i18n": "catalog:",
     "@lobehub/i18n-cli": "catalog:",
     "@nx/eslint": "catalog:",

pnpm-lock.yaml

@@ -18,6 +18,9 @@ catalogs:
     '@formkit/auto-animate':
       specifier: ^0.9.0
       version: 0.9.0
+    '@google/generative-ai':
+      specifier: ^0.24.1
+      version: 0.24.1
     '@iconify-json/lucide':
       specifier: ^1.1.178
       version: 1.2.79
@@ -573,6 +576,9 @@ importers:
       '@eslint/js':
         specifier: 'catalog:'
         version: 9.39.1
+      '@google/generative-ai':
+        specifier: 'catalog:'
+        version: 0.24.1
       '@intlify/eslint-plugin-vue-i18n':
         specifier: 'catalog:'
         version: 4.1.1(eslint@9.39.1(jiti@2.6.1))(jsonc-eslint-parser@2.4.0)(vue-eslint-parser@10.4.0(eslint@9.39.1(jiti@2.6.1)))(yaml-eslint-parser@1.3.0)
@@ -2210,6 +2216,10 @@ packages:
   '@formkit/auto-animate@0.9.0':
     resolution: {integrity: sha512-VhP4zEAacXS3dfTpJpJ88QdLqMTcabMg0jwpOSxZ/VzfQVfl3GkZSCZThhGC5uhq/TxPHPzW0dzr4H9Bb1OgKA==}
 
+  '@google/generative-ai@0.24.1':
+    resolution: {integrity: sha512-MqO+MLfM6kjxcKoy0p1wRzG3b4ZZXtPI+z2IE26UogS2Cm/XHO+7gGRBh6gcJsOiIVoH93UwKvW4HdgiOZCy9Q==}
+    engines: {node: '>=18.0.0'}
+
   '@grpc/grpc-js@1.9.15':
     resolution: {integrity: sha512-nqE7Hc0AzI+euzUwDAy0aY5hCp10r734gMGRdU+qOPX0XSceI2ULrcXB5U2xSc5VkWwalCj4M7GzCAygZl2KoQ==}
     engines: {node: ^8.13.0 || >=10.10.0}
@@ -8659,6 +8669,9 @@ packages:
   vue-component-type-helpers@3.2.5:
     resolution: {integrity: sha512-tkvNr+bU8+xD/onAThIe7CHFvOJ/BO6XCOrxMzeytJq40nTfpGDJuVjyCM8ccGZKfAbGk2YfuZyDMXM56qheZQ==}
 
+  vue-component-type-helpers@3.2.6:
+    resolution: {integrity: sha512-O02tnvIfOQVmnvoWwuSydwRoHjZVt8UEBR+2p4rT35p8GAy5VTlWP8o5qXfJR/GWCN0nVZoYWsVUvx2jwgdBmQ==}
+
   vue-demi@0.14.10:
     resolution: {integrity: sha512-nMZBOwuzabUO0nLgIcc6rycZEebF6eeUfaiQx9+WSk8e29IbLvPU9feI6tqW4kTo3hvoYAJkMh8n8D0fuISphg==}
     engines: {node: '>=12'}
@@ -10448,6 +10461,8 @@ snapshots:
 
   '@formkit/auto-animate@0.9.0': {}
 
+  '@google/generative-ai@0.24.1': {}
+
   '@grpc/grpc-js@1.9.15':
     dependencies:
       '@grpc/proto-loader': 0.7.13
@@ -11800,7 +11815,7 @@ snapshots:
       storybook: 10.2.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       type-fest: 2.19.0
       vue: 3.5.13(typescript@5.9.3)
-      vue-component-type-helpers: 3.2.5
+      vue-component-type-helpers: 3.2.6
 
   '@swc/helpers@0.5.17':
     dependencies:
@@ -17938,6 +17953,8 @@ snapshots:
 
   vue-component-type-helpers@3.2.5: {}
 
+  vue-component-type-helpers@3.2.6: {}
+
   vue-demi@0.14.10(vue@3.5.13(typescript@5.9.3)):
     dependencies:
       vue: 3.5.13(typescript@5.9.3)

pnpm-workspace.yaml

@@ -7,6 +7,7 @@ catalog:
   '@comfyorg/comfyui-electron-types': 0.6.2
   '@eslint/js': ^9.39.1
   '@formkit/auto-animate': ^0.9.0
+  '@google/generative-ai': ^0.24.1
   '@iconify-json/lucide': ^1.1.178
   '@iconify/json': ^2.2.380
   '@iconify/tailwind4': ^1.2.0

scripts/qa-analyze-pr.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest'
+
+import { extractMediaUrls } from './qa-analyze-pr'
+
+describe('extractMediaUrls', () => {
+  it('extracts markdown image URLs', () => {
+    const text = '![screenshot](https://example.com/image.png)'
+    expect(extractMediaUrls(text)).toEqual(['https://example.com/image.png'])
+  })
+
+  it('extracts multiple markdown images', () => {
+    const text = [
+      '![before](https://example.com/before.png)',
+      'Some text',
+      '![after](https://example.com/after.jpg)'
+    ].join('\n')
+    expect(extractMediaUrls(text)).toEqual([
+      'https://example.com/before.png',
+      'https://example.com/after.jpg'
+    ])
+  })
+
+  it('extracts raw URLs with media extensions', () => {
+    const text = 'Check this: https://cdn.example.com/demo.mp4 for details'
+    expect(extractMediaUrls(text)).toEqual(['https://cdn.example.com/demo.mp4'])
+  })
+
+  it('extracts GitHub user-attachments URLs', () => {
+    const text =
+      'https://github.com/user-attachments/assets/abc12345-6789-0def-1234-567890abcdef'
+    expect(extractMediaUrls(text)).toEqual([
+      'https://github.com/user-attachments/assets/abc12345-6789-0def-1234-567890abcdef'
+    ])
+  })
+
+  it('extracts private-user-images URLs', () => {
+    const text =
+      'https://private-user-images.githubusercontent.com/12345/abcdef-1234?jwt=token123'
+    expect(extractMediaUrls(text)).toEqual([
+      'https://private-user-images.githubusercontent.com/12345/abcdef-1234?jwt=token123'
+    ])
+  })
+
+  it('extracts URLs with query parameters', () => {
+    const text = 'https://example.com/image.png?w=800&h=600'
+    expect(extractMediaUrls(text)).toEqual([
+      'https://example.com/image.png?w=800&h=600'
+    ])
+  })
+
+  it('deduplicates URLs', () => {
+    const text = [
+      '![img](https://example.com/same.png)',
+      '![img2](https://example.com/same.png)',
+      'Also https://example.com/same.png'
+    ].join('\n')
+    expect(extractMediaUrls(text)).toEqual(['https://example.com/same.png'])
+  })
+
+  it('returns empty array for empty input', () => {
+    expect(extractMediaUrls('')).toEqual([])
+  })
+
+  it('returns empty array for text with no media URLs', () => {
+    expect(extractMediaUrls('Just some text without any URLs')).toEqual([])
+  })
+
+  it('handles mixed media types', () => {
+    const text = [
+      '![screen](https://example.com/screenshot.png)',
+      'Video: https://example.com/demo.webm',
+      '![gif](https://example.com/animation.gif)'
+    ].join('\n')
+    const urls = extractMediaUrls(text)
+    expect(urls).toContain('https://example.com/screenshot.png')
+    expect(urls).toContain('https://example.com/demo.webm')
+    expect(urls).toContain('https://example.com/animation.gif')
+  })
+
+  it('ignores non-http URLs in markdown', () => {
+    const text = '![local](./local-image.png)'
+    expect(extractMediaUrls(text)).toEqual([])
+  })
+})

scripts/qa-analyze-pr.ts

@@ -0,0 +1,764 @@
+#!/usr/bin/env tsx
+/**
+ * QA PR Analysis Script
+ *
+ * Deeply analyzes a PR using Gemini Pro to generate targeted QA guides
+ * for before/after recording sessions. Fetches PR thread, extracts media,
+ * and produces structured test plans.
+ *
+ * Usage:
+ *   pnpm exec tsx scripts/qa-analyze-pr.ts \
+ *     --pr-number 10270 \
+ *     --repo owner/repo \
+ *     --output-dir qa-guides/ \
+ *     [--model gemini-2.5-pro]
+ *
+ * Env: GEMINI_API_KEY (required)
+ */
+
+import { execSync } from 'node:child_process'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { GoogleGenerativeAI } from '@google/generative-ai'
+
+// ── Types ──
+
+interface QaGuideStep {
+  action: string
+  description: string
+  expected_before?: string
+  expected_after?: string
+}
+
+interface QaGuide {
+  summary: string
+  test_focus: string
+  prerequisites: string[]
+  steps: QaGuideStep[]
+  visual_checks: string[]
+}
+
+interface PrThread {
+  title: string
+  body: string
+  labels: string[]
+  issueComments: string[]
+  reviewComments: string[]
+  reviews: string[]
+  diff: string
+}
+
+type TargetType = 'pr' | 'issue'
+
+interface Options {
+  prNumber: string
+  repo: string
+  outputDir: string
+  model: string
+  apiKey: string
+  mediaBudgetBytes: number
+  maxVideoBytes: number
+  type: TargetType
+}
+
+// ── CLI parsing ──
+
+function parseArgs(): Options {
+  const args = process.argv.slice(2)
+  const opts: Partial<Options> = {
+    model: 'gemini-2.5-pro',
+    apiKey: process.env.GEMINI_API_KEY || '',
+    mediaBudgetBytes: 20 * 1024 * 1024,
+    maxVideoBytes: 10 * 1024 * 1024,
+    type: 'pr'
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--pr-number':
+        opts.prNumber = args[++i]
+        break
+      case '--repo':
+        opts.repo = args[++i]
+        break
+      case '--output-dir':
+        opts.outputDir = args[++i]
+        break
+      case '--model':
+        opts.model = args[++i]
+        break
+      case '--type':
+        opts.type = args[++i] as TargetType
+        break
+      case '--help':
+        console.warn(
+          'Usage: qa-analyze-pr.ts --pr-number <num> --repo <owner/repo> --output-dir <path> [--model <model>] [--type pr|issue]'
+        )
+        process.exit(0)
+    }
+  }
+
+  if (!opts.prNumber || !opts.repo || !opts.outputDir) {
+    console.error(
+      'Required: --pr-number <num> --repo <owner/repo> --output-dir <path>'
+    )
+    process.exit(1)
+  }
+
+  if (!opts.apiKey) {
+    console.error('GEMINI_API_KEY environment variable is required')
+    process.exit(1)
+  }
+
+  return opts as Options
+}
+
+// ── PR thread fetching ──
+
+function ghExec(cmd: string): string {
+  try {
+    return execSync(cmd, {
+      encoding: 'utf-8',
+      timeout: 30_000,
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim()
+  } catch (err) {
+    console.warn(`gh command failed: ${cmd}`)
+    console.warn((err as Error).message)
+    return ''
+  }
+}
+
+function fetchPrThread(prNumber: string, repo: string): PrThread {
+  console.warn('Fetching PR thread...')
+
+  const prView = ghExec(
+    `gh pr view ${prNumber} --repo ${repo} --json title,body,labels`
+  )
+  const prData = prView
+    ? JSON.parse(prView)
+    : { title: '', body: '', labels: [] }
+
+  const issueCommentsRaw = ghExec(
+    `gh api repos/${repo}/issues/${prNumber}/comments --paginate`
+  )
+  const issueComments: string[] = issueCommentsRaw
+    ? JSON.parse(issueCommentsRaw).map((c: { body: string }) => c.body)
+    : []
+
+  const reviewCommentsRaw = ghExec(
+    `gh api repos/${repo}/pulls/${prNumber}/comments --paginate`
+  )
+  const reviewComments: string[] = reviewCommentsRaw
+    ? JSON.parse(reviewCommentsRaw).map((c: { body: string }) => c.body)
+    : []
+
+  const reviewsRaw = ghExec(
+    `gh api repos/${repo}/pulls/${prNumber}/reviews --paginate`
+  )
+  const reviews: string[] = reviewsRaw
+    ? JSON.parse(reviewsRaw)
+        .filter((r: { body: string }) => r.body)
+        .map((r: { body: string }) => r.body)
+    : []
+
+  const diff = ghExec(`gh pr diff ${prNumber} --repo ${repo}`)
+
+  console.warn(
+    `PR #${prNumber}: "${prData.title}" | ` +
+      `${issueComments.length} issue comments, ` +
+      `${reviewComments.length} review comments, ` +
+      `${reviews.length} reviews, ` +
+      `diff: ${diff.length} chars`
+  )
+
+  return {
+    title: prData.title || '',
+    body: prData.body || '',
+    labels: (prData.labels || []).map((l: { name: string }) => l.name),
+    issueComments,
+    reviewComments,
+    reviews,
+    diff
+  }
+}
+
+interface IssueThread {
+  title: string
+  body: string
+  labels: string[]
+  comments: string[]
+}
+
+function fetchIssueThread(issueNumber: string, repo: string): IssueThread {
+  console.warn('Fetching issue thread...')
+
+  const issueView = ghExec(
+    `gh issue view ${issueNumber} --repo ${repo} --json title,body,labels`
+  )
+  const issueData = issueView
+    ? JSON.parse(issueView)
+    : { title: '', body: '', labels: [] }
+
+  const commentsRaw = ghExec(
+    `gh api repos/${repo}/issues/${issueNumber}/comments --paginate`
+  )
+  const comments: string[] = commentsRaw
+    ? JSON.parse(commentsRaw).map((c: { body: string }) => c.body)
+    : []
+
+  console.warn(
+    `Issue #${issueNumber}: "${issueData.title}" | ` +
+      `${comments.length} comments`
+  )
+
+  return {
+    title: issueData.title || '',
+    body: issueData.body || '',
+    labels: (issueData.labels || []).map((l: { name: string }) => l.name),
+    comments
+  }
+}
+
+// ── Media extraction ──
+
+const MEDIA_EXTENSIONS = /\.(png|jpg|jpeg|gif|webp|mp4|webm|mov)$/i
+
+const MEDIA_URL_PATTERNS = [
+  // Markdown images: ![alt](url)
+  /!\[[^\]]*\]\(([^)]+)\)/g,
+  // GitHub user-attachments
+  /https:\/\/github\.com\/user-attachments\/assets\/[a-f0-9-]+/g,
+  // Private user images
+  /https:\/\/private-user-images\.githubusercontent\.com\/[^\s)"]+/g,
+  // Raw URLs with media extensions (standalone or in text)
+  /(?<!="|=')https?:\/\/[^\s)<>"]+\.(?:png|jpg|jpeg|gif|webp|mp4|webm|mov)(?:\?[^\s)<>"]*)?/gi
+]
+
+export function extractMediaUrls(text: string): string[] {
+  if (!text) return []
+
+  const urls = new Set<string>()
+
+  for (const pattern of MEDIA_URL_PATTERNS) {
+    // Reset lastIndex for global patterns
+    pattern.lastIndex = 0
+    let match: RegExpExecArray | null
+    while ((match = pattern.exec(text)) !== null) {
+      // For markdown images, the URL is in capture group 1
+      const url = match[1] || match[0]
+      // Clean trailing markdown/html artifacts
+      const cleaned = url.replace(/[)>"'\s]+$/, '')
+      if (cleaned.startsWith('http')) {
+        urls.add(cleaned)
+      }
+    }
+  }
+
+  return [...urls]
+}
+
+// ── Media downloading ──
+
+const ALLOWED_MEDIA_DOMAINS = [
+  'github.com',
+  'raw.githubusercontent.com',
+  'user-images.githubusercontent.com',
+  'private-user-images.githubusercontent.com',
+  'objects.githubusercontent.com',
+  'github.githubassets.com'
+]
+
+function isAllowedMediaDomain(url: string): boolean {
+  try {
+    const hostname = new URL(url).hostname
+    return ALLOWED_MEDIA_DOMAINS.some(
+      (domain) => hostname === domain || hostname.endsWith(`.${domain}`)
+    )
+  } catch {
+    return false
+  }
+}
+
+async function downloadMedia(
+  urls: string[],
+  outputDir: string,
+  budgetBytes: number,
+  maxVideoBytes: number
+): Promise<Array<{ path: string; mimeType: string }>> {
+  const downloaded: Array<{ path: string; mimeType: string }> = []
+  let totalBytes = 0
+
+  const mediaDir = resolve(outputDir, 'media')
+  mkdirSync(mediaDir, { recursive: true })
+
+  for (const url of urls) {
+    if (totalBytes >= budgetBytes) {
+      console.warn(
+        `Media budget exhausted (${totalBytes} bytes), skipping rest`
+      )
+      break
+    }
+
+    if (!isAllowedMediaDomain(url)) {
+      console.warn(`Skipping non-GitHub URL: ${url.slice(0, 80)}`)
+      continue
+    }
+
+    try {
+      const response = await fetch(url, {
+        signal: AbortSignal.timeout(15_000),
+        headers: { Accept: 'image/*,video/*' },
+        redirect: 'follow'
+      })
+
+      if (!response.ok) {
+        console.warn(`Failed to download ${url}: ${response.status}`)
+        continue
+      }
+
+      const contentLength = response.headers.get('content-length')
+      if (contentLength) {
+        const declaredSize = Number.parseInt(contentLength, 10)
+        if (declaredSize > budgetBytes - totalBytes) {
+          console.warn(
+            `Content-Length ${declaredSize} would exceed budget, skipping ${url}`
+          )
+          continue
+        }
+      }
+
+      const contentType = response.headers.get('content-type') || ''
+      const buffer = Buffer.from(await response.arrayBuffer())
+
+      // Skip oversized videos
+      const isVideo =
+        contentType.startsWith('video/') || /\.(mp4|webm|mov)$/i.test(url)
+      if (isVideo && buffer.length > maxVideoBytes) {
+        console.warn(
+          `Skipping large video ${url} (${(buffer.length / 1024 / 1024).toFixed(1)}MB > ${(maxVideoBytes / 1024 / 1024).toFixed(0)}MB cap)`
+        )
+        continue
+      }
+
+      if (totalBytes + buffer.length > budgetBytes) {
+        console.warn(`Would exceed budget, skipping ${url}`)
+        continue
+      }
+
+      const ext = guessExtension(url, contentType)
+      const filename = `media-${downloaded.length}${ext}`
+      const filepath = resolve(mediaDir, filename)
+      writeFileSync(filepath, buffer)
+      totalBytes += buffer.length
+
+      const mimeType = contentType.split(';')[0].trim() || guessMimeType(ext)
+
+      downloaded.push({ path: filepath, mimeType })
+      console.warn(
+        `Downloaded: ${url.slice(0, 80)}... (${(buffer.length / 1024).toFixed(0)}KB)`
+      )
+    } catch (err) {
+      console.warn(`Failed to download ${url}: ${(err as Error).message}`)
+    }
+  }
+
+  console.warn(
+    `Downloaded ${downloaded.length}/${urls.length} media files ` +
+      `(${(totalBytes / 1024 / 1024).toFixed(1)}MB)`
+  )
+  return downloaded
+}
+
+function guessExtension(url: string, contentType: string): string {
+  const urlMatch = url.match(MEDIA_EXTENSIONS)
+  if (urlMatch) return urlMatch[0].toLowerCase()
+
+  const typeMap: Record<string, string> = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+    'video/mp4': '.mp4',
+    'video/webm': '.webm'
+  }
+  return typeMap[contentType.split(';')[0]] || '.bin'
+}
+
+function guessMimeType(ext: string): string {
+  const map: Record<string, string> = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime'
+  }
+  return map[ext] || 'application/octet-stream'
+}
+
+// ── Gemini analysis ──
+
+function buildIssueAnalysisPrompt(issue: IssueThread): string {
+  const allText = [
+    `# Issue: ${issue.title}`,
+    '',
+    '## Description',
+    issue.body,
+    '',
+    issue.comments.length > 0
+      ? `## Comments\n${issue.comments.join('\n\n---\n\n')}`
+      : ''
+  ]
+    .filter(Boolean)
+    .join('\n')
+
+  return `You are a senior QA engineer analyzing a bug report for ComfyUI frontend (a Vue 3 + TypeScript web application for AI image generation workflows).
+
+Your task: Generate a single targeted QA reproduction guide to verify this bug on the current main branch.
+
+${allText}
+
+## Available test actions
+Each step must use one of these actions:
+- "openMenu" — clicks the Comfy hamburger menu (top-left C logo)
+- "hoverMenuItem" — hovers a top-level menu item to open submenu (label required)
+- "clickMenuItem" — clicks an item in the visible submenu (label required)
+- "fillDialog" — fills dialog input and presses Enter (text required)
+- "pressKey" — presses a keyboard key (key required)
+- "click" — clicks an element by visible text (text required)
+- "wait" — waits briefly (ms required, max 3000)
+- "screenshot" — takes a screenshot (name required)
+
+## Output format
+Return a JSON object with exactly one key: "reproduce", containing:
+{
+  "summary": "One sentence: what bug this issue reports",
+  "test_focus": "Specific behavior to reproduce",
+  "prerequisites": ["e.g. Load default workflow"],
+  "steps": [
+    {
+      "action": "openMenu",
+      "description": "Open the main menu to trigger the reported bug",
+      "expected_before": "What should happen if the bug is present"
+    }
+  ],
+  "visual_checks": ["Specific visual evidence of the bug to look for"]
+}
+
+## Rules
+- REPRODUCE guide: 3-6 steps, under 30 seconds. Follow the issue's reproduction steps closely.
+- Focus on triggering and demonstrating the SPECIFIC bug reported.
+- Use information from the issue description and comments to understand the bug.
+- Include at least one screenshot step to capture the bug state.
+- Do NOT include login steps.
+- Menu pattern: openMenu -> hoverMenuItem -> clickMenuItem or screenshot.
+- Output ONLY valid JSON, no markdown fences or explanation.`
+}
+
+function buildAnalysisPrompt(thread: PrThread): string {
+  const allText = [
+    `# PR: ${thread.title}`,
+    '',
+    '## Description',
+    thread.body,
+    '',
+    thread.issueComments.length > 0
+      ? `## Issue Comments\n${thread.issueComments.join('\n\n---\n\n')}`
+      : '',
+    thread.reviewComments.length > 0
+      ? `## Review Comments\n${thread.reviewComments.join('\n\n---\n\n')}`
+      : '',
+    thread.reviews.length > 0
+      ? `## Reviews\n${thread.reviews.join('\n\n---\n\n')}`
+      : '',
+    '',
+    '## Diff (truncated)',
+    '```',
+    thread.diff.slice(0, 8000),
+    '```'
+  ]
+    .filter(Boolean)
+    .join('\n')
+
+  return `You are a senior QA engineer analyzing a pull request for ComfyUI frontend (a Vue 3 + TypeScript web application for AI image generation workflows).
+
+Your task: Generate TWO targeted QA test guides — one for BEFORE the PR (main branch) and one for AFTER (PR branch).
+
+${allText}
+
+## Available test actions
+Each step must use one of these actions:
+- "openMenu" — clicks the Comfy hamburger menu (top-left C logo)
+- "hoverMenuItem" — hovers a top-level menu item to open submenu (label required)
+- "clickMenuItem" — clicks an item in the visible submenu (label required)
+- "fillDialog" — fills dialog input and presses Enter (text required)
+- "pressKey" — presses a keyboard key (key required)
+- "click" — clicks an element by visible text (text required)
+- "wait" — waits briefly (ms required, max 3000)
+- "screenshot" — takes a screenshot (name required)
+
+## Output format
+Return a JSON object with exactly two keys: "before" and "after", each containing:
+{
+  "summary": "One sentence: what this PR changes",
+  "test_focus": "Specific behaviors to verify in this recording",
+  "prerequisites": ["e.g. Load default workflow"],
+  "steps": [
+    {
+      "action": "openMenu",
+      "description": "Open the main menu to check file options",
+      "expected_before": "Old behavior description (before key only)",
+      "expected_after": "New behavior description (after key only)"
+    }
+  ],
+  "visual_checks": ["Specific visual elements to look for"]
+}
+
+## Rules
+- BEFORE guide: 2-4 steps, under 15 seconds. Show OLD/missing behavior.
+- AFTER guide: 3-6 steps, under 30 seconds. Prove the fix/feature works.
+- Focus on the SPECIFIC behavior changed by this PR, not generic testing.
+- Use information from PR description, screenshots, and comments to understand intended behavior.
+- Include at least one screenshot step in each guide.
+- Do NOT include login steps.
+- Menu pattern: openMenu -> hoverMenuItem -> clickMenuItem or screenshot.
+- Output ONLY valid JSON, no markdown fences or explanation.`
+}
+
+async function analyzeWithGemini(
+  thread: PrThread,
+  media: Array<{ path: string; mimeType: string }>,
+  model: string,
+  apiKey: string
+): Promise<{ before: QaGuide; after: QaGuide }> {
+  const genAI = new GoogleGenerativeAI(apiKey)
+  const geminiModel = genAI.getGenerativeModel({ model })
+
+  const prompt = buildAnalysisPrompt(thread)
+
+  const parts: Array<
+    { text: string } | { inlineData: { mimeType: string; data: string } }
+  > = [{ text: prompt }]
+
+  // Add media as inline data
+  for (const item of media) {
+    try {
+      const buffer = readFileSync(item.path)
+      parts.push({
+        inlineData: {
+          mimeType: item.mimeType,
+          data: buffer.toString('base64')
+        }
+      })
+    } catch (err) {
+      console.warn(
+        `Failed to read media ${item.path}: ${(err as Error).message}`
+      )
+    }
+  }
+
+  console.warn(
+    `Sending to ${model}: ${prompt.length} chars text, ${media.length} media files`
+  )
+
+  const result = await geminiModel.generateContent({
+    contents: [{ role: 'user', parts }],
+    generationConfig: {
+      temperature: 0.2,
+      maxOutputTokens: 8192,
+      responseMimeType: 'application/json'
+    }
+  })
+
+  let text = result.response.text()
+  // Strip markdown fences if present
+  text = text
+    .replace(/^```(?:json)?\n?/gm, '')
+    .replace(/```$/gm, '')
+    .trim()
+
+  console.warn('Gemini response received')
+  console.warn('Raw response (first 500 chars):', text.slice(0, 500))
+  const parsed = JSON.parse(text)
+
+  // Handle different response shapes from Gemini
+  let before: QaGuide
+  let after: QaGuide
+
+  if (Array.isArray(parsed) && parsed.length >= 2) {
+    // Array format: [before, after]
+    before = parsed[0]
+    after = parsed[1]
+  } else if (parsed.before && parsed.after) {
+    // Object format: { before, after }
+    before = parsed.before
+    after = parsed.after
+  } else {
+    // Try nested wrapper keys
+    const inner = parsed.qa_guide ?? parsed.guides ?? parsed
+    if (inner.before && inner.after) {
+      before = inner.before
+      after = inner.after
+    } else {
+      console.warn(
+        'Full response:',
+        JSON.stringify(parsed, null, 2).slice(0, 2000)
+      )
+      throw new Error(
+        `Unexpected response shape. Got keys: ${Object.keys(parsed).join(', ')}`
+      )
+    }
+  }
+
+  return { before, after }
+}
+
+async function analyzeIssueWithGemini(
+  issue: IssueThread,
+  media: Array<{ path: string; mimeType: string }>,
+  model: string,
+  apiKey: string
+): Promise<QaGuide> {
+  const genAI = new GoogleGenerativeAI(apiKey)
+  const geminiModel = genAI.getGenerativeModel({ model })
+
+  const prompt = buildIssueAnalysisPrompt(issue)
+
+  const parts: Array<
+    { text: string } | { inlineData: { mimeType: string; data: string } }
+  > = [{ text: prompt }]
+
+  for (const item of media) {
+    try {
+      const buffer = readFileSync(item.path)
+      parts.push({
+        inlineData: {
+          mimeType: item.mimeType,
+          data: buffer.toString('base64')
+        }
+      })
+    } catch (err) {
+      console.warn(
+        `Failed to read media ${item.path}: ${(err as Error).message}`
+      )
+    }
+  }
+
+  console.warn(
+    `Sending to ${model}: ${prompt.length} chars text, ${media.length} media files`
+  )
+
+  const result = await geminiModel.generateContent({
+    contents: [{ role: 'user', parts }],
+    generationConfig: {
+      temperature: 0.2,
+      maxOutputTokens: 8192,
+      responseMimeType: 'application/json'
+    }
+  })
+
+  let text = result.response.text()
+  text = text
+    .replace(/^```(?:json)?\n?/gm, '')
+    .replace(/```$/gm, '')
+    .trim()
+
+  console.warn('Gemini response received')
+  console.warn('Raw response (first 500 chars):', text.slice(0, 500))
+  const parsed = JSON.parse(text)
+
+  const guide: QaGuide =
+    parsed.reproduce ?? parsed.qa_guide?.reproduce ?? parsed
+  return guide
+}
+
+// ── Main ──
+
+async function main() {
+  const opts = parseArgs()
+  mkdirSync(opts.outputDir, { recursive: true })
+
+  if (opts.type === 'issue') {
+    await analyzeIssue(opts)
+  } else {
+    await analyzePr(opts)
+  }
+}
+
+async function analyzeIssue(opts: Options) {
+  const issue = fetchIssueThread(opts.prNumber, opts.repo)
+
+  const allText = [issue.body, ...issue.comments].join('\n')
+  const mediaUrls = extractMediaUrls(allText)
+  console.warn(`Found ${mediaUrls.length} media URLs`)
+
+  const media = await downloadMedia(
+    mediaUrls,
+    opts.outputDir,
+    opts.mediaBudgetBytes,
+    opts.maxVideoBytes
+  )
+
+  const guide = await analyzeIssueWithGemini(
+    issue,
+    media,
+    opts.model,
+    opts.apiKey
+  )
+
+  const beforePath = resolve(opts.outputDir, 'qa-guide-before.json')
+  writeFileSync(beforePath, JSON.stringify(guide, null, 2))
+
+  console.warn(`Wrote QA guide:`)
+  console.warn(`  Reproduce: ${beforePath}`)
+}
+
+async function analyzePr(opts: Options) {
+  const thread = fetchPrThread(opts.prNumber, opts.repo)
+
+  const allText = [
+    thread.body,
+    ...thread.issueComments,
+    ...thread.reviewComments,
+    ...thread.reviews
+  ].join('\n')
+  const mediaUrls = extractMediaUrls(allText)
+  console.warn(`Found ${mediaUrls.length} media URLs`)
+
+  const media = await downloadMedia(
+    mediaUrls,
+    opts.outputDir,
+    opts.mediaBudgetBytes,
+    opts.maxVideoBytes
+  )
+
+  const guides = await analyzeWithGemini(thread, media, opts.model, opts.apiKey)
+
+  const beforePath = resolve(opts.outputDir, 'qa-guide-before.json')
+  const afterPath = resolve(opts.outputDir, 'qa-guide-after.json')
+  writeFileSync(beforePath, JSON.stringify(guides.before, null, 2))
+  writeFileSync(afterPath, JSON.stringify(guides.after, null, 2))
+
+  console.warn(`Wrote QA guides:`)
+  console.warn(`  Before: ${beforePath}`)
+  console.warn(`  After:  ${afterPath}`)
+}
+
+import { fileURLToPath } from 'node:url'
+
+function isExecutedAsScript(metaUrl: string): boolean {
+  const modulePath = fileURLToPath(metaUrl)
+  const scriptPath = process.argv[1] ? resolve(process.argv[1]) : ''
+  return modulePath === scriptPath
+}
+
+if (isExecutedAsScript(import.meta.url)) {
+  main().catch((err) => {
+    console.error('PR analysis failed:', err)
+    process.exit(1)
+  })
+}

scripts/qa-batch.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# Batch-trigger QA runs by creating and pushing sno-qa-* branches.
+#
+# Usage:
+#   ./scripts/qa-batch.sh 10394 10238 9996          # Trigger specific numbers
+#   ./scripts/qa-batch.sh --from tmp/issues.md --top 5  # From triage file
+#   ./scripts/qa-batch.sh --dry-run 10394 10238     # Preview only
+#   ./scripts/qa-batch.sh --cleanup                 # Delete old sno-qa-* branches
+
+set -euo pipefail
+
+DELAY=5
+DRY_RUN=false
+CLEANUP=false
+FROM_FILE=""
+TOP_N=0
+NUMBERS=()
+
+die() { echo "error: $*" >&2; exit 1; }
+
+usage() {
+  cat <<'EOF'
+Usage: qa-batch.sh [options] [numbers...]
+
+Options:
+  --from <file>   Extract numbers from a triage markdown file
+  --top <N>       Take first N entries from Tier 1 (requires --from)
+  --dry-run       Print what would happen without pushing
+  --cleanup       Delete all sno-qa-* remote branches
+  --delay <secs>  Seconds between pushes (default: 5)
+  -h, --help      Show this help
+EOF
+  exit 0
+}
+
+# --- Parse args ---
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --from)     FROM_FILE="$2"; shift 2 ;;
+    --top)      TOP_N="$2"; shift 2 ;;
+    --dry-run)  DRY_RUN=true; shift ;;
+    --cleanup)  CLEANUP=true; shift ;;
+    --delay)    DELAY="$2"; shift 2 ;;
+    -h|--help)  usage ;;
+    -*)         die "unknown option: $1" ;;
+    *)          NUMBERS+=("$1"); shift ;;
+  esac
+done
+
+# --- Cleanup mode ---
+if $CLEANUP; then
+  echo "Fetching remote sno-qa-* branches..."
+  branches=$(git ls-remote --heads origin 'refs/heads/sno-qa-*' | awk '{print $2}' | sed 's|refs/heads/||')
+
+  if [[ -z "$branches" ]]; then
+    echo "No sno-qa-* branches found on remote."
+    exit 0
+  fi
+
+  echo "Found branches:"
+  echo "$branches" | sed 's/^/  /'
+  echo
+
+  if $DRY_RUN; then
+    echo "[dry-run] Would delete the above branches."
+    exit 0
+  fi
+
+  read -rp "Delete all of the above? [y/N] " confirm
+  if [[ "$confirm" != "y" && "$confirm" != "Y" ]]; then
+    echo "Aborted."
+    exit 0
+  fi
+
+  for branch in $branches; do
+    echo "Deleting origin/$branch..."
+    git push origin --delete "$branch"
+  done
+  echo "Done. Cleaned up $(echo "$branches" | wc -l | tr -d ' ') branches."
+  exit 0
+fi
+
+# --- Extract numbers from markdown ---
+if [[ -n "$FROM_FILE" ]]; then
+  [[ -f "$FROM_FILE" ]] || die "file not found: $FROM_FILE"
+  [[ "$TOP_N" -gt 0 ]] || die "--top N required with --from"
+
+  # Extract Tier 1 table rows: | N | [#NNNNN](...) | ...
+  # Stop at the next ## heading after Tier 1
+  extracted=$(awk '/^## Tier 1/,/^## Tier [^1]/' "$FROM_FILE" \
+    | grep -oP '\[#\K\d+' \
+    | head -n "$TOP_N")
+
+  if [[ -z "$extracted" ]]; then
+    die "no numbers found in $FROM_FILE"
+  fi
+
+  while IFS= read -r num; do
+    NUMBERS+=("$num")
+  done <<< "$extracted"
+fi
+
+[[ ${#NUMBERS[@]} -gt 0 ]] || die "no numbers specified. Use positional args or --from/--top."
+
+# --- Validate ---
+for num in "${NUMBERS[@]}"; do
+  [[ "$num" =~ ^[0-9]+$ ]] || die "invalid number: $num"
+done
+
+# Deduplicate
+NUMBERS=($(printf '%s\n' "${NUMBERS[@]}" | sort -un))
+
+# --- Push branches ---
+echo "Triggering QA for: ${NUMBERS[*]}"
+if $DRY_RUN; then
+  echo "[dry-run]"
+fi
+echo
+
+pushed=()
+skipped=()
+
+# Fetch remote refs once
+remote_refs=$(git ls-remote --heads origin 'refs/heads/sno-qa-*' 2>/dev/null | awk '{print $2}' | sed 's|refs/heads/||')
+
+for num in "${NUMBERS[@]}"; do
+  branch="sno-qa-$num"
+
+  # Check if already exists on remote
+  if echo "$remote_refs" | grep -qx "$branch"; then
+    echo "  skip: $branch (already exists on remote)"
+    skipped+=("$num")
+    continue
+  fi
+
+  if $DRY_RUN; then
+    echo "  would push: $branch"
+    pushed+=("$num")
+    continue
+  fi
+
+  # Create branch at current HEAD and push
+  git branch -f "$branch" HEAD
+  git push origin "$branch"
+  pushed+=("$num")
+  echo "  pushed: $branch"
+
+  # Clean up local branch
+  git branch -D "$branch" 2>/dev/null || true
+
+  # Delay between pushes to avoid CI concurrency storm
+  if [[ "$num" != "${NUMBERS[-1]}" ]]; then
+    echo "  waiting ${DELAY}s..."
+    sleep "$DELAY"
+  fi
+done
+
+# --- Summary ---
+echo
+echo "=== Summary ==="
+echo "Triggered: ${#pushed[@]}"
+echo "Skipped:   ${#skipped[@]}"
+
+if [[ ${#pushed[@]} -gt 0 ]]; then
+  echo
+  echo "Triggered numbers: ${pushed[*]}"
+  repo_url=$(git remote get-url origin | sed 's/\.git$//' | sed 's|git@github.com:|https://github.com/|')
+  echo "Actions: ${repo_url}/actions"
+fi
+
+if [[ ${#skipped[@]} -gt 0 ]]; then
+  echo
+  echo "Skipped (already exist): ${skipped[*]}"
+  echo "Use --cleanup first to remove old branches."
+fi

scripts/qa-generate-test.ts

@@ -0,0 +1,208 @@
+#!/usr/bin/env tsx
+/**
+ * Generates a Playwright regression test (.spec.ts) from a QA report + PR diff.
+ * Uses Gemini to produce a test that asserts UIUX behavior verified during QA.
+ *
+ * Usage:
+ *   pnpm exec tsx scripts/qa-generate-test.ts \
+ *     --qa-report <path>       QA video review report (markdown)
+ *     --pr-diff <path>         PR diff file
+ *     --output <path>          Output .spec.ts file path
+ *     --model <name>           Gemini model (default: gemini-2.5-flash)
+ */
+import { readFile, writeFile } from 'node:fs/promises'
+import { basename, resolve } from 'node:path'
+
+import { GoogleGenerativeAI } from '@google/generative-ai'
+
+interface CliOptions {
+  qaReport: string
+  prDiff: string
+  output: string
+  model: string
+}
+
+const DEFAULTS: CliOptions = {
+  qaReport: '',
+  prDiff: '',
+  output: '',
+  model: 'gemini-2.5-flash'
+}
+
+// ── Fixture API reference for the prompt ────────────────────────────
+const FIXTURE_API = `
+## ComfyUI Playwright Test Fixture API
+
+Import pattern:
+\`\`\`typescript
+import { expect } from '@playwright/test'
+import { comfyPageFixture as test } from '../fixtures/ComfyPage'
+\`\`\`
+
+### Available helpers on \`comfyPage\`:
+- \`comfyPage.page\` — raw Playwright Page
+- \`comfyPage.menu.topbar\` — Topbar helper:
+  - \`.getTabNames(): Promise<string[]>\` — get all open tab names
+  - \`.getActiveTabName(): Promise<string>\` — get active tab name
+  - \`.saveWorkflow(name)\` — Save via File > Save dialog
+  - \`.saveWorkflowAs(name)\` — Save via File > Save As dialog
+  - \`.exportWorkflow(name)\` — Export via File > Export dialog
+  - \`.triggerTopbarCommand(path: string[])\` — e.g. ['File', 'Save As']
+  - \`.getWorkflowTab(name)\` — get a tab locator by name
+  - \`.closeWorkflowTab(name)\` — close a tab
+  - \`.openTopbarMenu()\` — open the hamburger menu
+  - \`.openSubmenu(label)\` — hover to open a submenu
+- \`comfyPage.menu.workflowsTab\` — Workflows sidebar:
+  - \`.open()\` / \`.close()\` — toggle sidebar
+  - \`.getTopLevelSavedWorkflowNames()\` — list saved workflows
+  - \`.getPersistedItem(name)\` — get a workflow item locator
+- \`comfyPage.workflow\` — WorkflowHelper:
+  - \`.loadWorkflow(name)\` — load from browser_tests/assets/{name}.json
+  - \`.setupWorkflowsDirectory(structure)\` — setup test directory
+  - \`.deleteWorkflow(name)\` — delete a workflow
+  - \`.isCurrentWorkflowModified(): Promise<boolean>\` — check dirty state
+  - \`.getUndoQueueSize()\` / \`.getRedoQueueSize()\`
+- \`comfyPage.settings.setSetting(key, value)\` — change settings
+- \`comfyPage.keyboard\` — KeyboardHelper:
+  - \`.undo()\` / \`.redo()\` / \`.bypass()\`
+- \`comfyPage.nodeOps\` — NodeOperationsHelper
+- \`comfyPage.canvas\` — CanvasHelper
+- \`comfyPage.contextMenu\` — ContextMenu
+- \`comfyPage.toast\` — ToastHelper
+- \`comfyPage.confirmDialog\` — confirmation dialog
+- \`comfyPage.nextFrame()\` — wait for Vue re-render
+
+### Test patterns:
+- Use \`test.describe('Name', { tag: '@ui' }, () => { ... })\` for UI tests
+- Use \`test.beforeEach\` to set up common state (settings, workflow dir)
+- Use \`expect(locator).toHaveScreenshot('name.png')\` for visual assertions
+- Use \`expect(locator).toBeVisible()\` / \`.toHaveText()\` for behavioral assertions
+- Use \`comfyPage.workflow.setupWorkflowsDirectory({})\` to ensure clean state
+`
+
+// ── Prompt builder ──────────────────────────────────────────────────
+function buildPrompt(qaReport: string, prDiff: string): string {
+  return `You are a Playwright test generator for the ComfyUI frontend.
+
+Your task: Generate a single .spec.ts regression test file that asserts the UIUX behavior
+described in the QA report below. The test must:
+
+1. Use the ComfyUI Playwright fixture API (documented below)
+2. Test UIUX behavior ONLY — element visibility, tab names, dialog states, workflow states
+3. NOT test code implementation details
+4. Be concise — only test the behavior that the PR changed
+5. Follow existing test conventions (see API reference)
+
+${FIXTURE_API}
+
+## QA Video Review Report
+${qaReport}
+
+## PR Diff (for context on what changed)
+${prDiff.slice(0, 8000)}
+
+## Output Requirements
+- Output ONLY the .spec.ts file content — no markdown fences, no explanations
+- Start with imports, end with closing brace
+- Use descriptive test names that explain the expected behavior
+- Add screenshot assertions where visual verification matters
+- Keep it focused: 2-5 test cases covering the core behavioral change
+- Use \`test.beforeEach\` for common setup (settings, workflow directory)
+- Tag the describe block with \`{ tag: '@ui' }\` or \`{ tag: '@workflow' }\` as appropriate
+`
+}
+
+// ── Gemini call ─────────────────────────────────────────────────────
+async function generateTest(
+  qaReport: string,
+  prDiff: string,
+  model: string
+): Promise<string> {
+  const apiKey = process.env.GEMINI_API_KEY
+  if (!apiKey) throw new Error('GEMINI_API_KEY env var required')
+
+  const genAI = new GoogleGenerativeAI(apiKey)
+  const genModel = genAI.getGenerativeModel({ model })
+
+  const prompt = buildPrompt(qaReport, prDiff)
+  console.warn(`Sending prompt to ${model} (${prompt.length} chars)...`)
+
+  const result = await genModel.generateContent({
+    contents: [{ role: 'user', parts: [{ text: prompt }] }],
+    generationConfig: {
+      temperature: 0.2,
+      maxOutputTokens: 8192
+    }
+  })
+
+  const text = result.response.text()
+
+  // Strip markdown fences if model wraps output
+  return text
+    .replace(/^```(?:typescript|ts)?\n?/, '')
+    .replace(/\n?```$/, '')
+    .trim()
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────
+function parseArgs(): CliOptions {
+  const args = process.argv.slice(2)
+  const opts = { ...DEFAULTS }
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--qa-report':
+        opts.qaReport = args[++i]
+        break
+      case '--pr-diff':
+        opts.prDiff = args[++i]
+        break
+      case '--output':
+        opts.output = args[++i]
+        break
+      case '--model':
+        opts.model = args[++i]
+        break
+      case '--help':
+        console.warn(`Usage:
+  pnpm exec tsx scripts/qa-generate-test.ts [options]
+
+Options:
+  --qa-report <path>   QA video review report (markdown) [required]
+  --pr-diff <path>     PR diff file [required]
+  --output <path>      Output .spec.ts path [required]
+  --model <name>       Gemini model (default: gemini-2.5-flash)`)
+        process.exit(0)
+    }
+  }
+
+  if (!opts.qaReport || !opts.prDiff || !opts.output) {
+    console.error('Missing required args. Run with --help for usage.')
+    process.exit(1)
+  }
+
+  return opts
+}
+
+async function main() {
+  const opts = parseArgs()
+
+  const qaReport = await readFile(resolve(opts.qaReport), 'utf-8')
+  const prDiff = await readFile(resolve(opts.prDiff), 'utf-8')
+
+  console.warn(
+    `QA report: ${basename(opts.qaReport)} (${qaReport.length} chars)`
+  )
+  console.warn(`PR diff: ${basename(opts.prDiff)} (${prDiff.length} chars)`)
+
+  const testCode = await generateTest(qaReport, prDiff, opts.model)
+
+  const outputPath = resolve(opts.output)
+  await writeFile(outputPath, testCode + '\n')
+  console.warn(`Generated test: ${outputPath} (${testCode.length} chars)`)
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

scripts/qa-record.ts

@@ -0,0 +1,578 @@
+#!/usr/bin/env tsx
+/**
+ * QA Recording Script
+ *
+ * Records a ComfyUI frontend QA session using Playwright with video capture.
+ * Uses Gemini to generate targeted test steps based on the PR diff.
+ *
+ * Usage:
+ *   pnpm exec tsx scripts/qa-record.ts \
+ *     --mode before|after \
+ *     --diff <path-to-diff> \
+ *     --output-dir <path> \
+ *     [--url <server-url>] \
+ *     [--model <gemini-model>]
+ *
+ * Env: GEMINI_API_KEY (required)
+ */
+
+import { chromium } from '@playwright/test'
+import type { Page } from '@playwright/test'
+import { GoogleGenerativeAI } from '@google/generative-ai'
+import { readFileSync, mkdirSync, readdirSync, renameSync, statSync } from 'fs'
+
+// ── Types ──
+
+type TestAction =
+  | { action: 'openMenu' }
+  | { action: 'hoverMenuItem'; label: string }
+  | { action: 'clickMenuItem'; label: string }
+  | { action: 'fillDialog'; text: string }
+  | { action: 'pressKey'; key: string }
+  | { action: 'click'; text: string }
+  | { action: 'wait'; ms: number }
+  | { action: 'screenshot'; name: string }
+
+type RecordMode = 'before' | 'after' | 'reproduce'
+
+interface Options {
+  mode: RecordMode
+  diffFile?: string
+  outputDir: string
+  serverUrl: string
+  model: string
+  apiKey: string
+  testPlanFile?: string
+  qaGuideFile?: string
+}
+
+// ── CLI parsing ──
+
+function parseArgs(): Options {
+  const args = process.argv.slice(2)
+  const opts: Partial<Options> = {
+    model: 'gemini-2.5-flash',
+    serverUrl: 'http://127.0.0.1:8188',
+    apiKey: process.env.GEMINI_API_KEY || ''
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--mode':
+        opts.mode = args[++i] as RecordMode
+        break
+      case '--diff':
+        opts.diffFile = args[++i]
+        break
+      case '--output-dir':
+        opts.outputDir = args[++i]
+        break
+      case '--url':
+        opts.serverUrl = args[++i]
+        break
+      case '--model':
+        opts.model = args[++i]
+        break
+      case '--test-plan':
+        opts.testPlanFile = args[++i]
+        break
+      case '--qa-guide':
+        opts.qaGuideFile = args[++i]
+        break
+      case '--help':
+        console.warn(
+          'Usage: qa-record.ts --mode before|after|reproduce --output-dir <path> [--diff <path>] [--url <url>] [--model <model>] [--test-plan <path>] [--qa-guide <path>]'
+        )
+        process.exit(0)
+    }
+  }
+
+  if (!opts.mode || !opts.outputDir) {
+    console.error('Required: --mode before|after|reproduce --output-dir <path>')
+    process.exit(1)
+  }
+
+  const validModes: RecordMode[] = ['before', 'after', 'reproduce']
+  if (!validModes.includes(opts.mode)) {
+    console.error(
+      `Invalid --mode "${opts.mode}". Must be one of: ${validModes.join(', ')}`
+    )
+    process.exit(1)
+  }
+
+  if (!opts.diffFile && opts.mode !== 'reproduce') {
+    console.error('--diff is required for before/after modes')
+    process.exit(1)
+  }
+
+  if (!opts.apiKey) {
+    console.error('GEMINI_API_KEY environment variable is required')
+    process.exit(1)
+  }
+
+  return opts as Options
+}
+
+// ── Gemini test step generation ──
+
+function buildPrompt(
+  mode: string,
+  diff: string,
+  testPlan?: string,
+  qaGuide?: string
+): string {
+  const modeDescriptions: Record<string, string> = {
+    before:
+      'BEFORE (main branch). Show the OLD state briefly — under 15 seconds. One quick demonstration of missing feature / old behavior.',
+    after:
+      'AFTER (PR branch). Prove the changes work — 3-6 targeted steps, under 30 seconds.',
+    reproduce:
+      'REPRODUCE a reported issue on main branch. Follow the reproduction steps to trigger and demonstrate the reported bug — 3-6 steps, under 30 seconds.'
+  }
+  const modeDesc = modeDescriptions[mode] ?? modeDescriptions.before
+
+  const qaGuideSection = qaGuide
+    ? `
+## QA Analysis Guide (follow closely)
+A deep analysis of this PR has produced the following targeted test guide.
+Follow these steps closely — they were generated from the full PR thread,
+screenshots, and reviewer comments.
+
+${qaGuide.slice(0, 6000)}
+`
+    : ''
+
+  const testPlanSection = testPlan
+    ? `
+## QA Test Plan Reference
+Use this test plan to identify which test categories are relevant to the PR diff.
+Pick test steps from the most relevant categories.
+
+${testPlan.slice(0, 4000)}
+`
+    : ''
+
+  return `You are generating test steps for a ComfyUI frontend QA recording.
+
+MODE: ${modeDesc}
+
+## Available actions (JSON array)
+Each step is an object with an "action" field:
+- { "action": "openMenu" } — clicks the Comfy hamburger menu (top-left C logo)
+- { "action": "hoverMenuItem", "label": "File" } — hovers a top-level menu item to open submenu
+- { "action": "clickMenuItem", "label": "Save As" } — clicks an item in the visible submenu
+- { "action": "fillDialog", "text": "test-name" } — fills the dialog input and presses Enter
+- { "action": "pressKey", "key": "Escape" } — presses a keyboard key
+- { "action": "click", "text": "Button Text" } — clicks an element by visible text
+- { "action": "wait", "ms": 1000 } — waits (use sparingly, max 3000ms)
+- { "action": "screenshot", "name": "step-name" } — takes a screenshot
+${qaGuideSection}${testPlanSection}
+${diff ? `## PR Diff\n\`\`\`\n${diff.slice(0, 3000)}\n\`\`\`` : ''}
+
+## Rules
+- Output ONLY a valid JSON array of actions, no markdown fences or explanation
+- ${mode === 'reproduce' ? 'Follow the reproduction steps to trigger and demonstrate the reported bug' : mode === 'before' ? 'Keep it minimal — just show the old/missing behavior' : 'Test the specific behavior that changed in the PR'}
+- Always include at least one screenshot
+- Do NOT include login steps (handled automatically)
+- Menu navigation pattern: openMenu → hoverMenuItem → clickMenuItem (or screenshot)
+${qaGuide ? '- Follow the QA Analysis Guide steps closely — they are well-researched and specific' : diff ? '- Pick test steps from the QA test plan categories that are most relevant to the diff' : '- Pick test steps from the QA test plan categories most likely to reveal bugs'}
+
+## Example output
+[
+  {"action":"openMenu"},
+  {"action":"hoverMenuItem","label":"File"},
+  {"action":"screenshot","name":"file-menu"},
+  {"action":"clickMenuItem","label":"Save As"},
+  {"action":"wait","ms":800},
+  {"action":"fillDialog","text":"test-save"},
+  {"action":"wait","ms":2000},
+  {"action":"screenshot","name":"after-save"}
+]`
+}
+
+async function generateTestSteps(opts: Options): Promise<TestAction[]> {
+  const diff = opts.diffFile ? readFileSync(opts.diffFile, 'utf-8') : ''
+  const testPlan = opts.testPlanFile
+    ? readFileSync(opts.testPlanFile, 'utf-8')
+    : undefined
+  let qaGuide: string | undefined
+  if (opts.qaGuideFile) {
+    try {
+      qaGuide = readFileSync(opts.qaGuideFile, 'utf-8')
+      console.warn(`Using QA guide: ${opts.qaGuideFile}`)
+    } catch {
+      console.warn(
+        `QA guide not found: ${opts.qaGuideFile}, continuing without`
+      )
+    }
+  }
+  const prompt = buildPrompt(opts.mode, diff, testPlan, qaGuide)
+
+  const genAI = new GoogleGenerativeAI(opts.apiKey)
+  const model = genAI.getGenerativeModel({ model: opts.model })
+
+  console.warn(`Generating ${opts.mode} test steps with ${opts.model}...`)
+
+  const result = await model.generateContent({
+    contents: [{ role: 'user', parts: [{ text: prompt }] }],
+    generationConfig: { temperature: 0.2, maxOutputTokens: 4096 }
+  })
+
+  let text = result.response.text()
+  // Strip markdown fences if present
+  text = text
+    .replace(/^```(?:json)?\n?/gm, '')
+    .replace(/```$/gm, '')
+    .trim()
+
+  console.warn('Generated steps:', text)
+
+  const steps: TestAction[] = JSON.parse(text)
+  if (!Array.isArray(steps)) throw new Error('Expected JSON array')
+  return steps
+}
+
+// ── Fallback steps ──
+
+const FALLBACK_BEFORE: TestAction[] = [
+  { action: 'openMenu' },
+  { action: 'wait', ms: 300 },
+  { action: 'hoverMenuItem', label: 'File' },
+  { action: 'wait', ms: 500 },
+  { action: 'screenshot', name: 'file-menu-before' },
+  { action: 'pressKey', key: 'Escape' },
+  { action: 'wait', ms: 500 },
+  { action: 'screenshot', name: 'editor-before' }
+]
+
+const FALLBACK_AFTER: TestAction[] = [
+  { action: 'openMenu' },
+  { action: 'wait', ms: 300 },
+  { action: 'hoverMenuItem', label: 'File' },
+  { action: 'wait', ms: 500 },
+  { action: 'screenshot', name: 'file-menu-after' },
+  { action: 'pressKey', key: 'Escape' },
+  { action: 'wait', ms: 500 },
+  { action: 'screenshot', name: 'editor-after' }
+]
+
+const FALLBACK_REPRODUCE: TestAction[] = FALLBACK_BEFORE
+
+const FALLBACK_STEPS: Record<RecordMode, TestAction[]> = {
+  before: FALLBACK_BEFORE,
+  after: FALLBACK_AFTER,
+  reproduce: FALLBACK_REPRODUCE
+}
+
+// ── Playwright helpers ──
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+async function openComfyMenu(page: Page) {
+  const menuTrigger = page.locator('.comfy-menu-button-wrapper')
+  const menuPopup = page.locator('.comfy-command-menu')
+
+  // Close if already open
+  if (await menuPopup.isVisible().catch(() => false)) {
+    await page.locator('body').click({ position: { x: 500, y: 300 } })
+    await sleep(500)
+  }
+
+  if (await menuTrigger.isVisible({ timeout: 3000 }).catch(() => false)) {
+    await menuTrigger.click()
+  } else {
+    // Fallback: click where the C logo menu button typically is
+    console.warn('Menu button not found by selector, using coordinate click')
+    await page.mouse.click(46, 36)
+    await sleep(300)
+  }
+
+  try {
+    await menuPopup.waitFor({ state: 'visible', timeout: 3000 })
+  } catch {
+    console.warn('Menu popup did not appear')
+  }
+  await sleep(300)
+}
+
+async function hoverMenuItem(page: Page, label: string) {
+  // Top-level items use .p-menubar-item-label in the comfy-command-menu
+  const menuLabel = page.locator(`.p-menubar-item-label:text-is("${label}")`)
+  if (await menuLabel.isVisible().catch(() => false)) {
+    // Hover the parent .p-tieredmenu-item to trigger submenu
+    const menuItem = page
+      .locator('.comfy-command-menu .p-tieredmenu-item')
+      .filter({ has: menuLabel })
+    await menuItem.hover()
+    // Wait for submenu to appear
+    try {
+      await page
+        .locator('.p-tieredmenu-submenu:visible')
+        .last()
+        .waitFor({ state: 'visible', timeout: 2000 })
+    } catch {
+      console.warn(`Submenu for "${label}" did not appear`)
+    }
+    await sleep(300)
+  } else {
+    console.warn(`Menu item "${label}" not visible`)
+  }
+}
+
+async function clickSubmenuItem(page: Page, label: string) {
+  const submenu = page.locator('.p-tieredmenu-submenu:visible').last()
+  const item = submenu
+    .locator('.p-tieredmenu-item')
+    .filter({ hasText: label })
+    .first()
+  if (await item.isVisible().catch(() => false)) {
+    await item.click()
+    await sleep(800)
+  } else {
+    console.warn(`Submenu item "${label}" not found`)
+  }
+}
+
+async function fillDialogAndConfirm(page: Page, text: string) {
+  const input = page.locator('.p-dialog-content input')
+  if (await input.isVisible().catch(() => false)) {
+    await input.fill(text)
+    await sleep(300)
+    await page.keyboard.press('Enter')
+    await sleep(2000)
+  } else {
+    console.warn('Dialog input not found')
+  }
+}
+
+async function clickByText(page: Page, text: string) {
+  const el = page.locator(`text=${text}`).first()
+  if (await el.isVisible().catch(() => false)) {
+    await el.click()
+    await sleep(500)
+  } else {
+    console.warn(`Element with text "${text}" not found`)
+  }
+}
+
+// ── Step executor ──
+
+async function executeSteps(
+  page: Page,
+  steps: TestAction[],
+  outputDir: string
+) {
+  for (const step of steps) {
+    console.warn(
+      `  → ${step.action}${('label' in step && `: ${step.label}`) || ('text' in step && `: ${step.text}`) || ('name' in step && `: ${step.name}`) || ''}`
+    )
+    switch (step.action) {
+      case 'openMenu':
+        await openComfyMenu(page)
+        break
+      case 'hoverMenuItem':
+        await hoverMenuItem(page, step.label)
+        break
+      case 'clickMenuItem':
+        await clickSubmenuItem(page, step.label)
+        break
+      case 'fillDialog':
+        await fillDialogAndConfirm(page, step.text)
+        break
+      case 'pressKey':
+        try {
+          await page.keyboard.press(step.key)
+          await sleep(300)
+        } catch (e) {
+          console.warn(
+            `Skipping invalid key "${step.key}": ${e instanceof Error ? e.message : e}`
+          )
+        }
+        break
+      case 'click':
+        await clickByText(page, step.text)
+        break
+      case 'wait':
+        await sleep(Math.min(step.ms, 5000))
+        break
+      case 'screenshot': {
+        const safeName = step.name.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 100)
+        await page.screenshot({
+          path: `${outputDir}/${safeName}.png`
+        })
+        break
+      }
+      default:
+        console.warn(`Unknown action: ${JSON.stringify(step)}`)
+    }
+  }
+}
+
+// ── Login flow ──
+
+async function loginAsQaCi(page: Page, _serverUrl: string) {
+  console.warn('Logging in as qa-ci...')
+
+  // Detect login page by looking for the "New user" input
+  const newUserInput = page.locator('input[placeholder*="username"]').first()
+  const isLoginPage = await newUserInput
+    .isVisible({ timeout: 5000 })
+    .catch(() => false)
+
+  if (isLoginPage) {
+    console.warn('Login page detected, selecting existing user...')
+
+    // Try selecting existing user from dropdown (created by Pre-seed step)
+    const dropdown = page
+      .locator('.p-select, .p-dropdown, [role="combobox"]')
+      .first()
+    let loginDone = false
+
+    if (await dropdown.isVisible().catch(() => false)) {
+      await dropdown.click()
+      await sleep(500)
+
+      // Look for qa-ci in the dropdown options
+      const option = page.locator('text=qa-ci').first()
+      if (await option.isVisible({ timeout: 2000 }).catch(() => false)) {
+        await option.click()
+        await sleep(300)
+        console.warn('Selected qa-ci from dropdown')
+
+        const nextBtn = page.getByRole('button', { name: 'Next' })
+        if (await nextBtn.isVisible().catch(() => false)) {
+          await nextBtn.click({ timeout: 5000 })
+          console.warn('Clicked Next with existing user')
+          loginDone = true
+          await sleep(5000)
+        }
+      } else {
+        // Close dropdown
+        await page.keyboard.press('Escape')
+        await sleep(300)
+        console.warn('qa-ci not found in dropdown')
+      }
+    }
+
+    // Fallback: create new user with unique name
+    if (!loginDone) {
+      const uniqueName = `qa-${Date.now()}`
+      console.warn(`Creating new user: ${uniqueName}`)
+      await newUserInput.fill(uniqueName)
+      await sleep(500)
+      const nextBtn = page.getByRole('button', { name: 'Next' })
+      await nextBtn.click({ timeout: 5000 })
+      console.warn('Clicked Next with new user')
+      await sleep(5000)
+    }
+  } else {
+    console.warn('No login page detected, continuing...')
+  }
+
+  // Skip tutorial/template gallery
+  await page.evaluate(() => {
+    localStorage.setItem('Comfy.TutorialCompleted', 'true')
+  })
+
+  // Close template gallery if it appeared
+  await page.keyboard.press('Escape')
+  await sleep(1000)
+
+  // Dismiss error popup if present
+  const dismissBtn = page.locator('text=Dismiss').first()
+  if (await dismissBtn.isVisible().catch(() => false)) {
+    await dismissBtn.click()
+    await sleep(500)
+  }
+
+  // Wait for the editor UI to be fully loaded (menu button visible)
+  try {
+    await page
+      .locator('.comfy-menu-button-wrapper')
+      .waitFor({ state: 'visible', timeout: 15000 })
+    console.warn('Editor UI loaded (menu button visible)')
+  } catch {
+    console.warn('Menu button not visible after 15s')
+    console.warn(`Current URL: ${page.url()}`)
+  }
+  await sleep(1000)
+}
+
+// ── Main ──
+
+async function main() {
+  const opts = parseArgs()
+  mkdirSync(opts.outputDir, { recursive: true })
+
+  // Generate or fall back to default test steps
+  let steps: TestAction[]
+  try {
+    steps = await generateTestSteps(opts)
+  } catch (err) {
+    console.warn('Gemini generation failed, using fallback steps:', err)
+    steps = FALLBACK_STEPS[opts.mode]
+  }
+
+  // Launch browser with video recording (Chromium for WebGL support)
+  const browser = await chromium.launch({ headless: true })
+  const context = await browser.newContext({
+    viewport: { width: 1280, height: 720 },
+    recordVideo: { dir: opts.outputDir, size: { width: 1280, height: 720 } }
+  })
+  const page = await context.newPage()
+
+  try {
+    console.warn(`Opening ComfyUI at ${opts.serverUrl}`)
+    await page.goto(opts.serverUrl, {
+      waitUntil: 'domcontentloaded',
+      timeout: 30000
+    })
+    await sleep(2000)
+
+    await loginAsQaCi(page, opts.serverUrl)
+
+    // Debug: capture page state after login
+    await page.screenshot({
+      path: `${opts.outputDir}/debug-after-login-${opts.mode}.png`
+    })
+    console.warn(`Debug screenshot saved: debug-after-login-${opts.mode}.png`)
+    console.warn('Editor ready — executing test steps')
+
+    await executeSteps(page, steps, opts.outputDir)
+
+    await sleep(2000)
+  } finally {
+    await context.close()
+    await browser.close()
+  }
+
+  // Rename the recorded video to expected filename
+  const videoName =
+    opts.mode === 'before' ? 'qa-before-session.webm' : 'qa-session.webm'
+  // reproduce mode uses 'qa-session.webm' (same as after — it's the primary video)
+  const knownNames = new Set(['qa-before-session.webm', 'qa-session.webm'])
+  const files = readdirSync(opts.outputDir)
+    .filter((f) => f.endsWith('.webm') && !knownNames.has(f))
+    .sort((a, b) => {
+      const mtimeA = statSync(`${opts.outputDir}/${a}`).mtimeMs
+      const mtimeB = statSync(`${opts.outputDir}/${b}`).mtimeMs
+      return mtimeB - mtimeA
+    })
+  if (files.length > 0) {
+    const recorded = files[0]
+    renameSync(
+      `${opts.outputDir}/${recorded}`,
+      `${opts.outputDir}/${videoName}`
+    )
+    console.warn(`Video saved: ${opts.outputDir}/${videoName}`)
+  } else {
+    console.warn('WARNING: No .webm video found after recording')
+  }
+
+  console.warn('Recording complete!')
+}
+
+main().catch((err) => {
+  console.error('Recording failed:', err)
+  process.exit(1)
+})

scripts/qa-video-review.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  extractPlatformFromArtifactDirName,
+  pickLatestVideosByPlatform,
+  selectVideoCandidateByFile
+} from './qa-video-review'
+
+describe('extractPlatformFromArtifactDirName', () => {
+  it('extracts and normalizes known qa artifact directory names', () => {
+    expect(
+      extractPlatformFromArtifactDirName('qa-report-Windows-22818315023')
+    ).toBe('windows')
+    expect(
+      extractPlatformFromArtifactDirName('qa-report-macOS-22818315023')
+    ).toBe('macos')
+    expect(
+      extractPlatformFromArtifactDirName('qa-report-Linux-22818315023')
+    ).toBe('linux')
+  })
+
+  it('falls back to slugifying unknown directory names', () => {
+    expect(extractPlatformFromArtifactDirName('custom platform run')).toBe(
+      'custom-platform-run'
+    )
+  })
+})
+
+describe('pickLatestVideosByPlatform', () => {
+  it('keeps only the latest candidate per platform', () => {
+    const selected = pickLatestVideosByPlatform([
+      {
+        platformName: 'windows',
+        videoPath: '/tmp/windows-old.mp4',
+        mtimeMs: 100
+      },
+      {
+        platformName: 'windows',
+        videoPath: '/tmp/windows-new.mp4',
+        mtimeMs: 200
+      },
+      {
+        platformName: 'linux',
+        videoPath: '/tmp/linux.mp4',
+        mtimeMs: 150
+      }
+    ])
+
+    expect(selected).toEqual([
+      {
+        platformName: 'linux',
+        videoPath: '/tmp/linux.mp4',
+        mtimeMs: 150
+      },
+      {
+        platformName: 'windows',
+        videoPath: '/tmp/windows-new.mp4',
+        mtimeMs: 200
+      }
+    ])
+  })
+})
+
+describe('selectVideoCandidateByFile', () => {
+  it('selects a single candidate by artifacts-relative path', () => {
+    const selected = selectVideoCandidateByFile(
+      [
+        {
+          platformName: 'windows',
+          videoPath: '/tmp/qa-artifacts/qa-report-Windows-1/qa-session.mp4',
+          mtimeMs: 100
+        },
+        {
+          platformName: 'linux',
+          videoPath: '/tmp/qa-artifacts/qa-report-Linux-1/qa-session.mp4',
+          mtimeMs: 200
+        }
+      ],
+      {
+        artifactsDir: '/tmp/qa-artifacts',
+        videoFile: 'qa-report-Linux-1/qa-session.mp4'
+      }
+    )
+
+    expect(selected).toEqual({
+      platformName: 'linux',
+      videoPath: '/tmp/qa-artifacts/qa-report-Linux-1/qa-session.mp4',
+      mtimeMs: 200
+    })
+  })
+
+  it('throws when basename matches multiple videos', () => {
+    expect(() =>
+      selectVideoCandidateByFile(
+        [
+          {
+            platformName: 'windows',
+            videoPath: '/tmp/qa-artifacts/qa-report-Windows-1/qa-session.mp4',
+            mtimeMs: 100
+          },
+          {
+            platformName: 'linux',
+            videoPath: '/tmp/qa-artifacts/qa-report-Linux-1/qa-session.mp4',
+            mtimeMs: 200
+          }
+        ],
+        {
+          artifactsDir: '/tmp/qa-artifacts',
+          videoFile: 'qa-session.mp4'
+        }
+      )
+    ).toThrow('matched 2 videos')
+  })
+
+  it('throws when there is no matching video', () => {
+    expect(() =>
+      selectVideoCandidateByFile(
+        [
+          {
+            platformName: 'windows',
+            videoPath: '/tmp/qa-artifacts/qa-report-Windows-1/qa-session.mp4',
+            mtimeMs: 100
+          }
+        ],
+        {
+          artifactsDir: '/tmp/qa-artifacts',
+          videoFile: 'qa-report-macOS-1/qa-session.mp4'
+        }
+      )
+    ).toThrow('No video matched')
+  })
+
+  it('throws when video file is missing', () => {
+    expect(() =>
+      selectVideoCandidateByFile(
+        [
+          {
+            platformName: 'windows',
+            videoPath: '/tmp/qa-artifacts/qa-report-Windows-1/qa-session.mp4',
+            mtimeMs: 100
+          }
+        ],
+        {
+          artifactsDir: '/tmp/qa-artifacts',
+          videoFile: '   '
+        }
+      )
+    ).toThrow('--video-file is required')
+  })
+})

scripts/qa-video-review.ts

@@ -0,0 +1,711 @@
+#!/usr/bin/env tsx
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { basename, dirname, extname, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { GoogleGenerativeAI } from '@google/generative-ai'
+import { globSync } from 'glob'
+
+interface CliOptions {
+  artifactsDir: string
+  videoFile: string
+  beforeVideo: string
+  outputDir: string
+  model: string
+  requestTimeoutMs: number
+  dryRun: boolean
+  prContext: string
+}
+
+interface VideoCandidate {
+  platformName: string
+  videoPath: string
+  mtimeMs: number
+}
+
+const DEFAULT_OPTIONS: CliOptions = {
+  artifactsDir: './tmp/qa-artifacts',
+  videoFile: '',
+  beforeVideo: '',
+  outputDir: './tmp',
+  model: 'gemini-2.5-flash',
+  requestTimeoutMs: 300_000,
+  dryRun: false,
+  prContext: ''
+}
+
+const USAGE = `Usage:
+  pnpm exec tsx scripts/qa-video-review.ts [options]
+
+Options:
+  --artifacts-dir <path>        Artifacts root directory
+                                 (default: ./tmp/qa-artifacts)
+  --video-file <name-or-path>   Video file to analyze (required)
+                                 (supports basename or relative/absolute path)
+  --before-video <path>         Before video (main branch) for comparison
+                                 When provided, sends both videos to Gemini
+                                 for comparative before/after analysis
+  --output-dir <path>           Output directory for markdown reports
+                                 (default: ./tmp)
+  --model <name>                Gemini model
+                                 (default: gemini-2.5-flash)
+  --request-timeout-ms <n>      Request timeout in milliseconds
+                                 (default: 300000)
+  --pr-context <file>           File with PR context (title, body, diff)
+                                 for PR-aware review
+  --dry-run                     Discover videos and output targets only
+  --help                        Show this help text
+
+Environment:
+  GEMINI_API_KEY                Required unless --dry-run
+`
+
+function parsePositiveInteger(rawValue: string, flagName: string): number {
+  const parsedValue = Number.parseInt(rawValue, 10)
+  if (!Number.isInteger(parsedValue) || parsedValue <= 0) {
+    throw new Error(`Invalid value for ${flagName}: "${rawValue}"`)
+  }
+  return parsedValue
+}
+
+function parseCliOptions(args: string[]): CliOptions {
+  const options: CliOptions = { ...DEFAULT_OPTIONS }
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index]
+    const nextValue = args[index + 1]
+    const requireValue = (flagName: string): string => {
+      if (!nextValue || nextValue.startsWith('--')) {
+        throw new Error(`Missing value for ${flagName}`)
+      }
+      index += 1
+      return nextValue
+    }
+
+    if (argument === '--help') {
+      process.stdout.write(USAGE)
+      process.exit(0)
+    }
+
+    if (argument === '--artifacts-dir') {
+      options.artifactsDir = requireValue(argument)
+      continue
+    }
+
+    if (argument === '--video-file') {
+      options.videoFile = requireValue(argument)
+      continue
+    }
+
+    if (argument === '--output-dir') {
+      options.outputDir = requireValue(argument)
+      continue
+    }
+
+    if (argument === '--model') {
+      options.model = requireValue(argument)
+      continue
+    }
+
+    if (argument === '--request-timeout-ms') {
+      options.requestTimeoutMs = parsePositiveInteger(
+        requireValue(argument),
+        argument
+      )
+      continue
+    }
+
+    if (argument === '--before-video') {
+      options.beforeVideo = requireValue(argument)
+      continue
+    }
+
+    if (argument === '--pr-context') {
+      options.prContext = requireValue(argument)
+      continue
+    }
+
+    if (argument === '--dry-run') {
+      options.dryRun = true
+      continue
+    }
+
+    throw new Error(`Unknown argument: ${argument}`)
+  }
+
+  return options
+}
+
+function normalizePlatformName(value: string): string {
+  const slug = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+  return slug.length > 0 ? slug : 'unknown-platform'
+}
+
+export function extractPlatformFromArtifactDirName(dirName: string): string {
+  const matchedValue = dirName.match(/^qa-report-(.+?)(?:-\d+)?$/i)?.[1]
+  return normalizePlatformName(matchedValue ?? dirName)
+}
+
+function extractPlatformFromVideoPath(videoPath: string): string {
+  const artifactDirName = basename(dirname(videoPath))
+  return extractPlatformFromArtifactDirName(artifactDirName)
+}
+
+export function pickLatestVideosByPlatform(
+  candidates: VideoCandidate[]
+): VideoCandidate[] {
+  const latestByPlatform = new Map<string, VideoCandidate>()
+
+  for (const candidate of candidates) {
+    const current = latestByPlatform.get(candidate.platformName)
+    if (!current || candidate.mtimeMs > current.mtimeMs) {
+      latestByPlatform.set(candidate.platformName, candidate)
+    }
+  }
+
+  return [...latestByPlatform.values()].sort((a, b) =>
+    a.platformName.localeCompare(b.platformName)
+  )
+}
+
+function toProjectRelativePath(targetPath: string): string {
+  const relativePath = relative(process.cwd(), targetPath)
+  if (relativePath.startsWith('.')) {
+    return relativePath
+  }
+  return `./${relativePath}`
+}
+
+function errorToString(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function normalizePathForMatch(value: string): string {
+  return value.replaceAll('\\', '/').replace(/^\.\/+/, '')
+}
+
+export function selectVideoCandidateByFile(
+  candidates: VideoCandidate[],
+  options: { artifactsDir: string; videoFile: string }
+): VideoCandidate {
+  const requestedValue = options.videoFile.trim()
+  if (requestedValue.length === 0) {
+    throw new Error('--video-file is required')
+  }
+
+  const artifactsRoot = resolve(options.artifactsDir)
+  const requestedAbsolutePath = resolve(requestedValue)
+  const requestedPathKey = normalizePathForMatch(requestedValue)
+
+  const matches = candidates.filter((candidate) => {
+    const candidateAbsolutePath = resolve(candidate.videoPath)
+    if (candidateAbsolutePath === requestedAbsolutePath) {
+      return true
+    }
+
+    const candidateBaseName = basename(candidate.videoPath)
+    if (candidateBaseName === requestedValue) {
+      return true
+    }
+
+    const relativeToCwd = normalizePathForMatch(
+      relative(process.cwd(), candidateAbsolutePath)
+    )
+    if (relativeToCwd === requestedPathKey) {
+      return true
+    }
+
+    const relativeToArtifacts = normalizePathForMatch(
+      relative(artifactsRoot, candidateAbsolutePath)
+    )
+    return relativeToArtifacts === requestedPathKey
+  })
+
+  if (matches.length === 1) {
+    return matches[0]
+  }
+
+  if (matches.length === 0) {
+    const availableVideos = candidates.map((candidate) =>
+      toProjectRelativePath(candidate.videoPath)
+    )
+    throw new Error(
+      [
+        `No video matched --video-file "${options.videoFile}".`,
+        'Available videos:',
+        ...availableVideos.map((videoPath) => `- ${videoPath}`)
+      ].join('\n')
+    )
+  }
+
+  throw new Error(
+    [
+      `--video-file "${options.videoFile}" matched ${matches.length} videos.`,
+      'Please pass a more specific path.',
+      ...matches.map((match) => `- ${toProjectRelativePath(match.videoPath)}`)
+    ].join('\n')
+  )
+}
+
+async function collectVideoCandidates(
+  artifactsDir: string
+): Promise<VideoCandidate[]> {
+  const absoluteArtifactsDir = resolve(artifactsDir)
+  const videoPaths = globSync('**/qa-session.mp4', {
+    cwd: absoluteArtifactsDir,
+    absolute: true,
+    nodir: true
+  }).sort()
+
+  const candidates = await Promise.all(
+    videoPaths.map(async (videoPath) => {
+      const videoStat = await stat(videoPath)
+      return {
+        platformName: extractPlatformFromVideoPath(videoPath),
+        videoPath,
+        mtimeMs: videoStat.mtimeMs
+      }
+    })
+  )
+
+  return candidates
+}
+
+function getMimeType(filePath: string): string {
+  const ext = extname(filePath).toLowerCase()
+  const mimeMap: Record<string, string> = {
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime',
+    '.avi': 'video/x-msvideo',
+    '.mkv': 'video/x-matroska',
+    '.m4v': 'video/mp4'
+  }
+  return mimeMap[ext] || 'video/mp4'
+}
+
+function buildReviewPrompt(options: {
+  platformName: string
+  videoPath: string
+  prContext: string
+  isComparative: boolean
+}): string {
+  const { platformName, videoPath, prContext, isComparative } = options
+
+  if (isComparative) {
+    return buildComparativePrompt(platformName, videoPath, prContext)
+  }
+
+  return buildSingleVideoPrompt(platformName, videoPath, prContext)
+}
+
+function buildComparativePrompt(
+  platformName: string,
+  videoPath: string,
+  prContext: string
+): string {
+  const lines = [
+    'You are a senior QA engineer performing a BEFORE/AFTER comparison review.',
+    '',
+    'You are given TWO videos:',
+    '- **Video 1 (BEFORE)**: The main branch BEFORE the PR. This shows the OLD behavior.',
+    '- **Video 2 (AFTER)**: The PR branch AFTER the changes. This shows the NEW behavior.',
+    '',
+    'Both videos show the same test steps executed on different code versions.',
+    ''
+  ]
+
+  if (prContext) {
+    lines.push('## PR Context', prContext, '')
+  }
+
+  lines.push(
+    '## Your Task',
+    `Platform: "${platformName}". After video: ${toProjectRelativePath(videoPath)}.`,
+    '',
+    '1. **BEFORE video**: Does it demonstrate the old behavior or bug that the PR aims to fix?',
+    '   Describe what you observe — this establishes the baseline.',
+    '2. **AFTER video**: Does it prove the PR fix works? Is the intended new behavior visible?',
+    '3. **Comparison**: What specifically changed between before and after?',
+    '4. **Regressions**: Did the PR introduce any new problems visible in the AFTER video',
+    '   that were NOT present in the BEFORE video?',
+    '',
+    'Note: Brief black frames during page transitions are NORMAL.',
+    'Report only concrete, visible differences. Avoid speculation.',
+    '',
+    'Return markdown with these sections exactly:',
+    '## Summary',
+    '(What the PR changes, whether BEFORE confirms the old behavior, whether AFTER proves the fix)',
+    '',
+    '## Behavior Changes',
+    'Summarize ALL behavioral differences as a markdown TABLE:',
+    '| Behavior | Before (main) | After (PR) | Verdict |',
+    '',
+    '- **Behavior**: short name for the behavior (e.g. "Save shortcut label", "Menu hover style")',
+    '- **Before (main)**: how it works/looks in the BEFORE video',
+    '- **After (PR)**: how it works/looks in the AFTER video',
+    '- **Verdict**: `Fixed`, `Improved`, `Changed`, `Regression`, or `No Change`',
+    '',
+    'One row per distinct behavior. Include both changed AND unchanged key behaviors',
+    'that were tested, so reviewers can confirm nothing was missed.',
+    '',
+    '## Timeline Comparison',
+    'Present a chronological frame-by-frame comparison as a markdown TABLE:',
+    '| Time | Type | Severity | Before (main) | After (PR) |',
+    '',
+    '- **Time**: timestamp or range from the videos (e.g. `0:05-0:08`)',
+    '- **Type**: category such as `Visual`, `Behavior`, `Layout`, `Text`, `Animation`, `Menu`, `State`',
+    '- **Severity**: `None` (neutral change), `Fixed` (bug resolved), `Regression`, `Minor`, `Major`',
+    '- **Before (main)**: what is observed in the BEFORE video at that time',
+    '- **After (PR)**: what is observed in the AFTER video at that time',
+    '',
+    'Include one row per distinct observable difference. If behavior is identical at a timestamp,',
+    'omit that row. Focus on meaningful differences, not narrating every frame.',
+    '',
+    '## Confirmed Issues',
+    'For each issue, use this exact format:',
+    '',
+    '### [Short issue title]',
+    '`SEVERITY` `TIMESTAMP` `Confidence: LEVEL`',
+    '',
+    '[Description — specify whether it appears in BEFORE, AFTER, or both]',
+    '',
+    '**Evidence:** [What you observed at the given timestamp in which video]',
+    '',
+    '**Suggested Fix:** [Actionable recommendation]',
+    '',
+    '---',
+    '',
+    '## Possible Issues (Needs Human Verification)',
+    '## Overall Risk',
+    '(Assess whether the PR achieves its goal based on the before/after comparison)'
+  )
+
+  return lines.filter(Boolean).join('\n')
+}
+
+function buildSingleVideoPrompt(
+  platformName: string,
+  videoPath: string,
+  prContext: string
+): string {
+  const lines = [
+    'You are a senior QA engineer reviewing a UI test session recording.',
+    ''
+  ]
+
+  const isIssueContext =
+    prContext &&
+    /^### Issue #|^Title:.*\bbug\b|^This video attempts to reproduce/im.test(
+      prContext
+    )
+
+  if (prContext) {
+    if (isIssueContext) {
+      lines.push(
+        '## Issue Context',
+        'This video attempts to reproduce a reported bug on the main branch.',
+        'Your review MUST evaluate whether the reported bug is visible and reproducible.',
+        '',
+        prContext,
+        '',
+        '## Review Instructions',
+        '1. Does the video demonstrate the reported bug occurring?',
+        '2. Is the bug clearly visible and reproducible from the steps shown?',
+        '3. Are there any other issues visible during the reproduction attempt?',
+        ''
+      )
+    } else {
+      lines.push(
+        '## PR Context',
+        'The video is a QA session testing a specific pull request.',
+        'Your review MUST evaluate whether the PR achieves its stated purpose.',
+        '',
+        prContext,
+        '',
+        '## Review Instructions',
+        "1. Does the video demonstrate the PR's intended behavior working correctly?",
+        '2. Are there regressions or side effects caused by the PR changes?',
+        '3. Does the observed behavior match what the PR claims to implement/fix?',
+        ''
+      )
+    }
+  }
+
+  lines.push(
+    `Review this QA session video for platform "${platformName}".`,
+    `Source video: ${toProjectRelativePath(videoPath)}.`,
+    'The video shows the full test session — analyze it chronologically.',
+    'Focus on UI regressions, broken states, visual glitches, unreadable text, missing labels/i18n, and clear workflow failures.',
+    'Note: Brief black frames during page transitions are NORMAL and should NOT be reported as issues.',
+    'Report only concrete, visible problems and avoid speculation.',
+    'If confidence is low, mark it explicitly.',
+    '',
+    'Return markdown with these sections exactly:',
+    '## Summary',
+    isIssueContext
+      ? '(Explain what bug was reported and whether the video confirms it is reproducible)'
+      : prContext
+        ? '(Explain what the PR intended and whether the video confirms it works)'
+        : '',
+    '## Confirmed Issues',
+    'For each confirmed issue, use this exact format (one block per issue):',
+    '',
+    '### [Short issue title]',
+    '`HIGH` `01:03` `Confidence: High`',
+    '',
+    '[Description of the issue — what went wrong and what was expected]',
+    '',
+    '**Evidence:** [What you observed in the video at the given timestamp]',
+    '',
+    '**Suggested Fix:** [Actionable recommendation]',
+    '',
+    '---',
+    '',
+    'The first line after the heading MUST be exactly three backtick-wrapped labels:',
+    '`SEVERITY` `TIMESTAMP` `Confidence: LEVEL`',
+    'Do NOT use a table for issues — use the block format above.',
+    '## Possible Issues (Needs Human Verification)',
+    '## Overall Risk'
+  )
+
+  return lines.filter(Boolean).join('\n')
+}
+
+const MAX_VIDEO_BYTES = 100 * 1024 * 1024
+
+async function readVideoFile(videoPath: string): Promise<Buffer> {
+  const fileStat = await stat(videoPath)
+  if (fileStat.size > MAX_VIDEO_BYTES) {
+    throw new Error(
+      `Video ${basename(videoPath)} is ${formatBytes(fileStat.size)}, exceeds ${formatBytes(MAX_VIDEO_BYTES)} limit`
+    )
+  }
+  return readFile(videoPath)
+}
+
+async function requestGeminiReview(options: {
+  apiKey: string
+  model: string
+  platformName: string
+  videoPath: string
+  beforeVideoPath: string
+  timeoutMs: number
+  prContext: string
+}): Promise<string> {
+  const genAI = new GoogleGenerativeAI(options.apiKey)
+  const model = genAI.getGenerativeModel({ model: options.model })
+
+  const isComparative = options.beforeVideoPath.length > 0
+  const prompt = buildReviewPrompt({
+    platformName: options.platformName,
+    videoPath: options.videoPath,
+    prContext: options.prContext,
+    isComparative
+  })
+
+  const parts: Array<
+    { text: string } | { inlineData: { mimeType: string; data: string } }
+  > = [{ text: prompt }]
+
+  if (isComparative) {
+    const beforeBuffer = await readVideoFile(options.beforeVideoPath)
+    parts.push(
+      { text: 'Video 1 — BEFORE (main branch):' },
+      {
+        inlineData: {
+          mimeType: getMimeType(options.beforeVideoPath),
+          data: beforeBuffer.toString('base64')
+        }
+      }
+    )
+  }
+
+  const afterBuffer = await readVideoFile(options.videoPath)
+  if (isComparative) {
+    parts.push({ text: 'Video 2 — AFTER (PR branch):' })
+  }
+  parts.push({
+    inlineData: {
+      mimeType: getMimeType(options.videoPath),
+      data: afterBuffer.toString('base64')
+    }
+  })
+
+  const result = await model.generateContent(parts, {
+    timeout: options.timeoutMs
+  })
+  const response = result.response
+  const text = response.text()
+
+  if (!text || text.trim().length === 0) {
+    throw new Error('Gemini API returned no output text')
+  }
+
+  return text.trim()
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+function buildReportMarkdown(input: {
+  platformName: string
+  model: string
+  videoPath: string
+  videoSizeBytes: number
+  beforeVideoPath?: string
+  beforeVideoSizeBytes?: number
+  reviewText: string
+}): string {
+  const headerLines = [
+    `# ${input.platformName} QA Video Report`,
+    '',
+    `- Generated at: ${new Date().toISOString()}`,
+    `- Model: \`${input.model}\``
+  ]
+
+  if (input.beforeVideoPath) {
+    headerLines.push(
+      `- Before video: \`${toProjectRelativePath(input.beforeVideoPath)}\` (${formatBytes(input.beforeVideoSizeBytes ?? 0)})`,
+      `- After video: \`${toProjectRelativePath(input.videoPath)}\` (${formatBytes(input.videoSizeBytes)})`,
+      '- Mode: **Comparative (before/after)**'
+    )
+  } else {
+    headerLines.push(
+      `- Source video: \`${toProjectRelativePath(input.videoPath)}\``,
+      `- Video size: ${formatBytes(input.videoSizeBytes)}`
+    )
+  }
+
+  headerLines.push('', '## AI Review', '')
+  return `${headerLines.join('\n')}${input.reviewText.trim()}\n`
+}
+
+async function reviewVideo(
+  video: VideoCandidate,
+  options: CliOptions,
+  apiKey: string
+): Promise<void> {
+  let prContext = ''
+  if (options.prContext) {
+    try {
+      prContext = await readFile(options.prContext, 'utf-8')
+      process.stdout.write(
+        `[${video.platformName}] Loaded PR context from ${options.prContext}\n`
+      )
+    } catch {
+      process.stdout.write(
+        `[${video.platformName}] Warning: Could not read PR context file ${options.prContext}\n`
+      )
+    }
+  }
+
+  const beforeVideoPath = options.beforeVideo
+    ? resolve(options.beforeVideo)
+    : ''
+
+  if (beforeVideoPath) {
+    const beforeStat = await stat(beforeVideoPath)
+    process.stdout.write(
+      `[${video.platformName}] Before video: ${toProjectRelativePath(beforeVideoPath)} (${formatBytes(beforeStat.size)})\n`
+    )
+  }
+
+  process.stdout.write(
+    `[${video.platformName}] Sending ${beforeVideoPath ? '2 videos (comparative)' : 'video'} to ${options.model}\n`
+  )
+
+  const reviewText = await requestGeminiReview({
+    apiKey,
+    model: options.model,
+    platformName: video.platformName,
+    videoPath: video.videoPath,
+    beforeVideoPath,
+    timeoutMs: options.requestTimeoutMs,
+    prContext
+  })
+
+  const videoStat = await stat(video.videoPath)
+  const outputPath = resolve(
+    options.outputDir,
+    `${video.platformName}-qa-video-report.md`
+  )
+
+  const reportInput: Parameters<typeof buildReportMarkdown>[0] = {
+    platformName: video.platformName,
+    model: options.model,
+    videoPath: video.videoPath,
+    videoSizeBytes: videoStat.size,
+    reviewText
+  }
+
+  if (beforeVideoPath) {
+    const beforeStat = await stat(beforeVideoPath)
+    reportInput.beforeVideoPath = beforeVideoPath
+    reportInput.beforeVideoSizeBytes = beforeStat.size
+  }
+
+  const reportMarkdown = buildReportMarkdown(reportInput)
+
+  await mkdir(dirname(outputPath), { recursive: true })
+  await writeFile(outputPath, reportMarkdown, 'utf-8')
+
+  process.stdout.write(
+    `[${video.platformName}] Wrote ${toProjectRelativePath(outputPath)}\n`
+  )
+}
+
+function isExecutedAsScript(metaUrl: string): boolean {
+  const modulePath = fileURLToPath(metaUrl)
+  const scriptPath = process.argv[1] ? resolve(process.argv[1]) : ''
+  return modulePath === scriptPath
+}
+
+async function main(): Promise<void> {
+  const options = parseCliOptions(process.argv.slice(2))
+  const candidates = await collectVideoCandidates(options.artifactsDir)
+
+  if (candidates.length === 0) {
+    process.stdout.write(
+      `No qa-session.mp4 files found under ${toProjectRelativePath(resolve(options.artifactsDir))}\n`
+    )
+    return
+  }
+
+  const selectedVideo = selectVideoCandidateByFile(candidates, {
+    artifactsDir: options.artifactsDir,
+    videoFile: options.videoFile
+  })
+
+  process.stdout.write(
+    `Selected ${selectedVideo.platformName}: ${toProjectRelativePath(selectedVideo.videoPath)}\n`
+  )
+
+  if (options.dryRun) {
+    process.stdout.write('\nDry run mode enabled, no API calls were made.\n')
+    return
+  }
+
+  const apiKey = process.env.GEMINI_API_KEY
+  if (!apiKey) {
+    throw new Error('GEMINI_API_KEY is required unless --dry-run is set')
+  }
+
+  await reviewVideo(selectedVideo, options, apiKey)
+}
+
+if (isExecutedAsScript(import.meta.url)) {
+  void main().catch((error: unknown) => {
+    const message = errorToString(error)
+    process.stderr.write(`qa-video-review failed: ${message}\n`)
+    process.exit(1)
+  })
+}