@mysten-incubation/devstack 0.0.1 → 0.1.0

package/dist/api/run-stack.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"run-stack.mjs","names":[],"sources":["../../src/api/run-stack.ts"],"sourcesContent":["// `runStack(stack, opts?)` — top-level programmatic embedding.\n//\n// Cutover blocker #3 (api-surface-design.md § Stack handle, parity-\n// matrix.md \"Programmatic embedding\"): `defineDevstack(...)` returns a\n// static `Stack<Members>` manifest with no runnable surface. Library\n// consumers (vitest setup, custom hosts, Effect-native apps, embedded\n// fixtures) had to re-implement `cli/main.ts:runUpLive`'s substrate\n// Layer composition. `runStack` is the single seam — it consumes the\n// shared `substrate/runtime/run.ts` helper the CLI also consumes.\n//\n// Shape:\n//\n// ```ts\n// const stack = defineDevstack(...);\n// const handle = runStack(stack, { runtimeRoot: '/tmp/devstack' });\n// await Effect.runPromise(handle.start);\n// // ... interact ...\n// await Effect.runPromise(handle.stop);\n// await Effect.runPromise(handle.awaitShutdown);\n// ```\n//\n// `start` resolves when every plugin has reached `ready` (or when one\n// fails to acquire — `start` then fails with `BootError`). `stop`\n// triggers graceful shutdown; `awaitShutdown` resolves when the fiber\n// finishes its scope finalizers.\n\nimport {\n\tCause,\n\tDeferred,\n\tEffect,\n\tExit,\n\tFiber,\n\tLayer,\n\tLogger,\n\tQueue,\n\tStream,\n\tSubscriptionRef,\n} from 'effect';\n\nimport { appName, chainId, stackName } from '../substrate/brand.ts';\nimport type { Identity } from '../substrate/identity.ts';\nimport type { EngineEvent } from '../substrate/events.ts';\nimport type { SubscribableState } from '../substrate/projection.ts';\nimport { makeProjectionRef } from '../substrate/runtime/projection/index.ts';\nimport { buildSubstrateLayers, superviseStackEffect } from '../substrate/runtime/run.ts';\nimport {\n\tbuildProductionOrchestratorSinks,\n\tbuildProductionPostAcquireHook,\n\tlayerProductionOrchestrators,\n\ttype ProductionCodegenOptions,\n} from '../orchestrators/runtime-composition.ts';\nimport {\n\textendBuiltInPluginContext,\n\tlayerBuiltInPluginRuntime,\n} from '../runtime/built-in-plugin-layers.ts';\nimport { readStackEngine, type Stack } from './define-devstack.ts';\nimport type { AnyPlugin } from '../substrate/plugin.ts';\nimport { resolveAppName, resolveStackName } from './inference-network.ts';\n\n// -----------------------------------------------------------------------------\n// Public types\n// -----------------------------------------------------------------------------\n\n/** Identity overrides for `runStack`. App and stack fall back through\n *  shared package metadata inference after their env overrides. */\nexport interface RunStackIdentityOptions {\n\treadonly app?: string;\n\treadonly stack?: string;\n\treadonly network?: string;\n}\n\nexport interface RunStackOptions {\n\t/** Identity overrides — falls back to env + library defaults. */\n\treadonly identity?: RunStackIdentityOptions;\n\t/** User application root. Codegen defaults to `<appRoot>/src/generated`.\n\t *  Defaults to `process.cwd()`. */\n\treadonly appRoot?: string;\n\t/** Codegen output overrides for embedded tests or custom app layout. */\n\treadonly codegen?: Omit<ProductionCodegenOptions, 'appRoot'>;\n\t/** Filesystem root under which the substrate stores per-stack\n\t *  artifacts (cache, snapshots, manifest, projection, etc.).\n\t *  Defaults to `$DEVSTACK_STATE_DIR` then `<cwd>/.devstack`. */\n\treadonly runtimeRoot?: string;\n\t/** Extra Layer composition. Reserved for plugin-author overlays\n\t *  (e.g. custom `CapabilitySinks`, Logger) per ARCHITECTURE.md\n\t *  § Plugin-author extension via Layer composition. */\n\treadonly layers?: Layer.Layer<never>;\n}\n\n/** Boot error surfaced by `RunHandle.start`. Wraps the supervisor's\n *  startup failure tree for cascade-formatter rendering. */\nexport interface BootError {\n\treadonly _tag: 'BootError';\n\treadonly cause: Cause.Cause<unknown>;\n}\n\n/** Programmatic handle. Symmetric with the attached CLI surface:\n *  `events`, `state`, and `awaitShutdown` are the same primitives the\n *  TUI consumes in-process. */\nexport interface RunHandle {\n\t/** Boot the supervisor and resolve when every plugin reaches\n\t *  `ready`. Fails with `BootError` if any plugin's acquire path\n\t *  fails. */\n\treadonly start: Effect.Effect<void, BootError, never>;\n\t/** Trigger graceful shutdown: enqueues `shutdown.requested` onto\n\t *  the supervisor's command channel, then awaits the fiber. */\n\treadonly stop: Effect.Effect<void, never, never>;\n\t/** Resolve when the supervisor fiber exits. Always succeeds — any\n\t *  errors surface via `start`. */\n\treadonly awaitShutdown: Effect.Effect<void, never, never>;\n\t/** Tail of typed engine events from the supervisor's hub. The\n\t *  upstream is a `Queue.Dequeue`; consume via `Stream.run...`. */\n\treadonly events: Stream.Stream<EngineEvent, never, never>;\n\t/** The supervisor's live projection. Renderers + tests read this\n\t *  directly; changes flow through `SubscriptionRef.changes`. */\n\treadonly state: SubscriptionRef.SubscriptionRef<SubscribableState>;\n}\n\n// -----------------------------------------------------------------------------\n// Identity resolution\n// -----------------------------------------------------------------------------\n\nconst resolveIdentity = (\n\tstack: Stack<ReadonlyArray<AnyPlugin>>,\n\topts: RunStackIdentityOptions | undefined,\n\tcwd: string,\n): Identity => {\n\tconst app = resolveAppName({\n\t\texplicit: opts?.app,\n\t\tcwd,\n\t});\n\tconst stackNameStr = resolveStackName({\n\t\texplicit: opts?.stack ?? stack.options.stackName,\n\t\tcwd,\n\t});\n\tconst network = opts?.network ?? process.env.DEVSTACK_NETWORK ?? 'sui:local';\n\treturn {\n\t\tapp: appName(app),\n\t\tstack: stackName(stackNameStr),\n\t\tchain: chainId(network),\n\t};\n};\n\nconst resolveRuntimeRoot = (override: string | undefined): string => {\n\tif (override !== undefined) return override;\n\tconst envRoot = process.env.DEVSTACK_STATE_DIR;\n\tif (envRoot !== undefined && envRoot.length > 0) return envRoot;\n\treturn `${process.cwd()}/.devstack`;\n};\n\nconst toBootError = (cause: Cause.Cause<unknown>): BootError => ({\n\t_tag: 'BootError',\n\tcause,\n});\n\n// -----------------------------------------------------------------------------\n// runStack\n// -----------------------------------------------------------------------------\n\n/**\n * Boot a `Stack` for programmatic embedding. Returns a `RunHandle`\n * synchronously; the supervisor fiber is forked on `start`.\n *\n * Lifecycle:\n *\n *   1. `runStack(stack, opts)` — synchronous; no fiber forked yet.\n *   2. `await Effect.runPromise(handle.start)` — forks the supervisor,\n *      blocks until every plugin reaches `ready` (or fails with\n *      `BootError`).\n *   3. Use `handle.events` / `handle.state` to observe.\n *   4. `await Effect.runPromise(handle.stop)` — graceful shutdown.\n *   5. `handle.awaitShutdown` resolves once finalizers complete.\n *\n * Internal architecture: the handle stores a `Deferred` for boot\n * completion. The supervised body forks a watcher fiber over the\n * registry's `awaitReady` per node; once every node is `ready` (or one\n * fails) the deferred completes. `start` awaits it.\n */\nexport const runStack = (\n\tstack: Stack<ReadonlyArray<AnyPlugin>>,\n\topts: RunStackOptions = {},\n): RunHandle => {\n\tconst engineStack = readStackEngine(stack);\n\tconst runtimeRoot = resolveRuntimeRoot(opts.runtimeRoot);\n\tconst appRoot = opts.appRoot ?? process.cwd();\n\tconst identity = resolveIdentity(stack, opts.identity, appRoot);\n\tconst codegen = opts.codegen ?? engineStack.options.codegen;\n\n\tconst supervisedStack = {\n\t\t_tag: 'Stack' as const,\n\t\tmembers: engineStack.members,\n\t\toptions: engineStack.options,\n\t};\n\n\t// State + handle slots are created at `runStack(...)` time so the\n\t// caller can subscribe to `state.changes` BEFORE `start` runs.\n\t// `SubscriptionRef.make` and `Deferred.make` are both sync-effects\n\t// (no side-effects, no async); `Effect.runSync` is safe here.\n\tconst state = Effect.runSync(makeProjectionRef());\n\tconst bootDeferred = Effect.runSync(Deferred.make<void, BootError>());\n\tconst stopRequested = Effect.runSync(Deferred.make<void>());\n\tconst eventQueueRef = Effect.runSync(Deferred.make<Queue.Dequeue<EngineEvent>>());\n\tconst fiberRef = Effect.runSync(Deferred.make<Fiber.Fiber<void, never>>());\n\n\tconst substrate = layerProductionOrchestrators({\n\t\tcodegen: {\n\t\t\tappRoot,\n\t\t\toutputDir: codegen?.outputDir,\n\t\t\tstackSubdir: codegen?.stackSubdir ?? null,\n\t\t},\n\t}).pipe(Layer.provideMerge(buildSubstrateLayers(identity, runtimeRoot)));\n\n\tconst supervised = Effect.gen(function* () {\n\t\tconst orchestratorSinks = yield* buildProductionOrchestratorSinks();\n\t\tconst postAcquireHook = yield* buildProductionPostAcquireHook({ extras: stack.options.extras });\n\t\tyield* superviseStackEffect(supervisedStack, identity, state, {\n\t\t\torchestratorSinks,\n\t\t\tpostAcquireHook,\n\t\t\textendContext: extendBuiltInPluginContext,\n\t\t\twithinScope: (handle) =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tyield* Deferred.succeed(eventQueueRef, handle.events);\n\n\t\t\t\t\t// Watch every plugin for `ready`; resolve `bootDeferred` once\n\t\t\t\t\t// every node has reached ready (or one fails). The\n\t\t\t\t\t// `awaitReady` callbacks resolve from the per-plugin\n\t\t\t\t\t// ready-gates the registry holds — see supervisor §\n\t\t\t\t\t// \"ready-gate awaits its acquire effect\".\n\t\t\t\t\t// Both forks tie to the surrounding scope (the supervised\n\t\t\t\t\t// scope inside superviseStackEffect). When the supervisor\n\t\t\t\t\t// scope closes — either via graceful shutdown or interrupt\n\t\t\t\t\t// — these fibers are torn down with it.\n\t\t\t\t\tyield* Effect.forkScoped(\n\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\tconst exits = yield* Effect.forEach(\n\t\t\t\t\t\t\t\thandle.graph.nodes,\n\t\t\t\t\t\t\t\t([key]) => handle.registry.awaitReady(key).pipe(Effect.exit),\n\t\t\t\t\t\t\t\t{ concurrency: 'unbounded' },\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\tconst firstFailure = exits.find(Exit.isFailure);\n\t\t\t\t\t\t\tif (firstFailure === undefined) {\n\t\t\t\t\t\t\t\tyield* Deferred.succeed(bootDeferred, undefined);\n\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\tyield* Deferred.fail(bootDeferred, toBootError(firstFailure.cause));\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\n\t\t\t\t\t// Bridge `stop` requests onto the supervisor's command\n\t\t\t\t\t// channel. The supervisor's command loop treats\n\t\t\t\t\t// `shutdown.requested` as the graceful-shutdown signal.\n\t\t\t\t\tyield* Effect.forkScoped(\n\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\tyield* Deferred.await(stopRequested);\n\t\t\t\t\t\t\tyield* Queue.offer(handle.commands, {\n\t\t\t\t\t\t\t\ttag: 'shutdown.requested',\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t}),\n\t\t}).pipe(Effect.provide(layerBuiltInPluginRuntime(orchestratorSinks)));\n\t});\n\n\tconst loggerLayer = Logger.layer([]);\n\tconst layered =\n\t\topts.layers === undefined\n\t\t\t? supervised.pipe(Effect.provide(substrate), Effect.provide(loggerLayer))\n\t\t\t: supervised.pipe(\n\t\t\t\t\tEffect.provide(substrate),\n\t\t\t\t\tEffect.provide(loggerLayer),\n\t\t\t\t\tEffect.provide(opts.layers),\n\t\t\t\t);\n\n\t// Convert any uncaught cause into a boot failure if the deferred\n\t// hasn't completed. The cause is preserved via the fiber's exit for\n\t// `awaitShutdown` consumers that need to inspect it.\n\tconst supervisedProgram: Effect.Effect<void, never, never> = layered.pipe(\n\t\tEffect.catchCause((cause) =>\n\t\t\tDeferred.fail(bootDeferred, toBootError(cause)).pipe(\n\t\t\t\tEffect.asVoid,\n\t\t\t\tEffect.catch(() => Effect.void),\n\t\t\t),\n\t\t),\n\t);\n\n\tconst start: Effect.Effect<void, BootError, never> = Effect.gen(function* () {\n\t\tconst alreadyStarted = yield* Deferred.isDone(fiberRef);\n\t\tif (!alreadyStarted) {\n\t\t\t// `forkDetach` (v4 spelling of v3's `forkDaemon`) decouples the\n\t\t\t// supervisor fiber from the `start` fiber's scope. `forkChild`\n\t\t\t// would tie the supervisor to whatever fiber runs `start`, and\n\t\t\t// once `start` resolves (after `bootDeferred` succeeds) the\n\t\t\t// runtime would interrupt the supervisor — transitioning every\n\t\t\t// plugin `ready → stopping → stopped` before the caller can\n\t\t\t// read post-ready state or call `handle.stop`. The handle's\n\t\t\t// explicit `stop` + `awaitShutdown` paths are the only\n\t\t\t// shutdown signals; the captured `Fiber` reference is how the\n\t\t\t// daemon stays releasable.\n\t\t\tconst fiber = yield* Effect.forkDetach(supervisedProgram);\n\t\t\tyield* Deferred.succeed(fiberRef, fiber);\n\t\t}\n\t\tyield* Deferred.await(bootDeferred);\n\t});\n\n\tconst stop: Effect.Effect<void, never, never> = Effect.gen(function* () {\n\t\tyield* Deferred.succeed(stopRequested, undefined).pipe(Effect.catch(() => Effect.void));\n\t\tconst alreadyStarted = yield* Deferred.isDone(fiberRef);\n\t\tif (!alreadyStarted) {\n\t\t\treturn;\n\t\t}\n\t\tconst fiber = yield* Deferred.await(fiberRef);\n\t\t// `Fiber.await` returns an `Exit` without raising — handles both\n\t\t// success and interrupt-cause cases (the supervisor's\n\t\t// graceful-shutdown path closes the scope, which surfaces as an\n\t\t// interrupt cause if the fiber was mid-await on the latch poll).\n\t\tyield* Fiber.await(fiber);\n\t});\n\n\tconst awaitShutdown: Effect.Effect<void, never, never> = Effect.gen(function* () {\n\t\tconst alreadyStarted = yield* Deferred.isDone(fiberRef);\n\t\tif (!alreadyStarted) {\n\t\t\treturn;\n\t\t}\n\t\tconst fiber = yield* Deferred.await(fiberRef);\n\t\tyield* Fiber.await(fiber);\n\t});\n\n\tconst events: Stream.Stream<EngineEvent, never, never> = Stream.unwrap(\n\t\tEffect.gen(function* () {\n\t\t\tconst queue = yield* Deferred.await(eventQueueRef);\n\t\t\treturn Stream.fromQueue(queue);\n\t\t}),\n\t);\n\n\treturn {\n\t\tstart,\n\t\tstop,\n\t\tawaitShutdown,\n\t\tevents,\n\t\tstate,\n\t};\n};\n"],"mappings":"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"}
+{"version":3,"file":"run-stack.mjs","names":[],"sources":["../../src/api/run-stack.ts"],"sourcesContent":["// `runStack(stack, opts?)` — top-level programmatic embedding.\n//\n// `defineDevstack(...)` returns a static `Stack<Members>` manifest with\n// no runnable surface. Library consumers (vitest setup, custom hosts,\n// Effect-native apps, embedded fixtures) would otherwise have to\n// re-implement `cli/wirings/up.ts:runUpLive`'s substrate Layer composition.\n// `runStack` is the single embedder seam — it consumes the same\n// `orchestrators/runtime-composition.ts` helper the CLI consumes. See\n// ARCHITECTURE.md §\"Layer composition lives at L3, not L0\".\n//\n// Shape:\n//\n// ```ts\n// const stack = defineDevstack(...);\n// const handle = runStack(stack, { runtimeRoot: '/tmp/devstack' });\n// await Effect.runPromise(handle.start);\n// // ... interact ...\n// await Effect.runPromise(handle.stop);\n// await Effect.runPromise(handle.awaitShutdown);\n// ```\n//\n// `start` resolves when every plugin has reached `ready` (or when one\n// fails to acquire — `start` then fails with `BootError`). `stop`\n// triggers graceful shutdown; `awaitShutdown` resolves when the fiber\n// finishes its scope finalizers.\n\nimport {\n\tCause,\n\tContext,\n\tDeferred,\n\tEffect,\n\tExit,\n\tFiber,\n\tLayer,\n\tLogger,\n\tQueue,\n\tRef,\n\tScope,\n\tStream,\n\tSubscriptionRef,\n} from 'effect';\n\nimport { appName, chainId, stackName } from '../substrate/brand.ts';\nimport type { Identity } from '../substrate/identity.ts';\nimport type { EngineEvent } from '../substrate/events.ts';\nimport type { SubscribableState } from '../substrate/projection.ts';\nimport { CapabilitySinksService } from '../substrate/runtime/capability-sinks/index.ts';\nimport { makeProjectionRefSync } from '../substrate/runtime/index.ts';\nimport { buildSubstrateLayers, superviseStackEffect } from '../orchestrators/run.ts';\nimport {\n\tbuildProductionOrchestratorSinks,\n\tbuildProductionPostAcquireHook,\n\tlayerProductionOrchestrators,\n\ttype ProductionCodegenOptions,\n} from '../orchestrators/runtime-composition.ts';\nimport { resolveCodegenOutput } from '../orchestrators/codegen/output-location.ts';\nimport {\n\textendBuiltInPluginContext,\n\tlayerBuiltInPluginRuntime,\n} from '../orchestrators/built-in-plugin-layers.ts';\nimport { readStackEngine, type Stack } from './define-devstack.ts';\nimport type { AnyPlugin } from '../substrate/plugin.ts';\nimport {\n\tresolveAppName,\n\tresolveNetworkSync,\n\tresolveStackName,\n\tresolveStateDir,\n} from './inference-network.ts';\n\n// -----------------------------------------------------------------------------\n// Public types\n// -----------------------------------------------------------------------------\n\n/** Identity overrides for `runStack`. App and stack fall back through\n *  shared package metadata inference after their env overrides. */\nexport interface RunStackIdentityOptions {\n\treadonly app?: string;\n\treadonly stack?: string;\n\treadonly network?: string;\n}\n\nexport interface RunStackOptions {\n\t/** Identity overrides — falls back to env + library defaults. */\n\treadonly identity?: RunStackIdentityOptions;\n\t/** User application root. Codegen defaults to `<appRoot>/src/generated`.\n\t *  Defaults to `process.cwd()`. */\n\treadonly appRoot?: string;\n\t/** Codegen output overrides for embedded tests or custom app layout. */\n\treadonly codegen?: Omit<ProductionCodegenOptions, 'appRoot'>;\n\t/** Filesystem root under which the substrate stores per-stack\n\t *  artifacts (cache, snapshots, manifest, projection, etc.).\n\t *  Precedence: `runtimeRoot` > `stateDir` (this option or\n\t *  `DevstackOptions.stateDir` on the stack) > `$DEVSTACK_STATE_DIR`\n\t *  > `<cwd>/.devstack`. */\n\treadonly runtimeRoot?: string;\n\t/** Sibling of `runtimeRoot` — the `DevstackOptions.stateDir` field\n\t *  threaded through `runStack` so a stack-level default can be\n\t *  overridden per-embedding without forcing every call site to\n\t *  flip between `runtimeRoot` and `stateDir`. Same semantics as\n\t *  `runtimeRoot`; lower precedence. */\n\treadonly stateDir?: string;\n\t/** Extend the plugin execution context after built-in plugin\n\t *  services are installed. Use this for custom plugin-author\n\t *  services, capability sinks, or logger overrides. */\n\treadonly extendContext?: (\n\t\tctx: Context.Context<never>,\n\t) => Effect.Effect<Context.Context<never>, never, Scope.Scope | CapabilitySinksService>;\n}\n\n/** Boot error surfaced by `RunHandle.start`. Wraps the supervisor's\n *  startup failure tree for cascade-formatter rendering. */\nexport interface BootError {\n\treadonly _tag: 'BootError';\n\treadonly cause: Cause.Cause<unknown>;\n}\n\n/** Programmatic handle. Symmetric with the attached CLI surface:\n *  `events`, `state`, and `awaitShutdown` are the same primitives the\n *  TUI consumes in-process. */\nexport interface RunHandle {\n\t/** Boot the supervisor and resolve when every plugin reaches\n\t *  `ready`. Fails with `BootError` if any plugin's acquire path\n\t *  fails. */\n\treadonly start: Effect.Effect<void, BootError, never>;\n\t/** Trigger graceful shutdown: enqueues `shutdown.requested` onto\n\t *  the supervisor's command channel, then awaits the fiber. */\n\treadonly stop: Effect.Effect<void, never, never>;\n\t/** Resolve when the supervisor fiber exits. Succeeds on a clean\n\t *  shutdown; fails with the captured `Cause` if the supervisor died\n\t *  mid-run after boot completed (e.g. a plugin scope finalizer\n\t *  defect). Boot-time failures still surface via `start`. */\n\treadonly awaitShutdown: Effect.Effect<void, unknown, never>;\n\t/** Tail of typed engine events from the supervisor's hub. The\n\t *  upstream is a `Queue.Dequeue`; consume via `Stream.run...`. */\n\treadonly events: Stream.Stream<EngineEvent, never, never>;\n\t/** The supervisor's live projection. Renderers + tests read this\n\t *  directly; changes flow through `SubscriptionRef.changes`. */\n\treadonly state: SubscriptionRef.SubscriptionRef<SubscribableState>;\n}\n\n// -----------------------------------------------------------------------------\n// Identity resolution\n// -----------------------------------------------------------------------------\n\nconst resolveIdentity = (\n\tstack: Stack<ReadonlyArray<AnyPlugin>>,\n\topts: RunStackIdentityOptions | undefined,\n\tcwd: string,\n): Identity => {\n\tconst app = resolveAppName({\n\t\texplicit: opts?.app,\n\t\tcwd,\n\t});\n\tconst stackNameStr = resolveStackName({\n\t\texplicit: opts?.stack ?? stack.options.stackName,\n\t\tcwd,\n\t});\n\t// Parse + validate up-front so a malformed value fails here rather\n\t// than downstream when a plugin probes the chain id. We keep the\n\t// raw input string (`'sui:local'`, `'sui:testnet'`, …) for the\n\t// chain-id brand so existing on-disk cache namespaces and plugin\n\t// equality checks (`chain === 'sui:testnet'`) remain stable.\n\tconst resolved = resolveNetworkSync({\n\t\texplicit: opts?.network,\n\t\tenv: process.env.DEVSTACK_NETWORK,\n\t\texplicitSource: 'runStack({ identity.network })',\n\t});\n\treturn {\n\t\tapp: appName(app),\n\t\tstack: stackName(stackNameStr),\n\t\tchain: chainId(resolved.raw),\n\t};\n};\n\nconst toBootError = (cause: Cause.Cause<unknown>): BootError => ({\n\t_tag: 'BootError',\n\tcause,\n});\n\n// -----------------------------------------------------------------------------\n// runStack\n// -----------------------------------------------------------------------------\n\n/**\n * Boot a `Stack` for programmatic embedding. Returns a `RunHandle`\n * synchronously; the supervisor fiber is forked on `start`.\n *\n * Lifecycle:\n *\n *   1. `runStack(stack, opts)` — synchronous; no fiber forked yet.\n *   2. `await Effect.runPromise(handle.start)` — forks the supervisor,\n *      blocks until every plugin reaches `ready` (or fails with\n *      `BootError`).\n *   3. Use `handle.events` / `handle.state` to observe.\n *   4. `await Effect.runPromise(handle.stop)` — graceful shutdown.\n *   5. `handle.awaitShutdown` resolves once finalizers complete.\n *\n * Internal architecture: the handle stores a `Deferred` for boot\n * completion. The supervised body forks a watcher fiber over the\n * registry's `awaitReady` per node; once every node is `ready` (or one\n * fails) the deferred completes. `start` awaits it.\n */\nexport const runStack = (\n\tstack: Stack<ReadonlyArray<AnyPlugin>>,\n\topts: RunStackOptions = {},\n): RunHandle => {\n\tconst engineStack = readStackEngine(stack);\n\tconst runtimeRoot = resolveStateDir({\n\t\truntimeRoot: opts.runtimeRoot,\n\t\tstateDir: opts.stateDir ?? engineStack.options.stateDir,\n\t\tenv: process.env.DEVSTACK_STATE_DIR,\n\t\tcwd: process.cwd(),\n\t});\n\tconst appRoot = opts.appRoot ?? process.cwd();\n\tconst identity = resolveIdentity(stack, opts.identity, appRoot);\n\tconst codegen = opts.codegen ?? engineStack.options.codegen;\n\n\tconst supervisedStack = {\n\t\t_tag: 'Stack' as const,\n\t\tmembers: engineStack.members,\n\t\toptions: engineStack.options,\n\t};\n\n\t// State + handle slots are created at `runStack(...)` time so the\n\t// caller can subscribe to `state.changes` BEFORE `start` runs.\n\t// `Deferred.make` is sync-effect (no side-effects, no async);\n\t// `Effect.runSync` is safe for it. The projection ref is allocated\n\t// via the explicit `makeProjectionRefSync` so the sync contract is\n\t// pinned at the substrate constructor — if `makeProjectionRef`\n\t// ever picks up an async/Layer wrapper (`withSpan`, annotation),\n\t// `makeProjectionRefSync` must remain sync-only or be replaced by\n\t// a Deferred-handoff seam at this boot-time call site.\n\tconst state = makeProjectionRefSync();\n\tconst bootDeferred = Effect.runSync(Deferred.make<void, BootError>());\n\tconst stopRequested = Effect.runSync(Deferred.make<void>());\n\tconst eventQueueRef = Effect.runSync(Deferred.make<Queue.Dequeue<EngineEvent>>());\n\tconst fiberRef = Effect.runSync(Deferred.make<Fiber.Fiber<void, never>>());\n\tconst startClaim = Effect.runSync(Ref.make(false));\n\t// Tee for mid-run defects/failures. `Deferred.fail(bootDeferred, …)`\n\t// below is a no-op once `bootDeferred` has succeeded (post-boot), so\n\t// without this sibling ref a late scope-finalizer defect would\n\t// otherwise leave the supervised fiber exiting `Success(void)` and\n\t// `awaitShutdown` resolving clean — the operator would have no\n\t// signal. `awaitShutdown` re-raises whatever this ref captured.\n\tconst midRunCauseRef = Effect.runSync(Ref.make<Cause.Cause<unknown> | null>(null));\n\n\t// Resolve the per-stack codegen output location: home run (effective\n\t// stack === config `stackName`) → `src/generated/`; a non-home\n\t// embedding → `.devstack/stacks/<stack>/generated/`. An explicit\n\t// `opts.codegen.outputDir` (or the stack's own\n\t// `codegen.outputDir`) is honored verbatim by the resolver. Both the\n\t// home stack (`engineStack.options.stackName`) and the effective\n\t// stack (the resolved `identity.stack`) are in scope here, mirroring\n\t// the CLI's `buildVerbLayers` seam.\n\tconst codegenOutput = resolveCodegenOutput({\n\t\tappRoot,\n\t\teffectiveStack: String(identity.stack),\n\t\thomeStack: engineStack.options.stackName,\n\t\texplicitOutputDir: codegen?.outputDir,\n\t\texplicitStackSubdir: codegen?.stackSubdir ?? null,\n\t});\n\tconst substrate = layerProductionOrchestrators({\n\t\tcodegen: {\n\t\t\tappRoot,\n\t\t\toutputDir: codegenOutput.outputDir,\n\t\t\tstackSubdir: codegenOutput.stackSubdir,\n\t\t},\n\t}).pipe(Layer.provideMerge(buildSubstrateLayers(identity, runtimeRoot)));\n\n\tconst supervised = Effect.gen(function* () {\n\t\tconst orchestratorSinks = yield* buildProductionOrchestratorSinks();\n\t\tconst postAcquireHook = yield* buildProductionPostAcquireHook({ extras: stack.options.extras });\n\t\tyield* superviseStackEffect(supervisedStack, identity, state, {\n\t\t\torchestratorSinks,\n\t\t\tpostAcquireHook,\n\t\t\textendContext: (ctx) =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tconst builtInContext = yield* extendBuiltInPluginContext(ctx);\n\t\t\t\t\treturn opts.extendContext === undefined\n\t\t\t\t\t\t? builtInContext\n\t\t\t\t\t\t: yield* opts.extendContext(builtInContext);\n\t\t\t\t}),\n\t\t\tbeforeInitialAcquire: (handle) =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tyield* Deferred.succeed(eventQueueRef, handle.events).pipe(\n\t\t\t\t\t\tEffect.catch(() => Effect.void),\n\t\t\t\t\t);\n\n\t\t\t\t\t// Bridge `stop` requests onto the supervisor's command\n\t\t\t\t\t// channel before acquire starts so a boot failure cannot\n\t\t\t\t\t// leave the public handle without an event/command bridge.\n\t\t\t\t\tyield* Effect.forkScoped(\n\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\tyield* Deferred.await(stopRequested);\n\t\t\t\t\t\t\tyield* Queue.offer(handle.commands, {\n\t\t\t\t\t\t\t\ttag: 'shutdown.requested',\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t}),\n\t\t\twithinScope: (handle) =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t// Watch every plugin for `ready`; resolve `bootDeferred` once\n\t\t\t\t\t// every node has reached ready (or one fails). The\n\t\t\t\t\t// `awaitReady` callbacks resolve from the per-plugin\n\t\t\t\t\t// ready-gates the registry holds — see supervisor §\n\t\t\t\t\t// \"ready-gate awaits its acquire effect\".\n\t\t\t\t\t// Both forks tie to the surrounding scope (the supervised\n\t\t\t\t\t// scope inside superviseStackEffect). When the supervisor\n\t\t\t\t\t// scope closes — either via graceful shutdown or interrupt\n\t\t\t\t\t// — these fibers are torn down with it.\n\t\t\t\t\tyield* Effect.forkScoped(\n\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\tconst exits = yield* Effect.forEach(\n\t\t\t\t\t\t\t\thandle.graph.nodes,\n\t\t\t\t\t\t\t\t([key]) => handle.registry.awaitReady(key).pipe(Effect.exit),\n\t\t\t\t\t\t\t\t{ concurrency: 'unbounded' },\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\tconst firstFailure = exits.find(Exit.isFailure);\n\t\t\t\t\t\t\tif (firstFailure === undefined) {\n\t\t\t\t\t\t\t\tyield* Deferred.succeed(bootDeferred, undefined);\n\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\tyield* Deferred.fail(bootDeferred, toBootError(firstFailure.cause));\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t}),\n\t\t}).pipe(Effect.provide(layerBuiltInPluginRuntime(orchestratorSinks)));\n\t});\n\n\tconst loggerLayer = Logger.layer([]);\n\tconst layered = supervised.pipe(Effect.provide(substrate), Effect.provide(loggerLayer));\n\n\t// Convert any uncaught cause into a boot failure if the deferred\n\t// hasn't completed. If `bootDeferred` HAS already succeeded then\n\t// `Deferred.fail` is a no-op — the cause is a mid-run failure\n\t// (e.g. a plugin scope finalizer defect) and would otherwise be\n\t// silently dropped: the fiber exits `Success(void)` and\n\t// `awaitShutdown` resolves clean. Tee the cause into\n\t// `midRunCauseRef` so `awaitShutdown` can re-surface it, AND emit\n\t// `Effect.logError(Cause.pretty(cause))` so observability stays\n\t// loud regardless of whether anyone awaits. Boot failures (still in\n\t// the bootDeferred-pending window) only surface via `start`, not\n\t// here — we'd otherwise re-raise them on `awaitShutdown` after\n\t// `start` already rejected.\n\tconst supervisedProgram: Effect.Effect<void, never, never> = layered.pipe(\n\t\tEffect.catchCause((cause) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst bootAlreadyCompleted = yield* Deferred.isDone(bootDeferred);\n\t\t\t\tyield* Deferred.fail(bootDeferred, toBootError(cause)).pipe(\n\t\t\t\t\tEffect.asVoid,\n\t\t\t\t\tEffect.catch(() => Effect.void),\n\t\t\t\t);\n\t\t\t\tif (bootAlreadyCompleted) {\n\t\t\t\t\tyield* Ref.set(midRunCauseRef, cause);\n\t\t\t\t}\n\t\t\t\tyield* Effect.logError(`devstack runStack: supervisor died\\n${Cause.pretty(cause)}`);\n\t\t\t}),\n\t\t),\n\t);\n\n\tconst start: Effect.Effect<void, BootError, never> = Effect.uninterruptibleMask((restore) =>\n\t\tEffect.gen(function* () {\n\t\t\tconst shouldStart = yield* Ref.modify(startClaim, (started) =>\n\t\t\t\tstarted ? [false, true] : [true, true],\n\t\t\t);\n\t\t\tif (shouldStart) {\n\t\t\t\t// `forkDetach` (v4 spelling of v3's `forkDaemon`) decouples the\n\t\t\t\t// supervisor fiber from the `start` fiber's scope. `forkChild`\n\t\t\t\t// would tie the supervisor to whatever fiber runs `start`, and\n\t\t\t\t// once `start` resolves (after `bootDeferred` succeeds) the\n\t\t\t\t// runtime would interrupt the supervisor — transitioning every\n\t\t\t\t// plugin `ready → stopping → stopped` before the caller can\n\t\t\t\t// read post-ready state or call `handle.stop`. The handle's\n\t\t\t\t// explicit `stop` + `awaitShutdown` paths are the only\n\t\t\t\t// shutdown signals; the captured `Fiber` reference is how the\n\t\t\t\t// daemon stays releasable.\n\t\t\t\tconst fiber = yield* Effect.forkDetach(supervisedProgram);\n\t\t\t\tyield* Deferred.succeed(fiberRef, fiber);\n\t\t\t}\n\t\t\tyield* restore(Deferred.await(bootDeferred));\n\t\t}),\n\t);\n\n\tconst stop: Effect.Effect<void, never, never> = Effect.gen(function* () {\n\t\tyield* Deferred.succeed(stopRequested, undefined).pipe(Effect.catch(() => Effect.void));\n\t\tconst alreadyStarted = yield* Deferred.isDone(fiberRef);\n\t\tif (!alreadyStarted) {\n\t\t\treturn;\n\t\t}\n\t\tconst fiber = yield* Deferred.await(fiberRef);\n\t\t// `Fiber.await` returns an `Exit` without raising — handles both\n\t\t// success and interrupt-cause cases (the supervisor's\n\t\t// graceful-shutdown path closes the scope, which surfaces as an\n\t\t// interrupt cause if the fiber was mid-await on the latch poll).\n\t\tyield* Fiber.await(fiber);\n\t});\n\n\tconst awaitShutdown: Effect.Effect<void, unknown, never> = Effect.gen(function* () {\n\t\tconst alreadyStarted = yield* Deferred.isDone(fiberRef);\n\t\tif (!alreadyStarted) {\n\t\t\treturn;\n\t\t}\n\t\tconst fiber = yield* Deferred.await(fiberRef);\n\t\tyield* Fiber.await(fiber);\n\t\t// Re-surface any mid-run defect/failure captured by the\n\t\t// supervised body's `catchCause` (boot failures are already\n\t\t// surfaced via `start`). Without this re-raise a plugin scope\n\t\t// finalizer defect would silently drop and operators get no\n\t\t// signal — see the comment on `midRunCauseRef` above.\n\t\tconst midRunCause = yield* Ref.get(midRunCauseRef);\n\t\tif (midRunCause !== null) {\n\t\t\treturn yield* Effect.failCause(midRunCause);\n\t\t}\n\t});\n\n\tconst events: Stream.Stream<EngineEvent, never, never> = Stream.unwrap(\n\t\tEffect.gen(function* () {\n\t\t\tconst queue = yield* Deferred.await(eventQueueRef);\n\t\t\treturn Stream.fromQueue(queue);\n\t\t}),\n\t);\n\n\treturn {\n\t\tstart,\n\t\tstop,\n\t\tawaitShutdown,\n\t\tevents,\n\t\tstate,\n\t};\n};\n"],"mappings":"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"}

package/dist/build-integrations/playwright/config.d.mts

@@ -2,6 +2,7 @@ import { ResolveStackContextOptions } from "./stack-context.mjs";
 
 //#region src/build-integrations/playwright/config.d.ts
 type PlaywrightReporterShape = [string] | [string, Record<string, unknown>];
+type PlaywrightGlobalSetupShape = string | string[];
 /** Base subset of `PlaywrightTestConfig` this surface produces. The
  *  full type lives in `@playwright/test`; we keep this structural so
  *  the helpers compile without the peer. */
@@ -12,7 +13,7 @@ interface PlaywrightBaseConfigShape {
   readonly retries: number;
   readonly workers: number;
   readonly reporter: PlaywrightReporterShape[] | string;
-  readonly globalSetup?: string;
+  readonly globalSetup?: PlaywrightGlobalSetupShape;
   readonly globalTeardown?: string;
 }
 type PlaywrightUseConfigShape = {
@@ -40,9 +41,10 @@ interface PlaywrightWebServerConfigShape {
 interface DevstackPlaywrightBaseConfigOptions {
   /** Test directory. Default: `'./e2e'` (architecture invariant). */
   readonly testDir?: string;
-  /** Path to a global-setup module. Default: not wired. Pass `null`
-   *  to keep the property omitted when composing conditionally. */
-  readonly globalSetup?: string | null;
+  /** Path to a global-setup module. Default: the devstack setup that
+   *  waits for post-acquire codegen before specs load the app. Pass
+   *  `null` to keep the property omitted when composing conditionally. */
+  readonly globalSetup?: PlaywrightGlobalSetupShape | null;
 }
 interface DevstackPlaywrightEndpointOptions extends ResolveStackContextOptions {
   /** Endpoint name whose URL becomes `webServer.url` + `use.baseURL`.

package/dist/build-integrations/playwright/config.mjs

@@ -1,10 +1,12 @@
+import { BUILT_IN_ENDPOINT_ALIASES } from "../runtime/conventional-routes.mjs";
 import { resolveEndpointUrl } from "./stack-context.mjs";
 //#region src/build-integrations/playwright/config.ts
+const DEFAULT_GLOBAL_SETUP = "@mysten-incubation/devstack/playwright/global-setup";
 const DEFAULT_TEST_DIR = "./e2e";
 const DEFAULT_COMMAND = "pnpm dev";
 const DEFAULT_WEBSERVER_TIMEOUT_MS = 3e5;
 const DEFAULT_GRACEFUL_SHUTDOWN_MS = 1e4;
-const DEFAULT_ENDPOINT_NAME = "dev";
+const DEFAULT_ENDPOINT_NAME = BUILT_IN_ENDPOINT_ALIASES.app;
 /**
 * Resolve the browser app URL Playwright should target. This is the
 * only helper here that may synchronously read the manifest; callers
@@ -29,14 +31,14 @@ const devstackPlaywrightBaseConfig = (options = {}) => {
 		retries: ci ? 2 : 0,
 		workers: 1,
 		reporter: ci ? [["github"], ["list"]] : "list",
-		globalSetup: options.globalSetup === null ? void 0 : options.globalSetup ?? void 0
+		globalSetup: options.globalSetup === null ? void 0 : options.globalSetup ?? DEFAULT_GLOBAL_SETUP
 	};
 };
 const devstackPlaywrightUse = (options = {}) => ({
 	baseURL: resolveDevstackPlaywrightBaseURL(options),
 	trace: options.trace ?? "on-first-retry",
 	screenshot: options.screenshot ?? "only-on-failure",
-	...options.use ?? {}
+	...options.use
 });
 const devstackPlaywrightProjects = (options = {}) => [{
 	name: "chromium",

package/dist/build-integrations/playwright/config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":[],"sources":["../../../src/build-integrations/playwright/config.ts"],"sourcesContent":["// Playwright config helpers.\n//\n// Architecture (distilled/23-build-integrations.md § Playwright /\n// \"What it produces\"):\n//\n//   Composable pieces for a canonical `PlaywrightTestConfig`\n//   (workers 1, fullyParallel false, `testDir: './e2e'`,\n//   CI-aware reporter/retries/forbidOnly, graceful-shutdown wiring\n//   with a SIGTERM + 10s timeout), plus `webServer` + `baseURL`\n//   low-level resolvers.\n//\n// Load-bearing invariants this module enforces:\n//   - `workers: 1` and `fullyParallel: false` — single supervisor per\n//     stack; parallel tests would contend on shared faucet / wallet\n//     / RPC (distilled § Invariants).\n//   - `webServer.gracefulShutdown` SIGTERM + 10s — without this the\n//     default SIGKILL-on-shell orphans vite + supervisor descendants\n//     holding ports (distilled § Learnings: \"Graceful-shutdown wiring\n//     at the Playwright layer fixed a real bug\").\n//   - `webServer.url` settable at config-load time even with no\n//     manifest — via cold-start fallback to a conventional URL.\n//   - `webServer.reuseExistingServer: !CI` — dev iteration reuses,\n//     CI always boots fresh.\n//\n// This module returns `PlaywrightTestConfig`-shaped fragments. We do\n// NOT import `@playwright/test` at module init: the types are\n// structural and we accept the optional-peer cost rather than\n// importing transitively from a build-integration that must be\n// loadable without `@playwright/test` (matching the Vitest helpers'\n// optional-peer pattern).\n\nimport { type ResolveStackContextOptions, resolveEndpointUrl } from './stack-context.ts';\n\n// -----------------------------------------------------------------------------\n// PlaywrightTestConfig shape (structural; we do NOT import the type\n// directly to keep `@playwright/test` an optional peer)\n// -----------------------------------------------------------------------------\n\ntype PlaywrightReporterShape = [string] | [string, Record<string, unknown>];\n\n/** Base subset of `PlaywrightTestConfig` this surface produces. The\n *  full type lives in `@playwright/test`; we keep this structural so\n *  the helpers compile without the peer. */\nexport interface PlaywrightBaseConfigShape {\n\treadonly testDir: string;\n\treadonly fullyParallel: boolean;\n\treadonly forbidOnly: boolean;\n\treadonly retries: number;\n\treadonly workers: number;\n\treadonly reporter: PlaywrightReporterShape[] | string;\n\treadonly globalSetup?: string;\n\treadonly globalTeardown?: string;\n}\n\nexport type PlaywrightUseConfigShape = {\n\treadonly baseURL: string;\n\treadonly trace: 'on-first-retry' | 'off' | 'retain-on-failure';\n\treadonly screenshot: 'only-on-failure' | 'off' | 'on';\n} & Record<string, unknown>;\n\nexport interface PlaywrightProjectShape {\n\tname: string;\n\tuse: Record<string, unknown>;\n}\n\nexport interface PlaywrightWebServerConfigShape {\n\treadonly command: string;\n\treadonly url: string;\n\treadonly reuseExistingServer: boolean;\n\treadonly timeout: number;\n\treadonly stdout: 'pipe' | 'ignore';\n\treadonly stderr: 'pipe' | 'ignore';\n\treadonly gracefulShutdown: { readonly signal: 'SIGTERM'; readonly timeout: number };\n\treadonly env?: Record<string, string>;\n}\n\n// -----------------------------------------------------------------------------\n// Public option shape\n// -----------------------------------------------------------------------------\n\nexport interface DevstackPlaywrightBaseConfigOptions {\n\t/** Test directory. Default: `'./e2e'` (architecture invariant). */\n\treadonly testDir?: string;\n\n\t/** Path to a global-setup module. Default: not wired. Pass `null`\n\t *  to keep the property omitted when composing conditionally. */\n\treadonly globalSetup?: string | null;\n}\n\nexport interface DevstackPlaywrightEndpointOptions extends ResolveStackContextOptions {\n\t/** Endpoint name whose URL becomes `webServer.url` + `use.baseURL`.\n\t *  Default: `'dev'` (the host-service dev server endpoint). */\n\treadonly endpointName?: string;\n\n\t/** Explicit baseURL override. When set, manifest discovery is\n\t *  bypassed entirely. */\n\treadonly baseURL?: string;\n}\n\nexport interface DevstackPlaywrightWebServerOptions extends DevstackPlaywrightEndpointOptions {\n\t/** Command Playwright runs to bring up the stack. Default:\n\t *  `'pnpm dev'`. */\n\treadonly command?: string;\n\n\t/** Hard cap (ms) for `webServer` URL to become reachable. Default:\n\t *  300_000 (5 min) — accounts for cold supervisor boot under\n\t *  Docker pulls. */\n\treadonly webServerTimeoutMs?: number;\n\n\t/** Hard cap (ms) for `webServer.gracefulShutdown`. Default: 10_000\n\t *  (10 s) — load-bearing per architecture § Invariants. */\n\treadonly gracefulShutdownTimeoutMs?: number;\n\n\t/** Extra env to forward to `webServer.command`. Merged after the\n\t *  preset's own env (PLAYWRIGHT=1, DEVSTACK_STACK). */\n\treadonly env?: Record<string, string>;\n}\n\nexport interface DevstackPlaywrightProjectsOptions {\n\t/** Extra Playwright projects to append to the default Chromium\n\t *  project. */\n\treadonly projects?: ReadonlyArray<PlaywrightProjectShape>;\n}\n\nexport interface DevstackPlaywrightUseOptions extends DevstackPlaywrightEndpointOptions {\n\treadonly trace?: PlaywrightUseConfigShape['trace'];\n\treadonly screenshot?: PlaywrightUseConfigShape['screenshot'];\n\treadonly use?: Omit<Partial<PlaywrightUseConfigShape>, 'baseURL'>;\n}\n\n// -----------------------------------------------------------------------------\n// Defaults\n// -----------------------------------------------------------------------------\n\nconst DEFAULT_TEST_DIR = './e2e';\nconst DEFAULT_COMMAND = 'pnpm dev';\nconst DEFAULT_WEBSERVER_TIMEOUT_MS = 300_000;\nconst DEFAULT_GRACEFUL_SHUTDOWN_MS = 10_000;\nconst DEFAULT_ENDPOINT_NAME = 'dev';\n\n// -----------------------------------------------------------------------------\n// Builders\n// -----------------------------------------------------------------------------\n\n/**\n * Resolve the browser app URL Playwright should target. This is the\n * only helper here that may synchronously read the manifest; callers\n * can pass `baseURL` to bypass discovery entirely.\n */\nexport const resolveDevstackPlaywrightBaseURL = (\n\toptions: DevstackPlaywrightEndpointOptions = {},\n): string => {\n\tconst endpointName = options.endpointName ?? DEFAULT_ENDPOINT_NAME;\n\treturn (\n\t\toptions.baseURL ??\n\t\tresolveEndpointUrl(endpointName, {\n\t\t\t...(options.cwd !== undefined ? { cwd: options.cwd } : {}),\n\t\t\t...(options.manifestPath !== undefined ? { manifestPath: options.manifestPath } : {}),\n\t\t\t...(options.stack !== undefined ? { stack: options.stack } : {}),\n\t\t\t...(options.stateDir !== undefined ? { stateDir: options.stateDir } : {}),\n\t\t\t...(options.env !== undefined ? { env: options.env } : {}),\n\t\t}).url\n\t);\n};\n\nexport const devstackPlaywrightBaseConfig = (\n\toptions: DevstackPlaywrightBaseConfigOptions = {},\n): PlaywrightBaseConfigShape => {\n\tconst ci = Boolean(process.env.CI);\n\treturn {\n\t\ttestDir: options.testDir ?? DEFAULT_TEST_DIR,\n\t\tfullyParallel: false,\n\t\tforbidOnly: ci,\n\t\tretries: ci ? 2 : 0,\n\t\tworkers: 1,\n\t\treporter: ci ? [['github'], ['list']] : 'list',\n\t\tglobalSetup: options.globalSetup === null ? undefined : (options.globalSetup ?? undefined),\n\t};\n};\n\nexport const devstackPlaywrightUse = (\n\toptions: DevstackPlaywrightUseOptions = {},\n): PlaywrightUseConfigShape => ({\n\tbaseURL: resolveDevstackPlaywrightBaseURL(options),\n\ttrace: options.trace ?? 'on-first-retry',\n\tscreenshot: options.screenshot ?? 'only-on-failure',\n\t...(options.use ?? {}),\n});\n\nexport const devstackPlaywrightProjects = (\n\toptions: DevstackPlaywrightProjectsOptions = {},\n): PlaywrightProjectShape[] => [\n\t{\n\t\tname: 'chromium',\n\t\tuse: { browserName: 'chromium' },\n\t},\n\t...(options.projects ?? []),\n];\n\nexport const devstackPlaywrightWebServer = (\n\toptions: DevstackPlaywrightWebServerOptions = {},\n): PlaywrightWebServerConfigShape => {\n\tconst env = options.env ? { ...options.env } : {};\n\tconst ci = Boolean(process.env.CI);\n\tconst baseURL = resolveDevstackPlaywrightBaseURL(options);\n\tconst presetEnv: Record<string, string> = {\n\t\tPLAYWRIGHT: '1',\n\t\t...(options.stack !== undefined ? { DEVSTACK_STACK: options.stack } : {}),\n\t\t...env,\n\t};\n\n\treturn {\n\t\tcommand: options.command ?? DEFAULT_COMMAND,\n\t\turl: baseURL,\n\t\treuseExistingServer: !ci,\n\t\ttimeout: options.webServerTimeoutMs ?? DEFAULT_WEBSERVER_TIMEOUT_MS,\n\t\tstdout: 'pipe',\n\t\tstderr: 'pipe',\n\t\tgracefulShutdown: {\n\t\t\tsignal: 'SIGTERM',\n\t\t\ttimeout: options.gracefulShutdownTimeoutMs ?? DEFAULT_GRACEFUL_SHUTDOWN_MS,\n\t\t},\n\t\tenv: presetEnv,\n\t};\n};\n"],"mappings":";;AAsIA,MAAM,mBAAmB;AACzB,MAAM,kBAAkB;AACxB,MAAM,+BAA+B;AACrC,MAAM,+BAA+B;AACrC,MAAM,wBAAwB;;;;;;AAW9B,MAAa,oCACZ,UAA6C,EAAE,KACnC;CACZ,MAAM,eAAe,QAAQ,gBAAgB;AAC7C,QACC,QAAQ,WACR,mBAAmB,cAAc;EAChC,GAAI,QAAQ,QAAQ,KAAA,IAAY,EAAE,KAAK,QAAQ,KAAK,GAAG,EAAE;EACzD,GAAI,QAAQ,iBAAiB,KAAA,IAAY,EAAE,cAAc,QAAQ,cAAc,GAAG,EAAE;EACpF,GAAI,QAAQ,UAAU,KAAA,IAAY,EAAE,OAAO,QAAQ,OAAO,GAAG,EAAE;EAC/D,GAAI,QAAQ,aAAa,KAAA,IAAY,EAAE,UAAU,QAAQ,UAAU,GAAG,EAAE;EACxE,GAAI,QAAQ,QAAQ,KAAA,IAAY,EAAE,KAAK,QAAQ,KAAK,GAAG,EAAE;EACzD,CAAC,CAAC;;AAIL,MAAa,gCACZ,UAA+C,EAAE,KAClB;CAC/B,MAAM,KAAK,QAAQ,QAAQ,IAAI,GAAG;AAClC,QAAO;EACN,SAAS,QAAQ,WAAW;EAC5B,eAAe;EACf,YAAY;EACZ,SAAS,KAAK,IAAI;EAClB,SAAS;EACT,UAAU,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,GAAG;EACxC,aAAa,QAAQ,gBAAgB,OAAO,KAAA,IAAa,QAAQ,eAAe,KAAA;EAChF;;AAGF,MAAa,yBACZ,UAAwC,EAAE,MACX;CAC/B,SAAS,iCAAiC,QAAQ;CAClD,OAAO,QAAQ,SAAS;CACxB,YAAY,QAAQ,cAAc;CAClC,GAAI,QAAQ,OAAO,EAAE;CACrB;AAED,MAAa,8BACZ,UAA6C,EAAE,KACjB,CAC9B;CACC,MAAM;CACN,KAAK,EAAE,aAAa,YAAY;CAChC,EACD,GAAI,QAAQ,YAAY,EAAE,CAC1B;AAED,MAAa,+BACZ,UAA8C,EAAE,KACZ;CACpC,MAAM,MAAM,QAAQ,MAAM,EAAE,GAAG,QAAQ,KAAK,GAAG,EAAE;CACjD,MAAM,KAAK,QAAQ,QAAQ,IAAI,GAAG;CAClC,MAAM,UAAU,iCAAiC,QAAQ;CACzD,MAAM,YAAoC;EACzC,YAAY;EACZ,GAAI,QAAQ,UAAU,KAAA,IAAY,EAAE,gBAAgB,QAAQ,OAAO,GAAG,EAAE;EACxE,GAAG;EACH;AAED,QAAO;EACN,SAAS,QAAQ,WAAW;EAC5B,KAAK;EACL,qBAAqB,CAAC;EACtB,SAAS,QAAQ,sBAAsB;EACvC,QAAQ;EACR,QAAQ;EACR,kBAAkB;GACjB,QAAQ;GACR,SAAS,QAAQ,6BAA6B;GAC9C;EACD,KAAK;EACL"}
+{"version":3,"file":"config.mjs","names":[],"sources":["../../../src/build-integrations/playwright/config.ts"],"sourcesContent":["// Playwright config helpers.\n//\n// Architecture (distilled/23-build-integrations.md § Playwright /\n// \"What it produces\"):\n//\n//   Composable pieces for a canonical `PlaywrightTestConfig`\n//   (workers 1, fullyParallel false, `testDir: './e2e'`,\n//   CI-aware reporter/retries/forbidOnly, graceful-shutdown wiring\n//   with a SIGTERM + 10s timeout), plus `webServer` + `baseURL`\n//   low-level resolvers.\n//\n// Load-bearing invariants this module enforces:\n//   - `workers: 1` and `fullyParallel: false` — single supervisor per\n//     stack; parallel tests would contend on shared faucet / wallet\n//     / RPC (distilled § Invariants).\n//   - `webServer.gracefulShutdown` SIGTERM + 10s — without this the\n//     default SIGKILL-on-shell orphans vite + supervisor descendants\n//     holding ports (distilled § Learnings: \"Graceful-shutdown wiring\n//     at the Playwright layer fixed a real bug\").\n//   - `webServer.url` settable at config-load time even with no\n//     manifest — via cold-start fallback to a conventional URL.\n//   - `webServer.reuseExistingServer: !CI` — dev iteration reuses,\n//     CI always boots fresh.\n//\n// This module returns `PlaywrightTestConfig`-shaped fragments. We do\n// NOT import `@playwright/test` at module init: the types are\n// structural and we accept the optional-peer cost rather than\n// importing transitively from a build-integration that must be\n// loadable without `@playwright/test` (matching the Vitest helpers'\n// optional-peer pattern).\n\nimport { BUILT_IN_ENDPOINT_ALIASES } from '../runtime/conventional-routes.ts';\nimport { type ResolveStackContextOptions, resolveEndpointUrl } from './stack-context.ts';\n\n// -----------------------------------------------------------------------------\n// PlaywrightTestConfig shape (structural; we do NOT import the type\n// directly to keep `@playwright/test` an optional peer)\n// -----------------------------------------------------------------------------\n\ntype PlaywrightReporterShape = [string] | [string, Record<string, unknown>];\ntype PlaywrightGlobalSetupShape = string | string[];\n\nconst DEFAULT_GLOBAL_SETUP = '@mysten-incubation/devstack/playwright/global-setup';\n\n/** Base subset of `PlaywrightTestConfig` this surface produces. The\n *  full type lives in `@playwright/test`; we keep this structural so\n *  the helpers compile without the peer. */\nexport interface PlaywrightBaseConfigShape {\n\treadonly testDir: string;\n\treadonly fullyParallel: boolean;\n\treadonly forbidOnly: boolean;\n\treadonly retries: number;\n\treadonly workers: number;\n\treadonly reporter: PlaywrightReporterShape[] | string;\n\treadonly globalSetup?: PlaywrightGlobalSetupShape;\n\treadonly globalTeardown?: string;\n}\n\nexport type PlaywrightUseConfigShape = {\n\treadonly baseURL: string;\n\treadonly trace: 'on-first-retry' | 'off' | 'retain-on-failure';\n\treadonly screenshot: 'only-on-failure' | 'off' | 'on';\n} & Record<string, unknown>;\n\nexport interface PlaywrightProjectShape {\n\tname: string;\n\tuse: Record<string, unknown>;\n}\n\nexport interface PlaywrightWebServerConfigShape {\n\treadonly command: string;\n\treadonly url: string;\n\treadonly reuseExistingServer: boolean;\n\treadonly timeout: number;\n\treadonly stdout: 'pipe' | 'ignore';\n\treadonly stderr: 'pipe' | 'ignore';\n\treadonly gracefulShutdown: { readonly signal: 'SIGTERM'; readonly timeout: number };\n\treadonly env?: Record<string, string>;\n}\n\n// -----------------------------------------------------------------------------\n// Public option shape\n// -----------------------------------------------------------------------------\n\nexport interface DevstackPlaywrightBaseConfigOptions {\n\t/** Test directory. Default: `'./e2e'` (architecture invariant). */\n\treadonly testDir?: string;\n\n\t/** Path to a global-setup module. Default: the devstack setup that\n\t *  waits for post-acquire codegen before specs load the app. Pass\n\t *  `null` to keep the property omitted when composing conditionally. */\n\treadonly globalSetup?: PlaywrightGlobalSetupShape | null;\n}\n\nexport interface DevstackPlaywrightEndpointOptions extends ResolveStackContextOptions {\n\t/** Endpoint name whose URL becomes `webServer.url` + `use.baseURL`.\n\t *  Default: `'dev'` (the host-service dev server endpoint). */\n\treadonly endpointName?: string;\n\n\t/** Explicit baseURL override. When set, manifest discovery is\n\t *  bypassed entirely. */\n\treadonly baseURL?: string;\n}\n\nexport interface DevstackPlaywrightWebServerOptions extends DevstackPlaywrightEndpointOptions {\n\t/** Command Playwright runs to bring up the stack. Default:\n\t *  `'pnpm dev'`. */\n\treadonly command?: string;\n\n\t/** Hard cap (ms) for `webServer` URL to become reachable. Default:\n\t *  300_000 (5 min) — accounts for cold supervisor boot under\n\t *  Docker pulls. */\n\treadonly webServerTimeoutMs?: number;\n\n\t/** Hard cap (ms) for `webServer.gracefulShutdown`. Default: 10_000\n\t *  (10 s) — load-bearing per architecture § Invariants. */\n\treadonly gracefulShutdownTimeoutMs?: number;\n\n\t/** Extra env to forward to `webServer.command`. Merged after the\n\t *  preset's own env (PLAYWRIGHT=1, DEVSTACK_STACK). */\n\treadonly env?: Record<string, string>;\n}\n\nexport interface DevstackPlaywrightProjectsOptions {\n\t/** Extra Playwright projects to append to the default Chromium\n\t *  project. */\n\treadonly projects?: ReadonlyArray<PlaywrightProjectShape>;\n}\n\nexport interface DevstackPlaywrightUseOptions extends DevstackPlaywrightEndpointOptions {\n\treadonly trace?: PlaywrightUseConfigShape['trace'];\n\treadonly screenshot?: PlaywrightUseConfigShape['screenshot'];\n\treadonly use?: Omit<Partial<PlaywrightUseConfigShape>, 'baseURL'>;\n}\n\n// -----------------------------------------------------------------------------\n// Defaults\n// -----------------------------------------------------------------------------\n\nconst DEFAULT_TEST_DIR = './e2e';\nconst DEFAULT_COMMAND = 'pnpm dev';\nconst DEFAULT_WEBSERVER_TIMEOUT_MS = 300_000;\nconst DEFAULT_GRACEFUL_SHUTDOWN_MS = 10_000;\nconst DEFAULT_ENDPOINT_NAME = BUILT_IN_ENDPOINT_ALIASES.app;\n\n// -----------------------------------------------------------------------------\n// Builders\n// -----------------------------------------------------------------------------\n\n/**\n * Resolve the browser app URL Playwright should target. This is the\n * only helper here that may synchronously read the manifest; callers\n * can pass `baseURL` to bypass discovery entirely.\n */\nexport const resolveDevstackPlaywrightBaseURL = (\n\toptions: DevstackPlaywrightEndpointOptions = {},\n): string => {\n\tconst endpointName = options.endpointName ?? DEFAULT_ENDPOINT_NAME;\n\treturn (\n\t\toptions.baseURL ??\n\t\tresolveEndpointUrl(endpointName, {\n\t\t\t...(options.cwd !== undefined ? { cwd: options.cwd } : {}),\n\t\t\t...(options.manifestPath !== undefined ? { manifestPath: options.manifestPath } : {}),\n\t\t\t...(options.stack !== undefined ? { stack: options.stack } : {}),\n\t\t\t...(options.stateDir !== undefined ? { stateDir: options.stateDir } : {}),\n\t\t\t...(options.env !== undefined ? { env: options.env } : {}),\n\t\t}).url\n\t);\n};\n\nexport const devstackPlaywrightBaseConfig = (\n\toptions: DevstackPlaywrightBaseConfigOptions = {},\n): PlaywrightBaseConfigShape => {\n\tconst ci = Boolean(process.env.CI);\n\treturn {\n\t\ttestDir: options.testDir ?? DEFAULT_TEST_DIR,\n\t\tfullyParallel: false,\n\t\tforbidOnly: ci,\n\t\tretries: ci ? 2 : 0,\n\t\tworkers: 1,\n\t\treporter: ci ? [['github'], ['list']] : 'list',\n\t\tglobalSetup:\n\t\t\toptions.globalSetup === null ? undefined : (options.globalSetup ?? DEFAULT_GLOBAL_SETUP),\n\t};\n};\n\nexport const devstackPlaywrightUse = (\n\toptions: DevstackPlaywrightUseOptions = {},\n): PlaywrightUseConfigShape => ({\n\tbaseURL: resolveDevstackPlaywrightBaseURL(options),\n\ttrace: options.trace ?? 'on-first-retry',\n\tscreenshot: options.screenshot ?? 'only-on-failure',\n\t...options.use,\n});\n\nexport const devstackPlaywrightProjects = (\n\toptions: DevstackPlaywrightProjectsOptions = {},\n): PlaywrightProjectShape[] => [\n\t{\n\t\tname: 'chromium',\n\t\tuse: { browserName: 'chromium' },\n\t},\n\t...(options.projects ?? []),\n];\n\nexport const devstackPlaywrightWebServer = (\n\toptions: DevstackPlaywrightWebServerOptions = {},\n): PlaywrightWebServerConfigShape => {\n\tconst env = options.env ? { ...options.env } : {};\n\tconst ci = Boolean(process.env.CI);\n\tconst baseURL = resolveDevstackPlaywrightBaseURL(options);\n\tconst presetEnv: Record<string, string> = {\n\t\tPLAYWRIGHT: '1',\n\t\t...(options.stack !== undefined ? { DEVSTACK_STACK: options.stack } : {}),\n\t\t...env,\n\t};\n\n\treturn {\n\t\tcommand: options.command ?? DEFAULT_COMMAND,\n\t\turl: baseURL,\n\t\treuseExistingServer: !ci,\n\t\ttimeout: options.webServerTimeoutMs ?? DEFAULT_WEBSERVER_TIMEOUT_MS,\n\t\tstdout: 'pipe',\n\t\tstderr: 'pipe',\n\t\tgracefulShutdown: {\n\t\t\tsignal: 'SIGTERM',\n\t\t\ttimeout: options.gracefulShutdownTimeoutMs ?? DEFAULT_GRACEFUL_SHUTDOWN_MS,\n\t\t},\n\t\tenv: presetEnv,\n\t};\n};\n"],"mappings":";;;AA0CA,MAAM,uBAAuB;AAiG7B,MAAM,mBAAmB;AACzB,MAAM,kBAAkB;AACxB,MAAM,+BAA+B;AACrC,MAAM,+BAA+B;AACrC,MAAM,wBAAwB,0BAA0B;;;;;;AAWxD,MAAa,oCACZ,UAA6C,EAAE,KACnC;CACZ,MAAM,eAAe,QAAQ,gBAAgB;AAC7C,QACC,QAAQ,WACR,mBAAmB,cAAc;EAChC,GAAI,QAAQ,QAAQ,KAAA,IAAY,EAAE,KAAK,QAAQ,KAAK,GAAG,EAAE;EACzD,GAAI,QAAQ,iBAAiB,KAAA,IAAY,EAAE,cAAc,QAAQ,cAAc,GAAG,EAAE;EACpF,GAAI,QAAQ,UAAU,KAAA,IAAY,EAAE,OAAO,QAAQ,OAAO,GAAG,EAAE;EAC/D,GAAI,QAAQ,aAAa,KAAA,IAAY,EAAE,UAAU,QAAQ,UAAU,GAAG,EAAE;EACxE,GAAI,QAAQ,QAAQ,KAAA,IAAY,EAAE,KAAK,QAAQ,KAAK,GAAG,EAAE;EACzD,CAAC,CAAC;;AAIL,MAAa,gCACZ,UAA+C,EAAE,KAClB;CAC/B,MAAM,KAAK,QAAQ,QAAQ,IAAI,GAAG;AAClC,QAAO;EACN,SAAS,QAAQ,WAAW;EAC5B,eAAe;EACf,YAAY;EACZ,SAAS,KAAK,IAAI;EAClB,SAAS;EACT,UAAU,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,GAAG;EACxC,aACC,QAAQ,gBAAgB,OAAO,KAAA,IAAa,QAAQ,eAAe;EACpE;;AAGF,MAAa,yBACZ,UAAwC,EAAE,MACX;CAC/B,SAAS,iCAAiC,QAAQ;CAClD,OAAO,QAAQ,SAAS;CACxB,YAAY,QAAQ,cAAc;CAClC,GAAG,QAAQ;CACX;AAED,MAAa,8BACZ,UAA6C,EAAE,KACjB,CAC9B;CACC,MAAM;CACN,KAAK,EAAE,aAAa,YAAY;CAChC,EACD,GAAI,QAAQ,YAAY,EAAE,CAC1B;AAED,MAAa,+BACZ,UAA8C,EAAE,KACZ;CACpC,MAAM,MAAM,QAAQ,MAAM,EAAE,GAAG,QAAQ,KAAK,GAAG,EAAE;CACjD,MAAM,KAAK,QAAQ,QAAQ,IAAI,GAAG;CAClC,MAAM,UAAU,iCAAiC,QAAQ;CACzD,MAAM,YAAoC;EACzC,YAAY;EACZ,GAAI,QAAQ,UAAU,KAAA,IAAY,EAAE,gBAAgB,QAAQ,OAAO,GAAG,EAAE;EACxE,GAAG;EACH;AAED,QAAO;EACN,SAAS,QAAQ,WAAW;EAC5B,KAAK;EACL,qBAAqB,CAAC;EACtB,SAAS,QAAQ,sBAAsB;EACvC,QAAQ;EACR,QAAQ;EACR,kBAAkB;GACjB,QAAQ;GACR,SAAS,QAAQ,6BAA6B;GAC9C;EACD,KAAK;EACL"}

package/dist/build-integrations/playwright/errors.d.mts

@@ -1,5 +1,5 @@
-import * as _$effect_Types0 from "effect/Types";
 import * as _$effect_Cause0 from "effect/Cause";
+import * as _$effect_Types0 from "effect/Types";
 
 //#region src/build-integrations/playwright/errors.d.ts
 declare const PlaywrightManifestDiscoveryError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {

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

@@ -1,4 +1,6 @@
+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 | (() =>
@@ -6,25 +8,28 @@ import { ResolveStackContextOptions } from "./stack-context.mjs";
  *  without `@playwright/test`. */
 type PlaywrightGlobalSetup = () => Promise<void | (() => Promise<void>)>;
 /**
- * The shape global-setup writes to disk for in-spec tests to read.
- * Tests do NOT re-walk-up to find the manifest at every assertion —
- * they read this prepared fixture, which is faster and avoids a
- * subtle cwd-mismatch class of failure when Playwright runs tests
+ * 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.
  *
- * The fixture is written to a Playwright-known path (resolved from
- * env Playwright populates) so worker processes pick it up. The
- * setup also stamps `DEVSTACK_MANIFEST_PATH` into the worker env so
- * `wallet-context` can reach the file without re-running discovery.
+ * 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.
  */
-interface PlaywrightStackFixture {
-  readonly endpoints: Readonly<Record<string, string>>;
-  readonly walletEndpoint: string | null;
-  readonly manifestPath: string;
-  readonly stack: string;
-  readonly app: string;
-}
+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`
@@ -46,19 +51,40 @@ interface DefineGlobalSetupOptions extends ResolveStackContextOptions {
    */
   readonly preloadContext?: boolean;
 }
+/**
+ * @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).
  */
 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. */
+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. */
+ *  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, readStashedFixture };
+export { DefineGlobalSetupOptions, PlaywrightGlobalSetup, PlaywrightStackFixture, STACK_CONTEXT_SLOT, buildGlobalSetup, decodeWatchedRecord, _default as default, readStashedFixture };
 //# sourceMappingURL=global-setup.d.mts.map

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

@@ -1,5 +1,223 @@
-import { readStackContext } from "./stack-context.mjs";
+import { WALLET_ENDPOINT_KEY } from "../../contracts/wallet-protocol.mjs";
+import { resolveDiscoveryEnv } from "../runtime/resolve-discovery-env.mjs";
+import { discoverSingleStackManifestPath } from "../runtime/discover.mjs";
+import "../runtime/wallet-paths.mjs";
+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";
 //#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 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 } : {} });
+	return discoverSingleStackManifestPath({
+		...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+		stateDir
+	});
+};
+const readContextForSetup = (options) => {
+	try {
+		return readStackContext(options);
+	} catch (cause) {
+		if (!(cause instanceof PlaywrightManifestDiscoveryError)) throw cause;
+		const inferredManifestPath = findSingleStackManifestPath(options);
+		if (inferredManifestPath === null) throw cause;
+		return readStackContext({
+			...options,
+			manifestPath: inferredManifestPath
+		});
+	}
+};
+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;
+};
+/**
+* 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
@@ -7,7 +225,7 @@ import { readStackContext } from "./stack-context.mjs";
 */
 const buildGlobalSetup = (options = {}) => {
 	return async () => {
-		const ctx = readStackContext(options);
+		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.`);
 		}
@@ -18,27 +236,46 @@ const buildGlobalSetup = (options = {}) => {
 		if (options.preloadContext ?? true) stashStackContext(ctx);
 	};
 };
-buildGlobalSetup();
+/** 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. */
-const STACK_CONTEXT_SLOT = "__devstackPlaywrightStackContext__";
+*  to avoid a second disk read. Re-exported from the runtime slot
+*  module so consumers can import either side. */
+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)]));
+	for (const [alias, canonical] of Object.entries(BUILT_IN_ENDPOINT_ALIASES)) {
+		if (alias in endpoints) continue;
+		const url = endpoints[canonical];
+		if (url !== void 0) endpoints[alias] = url;
+	}
+	stashGeneration += 1;
 	const fixture = {
-		endpoints: Object.fromEntries(ctx.endpointNames.map((name) => [name, ctx.endpoint(name)])),
-		walletEndpoint: ctx.endpointMaybe("wallet"),
+		endpoints,
+		walletEndpoint: ctx.endpointMaybe(WALLET_ENDPOINT_KEY),
 		manifestPath: ctx.manifestPath,
 		stack: ctx.manifest.identity.stack,
-		app: ctx.manifest.identity.app
+		app: ctx.manifest.identity.app,
+		generation: stashGeneration
 	};
-	globalThis[STACK_CONTEXT_SLOT] = fixture;
+	const previous = globalThis[PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY];
+	if (previous !== void 0) try {
+		process.stderr.write(`[devstack/playwright] global-setup re-ran (generation ${previous.generation} → ${fixture.generation}); downstream consumers should re-read globalThis[${PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY}].\n`);
+	} 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`). */
-const readStashedFixture = () => {
-	return globalThis["__devstackPlaywrightStackContext__"] ?? null;
-};
+const readStashedFixture = () => globalThis["__devstackPlaywrightStackContext__"] ?? null;
 //#endregion
-export { STACK_CONTEXT_SLOT, buildGlobalSetup, readStashedFixture };
+export { STACK_CONTEXT_SLOT, buildGlobalSetup, decodeWatchedRecord, global_setup_default as default, readStashedFixture };
 
 //# sourceMappingURL=global-setup.mjs.map