codebyplan 1.11.1 → 1.12.0

package/templates/skills/cbp-e2e-setup/SKILL.md

@@ -0,0 +1,254 @@
+---
+scope: org-shared
+name: cbp-e2e-setup
+description: Detect installed E2E frameworks, ask which to enable, record credentials source (gitignored env-file path + var names only, never secrets), and write/refresh .codebyplan/e2e.json. Interactive, idempotent.
+argument-hint: "[--force]"
+model: sonnet
+effort: xhigh
+allowed-tools: Read, Write, Edit, Bash(cat *), Bash(jq *), Bash(which *), Bash(test *), Bash(mkdir *), Bash(cp *), Bash(echo *), Bash(date *), Bash(mv *), Bash(git check-ignore *), AskUserQuestion, mcp__codebyplan__get_repos
+---
+
+# E2E Setup
+
+Configure `.codebyplan/e2e.json` so the E2E test pipeline knows which frameworks are
+enabled, where each app lives, and where to read credentials at test time.
+
+Invoke at any time. Already-configured frameworks are preserved unless `--force` is passed.
+Pass `--force` to re-ask all questions including credentials blocks.
+
+## Arguments
+
+Inspect `$ARGUMENTS` for `--force`. If present, set `force_mode = true`.
+Absent: use idempotent mode — preserve existing credentials blocks, skip re-asking
+already-configured frameworks.
+
+## Step 1 — Detect installed frameworks
+
+Run both detection signals and merge:
+
+**Signal A — DB tech_stack** via `mcp__codebyplan__get_repos` (match `repo_id` from
+`.codebyplan/repo.json`). Scan `tech_stack[]` for: `playwright`, `maestro`, `xcuitest`,
+`webdriverio`, `@wdio/cli`, `@vscode/test-cli`.
+
+**Signal B — Filesystem probes:**
+
+```bash
+test -f playwright.config.ts  || test -f playwright.config.js  # → playwright
+test -f maestro/config.yaml   || test -d maestro               # → maestro
+test -d ios && find ios -name '*UITests' -maxdepth 2 | grep -q . # → xcuitest
+test -f wdio.conf.ts          || test -f wdio.conf.js          # → tauri (wdio)
+test -f .vscode-test.mjs      || test -d apps/vscode           # → vscode
+```
+
+**Signal C — Read existing `.codebyplan/e2e.json`** for idempotent merge:
+
+```bash
+cat .codebyplan/e2e.json 2>/dev/null || echo '{}'
+```
+
+A framework detected by A or B is "detected". A framework already in e2e.json is
+"configured". A framework with `enabled: false` in e2e.json is "configured-disabled".
+
+## Step 2 — Ask which to enable
+
+Display a summary table of detection results:
+
+```
+Framework   | Detected | Configured | Status
+----------- | -------- | ---------- | ------
+playwright  | yes      | yes        | enabled
+maestro     | no       | no         | absent
+xcuitest    | no       | no         | absent
+tauri       | no       | no         | absent
+vscode      | no       | no         | absent
+```
+
+AskUserQuestion (multi-select):
+
+```
+Which E2E frameworks should be enabled?
+Detected frameworks are pre-checked. Undetected ones can still be enabled.
+
+Select all that apply:
+A) playwright  (web — Next.js)
+B) maestro     (mobile — Expo/React Native)
+C) xcuitest    (iOS native — Apple Watch, HealthKit, system dialogs)
+D) tauri       (desktop — WebDriverIO + tauri-driver)
+E) vscode      (VS Code extension — @vscode/test-cli)
+```
+
+In `--force` mode: re-ask even for frameworks already enabled.
+Otherwise: frameworks already `enabled: true` in e2e.json are kept without asking.
+
+## Step 3 — Mobile platforms (conditional)
+
+If maestro or xcuitest is in the enabled set and the framework is not yet configured
+(or `--force`), AskUserQuestion:
+
+```
+Mobile platform target for <framework>:
+A) Android only
+B) iOS only
+C) Both Android and iOS
+```
+
+Record the answer as `platforms: ["android"]`, `["ios"]`, or `["android", "ios"]` on the
+framework config block.
+
+## Step 4 — Credentials source
+
+For each enabled framework that touches auth (playwright, maestro, xcuitest):
+
+**Idempotency gate** (skip if `--force` is absent AND
+`credentials.frameworks[framework].email_var` AND
+`credentials.frameworks[framework].password_var` are both set to non-empty strings —
+an empty `{}` entry counts as unconfigured, so prompt for it):
+
+```
+Credentials block for <framework> already configured — use --force to reset.
+  env_file: <path>
+  email_var: <var>
+  password_var: <var>
+```
+
+Print the preserved values and continue to Step 5.
+
+**Otherwise**, AskUserQuestion (one question per framework, step-by-step):
+
+```
+Credentials source for <framework>
+
+1. Gitignored env-file path that holds the secrets
+   (default: .codebyplan/e2e.env — a dedicated file, separate from app .env.local)
+   Path: ___
+
+2. Email env var name (default: E2E_TEST_EMAIL for playwright, TEST_EMAIL for others)
+   Var name: ___
+
+3. Password env var name (default: E2E_TEST_PASSWORD for playwright, TEST_PASSWORD for others)
+   Var name: ___
+
+4. (Optional) Provision script path — the skill only records the path, never creates it
+   (convention: scripts/provision-e2e-user.ts — leave blank to skip)
+   Path: ___
+```
+
+After collecting the env-file path, verify it is gitignored and capture the result —
+this boolean is persisted as the required `credentials.gitignored` field:
+
+```bash
+git check-ignore -q <env_file_path> && GITIGNORED=true || GITIGNORED=false
+```
+
+If NOT ignored (`GITIGNORED=false`): warn and offer to append it:
+
+```
+Warning: <path> is not in .gitignore.
+This file will contain live credentials — committing it is a credential leak.
+Append <path> to .gitignore? (Y/n)
+```
+
+On yes: append the path to `.gitignore` and set `GITIGNORED=true`. On no: leave
+`GITIGNORED=false` and record in the output but do not block.
+
+Carry `gitignored: $GITIGNORED` into the credentials block assembled for Step 5 — the
+`E2eCredentials.gitignored` field is required, so it must always be populated.
+
+Never write secret values into e2e.json — only the path, var names, and provision_script
+reference are persisted.
+
+## Step 5 — Write .codebyplan/e2e.json
+
+Build the updated payload conforming to the `E2eConfig` schema
+(`packages/codebyplan-package/src/lib/types.ts`).
+
+For playwright, derive `base_url` from `.codebyplan/server.json`:
+
+```bash
+jq -r '.port_allocations[] | select(.label == "Web Dev") | "http://localhost:\(.port)"' \
+  .codebyplan/server.json | head -1
+```
+
+Match by the `Web Dev` label rather than `server_type == "nextjs"` — a repo can have
+several `nextjs` allocations (e.g. one per sibling worktree), so array-position
+`head -1` is not stable. Confirm the derived URL with the user before writing
+(`Derived base_url: <url> — correct? (Y/n)`) and allow an override. Store as
+`frameworks.playwright.base_url`.
+
+Idempotency rule: the jq object-merge (`. + {...}`) REPLACES top-level keys, so build
+`$CREDENTIALS_JSON` as a deep-merge of the existing block and the newly-collected data
+BEFORE the write — otherwise a second run for an additional framework would clobber the
+first framework's credentials. Assemble it in the shell:
+
+```bash
+EXISTING_CREDS=$(jq -c '.credentials // {}' .codebyplan/e2e.json)
+CREDENTIALS_JSON=$(echo "$EXISTING_CREDS" | jq -c --argjson new "$NEW_CREDS_JSON" '. * $new')
+```
+
+The `*` operator deep-merges, so frameworks skipped by the idempotency gate keep their
+prior entry. Then write atomically using jq temp+mv to avoid partial writes (only the two
+schema fields `frameworks` and `credentials` are written — `E2eConfig` defines no other):
+
+```bash
+jq --argjson frameworks "$FRAMEWORKS_JSON" \
+   --argjson credentials "$CREDENTIALS_JSON" \
+   '. + {frameworks: $frameworks, credentials: $credentials}' \
+   .codebyplan/e2e.json > .codebyplan/e2e.json.tmp \
+   && mv .codebyplan/e2e.json.tmp .codebyplan/e2e.json
+```
+
+Framework config shape per framework:
+
+| Field        | playwright          | maestro / xcuitest   | tauri / vscode |
+| ------------ | ------------------- | -------------------- | -------------- |
+| `enabled`    | true                | true                 | true           |
+| `app`        | `apps/web` (nextjs) | `apps/<expo-app>`    | `apps/desktop` / `apps/vscode` |
+| `config_path`| `playwright.config.ts` | `maestro/config.yaml` | `wdio.conf.ts` / `.vscode-test.mjs` |
+| `auto_run`   | false               | false                | false          |
+| `test_dir`   | `apps/web/e2e`      | —                    | —              |
+| `base_url`   | from server.json    | —                    | —              |
+| `platforms`  | —                   | from Step 3          | —              |
+
+Disabled frameworks get `enabled: false`; all other fields are preserved from their
+prior configured state.
+
+## Step 6 — Verify and report
+
+Re-read `.codebyplan/e2e.json` and emit a per-framework summary:
+
+```
+E2E Setup — Complete
+
+Framework   | Status   | App        | base_url / platforms  | Creds source
+----------- | -------- | ---------- | --------------------- | ------------
+playwright  | enabled  | apps/web   | http://localhost:3010 | .codebyplan/e2e.env (E2E_TEST_EMAIL)
+maestro     | disabled | —          | —                     | —
+...
+
+e2e.json written to .codebyplan/e2e.json
+
+Next steps per framework — see reference docs:
+  playwright  → reference/playwright.md
+  maestro     → reference/maestro.md
+  xcuitest    → reference/xcuitest.md
+  tauri       → reference/tauri.md
+  vscode      → reference/vscode.md
+```
+
+## Key Rules
+
+- Never write secret values into e2e.json — only env-file path + var names
+- Gitignore guard runs before any credentials are persisted
+- Preserved credentials blocks are printed verbatim so the user can verify them
+- Atomic write (tmp + mv) — never leaves e2e.json in a partial state
+- `auto_run: false` by default — the user opts in explicitly
+
+## Additional resources
+
+- Playwright install + auth + CI: [reference/playwright.md](reference/playwright.md)
+- Maestro install + flows + CI: [reference/maestro.md](reference/maestro.md)
+- Tauri (WebDriverIO): [reference/tauri.md](reference/tauri.md)
+- VS Code extension testing: [reference/vscode.md](reference/vscode.md)
+- XCUITest (iOS native): [reference/xcuitest.md](reference/xcuitest.md)
+- E2E schema types: `packages/codebyplan-package/src/lib/types.ts` (E2eConfig)
+- Shared E2E conventions: `.claude/context/testing/e2e.md`

package/templates/skills/cbp-e2e-setup/reference/maestro.md

@@ -0,0 +1,200 @@
+# Maestro Reference
+
+Full install, config, flows, and CI walkthrough for Maestro on an Expo/React Native project.
+Source: vendor/maestro/v2.6 + `.claude/context/testing/e2e.md`.
+
+## Prerequisites
+
+- Java 17 or later: `java -version` (install via `brew install openjdk@17` on macOS)
+- Android emulator (for android targets) or iOS Simulator (for ios targets)
+- Expo app bundled and running on the target device/emulator
+
+## Install
+
+```bash
+# macOS — recommended
+curl -fsSL "https://get.maestro.mobile.dev" | bash
+
+# Alternative: Homebrew tap
+brew tap mobile-dev-inc/tap
+brew install maestro
+```
+
+Verify:
+
+```bash
+maestro --version
+```
+
+Update later with: `maestro upgrade`
+
+## maestro/config.yaml
+
+Create at repo root under `maestro/config.yaml`:
+
+```yaml
+# Maestro workspace configuration
+# See: https://docs.maestro.dev/maestro-flows/workspace-management/repository-configuration
+
+appId: com.yourorg.yourapp   # must match app.config.ts / expo config
+env:
+  TEST_EMAIL: ${TEST_EMAIL}
+  TEST_PASSWORD: ${TEST_PASSWORD}
+  APP_ID: com.yourorg.yourapp
+```
+
+`appId` must match the value in `app.config.ts` `ios.bundleIdentifier` /
+`android.package`. If they differ across platforms, use the Android package ID for
+Maestro's `appId` on Android and the iOS bundle ID on iOS tests.
+
+## Shared login flow
+
+Create `maestro/flows/_shared/login.yaml`:
+
+```yaml
+appId: ${APP_ID}
+---
+- launchApp:
+    clearState: true
+- assertVisible: "Sign in"
+- tapOn: "Email"
+- inputText: ${TEST_EMAIL}
+- tapOn: "Password"
+- inputText: ${TEST_PASSWORD}
+- tapOn: "Sign in"
+- assertVisible:
+    text: ".*"        # Replace with a post-login element (e.g. "Dashboard")
+    timeout: 15000
+```
+
+Reference it from any other flow:
+
+```yaml
+- runFlow: _shared/login.yaml
+```
+
+## Auth probe flow
+
+`maestro/flows/_probe/auth.yaml` — minimal login verification:
+
+```yaml
+appId: ${APP_ID}
+tags:
+  - probe
+---
+- launchApp:
+    clearState: true
+- assertVisible: "Sign in"
+- tapOn: "Email"
+- inputText: ${TEST_EMAIL}
+- tapOn: "Password"
+- inputText: ${TEST_PASSWORD}
+- tapOn: "Sign in"
+- assertVisible:
+    text: ".*"
+    timeout: 15000
+```
+
+Run the probe before the full suite: `maestro test maestro/flows/_probe/auth.yaml`
+
+## Platform targeting
+
+Maestro v2.6 exposes `-p` / `--platform` as a global option (placed BEFORE the `test`
+subcommand). Values: `android`, `ios`, or `web`.
+
+Run on Android: start an Android emulator, then
+
+```bash
+maestro --platform=android test maestro/flows/
+```
+
+Run on iOS: boot an iOS Simulator, then
+
+```bash
+maestro --platform=ios test maestro/flows/
+```
+
+Omitting the flag is also valid — platform is then implicit from whichever single
+emulator/simulator is currently running.
+
+Target a specific device by UDID / emulator name:
+
+```bash
+maestro test --device <device-id> maestro/flows/
+```
+
+## Directory structure
+
+```
+maestro/
+  config.yaml
+  flows/
+    _shared/
+      login.yaml
+      open-side-menu.yaml
+    _probe/
+      auth.yaml
+    onboarding/
+      signup.yaml
+    home/
+      dashboard.yaml
+```
+
+One subdirectory per app module under `maestro/flows/`. Shared flows under `_shared/`.
+
+## Screenshots
+
+```yaml
+- takeScreenshot: "after-login"
+```
+
+Configure a repo-local screenshots path in `maestro/config.yaml`:
+
+```yaml
+screenshotsDir: maestro/screenshots
+```
+
+## pnpm scripts
+
+Add to root `package.json`:
+
+```json
+{
+  "scripts": {
+    "maestro:test": "maestro test maestro/flows/",
+    "maestro:test:probe": "maestro test maestro/flows/_probe/",
+    "maestro:studio": "maestro studio"
+  }
+}
+```
+
+## CI (GitHub Actions)
+
+Maestro CI runs require a connected device. For GitHub Actions use
+[Maestro Cloud](https://cloud.maestro.dev) or a self-hosted runner with a connected
+device. A minimal Maestro Cloud step:
+
+```yaml
+- name: Run Maestro flows
+  uses: mobile-dev-inc/action-maestro-cloud@v1
+  with:
+    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
+    app-file: path/to/app.apk   # or .ipa
+    flow-file: maestro/flows/
+  env:
+    TEST_EMAIL: ${{ secrets.TEST_EMAIL }}
+    TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
+```
+
+For local self-hosted runner, set `TEST_EMAIL` and `TEST_PASSWORD` as runner env vars.
+
+## Pitfalls
+
+**App ID mismatch** — `appId` in config.yaml must exactly match the compiled bundle
+identifier. Re-run `expo prebuild` if you changed the identifier after prebuild.
+
+**clearState: true** — always clear app state in `launchApp` for the login flow so
+each run starts from a signed-out state.
+
+**Java version** — Maestro requires Java 17+. If `maestro --version` fails, check
+`JAVA_HOME` or install via Homebrew.

package/templates/skills/cbp-e2e-setup/reference/playwright.md

@@ -0,0 +1,212 @@
+# Playwright Reference
+
+Full install, config, auth, and CI walkthrough for Playwright on a Next.js monorepo.
+Source: vendor/playwright/v1.60 + `.claude/context/testing/e2e.md`.
+
+## Install
+
+```bash
+pnpm add -D @playwright/test
+pnpm exec playwright install chromium
+```
+
+For CI with system dependencies:
+
+```bash
+pnpm exec playwright install --with-deps chromium
+```
+
+## playwright.config.ts
+
+Derive `baseURL` from `.codebyplan/server.json` at config-read time:
+
+```ts
+import { defineConfig, devices } from "@playwright/test";
+import { execSync } from "child_process";
+import path from "path";
+
+// Pull the Web Dev port from server.json so config stays in sync. Match by label
+// rather than server_type — a repo can have several nextjs allocations, so
+// array-position head -1 is not stable.
+function getBaseUrl(): string {
+  try {
+    const raw = execSync(
+      "jq -r '.port_allocations[] | select(.label==\"Web Dev\") | .port' .codebyplan/server.json 2>/dev/null | head -1",
+      { encoding: "utf-8" }
+    ).trim();
+    const port = parseInt(raw, 10);
+    return `http://localhost:${port}`;
+  } catch {
+    return "http://localhost:3010"; // fallback
+  }
+}
+
+export default defineConfig({
+  testDir: "apps/web/e2e",
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1, // serialize against shared remote Supabase — see e2e.md § Supabase Parallelism
+  reporter: process.env.CI ? "github" : "html",
+  globalSetup: "./apps/web/e2e/global-setup", // string path — resolved relative to config; safe under ESM
+  use: {
+    baseURL: getBaseUrl(),
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+  },
+  projects: [
+    { name: "setup", testMatch: /global\.setup\.ts/ },
+    {
+      name: "web",
+      use: { ...devices["Desktop Chrome"], storageState: "apps/web/e2e/.auth/user.json" },
+      dependencies: ["setup"],
+    },
+  ],
+  webServer: {
+    command: "pnpm --filter @codebyplan/web dev",
+    url: getBaseUrl(),
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+Key options:
+
+| Option | Why |
+| --- | --- |
+| `workers: 1` | Prevents auth/RLS races on a shared remote Supabase project |
+| `globalSetup` | Logs in once, writes `storageState` so tests start authenticated |
+| `reuseExistingServer` | Skip dev-server startup when already running locally |
+
+## Auth — global setup + storage state
+
+Create `apps/web/e2e/global-setup.ts`:
+
+```ts
+import { chromium, FullConfig } from "@playwright/test";
+import path from "path";
+
+const AUTH_FILE = path.join(__dirname, ".auth/user.json");
+
+export default async function globalSetup(config: FullConfig) {
+  const email = process.env.E2E_TEST_EMAIL;
+  const password = process.env.E2E_TEST_PASSWORD;
+
+  if (!email || !password) {
+    throw new Error(
+      "E2E_TEST_EMAIL and E2E_TEST_PASSWORD must be set.\n" +
+        "Copy .env.local.example to .env.local, then run: pnpm e2e:provision"
+    );
+  }
+
+  const { baseURL } = config.projects[0].use;
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  await page.goto(`${baseURL}/login`);
+  await page.getByLabel(/email/i).fill(email);
+  await page.getByLabel(/password/i).fill(password);
+  await page.getByRole("button", { name: /sign in|log in/i }).click();
+  await page.waitForURL(/\/(dashboard|home|app)/, { timeout: 15_000 });
+
+  // Warm up the first route to avoid cold-start timeouts in specs
+  await page.goto(baseURL!);
+  await page.context().storageState({ path: AUTH_FILE });
+  await browser.close();
+}
+```
+
+Gitignore the auth state — run before first use:
+
+```bash
+mkdir -p apps/web/e2e/.auth
+echo "apps/web/e2e/.auth/" >> .gitignore
+```
+
+## Auth probe spec
+
+`apps/web/e2e/_probe/auth.spec.ts` — validates the login path directly (outside
+storage-state flow) so credential failures are diagnosed cleanly:
+
+```ts
+import { test, expect } from "@playwright/test";
+
+test("auth probe: can log in with E2E_TEST_EMAIL/E2E_TEST_PASSWORD", async ({
+  page,
+}) => {
+  const email = process.env.E2E_TEST_EMAIL;
+  const password = process.env.E2E_TEST_PASSWORD;
+  expect(email, "E2E_TEST_EMAIL env var is required").toBeTruthy();
+  expect(password, "E2E_TEST_PASSWORD env var is required").toBeTruthy();
+
+  await page.goto("/login");
+  await page.getByLabel(/email/i).fill(email!);
+  await page.getByLabel(/password/i).fill(password!);
+  await page.getByRole("button", { name: /sign in|log in/i }).click();
+
+  await expect(page).toHaveURL(/\/(dashboard|home|app)/, { timeout: 15_000 });
+});
+```
+
+Run the probe before the full suite: `pnpm exec playwright test --project=web _probe/auth`.
+
+## Provision script convention
+
+Every repo with Playwright auth ships `scripts/provision-e2e-user.ts` — an idempotent
+script that creates the test user in the dev Supabase project. Wire it to `package.json`:
+
+```json
+{
+  "scripts": {
+    "e2e:provision": "tsx scripts/provision-e2e-user.ts"
+  }
+}
+```
+
+The skill records the path; the repo author writes the script. See
+`.claude/context/testing/e2e.md` § Provisioning Playwright credentials for the full
+contract (idempotency, multi-tenant subdomain, `.env.local.example`).
+
+## CI secrets
+
+Add these four secrets to the GitHub repo (Settings → Secrets → Actions):
+
+| Secret | Purpose |
+| --- | --- |
+| `E2E_TEST_EMAIL` | Test account email |
+| `E2E_TEST_PASSWORD` | Test account password |
+| `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL |
+| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | Supabase publishable (anon) key |
+
+## GitHub Actions snippet
+
+```yaml
+- name: Install Playwright browsers
+  run: pnpm exec playwright install --with-deps chromium
+
+- name: Run Playwright tests
+  run: pnpm exec playwright test
+  env:
+    E2E_TEST_EMAIL: ${{ secrets.E2E_TEST_EMAIL }}
+    E2E_TEST_PASSWORD: ${{ secrets.E2E_TEST_PASSWORD }}
+    NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
+    NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: ${{ secrets.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY }}
+```
+
+## Pitfalls
+
+**Cold-start timeouts** — Next.js dev mode compiles routes lazily. The warmup fetch in
+`globalSetup` (after `page.goto(baseURL!)`) primes the compiler before specs run.
+
+**SCSS Module selectors** — prefer `[class*='componentName']` with `.first()` over
+positional `.nth(N)` locators. Prefer `getByRole`/`getByLabel`/`getByTestId` when
+accessible names are available.
+
+**SCSS import errors in tests** — Playwright runs in Node, not webpack. If your test
+imports a component that imports SCSS, configure `playwright.config.ts` to use
+`@playwright/test`'s built-in transform or exclude such imports.
+
+**Port mismatch** — before running, compare `playwright.config.ts` `baseURL` port with
+`.codebyplan/server.json`. On mismatch, the `cbp-e2e-playwright` agent will ask which is
+correct — do not guess.