@postxl/generators 1.16.0 → 1.17.1

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/devops/generators/e2e-yml.generator.js

@@ -70,7 +70,6 @@ function generateE2EYaml(context) {
           env:
             VITE_PUBLIC_API_URL: http://localhost:3001
             VITE_PUBLIC_BASE_URL: http://localhost:3000
-            VITE_PUBLIC_MAPBOX_ACCESS_TOKEN: \${{ secrets.MAPBOX_ACCESS_TOKEN }}
 
         - name: Check if Backend and Frontend are running and Print Logs
           run: |
@@ -164,6 +163,14 @@ function generateE2EYaml(context) {
             ENABLE_BACKEND_SHUTDOWN: true
             PLAYWRIGHT_WORKERS: 2
 
+        - name: Dump runtime logs on failure
+          if: \${{ failure() }}
+          run: |
+            echo "Backend runtime log tail:"
+            tail -n 500 backend/backend.log || true
+            echo "Frontend runtime log tail:"
+            tail -n 500 frontend/frontend.log || true
+
         - name: Upload Playwright Report
           uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 #v4.6.2
           if: \${{ !cancelled() }}
@@ -172,6 +179,16 @@ function generateE2EYaml(context) {
             path: e2e/test-results
             retention-days: 5
 
+        - name: Upload Runtime Logs
+          uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 #v4.6.2
+          if: \${{ failure() && !cancelled() }}
+          with:
+            name: runtime-logs
+            path: |
+              backend/backend.log
+              frontend/frontend.log
+            retention-days: 5
+
         - name: Upload Backend Coverage
           uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 #v4.6.2
           if: \${{ !cancelled() }}

package/dist/devops/generators/e2e-yml.generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"e2e-yml.generator.js","sourceRoot":"","sources":["../../../src/devops/generators/e2e-yml.generator.ts"],"names":[],"mappings":";;AAEA,0CAoMC;AApMD,SAAgB,eAAe,CAAC,OAA4B;IAC1D,MAAM,EACJ,MAAM,EAAE,EAAE,QAAQ,EAAE,GACrB,GAAG,OAAO,CAAA;IACX,0FAA0F;IAC1F,MAAM,gBAAgB,GAAG,gDAAgD,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;IAE9F,OAAO,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;QAqBT,QAAQ,CAAC,CAAC,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;;;;;;;;;;;UAoB9C,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;;;;;;;cAgB3C,QAAQ,CAAC,CAAC,CAAC,yBAAyB,gBAAgB,GAAG,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmIzE,CAAA;AACD,CAAC;AAED,MAAM,sBAAsB,GAAG,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAkB,EAAE,EAAE,CAAC;;;;;6BAKxD,QAAQ;iCACJ,QAAQ;2BACd,QAAQ;;;;;;;;;CASlC,CAAA;AAED,MAAM,aAAa,GAAG,CAAC,gBAAwB,EAAE,EAAE,CAAC;;;;;oCAKhB,gBAAgB;CACnD,CAAA"}
+{"version":3,"file":"e2e-yml.generator.js","sourceRoot":"","sources":["../../../src/devops/generators/e2e-yml.generator.ts"],"names":[],"mappings":";;AAEA,0CAqNC;AArND,SAAgB,eAAe,CAAC,OAA4B;IAC1D,MAAM,EACJ,MAAM,EAAE,EAAE,QAAQ,EAAE,GACrB,GAAG,OAAO,CAAA;IACX,0FAA0F;IAC1F,MAAM,gBAAgB,GAAG,gDAAgD,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;IAE9F,OAAO,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;QAqBT,QAAQ,CAAC,CAAC,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;;;;;;;;;;;UAoB9C,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;;;;;;;cAgB3C,QAAQ,CAAC,CAAC,CAAC,yBAAyB,gBAAgB,GAAG,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoJzE,CAAA;AACD,CAAC;AAED,MAAM,sBAAsB,GAAG,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAkB,EAAE,EAAE,CAAC;;;;;6BAKxD,QAAQ;iCACJ,QAAQ;2BACd,QAAQ;;;;;;;;;CASlC,CAAA;AAED,MAAM,aAAa,GAAG,CAAC,gBAAwB,EAAE,EAAE,CAAC;;;;;oCAKhB,gBAAgB;CACnD,CAAA"}

package/dist/devops/generators/frontend-dockerfile.generator.js

@@ -28,8 +28,7 @@ ENV TURBO_TEAM=postxl
 # Safely use Turborepo secret according to https://docs.docker.com/build/building/secrets/
 RUN --mount=type=secret,id=TURBO_TOKEN \
   VITE_PUBLIC_API_URL=PLACEHOLDER_VITE_PUBLIC_API_URL VITE_PUBLIC_BASE_URL=PLACEHOLDER_VITE_PUBLIC_BASE_URL \
-  VITE_PUBLIC_MAPBOX_ACCESS_TOKEN=PLACEHOLDER_VITE_PUBLIC_MAPBOX_ACCESS_TOKEN VITE_PUBLIC_ENABLE_ANALYTICS=PLACEHOLDER_VITE_PUBLIC_ENABLE_ANALYTICS \
-  VITE_PUBLIC_ANALYTICS_SCRIPT_URL=PLACEHOLDER_VITE_PUBLIC_ANALYTICS_SCRIPT_URL VITE_PUBLIC_KEYCLOAK_URL=PLACEHOLDER_VITE_PUBLIC_KEYCLOAK_URL \
+  VITE_PUBLIC_KEYCLOAK_URL=PLACEHOLDER_VITE_PUBLIC_KEYCLOAK_URL \
   VITE_PUBLIC_KEYCLOAK_CLIENT_ID=PLACEHOLDER_VITE_PUBLIC_KEYCLOAK_CLIENT_ID VITE_PUBLIC_KEYCLOAK_REALM=PLACEHOLDER_VITE_PUBLIC_KEYCLOAK_REALM \
   VITE_PUBLIC_CHECK_LOGIN_IFRAME=PLACEHOLDER_VITE_PUBLIC_CHECK_LOGIN_IFRAME \
   pnpm ${isWorkspace ? `turbo:ci build --filter=@postxl/${slug} --filter=@postxl/${slug}-frontend --filter=@postxl/${slug}-api` : `turbo run build --filter=@postxl/${slug}-frontend --filter=@postxl/${slug}-api`}

package/dist/devops/generators/frontend-dockerfile.generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontend-dockerfile.generator.js","sourceRoot":"","sources":["../../../src/devops/generators/frontend-dockerfile.generator.ts"],"names":[],"mappings":";;AAEA,gEAKC;AALD,SAAgB,0BAA0B,CAAC,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,EAAuB;IAC/F,MAAM,WAAW,GAAG,WAAW,KAAK,WAAW,CAAA;IAC/C,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,YAAY,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IAExD,OAAO,kBAAkB,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAA;AAC7D,CAAC;AAED,MAAM,kBAAkB,GAAG,CAAC,EAC1B,SAAS,EACT,IAAI,EACJ,WAAW,GAKZ,EAAE,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,CAAA;;oCAEK,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;SAwBzD,WAAW,CAAC,CAAC,CAAC,mCAAmC,IAAI,qBAAqB,IAAI,8BAA8B,IAAI,MAAM,CAAC,CAAC,CAAC,oCAAoC,IAAI,8BAA8B,IAAI,MAAM;;;;;;;;;;;;;6BAarL,SAAS;;;6BAGT,SAAS;;;aAGzB,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,SAAS,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;aAUxC,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,SAAS,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;CAUpD,CAAA"}
+{"version":3,"file":"frontend-dockerfile.generator.js","sourceRoot":"","sources":["../../../src/devops/generators/frontend-dockerfile.generator.ts"],"names":[],"mappings":";;AAEA,gEAKC;AALD,SAAgB,0BAA0B,CAAC,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,EAAuB;IAC/F,MAAM,WAAW,GAAG,WAAW,KAAK,WAAW,CAAA;IAC/C,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,YAAY,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IAExD,OAAO,kBAAkB,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAA;AAC7D,CAAC;AAED,MAAM,kBAAkB,GAAG,CAAC,EAC1B,SAAS,EACT,IAAI,EACJ,WAAW,GAKZ,EAAE,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,CAAA;;oCAEK,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW;;;;;;;;;;;;;;;;;;;;;;;SAuBzD,WAAW,CAAC,CAAC,CAAC,mCAAmC,IAAI,qBAAqB,IAAI,8BAA8B,IAAI,MAAM,CAAC,CAAC,CAAC,oCAAoC,IAAI,8BAA8B,IAAI,MAAM;;;;;;;;;;;;;6BAarL,SAAS;;;6BAGT,SAAS;;;aAGzB,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,SAAS,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;aAUxC,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,SAAS,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;CAUpD,CAAA"}

package/dist/devops/generators/jenkinsfile.generator.js

@@ -38,8 +38,7 @@ function generateJenkinsfile({ devOps: { database, keycloak, useS3 }, schema: {
                                       -e KEYCLOAK_LOGOUT_REDIRECT_URL=\${KEYCLOAK_LOGOUT_REDIRECT_URL} \\`
         : '';
     const keycloakRunEnvFrontend = keycloak
-        ? `
-                                  -e VITE_PUBLIC_KEYCLOAK_URL=\${KEYCLOAK_URL} \\
+        ? `                                  -e VITE_PUBLIC_KEYCLOAK_URL=\${KEYCLOAK_URL} \\
                                   -e VITE_PUBLIC_KEYCLOAK_CLIENT_ID=\${KEYCLOAK_CLIENT_ID} \\
                                   -e VITE_PUBLIC_KEYCLOAK_REALM=\${KEYCLOAK_REALM} \\`
         : '';
@@ -82,7 +81,6 @@ function generateJenkinsfile({ devOps: { database, keycloak, useS3 }, schema: {
     return /*Jenkinsfile*/ `
 def secrets = [${dbSecrets}${keycloakSecrets}
   [envVar: 'TURBO_TOKEN', secretRef: 'op://PostXL service/Turborepo Cache Token/password'],
-  [envVar: 'MAPBOX_ACCESS_TOKEN', secretRef: 'op://PostXL service/Mapbox Access Token/password'],
 ]
 
 pipeline {
@@ -154,9 +152,7 @@ pipeline {
                                       \${REGISTRY}/\${PROJECT_NAME}_backend:latest"
                   sh "\${SSH_COMMAND} docker run -d --name \${PROJECT_NAME}_frontend \\
                                   -e VITE_PUBLIC_API_URL=\${API_URL} \\
-                                  -e VITE_PUBLIC_BASE_URL=\${FRONTEND_URL} \\
-                                  -e VITE_PUBLIC_MAPBOX_ACCESS_TOKEN=\${MAPBOX_ACCESS_TOKEN} \\
-                                  -e VITE_PUBLIC_ENABLE_ANALYTICS=false \\${keycloakRunEnvFrontend}
+                                  -e VITE_PUBLIC_BASE_URL=\${FRONTEND_URL} \\${keycloakRunEnvFrontend ? `\n${keycloakRunEnvFrontend}` : ''}
                                   -e VITE_PUBLIC_CHECK_LOGIN_IFRAME=true \\
                                   -p 0.0.0.0:\${PORT_MAPPING_FRONTEND} \\
                                   \${REGISTRY}/\${PROJECT_NAME}_frontend:latest"

package/dist/devops/generators/jenkinsfile.generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"jenkinsfile.generator.js","sourceRoot":"","sources":["../../../src/devops/generators/jenkinsfile.generator.ts"],"names":[],"mappings":";;AAEA,kDAmLC;AAnLD,SAAgB,mBAAmB,CAAC,EAClC,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,EACrC,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,GACT;IACpB,iFAAiF;IACjF,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACtC,MAAM,SAAS,GAAG,QAAQ;QACxB,CAAC,CAAC;mFAC6E,IAAI;mFACJ,IAAI;KAClF;QACD,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,eAAe,GAAG,QAAQ;QAC9B,CAAC,CAAC;oGAC8F,IAAI;KACnG;QACD,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,WAAW,GAAG,QAAQ;QAC1B,CAAC,CAAC;;gCAE0B,IAAI;4BACR,IAAI;;;SAGvB;QACL,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,KAAK,GAAG,QAAQ;QACpB,CAAC,CAAC;wIACkI;QACpI,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,cAAc,GAAG,QAAQ;QAC7B,CAAC,CAAC;;;;;;0GAMoG;QACtG,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,sBAAsB,GAAG,QAAQ;QACrC,CAAC,CAAC;;;sFAGgF;QAClF,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,KAAK,GAAG,KAAK;QACjB,CAAC,CAAC;;;;SAIG;QACL,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,QAAQ,GAAG,KAAK;QACpB,CAAC,CAAC;;;sEAGgE;QAClE,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,KAAK,GAAG;;;;;;;;;;;SAWP,CAAA;IAEP,MAAM,QAAQ,GAAG;;;;;;;;;;sGAUmF,CAAA;IAEpG,OAAO,eAAe,CAAC;iBACR,SAAS,GAAG,eAAe;;;;;;;;;;;;;;0BAclB,IAAI;;;;;;6BAMD,IAAI;;;kCAGC,IAAI;;UAE5B,WAAW,GAAG,KAAK,GAAG,KAAK;;;;;;;sBAOf,WAAW,KAAK,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,IAAI,GAAG;;;;;;;;sBAQvD,WAAW,KAAK,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;uEA2BN,KAAK,GAAG,cAAc,GAAG,QAAQ;wCAChE,QAAQ;;;;;;;;4EAQ4B,sBAAsB;;;;;;;;;;CAUjG,CAAA;AACD,CAAC"}
+{"version":3,"file":"jenkinsfile.generator.js","sourceRoot":"","sources":["../../../src/devops/generators/jenkinsfile.generator.ts"],"names":[],"mappings":";;AAEA,kDA+KC;AA/KD,SAAgB,mBAAmB,CAAC,EAClC,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,EACrC,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,GACT;IACpB,iFAAiF;IACjF,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACtC,MAAM,SAAS,GAAG,QAAQ;QACxB,CAAC,CAAC;mFAC6E,IAAI;mFACJ,IAAI;KAClF;QACD,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,eAAe,GAAG,QAAQ;QAC9B,CAAC,CAAC;oGAC8F,IAAI;KACnG;QACD,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,WAAW,GAAG,QAAQ;QAC1B,CAAC,CAAC;;gCAE0B,IAAI;4BACR,IAAI;;;SAGvB;QACL,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,KAAK,GAAG,QAAQ;QACpB,CAAC,CAAC;wIACkI;QACpI,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,cAAc,GAAG,QAAQ;QAC7B,CAAC,CAAC;;;;;;0GAMoG;QACtG,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,sBAAsB,GAAG,QAAQ;QACrC,CAAC,CAAC;;sFAEgF;QAClF,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,KAAK,GAAG,KAAK;QACjB,CAAC,CAAC;;;;SAIG;QACL,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,QAAQ,GAAG,KAAK;QACpB,CAAC,CAAC;;;sEAGgE;QAClE,CAAC,CAAC,EAAE,CAAA;IAEN,MAAM,KAAK,GAAG;;;;;;;;;;;SAWP,CAAA;IAEP,MAAM,QAAQ,GAAG;;;;;;;;;;sGAUmF,CAAA;IAEpG,OAAO,eAAe,CAAC;iBACR,SAAS,GAAG,eAAe;;;;;;;;;;;;;0BAalB,IAAI;;;;;;6BAMD,IAAI;;;kCAGC,IAAI;;UAE5B,WAAW,GAAG,KAAK,GAAG,KAAK;;;;;;;sBAOf,WAAW,KAAK,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,IAAI,GAAG;;;;;;;;sBAQvD,WAAW,KAAK,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;uEA2BN,KAAK,GAAG,cAAc,GAAG,QAAQ;wCAChE,QAAQ;;;;;;+EAM+B,sBAAsB,CAAC,CAAC,CAAC,KAAK,sBAAsB,EAAE,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;CAUzI,CAAA;AACD,CAAC"}

package/dist/devops/template/docker/frontend/entrypoint.sh

@@ -1,15 +1,12 @@
 #!/bin/sh
 
-if [ -z "$VITE_PUBLIC_API_URL" ] || [ -z "$VITE_PUBLIC_BASE_URL" ] || [ -z "$VITE_PUBLIC_MAPBOX_ACCESS_TOKEN" ] || [ -z "$VITE_PUBLIC_ENABLE_ANALYTICS" ] || [ -z "$VITE_PUBLIC_KEYCLOAK_URL" ] || [ -z "$VITE_PUBLIC_KEYCLOAK_CLIENT_ID" ] || [ -z "$VITE_PUBLIC_KEYCLOAK_REALM" ] || [ -z "$VITE_PUBLIC_CHECK_LOGIN_IFRAME" ]; then
-  echo "Error: VITE_PUBLIC_API_URL, VITE_PUBLIC_BASE_URL, VITE_PUBLIC_MAPBOX_ACCESS_TOKEN, VITE_PUBLIC_ENABLE_ANALYTICS, VITE_PUBLIC_KEYCLOAK_URL, VITE_PUBLIC_KEYCLOAK_CLIENT_ID, VITE_PUBLIC_KEYCLOAK_REALM, VITE_PUBLIC_CHECK_LOGIN_IFRAME is not defined" >&2
+if [ -z "$VITE_PUBLIC_API_URL" ] || [ -z "$VITE_PUBLIC_BASE_URL" ] || [ -z "$VITE_PUBLIC_KEYCLOAK_URL" ] || [ -z "$VITE_PUBLIC_KEYCLOAK_CLIENT_ID" ] || [ -z "$VITE_PUBLIC_KEYCLOAK_REALM" ] || [ -z "$VITE_PUBLIC_CHECK_LOGIN_IFRAME" ]; then
+  echo "Error: VITE_PUBLIC_API_URL, VITE_PUBLIC_BASE_URL, VITE_PUBLIC_KEYCLOAK_URL, VITE_PUBLIC_KEYCLOAK_CLIENT_ID, VITE_PUBLIC_KEYCLOAK_REALM, VITE_PUBLIC_CHECK_LOGIN_IFRAME is not defined" >&2
   exit 1
 fi
 
 find /app/frontend/dist \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "s#PLACEHOLDER_VITE_PUBLIC_API_URL#$VITE_PUBLIC_API_URL#g"
 find /app/frontend/dist \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "s#PLACEHOLDER_VITE_PUBLIC_BASE_URL#$VITE_PUBLIC_BASE_URL#g"
-find /app/frontend/dist \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "s#PLACEHOLDER_VITE_PUBLIC_MAPBOX_ACCESS_TOKEN#$VITE_PUBLIC_MAPBOX_ACCESS_TOKEN#g"
-find /app/frontend/dist \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "s#PLACEHOLDER_VITE_PUBLIC_ENABLE_ANALYTICS#$VITE_PUBLIC_ENABLE_ANALYTICS#g"
-find /app/frontend/dist \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "s#PLACEHOLDER_VITE_PUBLIC_ANALYTICS_SCRIPT_URL#$VITE_PUBLIC_ANALYTICS_SCRIPT_URL#g"
 find /app/frontend/dist \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "s#PLACEHOLDER_VITE_PUBLIC_KEYCLOAK_URL#$VITE_PUBLIC_KEYCLOAK_URL#g"
 find /app/frontend/dist \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "s#PLACEHOLDER_VITE_PUBLIC_KEYCLOAK_CLIENT_ID#$VITE_PUBLIC_KEYCLOAK_CLIENT_ID#g"
 find /app/frontend/dist \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "s#PLACEHOLDER_VITE_PUBLIC_KEYCLOAK_REALM#$VITE_PUBLIC_KEYCLOAK_REALM#g"

package/dist/e2e/e2e.generator.js

@@ -54,7 +54,23 @@ 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',
+            e2eArtifactsPath: isWorkspace ? `/projects/${slug}/e2e` : '/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 +86,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