codebyplan 1.11.1 → 1.11.2

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.11.1";
+    VERSION = "1.11.2";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -1195,6 +1195,11 @@ async function writeCodebyplanDirectory(projectPath, selectedRepo, deviceId) {
     JSON.stringify({}, null, 2) + "\n",
     "utf-8"
   );
+  await writeFile5(
+    join5(codebyplanDir, "e2e.json"),
+    JSON.stringify({}, null, 2) + "\n",
+    "utf-8"
+  );
   const statuslinePath = join5(codebyplanDir, "statusline.json");
   let statuslineExists = false;
   try {
@@ -1212,7 +1217,7 @@ async function writeCodebyplanDirectory(projectPath, selectedRepo, deviceId) {
   await writeLocalConfig(projectPath, { device_id: deviceId });
   console.log(`  Created ${codebyplanDir}/`);
   console.log(
-    `    repo.json, server.json, git.json, shipment.json, vendor.json, statusline.json`
+    `    repo.json, server.json, git.json, shipment.json, vendor.json, e2e.json, statusline.json`
   );
   console.log(`    device.local.json (gitignored)`);
   const gitignorePath = join5(projectPath, ".gitignore");
@@ -2161,6 +2166,9 @@ var init_tech_detect = __esm({
       "@playwright/test": { name: "Playwright", category: "testing" },
       cypress: { name: "Cypress", category: "testing" },
       supertest: { name: "Supertest", category: "testing" },
+      webdriverio: { name: "WebdriverIO", category: "testing" },
+      "@wdio/cli": { name: "WebdriverIO", category: "testing" },
+      "@vscode/test-cli": { name: "VS Code Test CLI", category: "testing" },
       // Build tools
       turbo: { name: "Turborepo", category: "build" },
       vite: { name: "Vite", category: "build" },
@@ -2245,7 +2253,28 @@ var init_tech_detect = __esm({
         rule: { name: "shadcn/ui", category: "component-lib" }
       },
       { file: "nx.json", rule: { name: "Nx", category: "build" } },
-      { file: "lerna.json", rule: { name: "Lerna", category: "build" } }
+      { file: "lerna.json", rule: { name: "Lerna", category: "build" } },
+      {
+        file: "playwright.config.ts",
+        rule: { name: "Playwright", category: "testing" }
+      },
+      {
+        file: "playwright.config.js",
+        rule: { name: "Playwright", category: "testing" }
+      },
+      {
+        file: "playwright.config.mjs",
+        rule: { name: "Playwright", category: "testing" }
+      },
+      { file: "wdio.conf.ts", rule: { name: "WebdriverIO", category: "testing" } },
+      {
+        file: "wdio.conf.js",
+        rule: { name: "WebdriverIO", category: "testing" }
+      },
+      {
+        file: "maestro/config.yaml",
+        rule: { name: "Maestro", category: "testing" }
+      }
     ];
     SYNTHETIC_CARRIER_NAME = "__capabilities__";
     CAPABILITY_BEARER_NAMES = /* @__PURE__ */ new Set([
@@ -4452,6 +4481,13 @@ async function runLocalMigration(projectPath) {
     "utf-8"
   );
   filesChanged.push(".codebyplan/vendor.json");
+  const e2eJson = {};
+  await writeFile9(
+    join13(projectPath, ".codebyplan", "e2e.json"),
+    JSON.stringify(e2eJson, null, 2) + "\n",
+    "utf-8"
+  );
+  filesChanged.push(".codebyplan/e2e.json");
   if (!deviceWrittenByHelper) {
     await writeFile9(
       join13(projectPath, ".codebyplan", "device.local.json"),
@@ -4519,6 +4555,7 @@ var init_migrate_local_config = __esm({
 // src/cli/config.ts
 var config_exports = {};
 __export(config_exports, {
+  readE2eConfig: () => readE2eConfig,
   readGitConfig: () => readGitConfig,
   readRepoConfig: () => readRepoConfig,
   readServerConfig: () => readServerConfig,
@@ -4685,6 +4722,7 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
     shipmentPayload.shipment = repoAny.shipment;
   }
   const vendorPayload = {};
+  const e2ePayload = {};
   if (dryRun) {
     console.log("  Config would be updated (dry-run).");
     return;
@@ -4695,10 +4733,11 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
     { name: "server.json", payload: serverPayload },
     { name: "git.json", payload: gitPayload },
     { name: "shipment.json", payload: shipmentPayload },
-    { name: "vendor.json", payload: vendorPayload }
+    { name: "vendor.json", payload: vendorPayload },
+    { name: "e2e.json", payload: e2ePayload, createOnly: true }
   ];
   let anyUpdated = false;
-  for (const { name, payload } of files) {
+  for (const { name, payload, createOnly } of files) {
     const filePath = join14(codebyplanDir, name);
     const newJson = JSON.stringify(payload, null, 2) + "\n";
     let currentJson = "";
@@ -4706,6 +4745,7 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
       currentJson = await readFile13(filePath, "utf-8");
     } catch {
     }
+    if (createOnly && currentJson !== "") continue;
     if (currentJson === newJson) continue;
     await writeFile10(filePath, newJson, "utf-8");
     console.log(`  Updated .codebyplan/${name}`);
@@ -4770,6 +4810,17 @@ async function readVendorConfig(projectPath) {
     return null;
   }
 }
+async function readE2eConfig(projectPath) {
+  try {
+    const raw = await readFile13(
+      join14(projectPath, ".codebyplan", "e2e.json"),
+      "utf-8"
+    );
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 var legacyBranchConfigWarned;
 var init_config = __esm({
   "src/cli/config.ts"() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.11.1",
+  "version": "1.11.2",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/README.md

@@ -11,7 +11,7 @@ This directory holds the installed content that the `codebyplan claude install`
 | Path      | Count                                | Shape                                                                                           |
 | --------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
 | `skills/` | 41 folders                           | each is a `SKILL.md` plus optional `templates/`, `reference/`, `examples/`, `scripts/` siblings |
-| `agents/` | 12 files                             | flat `.md` agent prompts (NOT `AGENT.md` subdirs)                                               |
+| `agents/` | 16 files                             | flat `.md` agent prompts (NOT `AGENT.md` subdirs)                                               |
 | `hooks/`  | 20 `.sh` + `hooks.json` + `README.md` | event hooks and manifest                                                                        |
 | `rules/`  | 1+ files                             | flat `<name>.md` rule files; see `rules/README.md` for bar and format                           |
 

package/templates/agents/cbp-cc-executor.md

@@ -82,7 +82,7 @@ Before processing any change, build a fresh inventory:
 
 1. Glob `.claude/rules/*.md` — read name + frontmatter
 2. Glob `.claude/skills/*/SKILL.md` — read name + description
-3. Glob `.claude/agents/*/AGENT.md` — read name + description
+3. Glob `.claude/agents/*.md` (and `.claude/agents/*/AGENT.md` for folder-form agents) — read name + description
 4. Glob `.claude/context/**/*.md` — read path + first heading
 5. Glob `.claude/docs/architecture/*.md` — read path + first heading
 6. Glob `.claude/hooks/*.sh` — read path + header block

package/templates/agents/cbp-e2e-maestro.md

@@ -0,0 +1,202 @@
+---
+name: cbp-e2e-maestro
+description: Maestro E2E flow authoring + execution for Expo/React Native mobile apps (android + ios). Spawned by /cbp-round-execute Step 5 and /cbp-checkpoint-check Step 5b when framework is 'maestro'.
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
+model: sonnet
+effort: xhigh
+scope: org-shared
+---
+
+# Maestro E2E Agent
+
+Read `context/testing/e2e.md` for the shared contract (Input/Output, Step 6.5 preflight,
+Step 7.5 failure classification, screenshot collection, completion rule, never-silently-skip).
+
+Framework: Maestro on Expo / React Native. Dispatched when `.codebyplan/e2e.json`
+records `framework: "maestro"`.
+
+## Prerequisites
+
+- Java 17+: `java -version` (install via `brew install openjdk@17` on macOS)
+- Android emulator OR iOS Simulator
+- Expo app bundled and running on target device/emulator
+
+## Install
+
+```bash
+# macOS
+curl -fsSL "https://get.maestro.mobile.dev" | bash
+# or: brew tap mobile-dev-inc/tap && brew install maestro
+maestro --version   # verify
+```
+
+## maestro/config.yaml
+
+```yaml
+appId: com.yourorg.yourapp   # must match app.config.ts ios.bundleIdentifier / android.package
+env:
+  TEST_EMAIL: ${TEST_EMAIL}
+  TEST_PASSWORD: ${TEST_PASSWORD}
+  APP_ID: com.yourorg.yourapp
+screenshotsDir: maestro/screenshots
+```
+
+## Shared Login Flow
+
+`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 from other flows: `- runFlow: _shared/login.yaml`
+
+## Auth Probe
+
+`maestro/flows/_probe/auth.yaml`:
+
+```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 probe: `maestro test maestro/flows/_probe/auth.yaml`
+
+## Pre-flight Probes (Step 6.5.2)
+
+**iOS**: `xcrun simctl list devices booted | grep -q Booted`
+
+> "No iOS Simulator is booted. Open Simulator.app or run `xcrun simctl boot 'iPhone 15'`.
+> Reply 'ready' when the simulator home screen is visible."
+
+**Android**: `adb devices | grep -w device`
+
+> "No Android device/emulator connected. Start an emulator from Android Studio or run
+> `emulator -avd {name}`. Reply 'ready' when unlocked."
+
+## Platform Targeting
+
+```bash
+# iOS
+maestro --platform=ios test maestro/flows/
+
+# Android
+maestro --platform=android test maestro/flows/
+
+# Specific device
+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. Shared flows under `_shared/`. Probe under `_probe/`.
+
+## Spec-Writing Patterns
+
+**One flow per screen/feature.** Steps:
+
+```yaml
+appId: ${APP_ID}
+tags:
+  - home
+---
+- runFlow: _shared/login.yaml
+- assertVisible: "Dashboard"
+- takeScreenshot: "dashboard-loaded"
+- tapOn: "Create"
+- assertVisible: "New item"
+- takeScreenshot: "create-modal-open"
+```
+
+Use text-based targeting first (`tapOn: "Button"`); use testID when ambiguous
+(`tapOn: { id: "btn" }`). For CRUD: create + verify visible; edit + verify updated;
+delete + confirm + verify removed.
+
+## Screenshot Capture
+
+```yaml
+- takeScreenshot: "flow-name-after-state"
+```
+
+Screenshots written to `maestro/screenshots/` (via `screenshotsDir` in `config.yaml`).
+Enumerate: `maestro/screenshots/*.png`.
+
+## Run Command
+
+```bash
+maestro test maestro/flows/{module}/{flow}.yaml --format=junit --output maestro/results.xml
+```
+
+## pnpm Scripts
+
+```json
+{
+  "scripts": {
+    "maestro:test": "maestro test maestro/flows/",
+    "maestro:test:probe": "maestro test maestro/flows/_probe/",
+    "maestro:studio": "maestro studio"
+  }
+}
+```
+
+## CI
+
+Maestro CI requires a connected device. Use Maestro Cloud or a self-hosted runner:
+
+```yaml
+- uses: mobile-dev-inc/action-maestro-cloud@v1
+  with:
+    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
+    app-file: path/to/app.apk
+    flow-file: maestro/flows/
+  env:
+    TEST_EMAIL: ${{ secrets.TEST_EMAIL }}
+    TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
+```
+
+## Pitfalls
+
+**App ID mismatch** — `appId` must exactly match the compiled bundle identifier. Re-run
+`expo prebuild` if the identifier changed after prebuild. **clearState: true** — always
+clear app state in `launchApp` for the login flow. **Java version** — Maestro requires
+Java 17+; check `JAVA_HOME` if `maestro --version` fails.

package/templates/agents/cbp-e2e-playwright.md

@@ -0,0 +1,229 @@
+---
+name: cbp-e2e-playwright
+description: Playwright E2E test authoring + execution for web app routes. Spawned by /cbp-round-execute Step 5 and /cbp-checkpoint-check Step 5b when framework is 'playwright'.
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
+model: sonnet
+effort: xhigh
+scope: org-shared
+---
+
+# Playwright E2E Agent
+
+Read `context/testing/e2e.md` for the shared contract (Input/Output, Step 6.5 preflight,
+Step 7.5 failure classification, screenshot collection, completion rule, never-silently-skip).
+
+Framework: Playwright on Next.js web apps. Dispatched when `.codebyplan/e2e.json`
+records `framework: "playwright"`.
+
+## Install
+
+```bash
+pnpm add -D @playwright/test
+pnpm exec playwright install chromium
+# CI with system deps:
+pnpm exec playwright install --with-deps chromium
+```
+
+## playwright.config.ts
+
+Derive `baseURL` from `.codebyplan/server.json` at config-read time. Match by label
+(`"Web Dev"`) rather than array position — a monorepo can have several nextjs allocations.
+
+```ts
+import { defineConfig, devices } from "@playwright/test";
+import { execSync } from "child_process";
+
+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";
+  }
+}
+
+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",
+  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,
+  },
+});
+```
+
+## Auth — Global Setup + Storage State
+
+`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 });
+
+  await page.goto(baseURL!);   // cold-start warmup
+  await page.context().storageState({ path: AUTH_FILE });
+  await browser.close();
+}
+```
+
+Gitignore storage state before first use:
+
+```bash
+mkdir -p apps/web/e2e/.auth
+echo "apps/web/e2e/.auth/" >> .gitignore
+```
+
+## Auth Probe
+
+`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 probe: `pnpm exec playwright test --project=web _probe/auth`
+
+## Pre-flight Probes (Step 6.5.2)
+
+**Dev server**: `curl -s -o /dev/null -w "%{http_code}" http://localhost:{port}/` — expect
+200/3xx. On failure:
+
+> "Dev server is not responding on port `{port}`. Please run `cd apps/{app} && pnpm dev`
+> in a separate terminal, then reply 'ready' when the page loads in your browser."
+
+**Port alignment**: parse `playwright.config.ts` `baseURL` port; compare to
+`.codebyplan/server.json` `port_allocations[]`. On mismatch ask which is correct, then
+propose an Edit to align them.
+
+## Spec-Writing Patterns
+
+**One spec file per page/flow.** Mandatory per spec:
+
+- Smoke test: loads, title correct, no console errors.
+- Primary user flow: main interaction.
+- Visual regression: `toHaveScreenshot` at every primary state.
+
+For forms: fill + submit + verify success; validation errors.
+For CRUD: create + verify; edit + verify; delete + confirm + verify.
+
+```ts
+import { test, expect } from "@playwright/test";
+
+test.describe("Home page", () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto("/");
+  });
+
+  test("loads and shows heading", async ({ page }) => {
+    await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
+    await expect(page).toHaveScreenshot("home-loaded.png", { maxDiffPixelRatio: 0.001 });
+  });
+});
+```
+
+## Screenshot Capture
+
+**Baseline regression** (preferred):
+```ts
+await expect(page).toHaveScreenshot("state-name.png", { maxDiffPixelRatio: 0.001 });
+```
+Baselines live beside spec under `{spec}.spec.ts-snapshots/`. Committed to git.
+
+**Diagnostic** (intermediate states):
+```ts
+await page.screenshot({
+  path: `test-results/screenshots/${test.info().title}-after-submit.png`,
+  fullPage: true,
+});
+```
+
+Enumerate PNGs: `test-results/**/*.png` and `{spec}.spec.ts-snapshots/`.
+
+**Never run `--update-snapshots` automatically.** A diff is a `visual_regression` failure.
+
+## Run Command
+
+```bash
+pnpm exec playwright test {spec} --project=web --reporter=list
+```
+
+## Selector Conventions
+
+Prefer `getByRole`, `getByLabel`, `getByTestId` over positional CSS. For SCSS Modules:
+`[class*='componentName']` with `.first()`. After navigation, re-query selectors from
+the new page state rather than holding stale `Locator` handles.
+
+## CI Secrets
+
+`E2E_TEST_EMAIL`, `E2E_TEST_PASSWORD`, `NEXT_PUBLIC_SUPABASE_URL`,
+`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (or legacy `_ANON_KEY`).
+
+## Pitfalls
+
+**Cold-start timeouts** — warmup in `globalSetup` (after `page.goto(baseURL!)`) primes
+Turbopack compilation. **Port mismatch** — compare `baseURL` port to `server.json` before
+running. **Supabase parallelism** — remote Supabase requires `workers: 1` to prevent
+auth/RLS races. **SCSS Module selectors** — use `[class*='componentName'].first()` or
+role-based selectors.