@jterrazz/test 15.3.0 → 16.0.0

package/README.md

@@ -1,504 +1,197 @@
 # @jterrazz/test
 
-Declarative testing framework for APIs, jobs, CLIs, websites, and mobile apps. Five constructors — `specification.api()`, `specification.jobs()`, `specification.cli()`, `specification.website()`, `specification.mobile()` — and specs that read as sentences: given → action → assertions. The vitest test name is the spec's description; all assertions go through `expect()` with auto-registered, subject-typed matchers.
+Declarative testing framework for modules, APIs, jobs, CLIs, rendered components, websites and native apps. Six constructors — `specification.api()`, `specification.jobs()`, `specification.cli()`, `specification.integration()`, `specification.website()`, `specification.mobile()` — plus the `component` chain, which starts nothing and needs none, and the module test, which needs neither.
+
+A spec reads as a sentence: given → action → assertions. The vitest test name is its only description, every assertion goes through `expect()` with subject-typed matchers, and the infrastructure a spec declares — Postgres, Redis, SQLite, a child process, a real Chromium, an iOS simulator — is started, isolated per worker and cleaned up for you.
 
 ```bash
 npm install -D @jterrazz/test vitest
 ```
 
-Everything a spec needs imports from `@jterrazz/test`. The exceptions are the two TOOL subpaths, which no spec ever imports: `@jterrazz/test/oxlint` (the zero-runtime lint plugin and its config fragment, loading no test runtime) and `@jterrazz/test/vitest` (what `vitest.config.ts` imports — the `defineSpecConfig()` preset and the `literate()` plugin).
+Everything a spec needs imports from `@jterrazz/test`; the entries beside it are tools no spec imports, and they are listed once — [docs/01 § What the tree publishes](docs/01-architecture.md#what-the-tree-publishes).
 
-## Quick start
+## One kind of test, one example
 
-### API testing (HTTP)
+Which kind a test is, is the first question — [the fork](docs/18-conventions.md#the-fork--which-kind-of-test-this-is) asks it in nine lines and the answer fixes the folder, the constructor and the project.
 
-```typescript
-// specs/api/api.specification.ts
-import { afterAll } from 'vitest';
-import { postgres, specification } from '@jterrazz/test';
-import { createApp } from '../../src/app.js';
-
-export const { api, cleanup } = await specification.api({
-    services: { db: postgres() }, // → compose service "db"
-    server: ({ db }) => createApp({ databaseUrl: db.connectionString }),
-});
-
-afterAll(cleanup);
-```
+**A module** — beside its code, nothing started ([docs/05](docs/05-module-tests.md)):
 
 ```typescript
-// specs/api/users/users.test.ts
+// src/domain/ranking.test.ts
+import { clock } from '@jterrazz/test';
 import { expect, test } from 'vitest';
-import { api } from '../api.specification.js';
-
-test('creates a user', async () => {
-    // Given - the complete request from _requests/create-user.http
-    const result = await api.request('create-user.http');
-
-    // Then - status + headers + body from _expected/user-created.http; row in db
-    expect(result.response).toMatch('user-created.http');
-    await expect(result.table('users')).toMatchRows({
-        columns: ['name'],
-        rows: [['Alice']],
-    });
-});
-```
-
-### CLI testing
-
-```typescript
-// specs/cli/cli.specification.ts
-import { resolve } from 'node:path';
-import { afterAll } from 'vitest';
-import { specification } from '@jterrazz/test';
-
-export const { cli, cleanup } = await specification.cli(
-    resolve(import.meta.dirname, '../../bin/my-cli.sh'),
-);
 
-afterAll(cleanup);
-```
+import { rank } from './ranking.js';
 
-```typescript
-// specs/cli/build/build.test.ts
-import { expect, test } from 'vitest';
-import { cli } from '../cli.specification.js';
+test('ranks a fresher post above an older one of equal score', () => {
+    // Given - two posts of equal score, one written this morning
+    using _ = clock.at('2026-03-04T09:30:00Z');
 
-test('builds the project', async () => {
-    // Given - sample app project spread into the cwd
-    const result = await cli.fixture('$FIXTURES/sample-app/').exec('build');
-
-    // Then - ESM output, no CJS
-    expect(result.exitCode).toBe(0);
-    expect(result.stdout).toContain('Build completed');
-    expect(result.file('dist/index.js').exists).toBe(true);
-    expect(result.file('dist/index.cjs').exists).toBe(false);
+    // Then - the fresher one leads
+    expect(rank(posts).map((post) => post.id)).toStrictEqual(['fresh', 'stale']);
 });
 ```
 
-A CLI session can also BE the spec file. A `<case>.spec.yaml` document states one scenario — its ground, then its runs — and executes either as a test file of its own (the `literate()` vite plugin) or through `cli.run('case.spec.yaml')`:
-
-```yaml
-description: refuses to build without a manifest
-runs:
-    - command: build
-      exit: 1
-      stderr: |
-          Error: no my-cli.yaml in the current directory
-```
-
-Same engine as the chain, same `{{token}}` grammar, same `TEST_UPDATE=1` — which rewrites each run's exit code and streams, and nothing else. A JSON Schema ships at `@jterrazz/test/schema` so an editor validates as you type. Full grammar: [docs/07-cli.md](docs/07-cli.md#spec-documents--casespecyaml).
-
-### Website testing (browser)
+**An integration spec** — a module against the real thing, or against a golden ([docs/06](docs/06-integration.md)):
 
 ```typescript
-// specs/website/website.specification.ts
-import { specification } from '@jterrazz/test';
-import { afterAll } from 'vitest';
-
-export const { cleanup, website } = await specification.website({
-    server: { command: 'node specs/_fixtures/website-app/server.mjs', ready: '/' },
-});
-
-afterAll(cleanup);
-```
-
-```typescript
-// specs/website/visit/head.test.ts
+// specs/integration/posts/find.spec.ts
 import { expect, test } from 'vitest';
-import { website } from '../website.specification.js';
 
-test('captures the full head surface of a rendered page', async () => {
-    // Given - the fixture homepage
-    const result = await website.visit('/');
+import { integration } from '../integration.specification.js';
 
-    // Then - one golden covers title, canonical, alternates, and metas
-    expect(result.status).toBe(200);
-    expect(result.head).toMatch('home.head.json');
-});
-```
+test('finds the post the migration wrote', async () => {
+    // Given - a seeded database
+    const result = await integration.seed('posts.sql').call(({ db }) => findPost(db, 'p-1'));
 
-### Mobile testing (iOS simulator)
-
-```typescript
-// specs/mobile/mobile.specification.ts
-import { specification } from '@jterrazz/test';
-import { afterAll } from 'vitest';
-
-export const { cleanup, mobile } = await specification.mobile({
-    app: { bundleId: 'com.jterrazz.fakenews' },
-    device: { name: 'iPhone 17', os: '26.5' },
+    // Then - the row comes back as the repository shapes it
+    expect(result.value).toMatch('found.json');
 });
-
-afterAll(cleanup);
 ```
 
-```typescript
-// specs/mobile/events/feed.test.ts
-import { expect, test } from 'vitest';
-import { mobile } from '../mobile.specification.js';
-
-test('shows the events feed behind its deep link', async () => {
-    // Given - the events screen
-    const result = await mobile.open('news://events');
-
-    // Then - one golden covers the whole projected accessibility tree
-    expect(result.screen).toMatch('events.screen.json');
-});
-```
-
-Actions are **terminal**: `.request()`, `.get()`, `.trigger()`, `.exec()`, `.call()`, `.fetch()`, `.visit()`, `.open()` execute the spec and resolve to a precisely typed result. There is no `.run()`, no label, and no `.spawn()`.
-
-## The six constructors
-
-One constructor per tested interface, each returning a record destructured with its canonical name:
-
-| Constructor                        | Returns                                  | Terminal actions                                             |
-| ---------------------------------- | ---------------------------------------- | ------------------------------------------------------------ |
-| `specification.api(options)`       | `{ api, cleanup, docker, orchestrator }` | `.request(file)`, `.get()`, `.post()`, `.put()`, `.delete()` |
-| `specification.jobs(options)`      | `{ jobs, cleanup, orchestrator }`        | `.trigger(name)`                                             |
-| `specification.cli(bin, options)`  | `{ cli, cleanup, docker, orchestrator }` | `.exec(args, { waitFor?, timeout? }?)`                       |
-| `specification.integration(opts?)` | `{ integration, cleanup }`               | `.call((services) => …)`                                     |
-| `specification.website(options)`   | `{ website, cleanup, url }`              | `.fetch(path)`, `.visit(path, scenario?)`                    |
-| `specification.mobile(options)`    | `{ mobile, cleanup, udid }`              | `.open(deepLink?, scenario?)`                                |
-
-A rendered component has no constructor: it starts nothing, so it is reached through the `component` chain directly (docs/16).
-
-### `specification.api({ services, server, mode?, root? })`
-
-One definition, two execution modes — the switch lives in `vitest.config.ts`, never in the specification file:
-
-- **`node`** (default): starts the declared services via testcontainers and runs the app in-process (Hono). Fastest feedback loop.
-- **`compose`**: runs `docker compose up` on `docker/compose.test.yaml` and sends real HTTP to the app service (`server` is ignored). Proves the shipped artifact.
+**A component** — a rendered unit in a real browser, beside its code ([docs/07](docs/07-component.md)):
 
-Resolution: `options.mode` > `TEST_MODE` env var > `'node'`. Only `.api()` has a mode.
-
-```typescript
-// vitest.config.ts — the mode switch lives HERE
-import { defineSpecConfig } from '@jterrazz/test/vitest';
-
-export default defineSpecConfig({
-    test: {
-        projects: [
-            { test: { name: 'http', include: ['specs/api/**/*.test.ts'] } },
-            {
-                test: {
-                    name: 'http-stack',
-                    include: ['specs/api/**/*.test.ts'],
-                    env: { TEST_MODE: 'compose' },
-                },
-            },
-        ],
-    },
-});
-```
-
-`services` is a named record. Keys type the `server` factory parameters, name databases for `.seed()`/`.table()` (`{ database: 'analyticsDb' }`), and drive the compose binding — a handle with no `composeService` option links to the compose service named exactly like its key, else the kebab-case conversion of the key (`analyticsDb` → `analytics-db`). If both names exist the binding is ambiguous and throws; `composeService` is the escape hatch for non-derivable names.
+```tsx
+// src/presentation/post-table.test.tsx
+import { component, content } from '@jterrazz/test';
+import { expect, test } from 'vitest';
 
-### `specification.jobs({ services, jobs, root? })`
+import { PostTable } from './post-table.js';
 
-Background jobs run in-process by definition — no HTTP server, no mode:
+test('says how much of the collection the table is showing', async () => {
+    // Given - a page of one row answering for a collection of two hundred
+    const result = await component.intercept(listing).render(<PostTable />, async (visitor) => {
+        await visitor.see(content('Showing 1 of 200 posts'));
+    });
 
-```typescript
-export const { jobs, cleanup } = await specification.jobs({
-    services: { db: postgres() },
-    jobs: ({ db }) => [nightlyReport(db)], // (services) => JobHandle[], or a static array
+    // Then - the table is qualified by what it is not showing
+    await expect(result.tree).toMatch('one-of-two-hundred.aria.yaml');
 });
-
-// In a test:
-const result = await jobs.seed('pending.sql').trigger('nightly-report');
 ```
 
-A `JobHandle` is `{ name: string; execute: () => Promise<void> }`.
-
-### `specification.cli(bin, { root?, services?, docker?, transform?, env?, serve? })`
-
-Runs a command binary against fixture projects in fresh temp directories. `env` (named environment sets) and `serve` (named servers) are the registries a [`<case>.spec.yaml`](docs/07-cli.md#spec-documents--casespecyaml) names by word. With `services`, connection URLs are injected into the child env automatically: `<KEY>_URL` per record key (CONSTANT_CASE at camelCase boundaries — `analyticsDb` → `ANALYTICS_DB_URL`), plus `DATABASE_URL` (exactly one SQL database) and `REDIS_URL` (exactly one redis). `.env()` overrides; `null` unsets.
+**A website** — the served page, driven in a browser ([docs/08](docs/08-website.md)):
 
 ```typescript
-export const { cli, cleanup } = await specification.cli('my-migrate-tool', {
-    services: { db: postgres() },
-});
-
-// DATABASE_URL / DB_URL are already in the child env:
-const result = await cli.seed('legacy-schema.sql').exec('up');
-```
-
-### `specification.website({ server?, url?, backend?, external?, root? })`
-
-Tests a rendered website: `.fetch(path)` for a raw HTTP exchange (redirects never followed), `.visit(path, scenario?)` for a page rendered in a real chromium. Exactly one of `server` (start the site locally — a free port injected as `PORT`, polled on `ready`) or `url` (target a running site) is required. `backend: { env, port? }` (server mode only) additionally starts a declared stub backend and injects its URL into the server child under `env`; each chain declares what it serves with `.intercept(contracts)`, the same contracts form `api`/`jobs` use.
+// specs/website/subscribe/subscribe.spec.ts
+import { button, content, field } from '@jterrazz/test';
+import { expect, test } from 'vitest';
 
-```typescript
-export const { website, cleanup } = await specification.website({
-    server: { command: 'node specs/_fixtures/website-app/server.mjs', ready: '/' },
-});
+import { website } from '../website.specification.js';
 
-// Raw exchange — status + headers, redirects surface as 3xx
-const redirect = await website.fetch('/old');
+test('subscribes through the form and captures the final state', async () => {
+    // Given - a visitor on the homepage
+    const result = await website.visit('/', async (visitor) => {
+        await visitor.fill(field('Email'), 'visitor@site.test');
+        await visitor.click(button('Subscribe'));
+        await visitor.see(content('Thanks for subscribing'));
+    });
 
-// Rendered page, optionally driven by a scenario (the When)
-const page = await website.visit('/', async (visitor) => {
-    await visitor.click(link('Articles'));
+    // Then - the page says so, and the console is clean
+    expect(result.content).toContain('Thanks for subscribing');
+    await expect(result.errors).toBeEmpty();
 });
 ```
 
-The handle destructures to `{ website, cleanup, url }` — no `docker`, no `orchestrator`. `.visit()` needs playwright (`npm install -D playwright && npx playwright install chromium`) — an optional peer dependency, only loaded when a spec actually renders a page. Full reference: [docs/14-website.md](docs/14-website.md).
-
-### `specification.mobile({ app, device, backend?, root? })`
-
-Tests a native app on the iOS simulator through a real XCUITest session (appium): `.open(deepLink?, scenario?)` terminates and relaunches the app (deterministic fresh state), applies the deep link, runs the scenario, and captures the final screen — the projected accessibility tree plus the visible texts. The simulator is resolved by `device: { name, os?, udid? }` via `xcrun simctl` (refusing on zero or several matches) and booted when shut down; the appium server is spawned from the caller project on a free port.
+**A mobile screen** — the installed app on a simulator ([docs/09](docs/09-mobile.md)):
 
 ```typescript
-export const { mobile, cleanup, udid } = await specification.mobile({
-    app: { bundleId: 'com.jterrazz.fakenews' },
-    device: { name: 'iPhone 17', os: '26.5' },
-});
-
-// A screen behind its deep link, driven by a scenario (the When)
-const result = await mobile.open('news://events', async (visitor) => {
-    await visitor.tap(button('Enquête Fauci COVID-19'));
-    await visitor.see(content('rapports'));
-});
-```
-
-The handle destructures to `{ mobile, cleanup, udid }` (plus `backendUrl` with `backend: { port? }` — a declared stub backend whose URL the CALLER wires into its own bundler env; the framework never touches Metro). The element vocabulary is the website facet's, unchanged — `button`, `field`, `content`, `testId`, `within` — landmarks excepted (an iOS screen has no ARIA regions; they refuse at runtime). Requires the app installed on the simulator plus the optional peers: `npm install -D appium webdriverio && npx appium driver install xcuitest`. Full reference: [docs/15-mobile.md](docs/15-mobile.md).
-
-### Root auto-discovery
-
-When `root` is absent, the framework walks up from the specification file to the **nearest** directory carrying `package.json` or `docker/compose.test.yaml`. In a workspace that is the member being tested, not the repository root above it. Pass `root` only when the convention does not fit. `root` is strictly the **project root** (compose detection + local-bin resolution, or the cwd of a `specification.website()` server command) — it is not a fixtures root; `.fixture()` resolves its own paths.
-
-## vitest config — `defineSpecConfig()`
+// specs/mobile/events/bookmark.spec.ts
+import { button, content } from '@jterrazz/test';
+import { expect, test } from 'vitest';
 
-`@jterrazz/test/vitest` is the subpath `vitest.config.ts` imports, never a spec. Beside `literate()` it exports the shared preset: what you pass is a plain vite/vitest config merged **over** its defaults, and `literate:` adds the plugin.
+import { mobile } from '../mobile.specification.js';
 
-```typescript
-import { defineSpecConfig } from '@jterrazz/test/vitest';
+test('bookmarks an event from its detail screen', async () => {
+    // Given - a visitor on the events feed
+    const result = await mobile.open('news://events', async (visitor) => {
+        await visitor.tap(button('Fauci inquiry'));
+        await visitor.see(content('reports'));
+        await visitor.tap(button('Bookmark'));
+    });
 
-export default defineSpecConfig({
-    literate: { specification: './specs/cli/cli.specification.ts' },
-    test: { include: ['specs/**/*.test.ts'] },
+    // Then - the capture reflects the screen after the interaction
+    expect(result.content).toContain('Bookmarked');
 });
 ```
 
-| Sets                               | To                                                     |
-| ---------------------------------- | ------------------------------------------------------ |
-| `cacheDir`                         | `.artifacts/vitest`                                    |
-| `test.coverage.reportsDirectory`   | `.artifacts/vitest/coverage` (bring your own provider) |
-| `test.testTimeout` / `hookTimeout` | `30_000`                                               |
-| `test.exclude`                     | vitest's defaults **+** `**/_fixtures/**`              |
-
-Nothing else: `fileParallelism`, `reporters`, `environment` and every `include` stay yours. Inline `projects` inherit the same defaults (vitest gives a project nothing from the root), arrays are concatenated rather than replaced, and scalars you state win. Full walkthrough, including migrating a hand-rolled config: [docs/02-developing.md](docs/02-developing.md#vitest-config-the-preset).
-
-Every artefact a run produces lands under `.artifacts/<tool>/` — one `.gitignore` line, one `rm -rf`. Per-run scratch (a CLI spec's temp cwd, a browser profile) stays in the OS temp dir.
-
-## Builder API
-
-### Setup (chainable)
-
-| Method                                  | Facets                          | Description                                                                                                 |
-| --------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `.seed("file.sql", { database? })`      | all                             | Load SQL from `_seeds/` — `database` is the record key (mandatory with ≥ 2 databases, forbidden with 1)     |
-| `.fixture("file")`                      | cli                             | Copy the feature-local `_fixtures/file` into the working directory                                          |
-| `.fixture("$FIXTURES/name/")`           | cli                             | Spread the shared `specs/_fixtures/<name>/` project into the cwd (trailing `/` = contents; layers)          |
-| `.env({ KEY: "value" })`                | cli                             | Set env vars on the child (`null` unsets, `$WORKDIR` expands, calls merge)                                  |
-| `.headers({ "Accept-Language": "fr" })` | api, website                    | Set HTTP request headers (merge on top of `.http` file headers, or on the browser context)                  |
-| `.intercept(contracts)`                 | all but cli                     | Declare the world: a `defineContracts(...)` composite — MSW on api/jobs, the stub backend on website/mobile |
-| `.intercept(contract)` / `([a, b])`     | all but cli                     | A single contract, or an ordered list                                                                       |
-| `.intercept(request, response)`         | all but cli                     | Inline pair, for one-off plumbing                                                                           |
-| `.clock("2026-03-04T09:30:00Z")`        | api, jobs, integration, website | Pin the calendar for this chain — the page's on website, this process's elsewhere                           |
-
-### Actions (terminal)
-
-| Method                                     | Facet   | Resolves to    | Description                                                                              |
-| ------------------------------------------ | ------- | -------------- | ---------------------------------------------------------------------------------------- |
-| `.request("create-user.http")`             | api     | `HttpResult`   | Send the COMPLETE request from `_requests/<file>` (method, path, headers, raw body)      |
-| `.get(path)` / `.delete(path)`             | api     | `HttpResult`   | Inline requests for simple cases                                                         |
-| `.post(path, body?)` / `.put(path, body?)` | api     | `HttpResult`   | Inline body: plain object, JSON-serialized                                               |
-| `.trigger("name")`                         | jobs    | `BaseResult`   | Execute a registered job                                                                 |
-| `.exec("args")`                            | cli     | `CliResult`    | Run the command                                                                          |
-| `.exec(["build", "start"])`                | cli     | `CliResult`    | Sequence in the same cwd; stops on first non-zero exit                                   |
-| `.exec("dev", { waitFor, timeout? })`      | cli     | `CliResult`    | Long-running: resolves at the pattern, killed at `timeout` (default 10 s)                |
-| `.run("case.spec.yaml")`                   | cli     | `CliResult`    | Run a `<case>.spec.yaml` — its ground and EVERY run asserted; the last one returns       |
-| `.fetch(path)`                             | website | `FetchResult`  | One raw HTTP exchange — redirects surface as 3xx, never followed                         |
-| `.visit(path, scenario?)`                  | website | `PageResult`   | Render the page in a shared chromium; with a scenario, the capture is the final state    |
-| `.open(deepLink?, scenario?)`              | mobile  | `ScreenResult` | Relaunch the app fresh on the simulator; with a scenario, the capture is the final state |
-
-One chain = one terminal action; databases reset at the start of every chain. Every cli spec runs in a fresh, empty temp directory.
-
-## Assertions — everything through `expect()`
-
-Accessors are **read-only**; the framework registers subject-typed matchers on vitest's `expect` automatically. `await` is required exactly where IO happens (tables, trees, containers).
+**An API** — the assembled app, met through a complete HTTP exchange ([docs/10](docs/10-api.md)):
 
 ```typescript
-// HTTP
-expect(result.status).toBe(201);
-expect(result.response).toMatch('user-created.http'); // _expected/<name> — status + header subset + body
-expect(result.response.body).toEqual({ error: 'User 999 not found' });
-
-// Tables (async — queries the database)
-await expect(result.table('orders', { database: 'db' })).toMatchRows({
-    columns: ['id', 'status', 'created_at'],
-    rows: [[match.uuid(), 'pending', match.iso8601()]],
-});
-await expect(result.table('orders', { database: 'db' })).toBeEmpty();
-
-// Streams (ANSI stripped by default; .text stays raw)
-expect(result.stdout).toContain('Build completed');
-expect(result.stdout).toMatch('help.txt'); // _expected/help.txt — {{token}}-aware
-expect(result.json).toMatch('config.json'); // _expected/config.json
-expect(result.json.value).toMatchObject({ name: 'shoply' });
-
-// Files & trees
-expect(result.file('my-shop/shoply.yaml').content).toContain('name: my-shop');
-await expect(result.directory('my-shop')).toMatch('shop-scaffold'); // _expected/shop-scaffold/
-await expect(result.filesystem).toMatch('upgraded-shop'); // whole cwd
-
-// Containers (docker-aware cli)
-await expect(result.container('alpha')).toBeRunning();
-```
-
-`toMatch` always resolves against `_expected/<name>` — every subject, no exceptions (only `.request()` reads `_requests/`). The folder is flat: a slash in the name creates a subfolder; the extension is part of the name and required, except for tree snapshots which are directories.
-
-**Updating snapshots:** `TEST_UPDATE=1` or `vitest -u`. Update mode writes **tokens**, not values — segments covered by an existing placeholder are preserved, and `{{workdir}}` is substituted automatically.
-
-## Dynamic values — one `{{token}}` grammar
-
-The same vocabulary works in `_expected/*.http` (body AND headers), `_expected/*.json`, text snapshots, and tree-snapshot file contents — and in code via `match.*`:
-
-`uuid` `ulid` `iso8601` `date` `time` `duration` `number` `int` `float` `semver` `sha` `hex` `base64` `port` `ip` `url` `email` `path` `workdir` `string` `any`
-
-Each token is capturable via `{{type#ref}}`: the first occurrence captures, later occurrences must be equal (scope: one spec). Code-side: `match.ref('order')`, `match.ref('intent', { not: 'order' })`, `match.regex(/…/)`.
-
-```http
-### _expected/order-created.http
-HTTP/1.1 201 Created
-Content-Type: application/json
-Location: /orders/{{uuid#order}}
-
-{
-    "id": "{{uuid#order}}",
-    "total": "{{number}}",
-    "createdAt": "{{iso8601}}"
-}
-```
-
-See [docs/09-tokens.md](docs/09-tokens.md) for the canonical accepted form of every token.
+// specs/api/users/create-user.spec.ts
+import { expect, test } from 'vitest';
 
-## Contracts
+import { api } from '../api.specification.js';
 
-Everything the outside world replies is a **contract** — a request to match and a response to serve, declared together. A feature owns a `contracts/` folder: a public `<name>.contracts.ts` facade (default export = the world, named exports = its scenarios) over internal `<provider>/<name>.ts` units, `provider ∈ { http, openai, anthropic }`.
+test('creates a user and returns its location', async () => {
+    // Given - an empty users table
+    const result = await api.seed('empty.sql').request('create-user.http');
 
-```typescript
-// contracts/openai/classify-product.ts
-import { defineContract, openai } from '@jterrazz/test';
-
-export default defineContract({
-    request: openai.responses({ user: /Product Classification/, tools: ['classify'] }),
-    response: openai.reply({ category: 'ELECTRONICS', confidence: 0.97 }),
+    // Then - the response matches the golden, tokens and all
+    expect(result.response).toMatch('user-created.http');
+    await expect(result.table('users')).toMatchRows({
+        columns: ['name'],
+        rows: [['Alice']],
+    });
 });
 ```
 
-```typescript
-// contracts/pipeline.contracts.ts
-import { defineContracts, http } from '@jterrazz/test';
-
-import classifyProduct from './openai/classify-product.js';
-import exchangeRates from './http/exchange-rates.js';
-
-const pipeline = defineContracts(classifyProduct, exchangeRates);
-
-export default pipeline;
-
-export const withRatesDown = () =>
-    pipeline.with({ request: http.get('/rates'), response: http.error(503) });
-```
+**A job** — what a name triggers, in-process ([docs/11](docs/11-jobs.md)):
 
 ```typescript
-const result = await jobs.intercept(pipeline).trigger('nightly-report');
-```
-
-Selection is first-match, one queue for every facet: `times` bounds how often a contract serves (omitted = unlimited, so retries and re-renders replay it), `required: true` fails the chain if it was never requested. Provider string filters are **exact** — the loose forms are explicit (`RegExp`, `match.includes('…')`). Failure simulation: `openai.error(429)`, `anthropic.timeout()`, `openai.malformed('not json')`. MSW ships as a direct dependency — no separate install. Full chapter: [docs/10-contracts.md](docs/10-contracts.md).
+// specs/jobs/digest/daily-digest.spec.ts
+import { expect, test } from 'vitest';
 
-## Docker-aware CLIs
+import { jobs } from '../jobs.specification.js';
 
-For CLIs that spawn containers, declare `docker: { envVar, nameLabel, testRunLabel }`. The runner injects a unique test-run id into the child env; the tested binary must label its containers with `testRunLabel=<id>`. Results expose lazy `.container(name)` accessors — and must be bound with `await using` so leaked containers are force-removed at scope exit:
+test('writes one digest row per active subscriber', async () => {
+    // Given - two active subscribers and one cancelled
+    const result = await jobs.seed('subscribers.sql').trigger('daily-digest');
 
-```typescript
-test('deploy spawns a labelled container', async () => {
-    // Given
-    await using result = await cli.fixture('$FIXTURES/two-shops/').exec('deploy alpha');
-
-    // Then - property reads are sync; only the matcher is async
-    const shop = result.container('alpha');
-    expect(shop.exists).toBe(true);
-    await expect(shop).toBeRunning();
-    expect(shop.file('/app/shoply.yaml').content).toContain('name: alpha');
+    // Then - only the active ones were written
+    await expect(result.table('digests')).toMatchRows({
+        columns: ['to'],
+        rows: [['a@site.test'], ['b@site.test']],
+    });
 });
 ```
 
-## Service factories
-
-| Factory      | Options                          | Connection string                     |
-| ------------ | -------------------------------- | ------------------------------------- |
-| `postgres()` | `composeService`, `image`, `env` | `postgresql://user:pass@host:port/db` |
-| `redis()`    | `composeService`, `image`        | `redis://host:port`                   |
-| `sqlite()`   | `init` or `prismaSchema`         | `file:/…/….sqlite`                    |
-
-`docker/compose.test.yaml` is the single source of truth for test infrastructure; `docker/<service>/init.sql` runs when the corresponding service starts. Parallel isolation is automatic per vitest worker: postgres clones a schema, redis assigns a database index, sqlite copies the template file, compose mode gets a dedicated project.
-
-`sqlite()` caches its schema template inside the project — `.artifacts/vitest/sqlite/template-<key>.sqlite` — so two checkouts never share one, and workers racing for a cold cache wait for the one that is building rather than all building at once. Details: [docs/11-services.md](docs/11-services.md#where-the-template-lives).
+**A CLI** — the built binary, usually as a document ([docs/12](docs/12-cli.md)):
 
-## Also exported
-
-Everything below comes from the package root (rule F1) — except the project helpers, which are `@jterrazz/test/vitest`'s. One line each; the chapter owns the detail.
-
-| Export                                                                                 | Is                                                                                                                  | Chapter                                                                         |
-| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `clock.at(iso)` · `.run(iso?)` · `.advance(ms)`                                        | The one time primitive — a `using` scope that pins `Date`, replacing `vi.useFakeTimers()` and `mockOfDate`          | [docs/12](docs/12-conventions.md#time--one-primitive-two-depths)                |
-| `intercept(…)`                                                                         | The same network double with no chain: `await using _ = await intercept(…)` in a module test                        | [docs/10](docs/10-contracts.md#intercept--the-same-double-with-no-chain)        |
-| `process({ command, ready?, … })`                                                      | The one shape an external process takes — a dev server, an API, a bundler, owned by the runner                      | [docs/11](docs/11-services.md#process--the-one-shape-an-external-process-takes) |
-| `http.stream(chunks, init?)` · `http.sse(events)`                                      | A chunked or server-sent response body a contract replies with                                                      | [docs/10](docs/10-contracts.md)                                                 |
-| `mockOf<T>()` · `mockOf<T>({ deep: false })`                                           | Deep double of a port (a member never stubbed answers with another double), or the flat one                         | [docs/12](docs/12-conventions.md#the-doubles-ladder)                            |
-| `mockOfDate`                                                                           | Freeze/reset the global `Date` via `.set(date)` / `.reset()` — `clock` is what replaces it                          | [docs/12](docs/12-conventions.md#time--one-primitive-two-depths)                |
-| `required(value, why)`                                                                 | The value, or a failure naming what was missing and why it mattered — instead of `!`                                | [docs/08](docs/08-assertions.md#two-helpers-that-are-not-matchers)              |
-| `waitUntil(predicate, { timeout?, interval?, why? })`                                  | Wait on a CONDITION, never a duration, on a real-time budget a pinned clock cannot starve                           | [docs/08](docs/08-assertions.md#two-helpers-that-are-not-matchers)              |
-| `unit()` `component()` `api()` `jobs()` `cli()` `integration()` `website()` `mobile()` | The vitest project helpers, each taking `{ include, exclude, timeout, serial }` on top of the project it already is | [docs/02](docs/02-developing.md#vitest-config-the-preset)                       |
-
-## Conventions
-
-Normative rules live in the constitution ([docs/12-conventions.md](docs/12-conventions.md)); the generated per-rule catalogue is [docs/13-linting.md](docs/13-linting.md). A facet (`specs/<facet>/`) carries its runner(s) at its root and holds domain folders; the folder follows the assets:
-
-```
-specs/<facet>/                  # api | jobs | cli | integration | website | mobile
-├── <facet>.specification.ts    # runner(s) at the facet ROOT (rule C1)
-└── <domain>/                   # a product command/area — 1..n test files
-    ├── <aspect>.test.ts
-    ├── _seeds/          # *.sql ONLY — database state
-    ├── _requests/       # *.http — inputs: COMPLETE request (method, path, headers, body)
-    ├── contracts/      # <name>.contracts.ts facade + <provider>/<name>.ts units + their .response.json / .request.ts data
-    ├── _fixtures/       # domain-local files/dirs copied into the cwd (cli) — shared pool lives at specs/_fixtures/
-    └── _expected/       # ALL expected fixtures, FLAT (incl. response *.http) — a slash in the name creates a subfolder
+```yaml
+# specs/cli/scaffold/new-project.spec.yaml
+description: scaffolds a project into an empty directory
+fixture: empty-dir
+runs:
+    - command: new my-app
+      exitCode: 0
+      stdout: scaffolded.txt
+      files:
+          my-app/package.json: package.json
 ```
 
-A test with its OWN asset dirs gets its own domain folder; tests without local assets group as sibling `<aspect>.test.ts` files inside a named group folder (the folder follows the assets). `.fixture(path)` is the one verb that copies into the cwd: domain-local (`_fixtures/…`) or shared (`$FIXTURES/…` → `specs/_fixtures/…`), with rsync trailing-slash semantics and layering. `.seed()` is SQL-only.
-
-Every test contains `// Given -` and `// Then -` comments (always both; `// When -` only if the action is not obvious — the chain IS the when). User-facing framework env vars: `TEST_MODE` and `TEST_UPDATE` — the only ones you set; the framework also reads vitest's `VITEST_POOL_ID` for per-worker isolation.
+## The map
 
-### Convention enforcement — the shipped lint plugin
+Everything is stated ONCE, in the chapter that owns it — a second copy here would be a second answer, and the one a reader meets first is the one that goes stale. The corpus map is [docs/README.md](docs/README.md).
 
-These conventions are not just prose: the package ships an oxlint plugin (`@jterrazz/test/oxlint`) with ~40 AST rules, plus a `jterrazz-test-check` binary (the conventions checker) that reads the data fixtures and cross-file relationships oxlint cannot. Wire the plugin into your `oxlint.config.ts` and run `jterrazz-test-check specs` in CI — the full four-channel catalogue (each rule, its channel and rationale) is generated into [docs/13-linting.md](docs/13-linting.md).
+| Subject                                                          | Chapter                                                          |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------- |
+| What the framework is, its trees, its channels, its four entries | [docs/01](docs/01-architecture.md)                               |
+| Installing it, the preset, the project helpers                   | [docs/02](docs/02-developing.md#vitest-config-the-preset)        |
+| What a consumer must bring: the peers, Docker, the pinned pair   | [docs/04](docs/04-operating.md#what-a-consumer-must-bring)       |
+| Each kind of test, one chapter, the same seven sections          | [docs/05](docs/05-module-tests.md)–[docs/12](docs/12-cli.md)     |
+| Naming an element: descriptors, verbs, `within`, exact names     | [docs/13](docs/13-elements.md)                                   |
+| Every matcher, by subject                                        | [docs/14](docs/14-assertions.md)                                 |
+| The `{{token}}` grammar, `#ref` captures, update mode            | [docs/15](docs/15-tokens.md)                                     |
+| Contracts, selection, provider builders, `intercept()`           | [docs/16](docs/16-contracts.md)                                  |
+| Services, init scripts, per-worker isolation, `process()`        | [docs/17](docs/17-services.md)                                   |
+| The conventions, and the catalogue that enforces them            | [docs/18](docs/18-conventions.md), [docs/19](docs/19-linting.md) |
 
-## Requirements
+The conventions are not prose alone: the package ships an oxlint plugin (`@jterrazz/test/oxlint`) and a `jterrazz-test-check` binary that reads the fixtures and cross-file relationships oxlint cannot. Every diagnostic ends in a rule id and an anchor into the generated catalogue.
 
-- **Docker** - testcontainers for node mode, docker compose for compose mode; not needed for `sqlite()`, plain cli specs, website specs, or mobile specs
-- **vitest** - peer dependency
-- **playwright** - optional peer dependency, only needed for `.visit()`: `npm install -D playwright && npx playwright install chromium`
-- **appium + webdriverio** - optional peer dependencies, only needed for `specification.mobile()`: `npm install -D appium webdriverio && npx appium driver install xcuitest` — plus Xcode, a simulator, and the app installed on it
-- **msw** - bundled as a direct dependency (powers `.intercept()` on a chain and `intercept()` in module scope, under node and in a page); no separate install
-- **hono** (or any web framework) - supplied by your project for in-process apps; the adapter only needs an object with a `request()` method, so it is not a peer
+Node 24 and vitest 5 are the required peers; everything else — a browser, a database driver, a simulator — is an optional peer, loaded the first time a spec needs it and named in the refusal when it is not there. What to install, and when: [docs/04](docs/04-operating.md#what-a-consumer-must-bring).
 
 ## Docs
 
-- Guide (chapters): [docs/README.md](docs/README.md) — getting started, API/jobs/CLI/website/mobile specs, assertions, tokens, contracts, services, conventions, linting
-- API reference: committed under [docs/reference/](docs/reference/) — compiled from source by `npm run docs`
-- Agent skill: [skills/jterrazz-test/](skills/jterrazz-test/) — mental model, per-facet references, generated rule reference
+- The corpus: [docs/README.md](docs/README.md) — the spine, one chapter per kind, the shared references, the enforcement.
+- API reference: [docs/reference/](docs/reference/) — compiled from source by `npm run docs`.
+- Agent skill: [skills/jterrazz-test/](skills/jterrazz-test/) — the fork, the mental model, and a generated signature card per kind.