@owlmeans/test 0.1.18-rc.9 → 0.1.18

package/README.md

@@ -1,14 +1,130 @@
 # @owlmeans/test
 
-Foundation helpers shared by the OwlMeans test packages and individual package test suites.
+Foundation helpers shared by the OwlMeans test packages and individual package test suites: the
+repo-root `.env` loader, environment gates that let a spec self-skip with a printed reason, and a
+JSON fixture loader. Every package's `tests/` uses it directly or through one of the harness
+packages built on it. It holds no auth mocks, no service gates and no browser driver — those are
+`@owlmeans/test-auth` (category B), `@owlmeans/test-integration` (category C) and
+`@owlmeans/test-ui` (category D). Tests run on `bun:test`; this package adds no runner. The
+package's skills are `testing-overview` (which category a package is in) and `testing-unit`.
 
-- `loadEnv(opts?)` — locate `<monorepo-root>/.env`, parse it, merge into `process.env` (idempotent; no-op when Bun already loaded the file via `--env-file`).
-- `requireEnv(keys)` — returns `{ ok: true }` or `{ skip: true, reason }` so callers can `test.skip(...)` when an integration variable is missing.
-- `hasEnv(key)` — boolean shorthand for conditional service provisioning in `tests/context.ts`.
-- `makeGates(spec)` — builds a frozen record of `{ <name>: { skip, reason } }` so a per-package `tests/context.ts` exposes one source of truth and individual specs can self-skip.
-- `loadFixture<T>(relPath)` — JSON fixture loader rooted at the consuming package's `tests/fixtures/`.
+## Installation
 
-Tests must be located at `packages/<pkg>/tests/`, named `*.spec.ts`. See the `testing-overview` skill for the full strategy.
+```bash
+bun add -d @owlmeans/test@^0.1.18
+```
+
+## Concepts
+
+- **Env file** — `<monorepo-root>/.env`, found by walking up from `process.cwd()` to a directory
+  holding `bun.lock`, or a `package.json` beside a `packages/` directory. Merged into `process.env`
+  once per process; a variable already set to a non-empty value wins. A missing file is not an error.
+- **Gate** — `EnvGate`: `{ ok: true }` when every required variable is set, otherwise
+  `{ skip: true, reason }` naming the missing ones.
+- **Gate map** — `makeGates({ name: [envKey, …] })`, a frozen record built once in a suite's
+  `tests/context.ts`; specs read it to choose `test` or `test.skip`.
+- **Fixture** — a JSON file under the consuming package's `tests/`, read relative to it.
+
+## Usage
+
+### Declare the suite's gates
+
+```typescript
+// tests/context.ts
+import { makeGates } from '@owlmeans/test'
+
+export const gates = makeGates({
+  openrouter: ['OPENROUTER_SECRET'],
+  anthropic: ['ANTHROPIC_SECRET'],
+})
+```
+
+### Self-skip a spec
+
+Bun picks `test` or `test.skip` synchronously, so decide from the gate at module scope:
+
+```typescript
+// tests/inference.spec.ts
+import { describe, expect, test } from 'bun:test'
+import { isSkip } from '@owlmeans/test'
+import { gates } from './context.js'
+
+const gate = gates.openrouter
+const it = isSkip(gate) ? test.skip : test
+
+describe('llm — openrouter', () => {
+  it(`answers a prompt${isSkip(gate) ? ` (${gate.reason})` : ''}`, async () => {
+    /* exercise the real provider */
+  })
+})
+```
+
+### Read the environment directly
+
+```typescript
+import { envHelper } from '@owlmeans/test'
+
+envHelper.loadEnv()                                  // idempotent; `{ force: true }` re-reads
+envHelper.loadEnv({ file: '/path/to/other/.env' })   // a workspace shaped differently
+
+if (envHelper.hasEnv('MONGO_URL')) {
+  /* provision the optional service in tests/context.ts */
+}
+
+const gate = envHelper.requireEnv(['SMTP_HOST', 'SMTP_PORT'])
+```
+
+### Load a fixture
+
+```typescript
+import { loadFixture } from '@owlmeans/test'
+
+const profile = loadFixture<ProfileRecord>('fixtures/profile.json') // <package>/tests/fixtures/profile.json
+```
+
+## API
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `envHelper` (`createEnvHelper()`) | helper | The env loader and gates below |
+| `envHelper.loadEnv(opts?)` | member | Locate `<monorepo-root>/.env`, parse it, merge into `process.env` (idempotent; no-op for variables Bun already loaded via `--env-file`) |
+| `envHelper.hasEnv(key)` | member | `loadEnv()`, then whether the variable is set and non-empty |
+| `envHelper.requireEnv(keys)` | member | `{ ok: true }` or `{ skip: true, reason }` so callers can `test.skip(...)` when an integration variable is missing |
+| `makeGates(spec)` | function | Frozen record of `{ <name>: EnvGate }` — one source of truth in `tests/context.ts` |
+| `isSkip(gate)` | function | Type guard narrowing an `EnvGate` to `{ skip: true, reason }` |
+| `loadFixture<T>(relPath)` | function | JSON fixture loader rooted at the consuming package's `tests/` |
+
+| Type | Purpose |
+|---|---|
+| `EnvGate`, `EnvOk`, `EnvSkip` | Gate outcome union and its branches |
+| `GateSpec`, `Gates<S>` | `{ name: string[] }` input and the frozen gate map it produces |
+| `LoadEnvOptions` | `{ force?, file? }` |
+| `EnvHelper` | The helper's interface |
+
+## Test layout
+
+Tests are located at `packages/<pkg>/tests/`, named `*.spec.ts`, and run with `bun test ./tests`
+from the package root. List `"./tests/**/*"` in the package `tsconfig.json` `exclude` so `tsc -b`
+never compiles specs. One real context per package lives in `tests/context.ts`; specs import its
+helper instead of building contexts themselves.
+
+## Common pitfalls
+
+- Awaiting anything before choosing `test` / `test.skip` — the choice must be a value already in hand.
+- A missing variable must skip, never fail; do not throw from a gate.
+- `loadFixture` resolves against `process.cwd()`, which `bun test` sets to the package root; running
+  specs from another directory breaks the path.
+- A workspace without `bun.lock` and without a `packages/` directory beside its `package.json` is not
+  found by `loadEnv` — pass `file` explicitly.
+- Do not add mocks here; auth mocks belong in `@owlmeans/test-auth`, and anything else is an
+  integration test.
+
+## Related packages
+
+- [`@owlmeans/test-auth`](../test-auth) — auth/authz mocks for category-B unit tests
+- [`@owlmeans/test-integration`](../test-integration) — service gates, namespaces and cleanup for category-C tests
+- [`@owlmeans/test-ui`](../test-ui) — Playwright-driven component acceptance for category D
+- [`@owlmeans/context`](../context) — the real context a suite's `tests/context.ts` builds
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -18,7 +134,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.13
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/test",
-  "version": "0.1.18-rc.9",
-  "generatedAt": "2026-09-10T18:54:42.490Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.720Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/testing-overview/SKILL.md

@@ -8,9 +8,17 @@ description: Decision matrix for which testing strategy to use per package in th
 
 Every package falls into exactly one of four testing categories. The category drives which `@owlmeans/test*` package(s) the tests depend on, where tests live, and what mocking is allowed.
 
-`@owlmeans/test` is the base every category builds on — env loading, env gates and fixture loading
-(`testing-unit` documents its exports). `@owlmeans/test-auth`, `@owlmeans/test-integration` and
-`@owlmeans/test-ui` each add one category's helpers on top of it.
+`@owlmeans/test` is the base every category builds on; each other harness package adds one
+category's helpers on top of it:
+
+| Package | Main exports | Documented in |
+|---|---|---|
+| `@owlmeans/test` | `loadEnv`, `requireEnv`, `hasEnv`, `makeGates`, `loadFixture` | `testing-unit` |
+| `@owlmeans/test-auth` | `makeFixtureKeyPair`, `makeMemoryTrustedResource`, `makeMockGuard`, `withAuth`, `signMockEnvelope`, `makeBearer`, fixtures `SUPERUSER`/`USER`/`SERVICE` | `testing-auth-unit` |
+| `@owlmeans/test-integration` | `mongoGate`, `redisGate`, `s3Gate`, `kubeGate`, `randomNamespace`, `registerCleanup`, `runCleanups` | `testing-integration` |
+| `@owlmeans/test-ui` | `launchBrowser`, `closeBrowser`, `withPage`, `mountComponent`, starter `harness/index.html` — on the `playwright` library, not `@playwright/test` | `testing-ui` |
+
+New auth mocks belong in `@owlmeans/test-auth`, never in a package's own `tests/`.
 
 ## Categories
 
@@ -23,13 +31,13 @@ Every package falls into exactly one of four testing categories. The category dr
 
 ## Package → category map
 
-All 101 packages, one category each.
+All 108 packages, one category each.
 
-- **A** (50): `agent`, `agent-common`, `agent-skills`, `api`, `api-config`, `api-config-client`, `api-config-server`, `astro`, `basic-ids`, `client-config`, `client-context`, `client-entrypoint`, `client-flow`, `client-job`, `client-resource`, `client-route`, `client-socket`, `config`, `consent`, `context`, `create-app`, `entrypoint`, `error`, `flow`, `i18n`, `iam`, `image-resource`, `llm-common`, `mailer`, `payment`, `queue`, `resource`, `route`, `router`, `server-auth-identity`, `server-context`, `server-entrypoint`, `server-iam`, `server-job`, `server-route`, `server-config`, `server-socket`, `server-wl`, `socket`, `state`, `static-resource`, `storage-common`, `web-db`, `web-gtm`, `web-router-react-router`
+- **A** (56): `agent`, `agent-common`, `agent-skills`, `api`, `api-config`, `api-config-client`, `api-config-server`, `astro`, `basic-ids`, `bot`, `bot-agent`, `client-config`, `client-context`, `client-entrypoint`, `client-flow`, `client-job`, `client-resource`, `client-route`, `client-socket`, `common-inquiry`, `config`, `consent`, `context`, `create-app`, `dep-config`, `entrypoint`, `error`, `flow`, `i18n`, `iam`, `image-resource`, `llm-common`, `mailer`, `payment`, `queue`, `resource`, `route`, `router`, `server-auth-identity`, `server-bot`, `server-context`, `server-entrypoint`, `server-iam`, `server-job`, `server-route`, `server-config`, `server-socket`, `server-wl`, `socket`, `state`, `static-resource`, `storage-common`, `web-db`, `web-gtm`, `web-inquiry`, `web-router-react-router`
 - **B** (20): `auth`, `auth-common`, `auth-otp`, `basic-envelope`, `basic-keys`, `client-auth`, `client-did`, `client-iam`, `client-payment`, `did`, `mui-oidc-rp`, `oidc`, `server-auth`, `server-auth-otp`, `server-oidc-provider`, `server-oidc-rp`, `web-auth`, `web-oidc-provider`, `web-oidc-rp`, `wled`
-- **C** (14): `kluster`, `llm` (live inference providers), `mailer-smtp`, `mongo`, `mongo-resource`, `postgres`, `postgres-resource`, `redis`, `redis-queue`, `redis-resource`, `server-api`, `server-app`, `server-mailer-mailgun`, `storage-resource`
-- **D** (11): `client`, `client-i18n`, `client-panel`, `client-wl`, `mui-panel`, `web-client`, `web-consent`, `web-flow`, `web-panel`, `web-router`, `web-wl`
-- **None** (6): `dep-config`, `_tpl`, and the four harness packages themselves — `test`, `test-auth`, `test-integration`, `test-ui`
+- **C** (16): `bot-postgres`, `kluster`, `llm` (live inference providers), `mailer-smtp`, `mongo`, `mongo-resource`, `planning-postgres`, `postgres`, `postgres-resource`, `redis`, `redis-queue`, `redis-resource`, `server-api`, `server-app`, `server-mailer-mailgun`, `storage-resource`
+- **D** (12): `client`, `client-i18n`, `client-panel`, `client-wl`, `mui-panel`, `web-bot`, `web-client`, `web-consent`, `web-flow`, `web-panel`, `web-router`, `web-wl`
+- **None** (5): `_tpl`, and the four harness packages themselves — `test`, `test-auth`, `test-integration`, `test-ui`
 
 A **contract** package and its **backend** split across categories. `queue`, `resource`,
 `storage-common` and `image-resource` are A — types, AJV schemas, error classes and declarations,
@@ -41,11 +49,16 @@ while one whose code issues real commands against the service is C even when it
 `redis-resource` imports `ioredis` for types alone and drives the client the db service hands it;
 `mongo-resource` carries its driver as a devDependency, for its specs only. Both are C.
 
+`server-bot` is A although its platforms are external services: they are reached only through the
+plugin seam, and its own API-faithful mock transport (a shipped feature, not a test mock) or a
+spec's `fetch` answering a platform's documented envelopes stands in for them; its store is any
+`Resource` (static resources in its specs). Its Postgres store, `bot-postgres`, is C.
+
 `web-router` is D, not A: it drives the History API, so its routing behaviour is only observable in
 a browser and its specs mount a real harness in chromium. A client-side package stays in A when it
 ships no component at all — `client-config`, `client-context`, `client-entrypoint`, `client-flow`,
-`client-job`, `client-resource`, `client-route`, `client-socket`, `web-db`, `web-gtm` and
-`web-router-react-router` are services, models and adapters, so `bun test` alone covers them.
+`client-job`, `client-resource`, `client-route`, `client-socket`, `web-db`, `web-gtm`, `web-inquiry`
+and `web-router-react-router` are services, models and adapters, so `bun test` alone covers them.
 
 A new package takes the category its own behaviour implies: an external service it cannot fake ⇒ C,
 a rendered React surface ⇒ D, an authenticated identity it must stand in for ⇒ B, otherwise A.

package/agent-meta/skills/testing-unit/SKILL.md

@@ -6,7 +6,7 @@ description: Category-A unit tests for OwlMeans Common packages — no mocks, re
 
 # Unit Tests — Category A (no mocks)
 
-**Install:** `"@owlmeans/test": "^0.1.18-rc.9"` in `devDependencies`
+**Install:** `"@owlmeans/test": "^0.1.18"` in `devDependencies`
 
 Apply this skill when adding tests to packages in category A (see `testing-overview`). The list includes core abstractions (`context`, `config`, `error`, `entrypoint`, `route`, `resource`, …) and platform-agnostic services (`api`, `state`, `flow`, `i18n`, `client-flow`, `client-socket`, `client-job`, `server-route`, `server-context`, `web-db`, …).
 

package/build/env.d.ts

@@ -1,15 +1,4 @@
-export interface EnvOk {
-    ok: true;
-}
-export interface EnvSkip {
-    skip: true;
-    reason: string;
-}
-export type EnvGate = EnvOk | EnvSkip;
-export declare const loadEnv: (opts?: {
-    force?: boolean;
-    file?: string;
-}) => void;
-export declare const hasEnv: (key: string) => boolean;
-export declare const requireEnv: (keys: string[]) => EnvGate;
+import type { EnvHelper } from './types.js';
+export declare const createEnvHelper: () => EnvHelper;
+export declare const envHelper: EnvHelper;
 //# sourceMappingURL=env.d.ts.map

package/build/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,IAAI,CAAA;CACT;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,OAAO,CAAA;AAkCrC,eAAO,MAAM,OAAO,UAAW;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,IAanE,CAAA;AAED,eAAO,MAAM,MAAM,QAAS,MAAM,KAAG,OAIpC,CAAA;AAED,eAAO,MAAM,UAAU,SAAU,MAAM,EAAE,KAAG,OAK3C,CAAA"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAW,SAAS,EAAkB,MAAM,YAAY,CAAA;AAKpE,eAAO,MAAM,eAAe,QAAO,SA4DlC,CAAA;AAED,eAAO,MAAM,SAAS,WAAoB,CAAA"}

package/build/env.js

@@ -1,63 +1,68 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+// Process-wide on purpose: the file is merged into `process.env`, which every helper instance shares.
 let loaded = false;
-const findRoot = (start) => {
-    let dir = start;
-    for (let i = 0; i < 10; i++) {
-        if (existsSync(resolve(dir, 'bun.lock')) || existsSync(resolve(dir, 'package.json')) && existsSync(resolve(dir, 'packages'))) {
-            return dir;
+export const createEnvHelper = () => {
+    const findRoot = (start) => {
+        let dir = start;
+        for (let i = 0; i < 10; i++) {
+            if (existsSync(resolve(dir, 'bun.lock')) || existsSync(resolve(dir, 'package.json')) && existsSync(resolve(dir, 'packages'))) {
+                return dir;
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
         }
-        const parent = dirname(dir);
-        if (parent === dir)
-            return null;
-        dir = parent;
-    }
-    return null;
-};
-const parseEnv = (text) => {
-    const out = {};
-    for (const raw of text.split(/\r?\n/)) {
-        const line = raw.trim();
-        if (line === '' || line.startsWith('#'))
-            continue;
-        const eq = line.indexOf('=');
-        if (eq < 1)
-            continue;
-        const key = line.slice(0, eq).trim();
-        let val = line.slice(eq + 1).trim();
-        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
-            val = val.slice(1, -1);
+        return null;
+    };
+    const parseEnv = (text) => {
+        const out = {};
+        for (const raw of text.split(/\r?\n/)) {
+            const line = raw.trim();
+            if (line === '' || line.startsWith('#'))
+                continue;
+            const eq = line.indexOf('=');
+            if (eq < 1)
+                continue;
+            const key = line.slice(0, eq).trim();
+            let val = line.slice(eq + 1).trim();
+            if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+                val = val.slice(1, -1);
+            }
+            out[key] = val;
         }
-        out[key] = val;
-    }
-    return out;
-};
-export const loadEnv = (opts) => {
-    if (loaded && opts?.force !== true)
-        return;
-    loaded = true;
-    const root = findRoot(process.cwd());
-    const envPath = opts?.file ?? (root != null ? resolve(root, '.env') : null);
-    if (envPath == null || !existsSync(envPath))
-        return;
-    const text = readFileSync(envPath, 'utf8');
-    const parsed = parseEnv(text);
-    for (const [k, v] of Object.entries(parsed)) {
-        if (process.env[k] == null || process.env[k] === '') {
-            process.env[k] = v;
+        return out;
+    };
+    const loadEnv = (opts) => {
+        if (loaded && opts?.force !== true)
+            return;
+        loaded = true;
+        const root = findRoot(process.cwd());
+        const envPath = opts?.file ?? (root != null ? resolve(root, '.env') : null);
+        if (envPath == null || !existsSync(envPath))
+            return;
+        const text = readFileSync(envPath, 'utf8');
+        const parsed = parseEnv(text);
+        for (const [k, v] of Object.entries(parsed)) {
+            if (process.env[k] == null || process.env[k] === '') {
+                process.env[k] = v;
+            }
         }
-    }
-};
-export const hasEnv = (key) => {
-    loadEnv();
-    const v = process.env[key];
-    return v != null && v !== '';
-};
-export const requireEnv = (keys) => {
-    loadEnv();
-    const missing = keys.filter(k => !hasEnv(k));
-    if (missing.length === 0)
-        return { ok: true };
-    return { skip: true, reason: `Missing env: ${missing.join(', ')}` };
+    };
+    const hasEnv = (key) => {
+        loadEnv();
+        const v = process.env[key];
+        return v != null && v !== '';
+    };
+    const requireEnv = (keys) => {
+        loadEnv();
+        const missing = keys.filter(k => !hasEnv(k));
+        if (missing.length === 0)
+            return { ok: true };
+        return { skip: true, reason: `Missing env: ${missing.join(', ')}` };
+    };
+    return { loadEnv, hasEnv, requireEnv };
 };
+export const envHelper = createEnvHelper();
 //# sourceMappingURL=env.js.map

package/build/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"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"}

package/build/gates.d.ts

@@ -1,8 +1,4 @@
-import type { EnvGate } from './env.js';
-export type GateSpec = Record<string, string[]>;
-export type Gates<S extends GateSpec> = {
-    readonly [K in keyof S]: EnvGate;
-};
+import type { EnvGate, GateSpec, Gates } from './types.js';
 /**
  * Build a frozen record of gates from a spec of `{ name: [envKey, ...] }`.
  * Use in `tests/context.ts` so a single source of truth describes which

package/build/gates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAEvC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAE/C,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,QAAQ,IAAI;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO;CAAE,CAAA;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,QAAQ,QAAQ,CAAC,KAAG,KAAK,CAAC,CAAC,CAM9D,CAAA;AAED,eAAO,MAAM,MAAM,SAAU,OAAO,KAAG,IAAI,IAAI;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAClC,CAAA"}
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,QAAQ,QAAQ,CAAC,KAAG,KAAK,CAAC,CAAC,CAM9D,CAAA;AAED,eAAO,MAAM,MAAM,SAAU,OAAO,KAAG,IAAI,IAAI;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAClC,CAAA"}

package/build/gates.js

@@ -1,4 +1,4 @@
-import { requireEnv } from './env.js';
+import { envHelper } from './env.js';
 /**
  * Build a frozen record of gates from a spec of `{ name: [envKey, ...] }`.
  * Use in `tests/context.ts` so a single source of truth describes which
@@ -8,7 +8,7 @@ import { requireEnv } from './env.js';
 export const makeGates = (spec) => {
     const out = {};
     for (const [name, keys] of Object.entries(spec)) {
-        out[name] = requireEnv(keys);
+        out[name] = envHelper.requireEnv(keys);
     }
     return Object.freeze(out);
 };

package/build/gates.js.map

@@ -1 +1 @@
-{"version":3,"file":"gates.js","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAOrC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAqB,IAAO,EAAY,EAAE;IACjE,MAAM,GAAG,GAAG,EAA6B,CAAA;IACzC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,GAAG,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAa,CAAA;AACvC,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,IAAa,EAA0C,EAAE,CAC7E,IAAwB,CAAC,IAAI,KAAK,IAAI,CAAA"}
+{"version":3,"file":"gates.js","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAGpC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAqB,IAAO,EAAY,EAAE;IACjE,MAAM,GAAG,GAAG,EAA6B,CAAA;IACzC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;IACxC,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAa,CAAA;AACvC,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,IAAa,EAA0C,EAAE,CAC7E,IAAwB,CAAC,IAAI,KAAK,IAAI,CAAA"}

package/build/index.d.ts

@@ -1,4 +1,5 @@
 export * from './env.js';
 export * from './gates.js';
 export * from './fixtures.js';
+export type * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,mBAAmB,YAAY,CAAA"}

package/build/types.d.ts

@@ -0,0 +1,31 @@
+export interface EnvOk {
+    ok: true;
+}
+export interface EnvSkip {
+    skip: true;
+    reason: string;
+}
+export type EnvGate = EnvOk | EnvSkip;
+export type GateSpec = Record<string, string[]>;
+export type Gates<S extends GateSpec> = {
+    readonly [K in keyof S]: EnvGate;
+};
+export interface LoadEnvOptions {
+    /** Re-read the file even when it was already loaded once in this process. */
+    force?: boolean;
+    /** The file to read instead of `<monorepo-root>/.env`. */
+    file?: string;
+}
+/** The test environment: `<monorepo-root>/.env` merged into `process.env`, and gates over it. */
+export interface EnvHelper {
+    /**
+     * Locate `<monorepo-root>/.env`, parse it and merge it into `process.env` — a variable that is
+     * already set and non-empty wins. Idempotent per process unless `force` is passed.
+     */
+    loadEnv: (opts?: LoadEnvOptions) => void;
+    /** Whether a variable is set to a non-empty value (after {@link EnvHelper.loadEnv}). */
+    hasEnv: (key: string) => boolean;
+    /** `{ ok: true }` when every key is set, otherwise `{ skip: true, reason }` naming the missing ones. */
+    requireEnv: (keys: string[]) => EnvGate;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,IAAI,CAAA;CACT;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;CACf;AAGD,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,OAAO,CAAA;AAGrC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAG/C,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,QAAQ,IAAI;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO;CAAE,CAAA;AAE5E,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,iGAAiG;AACjG,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,cAAc,KAAK,IAAI,CAAA;IACxC,wFAAwF;IACxF,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IAChC,wGAAwG;IACxG,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAA;CACxC"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/test",
-  "version": "0.1.18-rc.9",
+  "version": "0.1.18",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,11 +21,11 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.18-rc.9"
+    "@owlmeans/context": "^0.1.18"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "^0.1.18-rc.6",
-    "@types/bun": "^1.4.0",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@types/bun": "^1.4.2",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/env.ts

@@ -1,73 +1,70 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
+import type { EnvGate, EnvHelper, LoadEnvOptions } from './types.js'
 
-export interface EnvOk {
-  ok: true
-}
-
-export interface EnvSkip {
-  skip: true
-  reason: string
-}
-
-export type EnvGate = EnvOk | EnvSkip
-
+// Process-wide on purpose: the file is merged into `process.env`, which every helper instance shares.
 let loaded = false
 
-const findRoot = (start: string): string | null => {
-  let dir = start
-  for (let i = 0; i < 10; i++) {
-    if (existsSync(resolve(dir, 'bun.lock')) || existsSync(resolve(dir, 'package.json')) && existsSync(resolve(dir, 'packages'))) {
-      return dir
+export const createEnvHelper = (): EnvHelper => {
+  const findRoot = (start: string): string | null => {
+    let dir = start
+    for (let i = 0; i < 10; i++) {
+      if (existsSync(resolve(dir, 'bun.lock')) || existsSync(resolve(dir, 'package.json')) && existsSync(resolve(dir, 'packages'))) {
+        return dir
+      }
+      const parent = dirname(dir)
+      if (parent === dir) return null
+      dir = parent
     }
-    const parent = dirname(dir)
-    if (parent === dir) return null
-    dir = parent
+    return null
   }
-  return null
-}
 
-const parseEnv = (text: string): Record<string, string> => {
-  const out: Record<string, string> = {}
-  for (const raw of text.split(/\r?\n/)) {
-    const line = raw.trim()
-    if (line === '' || line.startsWith('#')) continue
-    const eq = line.indexOf('=')
-    if (eq < 1) continue
-    const key = line.slice(0, eq).trim()
-    let val = line.slice(eq + 1).trim()
-    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
-      val = val.slice(1, -1)
+  const parseEnv = (text: string): Record<string, string> => {
+    const out: Record<string, string> = {}
+    for (const raw of text.split(/\r?\n/)) {
+      const line = raw.trim()
+      if (line === '' || line.startsWith('#')) continue
+      const eq = line.indexOf('=')
+      if (eq < 1) continue
+      const key = line.slice(0, eq).trim()
+      let val = line.slice(eq + 1).trim()
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1)
+      }
+      out[key] = val
     }
-    out[key] = val
+    return out
   }
-  return out
-}
 
-export const loadEnv = (opts?: { force?: boolean, file?: string }): void => {
-  if (loaded && opts?.force !== true) return
-  loaded = true
-  const root = findRoot(process.cwd())
-  const envPath = opts?.file ?? (root != null ? resolve(root, '.env') : null)
-  if (envPath == null || !existsSync(envPath)) return
-  const text = readFileSync(envPath, 'utf8')
-  const parsed = parseEnv(text)
-  for (const [k, v] of Object.entries(parsed)) {
-    if (process.env[k] == null || process.env[k] === '') {
-      process.env[k] = v
+  const loadEnv = (opts?: LoadEnvOptions): void => {
+    if (loaded && opts?.force !== true) return
+    loaded = true
+    const root = findRoot(process.cwd())
+    const envPath = opts?.file ?? (root != null ? resolve(root, '.env') : null)
+    if (envPath == null || !existsSync(envPath)) return
+    const text = readFileSync(envPath, 'utf8')
+    const parsed = parseEnv(text)
+    for (const [k, v] of Object.entries(parsed)) {
+      if (process.env[k] == null || process.env[k] === '') {
+        process.env[k] = v
+      }
     }
   }
-}
 
-export const hasEnv = (key: string): boolean => {
-  loadEnv()
-  const v = process.env[key]
-  return v != null && v !== ''
-}
+  const hasEnv = (key: string): boolean => {
+    loadEnv()
+    const v = process.env[key]
+    return v != null && v !== ''
+  }
 
-export const requireEnv = (keys: string[]): EnvGate => {
-  loadEnv()
-  const missing = keys.filter(k => !hasEnv(k))
-  if (missing.length === 0) return { ok: true }
-  return { skip: true, reason: `Missing env: ${missing.join(', ')}` }
+  const requireEnv = (keys: string[]): EnvGate => {
+    loadEnv()
+    const missing = keys.filter(k => !hasEnv(k))
+    if (missing.length === 0) return { ok: true }
+    return { skip: true, reason: `Missing env: ${missing.join(', ')}` }
+  }
+
+  return { loadEnv, hasEnv, requireEnv }
 }
+
+export const envHelper = createEnvHelper()

package/src/gates.ts

@@ -1,9 +1,5 @@
-import { requireEnv } from './env.js'
-import type { EnvGate } from './env.js'
-
-export type GateSpec = Record<string, string[]>
-
-export type Gates<S extends GateSpec> = { readonly [K in keyof S]: EnvGate }
+import { envHelper } from './env.js'
+import type { EnvGate, GateSpec, Gates } from './types.js'
 
 /**
  * Build a frozen record of gates from a spec of `{ name: [envKey, ...] }`.
@@ -14,7 +10,7 @@ export type Gates<S extends GateSpec> = { readonly [K in keyof S]: EnvGate }
 export const makeGates = <S extends GateSpec>(spec: S): Gates<S> => {
   const out = {} as Record<string, EnvGate>
   for (const [name, keys] of Object.entries(spec)) {
-    out[name] = requireEnv(keys)
+    out[name] = envHelper.requireEnv(keys)
   }
   return Object.freeze(out) as Gates<S>
 }

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './env.js'
 export * from './gates.js'
 export * from './fixtures.js'
+export type * from './types.js'

package/src/types.ts

@@ -0,0 +1,37 @@
+export interface EnvOk {
+  ok: true
+}
+
+export interface EnvSkip {
+  skip: true
+  reason: string
+}
+
+// Kept as a type: a union of the two gate outcomes.
+export type EnvGate = EnvOk | EnvSkip
+
+// Kept as a type: a record over arbitrary gate names (an implicit index signature).
+export type GateSpec = Record<string, string[]>
+
+// Kept as a type: mapped over the spec's gate names.
+export type Gates<S extends GateSpec> = { readonly [K in keyof S]: EnvGate }
+
+export interface LoadEnvOptions {
+  /** Re-read the file even when it was already loaded once in this process. */
+  force?: boolean
+  /** The file to read instead of `<monorepo-root>/.env`. */
+  file?: string
+}
+
+/** The test environment: `<monorepo-root>/.env` merged into `process.env`, and gates over it. */
+export interface EnvHelper {
+  /**
+   * Locate `<monorepo-root>/.env`, parse it and merge it into `process.env` — a variable that is
+   * already set and non-empty wins. Idempotent per process unless `force` is passed.
+   */
+  loadEnv: (opts?: LoadEnvOptions) => void
+  /** Whether a variable is set to a non-empty value (after {@link EnvHelper.loadEnv}). */
+  hasEnv: (key: string) => boolean
+  /** `{ ok: true }` when every key is set, otherwise `{ skip: true, reason }` naming the missing ones. */
+  requireEnv: (keys: string[]) => EnvGate
+}