diff --git a/ai/backend-context.md b/ai/backend-context.md index 088ed62..8ab6a97 100644 --- a/ai/backend-context.md +++ b/ai/backend-context.md @@ -92,7 +92,8 @@ pattern. - Rebuild the development database with: ```sh - php artisan migrate:fresh --seed + direnv exec "$(git rev-parse --show-toplevel)" \ + php artisan migrate:fresh --seed ``` - Once a production database exists, replace this policy with additive, @@ -101,7 +102,12 @@ pattern. ## Before completing backend work - Run the focused test during development. -- Run `php artisan test` before completion. +- Run the full test suite before completion: + + ```sh + direnv exec "$(git rev-parse --show-toplevel)" php artisan test + ``` + - Run the Composer static-analysis scripts. - Fix failures caused by the change. Report unrelated baseline failures precisely rather than hiding them or expanding scope without authorization. diff --git a/ai/frontend-context.md b/ai/frontend-context.md index af25c82..3462801 100644 --- a/ai/frontend-context.md +++ b/ai/frontend-context.md @@ -33,13 +33,14 @@ Use npm and keep `package-lock.json` committed. Run commands from Install dependencies in a fresh checkout or worktree: ```sh -npm install +direnv exec "$(git rev-parse --show-toplevel)" npm install ``` Start the development server on the port assigned by the shell hook: ```sh -npm run dev -- --port "$VITE_PORT" +direnv exec "$(git rev-parse --show-toplevel)" \ + npm run dev -- --port "$VITE_PORT" ``` `process-compose` does not start or proxy the frontend. @@ -47,10 +48,10 @@ npm run dev -- --port "$VITE_PORT" The available validation commands are: ```sh -npm run format -npm run lint -npm run type-check -npm run build +direnv exec "$(git rev-parse --show-toplevel)" npm run format +direnv exec "$(git rev-parse --show-toplevel)" npm run lint +direnv exec "$(git rev-parse --show-toplevel)" npm run type-check +direnv exec "$(git rev-parse --show-toplevel)" npm run build ``` `npm run format` and `npm run lint` rewrite files. Review the resulting diff. diff --git a/ai/shared.md b/ai/shared.md index 2f792aa..9c921c2 100644 --- a/ai/shared.md +++ b/ai/shared.md @@ -45,28 +45,43 @@ those changes with the most relevant parser, formatter, dry run, or check. is the user's stack. Do not start, restart, or stop it unless the user asks. - A worktree owns its own isolated stack. The flake shell hook assigns a deterministic port offset and creates worktree-local PostgreSQL state. -- Start a worktree stack from its root with `process-compose up`. For - non-interactive use, run `process-compose up -D` and stop it with - `process-compose down`. +- Start a worktree stack from its root. For non-interactive use, start it + detached and stop it when finished, as shown below. - Do not use `process-compose -t=false` for a detached stack. It can leave an orphaned PostgreSQL process holding the data directory. -- Non-interactive agent shells do not automatically load direnv. A bare - `process-compose`, `php artisan`, or database command from a worktree can - silently use default ports and target the main checkout. -- Prefix worktree stack and database commands with `direnv exec `. - Examples: +- Non-interactive agent shells do not automatically load direnv. Bare project + commands can use missing tools, default ports, or paths from the main + checkout. +- Run project tooling that depends on the repository development environment + through direnv. This includes PHP, Composer, Artisan, npm, tests, builds, + database clients, and services. +- Resolve the direnv target from the worktree containing the agent's current + working directory. Never target the main checkout or a different worktree: ```sh - direnv exec process-compose up -D - direnv exec process-compose down - direnv exec php artisan migrate:fresh --seed + direnv exec "$(git rev-parse --show-toplevel)" + ``` + +- Git and environment-neutral read-only file inspection do not need the + direnv wrapper. +- Worktree stack examples: + + ```sh + direnv exec "$(git rev-parse --show-toplevel)" process-compose up -D + direnv exec "$(git rev-parse --show-toplevel)" process-compose down ``` - Run backend commands from `backend/`, or explicitly change into it in the - command. + command. The direnv target remains the worktree root. - Run frontend commands from `frontend/website/`. - `process-compose` does not start the frontend. Start it separately with - `npm run dev -- --port "$VITE_PORT"` when needed. + the worktree's assigned port when needed: + + ```sh + direnv exec "$(git rev-parse --show-toplevel)" \ + npm run dev -- --port "$VITE_PORT" + ``` + - When a normally valid check fails because a required service is down, surface the environmental failure. Do not skip the check or silently switch to a different database or service. @@ -143,8 +158,11 @@ those changes with the most relevant parser, formatter, dry run, or check. another checkout. Dependency paths and generated files must remain worktree-local. - The shell hook installs backend dependencies but does not install frontend - dependencies. Run `npm install` from `frontend/website/` when provisioning a - fresh worktree. + dependencies. From `frontend/website/`, provision them with: + + ```sh + direnv exec "$(git rev-parse --show-toplevel)" npm install + ``` Do not push anything. Make commits as the TDD workflow requires. @@ -155,12 +173,17 @@ gate affected by the change. ### Backend -- Run tests from `backend/` with `php artisan test`. +- Run tests from `backend/`: + + ```sh + direnv exec "$(git rev-parse --show-toplevel)" php artisan test + ``` + - Run the Composer checks defined by `backend/composer.json`: ```sh - composer types:check - composer test + direnv exec "$(git rev-parse --show-toplevel)" composer types:check + direnv exec "$(git rev-parse --show-toplevel)" composer test ``` - Do not claim a green gate when a command fails. If the failure predates the @@ -171,10 +194,10 @@ gate affected by the change. - Run these commands from `frontend/website/`: ```sh - npm run format - npm run lint - npm run type-check - npm run build + direnv exec "$(git rev-parse --show-toplevel)" npm run format + direnv exec "$(git rev-parse --show-toplevel)" npm run lint + direnv exec "$(git rev-parse --show-toplevel)" npm run type-check + direnv exec "$(git rev-parse --show-toplevel)" npm run build ``` - The formatter and linters rewrite files. Review their changes before @@ -184,8 +207,20 @@ gate affected by the change. ### Environment and integration -- For Nix or shell-hook changes, run `nix fmt` and `nix flake check`. -- For service configuration changes, run `process-compose --dry-run`. +- For Nix or shell-hook changes, run: + + ```sh + direnv exec "$(git rev-parse --show-toplevel)" nix fmt + direnv exec "$(git rev-parse --show-toplevel)" nix flake check + ``` + +- For service configuration changes, run: + + ```sh + direnv exec "$(git rev-parse --show-toplevel)" \ + process-compose --dry-run + ``` + - When a change affects runtime wiring, start the worktree's stack and verify the relevant endpoint or service against that worktree. - If you started the stack only for validation, stop it before finishing.