@geekmidas/cli 10.0.0-alpha.6 → 10.0.0-alpha.60

package/dist/ready-CIHpnUc5.mjs

@@ -0,0 +1,760 @@
+import { i as ConstructGenerator, t as discover } from "./discover-FrYvzkeC.mjs";
+import { n as EndpointGenerator, r as runtimeFor, t as OpenApiTsGenerator } from "./OpenApiTsGenerator-CvVr1Ilz.mjs";
+import { n as DEFAULT_CACHE, t as readFakes } from "./fakes-C9RiT6XG.mjs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { canonicalId, kebabCase, provideKey, serviceKey } from "@geekmidas/manifest";
+import { pathToFileURL } from "node:url";
+import { Subscriber } from "@geekmidas/constructs/subscribers";
+import { EnvironmentParser } from "@geekmidas/envkit";
+import { serviceContext } from "@geekmidas/services";
+//#region src/generators/drivers.ts
+/**
+* Driver registration for generated entry points.
+*
+* A construct declares that it needs object storage and is handed one URL; the
+* scheme in that URL picks the driver that builds the client. Which drivers
+* exist is therefore the *entry point's* decision, not the construct's and not
+* the application's — an app that never talks to S3 should never resolve the AWS
+* SDK, and application code that registers a driver has named a provider in the
+* one layer this design keeps provider-free.
+*
+* So the generated entries register: `gkm dev`'s server for local development,
+* and each Lambda handler for its own target. Registration is an explicit call
+* rather than an import side effect, because a side-effecting module is exactly
+* what a bundler is entitled to drop.
+*/
+/** The `s3://` driver, which serves MinIO locally and S3 deployed. */
+const S3 = {
+	imports: `import { registerStorageDriver } from '@geekmidas/storage';\nimport { s3Driver } from '@geekmidas/storage/aws';`,
+	setup: "registerStorageDriver(s3Driver);"
+};
+const NONE = {
+	imports: "",
+	setup: ""
+};
+/**
+* The cache driver for a backend — exactly one, never all three.
+*
+* Keyed off the *backend* rather than off a dependency, because unlike storage
+* the backend already says which driver is right: a project caching in Postgres
+* resolves `pg` and never `ioredis`, and one caching in Upstash resolves
+* neither. That is the whole reason the drivers live behind separate subpaths.
+*
+* Both HTTP schemes are registered for Upstash, because the local proxy speaks
+* `http://` and Upstash speaks `https://`, and an entry that registered one
+* would work in exactly one of the two places.
+*/
+const CACHE_DRIVERS = {
+	upstash: {
+		imports: `import { registerCacheDriver } from '@geekmidas/cache';\nimport { upstashCacheDriver, upstashInsecureCacheDriver } from '@geekmidas/cache/upstash';`,
+		setup: "registerCacheDriver(upstashCacheDriver);\nregisterCacheDriver(upstashInsecureCacheDriver);"
+	},
+	elasticache: {
+		imports: `import { registerCacheDriver } from '@geekmidas/cache';\nimport { redisCacheDriver, redissCacheDriver } from '@geekmidas/cache/redis';`,
+		setup: "registerCacheDriver(redisCacheDriver);\nregisterCacheDriver(redissCacheDriver);"
+	},
+	db: {
+		imports: `import { registerCacheDriver } from '@geekmidas/cache';\nimport { postgresCacheDriver } from '@geekmidas/cache/postgres';`,
+		setup: "registerCacheDriver(postgresCacheDriver);"
+	}
+};
+/**
+* Everything a generated entry should register: object storage, and the cache.
+*
+* Merged here rather than threaded separately, because a generated file has one
+* import block and one setup block whatever fills them.
+*/
+function driversFor(options) {
+	const backends = options.cache === false || options.cache === void 0 ? [] : typeof options.cache === "string" ? [options.cache] : options.cache;
+	const parts = [storageDriversFor(options.appRoot), ...[...new Set(backends)].map((backend) => CACHE_DRIVERS[backend] ?? CACHE_DRIVERS[DEFAULT_CACHE.aws])].filter((part) => part.imports || part.setup);
+	if (parts.length === 0) return NONE;
+	return {
+		imports: parts.map((part) => part.imports).join("\n"),
+		setup: parts.map((part) => part.setup).join("\n")
+	};
+}
+/**
+* Which cache backends an app's entry actually has to speak.
+*
+* The config answers this for a cache that named nowhere, and the *declaration*
+* answers it for one that named a database — `orders.cache('Sessions')` is a
+* statement about the application, so a deployment cannot move that cache and
+* the entry cannot register a driver for somewhere else.
+*
+* Reading only the config is how an entry ends up registering the Upstash
+* driver for a URL the target composed as `postgres://`, which fails at the
+* first request with `UnregisteredCacheScheme` and a stack that points at the
+* cache rather than at the config that disagreed.
+*/
+function cacheBackendsIn(manifest, configured) {
+	const caches = Object.values(manifest).filter((d) => d.kind === "cache");
+	return [...new Set(caches.map((c) => c.of ? "db" : configured))];
+}
+/**
+* The drivers an app's entry points should register.
+*
+* Keyed off the dependency rather than off a declared bucket, because the entry
+* is generated before discovery has run on the watcher's rebuild path — and an
+* app that installed `@geekmidas/storage` has already paid for the SDK it would
+* otherwise resolve lazily.
+*
+* "Installed" the way Node resolves it: the app's own `package.json`, or any
+* directory above it. A workspace that lists `@geekmidas/storage` once, at its
+* root, is the common case — and reading only the app's file registered no S3
+* driver there, so the first service to inject a bucket threw
+* `UnregisteredStorageScheme`. A queue whose consumer depended on one logged
+* that once and was never polled.
+*/
+function storageDriversFor(appRoot) {
+	return dependsOnStorage(appRoot) ? S3 : NONE;
+}
+function dependsOnStorage(appRoot) {
+	for (let dir = resolve(appRoot);; dir = dirname(dir)) {
+		if (listsStorage(join(dir, "package.json"))) return true;
+		if (dirname(dir) === dir) return false;
+	}
+}
+function listsStorage(manifest) {
+	if (!existsSync(manifest)) return false;
+	try {
+		const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+		return Boolean(pkg.dependencies?.["@geekmidas/storage"] ?? pkg.devDependencies?.["@geekmidas/storage"]);
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/generators/SubscriberGenerator.ts
+var SubscriberGenerator = class extends ConstructGenerator {
+	isConstruct(value) {
+		return Subscriber.isSubscriber(value);
+	}
+	async build(context, constructs, outputDir, options) {
+		const target = options?.target ?? "aws";
+		const logger = console;
+		const subscriberInfos = [];
+		if (target === "server") {
+			await this.generateServerSubscribersFile(outputDir, constructs);
+			logger.log(`Generated server subscribers file with ${constructs.length} subscribers (polling mode)`);
+			return subscriberInfos;
+		}
+		if (constructs.length === 0) return subscriberInfos;
+		const subscribersDir = join(outputDir, "subscribers");
+		await mkdir(subscribersDir, { recursive: true });
+		for (const { key, construct, path } of constructs) {
+			const handlerFile = await this.generateSubscriberHandler(subscribersDir, path.relative, key, construct, context, construct.owner);
+			subscriberInfos.push({
+				name: key,
+				handler: relative(options?.root ?? process.cwd(), handlerFile).replace(/\.ts$/, ".handler"),
+				subscribedEvents: construct.subscribedEvents || [],
+				...construct.topicName ? {
+					transport: "topic",
+					topic: construct.topicName
+				} : {},
+				timeout: construct.timeout,
+				memorySize: construct.memorySize,
+				environment: await construct.getEnvironment({ markOptional: context.markOptional }),
+				dependencies: construct.constructs
+			});
+			logger.log(`Generated subscriber handler: ${key}`);
+		}
+		return subscriberInfos;
+	}
+	async generateSubscriberHandler(outputDir, sourceFile, exportName, _subscriber, context, owner) {
+		const handlerFileName = `${exportName}.ts`;
+		const handlerPath = join(outputDir, handlerFileName);
+		const importPath = relative(dirname(handlerPath), sourceFile).replace(/\.ts$/, ".js");
+		const runtime = runtimeFor(context, dirname(handlerPath), owner);
+		const content = `import { AWSLambdaSubscriber } from '@geekmidas/constructs/aws';
+import { ${exportName} } from '${importPath}';
+${runtime.imports}
+${runtime.bindings}
+
+const adapter = new AWSLambdaSubscriber(envParser, ${exportName});
+
+export const handler = adapter.handler;
+`;
+		await writeFile(handlerPath, content);
+		return handlerPath;
+	}
+	async generateServerSubscribersFile(outputDir, subscribers) {
+		await mkdir(outputDir, { recursive: true });
+		const subscribersPath = join(outputDir, "subscribers.ts");
+		if (subscribers.length === 0) {
+			await writeFile(subscribersPath, `/**
+ * Generated subscribers setup — this app declares none.
+ */
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+
+export async function setupSubscribers(
+  _app: unknown,
+  _envParser: EnvironmentParser<any>,
+  _logger: Logger,
+): Promise<(port: number) => Promise<void>> {
+  return async () => {};
+}
+`);
+			return subscribersPath;
+		}
+		const importsByFile = /* @__PURE__ */ new Map();
+		for (const { path, key } of subscribers) {
+			const importPath = relative(dirname(subscribersPath), path.relative).replace(/\.ts$/, ".js");
+			importsByFile.set(importPath, [...importsByFile.get(importPath) ?? [], key]);
+		}
+		const content = `/**
+ * Generated subscribers setup.
+ *
+ * Each subscriber is run against the topic it is bound to, through that
+ * topic's own connection string:
+ *
+ * - **sns://** — pushed, not polled. The subscriber gets an HTTP route on this
+ *   server, and the route is subscribed to the topic with a filter policy of
+ *   the events it named, so SNS fans out to each subscriber. The route runs the
+ *   subscriber through the same adaptor a Lambda subscription does.
+ * - **anything else** (pgboss://, rabbitmq://, sqs://) — polled. On pg-boss
+ *   each subscriber drains a queue of its own, \`<topic>/<subscriber>\`, so
+ *   every subscriber sees every event; replicas of one subscriber share it.
+ *
+ * GKM_SUBSCRIBERS=off (\`gkm dev --no-subscribers\`) runs none of them.
+ * GKM_SUBSCRIBER_PUSH_URL is the address SNS pushes to; against the local
+ * emulator it defaults to this server through host.docker.internal.
+ */
+import { connect } from 'node:net';
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+import { EventConnectionFactory, Subscriber } from '@geekmidas/events';
+import type { EventConnection } from '@geekmidas/events';
+import { ServiceDiscovery } from '@geekmidas/services';
+${Array.from(importsByFile.entries()).map(([importPath, exports]) => `import { ${exports.join(", ")} } from '${importPath}';`).join("\n")}
+
+const subscribers = [
+${subscribers.map(({ key, construct }) => {
+			const connectionKey = construct.topicName ? provideKey(canonicalId(construct.topicName), "publisherConnectionString") : void 0;
+			return `  { id: '${key}', subscriber: ${key}, topic: ${construct.topicName ? `'${construct.topicName}'` : "undefined"}, connectionKey: ${connectionKey ? `'${connectionKey}'` : "undefined"} },`;
+		}).join("\n")}
+];
+
+/** The route a subscriber's pushes arrive on. */
+export const SUBSCRIBER_ROUTE = (id: string) => \`/__gkm/subscribers/\${id}\`;
+
+/** Resolves once something is accepting connections on the port. */
+async function listening(port: number): Promise<void> {
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const open = await new Promise<boolean>((resolve) => {
+      const socket = connect(port, '127.0.0.1');
+      socket.once('connect', () => { socket.end(); resolve(true); });
+      socket.once('error', () => resolve(false));
+    });
+    if (open) return;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+/**
+ * Mount each pushed subscriber's route and start each polled one. Returns what
+ * to run once the server is listening: subscribing a route makes SNS send its
+ * confirmation at once, so the route has to be reachable first.
+ */
+export async function setupSubscribers(
+  app: { post: (path: string, handler: (c: any) => unknown) => unknown },
+  envParser: EnvironmentParser<any>,
+  logger: Logger,
+): Promise<(port: number) => Promise<void>> {
+  if (process.env.GKM_SUBSCRIBERS === 'off') {
+    logger.info('Subscribers are off (--no-subscribers)');
+    return async () => {};
+  }
+
+  const serviceDiscovery = ServiceDiscovery.getInstance(envParser);
+  const connections = new Map<string, EventConnection>();
+  const afterListening: ((port: number) => Promise<void>)[] = [];
+
+  for (const { id, subscriber, topic, connectionKey } of subscribers) {
+    const events = subscriber.subscribedEvents || [];
+    if (events.length === 0) {
+      logger.warn({ subscriber: id }, 'Subscriber has no subscribed events, skipping');
+      continue;
+    }
+    const connectionString = connectionKey ? process.env[connectionKey] : undefined;
+    if (!connectionString) {
+      logger.error(
+        { subscriber: id, connectionKey },
+        'No connection string for the topic this subscriber is bound to',
+      );
+      continue;
+    }
+
+    try {
+      if (connectionString.startsWith('sns:')) {
+        const { SNSConnection, snsUrl, subscribeHttpEndpoint } = await import('@geekmidas/events/sns');
+        const { SnsPushSubscriberAdaptor } = await import('@geekmidas/constructs/subscribers');
+        const address = snsUrl.parse(connectionString);
+        const route = SUBSCRIBER_ROUTE(id);
+        const adaptor = new SnsPushSubscriberAdaptor(envParser, subscriber, {
+          topicArn: address.topicArn,
+          // An emulator signs nothing. Decided by the address this server was
+          // configured with, never by anything a request says about itself.
+          verify: !address.endpoint,
+          ...(address.endpoint ? { emulatorEndpoint: address.endpoint } : {}),
+        });
+
+        app.post(route, async (c: any) => {
+          const body = JSON.parse(await c.req.text());
+          const response = await adaptor.handle(body);
+          return c.json(response.body, response.status);
+        });
+
+        afterListening.push(async (port) => {
+          const base =
+            process.env.GKM_SUBSCRIBER_PUSH_URL ??
+            (address.endpoint ? \`http://host.docker.internal:\${port}\` : undefined);
+          if (!base) {
+            logger.error(
+              { subscriber: id },
+              'Set GKM_SUBSCRIBER_PUSH_URL to the public URL of this worker, which SNS pushes to',
+            );
+            return;
+          }
+          const connection = await SNSConnection.fromConnectionString(connectionString);
+          await subscribeHttpEndpoint(connection, {
+            endpoint: new URL(route, base).toString(),
+            events,
+          });
+          logger.info({ subscriber: id, events }, 'Subscriber subscribed for push');
+        });
+        continue;
+      }
+
+      let connection = connections.get(connectionString);
+      if (!connection) {
+        connection = await EventConnectionFactory.fromConnectionString(connectionString);
+        connections.set(connectionString, connection);
+      }
+      // Named, so a broker with one address for everything (pg-boss) gives
+      // this subscriber a queue of its own: fan-out, not competition.
+      const eventSubscriber = await Subscriber.fromConnection(connection, {
+        topic,
+        subscription: id,
+      });
+      const services = subscriber.services.length > 0
+        ? await serviceDiscovery.register(subscriber.services)
+        : {};
+      // The subscriber's database — the worker's, or its own — as \`db\`. A
+      // pushed subscriber gets it from the adaptor above instead.
+      const db = subscriber.databaseService
+        ? (await serviceDiscovery.register([subscriber.databaseService]))[
+            subscriber.databaseService.serviceName
+          ]
+        : undefined;
+
+      await eventSubscriber.subscribe(events, async (event) => {
+        try {
+          await subscriber.handler({
+            events: [event],
+            services: services as any,
+            logger: subscriber.logger,
+            db,
+          } as any);
+        } catch (error) {
+          logger.error({ error, event, subscriber: id }, 'Failed to process event');
+          // Rethrown so the transport keeps the event for a retry — as a queue
+          // consumer's failure does, and as a pushed subscriber's 500 does.
+          throw error;
+        }
+      });
+      logger.info({ subscriber: id, events }, 'Subscriber started polling');
+    } catch (error) {
+      // The message too: a missing module's code alone does not say which.
+      logger.error(
+        { error, message: (error as Error)?.message, subscriber: id },
+        'Failed to set up subscriber',
+      );
+    }
+  }
+
+  const shutdown = () => {
+    for (const connection of connections.values()) void connection.close();
+  };
+  process.once('SIGTERM', shutdown);
+  process.once('SIGINT', shutdown);
+
+  return async (port) => {
+    if (afterListening.length === 0) return;
+    await listening(port);
+    for (const subscribe of afterListening) {
+      await subscribe(port).catch((error) => {
+        logger.error({ error }, 'Failed to subscribe for push');
+      });
+    }
+  };
+}
+`;
+		await writeFile(subscribersPath, content);
+		return subscribersPath;
+	}
+};
+//#endregion
+//#region src/test/harness.ts
+/**
+* What `gkm test` writes for a feature test to be built from.
+*
+* `gkm test` already discovers an app's constructs and resolves the test
+* stage's environment; this keeps both, under `.gkm/test/`:
+*
+* - `manifest.json` — which construct and endpoint is exported where, and the
+*   environment the test stage resolved, keyed as the constructs derive keys.
+* - `clients/<surface>.ts` — each surface's typed client, from the same
+*   generator `gkm build` uses for the app's own.
+* - `index.ts` — the configured `it`, and a `Browser` holding one client per
+*   surface and one per auth server, each on the browser's `fetch`.
+*
+* A test imports `it` from there and declares nothing — not a construct, not an
+* environment key, not a client.
+*/
+/**
+* The variable the manifest's path travels in — what
+* `@geekmidas/constructs/testing` reads. Its own constant rather than an import:
+* that entry carries the whole harness (MSW, Hono, Vitest), and importing it
+* here put all of it on the start-up path of every `gkm` command.
+*/
+const TEST_MANIFEST_ENV = "GKM_TEST_MANIFEST";
+/** Where the harness lives, relative to the workspace root. */
+const TEST_HARNESS_DIR = ".gkm/test";
+/**
+* Better-auth's client plugin for each server plugin id.
+*
+* Written down rather than derived: the ids and the client names do not follow
+* one rule (`admin` pairs with `adminClient`, `email-otp` with
+* `emailOTPClient`), and a guess that missed would hand a test a client
+* silently lacking every method of that plugin. A server plugin not listed has
+* no client counterpart — `bearer`, `open-api` — or needs one from another
+* package, and is left out.
+*/
+const CLIENT_PLUGINS = {
+	admin: "adminClient",
+	anonymous: "anonymousClient",
+	"device-authorization": "deviceAuthorizationClient",
+	"email-otp": "emailOTPClient",
+	jwt: "jwtClient",
+	"last-login-method": "lastLoginMethodClient",
+	"magic-link": "magicLinkClient",
+	"multi-session": "multiSessionClient",
+	"oauth-popup": "oauthPopupClient",
+	"one-tap": "oneTapClient",
+	"one-time-token": "oneTimeTokenClient",
+	organization: "organizationClient",
+	"phone-number": "phoneNumberClient",
+	siwe: "siweClient",
+	"two-factor": "twoFactorClient",
+	username: "usernameClient"
+};
+/** Where a project keeps its test factories, relative to its root. */
+const DEFAULT_FACTORIES_DIR = "test/factories";
+/** A file in the factories folder that names no database construct. */
+var UnknownFactoryFile = class extends Error {
+	file;
+	known;
+	constructor(file, known) {
+		super(`${file} names no database construct, so no test could be handed it. ` + (known.length > 0 ? `The databases: ${known.join(", ")}. ` : "This project declares no database. ") + `Name a factory after its database: test/factories/<construct>.ts.`);
+		this.file = file;
+		this.known = known;
+		this.name = "UnknownFactoryFile";
+	}
+};
+/** A factory file that exports no `createFactory`. */
+var FactoryHasNoCreate = class extends Error {
+	file;
+	constructor(file) {
+		super(`${file} is a test factory but exports no \`createFactory\`. Export \`function createFactory(db: Kysely<Database>)\` returning the factory.`);
+		this.file = file;
+		this.name = "FactoryHasNoCreate";
+	}
+};
+/**
+* The factories in a folder, each matched to the database it is named after.
+*
+* A file that names no database, or exports no `createFactory`, is refused
+* rather than skipped: either is a factory no test would ever be handed.
+*/
+async function factorySources(folder, databases) {
+	if (!folder) return [];
+	const entries = await readdir(folder, { withFileTypes: true }).catch((error) => {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	});
+	const found = [];
+	for (const entry of entries) {
+		if (!entry.isFile() || !isFactoryFile(entry.name)) continue;
+		const file = join(folder, entry.name);
+		const id = canonicalId(entry.name.slice(0, -extname(entry.name).length));
+		if (!databases.includes(id)) throw new UnknownFactoryFile(file, databases);
+		if (typeof (await import(pathToFileURL(file).href)).createFactory !== "function") throw new FactoryHasNoCreate(file);
+		found.push({
+			file,
+			service: serviceKey(id)
+		});
+	}
+	return found.sort((a, b) => a.service < b.service ? -1 : 1);
+}
+function isFactoryFile(file) {
+	if (file.endsWith(".d.ts")) return false;
+	if (/\.(spec|test)\.[cm]?[jt]s$/.test(file)) return false;
+	return [
+		".ts",
+		".mts",
+		".js",
+		".mjs"
+	].includes(extname(file));
+}
+/** Write the manifest, the clients and the harness; return the manifest path. */
+async function writeTestHarness(options) {
+	const sources = {};
+	const declared = await discover({
+		patterns: options.patterns,
+		cwd: options.root,
+		sources
+	});
+	const endpoints = (await new EndpointGenerator().load(options.patterns, options.root)).map(({ key, construct, path }) => ({
+		surface: construct.owner ?? construct.surface?.id,
+		construct,
+		source: {
+			file: path.absolute,
+			export: key
+		}
+	})).filter((endpoint) => endpoint.surface !== void 0);
+	const subscribers = (await new SubscriberGenerator().load(options.patterns, options.root)).map(({ key, path }) => ({ source: {
+		file: path.absolute,
+		export: key
+	} }));
+	const manifest = {
+		stage: options.stage,
+		constructs: Object.fromEntries(Object.entries(declared).flatMap(([id, declaration]) => {
+			const source = sources[id];
+			return source ? [[id, {
+				kind: declaration.kind,
+				source: {
+					file: source.file,
+					export: source.exportName
+				}
+			}]] : [];
+		})),
+		endpoints: endpoints.map(({ surface, source }) => ({
+			surface,
+			source
+		})),
+		subscribers,
+		env: options.env
+	};
+	const surfaces = [...new Set(endpoints.map(({ surface }) => surface))];
+	const generator = new OpenApiTsGenerator();
+	const clients = await Promise.all(surfaces.map(async (surface) => ({
+		file: `${kebabCase(surface)}.ts`,
+		content: await generator.generate(endpoints.filter((endpoint) => endpoint.surface === surface).map(({ construct }) => construct), {
+			title: surface,
+			version: "1.0.0"
+		})
+	})));
+	const auths = await authClients(declared, sources, options.env);
+	const drivers = driversFor({
+		appRoot: options.root,
+		cache: cacheBackendsIn(declared, options.cacheBackend)
+	});
+	const owners = new Set(auths.map((auth) => auth.databaseId));
+	const databases = databaseSources(declared, sources).filter(({ id, kind }) => !owners.has(id) && kind !== "database-reader");
+	const factories = await factorySources(options.factories, databases.map(({ id }) => id));
+	const fakes = Object.entries(await readFakes(options.root, declared)).map(([id, { file }]) => ({
+		id,
+		file
+	}));
+	const services = serviceSources(declared, sources).filter(({ id }) => !owners.has(id));
+	const files = [.../* @__PURE__ */ new Set([
+		...Object.values(manifest.constructs).map(({ source }) => source.file),
+		...manifest.endpoints.map(({ source }) => source.file),
+		...(manifest.subscribers ?? []).map(({ source }) => source.file)
+	])];
+	const harnessFor = (dir) => harnessModule({
+		dir,
+		files,
+		databases,
+		surfaces: surfaces.map((id, index) => ({
+			id,
+			secured: clients[index].content.includes("authStrategies:")
+		})),
+		auths,
+		drivers,
+		factories,
+		fakes,
+		services,
+		mail: Object.values(declared).some(({ kind }) => kind === "email")
+	});
+	const json = `${JSON.stringify(manifest, null, 2)}\n`;
+	return (await Promise.all([...new Set(options.targets)].map(async (target) => {
+		const dir = join(target, TEST_HARNESS_DIR);
+		await rm(dir, {
+			recursive: true,
+			force: true
+		});
+		await mkdir(join(dir, "clients"), { recursive: true });
+		await writeFile(join(dir, "manifest.json"), json);
+		await writeFile(join(dir, "index.ts"), harnessFor(dir));
+		for (const client of clients) await writeFile(join(dir, "clients", client.file), client.content);
+		return join(dir, "manifest.json");
+	})))[0];
+}
+/** Each auth server, with the client plugins its server plugins pair with. */
+async function authClients(declared, sources, env) {
+	const clients = [];
+	const envParser = new EnvironmentParser({ ...env });
+	for (const [id, declaration] of Object.entries(declared)) {
+		const source = sources[id];
+		if (declaration.kind !== "rest-api" || !source) continue;
+		const exported = (await import(source.file))[source.exportName];
+		if (!isBetterAuth(exported) || exported.id !== id) continue;
+		const ids = await exported.pluginIds({
+			envParser,
+			context: serviceContext
+		});
+		clients.push({
+			id,
+			basePath: exported.basePath,
+			plugins: ids.flatMap((plugin) => CLIENT_PLUGINS[plugin] ?? []),
+			databaseId: exported.databaseId
+		});
+	}
+	return clients;
+}
+function isBetterAuth(value) {
+	return typeof value === "object" && value !== null && "pluginIds" in value && "basePath" in value;
+}
+/** `Api` → `api`, `AdminApi` → `adminApi`: a construct id as a property name. */
+function propertyOf(id) {
+	return id.charAt(0).toLowerCase() + id.slice(1);
+}
+/**
+* Every database construct the app declares — a database, a schema tenant, a
+* reader — keyed as a test is handed its transaction.
+*/
+function databaseSources(declared, sources) {
+	return Object.entries(declared).filter(([id, declaration]) => Boolean(sources[id] && declaration.kind.startsWith("database"))).map(([id, declaration]) => ({
+		id,
+		kind: declaration.kind,
+		service: serviceKey(id),
+		source: sources[id]
+	}));
+}
+/** The kinds whose construct hands a handler a client — what `services` reaches. */
+const SERVICE_KINDS = /* @__PURE__ */ new Set([
+	"cache",
+	"credential",
+	"database",
+	"database-schema",
+	"database-reader",
+	"email",
+	"encryption",
+	"external-api",
+	"file-server",
+	"objects",
+	"queue",
+	"topic"
+]);
+function serviceSources(declared, sources) {
+	return Object.entries(declared).filter(([id, declaration]) => Boolean(sources[id] && SERVICE_KINDS.has(declaration.kind))).map(([id, declaration]) => ({
+		id,
+		kind: declaration.kind,
+		service: serviceKey(id),
+		source: sources[id]
+	}));
+}
+/** An import specifier for `file`, from the harness written into `dir`. */
+function specifierFrom(dir, file) {
+	const path = relative(dir, file).replace(/\.tsx?$/, ".js");
+	return path.startsWith(".") ? path : `./${path}`;
+}
+function harnessModule(options) {
+	const { surfaces, auths, drivers, databases, services, dir, files, factories, fakes, mail } = options;
+	const magicLinks = mail ? auths.filter(({ plugins }) => plugins.includes("magicLinkClient")) : [];
+	const signIn = magicLinks.length === 1 ? magicLinks[0] : void 0;
+	const plugins = [...new Set(auths.flatMap(({ plugins }) => plugins))].sort();
+	const imports = [
+		`import {${services.length ? " type ClientOf," : ""}${databases.length ? " type DatabaseOf," : ""} featureTest, loadTestManifest${signIn ? ", signInWithMagicLink" : ""} } from '@geekmidas/constructs/testing';`,
+		...[...new Map([...databases, ...services].map((construct) => [construct.id, construct])).values()].map(({ id, source }) => `import type { ${source.exportName} as __${id} } from '${specifierFrom(dir, source.file)}';`),
+		`import { Browser as TestBrowser } from '@geekmidas/testkit/browser';`,
+		...surfaces.map(({ id }) => `import { createApi as create${id} } from './clients/${kebabCase(id)}.js';`),
+		...auths.length ? [`import { createAuthClient } from 'better-auth/client';`] : [],
+		...plugins.length ? [`import { ${plugins.join(", ")} } from 'better-auth/client/plugins';`] : [],
+		...drivers.imports ? [drivers.imports] : [],
+		...factories.map(({ file, service }) => `import { createFactory as __${service}Factory } from '${specifierFrom(dir, file)}';`),
+		...fakes.map(({ id, file }) => `import __${id}Fake from '${specifierFrom(dir, file)}';`),
+		...files.map((file, index) => `import * as __module${index} from '${specifierFrom(dir, file)}';`)
+	];
+	const url = (id) => `manifest.env[${JSON.stringify(provideKey(id, "url"))}]!`;
+	const members = [
+		...surfaces.map(({ id, secured }) => `	/** \`${id}\`, at ${provideKey(id, "url")}. */
+	readonly ${propertyOf(id)} = create${id}({
+		baseURL: ${url(id)},
+		fetch: this.fetch,${secured ? `
+		// Served in-process: no authorizer runs, so nothing is signed. A scheme
+		// with no strategy sends its request without credentials.
+		authStrategies: {} as never,` : ""}
+	});`),
+		...auths.map((auth) => `	/** \`${auth.id}\`, at ${provideKey(auth.id, "url")}. */
+	readonly ${propertyOf(auth.id)} = createAuthClient({
+		baseURL: \`\${${url(auth.id)}}${auth.basePath}\`,
+		plugins: [${auth.plugins.map((plugin) => `${plugin}()`).join(", ")}],
+		fetchOptions: { customFetchImpl: this.fetch },
+	});`),
+		...signIn ? [`	/**
+	 * Sign in as \`email\` through \`${signIn.id}\`'s magic link, the way a person
+	 * does — the email opened, the link followed. The session it then reports.
+	 * Without an address, as somebody new: \`user.email\` says who.
+	 */
+	signIn(email?: string) {
+		return signInWithMagicLink(this, this.${propertyOf(signIn.id)}, email);
+	}`] : []
+	];
+	const factoriesType = factories.length ? `{ ${factories.map(({ service }) => `${service}: typeof __${service}Factory`).join("; ")} }` : "";
+	const factoriesOption = factories.length ? `, factories: { ${factories.map(({ service }) => `${service}: __${service}Factory`).join(", ")} }` : "";
+	const fakesOption = fakes.length ? `, fakes: { ${fakes.map(({ id }) => `${id}: __${id}Fake`).join(", ")} }` : "";
+	const databasesType = `{ ${databases.map(({ id, service }) => `${service}: DatabaseOf<typeof __${id}>`).join("; ")} }`;
+	const servicesType = services.length ? `{ ${services.map(({ id, service }) => `${service}: ClientOf<typeof __${id}>`).join("; ")} }` : "";
+	const generics = databases.length || factoriesType || servicesType ? `<Browser, ${databases.length ? databasesType : "{}"}${factoriesType || servicesType ? `, ${factoriesType || "{}"}` : ""}${servicesType ? `, ${servicesType}` : ""}>` : "";
+	return `// Generated by \`gkm test\` from the app's constructs — do not edit.
+${imports.join("\n")}
+
+${drivers.setup ? `// The drivers the app's server entry registers, registered the same way.\n${drivers.setup}\n\n` : ""}const manifest = loadTestManifest(new URL('./manifest.json', import.meta.url));
+
+/** A browser with a client for every surface the app declares. */
+export class Browser extends TestBrowser {
+${members.join("\n\n")}
+}
+
+/** The app's modules, by the path the manifest records for each. */
+const modules = {
+${files.map((file, index) => `\t${JSON.stringify(file)}: __module${index},`).join("\n")}
+};
+
+/** \`it\`, for a test that drives the app the way it runs deployed. */
+export const it = featureTest${generics}({ manifest, modules, browser: Browser${factoriesOption}${fakesOption} });
+`;
+}
+//#endregion
+//#region src/test/ready.ts
+/**
+* The hand-off between `gkm test` and the Vitest global setup.
+*
+* `gkm test` reconciles and migrates the test stage before Vitest starts; the
+* setup, run inside Vitest, only has to load what that left. Started by plain
+* `vitest` instead, the setup runs `gkm test --setup` itself first — so there is
+* one way the stage gets ready, whichever started the suite.
+*/
+/** Set on the Vitest process by `gkm test`: the stage is ready, here. */
+const TEST_READY_ENV = "GKM_TEST_READY";
+/** Where `gkm test` records what it prepared, from where it ran. */
+const TEST_READY_FILE = ".gkm/test-ready.json";
+//#endregion
+export { writeTestHarness as a, driversFor as c, TEST_MANIFEST_ENV as i, TEST_READY_FILE as n, SubscriberGenerator as o, DEFAULT_FACTORIES_DIR as r, cacheBackendsIn as s, TEST_READY_ENV as t };
+
+//# sourceMappingURL=ready-CIHpnUc5.mjs.map