@jterrazz/test 14.2.0 → 15.0.0

package/README.md

@@ -87,7 +87,7 @@ runs:
           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/04-cli.md](docs/04-cli.md#spec-documents--casespecyaml).
+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)
 
@@ -210,7 +210,7 @@ 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/04-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.
+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.
 
 ```typescript
 export const { cli, cleanup } = await specification.cli('my-migrate-tool', {
@@ -239,7 +239,7 @@ const page = await website.visit('/', async (visitor) => {
 });
 ```
 
-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/11-website.md](docs/11-website.md).
+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? })`
 
@@ -258,7 +258,7 @@ const result = await mobile.open('news://events', async (visitor) => {
 });
 ```
 
-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/12-mobile.md](docs/12-mobile.md).
+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
 
@@ -284,7 +284,7 @@ export default defineSpecConfig({
 | `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/01-getting-started.md](docs/01-getting-started.md#vitest-config-the-preset).
+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.
 
@@ -378,7 +378,7 @@ Location: /orders/{{uuid#order}}
 }
 ```
 
-See [docs/06-tokens.md](docs/06-tokens.md) for the canonical accepted form of every token.
+See [docs/09-tokens.md](docs/09-tokens.md) for the canonical accepted form of every token.
 
 ## Contracts
 
@@ -413,7 +413,7 @@ export const withRatesDown = () =>
 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/07-contracts.md](docs/07-contracts.md).
+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).
 
 ## Docker-aware CLIs
 
@@ -442,7 +442,7 @@ test('deploy spawns a labelled container', async () => {
 
 `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/08-services.md](docs/08-services.md#where-the-template-lives).
+`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).
 
 ## Mocking utilities
 
@@ -457,7 +457,7 @@ import { mockOf, mockOfDate } from '@jterrazz/test';
 
 ## Conventions
 
-Normative rules live in the constitution ([docs/09-conventions.md](docs/09-conventions.md)); the generated per-rule catalogue is [docs/10-linting.md](docs/10-linting.md). A facet (`specs/<facet>/`) carries its runner(s) at its root and holds domain folders; the folder follows the assets:
+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 | integrations | lint
@@ -477,7 +477,7 @@ Every test contains `// Given -` and `// Then -` comments (always both; `// When
 
 ### Convention enforcement — the shipped lint plugin
 
-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/10-linting.md](docs/10-linting.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).
 
 ## Requirements
 

package/dist/ambiguity.js

@@ -119,7 +119,7 @@ function describeAmbiguity(options) {
 		"Disambiguate with one of:",
 		...fixes,
 		"",
-		"Docs: docs/11-website.md#designating-exactly-one-element (CONVENTIONS W3)"
+		"Docs: docs/14-website.md#designating-exactly-one-element (CONVENTIONS W3)"
 	].join("\n");
 }
 //#endregion

package/dist/appium.adapter.js

@@ -71,7 +71,7 @@ function describeMobileAmbiguity(options) {
 		"Disambiguate with one of:",
 		...fixes,
 		"",
-		"Docs: docs/12-mobile.md#designating-exactly-one-element (CONVENTIONS W3)"
+		"Docs: docs/15-mobile.md#designating-exactly-one-element (CONVENTIONS W3)"
 	].join("\n");
 }
 //#endregion

package/dist/artifacts.js

@@ -1671,11 +1671,19 @@ function updates(outcomes, scope) {
 	}));
 }
 /**
-* Start every server the document names, in declaration order, before the first
-* run. They all stay live for the whole file and are stopped together — one
-* document is one scenario, and its servers are part of its ground.
+* Start every server the document names, in declaration order, after `fixture:`
+* has been copied and before the first run. They all stay live for the whole
+* file and are stopped together — one document is one scenario, and its servers
+* are part of its ground.
+*
+* Every child is seeded with `TEST_WORKDIR`, the resolved working directory the
+* `{{workdir}}` token holds and `$WORKDIR` expands to. The fixtures are already
+* on disk when the child starts, so a served stub reads the world the document
+* laid down exactly as a stub binary reads its own fixture tree: a scenario is
+* a layer of files, never a flag threaded through the server. A document's
+* mapping-form env wins over it, key by key.
 */
-async function startServers(document, config, displayPath) {
+async function startServers(document, config, displayPath, workdir) {
 	const registry = config.serveRegistry ?? {};
 	const started = [];
 	const env = {};
@@ -1692,7 +1700,10 @@ async function startServers(document, config, displayPath) {
 		const adapter = new ServeAdapter({
 			command: registration.command,
 			ready: registration.ready
-		}, config.root ?? process.cwd(), "cli", entry.env);
+		}, config.root ?? process.cwd(), "cli", {
+			TEST_WORKDIR: workdir,
+			...entry.env
+		});
 		started.push(adapter);
 		try {
 			await adapter.start();
@@ -1749,8 +1760,9 @@ async function runSpecDocument(options) {
 		const { dest, src } = copyPlan(fixture.path, fileDir, workDir);
 		cpSync(src, dest, { recursive: true });
 	}
-	const servers = await startServers(document, config, displayPath);
-	const scope = new CaptureScope(safeRealpath(workDir));
+	const workdir = safeRealpath(workDir);
+	const servers = await startServers(document, config, displayPath, workdir);
+	const scope = new CaptureScope(workdir);
 	const env = expandWorkdir({
 		...options.baseEnv,
 		...servers.env,

package/dist/checker.js

@@ -415,7 +415,7 @@ function checkDockerRunnerAwaitUsing(rootDir) {
 			violations.push({
 				file: rel,
 				line,
-				message: `${rel}:${line}: result of docker-aware runner "${runner}" must be bound with \`await using\` so its containers are disposed (B5 — see docs/10-linting.md)`,
+				message: `${rel}:${line}: result of docker-aware runner "${runner}" must be bound with \`await using\` so its containers are disposed (B5 — see docs/13-linting.md)`,
 				severity: "error"
 			});
 		}
@@ -471,13 +471,13 @@ function checkDatabaseProperty(rootDir) {
 			if (count >= 2 && !hasDatabase) violations.push({
 				file: rel,
 				line,
-				message: `${rel}:${line}: .${verb}() must pass { database } — ${count} SQL databases are declared (A7 — see docs/10-linting.md)`,
+				message: `${rel}:${line}: .${verb}() must pass { database } — ${count} SQL databases are declared (A7 — see docs/13-linting.md)`,
 				severity: "error"
 			});
 			else if (count === 1 && hasDatabase) violations.push({
 				file: rel,
 				line,
-				message: `${rel}:${line}: .${verb}() must not pass { database } — a single SQL database is declared (A7 — see docs/10-linting.md)`,
+				message: `${rel}:${line}: .${verb}() must not pass { database } — a single SQL database is declared (A7 — see docs/13-linting.md)`,
 				severity: "error"
 			});
 		}
@@ -525,7 +525,7 @@ function checkDeadFixtures(rootDir) {
 			violations.push({
 				file: rel,
 				line: 1,
-				message: `${rel}: domain directory has ground subdirs (${groundSubdirs.join(", ")}) but no *.test.ts or *.spec.yaml (C9 — see docs/10-linting.md)`,
+				message: `${rel}: domain directory has ground subdirs (${groundSubdirs.join(", ")}) but no *.test.ts or *.spec.yaml (C9 — see docs/13-linting.md)`,
 				severity: "error"
 			});
 			continue;
@@ -551,7 +551,7 @@ function checkDeadFixtures(rootDir) {
 				violations.push({
 					file: relEntry,
 					line: 1,
-					message: `${relEntry}: dead fixture — no test literal in ${feature} references ${sub}/${entry.name} (C9 — see docs/10-linting.md)`,
+					message: `${relEntry}: dead fixture — no test literal in ${feature} references ${sub}/${entry.name} (C9 — see docs/13-linting.md)`,
 					severity
 				});
 			}
@@ -576,7 +576,7 @@ function checkPoolFixtures(rootDir) {
 			violations.push({
 				file: relEntry,
 				line: 1,
-				message: `${relEntry}: dead pool fixture — no spec under ${relative(rootDir, specsRoot)} references $FIXTURES/${entry.name} (C9 — see docs/10-linting.md)`,
+				message: `${relEntry}: dead pool fixture — no spec under ${relative(rootDir, specsRoot)} references $FIXTURES/${entry.name} (C9 — see docs/13-linting.md)`,
 				severity: "error"
 			});
 		}
@@ -678,7 +678,7 @@ function checkPoolFixtureSharing(rootDir) {
 		return {
 			file: relEntry,
 			line: 1,
-			message: `${relEntry}: only ${relLeaf} reaches for this pool fixture — the pool is what SEVERAL leaves share; move it to ${relLeaf}/${GROUND_FIXTURES}/${entry} and reference it as '${entry}' (C14 — see docs/10-linting.md, or run the checker with --fix)`,
+			message: `${relEntry}: only ${relLeaf} reaches for this pool fixture — the pool is what SEVERAL leaves share; move it to ${relLeaf}/${GROUND_FIXTURES}/${entry} and reference it as '${entry}' (C14 — see docs/13-linting.md, or run the checker with --fix)`,
 			severity: "error"
 		};
 	});
@@ -731,7 +731,7 @@ function checkLocalFixtureReach(rootDir) {
 				violations.push({
 					file: rel,
 					line,
-					message: `${rel}:${line}: fixture "${path}" reaches outside ${relative(rootDir, ground)} — a leaf's ground sits beside it; ground several leaves share goes to the $FIXTURES pool at ${relative(rootDir, pool)} (C15 — see docs/10-linting.md)`,
+					message: `${rel}:${line}: fixture "${path}" reaches outside ${relative(rootDir, ground)} — a leaf's ground sits beside it; ground several leaves share goes to the $FIXTURES pool at ${relative(rootDir, pool)} (C15 — see docs/13-linting.md)`,
 					severity: "error"
 				});
 			}
@@ -1152,7 +1152,7 @@ function checkSpecConventions(text, rel, path) {
 	].map(({ line, message, rule, severity }) => ({
 		file: rel,
 		line,
-		message: `${rel}:${line}: ${message} (${rule} — see docs/10-linting.md)`,
+		message: `${rel}:${line}: ${message} (${rule} — see docs/13-linting.md)`,
 		severity
 	}));
 }
@@ -1183,7 +1183,7 @@ function checkSpecDescriptionsUnique(rootDir) {
 		violations.push({
 			file: rel,
 			line: document.descriptionLine,
-			message: `${rel}:${document.descriptionLine}: "${document.description}" is already the description of ${first} — two documents of one directory cannot share a title (j4-spec-description-unique — see docs/10-linting.md)`,
+			message: `${rel}:${document.descriptionLine}: "${document.description}" is already the description of ${first} — two documents of one directory cannot share a title (j4-spec-description-unique — see docs/13-linting.md)`,
 			severity: "error"
 		});
 	}
@@ -1345,7 +1345,7 @@ function checkSpecFile(text, rel) {
 		return [{
 			file: rel,
 			line: error.line,
-			message: `${error.message} (D4b — see docs/10-linting.md)`,
+			message: `${error.message} (D4b — see docs/13-linting.md)`,
 			severity: "error"
 		}];
 	}
@@ -1401,13 +1401,13 @@ function checkConventionFiles(rootDir) {
 				if (depth1 && !REQUEST_LINE.test(firstLine(text))) violations.push({
 					file: rel,
 					line: 1,
-					message: `${rel}:1: a _requests/*.http file must start with a request line "METHOD /path" (D4b — see docs/10-linting.md)`,
+					message: `${rel}:1: a _requests/*.http file must start with a request line "METHOD /path" (D4b — see docs/13-linting.md)`,
 					severity: "error"
 				});
 				for (const { line, token } of findKnownTokens(text)) violations.push({
 					file: rel,
 					line,
-					message: `${rel}:${line}: token ${token} in a _requests/ file — requests are inputs, never matched; tokens are not validated here (D10 — see docs/10-linting.md)`,
+					message: `${rel}:${line}: token ${token} in a _requests/ file — requests are inputs, never matched; tokens are not validated here (D10 — see docs/13-linting.md)`,
 					severity: "warn",
 					token
 				});
@@ -1418,7 +1418,7 @@ function checkConventionFiles(rootDir) {
 			if (depth1 && entry.name.endsWith(".http") && !STATUS_LINE.test(firstLine(text))) violations.push({
 				file: rel,
 				line: 1,
-				message: `${rel}:1: an _expected/*.http file must start with a status line "HTTP/1.1 <status>" (D4b — see docs/10-linting.md)`,
+				message: `${rel}:1: an _expected/*.http file must start with a status line "HTTP/1.1 <status>" (D4b — see docs/13-linting.md)`,
 				severity: "error"
 			});
 			for (const { line, token } of findUnknownTokens(text)) violations.push({