@owlmeans/test-integration 0.1.18-rc.32 → 0.1.18-rc.33

package/README.md

@@ -4,10 +4,10 @@ Env-gated harness for integration tests of packages that talk to external servic
 
 Helpers exported here:
 
-- `mongoGate()`, `redisGate()`, `postgresGate()`, `s3Gate()`, `kubeGate()`, `smtpGate()` — read the env keys documented in `.env.example` and return `{ skip, reason?, env }`. A `tests/context.ts` uses these to decide whether to register the corresponding service in the real test context.
+- `gateHelper.mongoGate()`, `.redisGate()`, `.postgresGate()`, `.s3Gate()`, `.kubeGate()`, `.smtpGate()` — read the env keys documented in `.env.example` and return `{ skip, reason?, env }`. A `tests/context.ts` uses these to decide whether to register the corresponding service in the real test context.
 - The three datastore gates (`mongoGate`, `redisGate`, `postgresGate`) also require a host in the connection string to accept a TCP connect. A set variable pointing at nothing — a port-forward that is not running — closes the gate with a printed reason naming the variable and `host:port`, instead of failing the suite on a refused connection. The probe is synchronous, so gates keep being read at module scope.
 - `randomNamespace(prefix)` — short random suffix to keep DB names, key prefixes, and S3 prefixes unique per test run so suites can safely run in parallel.
-- `registerCleanup(fn)` + `runCleanups()` — opt-in `afterAll` cleanup queue.
+- `cleanupHelper.registerCleanup(fn)` + `cleanupHelper.runCleanups()` — opt-in `afterAll` cleanup queue.
 
 Specs do not call services through these helpers — they consume the per-package real test context built in `tests/context.ts` and only check `gates.<svc>.skip` to self-skip when the dependency is missing. See `testing-integration` skill for the full pattern.
 
@@ -19,7 +19,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.48
+npx @owlmeans/agent-skills@^0.1.18-rc.49
 ```
 
 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,
   "package": "@owlmeans/test-integration",
-  "version": "0.1.18-rc.32",
-  "generatedAt": "2026-10-05T08:32:19.106Z",
+  "version": "0.1.18-rc.33",
+  "generatedAt": "2026-10-05T21:03:06.387Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -6,7 +6,7 @@ description: Category-C integration tests for OwlMeans Common packages that talk
 
 # Integration Tests — Category C
 
-**Install:** `"@owlmeans/test-integration": "^0.1.18-rc.32"` in `devDependencies`
+**Install:** `"@owlmeans/test-integration": "^0.1.18-rc.33"` in `devDependencies`
 
 Category C applies to packages that integrate with external services: `postgres`,
 `postgres-resource`, `mongo`, `mongo-resource`, `redis`, `redis-resource`, `redis-queue`,
@@ -25,29 +25,29 @@ service hands it is category C even when it names no driver of its own.
 
 | Helper | Purpose |
 |---|---|
-| `postgresGate()`, `mongoGate()`, `redisGate()`, `s3Gate()`, `kubeGate()`, `smtpGate()` | Read env (and, for the three datastores, probe the address — below), return `IntegrationGate<E>` = `{ skip, reason?, env }`. |
+| `gateHelper` — `.postgresGate()`, `.mongoGate()`, `.redisGate()`, `.s3Gate()`, `.kubeGate()`, `.smtpGate()` | Read env (and, for the three datastores, probe the address — below), return `IntegrationGate<E>` = `{ skip, reason?, env }`. |
 | `IntegrationGate<E>` | `{ skip: boolean, reason?: string, env: Partial<E> }`. `env` holds only the variables that were actually populated. `skip` is a plain `boolean`, not a discriminant, so `env` stays `Partial<E>` on the open branch too — a suite reads a required variable through a cast: `gate.env.MONGO_URL as string`. |
 | `PostgresEnv`, `MongoEnv`, `RedisEnv`, `S3Env`, `KubeEnv`, `SmtpEnv` | The variable set each gate reads, so `tests/context.ts` types its exported gate. |
 | `randomNamespace(prefix, len?)` | Schema / DB / key / object-prefix namespacing for parallel-safe runs. Default 6 hex chars. |
-| `registerCleanup(fn)` + `runCleanups()` | Process-global LIFO queue. Only where **one** spec file of the package provisions anything — see below. |
+| `cleanupHelper.registerCleanup(fn)` + `.runCleanups()` | Process-global LIFO queue. Only where **one** spec file of the package provisions anything — see below. |
 
 Each gate fails closed on its **required** variables and treats the rest as optional:
 
 | Gate | Required | Optional |
 |---|---|---|
-| `mongoGate()` | `MONGO_URL` | `MONGO_TEST_DB_PREFIX` |
-| `postgresGate()` | `POSTGRES_URL` | `POSTGRES_TEST_DB_PREFIX` |
-| `redisGate()` | `REDIS_URL` | `REDIS_TEST_KEY_PREFIX` |
-| `s3Gate()` | `S3_ENDPOINT`, `S3_KEY`, `S3_SECRET`, `S3_TEST_BUCKET` | `S3_REGION` |
-| `kubeGate()` | `KUBE_CONFIG`, `KUBE_TEST_OK` | — |
-| `smtpGate()` | `SMTP_HOST`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_FROM`, `SMTP_TEST_TO` | `SMTP_PORT`, `SMTP_SECURE` |
+| `gateHelper.mongoGate()` | `MONGO_URL` | `MONGO_TEST_DB_PREFIX` |
+| `gateHelper.postgresGate()` | `POSTGRES_URL` | `POSTGRES_TEST_DB_PREFIX` |
+| `gateHelper.redisGate()` | `REDIS_URL` | `REDIS_TEST_KEY_PREFIX` |
+| `gateHelper.s3Gate()` | `S3_ENDPOINT`, `S3_KEY`, `S3_SECRET`, `S3_TEST_BUCKET` | `S3_REGION` |
+| `gateHelper.kubeGate()` | `KUBE_CONFIG`, `KUBE_TEST_OK` | — |
+| `gateHelper.smtpGate()` | `SMTP_HOST`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_FROM`, `SMTP_TEST_TO` | `SMTP_PORT`, `SMTP_SECURE` |
 
 `SMTP_TEST_TO` is required rather than optional because an open SMTP gate sends **real mail** — the
 suite must never guess a recipient.
 
 ### A datastore gate also asks whether the server answers
 
-`mongoGate()`, `redisGate()` and `postgresGate()` open only when their connection string is set
+`gateHelper.mongoGate()`, `.redisGate()` and `.postgresGate()` open only when their connection string is set
 **and** one of the hosts in it accepts a TCP connect (default ports 27017 / 6379 / 5432). A local
 `.env` keeps the port-forward address long after the forward is gone, and a gate that trusted the
 variable alone left `beforeAll` to spend its whole budget on `ECONNREFUSED` and fail the suite. An
@@ -64,12 +64,12 @@ Bun decides `test` vs `test.skip` synchronously and every consumer reads its gat
 so no `tests/context.ts` changes to get it. It is TCP only: no driver and no login, so a wrong
 password still opens the gate and fails in the suite, where it belongs. It answers "reachable" when
 it cannot tell — an SRV (`mongodb+srv://`) or unix-socket address, a string it cannot parse, a probe
-that cannot spawn — which is exactly the behaviour a gate had before it probed. `s3Gate()`,
-`kubeGate()` and `smtpGate()` do not probe: they name remote services, not a local forward.
+that cannot spawn — which is exactly the behaviour a gate had before it probed. `gateHelper.s3Gate()`,
+`.kubeGate()` and `.smtpGate()` do not probe: they name remote services, not a local forward.
 
 An optional variable is only in `env` when it was actually populated, which is why a suite reads a
 defaulted one — `POSTGRES_TEST_DB_PREFIX ?? 'omt'` — straight from `process.env` instead: calling
-any gate has already run `loadEnv`, so the `.env` values are in `process.env` by then.
+any gate has already run `envHelper.loadEnv`, so the `.env` values are in `process.env` by then.
 
 **Six services, six gates — a category-C package outside that set writes its own.** There is no
 gate for an LLM provider or for the Mailgun HTTP API, and none should be added to
@@ -90,7 +90,7 @@ asserts on the request it builds and the API's reply.
 ## Env contract
 
 One `.env.example` at the workspace root documents every variable, grouped by service, with
-comments; the `.env` beside it supplies real values for local runs and `loadEnv` (from
+comments; the `.env` beside it supplies real values for local runs and `envHelper.loadEnv` (from
 `@owlmeans/test`) picks it up. CI sets the same variables from secrets. **Empty value = skip, and
 so is a datastore address nothing answers at** — never a failure. A developer's `.env` may keep the
 port-forward address permanently: with the forward up the suites run, without it they skip.
@@ -143,7 +143,7 @@ A resource package (`*-resource`) owns the `Resource<T>` contract; the db packag
   translation — live in the **resource** package and gate on nothing: they leave the process
   alone. `@owlmeans/postgres-resource` is entirely this shape.
 - **Raw-driver specs** belong there too when the subject is the round trip and not the service.
-  `@owlmeans/mongo-resource` opens `mongoGate()`, derives a namespaced database with
+  `@owlmeans/mongo-resource` opens `gateHelper.mongoGate()`, derives a namespaced database with
   `randomNamespace`, registers a cleanup that drops it, and drives `mongodb` directly with the
   driver as its own devDependency — legitimate precisely because it never constructs the db
   service. It is also the one package that may use the global cleanup queue, because only that
@@ -156,10 +156,10 @@ A resource package (`*-resource`) owns the `Resource<T>` contract; the db packag
 ## Per-suite namespaces, not the global cleanup queue
 
 Bun runs **every spec file of a package in one process** with one shared module registry, and the
-queue is one array for that whole process. A process-global `registerCleanup`/`runCleanups()`
+queue is one array for that whole process. A process-global `cleanupHelper.registerCleanup`/`.runCleanups()`
 therefore misfires as soon as two spec files provision: the first to reach `afterAll` drains the
 entire queue and drops the namespaces of the files still to come. The queue is safe only where a
-**single** spec file provisions anything and that same file calls `runCleanups()`. That is the
+**single** spec file provisions anything and that same file calls `cleanupHelper.runCleanups()`. That is the
 shape `@owlmeans/mongo-resource` has — one gated round-trip spec registering one dropped database,
 beside two ungated spec files that translate criteria and references in memory and open nothing.
 
@@ -168,7 +168,7 @@ own teardown instead:
 
 ```ts
 // tests/context.ts
-export const gate: IntegrationGate<PostgresEnv> = postgresGate()
+export const gate: IntegrationGate<PostgresEnv> = gateHelper.postgresGate()
 
 export const makeSuite = (label: string): PgSuite => {
   const prefix = process.env.POSTGRES_TEST_DB_PREFIX ?? 'omt'
@@ -228,7 +228,7 @@ maker that runs more than once for the same alias re-declares the same entries a
 A `boot()` builds a whole new context, but the declarations belong to the module registry rather
 than to any context, so they carry across every boot in the process — deliberately.
 Never reset them inside a shared `boot()` helper: a `.migration()` registered before the boot
-would be silently dropped. A spec that wants a clean slate calls `resetDeclarations(alias)`
+would be silently dropped. A spec that wants a clean slate calls `pgDeclarationHelper.resetDeclarations(alias)` (or `mongoDeclarationHelper`'s)
 itself, which is what a spec simulating a restarted process should have to say out loud.
 
 Migration bodies belong at **module scope**, not inside the spec callback: the checksum
@@ -275,11 +275,11 @@ devDependencies.
 
 **Nothing auto-loads the workspace `.env`.** Bun reads a `.env` beside the working directory, so
 `bun test` inside a package never sees the one at the workspace root. The gates work because
-`@owlmeans/test`'s `loadEnv` does the loading itself and every gate calls it before reading a
+`@owlmeans/test`'s `envHelper.loadEnv` does the loading itself and every gate calls it before reading a
 variable: it walks up from the working directory for a `bun.lock`, or for a `package.json`
 sitting beside a directory named `packages`, and reads the `.env` it finds there. A variable
 already set to a non-empty value always wins, so `MONGO_URL=… bun test ./tests` still overrides
-the file. A workspace shaped any other way names the file itself — `loadEnv({ file })` at the top
+the file. A workspace shaped any other way names the file itself — `envHelper.loadEnv({ file })` at the top
 of `tests/context.ts`, before the gates run.
 
 Bun's per-test timeout is 5s, and **`bunfig.toml`'s `[test] timeout` does not raise it** — bun
@@ -301,7 +301,7 @@ bun test --timeout=60000 ./tests
 value instead, which also proves the call returned:
 
 ```ts
-expect(pgErrorToResourceError(circular)).toBe(circular)   // not: expect(() => …).not.toThrow()
+expect(pgErrorHelper.pgErrorToResourceError(circular)).toBe(circular)   // not: expect(() => …).not.toThrow()
 ```
 
 ## Rules
@@ -320,5 +320,5 @@ expect(pgErrorToResourceError(circular)).toBe(circular)   // not: expect(() =>
 ## When the env is partially populated
 
 Each gate fails closed. A test that needs both `S3_KEY` and `S3_SECRET` does not run if only
-one is set — `s3Gate()` reports `skip: true`. This is intentional: a half-configured
+one is set — `gateHelper.s3Gate()` reports `skip: true`. This is intentional: a half-configured
 environment must not produce false positives or partial coverage.

package/build/cleanup/types.d.ts

@@ -0,0 +1,20 @@
+export interface CleanupFn {
+    (): void | Promise<void>;
+}
+/** The opt-in teardown queue a suite's `tests/context.ts` fills and its `afterAll` drains. */
+export interface CleanupHelper {
+    /**
+     * Register a cleanup function that {@link CleanupHelper.runCleanups} will execute (LIFO).
+     * Use from `tests/context.ts` `setup()` to schedule teardown of resources
+     * that were provisioned for the suite (DB drop, key namespace flush,
+     * uploaded objects).
+     */
+    registerCleanup: (fn: CleanupFn) => void;
+    /**
+     * Run all pending cleanup functions in reverse registration order.
+     * Errors are swallowed and logged as warnings so a failing cleanup
+     * cannot mask a test failure.
+     */
+    runCleanups: () => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/cleanup/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cleanup/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IAAG,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE;AAEvD,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,eAAe,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,CAAA;IACxC;;;;OAIG;IACH,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACjC"}

package/build/cleanup/types.js

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

package/build/cleanup/types.js.map

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

package/build/cleanup.d.ts

@@ -1,15 +1,8 @@
-import type { CleanupFn } from './types.local.js';
-/**
- * Register a cleanup function that `runCleanups()` will execute (LIFO).
- * Use from `tests/context.ts` `setup()` to schedule teardown of resources
- * that were provisioned for the suite (DB drop, key namespace flush,
- * uploaded objects).
- */
+import type { CleanupFn, CleanupHelper } from './cleanup/types.js';
+export declare const createCleanupHelper: () => CleanupHelper;
+export declare const cleanupHelper: CleanupHelper;
+/** @deprecated compat:factory-refactor — use `cleanupHelper.registerCleanup(…)` */
 export declare const registerCleanup: (fn: CleanupFn) => void;
-/**
- * Run all pending cleanup functions in reverse registration order.
- * Errors are swallowed and logged as warnings so a failing cleanup
- * cannot mask a test failure.
- */
+/** @deprecated compat:factory-refactor — use `cleanupHelper.runCleanups()` */
 export declare const runCleanups: () => Promise<void>;
 //# sourceMappingURL=cleanup.d.ts.map

package/build/cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../src/cleanup.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAMjD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,OAAQ,SAAS,KAAG,IAE/C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAa,OAAO,CAAC,IAAI,CAUhD,CAAA"}
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../src/cleanup.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAOlE,eAAO,MAAM,mBAAmB,QAAO,aAkBtC,CAAA;AAED,eAAO,MAAM,aAAa,eAAwB,CAAA;AAElD,mFAAmF;AACnF,eAAO,MAAM,eAAe,OAAQ,SAAS,KAAG,IAAyC,CAAA;AAEzF,8EAA8E;AAC9E,eAAO,MAAM,WAAW,QAAa,OAAO,CAAC,IAAI,CAAsC,CAAA"}

package/build/cleanup.js

@@ -1,31 +1,29 @@
 import { logger } from '@owlmeans/log';
 const log = logger('test-integration');
+// Process-wide on purpose: every spec file of a run registers into, and drains, the same queue.
 const queue = [];
-/**
- * Register a cleanup function that `runCleanups()` will execute (LIFO).
- * Use from `tests/context.ts` `setup()` to schedule teardown of resources
- * that were provisioned for the suite (DB drop, key namespace flush,
- * uploaded objects).
- */
-export const registerCleanup = (fn) => {
-    queue.push(fn);
-};
-/**
- * Run all pending cleanup functions in reverse registration order.
- * Errors are swallowed and logged as warnings so a failing cleanup
- * cannot mask a test failure.
- */
-export const runCleanups = async () => {
-    while (queue.length > 0) {
-        const fn = queue.pop();
-        if (fn == null)
-            continue;
-        try {
-            await fn();
-        }
-        catch (err) {
-            log.warn('Cleanup failed', err);
+export const createCleanupHelper = () => {
+    const registerCleanup = (fn) => {
+        queue.push(fn);
+    };
+    const runCleanups = async () => {
+        while (queue.length > 0) {
+            const fn = queue.pop();
+            if (fn == null)
+                continue;
+            try {
+                await fn();
+            }
+            catch (err) {
+                log.warn('Cleanup failed', err);
+            }
         }
-    }
+    };
+    return { registerCleanup, runCleanups };
 };
+export const cleanupHelper = createCleanupHelper();
+/** @deprecated compat:factory-refactor — use `cleanupHelper.registerCleanup(…)` */
+export const registerCleanup = (fn) => cleanupHelper.registerCleanup(fn);
+/** @deprecated compat:factory-refactor — use `cleanupHelper.runCleanups()` */
+export const runCleanups = async () => await cleanupHelper.runCleanups();
 //# sourceMappingURL=cleanup.js.map

package/build/cleanup.js.map

@@ -1 +1 @@
-{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../src/cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAGtC,MAAM,GAAG,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAA;AAEtC,MAAM,KAAK,GAAgB,EAAE,CAAA;AAE7B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAa,EAAQ,EAAE;IACrD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AAChB,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,IAAmB,EAAE;IACnD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,EAAE,CAAA;QACtB,IAAI,EAAE,IAAI,IAAI;YAAE,SAAQ;QACxB,IAAI,CAAC;YACH,MAAM,EAAE,EAAE,CAAA;QACZ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAA;QACjC,CAAC;IACH,CAAC;AACH,CAAC,CAAA"}
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../src/cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAGtC,MAAM,GAAG,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAA;AAEtC,gGAAgG;AAChG,MAAM,KAAK,GAAgB,EAAE,CAAA;AAE7B,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAkB,EAAE;IACrD,MAAM,eAAe,GAAG,CAAC,EAAa,EAAQ,EAAE;QAC9C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC,CAAA;IAED,MAAM,WAAW,GAAG,KAAK,IAAmB,EAAE;QAC5C,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,EAAE,CAAA;YACtB,IAAI,EAAE,IAAI,IAAI;gBAAE,SAAQ;YACxB,IAAI,CAAC;gBACH,MAAM,EAAE,EAAE,CAAA;YACZ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAA;YACjC,CAAC;QACH,CAAC;IACH,CAAC,CAAA;IAED,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,CAAA;AACzC,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,mBAAmB,EAAE,CAAA;AAElD,mFAAmF;AACnF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAa,EAAQ,EAAE,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,CAAC,CAAA;AAEzF,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,IAAmB,EAAE,CAAC,MAAM,aAAa,CAAC,WAAW,EAAE,CAAA"}

package/build/gates/types.d.ts

@@ -0,0 +1,18 @@
+import type { IntegrationGate, KubeEnv, MongoEnv, PostgresEnv, RedisEnv, S3Env, SmtpEnv } from '../types.js';
+/**
+ * The env gates of the integration suites: each reads the variables documented in `.env.example`
+ * and answers `{ skip, reason?, env }`, so a `tests/context.ts` decides whether to register the
+ * real service and a spec self-skips when it is missing.
+ */
+export interface GateHelper {
+    /** `MONGO_URL` set AND a host in it accepting a TCP connect; `MONGO_TEST_DB_PREFIX` optional. */
+    mongoGate: () => IntegrationGate<MongoEnv>;
+    /** `REDIS_URL` set AND a host in it accepting a TCP connect; `REDIS_TEST_KEY_PREFIX` optional. */
+    redisGate: () => IntegrationGate<RedisEnv>;
+    s3Gate: () => IntegrationGate<S3Env>;
+    kubeGate: () => IntegrationGate<KubeEnv>;
+    /** `POSTGRES_URL` set AND a host in it accepting a TCP connect; `POSTGRES_TEST_DB_PREFIX` optional. */
+    postgresGate: () => IntegrationGate<PostgresEnv>;
+    smtpGate: () => IntegrationGate<SmtpEnv>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/gates/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/gates/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAE5G;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,iGAAiG;IACjG,SAAS,EAAE,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAA;IAC1C,kGAAkG;IAClG,SAAS,EAAE,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAA;IAC1C,MAAM,EAAE,MAAM,eAAe,CAAC,KAAK,CAAC,CAAA;IACpC,QAAQ,EAAE,MAAM,eAAe,CAAC,OAAO,CAAC,CAAA;IACxC,uGAAuG;IACvG,YAAY,EAAE,MAAM,eAAe,CAAC,WAAW,CAAC,CAAA;IAChD,QAAQ,EAAE,MAAM,eAAe,CAAC,OAAO,CAAC,CAAA;CACzC"}

package/build/gates/types.js

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

package/build/gates/types.js.map

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

package/build/gates.d.ts

@@ -1,8 +1,13 @@
-import type { IntegrationGate, KubeEnv, MongoEnv, PostgresEnv, RedisEnv, S3Env, SmtpEnv } from './types.js';
+import type { IntegrationGate, MongoEnv, PostgresEnv, RedisEnv, SmtpEnv } from './types.js';
+import type { GateHelper } from './gates/types.js';
+export declare const createGateHelper: () => GateHelper;
+export declare const gateHelper: GateHelper;
+/** @deprecated compat:factory-refactor — use `gateHelper.mongoGate()` */
 export declare const mongoGate: () => IntegrationGate<MongoEnv>;
+/** @deprecated compat:factory-refactor — use `gateHelper.redisGate()` */
 export declare const redisGate: () => IntegrationGate<RedisEnv>;
-export declare const s3Gate: () => IntegrationGate<S3Env>;
-export declare const kubeGate: () => IntegrationGate<KubeEnv>;
+/** @deprecated compat:factory-refactor — use `gateHelper.postgresGate()` */
 export declare const postgresGate: () => IntegrationGate<PostgresEnv>;
+/** @deprecated compat:factory-refactor — use `gateHelper.smtpGate()` */
 export declare const smtpGate: () => IntegrationGate<SmtpEnv>;
 //# sourceMappingURL=gates.d.ts.map

package/build/gates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAyB3G,eAAO,MAAM,SAAS,QAAO,eAAe,CAAC,QAAQ,CAC2D,CAAA;AAEhH,eAAO,MAAM,SAAS,QAAO,eAAe,CAAC,QAAQ,CAC2D,CAAA;AAEhH,eAAO,MAAM,MAAM,QAAO,eAAe,CAAC,KAAK,CAI5C,CAAA;AAEH,eAAO,MAAM,QAAQ,QAAO,eAAe,CAAC,OAAO,CACU,CAAA;AAE7D,eAAO,MAAM,YAAY,QAAO,eAAe,CAAC,WAAW,CACgE,CAAA;AAE3H,eAAO,MAAM,QAAQ,QAAO,eAAe,CAAC,OAAO,CAIhD,CAAA"}
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAW,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAS,OAAO,EAAE,MAAM,YAAY,CAAA;AAC3G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,eAAO,MAAM,gBAAgB,QAAO,UAiDnC,CAAA;AAED,eAAO,MAAM,UAAU,YAAqB,CAAA;AAE5C,yEAAyE;AACzE,eAAO,MAAM,SAAS,QAAO,eAAe,CAAC,QAAQ,CAA2B,CAAA;AAEhF,yEAAyE;AACzE,eAAO,MAAM,SAAS,QAAO,eAAe,CAAC,QAAQ,CAA2B,CAAA;AAEhF,4EAA4E;AAC5E,eAAO,MAAM,YAAY,QAAO,eAAe,CAAC,WAAW,CAA8B,CAAA;AAEzF,wEAAwE;AACxE,eAAO,MAAM,QAAQ,QAAO,eAAe,CAAC,OAAO,CAA0B,CAAA"}

package/build/gates.js

@@ -1,29 +1,41 @@
-import { hasEnv, requireEnv } from '@owlmeans/test';
-import { unreachableReason } from './reachability.js';
-const collect = (keys) => {
-    const env = {};
-    for (const k of keys) {
-        if (hasEnv(k))
-            env[k] = process.env[k];
-    }
-    return env;
+import { envHelper } from '@owlmeans/test';
+import { reachabilityUtils } from './reachability.js';
+export const createGateHelper = () => {
+    const collect = (keys) => {
+        const env = {};
+        for (const k of keys) {
+            if (envHelper.hasEnv(k))
+                env[k] = process.env[k];
+        }
+        return env;
+    };
+    const toIntegrationGate = (required, optional = [], reachable) => {
+        const gate = envHelper.requireEnv(required);
+        const env = collect([...required, ...optional]);
+        if (!('ok' in gate))
+            return { skip: true, reason: gate.reason, env };
+        if (reachable != null) {
+            const reason = reachabilityUtils.unreachableReason(reachable.key, process.env[reachable.key], reachable.defaultPort);
+            if (reason != null)
+                return { skip: true, reason, env };
+        }
+        return { skip: false, env };
+    };
+    const mongoGate = () => toIntegrationGate(['MONGO_URL'], ['MONGO_TEST_DB_PREFIX'], { key: 'MONGO_URL', defaultPort: 27017 });
+    const redisGate = () => toIntegrationGate(['REDIS_URL'], ['REDIS_TEST_KEY_PREFIX'], { key: 'REDIS_URL', defaultPort: 6379 });
+    const s3Gate = () => toIntegrationGate(['S3_ENDPOINT', 'S3_KEY', 'S3_SECRET', 'S3_TEST_BUCKET'], ['S3_REGION']);
+    const kubeGate = () => toIntegrationGate(['KUBE_CONFIG', 'KUBE_TEST_OK']);
+    const postgresGate = () => toIntegrationGate(['POSTGRES_URL'], ['POSTGRES_TEST_DB_PREFIX'], { key: 'POSTGRES_URL', defaultPort: 5432 });
+    const smtpGate = () => toIntegrationGate(['SMTP_HOST', 'SMTP_USER', 'SMTP_PASSWORD', 'SMTP_FROM', 'SMTP_TEST_TO'], ['SMTP_PORT', 'SMTP_SECURE']);
+    return { mongoGate, redisGate, s3Gate, kubeGate, postgresGate, smtpGate };
 };
-const toIntegrationGate = (required, optional = [], reachable) => {
-    const gate = requireEnv(required);
-    const env = collect([...required, ...optional]);
-    if (!('ok' in gate))
-        return { skip: true, reason: gate.reason, env };
-    if (reachable != null) {
-        const reason = unreachableReason(reachable.key, process.env[reachable.key], reachable.defaultPort);
-        if (reason != null)
-            return { skip: true, reason, env };
-    }
-    return { skip: false, env };
-};
-export const mongoGate = () => toIntegrationGate(['MONGO_URL'], ['MONGO_TEST_DB_PREFIX'], { key: 'MONGO_URL', defaultPort: 27017 });
-export const redisGate = () => toIntegrationGate(['REDIS_URL'], ['REDIS_TEST_KEY_PREFIX'], { key: 'REDIS_URL', defaultPort: 6379 });
-export const s3Gate = () => toIntegrationGate(['S3_ENDPOINT', 'S3_KEY', 'S3_SECRET', 'S3_TEST_BUCKET'], ['S3_REGION']);
-export const kubeGate = () => toIntegrationGate(['KUBE_CONFIG', 'KUBE_TEST_OK']);
-export const postgresGate = () => toIntegrationGate(['POSTGRES_URL'], ['POSTGRES_TEST_DB_PREFIX'], { key: 'POSTGRES_URL', defaultPort: 5432 });
-export const smtpGate = () => toIntegrationGate(['SMTP_HOST', 'SMTP_USER', 'SMTP_PASSWORD', 'SMTP_FROM', 'SMTP_TEST_TO'], ['SMTP_PORT', 'SMTP_SECURE']);
+export const gateHelper = createGateHelper();
+/** @deprecated compat:factory-refactor — use `gateHelper.mongoGate()` */
+export const mongoGate = () => gateHelper.mongoGate();
+/** @deprecated compat:factory-refactor — use `gateHelper.redisGate()` */
+export const redisGate = () => gateHelper.redisGate();
+/** @deprecated compat:factory-refactor — use `gateHelper.postgresGate()` */
+export const postgresGate = () => gateHelper.postgresGate();
+/** @deprecated compat:factory-refactor — use `gateHelper.smtpGate()` */
+export const smtpGate = () => gateHelper.smtpGate();
 //# sourceMappingURL=gates.js.map

package/build/gates.js.map

@@ -1 +1 @@
-{"version":3,"file":"gates.js","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAIrD,MAAM,OAAO,GAAG,CAAI,IAA0B,EAAc,EAAE;IAC5D,MAAM,GAAG,GAA2B,EAAE,CAAA;IACtC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,MAAM,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAW,CAAA;IAClD,CAAC;IACD,OAAO,GAAiB,CAAA;AAC1B,CAAC,CAAA;AAED,MAAM,iBAAiB,GAAG,CACxB,QAA8B,EAC9B,QAAQ,GAAyB,EAAE,EACnC,SAAwB,EACJ,EAAE;IACtB,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAA;IACjC,MAAM,GAAG,GAAG,OAAO,CAAI,CAAC,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAA;IAClD,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAA;IACpE,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAW,EAAE,SAAS,CAAC,WAAW,CAAC,CAAA;QAC5G,IAAI,MAAM,IAAI,IAAI;YAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAA;IACxD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;AAC7B,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,GAA8B,EAAE,CACvD,iBAAiB,CAAW,CAAC,WAAW,CAAC,EAAE,CAAC,sBAAsB,CAAC,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAA;AAEhH,MAAM,CAAC,MAAM,SAAS,GAAG,GAA8B,EAAE,CACvD,iBAAiB,CAAW,CAAC,WAAW,CAAC,EAAE,CAAC,uBAAuB,CAAC,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAA;AAEhH,MAAM,CAAC,MAAM,MAAM,GAAG,GAA2B,EAAE,CACjD,iBAAiB,CACf,CAAC,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,CAAC,EACxD,CAAC,WAAW,CAAC,CACd,CAAA;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,GAA6B,EAAE,CACrD,iBAAiB,CAAU,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,CAAA;AAE7D,MAAM,CAAC,MAAM,YAAY,GAAG,GAAiC,EAAE,CAC7D,iBAAiB,CAAc,CAAC,cAAc,CAAC,EAAE,CAAC,yBAAyB,CAAC,EAAE,EAAE,GAAG,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAA;AAE3H,MAAM,CAAC,MAAM,QAAQ,GAAG,GAA6B,EAAE,CACrD,iBAAiB,CACf,CAAC,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,cAAc,CAAC,EACxE,CAAC,WAAW,EAAE,aAAa,CAAC,CAC7B,CAAA"}
+{"version":3,"file":"gates.js","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"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"}

package/build/index.d.ts

@@ -1,5 +1,7 @@
 export * from './gates.js';
+export type * from './gates/types.js';
 export type * from './types.js';
 export * from './naming.js';
 export * from './cleanup.js';
+export type * from './cleanup/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,YAAY,CAAA;AAC1B,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,mBAAmB,kBAAkB,CAAA;AACrC,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,mBAAmB,oBAAoB,CAAA"}

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAE1B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAG1B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}

package/build/reachability/types.d.ts

@@ -0,0 +1,27 @@
+import type { ProbeTarget } from '../types.js';
+/**
+ * Whether the server a connection string names answers at all — asked synchronously, because
+ * Bun decides `test` vs `test.skip` synchronously and every gate is read at module scope.
+ */
+export interface ReachabilityUtils {
+    /**
+     * Every `host:port` in the authority of a connection string, or `null` when the string names
+     * nothing a TCP connect can check — an SRV record, a unix socket, or a shape this cannot read.
+     * `null` leaves the gate exactly as the variable alone would have it.
+     */
+    parseTargets: (url: string, defaultPort: number) => ProbeTarget[] | null;
+    /**
+     * `null` when at least one target accepts a TCP connection, otherwise the reason none did.
+     *
+     * A probe that cannot run at all also answers `null`: not knowing is not evidence the service is
+     * down, and the suite then behaves exactly as it did before probes existed.
+     */
+    probeTargets: (targets: ProbeTarget[]) => string | null;
+    /**
+     * The skip reason for a populated connection-string variable whose server does not answer, or
+     * `null` when it answers or cannot be probed. Printed once per variable and address, so a closed
+     * gate is never mistaken for a suite that has nothing to run.
+     */
+    unreachableReason: (variable: string, url: string, defaultPort: number) => string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/reachability/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/reachability/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,WAAW,EAAE,GAAG,IAAI,CAAA;IACxE;;;;;OAKG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,MAAM,GAAG,IAAI,CAAA;IACvD;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAA;CACzF"}

package/build/reachability/types.js

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

package/build/reachability/types.js.map

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

package/build/reachability.d.ts

@@ -1,21 +1,4 @@
-import type { ProbeTarget } from './types.js';
-/**
- * Every `host:port` in the authority of a connection string, or `null` when the string names
- * nothing a TCP connect can check — an SRV record, a unix socket, or a shape this cannot read.
- * `null` leaves the gate exactly as the variable alone would have it.
- */
-export declare const parseTargets: (url: string, defaultPort: number) => ProbeTarget[] | null;
-/**
- * `null` when at least one target accepts a TCP connection, otherwise the reason none did.
- *
- * A probe that cannot run at all also answers `null`: not knowing is not evidence the service is
- * down, and the suite then behaves exactly as it did before probes existed.
- */
-export declare const probeTargets: (targets: ProbeTarget[]) => string | null;
-/**
- * The skip reason for a populated connection-string variable whose server does not answer, or
- * `null` when it answers or cannot be probed. Printed once per variable and address, so a closed
- * gate is never mistaken for a suite that has nothing to run.
- */
-export declare const unreachableReason: (variable: string, url: string, defaultPort: number) => string | null;
+import type { ReachabilityUtils } from './reachability/types.js';
+export declare const createReachabilityUtils: () => ReachabilityUtils;
+export declare const reachabilityUtils: ReachabilityUtils;
 //# sourceMappingURL=reachability.d.ts.map

package/build/reachability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reachability.d.ts","sourceRoot":"","sources":["../src/reachability.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAiB7C;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAS,MAAM,eAAe,MAAM,KAAG,WAAW,EAAE,GAAG,IA6B/E,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,YAAa,WAAW,EAAE,KAAG,MAAM,GAAG,IAkB9D,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAAc,MAAM,OAAO,MAAM,eAAe,MAAM,KAAG,MAAM,GAAG,IAiB/F,CAAA"}
+{"version":3,"file":"reachability.d.ts","sourceRoot":"","sources":["../src/reachability.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAkBhE,eAAO,MAAM,uBAAuB,QAAO,iBAwE1C,CAAA;AAED,eAAO,MAAM,iBAAiB,mBAA4B,CAAA"}

package/build/reachability.js

@@ -11,84 +11,73 @@ const log = logger('test-integration');
  * it spends its whole `beforeAll` budget on a refused connection and FAILS. Only a TCP connect is
  * asked — never a login — so no driver is needed here and no credential leaves the variable.
  */
+// Process-wide on purpose: every gate of a run shares one answer per address and one warning per reason.
 const answers = new Map();
 const warned = new Set();
-/**
- * Every `host:port` in the authority of a connection string, or `null` when the string names
- * nothing a TCP connect can check — an SRV record, a unix socket, or a shape this cannot read.
- * `null` leaves the gate exactly as the variable alone would have it.
- */
-export const parseTargets = (url, defaultPort) => {
-    const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(url);
-    if (scheme == null || scheme[1].toLowerCase().endsWith('+srv')) {
-        return null;
-    }
-    const rest = url.slice(scheme[0].length);
-    const end = rest.search(/[/?#]/);
-    const authority = end < 0 ? rest : rest.slice(0, end);
-    const hosts = authority.slice(authority.lastIndexOf('@') + 1);
-    const targets = [];
-    for (const entry of hosts.split(',')) {
-        const match = /^(\[[^\]]+\]|[^:]*)(?::(\d+))?$/.exec(entry);
-        if (match == null) {
+export const createReachabilityUtils = () => {
+    const parseTargets = (url, defaultPort) => {
+        const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(url);
+        if (scheme == null || scheme[1].toLowerCase().endsWith('+srv')) {
             return null;
         }
-        let host;
-        try {
-            host = decodeURIComponent(match[1]).replace(/^\[|\]$/g, '');
+        const rest = url.slice(scheme[0].length);
+        const end = rest.search(/[/?#]/);
+        const authority = end < 0 ? rest : rest.slice(0, end);
+        const hosts = authority.slice(authority.lastIndexOf('@') + 1);
+        const targets = [];
+        for (const entry of hosts.split(',')) {
+            const match = /^(\[[^\]]+\]|[^:]*)(?::(\d+))?$/.exec(entry);
+            if (match == null) {
+                return null;
+            }
+            let host;
+            try {
+                host = decodeURIComponent(match[1]).replace(/^\[|\]$/g, '');
+            }
+            catch {
+                return null;
+            }
+            if (host === '' || host.includes('/')) {
+                return null;
+            }
+            targets.push({ host, port: match[2] != null ? parseInt(match[2], 10) : defaultPort });
+        }
+        return targets.length > 0 ? targets : null;
+    };
+    const probeTargets = (targets) => {
+        const key = targets.map(({ host, port }) => `${host}:${port}`).join(',');
+        if (answers.has(key)) {
+            return answers.get(key) ?? null;
         }
-        catch {
+        const result = spawnSync(process.execPath, ['-e', PROBE_SCRIPT], {
+            env: { ...process.env, OWLMEANS_TEST_PROBE: JSON.stringify([targets, CONNECT_TIMEOUT_MS]) },
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: CONNECT_TIMEOUT_MS + SPAWN_GRACE_MS,
+            encoding: 'utf8',
+        });
+        const answer = result.error == null && result.status === 1
+            ? `nothing answers at ${key} (${result.stdout.trim() !== '' ? result.stdout.trim() : 'unreachable'})`
+            : null;
+        answers.set(key, answer);
+        return answer;
+    };
+    const unreachableReason = (variable, url, defaultPort) => {
+        const targets = parseTargets(url, defaultPort);
+        if (targets == null) {
             return null;
         }
-        if (host === '' || host.includes('/')) {
+        const unreachable = probeTargets(targets);
+        if (unreachable == null) {
             return null;
         }
-        targets.push({ host, port: match[2] != null ? parseInt(match[2], 10) : defaultPort });
-    }
-    return targets.length > 0 ? targets : null;
-};
-/**
- * `null` when at least one target accepts a TCP connection, otherwise the reason none did.
- *
- * A probe that cannot run at all also answers `null`: not knowing is not evidence the service is
- * down, and the suite then behaves exactly as it did before probes existed.
- */
-export const probeTargets = (targets) => {
-    const key = targets.map(({ host, port }) => `${host}:${port}`).join(',');
-    if (answers.has(key)) {
-        return answers.get(key) ?? null;
-    }
-    const result = spawnSync(process.execPath, ['-e', PROBE_SCRIPT], {
-        env: { ...process.env, OWLMEANS_TEST_PROBE: JSON.stringify([targets, CONNECT_TIMEOUT_MS]) },
-        stdio: ['ignore', 'pipe', 'ignore'],
-        timeout: CONNECT_TIMEOUT_MS + SPAWN_GRACE_MS,
-        encoding: 'utf8',
-    });
-    const answer = result.error == null && result.status === 1
-        ? `nothing answers at ${key} (${result.stdout.trim() !== '' ? result.stdout.trim() : 'unreachable'})`
-        : null;
-    answers.set(key, answer);
-    return answer;
-};
-/**
- * The skip reason for a populated connection-string variable whose server does not answer, or
- * `null` when it answers or cannot be probed. Printed once per variable and address, so a closed
- * gate is never mistaken for a suite that has nothing to run.
- */
-export const unreachableReason = (variable, url, defaultPort) => {
-    const targets = parseTargets(url, defaultPort);
-    if (targets == null) {
-        return null;
-    }
-    const unreachable = probeTargets(targets);
-    if (unreachable == null) {
-        return null;
-    }
-    const reason = `${variable} is set, but ${unreachable} — start the service (or its port-forward) to run these specs`;
-    if (!warned.has(reason)) {
-        warned.add(reason);
-        log.warn('Skipping integration specs: a configured service is unreachable', { variable, unreachable });
-    }
-    return reason;
+        const reason = `${variable} is set, but ${unreachable} — start the service (or its port-forward) to run these specs`;
+        if (!warned.has(reason)) {
+            warned.add(reason);
+            log.warn('Skipping integration specs: a configured service is unreachable', { variable, unreachable });
+        }
+        return reason;
+    };
+    return { parseTargets, probeTargets, unreachableReason };
 };
+export const reachabilityUtils = createReachabilityUtils();
 //# sourceMappingURL=reachability.js.map

package/build/reachability.js.map

@@ -1 +1 @@
-{"version":3,"file":"reachability.js","sourceRoot":"","sources":["../src/reachability.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reachability.js","sourceRoot":"","sources":["../src/reachability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AACtC,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAIpF,MAAM,GAAG,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAA;AAEtC;;;;;;;;GAQG;AAEH,yGAAyG;AACzG,MAAM,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAA;AAChD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAA;AAEhC,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAsB,EAAE;IAC7D,MAAM,YAAY,GAAG,CAAC,GAAW,EAAE,WAAmB,EAAwB,EAAE;QAC9E,MAAM,MAAM,GAAG,4BAA4B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACrD,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/D,OAAO,IAAI,CAAA;QACb,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QAChC,MAAM,SAAS,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;QACrD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;QAE7D,MAAM,OAAO,GAAkB,EAAE,CAAA;QACjC,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,iCAAiC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAC3D,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;gBAClB,OAAO,IAAI,CAAA;YACb,CAAC;YACD,IAAI,IAAY,CAAA;YAChB,IAAI,CAAC;gBACH,IAAI,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;YAC7D,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAA;YACb,CAAC;YACD,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBACtC,OAAO,IAAI,CAAA;YACb,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAA;QACvF,CAAC;QAED,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAA;IAC5C,CAAC,CAAA;IAED,MAAM,YAAY,GAAG,CAAC,OAAsB,EAAiB,EAAE;QAC7D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACxE,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAA;QACjC,CAAC;QAED,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE;YAC/D,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,mBAAmB,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,EAAE;YAC3F,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACnC,OAAO,EAAE,kBAAkB,GAAG,cAAc;YAC5C,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAA;QACF,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YACxD,CAAC,CAAC,sBAAsB,GAAG,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,aAAa,GAAG;YACrG,CAAC,CAAC,IAAI,CAAA;QACR,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;QAExB,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IAED,MAAM,iBAAiB,GAAG,CAAC,QAAgB,EAAE,GAAW,EAAE,WAAmB,EAAiB,EAAE;QAC9F,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,EAAE,WAAW,CAAC,CAAA;QAC9C,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;YACpB,OAAO,IAAI,CAAA;QACb,CAAC;QACD,MAAM,WAAW,GAAG,YAAY,CAAC,OAAO,CAAC,CAAA;QACzC,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;YACxB,OAAO,IAAI,CAAA;QACb,CAAC;QAED,MAAM,MAAM,GAAG,GAAG,QAAQ,gBAAgB,WAAW,+DAA+D,CAAA;QACpH,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACxB,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YAClB,GAAG,CAAC,IAAI,CAAC,iEAAiE,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAA;QACxG,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IAED,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,CAAA;AAC1D,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,uBAAuB,EAAE,CAAA"}

package/build/types.local.d.ts

@@ -1,4 +1,3 @@
-export type CleanupFn = () => void | Promise<void>;
 /**
  * A connection-string variable whose server must answer a TCP connect for the gate to open.
  *

package/build/types.local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.local.d.ts","sourceRoot":"","sources":["../src/types.local.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;CACpB"}
+{"version":3,"file":"types.local.d.ts","sourceRoot":"","sources":["../src/types.local.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;CACpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/test-integration",
-  "version": "0.1.18-rc.32",
+  "version": "0.1.18-rc.33",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,8 +21,8 @@
     }
   },
   "dependencies": {
-    "@owlmeans/log": "^0.1.18-rc.1",
-    "@owlmeans/test": "^0.1.18-rc.34"
+    "@owlmeans/log": "^0.1.18-rc.2",
+    "@owlmeans/test": "^0.1.18-rc.35"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "^0.1.18-rc.6",

package/src/cleanup/types.ts

@@ -0,0 +1,18 @@
+export interface CleanupFn { (): void | Promise<void> }
+
+/** The opt-in teardown queue a suite's `tests/context.ts` fills and its `afterAll` drains. */
+export interface CleanupHelper {
+  /**
+   * Register a cleanup function that {@link CleanupHelper.runCleanups} will execute (LIFO).
+   * Use from `tests/context.ts` `setup()` to schedule teardown of resources
+   * that were provisioned for the suite (DB drop, key namespace flush,
+   * uploaded objects).
+   */
+  registerCleanup: (fn: CleanupFn) => void
+  /**
+   * Run all pending cleanup functions in reverse registration order.
+   * Errors are swallowed and logged as warnings so a failing cleanup
+   * cannot mask a test failure.
+   */
+  runCleanups: () => Promise<void>
+}

package/src/cleanup.ts

@@ -1,33 +1,35 @@
 import { logger } from '@owlmeans/log'
-import type { CleanupFn } from './types.local.js'
+import type { CleanupFn, CleanupHelper } from './cleanup/types.js'
 
 const log = logger('test-integration')
 
+// Process-wide on purpose: every spec file of a run registers into, and drains, the same queue.
 const queue: CleanupFn[] = []
 
-/**
- * Register a cleanup function that `runCleanups()` will execute (LIFO).
- * Use from `tests/context.ts` `setup()` to schedule teardown of resources
- * that were provisioned for the suite (DB drop, key namespace flush,
- * uploaded objects).
- */
-export const registerCleanup = (fn: CleanupFn): void => {
-  queue.push(fn)
-}
+export const createCleanupHelper = (): CleanupHelper => {
+  const registerCleanup = (fn: CleanupFn): void => {
+    queue.push(fn)
+  }
 
-/**
- * Run all pending cleanup functions in reverse registration order.
- * Errors are swallowed and logged as warnings so a failing cleanup
- * cannot mask a test failure.
- */
-export const runCleanups = async (): Promise<void> => {
-  while (queue.length > 0) {
-    const fn = queue.pop()
-    if (fn == null) continue
-    try {
-      await fn()
-    } catch (err) {
-      log.warn('Cleanup failed', err)
+  const runCleanups = async (): Promise<void> => {
+    while (queue.length > 0) {
+      const fn = queue.pop()
+      if (fn == null) continue
+      try {
+        await fn()
+      } catch (err) {
+        log.warn('Cleanup failed', err)
+      }
     }
   }
+
+  return { registerCleanup, runCleanups }
 }
+
+export const cleanupHelper = createCleanupHelper()
+
+/** @deprecated compat:factory-refactor — use `cleanupHelper.registerCleanup(…)` */
+export const registerCleanup = (fn: CleanupFn): void => cleanupHelper.registerCleanup(fn)
+
+/** @deprecated compat:factory-refactor — use `cleanupHelper.runCleanups()` */
+export const runCleanups = async (): Promise<void> => await cleanupHelper.runCleanups()

package/src/gates/types.ts

@@ -0,0 +1,18 @@
+import type { IntegrationGate, KubeEnv, MongoEnv, PostgresEnv, RedisEnv, S3Env, SmtpEnv } from '../types.js'
+
+/**
+ * The env gates of the integration suites: each reads the variables documented in `.env.example`
+ * and answers `{ skip, reason?, env }`, so a `tests/context.ts` decides whether to register the
+ * real service and a spec self-skips when it is missing.
+ */
+export interface GateHelper {
+  /** `MONGO_URL` set AND a host in it accepting a TCP connect; `MONGO_TEST_DB_PREFIX` optional. */
+  mongoGate: () => IntegrationGate<MongoEnv>
+  /** `REDIS_URL` set AND a host in it accepting a TCP connect; `REDIS_TEST_KEY_PREFIX` optional. */
+  redisGate: () => IntegrationGate<RedisEnv>
+  s3Gate: () => IntegrationGate<S3Env>
+  kubeGate: () => IntegrationGate<KubeEnv>
+  /** `POSTGRES_URL` set AND a host in it accepting a TCP connect; `POSTGRES_TEST_DB_PREFIX` optional. */
+  postgresGate: () => IntegrationGate<PostgresEnv>
+  smtpGate: () => IntegrationGate<SmtpEnv>
+}

package/src/gates.ts

@@ -1,51 +1,70 @@
-import { hasEnv, requireEnv } from '@owlmeans/test'
-import { unreachableReason } from './reachability.js'
+import { envHelper } from '@owlmeans/test'
+import { reachabilityUtils } from './reachability.js'
 import type { Reachable } from './types.local.js'
 import type { IntegrationGate, KubeEnv, MongoEnv, PostgresEnv, RedisEnv, S3Env, SmtpEnv } from './types.js'
+import type { GateHelper } from './gates/types.js'
 
-const collect = <E>(keys: (keyof E & string)[]): Partial<E> => {
-  const env: Record<string, string> = {}
-  for (const k of keys) {
-    if (hasEnv(k)) env[k] = process.env[k] as string
+export const createGateHelper = (): GateHelper => {
+  const collect = <E>(keys: (keyof E & string)[]): Partial<E> => {
+    const env: Record<string, string> = {}
+    for (const k of keys) {
+      if (envHelper.hasEnv(k)) env[k] = process.env[k] as string
+    }
+    return env as Partial<E>
   }
-  return env as Partial<E>
-}
 
-const toIntegrationGate = <E>(
-  required: (keyof E & string)[],
-  optional: (keyof E & string)[] = [],
-  reachable?: Reachable<E>
-): IntegrationGate<E> => {
-  const gate = requireEnv(required)
-  const env = collect<E>([...required, ...optional])
-  if (!('ok' in gate)) return { skip: true, reason: gate.reason, env }
-  if (reachable != null) {
-    const reason = unreachableReason(reachable.key, process.env[reachable.key] as string, reachable.defaultPort)
-    if (reason != null) return { skip: true, reason, env }
+  const toIntegrationGate = <E>(
+    required: (keyof E & string)[],
+    optional: (keyof E & string)[] = [],
+    reachable?: Reachable<E>
+  ): IntegrationGate<E> => {
+    const gate = envHelper.requireEnv(required)
+    const env = collect<E>([...required, ...optional])
+    if (!('ok' in gate)) return { skip: true, reason: gate.reason, env }
+    if (reachable != null) {
+      const reason = reachabilityUtils.unreachableReason(reachable.key, process.env[reachable.key] as string, reachable.defaultPort)
+      if (reason != null) return { skip: true, reason, env }
+    }
+    return { skip: false, env }
   }
-  return { skip: false, env }
-}
 
-export const mongoGate = (): IntegrationGate<MongoEnv> =>
-  toIntegrationGate<MongoEnv>(['MONGO_URL'], ['MONGO_TEST_DB_PREFIX'], { key: 'MONGO_URL', defaultPort: 27017 })
+  const mongoGate = (): IntegrationGate<MongoEnv> =>
+    toIntegrationGate<MongoEnv>(['MONGO_URL'], ['MONGO_TEST_DB_PREFIX'], { key: 'MONGO_URL', defaultPort: 27017 })
+
+  const redisGate = (): IntegrationGate<RedisEnv> =>
+    toIntegrationGate<RedisEnv>(['REDIS_URL'], ['REDIS_TEST_KEY_PREFIX'], { key: 'REDIS_URL', defaultPort: 6379 })
+
+  const s3Gate = (): IntegrationGate<S3Env> =>
+    toIntegrationGate<S3Env>(
+      ['S3_ENDPOINT', 'S3_KEY', 'S3_SECRET', 'S3_TEST_BUCKET'],
+      ['S3_REGION']
+    )
+
+  const kubeGate = (): IntegrationGate<KubeEnv> =>
+    toIntegrationGate<KubeEnv>(['KUBE_CONFIG', 'KUBE_TEST_OK'])
+
+  const postgresGate = (): IntegrationGate<PostgresEnv> =>
+    toIntegrationGate<PostgresEnv>(['POSTGRES_URL'], ['POSTGRES_TEST_DB_PREFIX'], { key: 'POSTGRES_URL', defaultPort: 5432 })
+
+  const smtpGate = (): IntegrationGate<SmtpEnv> =>
+    toIntegrationGate<SmtpEnv>(
+      ['SMTP_HOST', 'SMTP_USER', 'SMTP_PASSWORD', 'SMTP_FROM', 'SMTP_TEST_TO'],
+      ['SMTP_PORT', 'SMTP_SECURE']
+    )
+
+  return { mongoGate, redisGate, s3Gate, kubeGate, postgresGate, smtpGate }
+}
 
-export const redisGate = (): IntegrationGate<RedisEnv> =>
-  toIntegrationGate<RedisEnv>(['REDIS_URL'], ['REDIS_TEST_KEY_PREFIX'], { key: 'REDIS_URL', defaultPort: 6379 })
+export const gateHelper = createGateHelper()
 
-export const s3Gate = (): IntegrationGate<S3Env> =>
-  toIntegrationGate<S3Env>(
-    ['S3_ENDPOINT', 'S3_KEY', 'S3_SECRET', 'S3_TEST_BUCKET'],
-    ['S3_REGION']
-  )
+/** @deprecated compat:factory-refactor — use `gateHelper.mongoGate()` */
+export const mongoGate = (): IntegrationGate<MongoEnv> => gateHelper.mongoGate()
 
-export const kubeGate = (): IntegrationGate<KubeEnv> =>
-  toIntegrationGate<KubeEnv>(['KUBE_CONFIG', 'KUBE_TEST_OK'])
+/** @deprecated compat:factory-refactor — use `gateHelper.redisGate()` */
+export const redisGate = (): IntegrationGate<RedisEnv> => gateHelper.redisGate()
 
-export const postgresGate = (): IntegrationGate<PostgresEnv> =>
-  toIntegrationGate<PostgresEnv>(['POSTGRES_URL'], ['POSTGRES_TEST_DB_PREFIX'], { key: 'POSTGRES_URL', defaultPort: 5432 })
+/** @deprecated compat:factory-refactor — use `gateHelper.postgresGate()` */
+export const postgresGate = (): IntegrationGate<PostgresEnv> => gateHelper.postgresGate()
 
-export const smtpGate = (): IntegrationGate<SmtpEnv> =>
-  toIntegrationGate<SmtpEnv>(
-    ['SMTP_HOST', 'SMTP_USER', 'SMTP_PASSWORD', 'SMTP_FROM', 'SMTP_TEST_TO'],
-    ['SMTP_PORT', 'SMTP_SECURE']
-  )
+/** @deprecated compat:factory-refactor — use `gateHelper.smtpGate()` */
+export const smtpGate = (): IntegrationGate<SmtpEnv> => gateHelper.smtpGate()

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from './gates.js'
+export type * from './gates/types.js'
 export type * from './types.js'
 export * from './naming.js'
 export * from './cleanup.js'
+export type * from './cleanup/types.js'

package/src/reachability/types.ts

@@ -0,0 +1,27 @@
+import type { ProbeTarget } from '../types.js'
+
+/**
+ * Whether the server a connection string names answers at all — asked synchronously, because
+ * Bun decides `test` vs `test.skip` synchronously and every gate is read at module scope.
+ */
+export interface ReachabilityUtils {
+  /**
+   * Every `host:port` in the authority of a connection string, or `null` when the string names
+   * nothing a TCP connect can check — an SRV record, a unix socket, or a shape this cannot read.
+   * `null` leaves the gate exactly as the variable alone would have it.
+   */
+  parseTargets: (url: string, defaultPort: number) => ProbeTarget[] | null
+  /**
+   * `null` when at least one target accepts a TCP connection, otherwise the reason none did.
+   *
+   * A probe that cannot run at all also answers `null`: not knowing is not evidence the service is
+   * down, and the suite then behaves exactly as it did before probes existed.
+   */
+  probeTargets: (targets: ProbeTarget[]) => string | null
+  /**
+   * The skip reason for a populated connection-string variable whose server does not answer, or
+   * `null` when it answers or cannot be probed. Printed once per variable and address, so a closed
+   * gate is never mistaken for a suite that has nothing to run.
+   */
+  unreachableReason: (variable: string, url: string, defaultPort: number) => string | null
+}

package/src/reachability.ts

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process'
 import { logger } from '@owlmeans/log'
 import { CONNECT_TIMEOUT_MS, PROBE_SCRIPT, SPAWN_GRACE_MS } from './consts.local.js'
 import type { ProbeTarget } from './types.js'
+import type { ReachabilityUtils } from './reachability/types.js'
 
 const log = logger('test-integration')
 
@@ -15,91 +16,82 @@ const log = logger('test-integration')
  * asked — never a login — so no driver is needed here and no credential leaves the variable.
  */
 
+// Process-wide on purpose: every gate of a run shares one answer per address and one warning per reason.
 const answers = new Map<string, string | null>()
 const warned = new Set<string>()
 
-/**
- * Every `host:port` in the authority of a connection string, or `null` when the string names
- * nothing a TCP connect can check — an SRV record, a unix socket, or a shape this cannot read.
- * `null` leaves the gate exactly as the variable alone would have it.
- */
-export const parseTargets = (url: string, defaultPort: number): ProbeTarget[] | null => {
-  const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(url)
-  if (scheme == null || scheme[1].toLowerCase().endsWith('+srv')) {
-    return null
-  }
-  const rest = url.slice(scheme[0].length)
-  const end = rest.search(/[/?#]/)
-  const authority = end < 0 ? rest : rest.slice(0, end)
-  const hosts = authority.slice(authority.lastIndexOf('@') + 1)
-
-  const targets: ProbeTarget[] = []
-  for (const entry of hosts.split(',')) {
-    const match = /^(\[[^\]]+\]|[^:]*)(?::(\d+))?$/.exec(entry)
-    if (match == null) {
-      return null
-    }
-    let host: string
-    try {
-      host = decodeURIComponent(match[1]).replace(/^\[|\]$/g, '')
-    } catch {
-      return null
-    }
-    if (host === '' || host.includes('/')) {
+export const createReachabilityUtils = (): ReachabilityUtils => {
+  const parseTargets = (url: string, defaultPort: number): ProbeTarget[] | null => {
+    const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(url)
+    if (scheme == null || scheme[1].toLowerCase().endsWith('+srv')) {
       return null
     }
-    targets.push({ host, port: match[2] != null ? parseInt(match[2], 10) : defaultPort })
-  }
+    const rest = url.slice(scheme[0].length)
+    const end = rest.search(/[/?#]/)
+    const authority = end < 0 ? rest : rest.slice(0, end)
+    const hosts = authority.slice(authority.lastIndexOf('@') + 1)
 
-  return targets.length > 0 ? targets : null
-}
+    const targets: ProbeTarget[] = []
+    for (const entry of hosts.split(',')) {
+      const match = /^(\[[^\]]+\]|[^:]*)(?::(\d+))?$/.exec(entry)
+      if (match == null) {
+        return null
+      }
+      let host: string
+      try {
+        host = decodeURIComponent(match[1]).replace(/^\[|\]$/g, '')
+      } catch {
+        return null
+      }
+      if (host === '' || host.includes('/')) {
+        return null
+      }
+      targets.push({ host, port: match[2] != null ? parseInt(match[2], 10) : defaultPort })
+    }
 
-/**
- * `null` when at least one target accepts a TCP connection, otherwise the reason none did.
- *
- * A probe that cannot run at all also answers `null`: not knowing is not evidence the service is
- * down, and the suite then behaves exactly as it did before probes existed.
- */
-export const probeTargets = (targets: ProbeTarget[]): string | null => {
-  const key = targets.map(({ host, port }) => `${host}:${port}`).join(',')
-  if (answers.has(key)) {
-    return answers.get(key) ?? null
+    return targets.length > 0 ? targets : null
   }
 
-  const result = spawnSync(process.execPath, ['-e', PROBE_SCRIPT], {
-    env: { ...process.env, OWLMEANS_TEST_PROBE: JSON.stringify([targets, CONNECT_TIMEOUT_MS]) },
-    stdio: ['ignore', 'pipe', 'ignore'],
-    timeout: CONNECT_TIMEOUT_MS + SPAWN_GRACE_MS,
-    encoding: 'utf8',
-  })
-  const answer = result.error == null && result.status === 1
-    ? `nothing answers at ${key} (${result.stdout.trim() !== '' ? result.stdout.trim() : 'unreachable'})`
-    : null
-  answers.set(key, answer)
+  const probeTargets = (targets: ProbeTarget[]): string | null => {
+    const key = targets.map(({ host, port }) => `${host}:${port}`).join(',')
+    if (answers.has(key)) {
+      return answers.get(key) ?? null
+    }
 
-  return answer
-}
+    const result = spawnSync(process.execPath, ['-e', PROBE_SCRIPT], {
+      env: { ...process.env, OWLMEANS_TEST_PROBE: JSON.stringify([targets, CONNECT_TIMEOUT_MS]) },
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: CONNECT_TIMEOUT_MS + SPAWN_GRACE_MS,
+      encoding: 'utf8',
+    })
+    const answer = result.error == null && result.status === 1
+      ? `nothing answers at ${key} (${result.stdout.trim() !== '' ? result.stdout.trim() : 'unreachable'})`
+      : null
+    answers.set(key, answer)
 
-/**
- * The skip reason for a populated connection-string variable whose server does not answer, or
- * `null` when it answers or cannot be probed. Printed once per variable and address, so a closed
- * gate is never mistaken for a suite that has nothing to run.
- */
-export const unreachableReason = (variable: string, url: string, defaultPort: number): string | null => {
-  const targets = parseTargets(url, defaultPort)
-  if (targets == null) {
-    return null
-  }
-  const unreachable = probeTargets(targets)
-  if (unreachable == null) {
-    return null
+    return answer
   }
 
-  const reason = `${variable} is set, but ${unreachable} — start the service (or its port-forward) to run these specs`
-  if (!warned.has(reason)) {
-    warned.add(reason)
-    log.warn('Skipping integration specs: a configured service is unreachable', { variable, unreachable })
+  const unreachableReason = (variable: string, url: string, defaultPort: number): string | null => {
+    const targets = parseTargets(url, defaultPort)
+    if (targets == null) {
+      return null
+    }
+    const unreachable = probeTargets(targets)
+    if (unreachable == null) {
+      return null
+    }
+
+    const reason = `${variable} is set, but ${unreachable} — start the service (or its port-forward) to run these specs`
+    if (!warned.has(reason)) {
+      warned.add(reason)
+      log.warn('Skipping integration specs: a configured service is unreachable', { variable, unreachable })
+    }
+
+    return reason
   }
 
-  return reason
+  return { parseTargets, probeTargets, unreachableReason }
 }
+
+export const reachabilityUtils = createReachabilityUtils()

package/src/types.local.ts

@@ -1,5 +1,3 @@
-export type CleanupFn = () => void | Promise<void>
-
 /**
  * A connection-string variable whose server must answer a TCP connect for the gate to open.
  *