Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 34 additions & 18 deletions .agents/docs/architecture/testing-strategy.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ What is tested where, and what CI blocks a merge on. Writing an e2e test is
| ---------- | ---------- | --------------------------------------------------------------------- | -------------------- |
| Unit | vitest | `__tests__/<file>.test.ts` beside `<file>.ts`, or a package's `test/` | `pnpm test:coverage` |
| End-to-end | Playwright | `testing/src/specs/` | `pnpm test:e2e` |
| Type-check | `tsc` | code that fails to compile if the type breaks, e.g. `*.test-d.ts` | `pnpm lint` |
| Type-check | oxlint | code that fails to compile if the type breaks, e.g. `*.test-d.ts` | `pnpm lint` |

**There is no integration tier.** `apps/api` unit tests mock the Prisma layer entirely, so Playwright
is the only code path that touches a real database: a permissions or row-scoping change is untested
Expand Down Expand Up @@ -92,24 +92,38 @@ outside the project globs by design.

## `pnpm lint` is the type-check, and it edits files

Per-package `lint` is `tsc && oxlint --fix src`; there is no separate `typecheck` script, so a type
error surfaces as a lint failure and every run may rewrite the working tree. Exceptions:
Root `lint:root` is `oxlint --type-check --fix`: one process lints every file in the repo and reports
TypeScript's diagnostics for it, each file under its nearest `tsconfig.json`. No workspace has a `lint`
script except `apps/outreach`, and there is no separate `typecheck` script, so a type error surfaces as
a lint failure and every run may rewrite the working tree. To check part of the repo, pass a path:
`pnpm exec oxlint --type-check apps/web`. What that pass does not cover:

| Package | `lint` |
| ------------------------------------------------------------- | ------------------------------------------ |
| `apps/outreach` | `astro check && oxlint --fix src` |
| `packages/runtime-core` | `tsc --noEmit && oxlint --fix src` |
| `packages/instrument-stubs`, `packages/instrument-guidelines` | oxlint only — **no `tsc`** |
| `testing` | `pnpm gen:routes && tsc && oxlint --fix .` |
| `runtime/v1` | **none**, so never type-checked |
| Files | Checked by |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `.astro` templates | `apps/outreach`'s `lint`, which is `astro check` |
| `vendor/**`, `packages/runtime-bundler/test/fixtures/**` | nothing: `ignorePatterns` in `oxlint.config.ts` |
| `packages/instrument-stubs`, `packages/instrument-guidelines/bin` | linted, but neither has a `tsconfig.json`, so the repo's strict options do not apply |

## Turbo task graph

`lint`, `dev`, `dev:test` and `test:e2e` depend on `["^build", "^db:generate", "db:push"]`; `build`
on `["^build", "db:generate"]`. `test:e2e` is `cache: false`. **`test` is not a turbo task**: root
`pnpm test` is `env-cmd vitest`, with no build and no database. `globalDependencies` (`.env`,
`oxfmt.config.ts`, `oxlint.config.ts`, `packages/oxlint-config/src/**`, `tsconfig.json`) invalidate
every cached task when touched.
`pnpm lint` is `turbo run lint lint:root`. `//#lint:root` depends on `//#generated`, a task with no
script that names what a tool run over the whole repo reads and source control does not hold: both
Prisma clients, `testing`'s route types, and `instrument-library`'s build, which reaches `runtime-v1`
and `runtime-core` through `^build`. `test:e2e` depends on the same task, the gateway's `db:push`, and
`^build`, which builds the `playground-url` CLI that `testing/src/specs/playground.spec.ts` runs.
`dev` and `dev:test` depend on `["^build", "db:generate"]`, to which `apps/gateway/turbo.json` adds
`db:push`; `build` depends on `["^build", "db:generate"]` and `start` on `build`. `dev`, `dev:test`,
`start`, `test:e2e` and `db:push` are `cache: false`. A workspace whose task differs from the root
definition says so in its own `turbo.json` (`git ls-files '*turbo.json'` lists them).

**`test` is not a turbo task**: root `pnpm test` runs `pnpm build:exports`, which builds the packages
that export only build output, and then `env-cmd vitest`, with no database.

**A task sees a variable only through `env`.** `.env` is not a `globalDependency`, so editing it
invalidates nothing; `pnpm build` loads it with `env-cmd` and turbo passes on the keys a task declares.
Root `tsconfig.json` is the one `globalDependency`, and turbo adds `packages/oxlint-config` to every
task's hash because the root `package.json` depends on it. `build` hashes neither `*.md` nor
`__tests__/`, so editing an `AGENTS.md` or a unit test rebuilds nothing downstream.

## Coverage scope

Expand All @@ -124,7 +138,9 @@ counts their functions twice in the merged report.
`.github/workflows/ci.yaml`, one job, on `pull_request` to `main` or a `release/**` branch and
`workflow_dispatch` only — a push alone runs nothing. In order: `./scripts/generate-env.sh`, `pnpm install --frozen-lockfile`,
`pnpm lint`, `pnpm test:coverage`, Playwright install (chromium + firefox, capped at 10 minutes, after
lint and unit tests so a hung download cannot hide them), `pnpm test:e2e`.
lint and unit tests so a hung download cannot hide them), `pnpm test:e2e`. `actions/cache` restores
`.turbo/cache` before the first of them: a pull request reads the caches its own earlier runs saved
and the one the Release workflow's `validate` job last saved on its base branch.

Not gated: knip (`pnpm knip` exists), and formatting — oxfmt runs only in the `.husky/pre-commit`
hook, which formats rather than verifies.
Expand All @@ -147,5 +163,5 @@ Flag these rather than fixing them in passing; each is load-bearing somewhere.

- `turbo.json` declares `db:generate` `outputs: ["node_modules/@prisma/generated-client/**"]`, which
matches only `apps/gateway`'s schema; `apps/api/prisma/schema.prisma` has its `output` commented
out, so `@opendatacapture/api#db:generate` is `cache: false` to stop a cache hit restoring nothing.
Changing either half changes what `db:generate` produces.
out, so `apps/api/turbo.json` sets its `db:generate` to `cache: false` to stop a cache hit restoring
nothing. Changing either half changes what `db:generate` produces.
2 changes: 1 addition & 1 deletion .agents/docs/playbooks/add-e2e-test.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ starting — `playwright.config.ts` boots api, gateway, web and playground itsel
## Verify

```sh
pnpm --filter @opendatacapture/testing lint # gen:routes, tsc, oxlint .
pnpm lint # gen:routes, then the whole-repo type-check and lint
pnpm --filter @opendatacapture/testing test:e2e --list src/specs/<flow>.spec.ts # your titles, under [chromium]
pnpm --filter @opendatacapture/testing test:e2e src/specs/<flow>.spec.ts # one spec; setup still runs
pnpm test:e2e # whole suite, from repo root
Expand Down
5 changes: 3 additions & 2 deletions .agents/docs/playbooks/add-env-var.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,8 @@
6. **If the gateway reads it, add it to `apps/gateway/src/config.ts`.** That is a separate Zod schema
parsing `process.env` at import time; `$Env` never reaches the gateway.

7. **If a build reads it, add it to that task's `env` array in `turbo.json`.** Turbo runs in strict
7. **If a build reads it, add it to the `env` array of that workspace's `build` task, in its own
`turbo.json`** (`apps/web/turbo.json` is the shape). Turbo runs in strict
env mode: a task sees only `globalEnv` plus its own `env`, so the variable is `undefined` during
`pnpm build` even though `env-cmd` loaded `.env` before turbo started. `dev`/`start`/`test` scripts
load `.env` themselves (`env-cmd -f ../../.env`), so only build-time reads need this.
Expand All @@ -63,7 +64,7 @@
```sh
grep -n YOUR_KEY .env # present
pnpm dev # $Env is validated at boot; an invalid value crashes here. Ctrl-C once up
pnpm lint # tsc + the no-process.env rule
pnpm lint # the type-check + the no-process.env rule
pnpm test:coverage
pnpm build # only this catches a missing turbo.json `env` entry
```
3 changes: 1 addition & 2 deletions .agents/docs/playbooks/add-instrument.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,5 +65,4 @@ pnpm test:e2e
```

`available` listing your title under the right kind proves only that it built; it reaches a demo
instance only through step 4. `pnpm lint` (`tsc`) needs `runtime/v1/dist`, which is why the build
comes first.
instance only through step 4.
5 changes: 1 addition & 4 deletions .agents/docs/playbooks/add-vitest-project.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,9 +75,6 @@ project, so its test files are collected by nothing and CI stays green. The loud
```sh
pnpm exec vitest list --filesOnly --project <name> # your file, prefixed [<name>], nothing from outside
pnpm exec vitest --project <name>
pnpm lint # from the root; tsc now checks vitest.config.ts
pnpm lint # now type-checks vitest.config.ts
pnpm test # the repo-wide file count rises by yours
```

Run `pnpm lint` from the root: a package-scoped `lint` skips turbo's `^build` ordering and fails on
unbuilt dependencies rather than on your config.
4 changes: 2 additions & 2 deletions .agents/docs/playbooks/add-web-route.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ run the generator.
Until then `pnpm lint` fails in two workspaces: TS2345 in `apps/web`, and in `testing`, whose
`gen:routes` derives the `RouteTo` union from that tree, so your literal is not yet a valid
`pageModels` key. `gen:routes` reads `route-tree.ts` and never writes it, so it is yours to run
(`pnpm --filter @opendatacapture/testing gen:routes`); `testing`'s `lint` and `test:e2e` also run
(`pnpm --filter @opendatacapture/testing gen:routes`); `pnpm lint` and `testing`'s `test:e2e` also run
it first.

10. **Add the tests.** A unit test named after the route file, in a `__tests__/` folder beside it
Expand All @@ -66,7 +66,7 @@ run the generator.
## Verify

```sh
pnpm --filter @opendatacapture/web lint # TS2345 on your literal alone means the tree is not regenerated yet
pnpm lint # TS2345 on your literal alone means the tree is not regenerated yet
pnpm exec vitest --project web
pnpm test:e2e
```
Expand Down
3 changes: 1 addition & 2 deletions .agents/docs/playbooks/cut-a-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,7 @@ them. Never hand-edit a version field.

1. **Get the branch green before you bump.** Nothing after the PR runs a test against this code: the
release's `validate` job runs `pnpm lint` only. Run `pnpm check`
(`.agents/skills/finishing-changes/SKILL.md`); root `pnpm test` has no turbo `^build` behind it, so
run `pnpm build` once first. `pnpm lint` rewrites files, so commit any churn on its own before the
(`.agents/skills/finishing-changes/SKILL.md`). `pnpm lint` rewrites files, so commit any churn on its own before the
bump. Also confirm
`gh run list --workflow=Release --limit 1` is green on `main`: nothing local builds the Docker
images, and `build` gates both publishes.
Expand Down
5 changes: 1 addition & 4 deletions .agents/docs/playbooks/promote-to-react-core.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,10 +64,7 @@ done; `apps/web`'s until step 9.
## Verify

```sh
pnpm --filter @opendatacapture/react-core lint # an unresolved `@/…` here means step 6 is unfinished
pnpm --filter @opendatacapture/web lint
pnpm --filter @opendatacapture/gateway lint # meaningful only once step 9 wired the consumer
pnpm lint && pnpm test:coverage
pnpm lint && pnpm test:coverage # an unresolved `@/…` in packages/react-core means step 6 is unfinished
pnpm test:e2e
pnpm --filter @opendatacapture/storybook storybook # listed under React Core; prerequisites in storybook/AGENTS.md
```
Expand Down
12 changes: 6 additions & 6 deletions .agents/docs/playbooks/run-locally.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,18 +53,18 @@ one.
6. **`pnpm install`.** It also installs the husky pre-commit hook, which formats staged files with
oxfmt and runs neither lint nor tests.

7. **Run `pnpm build` once.** `runtime/v1/dist` is gitignored and read while Vite configs load, so a
7. **Run `pnpm build:exports` once.** It builds the packages that export only build output. `runtime/v1/dist` is gitignored and read while Vite configs load, so a
dev server started without it dies with
`ENOENT: no such file or directory, scandir '<repo>/runtime/v1/dist'` from `generateManifest`
(`packages/runtime-meta`), raised inside a plugin factory so it looks like a Vite configuration
error. Turbo's `dev`, `dev:test`, `lint` and `test:e2e` depend on `^build` and repair it; storybook,
outreach, root `pnpm test` and any bare `tsc` or `vitest` do not.
error. Root `pnpm dev`, `pnpm lint`, `pnpm test` and `pnpm test:e2e` build it first and so repair it;
storybook, outreach and any bare `tsc`, `oxlint` or `vitest` do not.

Done when `runtime/v1/dist` exists.

8. **`pnpm dev`** starts api, gateway and web only (`dev:core`); the gateway's sqlite `db:push` runs as
a dependency. The first run, and the first after any `.env` edit (`.env` is a turbo
`globalDependency`), spends minutes building before anything listens.
a dependency. A first run that skipped step 7 builds before anything listens; an `.env` edit rebuilds
nothing.

| App | Variable | Default |
| ------- | ------------------------- | ------- |
Expand All @@ -90,7 +90,7 @@ one.

## The apps `pnpm dev` does not start

Turbo hashes `.env` but never loads it, and `astro dev` does not read it either, hence the `env-cmd`
Turbo never loads `.env`, and `astro dev` does not read it either, hence the `env-cmd`
prefix.

| App | Command | Port |
Expand Down
6 changes: 3 additions & 3 deletions .agents/docs/workspace-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,9 @@ and a change is visible immediately. The exceptions:
- **`playground-url` and `serve-instrument`** build only their `bin`. `playground-url`'s library
export is still source. `serve-instrument` has no `exports` at all.

Turbo's `build`, `lint`, `dev` and `test:e2e` tasks depend on `^build`, so `pnpm build` and
`pnpm lint` from the root are always correct. Running `tsc` inside one package after a clean
checkout is not, and `pnpm test` builds nothing.
Root `pnpm build`, `pnpm lint`, `pnpm dev`, `pnpm test` and `pnpm test:e2e` build these first
(`.agents/docs/architecture/testing-strategy.md` §Turbo task graph), so they are always correct. A
bare `tsc`, `oxlint --type-check` or `vitest` after a clean checkout is not.

## Published to npm

Expand Down
12 changes: 6 additions & 6 deletions .agents/skills/finishing-changes/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@ with `.agents/skills/opening-issues/SKILL.md` and name the issue in your reply.
**A diff confined to these rows runs the row's checks in place of step 1**, then continues from step 7 (step 3
for unit tests). A diff spanning rows runs each row's checks; any other file means the full list.

| Files | Checks |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `AGENTS.md`, `.agents/`, `.claude/`, `.vscode/`, `.editorconfig`, READMEs | None: nothing reads them |
| `.github/workflows/` | None locally: the pull request's CI run is the check |
| `/docs`, `/blog`, `apps/outreach` | `pnpm --filter @opendatacapture/outreach lint`, then `build`; no e2e reaches it |
| Unit tests (`__tests__/`, a package's `test/`) | `pnpm lint` and `pnpm test:coverage`; the apps never load them |
| Files | Checks |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `AGENTS.md`, `.agents/`, `.claude/`, `.vscode/`, `.editorconfig`, READMEs | None: nothing reads them |
| `.github/workflows/` | None locally: the pull request's CI run is the check |
| `/docs`, `/blog`, `apps/outreach` | `pnpm lint`, then `pnpm --filter @opendatacapture/outreach build`; no e2e reaches it |
| Unit tests (`__tests__/`, a package's `test/`) | `pnpm lint` and `pnpm test:coverage`; the apps never load them |

1. **Run `pnpm check` from the repo root** and fix every failure, a coverage shortfall included. It runs
`pnpm lint`, `pnpm test:coverage` and `pnpm test:e2e` in sequence, so a lint failure hides the rest until it
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/review-pr/REVIEW.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ pnpm generate:env
TURBO_CONCURRENCY=2 pnpm lint
```

Review the merge result. PR refs exist only on the upstream repository, not on a fork, hence the URL rather than a remote name. If `refs/pull/<N>/merge` is missing, use `refs/pull/<N>/head` and say so in the evidence. Run `generate:env` inside the worktree and never copy the repo's `.env`, so `db:push` cannot touch the user's dev database. Keep `TURBO_CONCURRENCY=2`: three reviews share the user's machine.
Review the merge result. PR refs exist only on the upstream repository, not on a fork, hence the URL rather than a remote name. If `refs/pull/<N>/merge` is missing, use `refs/pull/<N>/head` and say so in the evidence. Run `generate:env` inside the worktree and never copy the repo's `.env`, so the `db:push` that turbo's `dev`, `dev:test` and `test:e2e` run cannot touch the user's dev database. Keep `TURBO_CONCURRENCY=2`: three reviews share the user's machine.

- `install` or `generate:env` fails → return BLOCKED (machine) and write nothing.
- `lint` fails → return BLOCKED (PR) with the errors, and write a reply body to the scratchpad asking the author to update their branch against `main`, ending with `Reviewed at commit <headRefOid>.`
Expand Down
26 changes: 26 additions & 0 deletions .agents/skills/turborepo/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
name: turborepo
description: Configure and troubleshoot Turborepo repositories. Use when working with turbo.json, task pipelines, caching, Remote Cache, the turbo CLI, filtering, environment variables, package boundaries, monorepo structure, or CI workflows.
---

# Turborepo

The complete Turborepo documentation ships inside the installed `turbo` package. Do not rely on this skill for framework guidance. Always read the bundled docs, which match the installed version exactly.

Start with:

```text
node_modules/turbo/docs/README.md
```

Use that task index to choose the smallest relevant documentation page. Read it before changing Turborepo configuration, package scripts, or CI workflows.

If the package manager uses a non-flat `node_modules` layout or a workspace link, resolve the package location first:

```sh
node -p "require.resolve('turbo/package.json')"
```

Then read `docs/README.md` relative to the resolved package directory.

If `turbo` is not installed, inspect the repository's package manager and existing version constraints before adding it. After installation, use the bundled docs rather than guidance for a different release.
1 change: 1 addition & 0 deletions .claude/skills/turborepo
2 changes: 0 additions & 2 deletions .env.template
Original file line number Diff line number Diff line change
Expand Up @@ -151,5 +151,3 @@ VITE_DEV_DISABLE_TUTORIAL=false
# Plausable analytics config (optional, set both to an empty string to disable)
PLAUSIBLE_BASE_URL=
PLAUSIBLE_WEB_DATA_DOMAIN=

TURBO_CACHE_DIR=".turbo"
Loading
Loading