@geonosis/testbed 1.0.0

package/dist/chunk-ULJUJOSR.js

@@ -0,0 +1,51 @@
+// src/workerd/strict.ts
+import { spawn } from "child_process";
+import { mkdtempSync, readFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+var DEFAULT_ARGS = ["vitest", "run", "--reporter=default", "--reporter=json"];
+var verdictOf = (report) => {
+  if (report === null) {
+    return {
+      ok: false,
+      why: "the runner wrote no JSON report \u2014 a crash before the reporter is not a pass"
+    };
+  }
+  const failed = report.numFailedTests ?? 0;
+  if (report.success !== true) {
+    const named = failed > 0 ? `, naming ${failed} failing test(s)` : " and named no failing test";
+    return { ok: false, why: `the runner reported success=${String(report.success)}${named}` };
+  }
+  return failed > 0 ? { ok: false, why: `${failed} test(s) failed` } : { ok: true, why: "" };
+};
+var readReport = (path) => {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+};
+var runStrict = async (options = {}) => {
+  const command = options.command ?? "npx";
+  if (command === "") throw new Error("runStrict needs a command to run");
+  const own = options.reportPath === void 0;
+  const reportPath = options.reportPath ?? join(mkdtempSync(join(tmpdir(), "geonosis-strict-")), "report.json");
+  const reportArg = options.reportArg ?? ((path) => `--outputFile=${path}`);
+  const args = [...options.args ?? DEFAULT_ARGS, reportArg(reportPath)];
+  try {
+    const code = await new Promise((done, fail) => {
+      const child = spawn(command, args, { stdio: options.stdio ?? "inherit" });
+      child.on("error", fail);
+      child.on("exit", (exited) => done(exited ?? 0));
+    });
+    return { code, reportPath, verdict: verdictOf(readReport(reportPath)) };
+  } finally {
+    if (own) rmSync(dirname(reportPath), { force: true, recursive: true });
+  }
+};
+
+export {
+  verdictOf,
+  readReport,
+  runStrict
+};

package/dist/chunk-UZPJWPL3.js

@@ -0,0 +1,59 @@
+// src/database-name.ts
+var MAX_IDENTIFIER_BYTES = 63;
+var createDatabaseNamer = (derive) => {
+  const issued = /* @__PURE__ */ new Map();
+  return (key) => {
+    const name = derive(key);
+    if (name === "") throw new Error(`the database name for "${key}" is empty`);
+    const bytes = Buffer.byteLength(name);
+    if (bytes > MAX_IDENTIFIER_BYTES) {
+      throw new Error(
+        `the database name for "${key}" is ${bytes} bytes; Postgres truncates at ${MAX_IDENTIFIER_BYTES}, so a longer one is a collision waiting to be silent`
+      );
+    }
+    const taken = issued.get(name);
+    if (taken !== void 0 && taken !== key) {
+      throw new Error(
+        `"${key}" and "${taken}" both derive the database "${name}" \u2014 they would collide, and each one's reset would empty the other's rows`
+      );
+    }
+    issued.set(name, key);
+    return name;
+  };
+};
+
+// src/fixtures.ts
+import { realpathSync } from "fs";
+import { isAbsolute, join, resolve, sep } from "path";
+var fixturesOnly = (root) => {
+  if (root === "") throw new Error('fixturesOnly needs a fixtures directory; it was given ""');
+  const base = realOf(resolve(root));
+  return (...segments) => {
+    const absolute = segments.find((segment) => isAbsolute(segment));
+    if (absolute !== void 0) {
+      throw new Error(
+        `"${absolute}" is an absolute path, and a fixture is named relative to the fixtures directory ${base}`
+      );
+    }
+    const asked = resolve(join(base, ...segments));
+    const real = realOf(asked);
+    if (real !== base && !real.startsWith(base + sep)) {
+      throw new Error(
+        `${segments.join("/")} resolves to ${real}, which is outside the fixtures directory ${base}`
+      );
+    }
+    return real;
+  };
+};
+var realOf = (path) => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+};
+
+export {
+  createDatabaseNamer,
+  fixturesOnly
+};

package/dist/cli.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import {
+  runStrict
+} from "./chunk-ULJUJOSR.js";
+
+// src/cli.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+
+// src/ci/db-matrix.ts
+var SAYS = {
+  boolean: "true or false",
+  string: "a string",
+  strings: "an array of strings"
+};
+var SHAPE = {
+  command: { kind: "string", required: true },
+  connectionEnv: { kind: "string", required: true },
+  connectionString: { kind: "string", required: true },
+  embedded: { kind: "boolean", required: false },
+  image: { kind: "string", required: false },
+  majors: { kind: "strings", required: true },
+  name: { kind: "string", required: true },
+  runsOn: { kind: "string", required: false },
+  setup: { kind: "strings", required: false }
+};
+var holds = (kind, value) => {
+  if (kind === "strings")
+    return Array.isArray(value) && value.every((one) => typeof one === "string");
+  return typeof value === (kind === "boolean" ? "boolean" : "string");
+};
+var said = (value) => value === void 0 ? "undefined" : JSON.stringify(value);
+var problemsIn = (block) => [
+  ...Object.entries(SHAPE).flatMap(([key, want]) => {
+    const value = block[key];
+    if (value === void 0)
+      return want.required ? [`${key} is missing \u2014 it takes ${SAYS[want.kind]}`] : [];
+    return holds(want.kind, value) ? [] : [`${key} is ${said(value)} \u2014 it takes ${SAYS[want.kind]}`];
+  }),
+  ...Object.keys(block).filter((key) => SHAPE[key] === void 0).map(
+    (key) => `${key} is not a key of \`testbed.matrix\`, which takes ${Object.keys(SHAPE).join(", ")}`
+  )
+];
+var readDbMatrix = (value, where) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `${where}: \`testbed.matrix\` is ${said(value)}, and a database matrix is a block of settings`
+    );
+  }
+  const block = value;
+  const problems = problemsIn(block);
+  if (problems.length > 0) {
+    throw new Error([`${where}: \`testbed.matrix\` cannot be read \u2014`, ...problems].join("\n  "));
+  }
+  return block;
+};
+var JOB_NAME = /^[A-Za-z][\w-]*$/;
+var DEFAULT_IMAGE = "postgres";
+var DEFAULT_RUNS_ON = "ubuntu-latest";
+var steps = (setup, command, env) => [
+  "      - uses: actions/checkout@v4",
+  "",
+  ...setup.flatMap((step) => [`      - run: ${step}`, ""]),
+  "      - name: The data layer",
+  ...env === void 0 ? [] : ["        env:", `          ${env[0]}: ${env[1]}`],
+  `        run: ${command}`
+];
+var renderDbMatrix = (matrix2) => {
+  if (!JOB_NAME.test(matrix2.name)) {
+    throw new Error(
+      `"${matrix2.name}" is not usable as a job name; it becomes "<name>-embedded" and "<name>-postgres"`
+    );
+  }
+  if (matrix2.command === "") throw new Error("a database matrix needs a command to run");
+  const embedded = matrix2.embedded ?? true;
+  const majors = matrix2.majors;
+  if (!embedded && majors.length === 0) {
+    throw new Error("a database matrix with no embedded leg and no majors has no legs to run");
+  }
+  if (majors.length > 0 && matrix2.connectionString === "") {
+    throw new Error(
+      `the majors ${majors.join(", ")} have no connection string to be reached by, so every one of them would run the embedded cell under a container's name`
+    );
+  }
+  const runsOn = matrix2.runsOn ?? DEFAULT_RUNS_ON;
+  const image = matrix2.image ?? DEFAULT_IMAGE;
+  const setup = matrix2.setup ?? [];
+  const embeddedJob = [
+    `  ${matrix2.name}-embedded:`,
+    `    runs-on: ${runsOn}`,
+    "    steps:",
+    ...steps(setup, matrix2.command)
+  ];
+  const postgresJob = [
+    `  ${matrix2.name}-postgres:`,
+    `    runs-on: ${runsOn}`,
+    "    strategy:",
+    // One major failing must not hide whether the other passes — that is the question a matrix asks.
+    "      fail-fast: false",
+    "      matrix:",
+    `        postgres: [${majors.map((major) => `'${major}'`).join(", ")}]`,
+    "    services:",
+    "      cell:",
+    `        image: ${image}:\${{ matrix.postgres }}`,
+    "        env:",
+    "          POSTGRES_PASSWORD: postgres",
+    "          POSTGRES_DB: postgres",
+    "        ports: ['5432:5432']",
+    // Without this the first connection races the container: the job starts, the client connects
+    // before Postgres is accepting, and the suite fails for a reason that is not in the code.
+    "        options: >-",
+    '          --health-cmd "pg_isready -U postgres"',
+    "          --health-interval 5s",
+    "          --health-timeout 5s",
+    "          --health-retries 20",
+    "    steps:",
+    ...steps(setup, matrix2.command, [matrix2.connectionEnv, matrix2.connectionString])
+  ];
+  return [
+    `name: ${matrix2.name}`,
+    "",
+    "on:",
+    "  push:",
+    "    branches: [main]",
+    "  pull_request:",
+    "    branches: [main]",
+    "",
+    "jobs:",
+    ...embedded ? [...embeddedJob, ""] : [],
+    ...majors.length > 0 ? postgresJob : [],
+    ""
+  ].join("\n");
+};
+
+// src/cli.ts
+var CONFIG = "geonosis.json";
+var flag = (argv, name) => {
+  const at = argv.indexOf(`--${name}`);
+  return at < 0 ? void 0 : argv[at + 1];
+};
+var matrixOf = (argv) => {
+  const at = resolve(flag(argv, "config") ?? CONFIG);
+  if (!existsSync(at)) throw new Error(`no ${CONFIG} at ${at}`);
+  const config = JSON.parse(readFileSync(at, "utf8"));
+  const matrix2 = config.testbed?.matrix;
+  if (matrix2 === void 0) {
+    throw new Error(`${at} has no \`testbed.matrix\` \u2014 there is nothing to render a workflow from`);
+  }
+  return readDbMatrix(matrix2, at);
+};
+var matrix = (argv) => {
+  const rendered = renderDbMatrix(matrixOf(argv));
+  const out = flag(argv, "out");
+  if (out === void 0) {
+    process.stdout.write(rendered);
+    return 0;
+  }
+  mkdirSync(dirname(resolve(out)), { recursive: true });
+  writeFileSync(resolve(out), rendered);
+  return 0;
+};
+var strict = async (argv) => {
+  const at = argv.indexOf("--");
+  const passthrough = at < 0 ? [] : argv.slice(at + 1);
+  const command = flag(argv, "command");
+  const { code, verdict } = await runStrict({
+    ...command === void 0 ? {} : { command },
+    args: command === void 0 ? ["vitest", "run", "--reporter=default", "--reporter=json", ...passthrough] : passthrough
+  });
+  if (!verdict.ok) {
+    process.stderr.write(`
+geonosis-testbed strict: ${verdict.why} (the runner exited ${code})
+`);
+    return 1;
+  }
+  return code;
+};
+var USAGE = `geonosis-testbed <command>
+
+  matrix [--config geonosis.json] [--out path]
+      Render the database matrix workflow from \`testbed.matrix\`.
+
+  strict [--command bin] [-- ...args]
+      Run a test runner and judge its JSON report, not its exit code.
+`;
+var main = async (argv) => {
+  const [command] = argv;
+  if (command === "matrix") return matrix(argv.slice(1));
+  if (command === "strict") return strict(argv.slice(1));
+  process.stderr.write(command === void 0 ? USAGE : `unknown command "${command}"
+
+${USAGE}`);
+  return 2;
+};
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 2;
+});

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { T as TestbedAdapter, C as ConformanceReport, a as TestbedConfig, b as Testbed } from './types-D-uHas5h.js';
+export { B as BootContext, c as BootResult, d as ConformanceCheck, D as DatabaseLifetime, e as DatabaseSpec, N as NetworkPolicy } from './types-D-uHas5h.js';
+
+/**
+ * How a caller lets the conformance suite see state change. The kit cannot know how to write a row
+ * through someone else's database handle, and without writing one a no-op `restore()` is
+ * indistinguishable from a real one — so that check is SKIPPED, by name, when no probe is given.
+ */
+type ConformanceProbe<Db> = {
+    read: (db: Db) => Promise<unknown> | unknown;
+    write: (db: Db) => Promise<void> | void;
+};
+type ConformanceOptions<Db> = {
+    probe?: ConformanceProbe<Db>;
+    /**
+     * How long a `waitFor` gets before the suite calls it hung. Set it ABOVE the adapter's own
+     * deadline: a correct rejection that arrives later is reported here as a hang.
+     */
+    waitForMs?: number;
+};
+/**
+ * The contract every testbed adapter holds, run against the adapter itself.
+ *
+ * Exported because a consumer writes adapters this repo never sees, and an adapter that has not
+ * been through this is a claim. Each check is a property something in one of the two harnesses
+ * really depends on — teardown fires from `afterAll` and from SIGTERM, so it is called twice; a
+ * restore before any snapshot returns whatever the template database happened to hold.
+ *
+ * It never throws for the adapter's sake: a broken adapter is a failed check with its own message
+ * in `detail`, because a conformance run that dies tells the reader less than one that reports.
+ */
+declare const runAdapterConformance: <Db>(adapter: TestbedAdapter<Db>, options?: ConformanceOptions<Db>) => Promise<ConformanceReport>;
+
+/**
+ * A database name, derived by the repo and then checked.
+ *
+ * The check that earns its keep is the last one. `sha1(description).slice(0, 12)` — the derivation
+ * both this kit's `medusa-built` adapter and the repo it came from use — is 48 bits, and two suites
+ * that collide do not fail: they share a database, and whichever one resets first empties the
+ * other's rows, with both green. Neither source repo notices.
+ */
+declare const createDatabaseNamer: (derive: (key: string) => string) => ((key: string) => string);
+
+/**
+ * A testbed is the arrangement around one engine call: where fixtures live, what a database is
+ * called and how long it lives, what the network may reach, and which adapter boots it.
+ *
+ * Everything it can refuse, it refuses HERE rather than at the first boot — a half-declared
+ * adapter or an allow-list of nothing is the kind of configuration that reads as working and
+ * gates nothing, which is the failure this kit exists to catch.
+ */
+declare const defineTestbed: <Db>(config: TestbedConfig<Db>) => Testbed<Db>;
+
+/**
+ * The fixtures law as a function: a resolver that returns a path inside `root` or throws.
+ *
+ * during.day's §4.3 — "a test reads and writes ONLY `apps/web/__tests__/__fixtures__/`" — exists
+ * because the directory next door in that repo holds real customers' purchase orders. Its own
+ * guard (`resolveWithinRoot`) compares strings, which two shapes get past: a sibling directory
+ * whose name merely starts with the root, and a symlink whose every character is inside it. Both
+ * are resolved here.
+ */
+declare const fixturesOnly: (root: string) => ((...segments: string[]) => string);
+
+export { type ConformanceOptions, type ConformanceProbe, ConformanceReport, Testbed, TestbedAdapter, TestbedConfig, createDatabaseNamer, defineTestbed, fixturesOnly, runAdapterConformance };

package/dist/index.js

@@ -0,0 +1,235 @@
+import {
+  createDatabaseNamer,
+  fixturesOnly
+} from "./chunk-UZPJWPL3.js";
+
+// src/conformance.ts
+var BOOT = "boot returns a handle";
+var REBOOT = "boots again after teardown";
+var RESTORE_REFUSED = "restore before a snapshot is refused";
+var RESTORE_ROUND_TRIP = "restore returns the snapshot";
+var TEARDOWN = "teardown is idempotent";
+var WAIT_KINDS = "waitFor declares the kinds it knows";
+var WAIT_REFUSES = "waitFor refuses a kind it does not know";
+var WAIT_REJECTS = "waitFor rejects when it never comes true";
+var WAIT_RESOLVES = "waitFor resolves when it comes true";
+var UNKNOWN_KIND = "a-kind-no-adapter-declares";
+var EVERY_CHECK = [
+  BOOT,
+  RESTORE_REFUSED,
+  RESTORE_ROUND_TRIP,
+  WAIT_KINDS,
+  WAIT_REJECTS,
+  WAIT_RESOLVES,
+  WAIT_REFUSES,
+  TEARDOWN,
+  REBOOT
+];
+var detailOf = (error) => error instanceof Error ? error.message : String(error);
+var runAdapterConformance = async (adapter, options = {}) => {
+  const checks = [];
+  const skipped = [];
+  const waitForMs = options.waitForMs ?? 500;
+  const ran = (name, ok, detail = "") => {
+    checks.push({ detail, name, ok });
+  };
+  const attempt = async (name, body) => {
+    try {
+      const detail = await body();
+      ran(name, detail === "", detail);
+    } catch (error) {
+      ran(name, false, detailOf(error));
+    }
+  };
+  const ctx = Object.freeze({
+    databaseName: "geonosis_conformance",
+    fixtures: "",
+    network: "none"
+  });
+  let booted;
+  try {
+    booted = await adapter.boot(ctx);
+    ran(
+      BOOT,
+      booted.db !== void 0,
+      booted.db === void 0 ? "boot resolved with db: undefined" : ""
+    );
+  } catch (error) {
+    ran(BOOT, false, detailOf(error));
+    return report(
+      adapter.id,
+      checks,
+      EVERY_CHECK.filter((name) => name !== BOOT)
+    );
+  }
+  const handle = booted;
+  if (adapter.restore && adapter.snapshot) {
+    const { restore, snapshot } = adapter;
+    await attempt(RESTORE_REFUSED, async () => {
+      try {
+        await restore();
+      } catch {
+        return "";
+      }
+      return "restore() resolved with no snapshot taken \u2014 it restored something nobody asked for";
+    });
+    const probe = options.probe;
+    if (probe) {
+      await attempt(RESTORE_ROUND_TRIP, async () => {
+        const before = await probe.read(handle.db);
+        await snapshot();
+        await probe.write(handle.db);
+        const after = await probe.read(handle.db);
+        if (same(before, after)) return "the probe wrote nothing its read could see";
+        await restore();
+        const restored = await probe.read(handle.db);
+        return same(before, restored) ? "" : `after restore the probe read ${json(restored)}, not the snapshot's ${json(before)}`;
+      });
+    } else {
+      skipped.push(RESTORE_ROUND_TRIP);
+    }
+  } else {
+    skipped.push(RESTORE_REFUSED, RESTORE_ROUND_TRIP);
+  }
+  if (adapter.waitFor) {
+    const { waitFor } = adapter;
+    const kinds = adapter.waitKinds ?? [];
+    const kind = kinds[0];
+    ran(
+      WAIT_KINDS,
+      kind !== void 0,
+      kind === void 0 ? "waitFor() is there and waitKinds names nothing to ask it for" : ""
+    );
+    if (kind === void 0) {
+      skipped.push(WAIT_REJECTS, WAIT_RESOLVES, WAIT_REFUSES);
+    } else {
+      await attempt(WAIT_REJECTS, async () => {
+        const settled = await race(
+          waitFor(kind, () => false),
+          waitForMs
+        );
+        if (settled === "timeout") {
+          return `waitFor did not settle within ${waitForMs}ms \u2014 either it hangs, or its own deadline is longer than this suite's waitForMs`;
+        }
+        return settled === "rejected" ? "" : "waitFor resolved for a predicate that is never true";
+      });
+      await attempt(WAIT_RESOLVES, async () => {
+        let seen = 0;
+        const settled = await race(
+          waitFor(kind, () => {
+            seen += 1;
+            return seen > 1;
+          }),
+          waitForMs
+        );
+        if (settled === "timeout") return `waitFor did not settle within ${waitForMs}ms`;
+        return settled === "resolved" ? "" : "waitFor rejected for a predicate that came true";
+      });
+      await attempt(WAIT_REFUSES, async () => {
+        const settled = await race(
+          waitFor(UNKNOWN_KIND, () => true),
+          waitForMs
+        );
+        if (settled === "timeout") return `waitFor hung on "${UNKNOWN_KIND}" for ${waitForMs}ms`;
+        return settled === "rejected" ? "" : `waitFor accepted "${UNKNOWN_KIND}", a kind it never declared`;
+      });
+    }
+  } else if ((adapter.waitKinds ?? []).length > 0) {
+    ran(WAIT_KINDS, false, "waitKinds names kinds and there is no waitFor() to ask");
+    skipped.push(WAIT_REJECTS, WAIT_RESOLVES, WAIT_REFUSES);
+  } else {
+    skipped.push(WAIT_KINDS, WAIT_REJECTS, WAIT_RESOLVES, WAIT_REFUSES);
+  }
+  await attempt(TEARDOWN, async () => {
+    await handle.teardown();
+    await handle.teardown();
+    return "";
+  });
+  await attempt(REBOOT, async () => {
+    const again = await adapter.boot(ctx);
+    await again.teardown();
+    return "";
+  });
+  return report(adapter.id, checks, skipped);
+};
+var report = (adapterId, checks, skipped) => ({
+  adapterId,
+  checks,
+  passed: checks.every((entry) => entry.ok),
+  skipped: [...skipped]
+});
+var json = (value) => JSON.stringify(value) ?? String(value);
+var same = (left, right) => json(left) === json(right);
+var race = async (promise, ms) => {
+  let timer;
+  const timeout = new Promise((done) => {
+    timer = setTimeout(() => done("timeout"), ms);
+  });
+  try {
+    return await Promise.race([
+      promise.then(
+        () => "resolved",
+        () => "rejected"
+      ),
+      timeout
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+// src/define.ts
+var LIFETIMES = ["file", "run", "suite"];
+var defineTestbed = (config) => {
+  const { adapter, database, fixtures, network } = config;
+  if (adapter.id === "") throw new Error("a testbed adapter needs an id; every diagnostic names it");
+  if (typeof adapter.boot !== "function") {
+    throw new TypeError(`the adapter "${adapter.id}" has no boot()`);
+  }
+  if (Boolean(adapter.snapshot) !== Boolean(adapter.restore)) {
+    throw new Error(
+      `the adapter "${adapter.id}" declares ${adapter.snapshot ? "snapshot" : "restore"} without ${adapter.snapshot ? "restore" : "snapshot"} \u2014 half of per-test isolation is not isolation`
+    );
+  }
+  const kinds = adapter.waitKinds ?? [];
+  if (adapter.waitFor && kinds.length === 0) {
+    throw new Error(
+      `the adapter "${adapter.id}" has waitFor() but no waitKinds \u2014 a caller cannot ask for a kind nobody named`
+    );
+  }
+  if (!adapter.waitFor && kinds.length > 0) {
+    throw new Error(`the adapter "${adapter.id}" declares waitKinds but has no waitFor() to call`);
+  }
+  if (!LIFETIMES.includes(database.per)) {
+    throw new Error(
+      `a database's "per" is one of ${LIFETIMES.join(", ")}; it was ${JSON.stringify(database.per)}`
+    );
+  }
+  if (typeof network !== "string" && network.allow.length === 0) {
+    throw new Error('an allow list of nothing is `network: "none"` spelt so it reads as permission');
+  }
+  const fixture = fixturesOnly(fixtures);
+  const root = fixture();
+  const databaseNameFor = createDatabaseNamer(database.name);
+  return {
+    adapterId: adapter.id,
+    allowsHost: (host) => typeof network !== "string" && network.allow.includes(host),
+    boot: (key) => adapter.boot(
+      Object.freeze({
+        databaseName: databaseNameFor(key),
+        fixtures: root,
+        network: frozen(network)
+      })
+    ),
+    databaseNameFor,
+    fixture,
+    per: database.per
+  };
+};
+var frozen = (network) => typeof network === "string" ? network : Object.freeze({ allow: Object.freeze([...network.allow]) });
+export {
+  createDatabaseNamer,
+  defineTestbed,
+  fixturesOnly,
+  runAdapterConformance
+};

package/dist/medusa-built/index.d.ts

@@ -0,0 +1,82 @@
+import { T as TestbedAdapter } from '../types-D-uHas5h.js';
+
+/**
+ * What `medusaIntegrationTestRunner` hands a suite, narrowed to what this adapter touches. Typed
+ * structurally rather than imported: `@medusajs/test-utils` is a PEER — a repo that runs Medusa
+ * already has it, and a repo that does not must not gain it by installing a testbed.
+ */
+type MedusaSuiteLike = {
+    dbConfig: {
+        clientUrl: string;
+        dbName: string;
+        schema: string;
+    };
+    dbConnection: unknown;
+    dbUtils: {
+        restore: (options?: {
+            templateName?: string;
+        }) => Promise<void>;
+        snapshot: (options?: {
+            templateName?: string;
+        }) => Promise<void>;
+    };
+    getContainer: () => unknown;
+    utils: {
+        waitWorkflowExecutions: () => Promise<void>;
+    };
+};
+type MedusaRunnerLike = (config: {
+    cwd?: string;
+    env?: Record<string, string>;
+    moduleName?: string;
+    testSuite: (options: MedusaSuiteLike) => void;
+}) => void;
+type MedusaIntegrationTestOptions = {
+    /** Where the app is built. Medusa's own default, and dielime's. */
+    builtDir?: string;
+    /** dielime's `sha1(description).slice(0, 12)` unless a repo names its databases another way. */
+    databaseName?: (description: string) => string;
+    /** The runner's own `describe`; the engine does not name the suite it registers. */
+    describe: (name: string, body: () => void) => void;
+    /**
+     * Which environment variables carry the connection. Medusa DEFAULTS every one of them, so an
+     * unset variable is not an error — it is a silent connection to whatever is on 5432.
+     */
+    connectionEnv?: readonly string[];
+    env?: Record<string, string>;
+    /** Optional: dielime's suites build their world through the booted app and have no fixtures. */
+    fixtures?: string;
+    /** `false` when a repo checks NODE_ENV itself. */
+    nodeEnv?: false | string;
+    requireBuilt?: boolean;
+    root: string;
+    runner: MedusaRunnerLike;
+    waitForMs?: number;
+};
+type MedusaIntegrationTest = {
+    adapterFor: (suite: MedusaSuiteLike) => TestbedAdapter<MedusaSuiteLike>;
+    /** Present only when the harness was given a fixtures directory to be contained by. */
+    fixture?: (...segments: string[]) => string;
+    runIntegrationTest: (description: string, suite: (options: MedusaSuiteLike) => void) => void;
+};
+/**
+ * dielime's 26-line `runIntegrationTest`, generalised — plus the four refusals its comment
+ * describes and its code does not make.
+ *
+ * The engine is injected, never imported: `medusaIntegrationTestRunner` boots a real Medusa app
+ * against a real Postgres, and a package that reached for it could not be installed by a repo on
+ * another runtime, nor tested without a database.
+ */
+declare const createMedusaIntegrationTest: (options: MedusaIntegrationTestOptions) => MedusaIntegrationTest;
+/**
+ * The suite options as a testbed adapter, so `runAdapterConformance` can judge them and so a suite
+ * can wait for the engine through the same call every other adapter answers.
+ *
+ * `boot` attaches rather than boots: the runner owns the application's lifecycle — it creates the
+ * database, migrates, snapshots to a TEMPLATE and restores from it before every test. What is
+ * missing from what it hands the suite is a guard on `restore`, and a way to wait that a test can
+ * reach before its assertion instead of after it.
+ */
+declare const medusaBuiltAdapter: (suite: MedusaSuiteLike, waitForMs?: number) => TestbedAdapter<MedusaSuiteLike>;
+
+export { type MedusaIntegrationTest, type MedusaIntegrationTestOptions, type MedusaRunnerLike, type MedusaSuiteLike, createMedusaIntegrationTest, medusaBuiltAdapter };