@postxl/generators 1.16.0 → 1.17.0

package/dist/base/template/.claude/commands/README.md

@@ -0,0 +1,65 @@
+# Custom Commands for Claude Code
+
+This directory contains custom command documentation that Claude Code can reference when assisting with development tasks.
+
+## Available Commands
+
+### 1. Run E2E Tests (`run-e2e-tests.md`)
+Comprehensive instructions for running end-to-end tests using Playwright.
+
+**Trigger phrases:**
+- "run e2e tests"
+- "run end-to-end tests"
+- "execute e2e test suite"
+
+### 2. Fix CI (`fix-ci.md`)
+Guidance for troubleshooting and fixing CI/CD pipeline issues.
+
+**Trigger phrases:**
+- "fix ci"
+- "help with continuous integration"
+
+### 3. Browser Observe (`browser-observe.md`)
+Instructions for browser-based testing and observation workflows.
+
+**Trigger phrases:**
+- "observe browser"
+- "start browser observation"
+
+### 4. Prepare E2E Tests (`prepare-e2e-tests.md`)
+Analyzes code changes, determines needed E2E test coverage, writes test specs, and runs them to verify they pass.
+
+**Trigger phrases:**
+- "prepare e2e tests"
+- "write e2e tests for my changes"
+- "add e2e test coverage"
+
+## How It Works
+
+When you ask Claude to perform one of these tasks, it will:
+1. Automatically detect the request based on your natural language
+2. Reference the appropriate command file
+3. Follow the detailed instructions in that file
+4. Execute the necessary steps to complete the task
+
+## Adding New Commands
+
+To add a new custom command:
+
+1. Create a new markdown file in this directory with a descriptive name (e.g., `deploy-staging.md`)
+2. Write clear, detailed instructions including:
+   - Overview of the task
+   - Prerequisites
+   - Step-by-step instructions
+   - Common issues and troubleshooting
+   - Examples
+3. Update this README to list the new command
+5. Commit all files to version control
+
+## Best Practices
+
+- **Be specific**: Include exact commands, file paths, and configuration details
+- **Include context**: Explain why certain steps are necessary
+- **Add troubleshooting**: Document common errors and solutions
+- **Use examples**: Show concrete examples of usage
+- **Keep updated**: Review and update commands as the project evolves

package/dist/base/template/.claude/settings.json

@@ -4,6 +4,8 @@
     "Read CLAUDE.md for project-specific guidance before making changes",
     "This is a PostXL-generated project - see the main PostXL monorepo CLAUDE.md for full documentation",
     "Always run type checks after code changes: pnpm run test:types",
-    "Use @postxl/ui-components for all UI elements - never create custom generic UI primitives"
+    "Use @postxl/ui-components for all UI elements - never create custom generic UI primitives",
+    "When asked to 'run e2e tests', 'run end-to-end tests', or 'execute e2e': ALWAYS read the detailed instructions from .claude/commands/run-e2e-tests.md first, then run the automated script at scripts/e2e.sh from the project root",
+    "When significant frontend or backend changes are made (new pages, routes, forms, tables, or API endpoints), proactively suggest running /prepare-e2e-tests to ensure E2E test coverage"
   ]
 }

package/dist/base/template/.github/.copilot-prompts.json

@@ -0,0 +1,22 @@
+{
+  "prompts": [
+    {
+      "name": "Run E2E Tests",
+      "description": "Run end-to-end tests using Playwright",
+      "path": "../.claude/commands/run-e2e-tests.md",
+      "tags": ["testing", "e2e", "playwright"]
+    },
+    {
+      "name": "Fix CI",
+      "description": "Help fix CI/CD pipeline issues",
+      "path": "../.claude/commands/fix-ci.md",
+      "tags": ["ci", "devops"]
+    },
+    {
+      "name": "Browser Observe",
+      "description": "Browser testing and observation workflows",
+      "path": "../.claude/commands/browser-observe.md",
+      "tags": ["testing", "browser"]
+    }
+  ]
+}

package/dist/e2e/e2e.generator.js

@@ -54,7 +54,22 @@ exports.generator = {
     },
     generate: async (context) => {
         const vfs = new Generator.VirtualFileSystem();
-        const templateContext = { schema: context.schema };
+        const { projectType, slug } = context.schema;
+        const isWorkspace = projectType === 'workspace';
+        // Template context with project-type-aware values
+        const templateContext = {
+            schema: context.schema,
+            // For e2e.sh
+            monorepoRootExpr: isWorkspace ? '"$(cd "$PROJECT_DIR/../.." && pwd)"' : '"$PROJECT_DIR"',
+            dockerWorkDir: isWorkspace ? `/pxl/projects/${slug}/e2e` : '/pxl/e2e',
+            nodeShimsCleanup: isWorkspace
+                ? 'rm -f /pxl/node_modules/.bin/node /pxl/projects/*/node_modules/.bin/node 2>/dev/null'
+                : 'rm -f /pxl/node_modules/.bin/node 2>/dev/null',
+            // For run-e2e-tests.md
+            cdProjectDir: isWorkspace ? `cd projects/${slug}\n` : '',
+            backendPath: isWorkspace ? `projects/${slug}/backend` : 'backend',
+            frontendPath: isWorkspace ? `projects/${slug}/frontend` : 'frontend',
+        };
         // Load e2e folder, excluding files that need template substitution
         await vfs.loadFolder({
             diskPath: path.resolve(__dirname, './template/e2e'),
@@ -70,6 +85,33 @@ exports.generator = {
             throw new Error(`Failed to generate package.json: ${packageJsonContent.unwrapErr().message}`);
         }
         vfs.write(`/e2e/${PACKAGE_JSON_FILENAME}`, packageJsonContent.unwrap());
+        // Generate e2e.sh with project-type-aware paths
+        const e2eShContent = await Generator.generateFromTemplate({
+            file: path.resolve(__dirname, './template/scripts/e2e.sh'),
+            context: templateContext,
+        });
+        if (e2eShContent.isErr()) {
+            throw new Error(`Failed to generate e2e.sh: ${e2eShContent.unwrapErr().message}`);
+        }
+        vfs.write('/scripts/e2e.sh', e2eShContent.unwrap());
+        // Generate run-e2e-tests.md with project-type-aware paths
+        const runE2eTestsMdContent = await Generator.generateFromTemplate({
+            file: path.resolve(__dirname, './template/.claude/commands/run-e2e-tests.md'),
+            context: templateContext,
+        });
+        if (runE2eTestsMdContent.isErr()) {
+            throw new Error(`Failed to generate run-e2e-tests.md: ${runE2eTestsMdContent.unwrapErr().message}`);
+        }
+        vfs.write('/.claude/commands/run-e2e-tests.md', runE2eTestsMdContent.unwrap());
+        // Generate prepare-e2e-tests.md with project-type-aware paths
+        const prepareE2eTestsMdContent = await Generator.generateFromTemplate({
+            file: path.resolve(__dirname, './template/.claude/commands/prepare-e2e-tests.md'),
+            context: templateContext,
+        });
+        if (prepareE2eTestsMdContent.isErr()) {
+            throw new Error(`Failed to generate prepare-e2e-tests.md: ${prepareE2eTestsMdContent.unwrapErr().message}`);
+        }
+        vfs.write('/.claude/commands/prepare-e2e-tests.md', prepareE2eTestsMdContent.unwrap());
         // write dynamic files
         vfs.write('/e2e/support/model-test-ids.ts', (0, model_test_id_generator_1.generateModelTestIds)(context.e2e));
         vfs.write('/scripts/docker.sh', (0, docker_sh_generator_1.generateDockerSh)(context));

package/dist/e2e/e2e.generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"e2e.generator.js","sourceRoot":"","sources":["../../src/e2e/e2e.generator.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAiC;AAEjC,6DAA8C;AAI9C,0EAAmE;AACnE,kFAA2E;AAE3E,MAAM,qBAAqB,GAAG,cAAc,CAAA;AAsB/B,QAAA,WAAW,GAAG,SAAS,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAA;AAErD,QAAA,SAAS,GAAiC;IACrD,EAAE,EAAE,mBAAW;IACf,QAAQ,EAAE,CAAC,mBAAW,CAAC;IAEvB,QAAQ,EAAE,CAAiD,GAAY,EAAiB,EAAE;QACxF,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;QACvF,OAAO;YACL,GAAG,GAAG;YACN,GAAG,EAAE;gBACH,OAAO,EAAE,EAAE;aACZ;SACF,CAAA;IACH,CAAC;IAED,QAAQ,EAAE,KAAK,EAAiC,OAAgB,EAAoB,EAAE;QACpF,MAAM,GAAG,GAAG,IAAI,SAAS,CAAC,iBAAiB,EAAE,CAAA;QAC7C,MAAM,eAAe,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAA;QAElD,mEAAmE;QACnE,MAAM,GAAG,CAAC,UAAU,CAAC;YACnB,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,gBAAgB,CAAC;YACnD,UAAU,EAAE,MAAM;YAClB,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,qBAAqB,CAAC;SAChE,CAAC,CAAA;QAEF,wCAAwC;QACxC,MAAM,kBAAkB,GAAG,MAAM,SAAS,CAAC,oBAAoB,CAAC;YAC9D,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,gBAAgB,EAAE,qBAAqB,CAAC;YACtE,OAAO,EAAE,eAAe;SACzB,CAAC,CAAA;QACF,IAAI,kBAAkB,CAAC,KAAK,EAAE,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,oCAAoC,kBAAkB,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,CAAA;QAC/F,CAAC;QACD,GAAG,CAAC,KAAK,CAAC,QAAQ,qBAAqB,EAAE,EAAE,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAA;QAEvE,sBAAsB;QACtB,GAAG,CAAC,KAAK,CAAC,gCAAgC,EAAE,IAAA,8CAAoB,EAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAA;QAC9E,GAAG,CAAC,KAAK,CAAC,oBAAoB,EAAE,IAAA,sCAAgB,EAAC,OAAO,CAAC,CAAC,CAAA;QAE1D,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAA;QAEnD,OAAO,OAAO,CAAA;IAChB,CAAC;CACF,CAAA"}
+{"version":3,"file":"e2e.generator.js","sourceRoot":"","sources":["../../src/e2e/e2e.generator.ts"],"names":[],"mappings":"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"}

package/dist/e2e/template/.claude/commands/prepare-e2e-tests.md

@@ -0,0 +1,251 @@
+# Prepare E2E Tests
+
+You are tasked with analyzing code changes and preparing end-to-end (E2E) tests for the <% schema.slug %> project.
+
+## Arguments
+
+- `$ARGUMENTS` - Optional: specific features or areas to focus testing on. If not provided, analyze the git diff automatically.
+
+## Overview
+
+This command analyzes your recent code changes, determines what E2E test coverage is needed, writes the test specs following existing patterns, and runs them to verify they pass.
+
+## Step 1: Analyze Changes
+
+### 1.1 Get Changed Files
+
+Determine what has changed by examining the git diff:
+
+```bash
+# If on a feature branch, diff against main
+git diff main...HEAD --name-only
+
+# Also check for any uncommitted changes
+git diff --name-only
+git diff --staged --name-only
+```
+
+If `$ARGUMENTS` was provided, focus analysis on the specified features or areas instead of the full diff.
+
+### 1.2 Categorize Changes
+
+Read each changed file and categorize it:
+
+- **Frontend pages/routes**: Files in `<% frontendPath %>/src/routes/` — need navigation tests, content verification, and visual snapshots
+- **Frontend components**: Files in `<% frontendPath %>/src/components/` or `<% frontendPath %>/src/pages/` — need interaction tests
+- **Backend endpoints/routers**: Files in `<% backendPath %>/libs/router-trpc/` or `<% backendPath %>/libs/actions/` — need frontend integration tests verifying data display
+- **Backend views**: Files in `<% backendPath %>/libs/view/` — need data display verification tests
+- **Shared types**: Files in `<% backendPath %>/libs/types/` — may affect existing tests
+- **Schema changes**: `postxl-schema.json` — affect models and may need comprehensive new tests
+- **Forms**: Components containing form elements (TanStack Form, inputs, selects) — need form interaction tests
+- **Tables/DataGrids**: Components using DataGrid — need data display, sorting, and filtering tests
+
+### 1.3 Read Changed Files
+
+For each changed file, read its content to understand:
+
+- What routes/URLs are added or modified
+- What data is displayed (model names, field names)
+- What user interactions are possible (clicks, form fills, navigation)
+- What test IDs are used (`data-test-id` attributes)
+
+Also read these reference files for context:
+
+```
+e2e/support/model-test-ids.ts       # Available test IDs
+e2e/fixtures/test-fixtures.ts       # Available test fixtures
+e2e/support/wait-for-page-loaded.ts # Page loading utility
+e2e/support/page-stability.ts       # API stability utility
+```
+
+### 1.4 Check Existing Test Coverage
+
+Read all existing spec files in `e2e/specs/` to understand what is already covered. Do not duplicate existing tests.
+
+## Step 2: Determine Test Coverage
+
+Based on the analysis, determine which tests to write:
+
+### For New Pages/Routes
+
+- **Navigation test**: Verify the page is accessible at its URL
+- **Content verification test**: Verify key content elements are visible
+- **Visual regression snapshot**: Capture a baseline screenshot with `toHaveScreenshot()`
+
+### For New Forms
+
+- **Form display test**: Verify form fields are rendered correctly
+- **Form interaction test**: Fill fields, submit, and verify success feedback
+- **Form validation test**: Submit with invalid data and verify error messages
+
+### For New Tables/Data Views
+
+- **Data display test**: Verify table renders with expected columns and data
+- **Sorting test**: Click column headers and verify sort order (if sortable)
+- **Empty state test**: Verify empty state message when no data exists
+
+### For API/Backend Changes
+
+- **Data integration test**: Verify the frontend correctly displays API data
+- **Error state test**: Verify error handling when API returns errors (if applicable)
+
+### For UI Component Changes
+
+- **Visual regression snapshot**: Capture screenshots of affected pages
+- **Interaction test**: Verify component interactions work correctly
+
+## Step 3: Write Tests
+
+### 3.1 Test File Structure
+
+Create new test files in `e2e/specs/` following the naming convention `<feature>.spec.ts`.
+
+**CRITICAL**: Always use the project's custom test fixtures, NOT bare Playwright imports:
+
+```typescript
+import { expect, test } from '../fixtures/test-fixtures'
+```
+
+### 3.2 Test Patterns to Follow
+
+**Reference the existing examples:**
+
+- `e2e/specs/example.spec.ts` — basic navigation, visual snapshots, content verification
+- `e2e/specs/example-backend-isolation.spec.ts` — backend isolation pattern
+
+**Navigation and Snapshot Test Pattern:**
+
+```typescript
+import { expect, test } from '../fixtures/test-fixtures'
+
+test.describe('<Feature Name>', () => {
+  test('<Page name> page is accessible', async ({ page }) => {
+    await page.goto('/<route>')
+    await expect(page).toHaveURL(/.*\/<route>$/)
+  })
+
+  test('<Page name> page visual snapshot', async ({ page }) => {
+    await page.goto('/<route>')
+    await expect(page).toHaveScreenshot()
+  })
+})
+```
+
+**Content Verification Pattern:**
+
+```typescript
+test('<Page> displays expected content', async ({ page }) => {
+  await page.goto('/<route>')
+  await expect(page.getByText('Expected Heading')).toBeVisible()
+  await expect(page.getByTestId('some-test-id')).toBeVisible()
+})
+```
+
+**Form Interaction Pattern:**
+
+```typescript
+test.describe('<Form Name> Form', () => {
+  test('can fill and submit form', async ({ page }) => {
+    await page.goto('/<form-route>')
+
+    // Fill form fields
+    await page.getByLabel('Field Name').fill('Test Value')
+    await page.getByRole('combobox').click()
+    await page.getByRole('option', { name: 'Option' }).click()
+
+    // Submit
+    await page.getByRole('button', { name: 'Submit' }).click()
+
+    // Verify success
+    await expect(page.getByText('Success')).toBeVisible()
+  })
+})
+```
+
+**Table/DataGrid Verification Pattern:**
+
+```typescript
+test.describe('<Model> Table', () => {
+  test('displays data in table', async ({ page }) => {
+    await page.goto('/<admin-route>')
+
+    // Verify table headers
+    await expect(page.getByText('Column Header')).toBeVisible()
+
+    // Verify data is loaded
+    await expect(page.locator('table tbody tr').first()).toBeVisible()
+  })
+})
+```
+
+### 3.3 Available Utilities
+
+Use these utilities from the `support/` and `fixtures/` directories:
+
+- `waitForPageLoaded(page)` from `support/wait-for-page-loaded` — wait for DOM + images
+- `waitForAppIdle(page)` from `support/page-stability` — wait for API requests to complete
+- `resetData()` from `support/reset-data` — reset backend data (stateful mode only)
+- `setData(data)` from `support/set-data` — set specific test data (stateful mode only)
+- `maskToast(page)` from `support/mask-toast` — hide toast notifications for screenshots
+- `clickCheckboxByName(page, name)` from `support/checkbox-click` — click checkboxes reliably
+- `MODEL_TEST_IDS` from `support/model-test-ids` — generated test IDs for models
+- `DataMocker` from `@mock-data/dataMocker.class` — create mock data
+
+### 3.4 Best Practices
+
+1. **Always use custom test fixtures**: `import { expect, test } from '../fixtures/test-fixtures'`
+2. **Use descriptive test names**: Explain what the test verifies, not how
+3. **Use `data-test-id` attributes**: Prefer `getByTestId()` for stable selectors
+4. **Use role-based selectors**: `getByRole('button', { name: '...' })` for accessibility
+5. **Avoid `waitForTimeout()`**: Use condition-based waits instead
+6. **Group related tests**: Use `test.describe()` blocks
+7. **Mask toasts for screenshots**: Use `maskToast(page)` before `toHaveScreenshot()` if toasts interfere
+8. **Do not modify existing test files** unless the changes specifically affect those tests
+
+## Step 4: Run and Verify
+
+### 4.1 Run the Tests
+
+Execute the E2E tests using the automated script:
+
+```bash
+<% cdProjectDir %>./scripts/e2e.sh
+```
+
+### 4.2 Handle First-Run Snapshot Baselines
+
+New tests with `toHaveScreenshot()` will fail on the first run because no baseline snapshot exists yet. This is expected. Re-run the tests to create the baseline and confirm the snapshot is correct.
+
+### 4.3 Investigate Failures
+
+If tests fail for reasons other than missing baselines, follow the investigation workflow from the `run-e2e-tests` command:
+
+1. **Parse test output** to identify which tests failed
+2. **Read the last run status**: `cat e2e/test-results/.last-run.json`
+3. **Read monocart report**: `cat e2e/monocart-report/index.json`
+4. **Analyze failure type**: snapshot mismatch, element not found, timeout, assertion failure
+5. **Read screenshots** from `e2e/test-results/` for visual context
+6. **Fix and re-run** until all tests pass
+
+### 4.4 Common Fixes
+
+- **Element not found**: Add `waitForPageLoaded()` or check the selector matches the DOM
+- **Timeout**: Add proper waits for API responses using `waitForAppIdle()`
+- **Toast interfering with screenshot**: Add `maskToast(page)` before the screenshot assertion
+- **Animation causing flaky snapshots**: The fixture auto-disables them, but custom CSS animations may need attention
+
+## Step 5: Report Summary
+
+After completing the process, provide:
+
+- **Changes analyzed**: List of files categorized by type
+- **Tests created**: List of new spec files with test names
+- **Test results**: Pass/fail status
+- **Coverage gaps**: Any areas that could not be automatically tested (e.g., require auth, complex multi-step workflows)
+
+## Important Notes
+
+- **Tests run in Docker** for consistent snapshots — never update snapshots outside Docker
+- **Use stateless mode** as default for E2E tests
+- **Follow existing patterns**: Match the coding style and structure of `example.spec.ts`
+- **CRITICAL**: Always run tests in a NEW terminal separate from backend and frontend

package/dist/e2e/template/.claude/commands/run-e2e-tests.md

@@ -0,0 +1,221 @@
+# Run E2E Tests
+
+You are tasked with helping the user run end-to-end (E2E) tests in the Claude Code environment (VS Code with Claude assistance).
+
+## Overview
+
+The E2E tests use Playwright to verify that the application works as expected from the user's perspective. This command works for the <% schema.slug %> project.
+
+**Tests always run inside a Docker container** to ensure snapshot consistency across different developer machines and CI. Docker guarantees identical rendering (fonts, DPI, browser version) so snapshot comparisons are deterministic regardless of the host OS.
+
+> **⚠️ TERMINAL MANAGEMENT IN CLAUDE CODE**: When running commands through Claude, terminal reuse can cause background services to be interrupted. To avoid this, manually open separate terminal windows using the VS Code Terminal menu before starting each service (Backend, Frontend, Tests). This ensures each service runs in its own isolated terminal.
+
+## E2E Test Modes
+
+The project supports two types of E2E tests:
+
+- **Stateful**: Tests that can change data. Each test runs a data reset before execution. Slower, uses limited seed data.
+- **Stateless**: Tests that don't alter server data, only test views. Faster, can use larger/more complex seed data.
+
+**For Claude Code environment, use stateless mode** as the default.
+
+## Prerequisites
+
+Before running E2E tests, ensure:
+
+1. **Docker is running** on the host machine
+2. **Backend is running** in E2E stateless mode (or let the script start it)
+3. **Frontend is built and running** in E2E mode with Docker URLs (or let the script build it)
+
+## Running E2E Tests
+
+### Option 1: Automated Script (Recommended)
+
+The easiest way to run E2E tests is using the automated script:
+
+```bash
+<% cdProjectDir %>./scripts/e2e.sh
+```
+
+**What the script does:**
+
+1. ✅ Auto-detects pnpm and activates Node.js 24+ (via nvm/fnm/volta)
+2. ✅ Checks if backend/frontend are already running (reuses them if available)
+3. 🚀 Starts backend in E2E stateless mode (if needed)
+4. 🏗️ Builds frontend with Docker URLs and starts preview server (if needed)
+5. 🧪 Runs E2E tests inside a Docker container
+6. 🧹 Cleans up only script-started processes on exit (Ctrl+C safe)
+
+**Benefits:**
+
+- Single command to run everything
+- Automatic service detection and reuse
+- Only cleans up processes it started (your manually-started services are preserved)
+- Detailed logs saved to `.e2e-backend.log` and `.e2e-frontend.log`
+- Works great with Claude Code
+
+```bash
+# Run E2E tests (Docker mode)
+<% cdProjectDir %>./scripts/e2e.sh
+
+# Just build the Docker image
+<% cdProjectDir %>./scripts/e2e.sh --build-image
+```
+
+### Option 2: Manual Step-by-Step Process
+
+If you prefer to start services manually before running the script:
+
+#### 1. Start Backend in E2E Stateless Mode
+
+**Open a new terminal** and run:
+
+```bash
+cd <% backendPath %>
+pnpm e2e:stateless
+```
+
+**Note**: Keep this terminal running.
+
+#### 2. Build and Start Frontend in E2E Mode
+
+**Open a new terminal** and run:
+
+```bash
+cd <% frontendPath %>
+pnpm e2e:build
+```
+
+**Note**: This builds the production version with `host.docker.internal` URLs required for Docker-based testing. Keep this terminal running.
+
+**Important**: Do NOT use `pnpm dev` for E2E tests — the Vite dev server uses `localhost` URLs which are not reachable from inside the Docker container.
+
+#### 3. Run E2E Tests
+
+**Open a new terminal** and run:
+
+```bash
+<% cdProjectDir %>./scripts/e2e.sh
+```
+
+The script will detect the running backend and frontend, skip starting them, and run the Docker test container directly.
+
+## Test Results and Reports
+
+### View Test Results
+
+- Detailed test results are saved in the `test-results/` directory
+- HTML report available in `playwright-report/`
+- Test coverage data in `monocart-report/`
+
+## Investigating Test Failures
+
+When tests fail, follow this investigation workflow **automatically** before asking the user for help.
+
+### Step 1: Identify Failed Tests
+
+1. Parse the test runner output to identify which tests failed and their error messages
+2. Read the last run status file for a quick summary:
+   ```bash
+   cat e2e/test-results/.last-run.json
+   ```
+3. Read the monocart report for detailed structured results (flaky detection, retry info):
+   ```bash
+   cat e2e/monocart-report/index.json
+   ```
+
+### Step 2: Analyze Failure Type
+
+Determine the failure category:
+
+- **Snapshot mismatch**: Expected vs actual screenshot differs. Look for `toHaveScreenshot` errors and compare images in `e2e/test-results/` and `e2e/specs/*-snapshots/`
+- **Element not found / Timeout**: A locator couldn't find an element or an action timed out. Usually indicates a selector change, missing wait, or race condition
+- **Assertion failure**: A `toEqual`, `toContain`, `toBeVisible` etc. check failed. Check if the expected value or app behavior changed
+- **Network/Connection error**: Backend or frontend unreachable. See Troubleshooting section below
+- **Flaky test**: Test passed on retry (monocart marks these as `caseType: "flaky"`). Needs stabilization
+
+### Step 3: Read Source Code and Artifacts
+
+1. **Read the failing spec file** to understand what the test does:
+   ```
+   e2e/specs/<test-file>.spec.ts
+   ```
+2. **Check screenshots** for visual context — read any `.png` files in `e2e/test-results/` to see what the page actually looked like
+3. **Check trace files** if available (captured on first retry): `e2e/test-results/*/trace.zip`
+4. **Read related page/component code** if the test interacts with specific frontend components or backend endpoints
+
+### Step 4: Fix and Re-run
+
+Based on the failure type:
+
+**For snapshot mismatches:**
+- If the visual change is intentional (e.g., you modified a component), update the snapshot:
+  ```bash
+  <% cdProjectDir %>./scripts/e2e.sh  # re-run — snapshots update inside Docker for consistency
+  ```
+- If unintentional, investigate what caused the rendering difference
+
+**For flaky tests (timing/race conditions):**
+- Add explicit waits using the project's `waitForPageLoaded()` utility or `page.waitForSelector()`
+- Replace `page.waitForTimeout()` with condition-based waits (e.g., `expect(locator).toBeVisible()`)
+- Use the `pageStability` fixture to wait for API requests to complete
+- Check if animations or transitions need to be disabled (the fixture auto-disables them, but custom CSS animations may need attention)
+
+**For element not found errors:**
+- Verify the selector matches the current DOM structure
+- Check if a data-testid was renamed or removed
+- Add a `waitForPageLoaded()` call before interacting with the element
+
+**For assertion failures:**
+- Check if the expected values need updating due to intentional code changes
+- Verify test data setup (seed data, mocked data) is correct
+
+### Step 5: Verify the Fix
+
+After applying fixes, re-run the tests:
+```bash
+<% cdProjectDir %>./scripts/e2e.sh
+```
+
+If a test was flaky, consider running it multiple times to confirm stability. You can run a single test file:
+```bash
+# Inside the Docker container or via the script, target specific tests
+<% cdProjectDir %>./scripts/e2e.sh  # full suite to confirm no regressions
+```
+
+## Troubleshooting
+
+### Connection Refused Errors
+
+If tests fail with connection errors like "connect ECONNREFUSED":
+
+1. **Verify Docker is running**: The test container needs Docker to be available
+2. **Verify backend is running**: Check that the backend is listening on port 4000 and E2E helper on port 3001
+3. **Verify frontend is running**: Check that the frontend preview server is on port 3000
+4. **Verify frontend was built with Docker URLs**: The frontend must be built with `VITE_PUBLIC_API_URL=http://host.docker.internal:3001`. If you started it with `pnpm dev`, restart with `pnpm e2e:build`
+
+### Greeting Test Shows "Hi !" (Empty User)
+
+This means the frontend cannot reach the backend API from inside the Docker container. The frontend was likely built with `localhost` URLs instead of `host.docker.internal`. Fix by:
+
+1. Stopping the frontend
+2. Rebuilding with `pnpm e2e:build` (uses Docker URLs)
+3. Or let `./scripts/e2e.sh` handle everything automatically
+
+### Database Connection Issues
+
+If tests fail with database authentication errors:
+
+1. Ensure your local database is running
+2. Check database credentials in the backend configuration
+3. Verify the database exists and migrations have been run
+
+## Important Notes
+
+- **Tests always run in Docker** for consistent snapshots and CI parity
+- **The script preserves your services**: Cleanup only kills processes the script started
+- **Frontend must use Docker URLs**: Built with `host.docker.internal` (via `pnpm e2e:build` or the script)
+- **Keep backend and frontend running** while executing tests
+- **Use stateless mode** as default for better performance
+- **Test results** are saved in `test-results/` directory
+- **CRITICAL**: Always run tests in a NEW terminal separate from backend and frontend terminals to avoid interrupting the servers

package/dist/e2e/template/scripts/e2e.sh

@@ -0,0 +1,398 @@
+#!/bin/bash
+
+# E2E Test Runner Script
+# This script starts backend, frontend, and runs E2E tests in Docker automatically.
+#
+# The script auto-detects pnpm and Node.js 24+ regardless of how it's invoked
+# (interactive shell, non-interactive subprocess, CI, Claude Code, etc.)
+
+set -e  # Exit on error
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+MONOREPO_ROOT=<% monorepoRootExpr %>
+
+# Ports
+BACKEND_PORT=3001
+FRONTEND_PORT=3000
+BACKEND_MAIN_PORT=4000
+
+# PID file paths
+BACKEND_PID_FILE="$PROJECT_DIR/.e2e-backend.pid"
+FRONTEND_PID_FILE="$PROJECT_DIR/.e2e-frontend.pid"
+
+# Docker image name
+DOCKER_IMAGE="e2e-pxl-env"
+
+# --------------------------------------------------------------------------
+# Environment setup: resolve pnpm and Node.js 24+
+# --------------------------------------------------------------------------
+# This section ensures pnpm and the correct Node.js version are available
+# even in non-interactive shells (e.g., Claude Code, CI, cron, subprocesses).
+
+setup_environment() {
+    # Common paths where pnpm might be installed
+    local search_paths=(
+        "$HOME/.local/share/pnpm"
+        "$HOME/.pnpm"
+        "/opt/homebrew/bin"
+        "/usr/local/bin"
+        "$HOME/.corepack/bin"
+    )
+
+    # Add search paths to PATH if they exist and aren't already in PATH
+    for p in "${search_paths[@]}"; do
+        if [[ -d "$p" ]] && [[ ":$PATH:" != *":$p:"* ]]; then
+            export PATH="$p:$PATH"
+        fi
+    done
+
+    # Resolve pnpm
+    PNPM_BIN=$(command -v pnpm 2>/dev/null || true)
+    if [[ -z "$PNPM_BIN" ]]; then
+        echo -e "${RED}❌ pnpm not found. Please install pnpm (https://pnpm.io/installation)${NC}"
+        exit 1
+    fi
+
+    # Check current Node.js version - we need 24+ for ESM require() support
+    local node_version
+    node_version=$(node --version 2>/dev/null | sed 's/^v//' | cut -d. -f1)
+
+    if [[ -n "$node_version" ]] && [[ "$node_version" -ge 24 ]]; then
+        echo -e "${GREEN}✅ Node.js $(node --version) detected${NC}"
+        return 0
+    fi
+
+    # Try to activate Node.js 24+ via nvm
+    if [[ -s "$HOME/.nvm/nvm.sh" ]]; then
+        export NVM_DIR="$HOME/.nvm"
+        # shellcheck source=/dev/null
+        source "$NVM_DIR/nvm.sh" 2>/dev/null
+
+        # Find a Node.js 24+ version installed via nvm
+        local nvm_node
+        nvm_node=$(nvm ls --no-alias --no-colors 2>/dev/null | grep -oE 'v2[4-9]\.[0-9]+\.[0-9]+|v[3-9][0-9]\.[0-9]+\.[0-9]+' | sort -V | tail -1 || true)
+
+        if [[ -n "$nvm_node" ]]; then
+            echo -e "${BLUE}🔄 Activating $nvm_node via nvm...${NC}"
+            nvm use "$nvm_node" >/dev/null 2>&1
+            # Ensure nvm's bin dir is first in PATH so pnpm picks it up
+            export PATH="$NVM_BIN:$PATH"
+            echo -e "${GREEN}✅ Node.js $(node --version) activated via nvm${NC}"
+            return 0
+        fi
+    fi
+
+    # Try to activate Node.js 24+ via fnm
+    if command -v fnm >/dev/null 2>&1; then
+        local fnm_node
+        fnm_node=$(fnm list 2>/dev/null | grep -oE 'v2[4-9]\.[0-9]+\.[0-9]+|v[3-9][0-9]\.[0-9]+\.[0-9]+' | sort -V | tail -1 || true)
+
+        if [[ -n "$fnm_node" ]]; then
+            echo -e "${BLUE}🔄 Activating $fnm_node via fnm...${NC}"
+            eval "$(fnm env)" 2>/dev/null
+            fnm use "$fnm_node" >/dev/null 2>&1
+            echo -e "${GREEN}✅ Node.js $(node --version) activated via fnm${NC}"
+            return 0
+        fi
+    fi
+
+    # Try to activate Node.js 24+ via volta
+    if command -v volta >/dev/null 2>&1; then
+        echo -e "${BLUE}🔄 Using volta for Node.js management...${NC}"
+        # volta manages node automatically based on package.json
+        local volta_node
+        volta_node=$(node --version 2>/dev/null | sed 's/^v//' | cut -d. -f1)
+        if [[ "$volta_node" -ge 24 ]]; then
+            echo -e "${GREEN}✅ Node.js $(node --version) via volta${NC}"
+            return 0
+        fi
+    fi
+
+    # Node.js 24+ not found - warn but don't fail (pnpm devEngines might handle it)
+    echo -e "${YELLOW}⚠️  Node.js 24+ not found (current: $(node --version 2>/dev/null || echo 'none')).${NC}"
+    echo -e "${YELLOW}   The project requires Node.js 24+ for ESM support.${NC}"
+    echo -e "${YELLOW}   Install via: nvm install 24 / fnm install 24 / volta install node@24${NC}"
+    echo -e "${YELLOW}   Continuing anyway (pnpm devEngines.runtime may auto-download it)...${NC}"
+}
+
+# Kill a process and all its descendants (children, grandchildren, etc.)
+kill_tree() {
+    local pid=$1
+    local children
+    children=$(pgrep -P "$pid" 2>/dev/null || true)
+    for child in $children; do
+        kill_tree "$child"
+    done
+    kill "$pid" 2>/dev/null || true
+}
+
+# Kill any remaining process listening on a port
+kill_port() {
+    local port=$1
+    local pids
+    pids=$(lsof -Pi :"$port" -sTCP:LISTEN -t 2>/dev/null || true)
+    if [[ -n "$pids" ]]; then
+        echo -e "${BLUE}   Killing remaining process(es) on port $port...${NC}"
+        echo "$pids" | xargs kill 2>/dev/null || true
+    fi
+}
+
+# Cleanup function
+cleanup() {
+    echo -e "\n${YELLOW}🧹 Cleaning up...${NC}"
+
+    # Kill backend if we started it
+    if [[ -f "$BACKEND_PID_FILE" ]]; then
+        BACKEND_PID=$(cat "$BACKEND_PID_FILE")
+        if ps -p "$BACKEND_PID" > /dev/null 2>&1; then
+            echo -e "${BLUE}⏹️  Stopping backend (PID: $BACKEND_PID)...${NC}"
+            kill_tree "$BACKEND_PID"
+        fi
+        rm -f "$BACKEND_PID_FILE"
+        # Ensure ports are fully released
+        sleep 0.5
+        kill_port $BACKEND_PORT
+        kill_port $BACKEND_MAIN_PORT
+    fi
+
+    # Kill frontend if we started it
+    if [[ -f "$FRONTEND_PID_FILE" ]]; then
+        FRONTEND_PID=$(cat "$FRONTEND_PID_FILE")
+        if ps -p "$FRONTEND_PID" > /dev/null 2>&1; then
+            echo -e "${BLUE}⏹️  Stopping frontend (PID: $FRONTEND_PID)...${NC}"
+            kill_tree "$FRONTEND_PID"
+        fi
+        rm -f "$FRONTEND_PID_FILE"
+        # Ensure port is fully released
+        sleep 0.5
+        kill_port $FRONTEND_PORT
+    fi
+
+    echo -e "${GREEN}✅ Cleanup complete${NC}"
+}
+
+# Register cleanup on script exit
+trap cleanup EXIT INT TERM
+
+# Check if services are already running
+check_services() {
+    echo -e "${BLUE}🔍 Checking for existing services...${NC}"
+
+    BACKEND_RUNNING=false
+    FRONTEND_RUNNING=false
+
+    if lsof -Pi :$BACKEND_PORT -sTCP:LISTEN -t >/dev/null 2>&1; then
+        echo -e "${YELLOW}⚠️  Backend already running on port $BACKEND_PORT${NC}"
+        BACKEND_RUNNING=true
+    fi
+
+    if lsof -Pi :$FRONTEND_PORT -sTCP:LISTEN -t >/dev/null 2>&1; then
+        echo -e "${YELLOW}⚠️  Frontend already running on port $FRONTEND_PORT${NC}"
+        FRONTEND_RUNNING=true
+    fi
+}
+
+# Wait for a service to be ready
+wait_for_service() {
+    local port=$1
+    local service_name=$2
+    local max_attempts=60  # 60 seconds timeout
+    local attempt=0
+
+    echo -e "${BLUE}⏳ Waiting for $service_name to be ready on port $port...${NC}"
+
+    while ! lsof -Pi :$port -sTCP:LISTEN -t >/dev/null 2>&1; do
+        attempt=$((attempt + 1))
+        if [[ $attempt -gt $max_attempts ]]; then
+            echo -e "${RED}❌ Timeout waiting for $service_name to start${NC}"
+            return 1
+        fi
+        sleep 1
+    done
+
+    echo -e "${GREEN}✅ $service_name is ready${NC}"
+    return 0
+}
+
+# Start backend
+start_backend() {
+    if [[ "$BACKEND_RUNNING" == "true" ]]; then
+        echo -e "${GREEN}✅ Using existing backend on port $BACKEND_PORT${NC}"
+        return 0
+    fi
+
+    echo -e "${BLUE}🚀 Starting backend in E2E stateless mode...${NC}"
+    cd "$PROJECT_DIR/backend"
+
+    # Start backend in background and save PID
+    "$PNPM_BIN" e2e:stateless > "$PROJECT_DIR/.e2e-backend.log" 2>&1 &
+    echo $! > "$BACKEND_PID_FILE"
+
+    # Wait for backend to be ready
+    if ! wait_for_service $BACKEND_PORT "Backend"; then
+        echo -e "${RED}❌ Failed to start backend${NC}"
+        echo -e "${YELLOW}📋 Backend log (last 20 lines):${NC}"
+        tail -n 20 "$PROJECT_DIR/.e2e-backend.log"
+        return 1
+    fi
+}
+
+# Build and start frontend
+start_frontend() {
+    if [[ "$FRONTEND_RUNNING" == "true" ]]; then
+        echo -e "${GREEN}✅ Using existing frontend on port $FRONTEND_PORT${NC}"
+        return 0
+    fi
+
+    echo -e "${BLUE}🏗️  Building frontend for E2E...${NC}"
+    cd "$PROJECT_DIR/frontend"
+
+    # Build frontend with Docker URLs (tests run inside Docker container accessing host services)
+    if ! VITE_PUBLIC_API_URL=http://host.docker.internal:3001 VITE_PUBLIC_BASE_URL=http://host.docker.internal:3000 NODE_V8_COVERAGE=.v8-coverage VITE_PUBLIC_MAPBOX_DISABLE_TRANSITIONS=true VITE_PUBLIC_USE_TEST_ASSETS=true VITE_AUTH=false "$PNPM_BIN" exec vite build; then
+        echo -e "${RED}❌ Failed to build frontend${NC}"
+        return 1
+    fi
+
+    echo -e "${BLUE}🚀 Starting frontend preview server...${NC}"
+
+    # Start frontend preview server in background and save PID
+    "$PNPM_BIN" exec vite preview --port 3000 > "$PROJECT_DIR/.e2e-frontend.log" 2>&1 &
+    echo $! > "$FRONTEND_PID_FILE"
+
+    # Wait for frontend to be ready
+    if ! wait_for_service $FRONTEND_PORT "Frontend"; then
+        echo -e "${RED}❌ Failed to start frontend${NC}"
+        echo -e "${YELLOW}📋 Frontend log (last 20 lines):${NC}"
+        tail -n 20 "$PROJECT_DIR/.e2e-frontend.log"
+        return 1
+    fi
+}
+
+# Build Docker image
+build_docker_image() {
+    echo -e "${BLUE}🐳 Building Docker image...${NC}"
+    cd "$PROJECT_DIR"
+
+    if docker build -t $DOCKER_IMAGE ./e2e/; then
+        echo -e "${GREEN}✅ Docker image built successfully${NC}"
+        return 0
+    else
+        echo -e "${RED}❌ Failed to build Docker image${NC}"
+        return 1
+    fi
+}
+
+# Run E2E tests in Docker
+run_tests() {
+    echo -e "${BLUE}🧪 Running E2E tests in Docker...${NC}"
+
+    # Build Docker image if it doesn't exist
+    if ! docker image inspect $DOCKER_IMAGE >/dev/null 2>&1; then
+        echo -e "${YELLOW}Docker image not found, building...${NC}"
+        if ! build_docker_image; then
+            return 1
+        fi
+    fi
+
+    echo -e "${BLUE}📦 Running tests in Docker container...${NC}"
+
+    # Clean test output directories so they can be recreated with correct permissions
+    rm -rf "$MONOREPO_ROOT/projects/demo/e2e/test-results" "$MONOREPO_ROOT/projects/demo/e2e/playwright-report" "$MONOREPO_ROOT/projects/demo/e2e/monocart-report"
+
+    # Run tests in Docker with proper volume mounting
+    # Use host user ID to avoid permission issues with mounted volumes
+    docker run --rm \
+        -v "$MONOREPO_ROOT:/pxl" \
+        -w <% dockerWorkDir %> \
+        --add-host=host.docker.internal:host-gateway \
+        $DOCKER_IMAGE \
+        /bin/bash -c "<% nodeShimsCleanup %>; pnpm e2e"
+
+    local test_exit_code=$?
+
+    if [[ $test_exit_code -eq 0 ]]; then
+        echo -e "${GREEN}✅ All tests passed!${NC}"
+    else
+        echo -e "${RED}❌ Tests failed with exit code $test_exit_code${NC}"
+    fi
+
+    return $test_exit_code
+}
+
+# Main execution
+main() {
+    echo -e "${GREEN}╔═══════════════════╗${NC}"
+    echo -e "${GREEN}║  E2E Test Runner  ║${NC}"
+    echo -e "${GREEN}╚═══════════════════╝${NC}\n"
+
+    echo -e "${BLUE}🐳 Running in Docker mode${NC}\n"
+
+    # Setup environment (resolve pnpm, activate Node.js 24+)
+    setup_environment
+
+    # Check for existing services
+    check_services
+
+    # Start backend
+    if ! start_backend; then
+        echo -e "${RED}❌ Failed to start backend. Exiting.${NC}"
+        exit 1
+    fi
+
+    # Start frontend
+    if ! start_frontend; then
+        echo -e "${RED}❌ Failed to start frontend. Exiting.${NC}"
+        exit 1
+    fi
+
+    # Run tests in Docker
+    run_tests
+    local exit_code=$?
+
+    exit $exit_code
+}
+
+# Parse command line arguments
+case "${1:-}" in
+    --help|-h)
+        echo "Usage: $0 [OPTIONS]"
+        echo ""
+        echo "Options:"
+        echo "  --help, -h      Show this help message"
+        echo "  --build-image   Build Docker image and exit"
+        echo ""
+        echo "This script automatically:"
+        echo "  1. Detects pnpm and activates Node.js 24+ (via nvm/fnm/volta)"
+        echo "  2. Checks if backend/frontend are already running (reuses them)"
+        echo "  3. Starts backend in E2E stateless mode (if needed)"
+        echo "  4. Builds and starts frontend preview server (if needed)"
+        echo "  5. Runs E2E tests in Docker"
+        echo "  6. Cleans up all processes on exit (Ctrl+C safe)"
+        echo ""
+        echo "Examples:"
+        echo "  $0                    # Run E2E tests"
+        echo "  $0 --build-image      # Just build the Docker image"
+        echo ""
+        echo "Logs:"
+        echo "  Backend log:  .e2e-backend.log"
+        echo "  Frontend log: .e2e-frontend.log"
+        exit 0
+        ;;
+    --build-image)
+        setup_environment
+        build_docker_image
+        exit $?
+        ;;
+    *)
+        main
+        ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postxl/generators",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Code generators for PXL - generates backend, frontend, Prisma schemas, and more",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -46,7 +46,7 @@
     "exceljs": "^4.4.0",
     "@postxl/generator": "^1.3.5",
     "@postxl/schema": "^1.6.0",
-    "@postxl/ui-components": "^1.5.1",
+    "@postxl/ui-components": "^1.5.2",
     "@postxl/utils": "^1.3.3"
   },
   "devDependencies": {},