Skip to content

Beautiful Open-Source Form Builder

chore: isolate Codex worktree development environments (#1203)

Julien Nahum7e4354c68787
diff --git a/.codex/environments/environment.toml b/.codex/environments/environment.toml
new file mode 100644
index 000000000..37958861b
--- /dev/null
+++ b/.codex/environments/environment.toml
@@ -0,0 +1,46 @@
+version = 1
+name = "opnform"
+
+[setup]
+script = '''
+cd "${CODEX_WORKTREE_PATH:-$PWD}"
+./scripts/codex-worktree-setup.sh
+'''
+
+[cleanup]
+script = '''
+cd "${CODEX_WORKTREE_PATH:-$PWD}"
+./scripts/codex-worktree-destroy.sh
+'''
+
+[[actions]]
+name = "Start app"
+icon = "run"
+command = '''
+cd "${CODEX_WORKTREE_PATH:-$PWD}"
+./scripts/codex-worktree-up.sh
+'''
+
+[[actions]]
+name = "Reset DB"
+icon = "test"
+command = '''
+cd "${CODEX_WORKTREE_PATH:-$PWD}"
+./scripts/codex-worktree-reset-db.sh
+'''
+
+[[actions]]
+name = "Stop app"
+icon = "debug"
+command = '''
+cd "${CODEX_WORKTREE_PATH:-$PWD}"
+./scripts/codex-worktree-down.sh
+'''
+
+[[actions]]
+name = "Run E2E"
+icon = "test"
+command = '''
+cd "${CODEX_WORKTREE_PATH:-$PWD}"
+./scripts/codex-worktree-test-e2e.sh
+'''
diff --git a/.gitignore b/.gitignore
index a72daf4a3..2d2f6ddd8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,8 @@ public/.DS_Store
*.DS_Store
docker-compose.override.yml
/.make.*
+/.e2e/
+/.playwright/
# Environment files
.env
diff --git a/AGENTS.md b/AGENTS.md
index 42dc9c65b..f54f8e2e0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -39,6 +39,15 @@ Instructions for AI coding agents working in this repository.
- If backend code changed, run relevant `php artisan test --filter=...` and broaden only if needed.
- Report what was run and what could not be run.
+## Codex Worktrees
+
+- Codex worktrees use the managed environment in `.codex/environments`.
+- The setup action provisions an isolated PostgreSQL Docker volume and seeded local Laravel/Nuxt stack for the current checkout.
+- Use the `Start app`, `Reset DB`, `Stop app`, and `Run E2E` actions, or their `scripts/codex-worktree-*.sh` equivalents.
+- The scripts print the worktree-specific UI URL. Verify this URL before trusting browser results; do not use the shared `docker-compose.dev.yml` stack for worktree checks.
+- Opening the worktree root URL signs in the seeded global and workspace admin automatically. Its credentials are `[email protected]` / `Abcd@1234` for manual and automated tests.
+- The seed includes three sample forms and five completed submissions across two public forms.
+
## Project Conventions
- Frontend:
diff --git a/README.md b/README.md
index 3a973c24c..031290a3f 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,29 @@ The easiest way to get started with OpnForm is through our [official managed ser
For self-hosted installations, please refer to our [Deployment Guides](https://docs.opnform.com/deployment). For local development, we provide a minimal Docker-based setup - check out our [Docker Development Guide](https://docs.opnform.com/deployment/docker-development).
+## Codex worktrees
+
+Codex creates an isolated local environment for each worktree. It uses a dedicated PostgreSQL Docker volume and local Laravel/Nuxt processes, so sibling worktrees do not share ports, data, or API configuration.
+
+Use the Codex `Start app`, `Reset DB`, and `Stop app` actions when available. You can also run the scripts directly:
+
+```bash
+./scripts/codex-worktree-setup.sh
+./scripts/codex-worktree-up.sh
+```
+
+The startup command prints the worktree-specific URL. Opening its root URL automatically signs in the local Codex admin (`[email protected]` / `Abcd@1234`). The seed also creates three forms, including five completed submissions across two public forms, so the dashboard and submission screens are immediately useful. Reset only the current worktree database with:
+
+```bash
+./scripts/codex-worktree-reset-db.sh
+```
+
+Run the browser suite against the running worktree with:
+
+```bash
+./scripts/codex-worktree-test-e2e.sh
+```
+
## Support & Community
If you need help or have questions, please join our [Discord community](https://discord.gg/YTSjU2a9TS). For more information and assistance, check out the following resources:
diff --git a/api/database/seeders/E2ETestSeeder.php b/api/database/seeders/E2ETestSeeder.php
index 921de37cc..9477541e7 100644
--- a/api/database/seeders/E2ETestSeeder.php
+++ b/api/database/seeders/E2ETestSeeder.php
@@ -2,22 +2,27 @@
namespace Database\Seeders;
+use App\Models\Forms\Form;
+use App\Models\Forms\FormSubmission;
use App\Models\User;
use App\Models\Workspace;
use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Str;
class E2ETestSeeder extends Seeder
{
public function run(): void
{
+ FormSubmission::query()->delete();
+ Form::withTrashed()->forceDelete();
DB::table('user_workspace')->truncate();
Workspace::query()->delete();
User::query()->delete();
$user = User::query()->create([
- 'name' => 'E2E User',
+ 'name' => 'Codex Admin',
'email' => '[email protected]',
'password' => Hash::make('Abcd@1234'),
'hear_about_us' => 'e2e',
@@ -32,5 +37,120 @@ class E2ETestSeeder extends Seeder
$user->workspaces()->sync([
$workspace->id => ['role' => User::ROLE_ADMIN],
]);
+
+ $feedbackProperties = $this->formProperties([
+ ['name' => 'Full name', 'type' => 'text', 'required' => true],
+ ['name' => 'Email address', 'type' => 'email', 'required' => true],
+ ['name' => 'Satisfaction', 'type' => 'rating', 'required' => true],
+ ['name' => 'Feedback', 'type' => 'text'],
+ ]);
+ $feedbackForm = $this->createForm($user, $workspace, [
+ 'title' => 'Product feedback',
+ 'properties' => $feedbackProperties,
+ 'presentation_style' => 'classic',
+ 'visibility' => 'public',
+ ]);
+ $this->createSubmissions($feedbackForm, [
+ [
+ $feedbackProperties[0]['id'] => 'Alice Martin',
+ $feedbackProperties[1]['id'] => '[email protected]',
+ $feedbackProperties[2]['id'] => 5,
+ $feedbackProperties[3]['id'] => 'The editor is quick and easy to use.',
+ ],
+ [
+ $feedbackProperties[0]['id'] => 'Lucas Bernard',
+ $feedbackProperties[1]['id'] => '[email protected]',
+ $feedbackProperties[2]['id'] => 4,
+ $feedbackProperties[3]['id'] => 'More keyboard shortcuts would be useful.',
+ ],
+ [
+ $feedbackProperties[0]['id'] => 'Maya Dupont',
+ $feedbackProperties[1]['id'] => '[email protected]',
+ $feedbackProperties[2]['id'] => 5,
+ $feedbackProperties[3]['id'] => 'The focused presentation is great for surveys.',
+ ],
+ ]);
+
+ $demoProperties = $this->formProperties([
+ ['name' => 'Work email', 'type' => 'email', 'required' => true],
+ ['name' => 'Company', 'type' => 'text', 'required' => true],
+ [
+ 'name' => 'Team size',
+ 'type' => 'select',
+ 'required' => true,
+ 'options' => [
+ ['name' => '1-10', 'id' => '1-10'],
+ ['name' => '11-50', 'id' => '11-50'],
+ ['name' => '51+', 'id' => '51+'],
+ ],
+ ],
+ ]);
+ $demoForm = $this->createForm($user, $workspace, [
+ 'title' => 'Book a product demo',
+ 'properties' => $demoProperties,
+ 'presentation_style' => 'focused',
+ 'visibility' => 'public',
+ 'show_progress_bar' => true,
+ ]);
+ $this->createSubmissions($demoForm, [
+ [
+ $demoProperties[0]['id'] => '[email protected]',
+ $demoProperties[1]['id'] => 'Acme',
+ $demoProperties[2]['id'] => '11-50',
+ ],
+ [
+ $demoProperties[0]['id'] => '[email protected]',
+ $demoProperties[1]['id'] => 'Northstar',
+ $demoProperties[2]['id'] => '51+',
+ ],
+ ]);
+
+ $this->createForm($user, $workspace, [
+ 'title' => 'Website redesign intake',
+ 'properties' => $this->formProperties([
+ ['name' => 'Project name', 'type' => 'text', 'required' => true],
+ ['name' => 'Target launch date', 'type' => 'date'],
+ ]),
+ 'visibility' => 'draft',
+ ]);
+ }
+
+ private function createForm(User $user, Workspace $workspace, array $attributes): Form
+ {
+ return Form::factory()
+ ->forWorkspace($workspace)
+ ->createdBy($user)
+ ->create($attributes);
+ }
+
+ private function createSubmissions(Form $form, array $submissions): void
+ {
+ foreach ($submissions as $index => $data) {
+ $form->submissions()->create([
+ 'data' => $data,
+ 'completion_time' => 30 + ($index * 15),
+ 'status' => FormSubmission::STATUS_COMPLETED,
+ 'meta' => [
+ 'source' => 'codex-seed',
+ 'utm_source' => 'local-demo',
+ ],
+ 'public_id' => Str::uuid()->toString(),
+ ]);
+ }
+ }
+
+ private function formProperties(array $fields): array
+ {
+ return array_map(function (array $field) {
+ return array_merge([
+ 'id' => Str::uuid()->toString(),
+ 'hidden' => false,
+ 'required' => false,
+ 'placeholder' => $field['name'],
+ 'prefill' => null,
+ 'help' => null,
+ 'notion_name' => $field['name'],
+ ], $field);
+ }, $fields);
}
}
diff --git a/api/tests/Feature/E2ETestSeederTest.php b/api/tests/Feature/E2ETestSeederTest.php
new file mode 100644
index 000000000..c3e211e8f
--- /dev/null
+++ b/api/tests/Feature/E2ETestSeederTest.php
@@ -0,0 +1,24 @@
+<?php
+
+use App\Models\Forms\Form;
+use App\Models\Forms\FormSubmission;
+use App\Models\User;
+use Database\Seeders\E2ETestSeeder;
+
+it('creates the Codex admin with realistic forms and submissions', function () {
+ config(['opnform.admin_emails' => ['[email protected]']]);
+
+ $this->seed(E2ETestSeeder::class);
+
+ $user = User::query()->where('email', '[email protected]')->firstOrFail();
+
+ expect($user->admin)->toBeTrue()
+ ->and($user->workspaces()->wherePivot('role', User::ROLE_ADMIN)->exists())->toBeTrue()
+ ->and(Form::query()->pluck('title')->all())->toEqualCanonicalizing([
+ 'Product feedback',
+ 'Book a product demo',
+ 'Website redesign intake',
+ ])
+ ->and(Form::query()->where('visibility', 'public')->count())->toBe(2)
+ ->and(FormSubmission::query()->count())->toBe(5);
+});
diff --git a/client/plugins/00.codex-auto-login.client.js b/client/plugins/00.codex-auto-login.client.js
new file mode 100644
index 000000000..8091ea6d3
--- /dev/null
+++ b/client/plugins/00.codex-auto-login.client.js
@@ -0,0 +1,28 @@
+import { authApi } from '~/api'
+
+export default defineNuxtPlugin(() => {
+ const config = useRuntimeConfig()
+
+ const isCodexAutoLoginEnabled = config.public.codexAutoLogin
+ && config.public.codexAutoLoginEmail
+ && config.public.codexAutoLoginPassword
+ && !navigator.webdriver
+ && window.location.pathname === '/'
+
+ if (!isCodexAutoLoginEnabled) {
+ return
+ }
+
+ const authStore = useAuthStore()
+ authStore.clearToken()
+
+ return authApi.login({
+ email: config.public.codexAutoLoginEmail,
+ password: config.public.codexAutoLoginPassword,
+ })
+ .then((tokenData) => useAuthFlow().handleAuthSuccess(tokenData, 'codex'))
+ .then(() => navigateTo({ name: 'home' }))
+ .catch((error) => {
+ console.warn('Codex auto-login failed.', error)
+ })
+})
diff --git a/client/runtimeConfig.js b/client/runtimeConfig.js
index 94c292490..ea297705d 100644
--- a/client/runtimeConfig.js
+++ b/client/runtimeConfig.js
@@ -13,6 +13,9 @@ export default {
apiBase: process.env.NUXT_PUBLIC_API_BASE || '',
appUrl: process.env.NUXT_PUBLIC_APP_URL || '',
env: process.env.NUXT_PUBLIC_ENV || 'local',
+ codexAutoLogin: process.env.NUXT_PUBLIC_CODEX_AUTO_LOGIN === 'true',
+ codexAutoLoginEmail: process.env.NUXT_PUBLIC_CODEX_AUTO_LOGIN_EMAIL || null,
+ codexAutoLoginPassword: process.env.NUXT_PUBLIC_CODEX_AUTO_LOGIN_PASSWORD || null,
hCaptchaSiteKey: process.env.NUXT_PUBLIC_H_CAPTCHA_SITE_KEY || null,
reCaptchaSiteKey: process.env.NUXT_PUBLIC_RE_CAPTCHA_SITE_KEY || null,
amplitudeCode: process.env.NUXT_PUBLIC_AMPLITUDE_CODE || null,
diff --git a/client/test/e2e/opnform-flows.spec.ts b/client/test/e2e/opnform-flows.spec.ts
index 596060c7f..659cba7d2 100644
--- a/client/test/e2e/opnform-flows.spec.ts
+++ b/client/test/e2e/opnform-flows.spec.ts
@@ -184,6 +184,9 @@ async function gotoPageWithRetry(page: Page, path: string, readyCheck: () => Pro
const response = await page.goto(path, { waitUntil: "commit", timeout: 10_000 })
expect(response?.status(), `unexpected status for ${path} on attempt ${attempt}`).toBeLessThan(500)
await readyCheck()
+ if (process.env.PLAYWRIGHT_DEV_SERVER === "1") {
+ await page.waitForTimeout(5000)
+ }
return
} catch (error) {
lastError = error
diff --git a/docker-compose.codex.yml b/docker-compose.codex.yml
new file mode 100644
index 000000000..f8b945199
--- /dev/null
+++ b/docker-compose.codex.yml
@@ -0,0 +1,19 @@
+services:
+ db:
+ image: postgres:16
+ environment:
+ POSTGRES_DB: ${CODEX_DB_NAME}
+ POSTGRES_USER: ${CODEX_DB_USERNAME}
+ POSTGRES_PASSWORD: ${CODEX_DB_PASSWORD}
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""]
+ interval: 2s
+ timeout: 5s
+ retries: 30
+ ports:
+ - "127.0.0.1:${CODEX_DB_PORT}:5432"
+ volumes:
+ - codex-postgres-data:/var/lib/postgresql/data
+
+volumes:
+ codex-postgres-data:
diff --git a/docs/deployment/docker-development.mdx b/docs/deployment/docker-development.mdx
index 8586b782c..d6f967a2d 100644
--- a/docs/deployment/docker-development.mdx
+++ b/docs/deployment/docker-development.mdx
@@ -66,6 +66,32 @@ After starting the development environment, OpnForm will automatically redirect
The development setup is intentionally simplified compared to our [Docker Deployment](/deployment/docker) production setup, with a focus on developer experience and faster iteration.
+## Codex worktrees
+
+When you create an OpnForm worktree in Codex, Codex uses the repository environment in `.codex/environments` to prepare an isolated local stack automatically. This workflow does not use the shared development containers from `docker-compose.dev.yml`.
+
+The worktree receives its own PostgreSQL Docker volume, API port, and Nuxt port. Laravel and Nuxt run from the current checkout, so the browser always reflects that worktree's files.
+
+Use the Codex actions when available:
+
+- **Start app** starts the database, API, and Nuxt server.
+- **Reset DB** runs migrations and `Database\\Seeders\\E2ETestSeeder` only for the current worktree.
+- **Stop app** stops Laravel and Nuxt while preserving the local database for a fast restart.
+- **Run E2E** resets the worktree database and runs Playwright against its local URLs.
+
+The scripts are also available from the repository root:
+
+```bash
+./scripts/codex-worktree-setup.sh
+./scripts/codex-worktree-up.sh
+```
+
+The startup output contains the exact UI URL. Opening its root URL automatically signs in the local Codex admin (`[email protected]` / `Abcd@1234`). The reset seed creates three sample forms and five completed submissions across two public forms.
+
+<Warning>
+Do not run `docker compose -f docker-compose.dev.yml up` for concurrent Codex worktrees. That stack has shared container names and fixed host ports. Use the Codex worktree actions instead.
+</Warning>
+
### Key Simplifications
- **No .env Files**: All configuration embedded in docker-compose.dev.yml - no environment file generation needed
diff --git a/scripts/codex-worktree-destroy.sh b/scripts/codex-worktree-destroy.sh
new file mode 100755
index 000000000..90e77a86f
--- /dev/null
+++ b/scripts/codex-worktree-destroy.sh
@@ -0,0 +1,15 @@
+#!/bin/sh
+
+set -eu
+
+ROOT_DIR=$(cd -- "$(dirname "$0")/.." && pwd)
+. "$ROOT_DIR/scripts/codex-worktree-lib.sh"
+
+"$ROOT_DIR/scripts/codex-worktree-down.sh"
+
+if command -v docker >/dev/null 2>&1 && docker compose version >/dev/null 2>&1; then
+ codex_compose down --volumes --remove-orphans
+fi
+
+rm -rf "$CODEX_STATE_DIR"
+echo "Destroyed Codex worktree services and PostgreSQL volume."
diff --git a/scripts/codex-worktree-down.sh b/scripts/codex-worktree-down.sh
new file mode 100755
index 000000000..15cf2ec65
--- /dev/null
+++ b/scripts/codex-worktree-down.sh
@@ -0,0 +1,14 @@
+#!/bin/sh
+
+set -eu
+
+ROOT_DIR=$(cd -- "$(dirname "$0")/.." && pwd)
+. "$ROOT_DIR/scripts/codex-worktree-lib.sh"
+
+stop_screen_file "$CODEX_STATE_DIR/client.screen" "Codex Nuxt server" || true
+stop_pid_file "$CODEX_STATE_DIR/client.pid" "Codex Nuxt server"
+stop_checkout_server_on_port "$CODEX_APP_PORT" "Codex Nuxt server"
+
+stop_screen_file "$CODEX_STATE_DIR/api.screen" "Codex Laravel server" || true
+stop_pid_file "$CODEX_STATE_DIR/api.pid" "Codex Laravel server"
+stop_checkout_server_on_port "$CODEX_API_PORT" "Codex Laravel server"
diff --git a/scripts/codex-worktree-lib.sh b/scripts/codex-worktree-lib.sh
new file mode 100755
index 000000000..5d399f183
--- /dev/null
+++ b/scripts/codex-worktree-lib.sh
@@ -0,0 +1,436 @@
+#!/bin/sh
+
+set -eu
+
+ROOT_DIR=$(cd -- "$(dirname "$0")/.." && pwd)
+CODEX_STATE_DIR="${CODEX_WORKTREE_STATE_DIR:-$ROOT_DIR/.e2e/codex}"
+CODEX_API_ENV_FILE="$ROOT_DIR/api/.env.codex"
+CODEX_CLIENT_ENV_FILE="$ROOT_DIR/client/.env.codex"
+CODEX_ENV_FILE="$CODEX_STATE_DIR/env"
+
+CODEX_HASH=$(printf '%s' "$ROOT_DIR" | cksum | awk '{ print $1 % 5000 }')
+CODEX_COMPOSE_PROJECT="opnform-codex-$CODEX_HASH"
+CODEX_DB_NAME="${CODEX_DB_NAME:-opnform_codex_$CODEX_HASH}"
+CODEX_DB_USERNAME="${CODEX_DB_USERNAME:-opnform}"
+CODEX_DB_PASSWORD="${CODEX_DB_PASSWORD:-opnform}"
+CODEX_DB_HOST="${CODEX_DB_HOST:-127.0.0.1}"
+CODEX_API_HOST="${CODEX_API_HOST:-127.0.0.1}"
+CODEX_APP_HOST="${CODEX_APP_HOST:-127.0.0.1}"
+CODEX_DB_PORT="${CODEX_DB_PORT:-$((20000 + CODEX_HASH))}"
+CODEX_API_PORT="${CODEX_API_PORT:-$((26000 + CODEX_HASH))}"
+CODEX_APP_PORT="${CODEX_APP_PORT:-$((32000 + CODEX_HASH))}"
+CODEX_API_SCREEN="opnform-codex-api-$CODEX_HASH"
+CODEX_CLIENT_SCREEN="opnform-codex-client-$CODEX_HASH"
+CODEX_CLIENT_NODE_STAMP="$CODEX_STATE_DIR/client-node.version"
+
+CODEX_API_BASE_URL="http://$CODEX_API_HOST:$CODEX_API_PORT"
+CODEX_APP_URL="http://$CODEX_APP_HOST:$CODEX_APP_PORT"
+CODEX_API_HEALTH_URL="$CODEX_API_BASE_URL/content/feature-flags"
+CODEX_APP_HEALTH_URL="$CODEX_APP_URL/login"
+
+export CODEX_COMPOSE_PROJECT CODEX_DB_NAME CODEX_DB_USERNAME CODEX_DB_PASSWORD
+export CODEX_DB_HOST CODEX_DB_PORT CODEX_API_HOST CODEX_API_PORT CODEX_APP_HOST CODEX_APP_PORT
+export CODEX_API_SCREEN CODEX_CLIENT_SCREEN
+
+ensure_codex_state_dir() {
+ mkdir -p "$CODEX_STATE_DIR"
+}
+
+codex_compose() {
+ docker compose \
+ --project-name "$CODEX_COMPOSE_PROJECT" \
+ --file "$ROOT_DIR/docker-compose.codex.yml" \
+ "$@"
+}
+
+ensure_docker_compose() {
+ if ! command -v docker >/dev/null 2>&1 || ! docker compose version >/dev/null 2>&1; then
+ echo "Docker Compose v2 is required for the Codex worktree database." >&2
+ exit 1
+ fi
+
+ if ! docker info >/dev/null 2>&1; then
+ echo "Docker is installed but the daemon is not available." >&2
+ exit 1
+ fi
+}
+
+write_codex_env_files() {
+ ensure_codex_state_dir
+
+ cat >"$CODEX_API_ENV_FILE" <<EOF
+APP_NAME="OpnForm Codex"
+APP_ENV=codex
+APP_DEBUG=true
+APP_LOG_LEVEL=debug
+APP_URL=$CODEX_API_BASE_URL
+APP_KEY=base64:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+APP_DEV_CORS=true
+
+LOG_CHANNEL=stack
+LOG_LEVEL=debug
+
+FRONT_URL=$CODEX_APP_URL
+FRONT_API_SECRET=secret
+
+DB_CONNECTION=pgsql
+DB_HOST=$CODEX_DB_HOST
+DB_PORT=$CODEX_DB_PORT
+DB_DATABASE=$CODEX_DB_NAME
+DB_USERNAME=$CODEX_DB_USERNAME
+DB_PASSWORD=$CODEX_DB_PASSWORD
+
+FILESYSTEM_DRIVER=local
+FILESYSTEM_DISK=local
+
+BROADCAST_CONNECTION=log
+CACHE_DRIVER=file
+CACHE_STORE=file
+QUEUE_CONNECTION=sync
+SESSION_DRIVER=file
+SESSION_LIFETIME=120
+
+MAIL_MAILER=log
+MAIL_FROM_ADDRESS=dev@localhost
+MAIL_FROM_NAME="OpnForm Codex"
+
+JWT_TTL=10080
+JWT_REMEMBER_TTL=43200
+JWT_SECRET=38hjE96gYu4ceKSSHNnzgeynMr2m3WkNBN2u7zzpVeiITtxFEloxAjcr7TCKuiiy
+JWT_SKIP_IP_UA_VALIDATION=true
+
+SELF_HOSTED=false
+ZAPIER_ENABLED=false
+EOF
+
+ cat >"$CODEX_CLIENT_ENV_FILE" <<EOF
+NUXT_LOG_LEVEL=info
+NUXT_PUBLIC_APP_URL=$CODEX_APP_URL
+NUXT_PUBLIC_API_BASE=$CODEX_API_BASE_URL
+NUXT_PRIVATE_API_BASE=$CODEX_API_BASE_URL
+NUXT_API_SECRET=secret
+NUXT_PUBLIC_ENV=codex
+NUXT_PUBLIC_CODEX_AUTO_LOGIN=true
+NUXT_PUBLIC_CODEX_AUTO_LOGIN_PASSWORD=Abcd@1234
+EOF
+
+ cat >"$CODEX_ENV_FILE" <<EOF
+CODEX_STATE_DIR=$CODEX_STATE_DIR
+CODEX_COMPOSE_PROJECT=$CODEX_COMPOSE_PROJECT
+CODEX_DB_NAME=$CODEX_DB_NAME
+CODEX_DB_HOST=$CODEX_DB_HOST
+CODEX_DB_PORT=$CODEX_DB_PORT
+CODEX_API_HOST=$CODEX_API_HOST
+CODEX_API_PORT=$CODEX_API_PORT
+CODEX_APP_HOST=$CODEX_APP_HOST
+CODEX_APP_PORT=$CODEX_APP_PORT
+CODEX_API_BASE_URL=$CODEX_API_BASE_URL
+CODEX_APP_URL=$CODEX_APP_URL
+CODEX_API_HEALTH_URL=$CODEX_API_HEALTH_URL
+CODEX_APP_HEALTH_URL=$CODEX_APP_HEALTH_URL
+EOF
+}
+
+print_codex_environment_summary() {
+ if [ "${CODEX_ENV_SUMMARY_PRINTED:-0}" = "1" ]; then
+ return 0
+ fi
+
+ echo "Codex worktree isolation:"
+ echo " Checkout: $ROOT_DIR"
+ echo " PostgreSQL/API/UI ports: $CODEX_DB_PORT / $CODEX_API_PORT / $CODEX_APP_PORT"
+ echo " Compose project: $CODEX_COMPOSE_PROJECT"
+ echo " State directory: $CODEX_STATE_DIR"
+ echo " Sibling worktrees use different ports, database volumes, and API bases."
+
+ CODEX_ENV_SUMMARY_PRINTED=1
+ export CODEX_ENV_SUMMARY_PRINTED
+}
+
+ensure_php_dependencies() {
+ if [ ! -f "$ROOT_DIR/api/vendor/autoload.php" ]; then
+ (
+ cd "$ROOT_DIR/api"
+ composer install --no-interaction --prefer-dist
+ )
+ fi
+}
+
+remove_node_modules() {
+ target="$ROOT_DIR/client/node_modules"
+ attempt=0
+
+ while [ -e "$target" ] && [ "$attempt" -lt 5 ]; do
+ rm -rf "$target" >/dev/null 2>&1 || true
+ attempt=$((attempt + 1))
+
+ if [ -e "$target" ]; then
+ sleep 1
+ fi
+ done
+
+ if [ -e "$target" ]; then
+ echo "Could not remove stale client/node_modules after $attempt attempts." >&2
+ exit 1
+ fi
+}
+
+node_version_is_supported() {
+ version="$1"
+ major=${version%%.*}
+ remainder=${version#*.}
+ minor=${remainder%%.*}
+
+ case "$major" in
+ 20) [ "$minor" -ge 11 ] ;;
+ 22|24) return 0 ;;
+ *) return 1 ;;
+ esac
+}
+
+select_node_candidate() {
+ candidate="$1"
+
+ [ -n "$candidate" ] && [ -x "$candidate" ] || return 1
+
+ version=$("$candidate" -p 'process.versions.node' 2>/dev/null || true)
+ node_version_is_supported "$version" || return 1
+
+ node_dir=$(dirname "$candidate")
+ npm_candidate="$node_dir/npm"
+ [ -x "$npm_candidate" ] || return 1
+
+ case ":$PATH:" in
+ *":$node_dir:"*) ;;
+ *) PATH="$node_dir:$PATH" ;;
+ esac
+
+ npm_version=$("$npm_candidate" --version 2>/dev/null || true)
+ [ -n "$npm_version" ] || return 1
+
+ CODEX_NODE_BIN="$candidate"
+ CODEX_NPM_BIN="$npm_candidate"
+ CODEX_NODE_VERSION="$version"
+ export PATH CODEX_NODE_BIN CODEX_NPM_BIN CODEX_NODE_VERSION
+ return 0
+}
+
+select_node_runtime() {
+ if [ -n "${CODEX_NODE_BIN:-}" ]; then
+ if select_node_candidate "$CODEX_NODE_BIN"; then
+ return 0
+ fi
+
+ echo "CODEX_NODE_BIN must point to a supported Node 20.11+, 22.x, or 24.x runtime with npm." >&2
+ exit 1
+ fi
+
+ herd_node="$HOME/Library/Application Support/Herd/config/nvm/versions/node/v20.20.1/bin/node"
+ bundled_node="$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node"
+ path_node=$(command -v node 2>/dev/null || true)
+
+ for candidate in "$herd_node" "$bundled_node" "$path_node"; do
+ if select_node_candidate "$candidate"; then
+ return 0
+ fi
+ done
+
+ echo "A supported Node runtime (20.11+, 22.x, or 24.x) with its matching npm is required." >&2
+ exit 1
+}
+
+ensure_node_dependencies() {
+ select_node_runtime
+ node_version="v$CODEX_NODE_VERSION"
+
+ install_reason=""
+ if [ ! -d "$ROOT_DIR/client/node_modules" ]; then
+ install_reason="missing node_modules"
+ elif [ ! -x "$ROOT_DIR/client/node_modules/.bin/nuxt" ]; then
+ install_reason="Nuxt binary missing"
+ elif [ ! -f "$CODEX_CLIENT_NODE_STAMP" ]; then
+ install_reason="Node runtime stamp missing"
+ elif [ "$(cat "$CODEX_CLIENT_NODE_STAMP" 2>/dev/null || true)" != "$node_version" ]; then
+ install_reason="Node runtime changed"
+ fi
+
+ if [ -n "$install_reason" ]; then
+ echo "Installing client dependencies with Node $node_version and npm $("$CODEX_NPM_BIN" --version) ($install_reason)."
+ if [ -d "$ROOT_DIR/client/node_modules" ]; then
+ remove_node_modules
+ fi
+
+ (
+ cd "$ROOT_DIR/client"
+ "$CODEX_NPM_BIN" ci --no-audit --no-fund
+ )
+ fi
+
+ ensure_codex_state_dir
+ printf '%s\n' "$node_version" >"$CODEX_CLIENT_NODE_STAMP"
+}
+
+port_is_listening() {
+ port="$1"
+ lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1
+}
+
+wait_for_url() {
+ label="$1"
+ url="$2"
+ log_file="$3"
+ attempt=0
+
+ until curl -fsS "$url" >/dev/null 2>&1; do
+ attempt=$((attempt + 1))
+ if [ "$attempt" -ge 90 ]; then
+ echo "$label did not become ready in time: $url" >&2
+ if [ -f "$log_file" ]; then
+ tail -n 120 "$log_file" >&2 || true
+ fi
+ exit 1
+ fi
+ sleep 2
+ done
+}
+
+wait_for_database() {
+ attempt=0
+
+ until codex_compose exec -T db pg_isready -U "$CODEX_DB_USERNAME" -d "$CODEX_DB_NAME" >/dev/null 2>&1; do
+ attempt=$((attempt + 1))
+ if [ "$attempt" -ge 45 ]; then
+ echo "Codex PostgreSQL database did not become ready in time." >&2
+ codex_compose ps >&2 || true
+ codex_compose logs --tail=120 db >&2 || true
+ exit 1
+ fi
+ sleep 2
+ done
+}
+
+ensure_codex_database() {
+ ensure_docker_compose
+ codex_compose up -d db
+ wait_for_database
+}
+
+database_is_migrated() {
+ codex_compose exec -T db \
+ psql -U "$CODEX_DB_USERNAME" -d "$CODEX_DB_NAME" -tAc \
+ "SELECT to_regclass('public.migrations') IS NOT NULL" 2>/dev/null \
+ | tr -d '[:space:]' \
+ | grep -qx 't'
+}
+
+screen_session_is_running() {
+ file="$1"
+
+ if [ ! -f "$file" ] || ! command -v screen >/dev/null 2>&1; then
+ return 1
+ fi
+
+ screen_name=$(cat "$file" 2>/dev/null || true)
+ [ -n "$screen_name" ] && screen -ls | grep -q "\\.${screen_name}[[:space:]]"
+}
+
+pid_file_is_running() {
+ file="$1"
+
+ if [ ! -f "$file" ]; then
+ return 1
+ fi
+
+ pid=$(cat "$file" 2>/dev/null || true)
+ case "$pid" in
+ ''|*[!0-9]*) return 1 ;;
+ esac
+
+ kill -0 "$pid" >/dev/null 2>&1
+}
+
+managed_server_is_running() {
+ screen_session_is_running "$1.screen" || pid_file_is_running "$1.pid"
+}
+
+stop_pid_file() {
+ file="$1"
+ label="$2"
+
+ if [ ! -f "$file" ]; then
+ return 0
+ fi
+
+ pid=$(cat "$file" 2>/dev/null || true)
+ rm -f "$file"
+
+ case "$pid" in
+ ''|*[!0-9]*) return 0 ;;
+ esac
+
+ if ! kill -0 "$pid" >/dev/null 2>&1; then
+ return 0
+ fi
+
+ pkill -TERM -P "$pid" >/dev/null 2>&1 || true
+ kill "$pid" >/dev/null 2>&1 || true
+ sleep 1
+
+ if kill -0 "$pid" >/dev/null 2>&1; then
+ pkill -KILL -P "$pid" >/dev/null 2>&1 || true
+ kill -KILL "$pid" >/dev/null 2>&1 || true
+ fi
+
+ echo "Stopped $label."
+}
+
+stop_screen_file() {
+ file="$1"
+ label="$2"
+
+ if [ ! -f "$file" ]; then
+ return 1
+ fi
+
+ screen_name=$(cat "$file" 2>/dev/null || true)
+ rm -f "$file"
+
+ if [ -z "$screen_name" ] || ! command -v screen >/dev/null 2>&1; then
+ return 1
+ fi
+
+ screen -S "$screen_name" -X quit >/dev/null 2>&1 || true
+ echo "Stopped $label."
+ return 0
+}
+
+stop_checkout_server_on_port() {
+ port="$1"
+ label="$2"
+ pids=$(lsof -nP -t -iTCP:"$port" -sTCP:LISTEN 2>/dev/null || true)
+ stopped=0
+
+ for pid in $pids; do
+ command=$(ps -p "$pid" -o command= 2>/dev/null || true)
+ process_cwd=$(lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | sed -n 's/^n//p' | head -n 1 || true)
+ case "$command:$process_cwd" in
+ *"$ROOT_DIR"*)
+ kill -TERM "$pid" >/dev/null 2>&1 || true
+ stopped=1
+ ;;
+ *) ;;
+ esac
+ done
+
+ if [ "$stopped" = "1" ]; then
+ sleep 1
+ for pid in $pids; do
+ if kill -0 "$pid" >/dev/null 2>&1; then
+ kill -KILL "$pid" >/dev/null 2>&1 || true
+ fi
+ done
+ echo "Stopped orphaned $label process on port $port."
+ fi
+}
diff --git a/scripts/codex-worktree-reset-db.sh b/scripts/codex-worktree-reset-db.sh
new file mode 100755
index 000000000..801b26db5
--- /dev/null
+++ b/scripts/codex-worktree-reset-db.sh
@@ -0,0 +1,21 @@
+#!/bin/sh
+
+set -eu
+
+ROOT_DIR=$(cd -- "$(dirname "$0")/.." && pwd)
+. "$ROOT_DIR/scripts/codex-worktree-lib.sh"
+
+write_codex_env_files
+ensure_php_dependencies
+ensure_codex_database
+
+rm -rf "$ROOT_DIR/api/storage/framework/cache/data"/* "$ROOT_DIR/api/storage/framework/sessions"/*
+
+(
+ cd "$ROOT_DIR/api"
+ APP_ENV=codex php artisan optimize:clear --env=codex
+ APP_ENV=codex php artisan migrate:fresh --seed --seeder=Database\\Seeders\\E2ETestSeeder --force --env=codex
+)
+
+echo "Codex worktree PostgreSQL database reset:"
+echo " $CODEX_DB_NAME on $CODEX_DB_HOST:$CODEX_DB_PORT"
diff --git a/scripts/codex-worktree-setup.sh b/scripts/codex-worktree-setup.sh
new file mode 100755
index 000000000..b745c207c
--- /dev/null
+++ b/scripts/codex-worktree-setup.sh
@@ -0,0 +1,34 @@
+#!/bin/sh
+
+set -eu
+
+ROOT_DIR=$(cd -- "$(dirname "$0")/.." && pwd)
+. "$ROOT_DIR/scripts/codex-worktree-lib.sh"
+
+RESET_DB=0
+for arg in "$@"; do
+ case "$arg" in
+ --reset-db) RESET_DB=1 ;;
+ *)
+ echo "Unknown option: $arg" >&2
+ exit 1
+ ;;
+ esac
+done
+
+write_codex_env_files
+ensure_php_dependencies
+ensure_node_dependencies
+ensure_codex_database
+print_codex_environment_summary
+
+if [ "$RESET_DB" = "1" ] || ! database_is_migrated; then
+ "$ROOT_DIR/scripts/codex-worktree-reset-db.sh"
+else
+ echo "Reusing existing Codex worktree PostgreSQL database:"
+ echo " $CODEX_DB_NAME on $CODEX_DB_HOST:$CODEX_DB_PORT"
+fi
+
+echo "Codex worktree environment ready:"
+echo " API: $CODEX_API_BASE_URL"
+echo " UI: $CODEX_APP_URL"
diff --git a/scripts/codex-worktree-test-e2e.sh b/scripts/codex-worktree-test-e2e.sh
new file mode 100755
index 000000000..e043997d5
--- /dev/null
+++ b/scripts/codex-worktree-test-e2e.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+
+set -eu
+
+ROOT_DIR=$(cd -- "$(dirname "$0")/.." && pwd)
+. "$ROOT_DIR/scripts/codex-worktree-lib.sh"
+
+"$ROOT_DIR/scripts/codex-worktree-up.sh"
+"$ROOT_DIR/scripts/codex-worktree-reset-db.sh"
+select_node_runtime
+
+cd "$ROOT_DIR/client"
+PLAYWRIGHT_NO_WEB_SERVER=1 \
+PLAYWRIGHT_DEV_SERVER=1 \
+PLAYWRIGHT_BASE_URL="$CODEX_APP_URL" \
+PLAYWRIGHT_API_BASE_URL="$CODEX_API_BASE_URL" \
+"$CODEX_NPM_BIN" exec -- playwright test "$@"
diff --git a/scripts/codex-worktree-up.sh b/scripts/codex-worktree-up.sh
new file mode 100755
index 000000000..08b708c61
--- /dev/null
+++ b/scripts/codex-worktree-up.sh
@@ -0,0 +1,104 @@
+#!/bin/sh
+
+set -eu
+
+ROOT_DIR=$(cd -- "$(dirname "$0")/.." && pwd)
+. "$ROOT_DIR/scripts/codex-worktree-lib.sh"
+
+if [ ! -f "$CODEX_API_ENV_FILE" ] || [ ! -f "$CODEX_CLIENT_ENV_FILE" ]; then
+ "$ROOT_DIR/scripts/codex-worktree-setup.sh"
+ CODEX_ENV_SUMMARY_PRINTED=1
+ export CODEX_ENV_SUMMARY_PRINTED
+else
+ write_codex_env_files
+ ensure_php_dependencies
+ ensure_node_dependencies
+ ensure_codex_database
+ if ! database_is_migrated; then
+ "$ROOT_DIR/scripts/codex-worktree-reset-db.sh"
+ fi
+fi
+
+print_codex_environment_summary
+
+start_api() {
+ if curl -fsS "$CODEX_API_HEALTH_URL" >/dev/null 2>&1; then
+ if managed_server_is_running "$CODEX_STATE_DIR/api"; then
+ echo "Reusing Codex Laravel server on $CODEX_API_BASE_URL"
+ return 0
+ fi
+
+ echo "Port $CODEX_API_PORT responds to the OpnForm API but is not managed by this worktree." >&2
+ exit 1
+ fi
+
+ if managed_server_is_running "$CODEX_STATE_DIR/api"; then
+ wait_for_url "Codex Laravel server" "$CODEX_API_HEALTH_URL" "$CODEX_STATE_DIR/api.log"
+ echo "Reusing Codex Laravel server on $CODEX_API_BASE_URL"
+ return 0
+ fi
+
+ if port_is_listening "$CODEX_API_PORT"; then
+ echo "Port $CODEX_API_PORT is already in use, but the Codex Laravel API is not responding." >&2
+ exit 1
+ fi
+
+ if command -v screen >/dev/null 2>&1; then
+ rm -f "$CODEX_STATE_DIR/api.pid"
+ screen -dmS "$CODEX_API_SCREEN" sh -lc "cd '$ROOT_DIR/api' && echo \$\$ >'$CODEX_STATE_DIR/api.pid' && exec env RUNNER_TRACKING_ID= APP_ENV=codex php artisan serve --host='$CODEX_API_HOST' --port='$CODEX_API_PORT' --env=codex >'$CODEX_STATE_DIR/api.log' 2>&1"
+ echo "$CODEX_API_SCREEN" >"$CODEX_STATE_DIR/api.screen"
+ else
+ rm -f "$CODEX_STATE_DIR/api.screen"
+ (
+ cd "$ROOT_DIR/api"
+ exec nohup env RUNNER_TRACKING_ID= APP_ENV=codex php artisan serve --host="$CODEX_API_HOST" --port="$CODEX_API_PORT" --env=codex
+ ) >"$CODEX_STATE_DIR/api.log" 2>&1 &
+ echo "$!" >"$CODEX_STATE_DIR/api.pid"
+ fi
+
+ wait_for_url "Codex Laravel server" "$CODEX_API_HEALTH_URL" "$CODEX_STATE_DIR/api.log"
+ echo "Started Codex Laravel server on $CODEX_API_BASE_URL"
+}
+
+start_client() {
+ if curl -fsS "$CODEX_APP_HEALTH_URL" >/dev/null 2>&1; then
+ if managed_server_is_running "$CODEX_STATE_DIR/client"; then
+ echo "Reusing Codex Nuxt server on $CODEX_APP_URL"
+ return 0
+ fi
+
+ echo "Port $CODEX_APP_PORT responds to the OpnForm UI but is not managed by this worktree." >&2
+ exit 1
+ fi
+
+ if port_is_listening "$CODEX_APP_PORT"; then
+ echo "Port $CODEX_APP_PORT is already in use, but the Codex Nuxt UI is not responding." >&2
+ exit 1
+ fi
+
+ if command -v screen >/dev/null 2>&1; then
+ rm -f "$CODEX_STATE_DIR/client.pid"
+ screen -dmS "$CODEX_CLIENT_SCREEN" sh -c "cd '$ROOT_DIR/client' && set -a && . '$CODEX_CLIENT_ENV_FILE' && set +a && echo \$\$ >'$CODEX_STATE_DIR/client.pid' && exec env PATH='$PATH' RUNNER_TRACKING_ID= NUXT_HOST='$CODEX_APP_HOST' NUXT_PORT='$CODEX_APP_PORT' '$CODEX_NPM_BIN' run dev -- --host '$CODEX_APP_HOST' --port '$CODEX_APP_PORT' >'$CODEX_STATE_DIR/client.log' 2>&1"
+ echo "$CODEX_CLIENT_SCREEN" >"$CODEX_STATE_DIR/client.screen"
+ else
+ rm -f "$CODEX_STATE_DIR/client.screen"
+ (
+ cd "$ROOT_DIR/client"
+ set -a
+ # shellcheck source=/dev/null
+ . "$CODEX_CLIENT_ENV_FILE"
+ set +a
+ exec nohup env RUNNER_TRACKING_ID= NUXT_HOST="$CODEX_APP_HOST" NUXT_PORT="$CODEX_APP_PORT" "$CODEX_NPM_BIN" run dev -- --host "$CODEX_APP_HOST" --port "$CODEX_APP_PORT"
+ ) >"$CODEX_STATE_DIR/client.log" 2>&1 &
+ echo "$!" >"$CODEX_STATE_DIR/client.pid"
+ fi
+
+ wait_for_url "Codex Nuxt server" "$CODEX_APP_HEALTH_URL" "$CODEX_STATE_DIR/client.log"
+ echo "Started Codex Nuxt server on $CODEX_APP_URL"
+}
+
+start_api
+start_client
+
+echo "Codex worktree app is ready:"
+echo " $CODEX_APP_URL"