@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/build-integrations/playwright/global-setup.d.mts

@@ -1,90 +1,61 @@
 import { PlaywrightStackFixture as PlaywrightStackFixture$1 } from "../runtime/playwright-stack-context-slot.mjs";
 import { ResolveStackContextOptions } from "./stack-context.mjs";
-import * as _$effect_SchemaAST0 from "effect/SchemaAST";
 
 //#region src/build-integrations/playwright/global-setup.d.ts
-/** Playwright's `globalSetup` signature is `() => Promise<void | (() =>
- *  Promise<void>)>` — we model it explicitly so the preset compiles
- *  without `@playwright/test`. */
+/** Playwright's `globalSetup` signature: a setup function that optionally
+ *  returns a teardown function. We model it explicitly so the preset
+ *  compiles without `@playwright/test`. */
 type PlaywrightGlobalSetup = () => Promise<void | (() => Promise<void>)>;
 /**
- * The shape global-setup writes for in-spec tests to read. Tests do
- * NOT re-walk-up to find the manifest at every assertion — they read
- * this prepared fixture from `globalThis`, which is faster and avoids
- * a subtle cwd-mismatch class of failure when Playwright runs tests
- * from a worker process.
- *
- * Re-export of the substrate-owned `runtime/playwright-stack-context-slot`
- * shape so both consumer surfaces agree on one type. The matching
- * typed `declare global` block lives next to the slot key so callers
- * can read/write `globalThis[KEY]` without a cast.
+ * Re-export of the substrate-owned fixture shape (the slot global-setup
+ * stashes for in-runner helpers). Spec WORKERS don't see this globalThis
+ * slot — they read the manifest off disk — but in-runner code and a
+ * single-process driver do.
  */
 type PlaywrightStackFixture = PlaywrightStackFixture$1;
 interface DefineGlobalSetupOptions extends ResolveStackContextOptions {
-  /**
-   * Wait for the supervisor's post-acquire codegen event before the
-   * browser loads the app. Default: `true`.
-   */
-  readonly waitForCodegen?: boolean;
-  /** Maximum wait for the manifest + codegen-ready event. */
-  readonly readyTimeoutMs?: number;
-  /** Poll interval while waiting for the manifest + codegen-ready event. */
-  readonly readyPollIntervalMs?: number;
-  /**
-   * Verify the manifest's `endpoints` has at least one entry. The
-   * supervisor's manifest writer always emits at least the `app`
-   * endpoint, so an empty `endpoints` lookup means the supervisor
-   * crashed before reaching its eager snapshot-and-write — fail
-   * fast here rather than letting tests time out.
-   */
+  /** Stack to boot. Default: `DEVSTACK_STACK` if set, else `'test'`.
+   *  (Browser e2e examples set `DEVSTACK_STACK=e2e` in their `test:e2e`
+   *  script, isolating them from a developer's dev stack.) */
+  readonly stack?: string;
+  /** Path to the app's `devstack.config.ts`. Default: walk-up from cwd. */
+  readonly configPath?: string;
+  /** Runtime root holding `stacks/<stack>/manifest.json`. Default:
+   *  `DEVSTACK_RUNTIME_ROOT` / `DEVSTACK_STATE_DIR` / `.devstack`. */
+  readonly runtimeRoot?: string;
+  /** Read-only path: attach to an already-running stack (no boot, no
+   *  teardown). Default `false`; also enabled by `DEVSTACK_TEST_REUSE=1`
+   *  or by passing an explicit `manifestPath`. */
+  readonly reuse?: boolean;
+  /** Hard cap (ms) for the stack to reach ready. Default 300_000 (5 min). */
+  readonly bootTimeoutMs?: number;
+  /** Fail fast if the resolved manifest exposes zero endpoints. */
   readonly requireNonEmptyEndpoints?: boolean;
-  /**
-   * Verify the named endpoints exist in the manifest. Used to fail
-   * fast when a test suite depends on a specific plugin (wallet,
-   * sui-faucet) being present in the resolved stack.
-   */
+  /** Fail fast if any of these endpoint names is absent. */
   readonly requireEndpoints?: ReadonlyArray<string>;
-  /**
-   * Pre-warm the stack context — read the manifest once and stash
-   * the result on `globalThis` so tests don't repeat the disk read.
-   * Default: `true`.
-   */
+  /** Stash the resolved context on `globalThis` for in-runner helpers.
+   *  Default `true`. */
   readonly preloadContext?: boolean;
 }
+/** The slot on `globalThis` where the prewarmed stack context lives.
+ *  In-spec helpers (`wallet-context.ts`) read from here when present. */
+declare const STACK_CONTEXT_SLOT: "__devstackPlaywrightStackContext__";
+/** Read the slot. Returns `null` if global-setup didn't run in this process
+ *  (e.g. a spec worker, or `globalSetup: null`). Callers MUST fall back to a
+ *  disk manifest read. */
+declare const readStashedFixture: () => PlaywrightStackFixture | null;
 /**
- * @internal Exported only so the through-surface test can assert the
- * drift-detection contract directly (a renamed discriminator must
- * THROW, not decode to `undefined`). Not part of the public API.
- */
-declare const decodeWatchedRecord: (input: unknown, options?: _$effect_SchemaAST0.ParseOptions) => {
-  readonly kind: "engine";
-  readonly event: {
-    readonly tag: string;
-    readonly endpoint?: {
-      readonly name: string;
-    } | undefined;
-  };
-} | {
-  readonly kind: "ack" | "error";
-};
-/**
- * Build a Playwright `globalSetup` function. The returned function
- * matches the signature Playwright expects (a default export of a
- * module path; we return the function so the preset can wire it).
+ * Build a Playwright `globalSetup` that boots (or, in reuse/read-only mode,
+ * attaches to) a dedicated stack and returns a teardown. Wire it as the
+ * config's `globalSetup` module path — `devstackPlaywrightBaseConfig`
+ * references this module's default export.
  */
 declare const buildGlobalSetup: (options?: DefineGlobalSetupOptions) => PlaywrightGlobalSetup;
-/** Default export shape that mirrors what Playwright's
- *  `defineConfig.globalSetup` resolves: a module whose default export
- *  is the setup function. */
+/** Default export = a ready-to-use Playwright `globalSetup` (boots the stack
+ *  resolved from `DEVSTACK_STACK`, tears it down on completion). This is what
+ *  `globalSetup: '@mysten-incubation/devstack/playwright/global-setup'`
+ *  resolves to. */
 declare const _default: PlaywrightGlobalSetup;
-/** The slot on `globalThis` where the prewarmed stack context lives.
- *  In-spec helpers (`wallet-context.ts`) read from here when present
- *  to avoid a second disk read. Re-exported from the runtime slot
- *  module so consumers can import either side. */
-declare const STACK_CONTEXT_SLOT: "__devstackPlaywrightStackContext__";
-/** Read the slot. Returns `null` if global-setup didn't run (e.g. the
- *  user opted out by passing `globalSetup: null`). */
-declare const readStashedFixture: () => PlaywrightStackFixture | null;
 //#endregion
-export { DefineGlobalSetupOptions, PlaywrightGlobalSetup, PlaywrightStackFixture, STACK_CONTEXT_SLOT, buildGlobalSetup, decodeWatchedRecord, _default as default, readStashedFixture };
+export { DefineGlobalSetupOptions, PlaywrightGlobalSetup, PlaywrightStackFixture, STACK_CONTEXT_SLOT, buildGlobalSetup, _default as default, readStashedFixture };
 //# sourceMappingURL=global-setup.d.mts.map

package/dist/build-integrations/playwright/global-setup.mjs

@@ -1,4 +1,6 @@
 import { WALLET_ENDPOINT_KEY } from "../../contracts/wallet-protocol.mjs";
+import { runStack } from "../../api/run-stack.mjs";
+import { loadDevstackConfig } from "../../api/load-config.mjs";
 import { resolveDiscoveryEnv } from "../runtime/resolve-discovery-env.mjs";
 import { discoverSingleStackManifestPath } from "../runtime/discover.mjs";
 import "../runtime/wallet-paths.mjs";
@@ -6,20 +8,88 @@ import { BUILT_IN_ENDPOINT_ALIASES } from "../runtime/conventional-routes.mjs";
 import { PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY } from "../runtime/playwright-stack-context-slot.mjs";
 import { PlaywrightManifestDiscoveryError } from "./errors.mjs";
 import { PLAYWRIGHT_ENV, readStackContext } from "./stack-context.mjs";
-import { Schema } from "effect";
-import { closeSync, openSync, readSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { Effect } from "effect";
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 //#region src/build-integrations/playwright/global-setup.ts
-const DEFAULT_READY_TIMEOUT_MS = 3e5;
-const DEFAULT_READY_POLL_INTERVAL_MS = 100;
-const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+const DEFAULT_BOOT_TIMEOUT_MS = 3e5;
+const DEFAULT_RUNTIME_ROOT = ".devstack";
+/** Default stack when `DEVSTACK_STACK` is unset. Examples override via the
+*  `test:e2e` script; this is only the bare fallback. */
+const DEFAULT_TEST_STACK = "test";
+const isTruthyEnv = (value) => value === "1" || value === "true" || value === "yes";
+const resolveStackName = (options, env) => {
+	const fromEnv = env[PLAYWRIGHT_ENV.STACK];
+	return options.stack ?? (fromEnv && fromEnv !== "" ? fromEnv : DEFAULT_TEST_STACK);
+};
+const resolveRuntimeRoot = (options, env) => options.runtimeRoot ?? (env.DEVSTACK_RUNTIME_ROOT || env.DEVSTACK_STATE_DIR || void 0) ?? DEFAULT_RUNTIME_ROOT;
+const withTimeout = async (promise, ms, label) => {
+	let timer;
+	const timeout = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`${label} timed out after ${ms}ms`)), ms);
+	});
+	try {
+		return await Promise.race([promise, timeout]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+};
+const safeStop = async (handle) => {
+	try {
+		await Effect.runPromise(handle.stop);
+	} catch {}
+	try {
+		await Effect.runPromise(handle.awaitShutdown);
+	} catch {}
+};
+/** After the in-process supervisor exits, graceful shutdown only STOPS the
+*  stack's containers (devstack keeps them for warm restarts). An ephemeral
+*  e2e stack should leave nothing behind, so run the production `devstack
+*  wipe` verb (force-removes containers + networks + volumes + per-stack
+*  state). Best-effort: failure never fails the test run, and a leftover
+*  stopped stack is force-recreated by the next boot. Skip with
+*  `DEVSTACK_TEST_KEEP=1` to leave the stack up for debugging. */
+const wipeStack = (stack, runtimeRoot, cwd) => new Promise((resolve) => {
+	const cliEntry = fileURLToPath(new URL("../../cli/main.mjs", import.meta.url));
+	if (!existsSync(cliEntry)) {
+		resolve();
+		return;
+	}
+	const child = spawn(process.execPath, [
+		cliEntry,
+		"wipe",
+		"--yes"
+	], {
+		cwd,
+		env: {
+			...process.env,
+			DEVSTACK_STACK: stack,
+			DEVSTACK_RUNTIME_ROOT: runtimeRoot
+		},
+		stdio: "ignore"
+	});
+	child.unref();
+	const done = () => resolve();
+	child.on("error", done);
+	child.on("exit", done);
+	setTimeout(() => {
+		child.kill();
+		resolve();
+	}, 12e4).unref?.();
+});
+const publishHandoff = (stack, manifestPath) => {
+	process.env[PLAYWRIGHT_ENV.STACK] = stack;
+	process.env[PLAYWRIGHT_ENV.MANIFEST_PATH] = manifestPath;
+};
 const stackOptionWasExplicit = (options) => {
 	const env = options.env ?? process.env;
 	return options.stack !== void 0 || options.manifestPath !== void 0 || env[PLAYWRIGHT_ENV.STACK] !== void 0 || env[PLAYWRIGHT_ENV.MANIFEST_PATH] !== void 0;
 };
 const findSingleStackManifestPath = (options) => {
 	if (stackOptionWasExplicit(options)) return null;
-	const { stateDir } = resolveDiscoveryEnv(options.env ?? process.env, { ...options.stateDir !== void 0 ? { stateDir: options.stateDir } : {} });
+	const { stateDir } = resolveDiscoveryEnv(options.env ?? process.env, options.stateDir !== void 0 ? { stateDir: options.stateDir } : {});
 	return discoverSingleStackManifestPath({
 		...options.cwd !== void 0 ? { cwd: options.cwd } : {},
 		stateDir
@@ -38,217 +108,16 @@ const readContextForSetup = (options) => {
 		});
 	}
 };
-const createCodegenWatchState = () => ({
-	fd: null,
-	offset: 0,
-	lineIndex: 0,
-	carry: "",
-	latestAppEndpointLine: -1,
-	latestCodegenLine: -1,
-	lastFileSize: 0,
-	decodeFailures: 0
-});
-const READ_CHUNK_BYTES = 64 * 1024;
-/**
-* Pinned-shape schema for the ndjson records we tail. The supervisor
-* emits a richer envelope (`protocol`/`seq`/`at` plus the full
-* `EngineEvent` union payload — see
-* `substrate/runtime/cross-process/command-channel/protocol.ts`
-* `EventRecordSchema`), but the watch only needs the discriminators
-* that route a record to `latestAppEndpointLine` / `latestCodegenLine`.
-*
-* The pin's job is to FAIL LOUDLY if one of those discriminators is
-* renamed upstream — a silent miss leaves the matchers permanently
-* unfired and deadlocks global-setup at the 5min `readyTimeout`. An
-* earlier version declared every field as `optional(Unknown)`, which
-* defeats that entirely: a `kind`→`recordKind` rename decoded to
-* `undefined` instead of throwing, so the watch silently stalled. We
-* therefore pin the stable discriminators as REQUIRED while keeping the
-* genuinely-variable axis (the engine `tag` value) permissive:
-*
-*   - The engine variant requires `kind: 'engine'` (the literal value
-*     the matchers test against, verified at `channel.ts` `publishEvent`)
-*     and a required `event.tag` STRING. Renaming `kind`, its `'engine'`
-*     value, the `event` key, or the `tag` key all fail decode — these
-*     are the deadlock-class discriminators. The `tag` VALUE stays open,
-*     so future `EngineEvent` tag additions need no change here.
-*   - `event.endpoint` is optional (most engine tags carry no endpoint),
-*     but WHERE present its `name` is REQUIRED. Renaming `name` on an
-*     `endpoint.registered` record therefore fails decode rather than
-*     silently leaving `latestAppEndpointLine` unset.
-*   - `ack` / `error` envelopes carry no `event`; a dedicated variant
-*     absorbs them so the supervisor's correlation replies don't flood
-*     `decodeFailures`. They are never routed.
-*
-* Deliberately NOT permissive about an unknown `kind`: a brand-new
-* envelope kind fails decode. That is a rare, intentional protocol
-* change (and would be made alongside updating consumers), and failing
-* loudly here is the same drift signal the engine-value pin provides.
-*/
-const WatchedEngineRecordSchema = Schema.Struct({
-	kind: Schema.Literal("engine"),
-	event: Schema.Struct({
-		tag: Schema.String,
-		endpoint: Schema.optional(Schema.Struct({ name: Schema.String }))
-	})
-});
-const WatchedReplyRecordSchema = Schema.Struct({ kind: Schema.Literals(["ack", "error"]) });
-const WatchedRecordSchema = Schema.Union([WatchedEngineRecordSchema, WatchedReplyRecordSchema]);
-/**
-* @internal Exported only so the through-surface test can assert the
-* drift-detection contract directly (a renamed discriminator must
-* THROW, not decode to `undefined`). Not part of the public API.
-*/
-const decodeWatchedRecord = Schema.decodeUnknownSync(WatchedRecordSchema);
-const isEngineRecord = (record) => record.kind === "engine";
-const isAppEndpointRegistration = (record) => isEngineRecord(record) && record.event.tag === "endpoint.registered" && record.event.endpoint?.name === BUILT_IN_ENDPOINT_ALIASES.app;
-const isCodegenEmitted = (record) => isEngineRecord(record) && record.event.tag === "codegen.emitted";
-const DEBUG_ENABLED = () => process.env.DEVSTACK_PLAYWRIGHT_DEBUG === "1";
-const debugLog = (message) => {
-	if (!DEBUG_ENABLED()) return;
-	try {
-		process.stderr.write(`[devstack/playwright] ${message}\n`);
-	} catch {}
-};
-const ingestNdjsonLine = (state, line) => {
-	if (line.length === 0) return;
-	state.lineIndex += 1;
-	let parsed;
-	try {
-		parsed = JSON.parse(line);
-	} catch {
-		state.decodeFailures += 1;
-		if (state.decodeFailures <= 3 || state.decodeFailures % 50 === 0) debugLog(`events.ndjson line ${state.lineIndex} failed JSON.parse (decodeFailures=${state.decodeFailures})`);
-		return;
-	}
-	let record;
-	try {
-		record = decodeWatchedRecord(parsed);
-	} catch (cause) {
-		state.decodeFailures += 1;
-		if (state.decodeFailures <= 3 || state.decodeFailures % 50 === 0) debugLog(`events.ndjson line ${state.lineIndex} failed Schema.decode (decodeFailures=${state.decodeFailures}): ${cause instanceof Error ? cause.message : String(cause)}`);
-		return;
-	}
-	if (isAppEndpointRegistration(record)) state.latestAppEndpointLine = state.lineIndex;
-	if (isCodegenEmitted(record)) state.latestCodegenLine = state.lineIndex;
+const validateContext = (ctx, options) => {
+	if (options.requireNonEmptyEndpoints === true && ctx.endpointNames.length === 0) throw new Error(`devstack manifest at ${ctx.manifestPath} has no endpoints. The supervisor likely failed before its eager snapshot write; check the boot logs for plugin acquire errors.`);
+	const required = options.requireEndpoints ?? [];
+	const missing = [];
+	for (const key of required) if (ctx.endpointMaybe(key) === null) missing.push(key);
+	if (missing.length > 0) throw new Error(`devstack manifest at ${ctx.manifestPath} is missing required endpoints: ${missing.join(", ")}. available endpoint names: ${ctx.endpointNames.join(", ") || "(none)"}. raw manifest keys: ${ctx.manifestEndpointKeys.join(", ") || "(none)"}.`);
 };
-/**
-* Advance the watch state by reading any bytes appended since the
-* previous poll. The fd is allocated lazily on the first poll (so a
-* file that doesn't yet exist isn't a hard error) and stays open across
-* polls until `closeCodegenWatch`. Returns `true` when the file has a
-* codegen-fresh state ready for caller continuation.
-*
-* Truncation/rotation: when `statSync(...).size < state.lastFileSize`
-* the file rotated. We close the old fd, reopen, and restart the
-* counters so the new tail's events aren't shadowed by stale
-* cross-poll state.
-*/
-const advanceCodegenWatch = (state, eventsPath) => {
-	if (state.fd === null) try {
-		state.fd = openSync(eventsPath, "r");
-	} catch {
-		return false;
-	}
-	try {
-		const size = statSync(eventsPath).size;
-		if (size < state.lastFileSize) {
-			try {
-				closeSync(state.fd);
-			} catch {}
-			state.fd = null;
-			state.offset = 0;
-			state.lineIndex = 0;
-			state.carry = "";
-			state.latestAppEndpointLine = -1;
-			state.latestCodegenLine = -1;
-			state.lastFileSize = 0;
-			try {
-				state.fd = openSync(eventsPath, "r");
-			} catch {
-				return false;
-			}
-		}
-		state.lastFileSize = size;
-		const buf = Buffer.allocUnsafe(READ_CHUNK_BYTES);
-		while (state.offset < size) {
-			const bytesRead = readSync(state.fd, buf, 0, READ_CHUNK_BYTES, state.offset);
-			if (bytesRead <= 0) break;
-			state.offset += bytesRead;
-			const segments = (state.carry + buf.subarray(0, bytesRead).toString("utf8")).split(/\r?\n/);
-			state.carry = segments.pop() ?? "";
-			for (const segment of segments) ingestNdjsonLine(state, segment);
-		}
-	} catch {}
-	if (state.latestCodegenLine < 0) return false;
-	if (state.latestAppEndpointLine < 0) return true;
-	return state.latestCodegenLine > state.latestAppEndpointLine;
-};
-const closeCodegenWatch = (state) => {
-	if (state.fd === null) return;
-	try {
-		closeSync(state.fd);
-	} catch {}
-	state.fd = null;
-};
-const waitForReadyStackContext = async (options) => {
-	const timeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
-	const intervalMs = options.readyPollIntervalMs ?? DEFAULT_READY_POLL_INTERVAL_MS;
-	const deadline = Date.now() + timeoutMs;
-	let lastError = null;
-	let ctx = null;
-	while (Date.now() <= deadline) try {
-		ctx = readContextForSetup(options);
-		break;
-	} catch (cause) {
-		lastError = cause;
-		await sleep(intervalMs);
-	}
-	if (ctx === null) throw new Error(`devstack manifest did not appear within ${timeoutMs}ms` + (lastError instanceof Error ? `: ${lastError.message}` : ""));
-	const eventsPath = join(dirname(ctx.manifestPath), "events.ndjson");
-	const watchState = createCodegenWatchState();
-	try {
-		while (Date.now() <= deadline) {
-			if (advanceCodegenWatch(watchState, eventsPath)) return ctx;
-			lastError = /* @__PURE__ */ new Error(`devstack has not emitted codegen yet; waiting on events next to ${ctx.manifestPath}`);
-			await sleep(intervalMs);
-		}
-	} finally {
-		closeCodegenWatch(watchState);
-	}
-	throw new Error(`devstack did not reach post-acquire codegen within ${timeoutMs}ms` + (lastError instanceof Error ? `: ${lastError.message}` : ""));
-};
-/**
-* Build a Playwright `globalSetup` function. The returned function
-* matches the signature Playwright expects (a default export of a
-* module path; we return the function so the preset can wire it).
-*/
-const buildGlobalSetup = (options = {}) => {
-	return async () => {
-		const ctx = options.waitForCodegen ?? true ? await waitForReadyStackContext(options) : readContextForSetup(options);
-		if (options.requireNonEmptyEndpoints === true) {
-			if (ctx.endpointNames.length === 0) throw new Error(`devstack manifest at ${ctx.manifestPath} has no endpoints. The supervisor likely failed before its eager snapshot write; check the dev server logs for plugin acquire errors.`);
-		}
-		const required = options.requireEndpoints ?? [];
-		const missing = [];
-		for (const key of required) if (ctx.endpointMaybe(key) === null) missing.push(key);
-		if (missing.length > 0) throw new Error(`devstack manifest at ${ctx.manifestPath} is missing required endpoints: ${missing.join(", ")}. available endpoint names: ${ctx.endpointNames.join(", ") || "(none)"}. raw manifest keys: ${ctx.manifestEndpointKeys.join(", ") || "(none)"}.`);
-		if (options.preloadContext ?? true) stashStackContext(ctx);
-	};
-};
-/** Default export shape that mirrors what Playwright's
-*  `defineConfig.globalSetup` resolves: a module whose default export
-*  is the setup function. */
-var global_setup_default = buildGlobalSetup();
 /** The slot on `globalThis` where the prewarmed stack context lives.
-*  In-spec helpers (`wallet-context.ts`) read from here when present
-*  to avoid a second disk read. Re-exported from the runtime slot
-*  module so consumers can import either side. */
+*  In-spec helpers (`wallet-context.ts`) read from here when present. */
 const STACK_CONTEXT_SLOT = PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY;
-/** Monotonic counter for fixture rotations within a single Node process.
-*  Survives across `stashStackContext` calls so a Playwright retry that
-*  re-runs global-setup stamps a fresh `generation` even though the
-*  module never reloads. */
 let stashGeneration = 0;
 const stashStackContext = (ctx) => {
 	const endpoints = Object.fromEntries(ctx.endpointNames.map((name) => [name, ctx.endpoint(name)]));
@@ -272,10 +141,65 @@ const stashStackContext = (ctx) => {
 	} catch {}
 	globalThis[PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY] = fixture;
 };
-/** Read the slot. Returns `null` if global-setup didn't run (e.g. the
-*  user opted out by passing `globalSetup: null`). */
+/** Read the slot. Returns `null` if global-setup didn't run in this process
+*  (e.g. a spec worker, or `globalSetup: null`). Callers MUST fall back to a
+*  disk manifest read. */
 const readStashedFixture = () => globalThis["__devstackPlaywrightStackContext__"] ?? null;
+/**
+* Build a Playwright `globalSetup` that boots (or, in reuse/read-only mode,
+* attaches to) a dedicated stack and returns a teardown. Wire it as the
+* config's `globalSetup` module path — `devstackPlaywrightBaseConfig`
+* references this module's default export.
+*/
+const buildGlobalSetup = (options = {}) => {
+	return async () => {
+		const env = options.env ?? process.env;
+		if ((options.reuse ?? isTruthyEnv(env.DEVSTACK_TEST_REUSE)) || options.manifestPath !== void 0) {
+			const ctx = readContextForSetup(options);
+			validateContext(ctx, options);
+			if (options.preloadContext ?? true) stashStackContext(ctx);
+			return async () => {};
+		}
+		const stack = resolveStackName(options, env);
+		const runtimeRoot = resolveRuntimeRoot(options, env);
+		const loaded = await Effect.runPromise(loadDevstackConfig(options.configPath)).catch((cause) => {
+			throw new Error(`devstack playwright globalSetup: failed to load devstack config — ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+		});
+		const appRoot = dirname(loaded.resolvedConfigPath);
+		const handle = runStack(loaded.stack, {
+			identity: { stack },
+			appRoot,
+			runtimeRoot,
+			...loaded.engine.options.codegen !== void 0 ? { codegen: loaded.engine.options.codegen } : {}
+		});
+		try {
+			await withTimeout(Effect.runPromise(handle.start), options.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS, `devstack playwright globalSetup: '${stack}' stack boot`);
+		} catch (cause) {
+			await safeStop(handle);
+			throw new Error(`devstack playwright globalSetup: failed to boot the '${stack}' stack. If a '${stack}' stack is already running, set DEVSTACK_TEST_REUSE=1 to run against it. Cause: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+		}
+		const ctx = readContextForSetup({
+			...options,
+			stack,
+			stateDir: runtimeRoot,
+			cwd: appRoot
+		});
+		validateContext(ctx, options);
+		publishHandoff(stack, ctx.manifestPath);
+		if (options.preloadContext ?? true) stashStackContext(ctx);
+		const keep = isTruthyEnv(env.DEVSTACK_TEST_KEEP);
+		return async () => {
+			await safeStop(handle);
+			if (!keep) await wipeStack(stack, runtimeRoot, appRoot);
+		};
+	};
+};
+/** Default export = a ready-to-use Playwright `globalSetup` (boots the stack
+*  resolved from `DEVSTACK_STACK`, tears it down on completion). This is what
+*  `globalSetup: '@mysten-incubation/devstack/playwright/global-setup'`
+*  resolves to. */
+var global_setup_default = buildGlobalSetup();
 //#endregion
-export { STACK_CONTEXT_SLOT, buildGlobalSetup, decodeWatchedRecord, global_setup_default as default, readStashedFixture };
+export { STACK_CONTEXT_SLOT, buildGlobalSetup, global_setup_default as default, readStashedFixture };
 
 //# sourceMappingURL=global-setup.mjs.map