Krabiclaw

Multi-tenant platform SaaS. Nuxt 5 nightly + Nitro 3 + Cloudflare Workers + D1.

Package manager: yarn only. Never npm or pnpm.

Scripts

Production Canary Runs

Real-send production canaries are intentionally off on normal main deploys to avoid accidental email/WhatsApp spend on every merge. To run them on demand, use the GitHub Actions workflow Production Real-Send Canaries and choose whether to send:

• the auth OTP canary
• the notification email/WhatsApp canary

That workflow always runs production smoke first, then only sends the real canaries you explicitly selected for that run.

See docs/notification-testing.md for the full policy on log-only vs live email/WhatsApp testing, production-safe verification, and which public submission paths send for real in production.

Local Setup

1. Install

corepack yarn install

The repository uses Node.js 24.18.1. Use the exact version declared in .nvmrc before installing dependencies. When changing Node, follow the Node runtime upgrade runbook so local development, CI, type definitions, and Worker builds move together.

Yarn accepts new direct and transitive package releases only after seven days. Routine yarn add and yarn up commands apply this rule automatically. CI installs the package graph immutably and rechecks registry metadata in its hardened job.

For an urgent reviewed security fix, update only the affected package:

corepack yarn up <package>@<fixed-version> --no-time-gate

Record the advisory and the reason for bypassing the wait in the pull request. Do not add a package to npmPreapprovedPackages or disable the age gate in .yarnrc.yml.

2. Environment

Copy .env.example to .env and fill in the application secrets there. This is the single local configuration for Nuxt, Wrangler, setup scripts, and E2E tests. See local development for setup and migrating an older .dev.vars file. No second secret file or symlink is needed.

3. Prepare local development

corepack yarn local:setup

The command is safe to repeat. It leaves local D1 at the current migration, fixture, credential, and foreign-key baseline, then prints the one local developer login:

URL: http://localhost:3000/login?email=developer%40playwright.example
Email: developer@playwright.example
Password: <fresh value generated by local:setup>

This localhost-only account is a member of every curated tenant and can access the platform dashboard. The password is generated on each setup run, printed once, and stored only as a hash in local D1. A repeated setup deletes existing local sessions, so sign in again with the newly printed password afterward.

4. Run

corepack yarn dev

App at http://localhost:3000.

yarn dev is the normal application-development loop. Nitro reads the bindings declared in wrangler.toml, emulates local D1/KV/R2 resources, and preserves Nuxt hot module replacement. It never resets D1. Run corepack yarn local:setup when you want to restore local D1 from a production snapshot.

Open tenant dashboards from the dashboard UI instead of guessing their URLs. When a route must be constructed manually, the dashboard segment is the organization's slug, not its subdomain, and everything else sits directly under it: Kikuzuki's locations are /dashboard/org-bVY8SxxUuG6Ctk2CQnfCk8T2cPsj4jJX/locations.

For production-runtime browser verification, use the generated Worker locally. Wrangler reads the same .env as Nuxt. Playwright also loads it and supplies test-specific local URLs and delivery settings to the Worker.

yarn test:e2e:local tests/e2e/tenant-rendering.spec.ts

For a production-like local Worker:

yarn dev:worker

After a successful build, yarn dev:worker:start restarts that same .output without rebuilding. Source edits are not compiled into .output automatically; use yarn dev for the normal HMR editing loop.

Playwright applies the local D1 schema, clears disposable E2E artifacts, restores a production snapshot, provisions verified synthetic Better Auth accounts, builds the Cloudflare Worker, and starts it under local workerd. Authenticated tests sign in through Better Auth with a random password generated inside the Playwright process; no email inbox or authentication bypass route is involved. Those test credentials are not a second manual login path. Use the local developer account printed by corepack yarn local:setup for browser work.

Local tenant tests use a shared-host routing contract: the browser targets localhost and the test helper supplies x-preview-tenant for the selected fixture. Deployed staging uses direct first-level tenant aliases instead. This is the authoritative local browser path; do not rely on direct *.localhost navigation for Worker browser verification.

http://localhost:3000/                  (x-preview-tenant: ncls)
http://localhost:3000/services          (x-preview-tenant: ncls)
http://localhost:3000/experiences       (x-preview-tenant: pottery-house)
http://localhost:3000/reservations      (x-preview-tenant: kikuzuki-krabi-thailand)

macOS file limit fix

ulimit -n 65536

Deployment

Deployment follows the branches in .github/workflows/ci.yml:

1. Pull requests run Checks and the E2E suite against a local Worker and a local D1 copied from production (db:pull:local). Nothing is deployed for a pull request.
2. Pushes to staging run Checks, then deploy the staging Worker, apply staging migrations, and run read-only MCP and tenant rendering against staging itself. Nothing writes test data into real staging.
3. Pushes to main run Checks, then deploy the production Worker, apply production migrations, and run read-only production browser verification.

CI invokes native Wrangler commands only in the matching branch job.

During an incident, use Cloudflare's deployment history to restore the last known-good production deployment without changing D1 data. Then land the source fix through staging and main and repeat the browser gates.

Production secrets live in the Cloudflare dashboard → Workers & Pages → krabiclaw → Settings → Variables.

Set protected internal job secrets with Wrangler:

openssl rand -base64 32
yarn wrangler secret put CRON_SECRET

CRON_SECRET protects internal scheduled endpoints. Local commands read their configuration from .env; deployed Workers use Cloudflare secrets and the variables in wrangler.toml.

MCP reconnect triage and Cloudflare auth debugging are documented in docs/observability.md.

The mandatory deployed-browser release gate and outage recovery rules are documented in docs/operations/release-and-outage-prevention.md.

Schema

server/db/schema.ts is the only schema source of truth; migrations/ holds generated output. Hand-written migrations are prohibited.

Stripe (local)

yarn stripe:listen

Copy the whsec_... signing secret it outputs into .env as STRIPE_WEBHOOK_SECRET. Swap back to the production webhook secret before deploying.

Native marketplace onboarding uses a separate Accounts v2 thin-event destination and signing secret. See Stripe Connect onboarding.