# Testing and releases

## Local setup

Use Node.js 22.16+ and pnpm 10.11.0. The monorepo has one lockfile and uses Turborepo. Install with `corepack pnpm install --frozen-lockfile`.

```sh
pnpm check
pnpm build
pnpm typecheck
pnpm test
pnpm test:e2e
```

Builds bundle Workers without publishing. API tests use Node/forks with mocked Cloudflare bindings and local SQLite. Tests enforce D1's 50-byte LIKE/GLOB pattern limit where relevant. Browser tests run the real dashboard/admin/docs and API against a local database; payment, email, storage and external services are isolated. They must never use production credentials or production data.

## Deployment gate

The GitHub workflow runs repository validation, builds, type checks, unit/integration tests and browser E2E tests. Deployment depends on successful validation of the same commit. Failed validation does not start deployment. Pull requests validate but do not deploy.

Native Git automatic deployments must be disabled for targets managed by this gate, to avoid parallel deployment outside the workflow. Pages project identities, domains and resource bindings are retained. Repository deployment entry points reject native CI publishing and require the validation commit receipt in GitHub Actions.

GitHub requires a scoped `CLOUDFLARE_API_TOKEN` secret and the correct account ID. Configure these through GitHub repository/environment settings; never commit credentials. A runtime token available to a development session is not automatically a GitHub Actions secret.

`dev` releases only XYZ. `main` releases only AI. Release production by explicitly merging tested dev changes into main. Do not push development changes to main without authorization.

## Schema upgrades

Account workspace limits and account integrations require release migrations 0006 and 0007. They add per-user limits, replace the static ownership triggers, add integration sources and allow account-level grants/audit events. Existing workspace-only grants are revoked because account access needs new consent. Users must reconnect.

Historical migrations 0001–0005 describe earlier manual cutovers and must not be replayed blindly. Release automation uses the separate release migrations directory/table, so historical credit cutovers cannot be reapplied accidentally. A newly initialized database using the current complete schema must baseline the release migration history instead of replaying ALTER TABLE steps.

Back up the target database before release. Test upgrades on disposable databases with foreign keys enabled. No schema deployment should drop product data or reset wallets.

## Documentation sites

The docs workspace builds static HTML, Markdown, search data, `/llms.txt`, `/llms-full.txt` and schemas generated from the API operation registry. Development docs are noindex. Production docs use canonical AI URLs. Both environments have separate Pages targets and custom domains.

## Coverage boundaries

Local E2E tests cover integration between applications and the API without using live Google, Stripe, SES, Cloudflare DNS or external agent clients. Provider-specific sign-in, payment settlement and actual Cloudflare provisioning still require environment smoke checks with authorized test accounts. Do not describe local tests as proof that an external provider is healthy.