create-claude-workspace 2.3.21 → 2.3.22

package/dist/scheduler/index.mjs

@@ -5,7 +5,7 @@ import { resolve } from 'node:path';
 import { existsSync, mkdirSync } from 'node:fs';
 import { config as dotenvConfig } from '@dotenvx/dotenvx';
 import { SCHEDULER_DEFAULTS } from './types.mjs';
-import { detectCIPlatform } from './git/ci-watcher.mjs';
+import { detectCIPlatform, checkPlatformCLI, installPlatformCLI } from './git/ci-watcher.mjs';
 import { fetchOpenIssues } from './tasks/issue-source.mjs';
 import { emptyState, readState, writeState, appendEvent, createEvent } from './state/state.mjs';
 import { WorkerPool } from './agents/worker-pool.mjs';
@@ -256,6 +256,26 @@ export async function runScheduler(opts) {
     else {
         state = emptyState(opts.concurrency);
     }
+    // Ensure platform CLI is available before task mode detection
+    const detectedPlatform = detectCIPlatform(opts.projectDir);
+    if (detectedPlatform !== 'none') {
+        const cliError = checkPlatformCLI(detectedPlatform);
+        if (cliError) {
+            const cli = detectedPlatform === 'github' ? 'gh' : 'glab';
+            logger.warn(`${cliError} — attempting auto-install of ${cli}`);
+            const installResult = installPlatformCLI(detectedPlatform);
+            if (installResult.success) {
+                logger.info(`Installed ${cli} via ${installResult.method}`);
+                const authError = checkPlatformCLI(detectedPlatform);
+                if (authError?.includes('not authenticated')) {
+                    logger.warn(`${cli} installed but needs authentication. Run: ${cli} auth login`);
+                }
+            }
+            else {
+                logger.error(`Failed to install ${cli}: ${installResult.error}`);
+            }
+        }
+    }
     // Task mode detection
     if (opts.taskMode) {
         state.taskMode = opts.taskMode;

package/dist/scheduler/loop.mjs

@@ -11,7 +11,7 @@ import { recordSession, getSession, clearSession } from './state/session.mjs';
 import { createWorktree, commitInWorktree, getChangedFiles, cleanupWorktree, mergeToMain, syncMain, pushWorktree, forcePushWorktree, rebaseOnMain, cleanMainForMerge, popStash, getMainBranch, listWorktrees, listOrphanedWorktrees, isBranchMerged, getCurrentBranch, hasUncommittedChanges, deleteBranchRemote, cleanMergedBranches, pruneRemoteBranches, findStaleUnmergedBranches, } from './git/manager.mjs';
 import { createPR, getPRStatus, getPRComments, mergePR, closePR } from './git/pr-manager.mjs';
 import { scanAgents } from './agents/health-checker.mjs';
-import { detectCIPlatform, checkPlatformCLI, installPlatformCLI, fetchFailureLogs } from './git/ci-watcher.mjs';
+import { detectCIPlatform, fetchFailureLogs } from './git/ci-watcher.mjs';
 import { createRelease } from './git/release.mjs';
 import { processInbox, addTaskMessageToTask } from './tasks/inbox.mjs';
 import { buildPlanPrompt, buildImplementPrompt, buildQAPrompt, buildReviewPrompt, buildReworkPrompt, buildCIFixPrompt, buildPRCommentPrompt, } from './agents/prompt-builder.mjs';
@@ -62,29 +62,6 @@ export async function runIteration(deps) {
             // Caller (scheduler.mts) handles pause state
         }
     }
-    // Pre-flight: ensure platform CLI is available
-    if (!state._recoveryDone) {
-        const ciPlatformPreflight = detectCIPlatform(projectDir);
-        if (ciPlatformPreflight !== 'none') {
-            const cliError = checkPlatformCLI(ciPlatformPreflight);
-            if (cliError) {
-                const cli = ciPlatformPreflight === 'github' ? 'gh' : 'glab';
-                logger.warn(`${cliError} — attempting auto-install of ${cli}`);
-                const installResult = installPlatformCLI(ciPlatformPreflight);
-                if (installResult.success) {
-                    logger.info(`Installed ${cli} via ${installResult.method}`);
-                    // Check auth after install
-                    const authError = checkPlatformCLI(ciPlatformPreflight);
-                    if (authError?.includes('not authenticated')) {
-                        logger.warn(`${cli} installed but needs authentication. Run: ${cli} auth login`);
-                    }
-                }
-                else {
-                    logger.error(`Failed to install ${cli}: ${installResult.error}`);
-                }
-            }
-        }
-    }
     // Pre-flight: commit uncommitted changes on main before any work
     if (!state._recoveryDone) {
         if (hasUncommittedChanges(projectDir)) {

package/dist/template/.claude/agents/orchestrator.md

@@ -568,7 +568,7 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
   - Ask for: TEST PLAN per layer, then full implementation, then RUN all tests and report results
 - **E2E tests**: Include in the prompt: "Write E2E tests for the following user flows: [list flows from TESTING section]. Use Playwright. Ensure E2E project is set up (scaffold via `nx g @nx/playwright:configuration` if missing)."
 - **Integration tests**: Include in the prompt: "Write integration tests for: [list endpoints/services from TESTING section]. Test real request/response cycles (use test server or supertest), database operations against test DB, and public API contracts. Keep integration tests in `*.integration.spec.ts` files (co-located next to source, same as unit tests)."
-- **Visual regression tests**: Include in the prompt: "Write visual regression tests (`*.vrt.spec.ts`) for these pages/views: [list from TESTING section]. Use the VRT template with 3-viewport matrix (mobile 375px, tablet 768px, desktop 1280px). Use `maxDiffPixelRatio: 0.01` and `fullPage: true` for page screenshots. Mask dynamic content (timestamps, user avatars) with `mask` option."
+- **Visual regression tests**: Include in the prompt: "Write visual regression tests (`*.vrt.spec.ts`) for these pages/views: [list from TESTING section]. Use the VRT template with 3-viewport matrix (mobile 375px, tablet 768px, desktop 1280px). Use `maxDiffPixelRatio: 0.01`. For page-level VRT use `expect(page)` with `fullPage: true`. For section/component VRT (hero, header, modal, etc.) use `expect(page.locator('...'))` to screenshot only the element — NEVER use `fullPage: true` on `page` for section-level tests. Mask dynamic content (timestamps, user avatars) with `mask` option. After generating baselines, visually verify every screenshot with the Read tool — check that each captures the correct scope (element vs full page) and shows fully rendered content."
 - **Baseline updates for intentional visual changes**: If the architect's plan describes intentional visual changes to existing pages (redesign, new theme, layout restructure), add to the test-engineer prompt: "Existing VRT baselines will need updating. After writing/updating VRT tests, run `nx e2e [APP]-e2e -- --update-snapshots` to regenerate baselines. Include the updated baseline images in the commit."
 - **Coverage requirement**: Include in the prompt: "Run ALL tests with `--coverage`. Coverage MUST stay above 80% (statements, branches, functions, lines). If coverage drops below 80%, add missing tests before returning."
 - **E2E tests**: Include in the prompt: "Start dev server, wait for readiness, run E2E tests, then kill the dev server port. Use `bunx kill-port 4200` for cleanup."

package/dist/template/.claude/agents/test-engineer.md

@@ -309,11 +309,17 @@ Automated pixel-by-pixel comparison against baseline screenshots. Catches uninte
 **Key behavior:** `toHaveScreenshot()` has built-in auto-retry — it takes consecutive screenshots until two consecutive captures match (page is stable), THEN compares against the golden baseline. This means it inherently waits for rendering to settle.
 
 ### When to write VRT tests
-- **Page-level views** — each route/page gets a VRT test covering default state
+- **Page-level views** — each route/page gets a VRT test covering default state. Use `expect(page).toHaveScreenshot(name, { fullPage: true })`
+- **Key sections/components** — hero, header, footer, sidebar, card grid, modal, form. Use `expect(page.locator('...')).toHaveScreenshot(name)` — screenshots the **element only**, not the full page
 - **Key interactive states** — modal open, form validation errors, empty state, loaded state, skeleton/loading
 - **Multi-component compositions** — dashboards, listings, onboarding flows
 - **Do NOT write VRT for**: individual dumb components in isolation, backend-only tasks, pages with highly dynamic content (live charts, video feeds, real-time data)
 
+**Choosing page vs element screenshot:**
+- If the test name describes the ENTIRE page (e.g., "checkout page default") → `expect(page)` + `fullPage: true`
+- If the test name describes a SECTION or COMPONENT (e.g., "hero section", "pricing cards") → `expect(locator)` without `fullPage`
+- **Rule of thumb**: the screenshot name should match what's actually captured. A file named `hero-desktop.png` must show only the hero, not the whole page.
+
 ### VRT file naming
 - `*.vrt.spec.ts` suffix — co-located with functional E2E tests in `apps/[APP]-e2e/src/` or `e2e/`
 - Example: `checkout.vrt.spec.ts` beside `checkout.spec.ts`
@@ -338,6 +344,7 @@ const VIEWPORTS = [
   { name: 'desktop', width: 1280, height: 720 },
 ] as const;
 
+// PAGE-LEVEL VRT — use fullPage: true, subject is the entire page
 test.describe('Checkout Page — Visual Regression', () => {
   for (const vp of VIEWPORTS) {
     test.describe(vp.name, () => {
@@ -345,11 +352,8 @@ test.describe('Checkout Page — Visual Regression', () => {
 
       test('default state', async ({ page }) => {
         await page.goto('/checkout');
-        // Wait for fonts — critical for consistent rendering
         await page.waitForFunction(() => document.fonts.ready);
-        // Wait for key content to be visible
         await expect(page.locator('[data-testid="checkout-form"]')).toBeVisible();
-        // toHaveScreenshot() auto-retries until two consecutive captures match
         await expect(page).toHaveScreenshot(`checkout-default-${vp.name}.png`, {
           fullPage: true,
         });
@@ -359,7 +363,28 @@ test.describe('Checkout Page — Visual Regression', () => {
         await page.goto('/checkout');
         await page.waitForFunction(() => document.fonts.ready);
         await page.getByRole('button', { name: 'Pay' }).click();
-        await expect(page).toHaveScreenshot(`checkout-errors-${vp.name}.png`);
+        await expect(page).toHaveScreenshot(`checkout-errors-${vp.name}.png`, {
+          fullPage: true,
+        });
+      });
+    });
+  }
+});
+
+// SECTION-LEVEL VRT — screenshot a specific element, NOT the full page
+// Use this for hero sections, headers, modals, forms, cards, etc.
+test.describe('Landing Page Hero — Visual Regression', () => {
+  for (const vp of VIEWPORTS) {
+    test.describe(vp.name, () => {
+      test.use({ viewport: { width: vp.width, height: vp.height } });
+
+      test('hero section', async ({ page }) => {
+        await page.goto('/');
+        await page.waitForFunction(() => document.fonts.ready);
+        const hero = page.locator('[data-testid="hero-section"]');
+        await expect(hero).toBeVisible();
+        // Screenshot the ELEMENT, not the page — captures only the hero
+        await expect(hero).toHaveScreenshot(`hero-${vp.name}.png`);
       });
     });
   }
@@ -388,7 +413,7 @@ export default defineConfig({
 - `threshold: 0.2` — per-pixel YIQ color difference tolerance (0 = exact, 1 = anything)
 - `animations: 'disabled'` — finite animations fast-forwarded to end, infinite reset
 - `scale: 'css'` — consistent screenshot size regardless of device pixel ratio
-- `fullPage: true` for page-level screenshots (captures below-fold), omit for component-state
+- `fullPage: true` for page-level screenshots (captures below-fold content). **Only use for page-level VRT** where the entire page is the subject. For section/component-state VRT (hero, header, modal, form), use **element-level screenshots** instead — see below
 - `mask: Locator[]` — overlay elements with colored boxes (hides dynamic content)
 - `stylePath: string | string[]` — CSS file injected before screenshot, **penetrates Shadow DOM** (unlike `mask`)
 
@@ -424,6 +449,25 @@ Remove `{platform}` from the path since all baselines are Linux. Set in `playwri
 - **First run** creates baselines (auto-retry takes two identical screenshots to confirm stability)
 - In CI: use the Playwright Docker image (`mcr.microsoft.com/playwright`) — same version as local Docker generation
 
+### Baseline validation (MANDATORY after first run)
+
+After generating baselines (first run or `--update-snapshots`), you MUST visually verify every generated screenshot before committing:
+
+1. **Read each baseline image** using the Read tool — you can view images directly
+2. **Verify correct scope**: Does the screenshot capture ONLY the intended subject?
+   - Page-level VRT (`fullPage: true` on `page`) → should show the entire page with all sections
+   - Section/component VRT (on `locator`) → should show ONLY that section/component, not the whole page
+   - **Common mistake**: using `expect(page).toHaveScreenshot()` with `fullPage: true` for a section-level test (e.g., "hero") — this captures the entire page instead of just the hero. Fix: screenshot the element locator, not the page
+3. **Verify content is rendered**: Screenshot must show actual content, not blank/loading/skeleton state
+4. **Verify no visual artifacts**: No overlapping elements, no broken layout, no missing images
+5. **If any screenshot is wrong**: fix the test (wrong locator, wrong wait, page vs element), delete the bad baseline, re-run to generate correct one, and re-validate
+
+**Quick validation checklist per screenshot:**
+- [ ] Shows the correct scope (element vs full page)
+- [ ] Content is fully rendered (not loading/skeleton)
+- [ ] No visual artifacts or layout breaks
+- [ ] Responsive variant looks correct for its viewport size
+
 ### Running VRT tests
 ```bash
 # Run VRT via Nx (CI or Docker)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-workspace",
-  "version": "2.3.21",
+  "version": "2.3.22",
   "author": "",
   "repository": {
     "type": "git",