Prepare an isolated development environment
Local development uses a repository-owned Supabase stack and synthetic fixtures. Shared functional checks use the separately declared application environment. Preparing one does not require resetting, seeding or borrowing credentials from the other.
The current repository pins Supabase CLI 2.116.0; use its Make targets rather than an unrelated globally installed CLI. Use Node.js 24, Python 3.11 or later and Docker as declared in the development guide. CI’s Python image is a separate declared execution input.
Prerequisites
Section titled “Prerequisites”Read the repository working agreement, current status, architecture and development guide. Check open PRs and git worktree list; reuse the worktree for this task. New worktrees belong under ~/worktrees/, with one writer. Do not continue a merged branch.
Each worktree owns its dependencies. Do not symlink node_modules from another checkout. Create the backend virtual environment using the development guide and install its runtime/development requirements. For frontend dependencies use the documented npm ci --legacy-peer-deps. The handbook has a separate dependency root and uses npm ci under docs/system.
Preparation procedure
Section titled “Preparation procedure”- Select the intended branch and inspect changes before installing or starting anything. Record which local services and ports are already in use.
- Install worktree dependencies with the documented versions. Keep runtime credentials out of the checkout. Before hermetic backend tests, check that runtime dotenv files and symlinks are absent and clear provider inputs. Preserve the committed synthetic frontend test configuration.
- Run
make startfrom the repository root. The repository CLI applies its migrations to its own local stack. Usemake statuslocally to obtain that stack’s settings; it can print local keys, so do not paste its output into evidence. - If the task needs a fresh synthetic dataset, run
make dev-data. This performs reset and seed; it destroys local data. It is not required just to build documentation and must never target the shared environment or a restored customer dataset. - Start the API and frontend using the daily commands. The documented API port is
8110; frontend Vite uses3000with a strict port. Use a deliberateTOOLORA_DEV_PORToverride and matching CORS/preflight settings if necessary. Keep local Auth origins consistently on127.0.0.1. - Run
make preflightand the focused checks for the changed surface. If schema changes exist, create a forward migration withmake migration, then regenerate types withmake types.
Expected result and target boundary
Section titled “Expected result and target boundary”| Observation | Expected result | Does not establish |
|---|---|---|
| Local stack startup | Repository migrations apply to the owned local project | Shared schema parity or recovered data |
| Synthetic seed | Reproducible fixture companies and actors | Completeness of historical imports |
| Preflight | Declared dependencies, ports and service prerequisites are usable | A successful business journey |
| Hermetic backend suite | Synthetic/local inputs without runtime secret loading | Provider acceptance |
| Documentation build | Local HTML, search and assets | Application publication |
Failure handling
Section titled “Failure handling”A busy strict frontend port is a failure to resolve, not permission to let Vite silently choose another port. A dotenv symlink is still runtime configuration and must not be followed by a hermetic suite. Missing Docker health or a migration mismatch requires diagnosis before resetting anything.
Database seed, reset and automated checks obtain their target from the stack’s status, not an ambient database URL. Upgrade rehearsal refuses unrelated host/port/database values. Do not broaden that routing interface to make a test easier to invoke.
Verification and shared checks
Section titled “Verification and shared checks”For a synthetic project edit, verify the intended actor, company and saved result through the actual changed path. A successful preflight only makes that check possible. Test levels explains the evidence boundaries.
Shared browser checks follow the saved-session procedure and persistent Vi Målar identities only when the changed flow requires them. Environment constraints include real Fortnox effects: never test final attest/export/send or an approval that queues payroll in Vi Målar. Configuration identities and schema release describe the separate authorized runtime procedures.