@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/api/run-stack.mjs

@@ -1,153 +1,34 @@
-import { readStackEngine } from "./define-devstack.mjs";
-import { appName, chainId, stackName } from "../substrate/brand.mjs";
-import "../substrate/runtime/capability-sinks/index.mjs";
-import { makeProjectionRefSync } from "../substrate/runtime/projection/state-ref.mjs";
-import "../substrate/runtime/index.mjs";
-import { buildSubstrateLayers, superviseStackEffect } from "../orchestrators/run.mjs";
-import { buildProductionOrchestratorSinks, buildProductionPostAcquireHook, layerProductionOrchestrators } from "../orchestrators/runtime-composition.mjs";
-import { resolveCodegenOutput } from "../orchestrators/codegen/output-location.mjs";
-import { extendBuiltInPluginContext, layerBuiltInPluginRuntime } from "../orchestrators/built-in-plugin-layers.mjs";
-import { resolveAppName, resolveNetworkSync, resolveStackName, resolveStateDir } from "./inference-network.mjs";
-import { Cause, Deferred, Effect, Exit, Fiber, Layer, Logger, Queue, Ref, Stream } from "effect";
+import { runStackWithBoot } from "./run-stack-internal.mjs";
 //#region src/api/run-stack.ts
-const resolveIdentity = (stack, opts, cwd) => {
-	const app = resolveAppName({
-		explicit: opts?.app,
-		cwd
-	});
-	const stackNameStr = resolveStackName({
-		explicit: opts?.stack ?? stack.options.stackName,
-		cwd
-	});
-	const resolved = resolveNetworkSync({
-		explicit: opts?.network,
-		env: process.env.DEVSTACK_NETWORK,
-		explicitSource: "runStack({ identity.network })"
-	});
-	return {
-		app: appName(app),
-		stack: stackName(stackNameStr),
-		chain: chainId(resolved.raw)
-	};
-};
-const toBootError = (cause) => ({
-	_tag: "BootError",
-	cause
-});
 /**
 * Boot a `Stack` for programmatic embedding. Returns a `RunHandle`
 * synchronously; the supervisor fiber is forked on `start`.
 *
-* Lifecycle:
+* Programmatic contract — call, then drive the returned handle's Effects:
 *
-*   1. `runStack(stack, opts)` — synchronous; no fiber forked yet.
-*   2. `await Effect.runPromise(handle.start)` — forks the supervisor,
-*      blocks until every plugin reaches `ready` (or fails with
-*      `BootError`).
-*   3. Use `handle.events` / `handle.state` to observe.
+*   1. `runStack(stack, opts)` — synchronous; NO fiber forked yet. Safe to
+*      read `handle.identity` and subscribe to `handle.state` /
+*      `handle.events` right away.
+*   2. `await Effect.runPromise(handle.start)` — forks the supervisor and
+*      blocks until every plugin reaches `ready` (or fails with `BootError`).
+*   3. Observe via `handle.state` (snapshot / changes) and `handle.events`
+*      (single-consumer tail); drive via `handle.commands` /
+*      `handle.runCommand`.
 *   4. `await Effect.runPromise(handle.stop)` — graceful shutdown.
-*   5. `handle.awaitShutdown` resolves once finalizers complete.
+*   5. `await Effect.runPromise(handle.awaitShutdown)` — resolves once scope
+*      finalizers complete (or re-raises a post-boot supervisor death).
 *
-* Internal architecture: the handle stores a `Deferred` for boot
-* completion. The supervised body forks a watcher fiber over the
-* registry's `awaitReady` per node; once every node is `ready` (or one
-* fails) the deferred completes. `start` awaits it.
+* Thin facade: delegates to `runStackWithBoot` (in `run-stack-internal.ts`)
+* with a zero-`boot` bag and no `commandHandler`, so this public path is
+* byte-identical to the pre-seam `runStack` body. The boot-injection seam
+* the CLI `up` verb consumes is non-public — it is NOT re-exported from
+* `index.ts`, and its substrate types never appear on `RunHandle`.
 */
-const runStack = (stack, opts = {}) => {
-	const engineStack = readStackEngine(stack);
-	const runtimeRoot = resolveStateDir({
-		runtimeRoot: opts.runtimeRoot,
-		stateDir: opts.stateDir ?? engineStack.options.stateDir,
-		env: process.env.DEVSTACK_STATE_DIR,
-		cwd: process.cwd()
-	});
-	const appRoot = opts.appRoot ?? process.cwd();
-	const identity = resolveIdentity(stack, opts.identity, appRoot);
-	const codegen = opts.codegen ?? engineStack.options.codegen;
-	const supervisedStack = {
-		_tag: "Stack",
-		members: engineStack.members,
-		options: engineStack.options
-	};
-	const state = makeProjectionRefSync();
-	const bootDeferred = Effect.runSync(Deferred.make());
-	const stopRequested = Effect.runSync(Deferred.make());
-	const eventQueueRef = Effect.runSync(Deferred.make());
-	const fiberRef = Effect.runSync(Deferred.make());
-	const startClaim = Effect.runSync(Ref.make(false));
-	const midRunCauseRef = Effect.runSync(Ref.make(null));
-	const codegenOutput = resolveCodegenOutput({
-		appRoot,
-		effectiveStack: String(identity.stack),
-		primaryStack: engineStack.options.stackName,
-		explicitOutputDir: codegen?.outputDir,
-		explicitStackSubdir: codegen?.stackSubdir ?? null
-	});
-	const substrate = layerProductionOrchestrators({ codegen: {
-		appRoot,
-		outputDir: codegenOutput.outputDir,
-		stackSubdir: codegenOutput.stackSubdir
-	} }).pipe(Layer.provideMerge(buildSubstrateLayers(identity, runtimeRoot)));
-	const supervised = Effect.gen(function* () {
-		const orchestratorSinks = yield* buildProductionOrchestratorSinks();
-		yield* superviseStackEffect(supervisedStack, identity, state, {
-			orchestratorSinks,
-			postAcquireHook: yield* buildProductionPostAcquireHook({ extras: stack.options.extras }),
-			extendContext: (ctx) => Effect.gen(function* () {
-				const builtInContext = yield* extendBuiltInPluginContext(ctx);
-				return opts.extendContext === void 0 ? builtInContext : yield* opts.extendContext(builtInContext);
-			}),
-			beforeInitialAcquire: (handle) => Effect.gen(function* () {
-				yield* Deferred.succeed(eventQueueRef, handle.events).pipe(Effect.catch(() => Effect.void));
-				yield* Effect.forkScoped(Effect.gen(function* () {
-					yield* Deferred.await(stopRequested);
-					yield* Queue.offer(handle.commands, { tag: "shutdown.requested" });
-				}));
-			}),
-			withinScope: (handle) => Effect.gen(function* () {
-				yield* Effect.forkScoped(Effect.gen(function* () {
-					const firstFailure = (yield* Effect.forEach(handle.graph.nodes, ([key]) => handle.registry.awaitReady(key).pipe(Effect.exit), { concurrency: "unbounded" })).find(Exit.isFailure);
-					if (firstFailure === void 0) yield* Deferred.succeed(bootDeferred, void 0);
-					else yield* Deferred.fail(bootDeferred, toBootError(firstFailure.cause));
-				}));
-			})
-		}).pipe(Effect.provide(layerBuiltInPluginRuntime(orchestratorSinks)));
-	});
-	const loggerLayer = Logger.layer([]);
-	const supervisedProgram = supervised.pipe(Effect.provide(substrate), Effect.provide(loggerLayer)).pipe(Effect.catchCause((cause) => Effect.gen(function* () {
-		const bootAlreadyCompleted = yield* Deferred.isDone(bootDeferred);
-		yield* Deferred.fail(bootDeferred, toBootError(cause)).pipe(Effect.asVoid, Effect.catch(() => Effect.void));
-		if (bootAlreadyCompleted) yield* Ref.set(midRunCauseRef, cause);
-		yield* Effect.logError(`devstack runStack: supervisor died\n${Cause.pretty(cause)}`);
-	})));
-	return {
-		start: Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
-			if (yield* Ref.modify(startClaim, (started) => started ? [false, true] : [true, true])) {
-				const fiber = yield* Effect.forkDetach(supervisedProgram);
-				yield* Deferred.succeed(fiberRef, fiber);
-			}
-			yield* restore(Deferred.await(bootDeferred));
-		})),
-		stop: Effect.gen(function* () {
-			yield* Deferred.succeed(stopRequested, void 0).pipe(Effect.catch(() => Effect.void));
-			if (!(yield* Deferred.isDone(fiberRef))) return;
-			const fiber = yield* Deferred.await(fiberRef);
-			yield* Fiber.await(fiber);
-		}),
-		awaitShutdown: Effect.gen(function* () {
-			if (!(yield* Deferred.isDone(fiberRef))) return;
-			const fiber = yield* Deferred.await(fiberRef);
-			yield* Fiber.await(fiber);
-			const midRunCause = yield* Ref.get(midRunCauseRef);
-			if (midRunCause !== null) return yield* Effect.failCause(midRunCause);
-		}),
-		events: Stream.unwrap(Effect.gen(function* () {
-			const queue = yield* Deferred.await(eventQueueRef);
-			return Stream.fromQueue(queue);
-		})),
-		state
-	};
-};
+const runStack = (stack, opts = {}) => runStackWithBoot(stack, {
+	...opts,
+	commandHandler: void 0,
+	boot: void 0
+});
 //#endregion
 export { runStack };
 

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// `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: primary run (effective\n\t// stack === config `stackName`) → `src/generated/`; a secondary\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// primary 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\tprimaryStack: 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":";;;;;;;;;;;;AAgJA,MAAM,mBACL,OACA,MACA,QACc;CACd,MAAM,MAAM,eAAe;EAC1B,UAAU,MAAM;EAChB;EACA,CAAC;CACF,MAAM,eAAe,iBAAiB;EACrC,UAAU,MAAM,SAAS,MAAM,QAAQ;EACvC;EACA,CAAC;CAMF,MAAM,WAAW,mBAAmB;EACnC,UAAU,MAAM;EAChB,KAAK,QAAQ,IAAI;EACjB,gBAAgB;EAChB,CAAC;AACF,QAAO;EACN,KAAK,QAAQ,IAAI;EACjB,OAAO,UAAU,aAAa;EAC9B,OAAO,QAAQ,SAAS,IAAI;EAC5B;;AAGF,MAAM,eAAe,WAA4C;CAChE,MAAM;CACN;CACA;;;;;;;;;;;;;;;;;;;;AAyBD,MAAa,YACZ,OACA,OAAwB,EAAE,KACX;CACf,MAAM,cAAc,gBAAgB,MAAM;CAC1C,MAAM,cAAc,gBAAgB;EACnC,aAAa,KAAK;EAClB,UAAU,KAAK,YAAY,YAAY,QAAQ;EAC/C,KAAK,QAAQ,IAAI;EACjB,KAAK,QAAQ,KAAK;EAClB,CAAC;CACF,MAAM,UAAU,KAAK,WAAW,QAAQ,KAAK;CAC7C,MAAM,WAAW,gBAAgB,OAAO,KAAK,UAAU,QAAQ;CAC/D,MAAM,UAAU,KAAK,WAAW,YAAY,QAAQ;CAEpD,MAAM,kBAAkB;EACvB,MAAM;EACN,SAAS,YAAY;EACrB,SAAS,YAAY;EACrB;CAWD,MAAM,QAAQ,uBAAuB;CACrC,MAAM,eAAe,OAAO,QAAQ,SAAS,MAAuB,CAAC;CACrE,MAAM,gBAAgB,OAAO,QAAQ,SAAS,MAAY,CAAC;CAC3D,MAAM,gBAAgB,OAAO,QAAQ,SAAS,MAAkC,CAAC;CACjF,MAAM,WAAW,OAAO,QAAQ,SAAS,MAAgC,CAAC;CAC1E,MAAM,aAAa,OAAO,QAAQ,IAAI,KAAK,MAAM,CAAC;CAOlD,MAAM,iBAAiB,OAAO,QAAQ,IAAI,KAAkC,KAAK,CAAC;CAUlF,MAAM,gBAAgB,qBAAqB;EAC1C;EACA,gBAAgB,OAAO,SAAS,MAAM;EACtC,cAAc,YAAY,QAAQ;EAClC,mBAAmB,SAAS;EAC5B,qBAAqB,SAAS,eAAe;EAC7C,CAAC;CACF,MAAM,YAAY,6BAA6B,EAC9C,SAAS;EACR;EACA,WAAW,cAAc;EACzB,aAAa,cAAc;EAC3B,EACD,CAAC,CAAC,KAAK,MAAM,aAAa,qBAAqB,UAAU,YAAY,CAAC,CAAC;CAExE,MAAM,aAAa,OAAO,IAAI,aAAa;EAC1C,MAAM,oBAAoB,OAAO,kCAAkC;AAEnE,SAAO,qBAAqB,iBAAiB,UAAU,OAAO;GAC7D;GACA,iBAAA,OAH8B,+BAA+B,EAAE,QAAQ,MAAM,QAAQ,QAAQ,CAAC;GAI9F,gBAAgB,QACf,OAAO,IAAI,aAAa;IACvB,MAAM,iBAAiB,OAAO,2BAA2B,IAAI;AAC7D,WAAO,KAAK,kBAAkB,KAAA,IAC3B,iBACA,OAAO,KAAK,cAAc,eAAe;KAC3C;GACH,uBAAuB,WACtB,OAAO,IAAI,aAAa;AACvB,WAAO,SAAS,QAAQ,eAAe,OAAO,OAAO,CAAC,KACrD,OAAO,YAAY,OAAO,KAAK,CAC/B;AAKD,WAAO,OAAO,WACb,OAAO,IAAI,aAAa;AACvB,YAAO,SAAS,MAAM,cAAc;AACpC,YAAO,MAAM,MAAM,OAAO,UAAU,EACnC,KAAK,sBACL,CAAC;MACD,CACF;KACA;GACH,cAAc,WACb,OAAO,IAAI,aAAa;AAUvB,WAAO,OAAO,WACb,OAAO,IAAI,aAAa;KAMvB,MAAM,gBAAe,OALA,OAAO,QAC3B,OAAO,MAAM,QACZ,CAAC,SAAS,OAAO,SAAS,WAAW,IAAI,CAAC,KAAK,OAAO,KAAK,EAC5D,EAAE,aAAa,aAAa,CAC5B,EAC0B,KAAK,KAAK,UAAU;AAC/C,SAAI,iBAAiB,KAAA,EACpB,QAAO,SAAS,QAAQ,cAAc,KAAA,EAAU;SAEhD,QAAO,SAAS,KAAK,cAAc,YAAY,aAAa,MAAM,CAAC;MAEnE,CACF;KACA;GACH,CAAC,CAAC,KAAK,OAAO,QAAQ,0BAA0B,kBAAkB,CAAC,CAAC;GACpE;CAEF,MAAM,cAAc,OAAO,MAAM,EAAE,CAAC;CAepC,MAAM,oBAdU,WAAW,KAAK,OAAO,QAAQ,UAAU,EAAE,OAAO,QAAQ,YAAY,CAclB,CAAC,KACpE,OAAO,YAAY,UAClB,OAAO,IAAI,aAAa;EACvB,MAAM,uBAAuB,OAAO,SAAS,OAAO,aAAa;AACjE,SAAO,SAAS,KAAK,cAAc,YAAY,MAAM,CAAC,CAAC,KACtD,OAAO,QACP,OAAO,YAAY,OAAO,KAAK,CAC/B;AACD,MAAI,qBACH,QAAO,IAAI,IAAI,gBAAgB,MAAM;AAEtC,SAAO,OAAO,SAAS,uCAAuC,MAAM,OAAO,MAAM,GAAG;GACnF,CACF,CACD;AAgED,QAAO;EACN,OA/DoD,OAAO,qBAAqB,YAChF,OAAO,IAAI,aAAa;AAIvB,OAAI,OAHuB,IAAI,OAAO,aAAa,YAClD,UAAU,CAAC,OAAO,KAAK,GAAG,CAAC,MAAM,KAAK,CACtC,EACgB;IAWhB,MAAM,QAAQ,OAAO,OAAO,WAAW,kBAAkB;AACzD,WAAO,SAAS,QAAQ,UAAU,MAAM;;AAEzC,UAAO,QAAQ,SAAS,MAAM,aAAa,CAAC;IAC3C,CA2CG;EACL,MAzC+C,OAAO,IAAI,aAAa;AACvE,UAAO,SAAS,QAAQ,eAAe,KAAA,EAAU,CAAC,KAAK,OAAO,YAAY,OAAO,KAAK,CAAC;AAEvF,OAAI,EAAC,OADyB,SAAS,OAAO,SAAS,EAEtD;GAED,MAAM,QAAQ,OAAO,SAAS,MAAM,SAAS;AAK7C,UAAO,MAAM,MAAM,MAAM;IA8BrB;EACJ,eA5B0D,OAAO,IAAI,aAAa;AAElF,OAAI,EAAC,OADyB,SAAS,OAAO,SAAS,EAEtD;GAED,MAAM,QAAQ,OAAO,SAAS,MAAM,SAAS;AAC7C,UAAO,MAAM,MAAM,MAAM;GAMzB,MAAM,cAAc,OAAO,IAAI,IAAI,eAAe;AAClD,OAAI,gBAAgB,KACnB,QAAO,OAAO,OAAO,UAAU,YAAY;IAc/B;EACb,QAXwD,OAAO,OAC/D,OAAO,IAAI,aAAa;GACvB,MAAM,QAAQ,OAAO,SAAS,MAAM,cAAc;AAClD,UAAO,OAAO,UAAU,MAAM;IAC7B,CAOI;EACN;EACA"}
+{"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/boot.ts` helpers the CLI consumes. See\n// ARCHITECTURE.md §\"Layer composition lives at L3, not L0\".\n//\n// This module is the THIN PUBLIC FACADE. The implementation — plus the\n// non-public boot-injection seam the CLI `up` verb routes through —\n// lives in `run-stack-internal.ts`. `runStack` delegates there with a\n// zero-`boot` bag, so the public surface (`RunHandle`, `RunStackOptions`,\n// `BootError`) and the zero-`boot` path stay byte-identical. The substrate\n// types on the internal seam (`InternalRunHandle`, the bag, the\n// `SupervisorHandle`) NEVER reach this public surface or `index.ts`.\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 type { Cause, Context, Effect, Queue, Scope, Stream, SubscriptionRef } from 'effect';\n\nimport type { Identity } from '../substrate/identity.ts';\nimport type { EngineCommand, EngineEvent } from '../substrate/events.ts';\nimport type { SubscribableState } from '../substrate/projection.ts';\nimport type { ProductionCodegenOptions } from '../orchestrators/boot.ts';\nimport type { Stack } from './define-devstack.ts';\nimport type { AnyPlugin } from '../substrate/plugin.ts';\nimport { runStackWithBoot } from './run-stack-internal.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 or logger overrides. */\n\treadonly extendContext?: (\n\t\tctx: Context.Context<never>,\n\t) => Effect.Effect<Context.Context<never>, never, Scope.Scope>;\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/**\n * The programmatic handle `runStack` returns. It is a small bag of Effect\n * values + readable refs — a functional surface, not an object with methods:\n * each lifecycle action (`start` / `stop` / `awaitShutdown`) is an\n * `Effect` you run, and each observation channel (`events` / `state`) is a\n * value you read. Returned synchronously, BEFORE any fiber is forked, so a\n * caller can subscribe to `state` / `events` ahead of `start`.\n *\n * Symmetric with the attached CLI surface: `events`, `state`, and\n * `awaitShutdown` are the SAME in-process primitives the TUI consumes.\n *\n * Typical use:\n *\n *   const handle = runStack(stack, opts);\n *   await Effect.runPromise(handle.start);          // boot → all ready\n *   const snapshot = await Effect.runPromise(SubscriptionRef.get(handle.state));\n *   await Effect.runPromise(handle.stop);           // graceful shutdown\n *   await Effect.runPromise(handle.awaitShutdown);  // finalizers done\n */\nexport interface RunHandle {\n\t/** Fork the supervisor fiber and resolve once EVERY plugin reaches\n\t *  `ready` (or a terminal `done`). Fails with `BootError` if any\n\t *  plugin's initial-acquire path fails. Idempotent: a second `start`\n\t *  is a no-op that just awaits the same boot gate. */\n\treadonly start: Effect.Effect<void, BootError, never>;\n\t/** Request graceful shutdown: publishes `shutdown.requested` onto the\n\t *  supervisor's command channel (driving scope finalizers), then awaits\n\t *  the fiber. Safe to call before `start` (returns immediately) and\n\t *  more than once. */\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 defect).\n\t *  Boot-time failures surface via `start`, not here — so a host that\n\t *  blocks the process on this Effect stays up for the supervisor's\n\t *  whole lifetime and learns of a post-boot death. */\n\treadonly awaitShutdown: Effect.Effect<void, unknown, never>;\n\t/** Tail of typed engine events off the supervisor's hub. SINGLE\n\t *  CONSUMER: the upstream is a `Queue.Dequeue`, so taking an event\n\t *  removes it — running this stream from two places SPLITS the events\n\t *  between them rather than fanning out. Consume it once (e.g. via\n\t *  `Stream.runForEach`) and tee downstream if you need multiple sinks.\n\t *  Empty until `start` wires the hub. */\n\treadonly events: Stream.Stream<EngineEvent, never, never>;\n\t/** The supervisor's live projection — the single read-model of stack\n\t *  state (identity, per-plugin lifecycle, cycle phase, log tail). Live\n\t *  for the supervisor's whole process lifetime: snapshot it with\n\t *  `SubscriptionRef.get`, or observe updates via `SubscriptionRef.changes`.\n\t *  Renderers + tests read it directly; nothing writes through it. */\n\treadonly state: SubscriptionRef.SubscriptionRef<SubscribableState>;\n\t/** Fire-and-forget publish side of the supervisor's command channel —\n\t *  enqueue an `EngineCommand` (`shutdown.requested`,\n\t *  `selective-restart.requested`, snapshot/wipe/prune verbs, …) and\n\t *  return immediately. The same queue the supervisor drains; the signal\n\t *  handler and the `stop` bridge publish here too. Use `runCommand` when\n\t *  you need to await the command's outcome. */\n\treadonly commands: Queue.Enqueue<EngineCommand>;\n\t/** Submit-and-AWAIT dispatch: publishes `command` in-band on the\n\t *  supervisor's command loop and resolves when the loop finishes\n\t *  handling it, re-failing with the handler's cause. Use this (over\n\t *  `commands`) when the caller must know the command succeeded —\n\t *  e.g. a destructive `snapshot.restore`. (The cross-process IPC bridge\n\t *  layers ack-correlation on top of this.) */\n\treadonly runCommand: (command: EngineCommand) => Effect.Effect<void, unknown, never>;\n\t/** The resolved `Identity` — app / stack / network — this handle booted\n\t *  with, after all option > env > inference resolution. Available\n\t *  synchronously, BEFORE `start`. */\n\treadonly identity: Identity;\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 * Programmatic contract — call, then drive the returned handle's Effects:\n *\n *   1. `runStack(stack, opts)` — synchronous; NO fiber forked yet. Safe to\n *      read `handle.identity` and subscribe to `handle.state` /\n *      `handle.events` right away.\n *   2. `await Effect.runPromise(handle.start)` — forks the supervisor and\n *      blocks until every plugin reaches `ready` (or fails with `BootError`).\n *   3. Observe via `handle.state` (snapshot / changes) and `handle.events`\n *      (single-consumer tail); drive via `handle.commands` /\n *      `handle.runCommand`.\n *   4. `await Effect.runPromise(handle.stop)` — graceful shutdown.\n *   5. `await Effect.runPromise(handle.awaitShutdown)` — resolves once scope\n *      finalizers complete (or re-raises a post-boot supervisor death).\n *\n * Thin facade: delegates to `runStackWithBoot` (in `run-stack-internal.ts`)\n * with a zero-`boot` bag and no `commandHandler`, so this public path is\n * byte-identical to the pre-seam `runStack` body. The boot-injection seam\n * the CLI `up` verb consumes is non-public — it is NOT re-exported from\n * `index.ts`, and its substrate types never appear on `RunHandle`.\n */\nexport const runStack = (\n\tstack: Stack<ReadonlyArray<AnyPlugin>>,\n\topts: RunStackOptions = {},\n): RunHandle => runStackWithBoot(stack, { ...opts, commandHandler: undefined, boot: undefined });\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA6LA,MAAa,YACZ,OACA,OAAwB,CAAC,MACV,iBAAiB,OAAO;CAAE,GAAG;CAAM,gBAAgB,KAAA;CAAW,MAAM,KAAA;AAAU,CAAC"}

package/dist/build-integrations/dapp-kit/index.d.mts

@@ -0,0 +1,61 @@
+//#region src/build-integrations/dapp-kit/index.d.ts
+/** A wallet-standard account as surfaced by dApp Kit. The dev wallet sets each
+ *  account's `label` to its devstack account name (`alice`, `bob`, …). */
+interface UiWalletAccountLike {
+  readonly address: string;
+  readonly label?: string;
+}
+interface UiWalletLike {
+  readonly name: string;
+  readonly accounts: readonly UiWalletAccountLike[];
+}
+/**
+ * The slice of a dApp Kit instance this bridge drives, generic over the app's
+ * concrete wallet type `W` (inferred from `$wallets`). The account type is
+ * DERIVED as `W['accounts'][number]` rather than inferred separately, so the
+ * objects pulled from `$wallets` flow back into `connectWallet` /
+ * `switchAccount` as their real (branded `UiWallet` / `UiWalletAccount`) types
+ * — a structural stand-in is not assignable to dApp Kit's branded parameters.
+ * The app passes its real `createDAppKit(...)` return value and `W` is inferred.
+ */
+interface TestableDAppKit<W extends UiWalletLike> {
+  connectWallet(args: {
+    wallet: W;
+    account: W['accounts'][number];
+  }): Promise<unknown>;
+  switchAccount(args: {
+    account: W['accounts'][number];
+  }): void;
+  readonly stores: {
+    readonly $wallets: {
+      get(): readonly W[];
+    };
+    readonly $connection: {
+      get(): {
+        readonly isConnected: boolean;
+        readonly wallet: {
+          readonly name: string;
+        } | null;
+      };
+    };
+  };
+}
+/**
+ * Register `dAppKit` with the `globalThis.__devstackDAppKit__` test slot that
+ * Playwright's `connectAs` / `selectAccount` helpers drive. Call once, DEV-only,
+ * after `createDAppKit(...)`:
+ *
+ * ```ts
+ * export const dAppKit = createDAppKit({ ... });
+ * if (import.meta.env.DEV) registerDAppKitForTesting(dAppKit);
+ * ```
+ *
+ * The published `selectAccount` performs a real connection: if already connected
+ * to the dev wallet it switches the active account; otherwise it connects,
+ * selecting the requested account. Account names resolve to the dev wallet's
+ * wallet-standard accounts by `label` (the devstack account name).
+ */
+declare function registerDAppKitForTesting<W extends UiWalletLike>(dAppKit: TestableDAppKit<W>): void;
+//#endregion
+export { TestableDAppKit, registerDAppKitForTesting };
+//# sourceMappingURL=index.d.mts.map

package/dist/build-integrations/dapp-kit/index.mjs

@@ -0,0 +1,58 @@
+import "../runtime/dapp-kit-slot.mjs";
+//#region src/build-integrations/dapp-kit/index.ts
+/** How long `selectAccount` waits for the dev wallet (and the requested
+*  account) to register before giving up — the wallet comes up asynchronously,
+*  so a `connectAs(...)` fired right after page load may beat it. */
+const RESOLVE_TIMEOUT_MS = 1e4;
+const RESOLVE_POLL_MS = 50;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Register `dAppKit` with the `globalThis.__devstackDAppKit__` test slot that
+* Playwright's `connectAs` / `selectAccount` helpers drive. Call once, DEV-only,
+* after `createDAppKit(...)`:
+*
+* ```ts
+* export const dAppKit = createDAppKit({ ... });
+* if (import.meta.env.DEV) registerDAppKitForTesting(dAppKit);
+* ```
+*
+* The published `selectAccount` performs a real connection: if already connected
+* to the dev wallet it switches the active account; otherwise it connects,
+* selecting the requested account. Account names resolve to the dev wallet's
+* wallet-standard accounts by `label` (the devstack account name).
+*/
+function registerDAppKitForTesting(dAppKit) {
+	const resolveLabelledAccount = async (accountName) => {
+		const deadline = Date.now() + RESOLVE_TIMEOUT_MS;
+		for (;;) {
+			for (const wallet of dAppKit.stores.$wallets.get()) {
+				const account = wallet.accounts.find((candidate) => candidate.label === accountName);
+				if (account !== void 0) return {
+					wallet,
+					account
+				};
+			}
+			if (Date.now() >= deadline) return null;
+			await sleep(RESOLVE_POLL_MS);
+		}
+	};
+	const selectAccount = async (accountName) => {
+		const found = await resolveLabelledAccount(accountName);
+		if (found === null) throw new Error(`connectAs("${accountName}"): no dev-wallet account labelled "${accountName}" registered within ${RESOLVE_TIMEOUT_MS}ms. Confirm the dev wallet is injected and the account name exists.`);
+		const { wallet, account } = found;
+		const connection = dAppKit.stores.$connection.get();
+		if (connection.isConnected && connection.wallet?.name === wallet.name) {
+			dAppKit.switchAccount({ account });
+			return;
+		}
+		await dAppKit.connectWallet({
+			wallet,
+			account
+		});
+	};
+	globalThis.__devstackDAppKit__ = { selectAccount };
+}
+//#endregion
+export { registerDAppKitForTesting };
+
+//# sourceMappingURL=index.mjs.map

package/dist/build-integrations/dapp-kit/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/build-integrations/dapp-kit/index.ts"],"sourcesContent":["// Copyright (c) Mysten Labs, Inc.\n// SPDX-License-Identifier: Apache-2.0\n//\n// dApp Kit test bridge — registers an app's dApp Kit instance so the Playwright\n// `connectAs` helper can drive a REAL connection during e2e.\n//\n// This is a TESTING feature, not an app feature. The app calls\n// `registerDAppKitForTesting(dAppKit)` DEV-only (it is a no-op consumer in\n// production: a `vite build` strips the `import.meta.env.DEV` branch and the\n// dev wallet is never injected). It performs NO connection on its own — the app\n// loads disconnected, dApp Kit's own `autoConnect` only re-connects a genuine\n// prior session, and an actual connection happens solely when a test calls the\n// published slot.\n//\n// The connection goes through dApp Kit's public API (`connectWallet` /\n// `switchAccount`) — no localStorage seeding, no narrowing/widening the\n// wallet's exposed accounts.\n//\n// Browser-safe: this module (and the `dapp-kit-slot` contract it imports) must\n// never pull in `node:*` — it is bundled into app pages by Vite.\n\nimport { DAPP_KIT_SLOT_KEY, type DAppKitSlot } from '../runtime/dapp-kit-slot.ts';\n\n/** A wallet-standard account as surfaced by dApp Kit. The dev wallet sets each\n *  account's `label` to its devstack account name (`alice`, `bob`, …). */\ninterface UiWalletAccountLike {\n\treadonly address: string;\n\treadonly label?: string;\n}\n\ninterface UiWalletLike {\n\treadonly name: string;\n\treadonly accounts: readonly UiWalletAccountLike[];\n}\n\n/**\n * The slice of a dApp Kit instance this bridge drives, generic over the app's\n * concrete wallet type `W` (inferred from `$wallets`). The account type is\n * DERIVED as `W['accounts'][number]` rather than inferred separately, so the\n * objects pulled from `$wallets` flow back into `connectWallet` /\n * `switchAccount` as their real (branded `UiWallet` / `UiWalletAccount`) types\n * — a structural stand-in is not assignable to dApp Kit's branded parameters.\n * The app passes its real `createDAppKit(...)` return value and `W` is inferred.\n */\nexport interface TestableDAppKit<W extends UiWalletLike> {\n\tconnectWallet(args: { wallet: W; account: W['accounts'][number] }): Promise<unknown>;\n\tswitchAccount(args: { account: W['accounts'][number] }): void;\n\treadonly stores: {\n\t\treadonly $wallets: { get(): readonly W[] };\n\t\treadonly $connection: {\n\t\t\tget(): { readonly isConnected: boolean; readonly wallet: { readonly name: string } | null };\n\t\t};\n\t};\n}\n\n/** How long `selectAccount` waits for the dev wallet (and the requested\n *  account) to register before giving up — the wallet comes up asynchronously,\n *  so a `connectAs(...)` fired right after page load may beat it. */\nconst RESOLVE_TIMEOUT_MS = 10_000;\nconst RESOLVE_POLL_MS = 50;\n\nconst sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));\n\n/**\n * Register `dAppKit` with the `globalThis.__devstackDAppKit__` test slot that\n * Playwright's `connectAs` / `selectAccount` helpers drive. Call once, DEV-only,\n * after `createDAppKit(...)`:\n *\n * ```ts\n * export const dAppKit = createDAppKit({ ... });\n * if (import.meta.env.DEV) registerDAppKitForTesting(dAppKit);\n * ```\n *\n * The published `selectAccount` performs a real connection: if already connected\n * to the dev wallet it switches the active account; otherwise it connects,\n * selecting the requested account. Account names resolve to the dev wallet's\n * wallet-standard accounts by `label` (the devstack account name).\n */\nexport function registerDAppKitForTesting<W extends UiWalletLike>(\n\tdAppKit: TestableDAppKit<W>,\n): void {\n\tconst resolveLabelledAccount = async (\n\t\taccountName: string,\n\t): Promise<{ wallet: W; account: W['accounts'][number] } | null> => {\n\t\tconst deadline = Date.now() + RESOLVE_TIMEOUT_MS;\n\t\tfor (;;) {\n\t\t\tfor (const wallet of dAppKit.stores.$wallets.get()) {\n\t\t\t\tconst account = wallet.accounts.find((candidate) => candidate.label === accountName);\n\t\t\t\tif (account !== undefined) return { wallet, account };\n\t\t\t}\n\t\t\tif (Date.now() >= deadline) return null;\n\t\t\tawait sleep(RESOLVE_POLL_MS);\n\t\t}\n\t};\n\n\tconst selectAccount = async (accountName: string): Promise<void> => {\n\t\tconst found = await resolveLabelledAccount(accountName);\n\t\tif (found === null) {\n\t\t\tthrow new Error(\n\t\t\t\t`connectAs(\"${accountName}\"): no dev-wallet account labelled \"${accountName}\" ` +\n\t\t\t\t\t`registered within ${RESOLVE_TIMEOUT_MS}ms. Confirm the dev wallet is injected ` +\n\t\t\t\t\t`and the account name exists.`,\n\t\t\t);\n\t\t}\n\t\tconst { wallet, account } = found;\n\t\tconst connection = dAppKit.stores.$connection.get();\n\t\tif (connection.isConnected && connection.wallet?.name === wallet.name) {\n\t\t\t// Already connected to the dev wallet — just switch the active account.\n\t\t\tdAppKit.switchAccount({ account });\n\t\t\treturn;\n\t\t}\n\t\tawait dAppKit.connectWallet({ wallet, account });\n\t};\n\n\t(globalThis as { [DAPP_KIT_SLOT_KEY]?: DAppKitSlot }).__devstackDAppKit__ = { selectAccount };\n}\n"],"mappings":";;;;;AA0DA,MAAM,qBAAqB;AAC3B,MAAM,kBAAkB;AAExB,MAAM,SAAS,OAA8B,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;;;;;;;;;;;;;;;;AAiB7F,SAAgB,0BACf,SACO;CACP,MAAM,yBAAyB,OAC9B,gBACmE;EACnE,MAAM,WAAW,KAAK,IAAI,IAAI;EAC9B,SAAS;GACR,KAAK,MAAM,UAAU,QAAQ,OAAO,SAAS,IAAI,GAAG;IACnD,MAAM,UAAU,OAAO,SAAS,MAAM,cAAc,UAAU,UAAU,WAAW;IACnF,IAAI,YAAY,KAAA,GAAW,OAAO;KAAE;KAAQ;IAAQ;GACrD;GACA,IAAI,KAAK,IAAI,KAAK,UAAU,OAAO;GACnC,MAAM,MAAM,eAAe;EAC5B;CACD;CAEA,MAAM,gBAAgB,OAAO,gBAAuC;EACnE,MAAM,QAAQ,MAAM,uBAAuB,WAAW;EACtD,IAAI,UAAU,MACb,MAAM,IAAI,MACT,cAAc,YAAY,sCAAsC,YAAY,sBACtD,mBAAmB,oEAE1C;EAED,MAAM,EAAE,QAAQ,YAAY;EAC5B,MAAM,aAAa,QAAQ,OAAO,YAAY,IAAI;EAClD,IAAI,WAAW,eAAe,WAAW,QAAQ,SAAS,OAAO,MAAM;GAEtE,QAAQ,cAAc,EAAE,QAAQ,CAAC;GACjC;EACD;EACA,MAAM,QAAQ,cAAc;GAAE;GAAQ;EAAQ,CAAC;CAChD;CAEA,WAAsD,sBAAsB,EAAE,cAAc;AAC7F"}

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

@@ -25,19 +25,6 @@ interface PlaywrightProjectShape {
   name: string;
   use: Record<string, unknown>;
 }
-interface PlaywrightWebServerConfigShape {
-  readonly command: string;
-  readonly url: string;
-  readonly reuseExistingServer: boolean;
-  readonly timeout: number;
-  readonly stdout: 'pipe' | 'ignore';
-  readonly stderr: 'pipe' | 'ignore';
-  readonly gracefulShutdown: {
-    readonly signal: 'SIGTERM';
-    readonly timeout: number;
-  };
-  readonly env?: Record<string, string>;
-}
 interface DevstackPlaywrightBaseConfigOptions {
   /** Test directory. Default: `'./e2e'` (architecture invariant). */
   readonly testDir?: string;
@@ -54,21 +41,6 @@ interface DevstackPlaywrightEndpointOptions extends ResolveStackContextOptions {
    *  bypassed entirely. */
   readonly baseURL?: string;
 }
-interface DevstackPlaywrightWebServerOptions extends DevstackPlaywrightEndpointOptions {
-  /** Command Playwright runs to bring up the stack. Default:
-   *  `'pnpm dev'`. */
-  readonly command?: string;
-  /** Hard cap (ms) for `webServer` URL to become reachable. Default:
-   *  300_000 (5 min) — accounts for cold supervisor boot under
-   *  Docker pulls. */
-  readonly webServerTimeoutMs?: number;
-  /** Hard cap (ms) for `webServer.gracefulShutdown`. Default: 10_000
-   *  (10 s) — load-bearing per architecture § Invariants. */
-  readonly gracefulShutdownTimeoutMs?: number;
-  /** Extra env to forward to `webServer.command`. Merged after the
-   *  preset's own env (PLAYWRIGHT=1, DEVSTACK_STACK). */
-  readonly env?: Record<string, string>;
-}
 interface DevstackPlaywrightProjectsOptions {
   /** Extra Playwright projects to append to the default Chromium
    *  project. */
@@ -88,7 +60,6 @@ declare const resolveDevstackPlaywrightBaseURL: (options?: DevstackPlaywrightEnd
 declare const devstackPlaywrightBaseConfig: (options?: DevstackPlaywrightBaseConfigOptions) => PlaywrightBaseConfigShape;
 declare const devstackPlaywrightUse: (options?: DevstackPlaywrightUseOptions) => PlaywrightUseConfigShape;
 declare const devstackPlaywrightProjects: (options?: DevstackPlaywrightProjectsOptions) => PlaywrightProjectShape[];
-declare const devstackPlaywrightWebServer: (options?: DevstackPlaywrightWebServerOptions) => PlaywrightWebServerConfigShape;
 //#endregion
-export { DevstackPlaywrightBaseConfigOptions, DevstackPlaywrightEndpointOptions, DevstackPlaywrightProjectsOptions, DevstackPlaywrightUseOptions, DevstackPlaywrightWebServerOptions, PlaywrightBaseConfigShape, PlaywrightProjectShape, PlaywrightUseConfigShape, PlaywrightWebServerConfigShape, devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, devstackPlaywrightWebServer, resolveDevstackPlaywrightBaseURL };
+export { DevstackPlaywrightBaseConfigOptions, DevstackPlaywrightEndpointOptions, DevstackPlaywrightProjectsOptions, DevstackPlaywrightUseOptions, PlaywrightBaseConfigShape, PlaywrightProjectShape, PlaywrightUseConfigShape, devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, resolveDevstackPlaywrightBaseURL };
 //# sourceMappingURL=config.d.mts.map

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

@@ -3,9 +3,6 @@ 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 = BUILT_IN_ENDPOINT_ALIASES.app;
 /**
 * Resolve the browser app URL Playwright should target. This is the
@@ -44,30 +41,7 @@ const devstackPlaywrightProjects = (options = {}) => [{
 	name: "chromium",
 	use: { browserName: "chromium" }
 }, ...options.projects ?? []];
-const devstackPlaywrightWebServer = (options = {}) => {
-	const env = options.env ? { ...options.env } : {};
-	const ci = Boolean(process.env.CI);
-	const baseURL = resolveDevstackPlaywrightBaseURL(options);
-	const presetEnv = {
-		PLAYWRIGHT: "1",
-		...options.stack !== void 0 ? { DEVSTACK_STACK: options.stack } : {},
-		...env
-	};
-	return {
-		command: options.command ?? DEFAULT_COMMAND,
-		url: baseURL,
-		reuseExistingServer: !ci,
-		timeout: options.webServerTimeoutMs ?? DEFAULT_WEBSERVER_TIMEOUT_MS,
-		stdout: "pipe",
-		stderr: "pipe",
-		gracefulShutdown: {
-			signal: "SIGTERM",
-			timeout: options.gracefulShutdownTimeoutMs ?? DEFAULT_GRACEFUL_SHUTDOWN_MS
-		},
-		env: presetEnv
-	};
-};
 //#endregion
-export { devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, devstackPlaywrightWebServer, resolveDevstackPlaywrightBaseURL };
+export { devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, resolveDevstackPlaywrightBaseURL };
 
 //# sourceMappingURL=config.mjs.map

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 { 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"}
+{"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), plus a `baseURL` resolver.\n//\n//   The stack is booted by the `globalSetup` (programmatic `runStack`,\n//   see `global-setup.ts`), NOT by Playwright's `webServer`. Playwright's\n//   `webServer` shells out (`pnpm dev`) and force-kills the supervisor on\n//   teardown before its container drain finishes, orphaning containers;\n//   the in-process `runStack` boot + `handle.stop` teardown drains cleanly.\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//   - `use.baseURL` settable at config-load time even with no manifest —\n//     via cold-start fallback to a conventional URL (the stack the\n//     globalSetup boots later answers on that conventional router host).\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\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 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_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"],"mappings":";;;AAyCA,MAAM,uBAAuB;AAmE7B,MAAM,mBAAmB;AACzB,MAAM,wBAAwB,0BAA0B;;;;;;AAWxD,MAAa,oCACZ,UAA6C,CAAC,MAClC;CACZ,MAAM,eAAe,QAAQ,gBAAgB;CAC7C,OACC,QAAQ,WACR,mBAAmB,cAAc;EAChC,GAAI,QAAQ,QAAQ,KAAA,IAAY,EAAE,KAAK,QAAQ,IAAI,IAAI,CAAC;EACxD,GAAI,QAAQ,iBAAiB,KAAA,IAAY,EAAE,cAAc,QAAQ,aAAa,IAAI,CAAC;EACnF,GAAI,QAAQ,UAAU,KAAA,IAAY,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;EAC9D,GAAI,QAAQ,aAAa,KAAA,IAAY,EAAE,UAAU,QAAQ,SAAS,IAAI,CAAC;EACvE,GAAI,QAAQ,QAAQ,KAAA,IAAY,EAAE,KAAK,QAAQ,IAAI,IAAI,CAAC;CACzD,CAAC,CAAC,CAAC;AAEL;AAEA,MAAa,gCACZ,UAA+C,CAAC,MACjB;CAC/B,MAAM,KAAK,QAAQ,QAAQ,IAAI,EAAE;CACjC,OAAO;EACN,SAAS,QAAQ,WAAW;EAC5B,eAAe;EACf,YAAY;EACZ,SAAS,KAAK,IAAI;EAClB,SAAS;EACT,UAAU,KAAK,CAAC,CAAC,QAAQ,GAAG,CAAC,MAAM,CAAC,IAAI;EACxC,aACC,QAAQ,gBAAgB,OAAO,KAAA,IAAa,QAAQ,eAAe;CACrE;AACD;AAEA,MAAa,yBACZ,UAAwC,CAAC,OACV;CAC/B,SAAS,iCAAiC,OAAO;CACjD,OAAO,QAAQ,SAAS;CACxB,YAAY,QAAQ,cAAc;CAClC,GAAG,QAAQ;AACZ;AAEA,MAAa,8BACZ,UAA6C,CAAC,MAChB,CAC9B;CACC,MAAM;CACN,KAAK,EAAE,aAAa,WAAW;AAChC,GACA,GAAI,QAAQ,YAAY,CAAC,CAC1B"}

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

@@ -1,8 +1,5 @@
-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 & {
+declare const PlaywrightManifestDiscoveryError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "PlaywrightManifestDiscoveryError";
 } & Readonly<A>;
 /**
@@ -20,7 +17,7 @@ declare class PlaywrightManifestDiscoveryError extends PlaywrightManifestDiscove
   readonly endpointKey?: string;
   readonly recoveryHint: string;
 }> {}
-declare const PlaywrightManifestShapeError_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 & {
+declare const PlaywrightManifestShapeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "PlaywrightManifestShapeError";
 } & Readonly<A>;
 /**
@@ -37,7 +34,7 @@ declare class PlaywrightManifestShapeError extends PlaywrightManifestShapeError_
   readonly recoveryHint: string;
   readonly cause?: unknown;
 }> {}
-declare const PlaywrightEndpointNotFoundError_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 & {
+declare const PlaywrightEndpointNotFoundError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "PlaywrightEndpointNotFoundError";
 } & Readonly<A>;
 /**
@@ -54,7 +51,7 @@ declare class PlaywrightEndpointNotFoundError extends PlaywrightEndpointNotFound
   readonly manifestKeys?: ReadonlyArray<string>;
   readonly recoveryHint: string;
 }> {}
-declare const PlaywrightWalletAdapterError_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 & {
+declare const PlaywrightWalletAdapterError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "PlaywrightWalletAdapterError";
 } & Readonly<A>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/build-integrations/playwright/errors.ts"],"sourcesContent":["// Playwright build-integration errors.\n//\n// Architecture (distilled/23-build-integrations.md § Playwright):\n// every failure surface for the preset is a tagged error so the\n// config-load (synchronous, runs before any supervisor exists) can\n// raise a structured signal with an embedded recovery recipe rather\n// than an opaque downstream NPE.\n//\n// Scope discipline: this surface owns FOUR error tags. Anything that\n// would be a fifth tag is either upstream (manifest schema error from\n// the L0 substrate, which we re-raise unchanged) or a programmer\n// defect (Effect.die / throw — not part of this contract).\n//\n// The Playwright config-load is synchronous (Playwright's\n// `defineConfig` is sync), so these errors are constructed and\n// thrown rather than `Effect.fail`-ed. The surface mirrors the\n// `Data.TaggedError` shape so the tags are uniform across the\n// codebase, but the catch sites are `try` / `instanceof` in\n// Playwright host code.\n\nimport { Data } from 'effect';\n\n// -----------------------------------------------------------------------------\n// Discovery — manifest could not be located and no conventional URL\n// fallback exists for the requested endpoint.\n// -----------------------------------------------------------------------------\n\n/**\n * The manifest could not be located on disk (no stack-scoped file\n * along the walk-up path) AND the requested endpoint has no\n * conventional URL fallback in the endpoint declaration registry.\n *\n * Recovery: run `devstack up` once to materialize the manifest, OR\n * pass an explicit `baseURL` to the Playwright config helpers to\n * bypass the discovery path.\n */\nexport class PlaywrightManifestDiscoveryError extends Data.TaggedError(\n\t'PlaywrightManifestDiscoveryError',\n)<{\n\treadonly message: string;\n\treadonly searchedPaths: ReadonlyArray<string>;\n\treadonly endpointKey?: string;\n\treadonly recoveryHint: string;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Shape — manifest exists but failed to decode against the L0\n// envelope schema.\n// -----------------------------------------------------------------------------\n\n/**\n * The manifest file was located but failed to decode against\n * `ManifestEnvelopeSchema`. Wraps the substrate's `ManifestError`\n * (reason = `decode-failed` | `version-mismatch`) with a recovery\n * recipe targeted at the Playwright user (delete + re-run `devstack\n * up` rather than the engine-side recovery).\n */\nexport class PlaywrightManifestShapeError extends Data.TaggedError('PlaywrightManifestShapeError')<{\n\treadonly message: string;\n\treadonly manifestPath: string;\n\treadonly phase: 'shape' | 'parse' | 'version-mismatch';\n\treadonly recoveryHint: string;\n\treadonly cause?: unknown;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Endpoint lookup — manifest decoded fine but the requested endpoint\n// is absent from the flat lookup.\n// -----------------------------------------------------------------------------\n\n/**\n * The manifest decoded but the requested endpoint name/alias is not\n * present.\n * Typically caused by a typo in user config or by referencing an\n * endpoint owned by a plugin not present in the resolved stack.\n */\nexport class PlaywrightEndpointNotFoundError extends Data.TaggedError(\n\t'PlaywrightEndpointNotFoundError',\n)<{\n\treadonly message: string;\n\treadonly endpointKey: string;\n\treadonly endpointName?: string;\n\treadonly available: ReadonlyArray<string>;\n\treadonly manifestKeys?: ReadonlyArray<string>;\n\treadonly recoveryHint: string;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Wallet adapter — the in-spec wallet helper could not talk to the\n// dev wallet's HTTP API.\n// -----------------------------------------------------------------------------\n\n/**\n * The wallet-context test helper failed to reach the dev wallet's\n * HTTP API (the supervisor's wallet plugin exposes an endpoint that\n * tests POST to for sign-tx flows). Typical causes: supervisor not\n * up, wallet endpoint not yet registered in the manifest, network\n * partition between test runner and supervisor.\n *\n * This tag is throwable from in-spec helpers AND constructible by\n * `wallet-context.ts` callers; it carries enough detail to format a\n * Playwright-friendly assertion failure.\n */\nexport class PlaywrightWalletAdapterError extends Data.TaggedError('PlaywrightWalletAdapterError')<{\n\treadonly message: string;\n\treadonly operation: 'sign-tx' | 'list-accounts' | 'switch-account' | 'fetch';\n\treadonly url?: string;\n\treadonly status?: number;\n\treadonly cause?: unknown;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Union for catch sites that want to handle every surface tag.\n// -----------------------------------------------------------------------------\n\n/** Discriminated union of every error the Playwright preset emits. */\nexport type PlaywrightIntegrationError =\n\t| PlaywrightManifestDiscoveryError\n\t| PlaywrightManifestShapeError\n\t| PlaywrightEndpointNotFoundError\n\t| PlaywrightWalletAdapterError;\n"],"mappings":";;;;;;;;;;;AAoCA,IAAa,mCAAb,cAAsD,KAAK,YAC1D,mCACA,CAKE;;;;;;;;AAcH,IAAa,+BAAb,cAAkD,KAAK,YAAY,+BAA+B,CAM/F;;;;;;;AAaH,IAAa,kCAAb,cAAqD,KAAK,YACzD,kCACA,CAOE;;;;;;;;;;;;AAkBH,IAAa,+BAAb,cAAkD,KAAK,YAAY,+BAA+B,CAM/F"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/build-integrations/playwright/errors.ts"],"sourcesContent":["// Playwright build-integration errors.\n//\n// Architecture (distilled/23-build-integrations.md § Playwright):\n// every failure surface for the preset is a tagged error so the\n// config-load (synchronous, runs before any supervisor exists) can\n// raise a structured signal with an embedded recovery recipe rather\n// than an opaque downstream NPE.\n//\n// Scope discipline: this surface owns FOUR error tags. Anything that\n// would be a fifth tag is either upstream (manifest schema error from\n// the L0 substrate, which we re-raise unchanged) or a programmer\n// defect (Effect.die / throw — not part of this contract).\n//\n// The Playwright config-load is synchronous (Playwright's\n// `defineConfig` is sync), so these errors are constructed and\n// thrown rather than `Effect.fail`-ed. The surface mirrors the\n// `Data.TaggedError` shape so the tags are uniform across the\n// codebase, but the catch sites are `try` / `instanceof` in\n// Playwright host code.\n\nimport { Data } from 'effect';\n\n// -----------------------------------------------------------------------------\n// Discovery — manifest could not be located and no conventional URL\n// fallback exists for the requested endpoint.\n// -----------------------------------------------------------------------------\n\n/**\n * The manifest could not be located on disk (no stack-scoped file\n * along the walk-up path) AND the requested endpoint has no\n * conventional URL fallback in the endpoint declaration registry.\n *\n * Recovery: run `devstack up` once to materialize the manifest, OR\n * pass an explicit `baseURL` to the Playwright config helpers to\n * bypass the discovery path.\n */\nexport class PlaywrightManifestDiscoveryError extends Data.TaggedError(\n\t'PlaywrightManifestDiscoveryError',\n)<{\n\treadonly message: string;\n\treadonly searchedPaths: ReadonlyArray<string>;\n\treadonly endpointKey?: string;\n\treadonly recoveryHint: string;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Shape — manifest exists but failed to decode against the L0\n// envelope schema.\n// -----------------------------------------------------------------------------\n\n/**\n * The manifest file was located but failed to decode against\n * `ManifestEnvelopeSchema`. Wraps the substrate's `ManifestError`\n * (reason = `decode-failed` | `version-mismatch`) with a recovery\n * recipe targeted at the Playwright user (delete + re-run `devstack\n * up` rather than the engine-side recovery).\n */\nexport class PlaywrightManifestShapeError extends Data.TaggedError('PlaywrightManifestShapeError')<{\n\treadonly message: string;\n\treadonly manifestPath: string;\n\treadonly phase: 'shape' | 'parse' | 'version-mismatch';\n\treadonly recoveryHint: string;\n\treadonly cause?: unknown;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Endpoint lookup — manifest decoded fine but the requested endpoint\n// is absent from the flat lookup.\n// -----------------------------------------------------------------------------\n\n/**\n * The manifest decoded but the requested endpoint name/alias is not\n * present.\n * Typically caused by a typo in user config or by referencing an\n * endpoint owned by a plugin not present in the resolved stack.\n */\nexport class PlaywrightEndpointNotFoundError extends Data.TaggedError(\n\t'PlaywrightEndpointNotFoundError',\n)<{\n\treadonly message: string;\n\treadonly endpointKey: string;\n\treadonly endpointName?: string;\n\treadonly available: ReadonlyArray<string>;\n\treadonly manifestKeys?: ReadonlyArray<string>;\n\treadonly recoveryHint: string;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Wallet adapter — the in-spec wallet helper could not talk to the\n// dev wallet's HTTP API.\n// -----------------------------------------------------------------------------\n\n/**\n * The wallet-context test helper failed to reach the dev wallet's\n * HTTP API (the supervisor's wallet plugin exposes an endpoint that\n * tests POST to for sign-tx flows). Typical causes: supervisor not\n * up, wallet endpoint not yet registered in the manifest, network\n * partition between test runner and supervisor.\n *\n * This tag is throwable from in-spec helpers AND constructible by\n * `wallet-context.ts` callers; it carries enough detail to format a\n * Playwright-friendly assertion failure.\n */\nexport class PlaywrightWalletAdapterError extends Data.TaggedError('PlaywrightWalletAdapterError')<{\n\treadonly message: string;\n\treadonly operation: 'sign-tx' | 'list-accounts' | 'switch-account' | 'fetch';\n\treadonly url?: string;\n\treadonly status?: number;\n\treadonly cause?: unknown;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Union for catch sites that want to handle every surface tag.\n// -----------------------------------------------------------------------------\n\n/** Discriminated union of every error the Playwright preset emits. */\nexport type PlaywrightIntegrationError =\n\t| PlaywrightManifestDiscoveryError\n\t| PlaywrightManifestShapeError\n\t| PlaywrightEndpointNotFoundError\n\t| PlaywrightWalletAdapterError;\n"],"mappings":";;;;;;;;;;;AAoCA,IAAa,mCAAb,cAAsD,KAAK,YAC1D,kCACD,CAAC,CAKE,CAAC;;;;;;;;AAcJ,IAAa,+BAAb,cAAkD,KAAK,YAAY,8BAA8B,CAAC,CAM/F,CAAC;;;;;;;AAaJ,IAAa,kCAAb,cAAqD,KAAK,YACzD,iCACD,CAAC,CAOE,CAAC;;;;;;;;;;;;AAkBJ,IAAa,+BAAb,cAAkD,KAAK,YAAY,8BAA8B,CAAC,CAM/F,CAAC"}