@mysten-incubation/devstack 0.0.0

package/dist/api/inference-network.mjs

@@ -0,0 +1,122 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+//#region src/api/inference-network.ts
+const DEFAULT_STACK_NAME = "main";
+const usefulName = (value) => {
+	const trimmed = value?.trim();
+	if (trimmed === void 0 || trimmed.length === 0) return void 0;
+	const unscoped = trimmed.replace(/^@[^/]+\//, "").replace(/^[^a-zA-Z0-9]+/, "");
+	return unscoped.length > 0 ? unscoped : void 0;
+};
+const readPackageName = (dir) => {
+	try {
+		const pkg = JSON.parse(readFileSync(resolve(dir, "package.json"), "utf8"));
+		return typeof pkg.name === "string" ? usefulName(pkg.name) : void 0;
+	} catch {
+		return;
+	}
+};
+const inferPackageNameFromCwd = (cwd = process.cwd()) => {
+	let dir = resolve(cwd);
+	for (let i = 0; i < 32; i += 1) {
+		const name = readPackageName(dir);
+		if (name !== void 0) return name;
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+};
+const resolveStackName = (options = {}) => {
+	const explicit = usefulName(options.explicit);
+	if (explicit !== void 0) return explicit;
+	const fromEnv = usefulName((options.env ?? process.env).DEVSTACK_STACK);
+	if (fromEnv !== void 0) return fromEnv;
+	const fromPackage = inferPackageNameFromCwd(options.cwd);
+	if (fromPackage !== void 0) return fromPackage;
+	return options.defaultName ?? "main";
+};
+const resolveAppName = (options = {}) => {
+	const explicit = usefulName(options.explicit);
+	if (explicit !== void 0) return explicit;
+	const fromEnv = usefulName((options.env ?? process.env).DEVSTACK_APP);
+	if (fromEnv !== void 0) return fromEnv;
+	const fromPackage = inferPackageNameFromCwd(options.cwd);
+	if (fromPackage !== void 0) return fromPackage;
+	return options.defaultName ?? "devstack";
+};
+const ACTIVE_DEVSTACK_NETWORK_NAMES = [
+	"localnet",
+	"testnet",
+	"mainnet",
+	"devnet"
+];
+const FORK_DEVSTACK_NETWORK_NAMES = [
+	"testnet-fork",
+	"mainnet-fork",
+	"devnet-fork"
+];
+const DEVSTACK_NETWORK_NAMES = [...ACTIVE_DEVSTACK_NETWORK_NAMES, ...FORK_DEVSTACK_NETWORK_NAMES];
+const NETWORK_ALIASES = {
+	local: "localnet",
+	localnet: "localnet",
+	"sui:local": "localnet",
+	"sui:localnet": "localnet",
+	testnet: "testnet",
+	"sui:testnet": "testnet",
+	mainnet: "mainnet",
+	"sui:mainnet": "mainnet",
+	devnet: "devnet",
+	"sui:devnet": "devnet",
+	"testnet-fork": "testnet-fork",
+	"sui:testnet-fork": "testnet-fork",
+	"mainnet-fork": "mainnet-fork",
+	"sui:mainnet-fork": "mainnet-fork",
+	"devnet-fork": "devnet-fork",
+	"sui:devnet-fork": "devnet-fork"
+};
+var DevstackNetworkParseError = class extends Error {
+	_tag = "DevstackNetworkParseError";
+	value;
+	source;
+	supported;
+	constructor(args) {
+		super(`${args.source} must be one of: ${DEVSTACK_NETWORK_NAMES.join(", ")} (got ${JSON.stringify(args.value)})`);
+		this.name = "DevstackNetworkParseError";
+		this.value = args.value;
+		this.source = args.source;
+		this.supported = DEVSTACK_NETWORK_NAMES;
+	}
+};
+const parseDevstackNetwork = (value, source = "DEVSTACK_NETWORK") => {
+	const raw = value?.trim();
+	const name = raw === void 0 || raw.length === 0 ? "localnet" : NETWORK_ALIASES[raw];
+	if (name === void 0) throw new DevstackNetworkParseError({
+		value: raw ?? "",
+		source
+	});
+	switch (name) {
+		case "localnet": return {
+			mode: "local",
+			name
+		};
+		case "testnet":
+		case "mainnet":
+		case "devnet": return {
+			mode: "live",
+			name,
+			network: name
+		};
+		case "testnet-fork":
+		case "mainnet-fork":
+		case "devnet-fork": return {
+			mode: "fork",
+			name,
+			upstream: name.replace(/-fork$/, "")
+		};
+	}
+};
+const parseDevstackNetworkName = (value, source = "DEVSTACK_NETWORK") => parseDevstackNetwork(value, source).name;
+//#endregion
+export { DEFAULT_STACK_NAME, parseDevstackNetworkName, resolveAppName, resolveStackName };
+
+//# sourceMappingURL=inference-network.mjs.map

package/dist/api/inference-network.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference-network.mjs","names":[],"sources":["../../src/api/inference-network.ts"],"sourcesContent":["import { readFileSync } from 'node:fs';\nimport { dirname, resolve } from 'node:path';\n\nexport const DEFAULT_STACK_NAME = 'main';\n\nexport interface StackNameResolutionOptions {\n\treadonly explicit?: string;\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n\treadonly cwd?: string;\n\treadonly defaultName?: string;\n}\n\nexport interface AppNameResolutionOptions {\n\treadonly explicit?: string;\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n\treadonly cwd?: string;\n\treadonly defaultName?: string;\n}\n\nconst usefulName = (value: string | undefined): string | undefined => {\n\tconst trimmed = value?.trim();\n\tif (trimmed === undefined || trimmed.length === 0) return undefined;\n\tconst unscoped = trimmed.replace(/^@[^/]+\\//, '').replace(/^[^a-zA-Z0-9]+/, '');\n\treturn unscoped.length > 0 ? unscoped : undefined;\n};\n\nexport const readPackageName = (dir: string): string | undefined => {\n\ttry {\n\t\tconst pkg = JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf8')) as {\n\t\t\treadonly name?: string;\n\t\t};\n\t\treturn typeof pkg.name === 'string' ? usefulName(pkg.name) : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n};\n\nexport const inferPackageNameFromCwd = (cwd: string = process.cwd()): string | undefined => {\n\tlet dir = resolve(cwd);\n\tfor (let i = 0; i < 32; i += 1) {\n\t\tconst name = readPackageName(dir);\n\t\tif (name !== undefined) return name;\n\t\tconst parent = dirname(dir);\n\t\tif (parent === dir) return undefined;\n\t\tdir = parent;\n\t}\n\treturn undefined;\n};\n\nexport const resolveStackName = (options: StackNameResolutionOptions = {}): string => {\n\tconst explicit = usefulName(options.explicit);\n\tif (explicit !== undefined) return explicit;\n\tconst env = options.env ?? process.env;\n\tconst fromEnv = usefulName(env.DEVSTACK_STACK);\n\tif (fromEnv !== undefined) return fromEnv;\n\tconst fromPackage = inferPackageNameFromCwd(options.cwd);\n\tif (fromPackage !== undefined) return fromPackage;\n\treturn options.defaultName ?? DEFAULT_STACK_NAME;\n};\n\nexport const resolveAppName = (options: AppNameResolutionOptions = {}): string => {\n\tconst explicit = usefulName(options.explicit);\n\tif (explicit !== undefined) return explicit;\n\tconst env = options.env ?? process.env;\n\tconst fromEnv = usefulName(env.DEVSTACK_APP);\n\tif (fromEnv !== undefined) return fromEnv;\n\tconst fromPackage = inferPackageNameFromCwd(options.cwd);\n\tif (fromPackage !== undefined) return fromPackage;\n\treturn options.defaultName ?? 'devstack';\n};\n\nexport const ACTIVE_DEVSTACK_NETWORK_NAMES = ['localnet', 'testnet', 'mainnet', 'devnet'] as const;\n\nexport const FORK_DEVSTACK_NETWORK_NAMES = ['testnet-fork', 'mainnet-fork', 'devnet-fork'] as const;\n\nexport const DEVSTACK_NETWORK_NAMES = [\n\t...ACTIVE_DEVSTACK_NETWORK_NAMES,\n\t...FORK_DEVSTACK_NETWORK_NAMES,\n] as const;\n\nexport type ActiveDevstackNetworkName = (typeof ACTIVE_DEVSTACK_NETWORK_NAMES)[number];\nexport type ForkDevstackNetworkName = (typeof FORK_DEVSTACK_NETWORK_NAMES)[number];\nexport type DevstackNetworkName = (typeof DEVSTACK_NETWORK_NAMES)[number];\nexport type LiveDevstackNetworkName = 'testnet' | 'mainnet' | 'devnet';\n\nexport type ParsedDevstackNetwork =\n\t| {\n\t\t\treadonly mode: 'local';\n\t\t\treadonly name: 'localnet';\n\t  }\n\t| {\n\t\t\treadonly mode: 'live';\n\t\t\treadonly name: LiveDevstackNetworkName;\n\t\t\treadonly network: LiveDevstackNetworkName;\n\t  }\n\t| {\n\t\t\treadonly mode: 'fork';\n\t\t\treadonly name: ForkDevstackNetworkName;\n\t\t\treadonly upstream: LiveDevstackNetworkName;\n\t  };\n\nconst NETWORK_ALIASES: Readonly<Record<string, DevstackNetworkName>> = {\n\tlocal: 'localnet',\n\tlocalnet: 'localnet',\n\t'sui:local': 'localnet',\n\t'sui:localnet': 'localnet',\n\ttestnet: 'testnet',\n\t'sui:testnet': 'testnet',\n\tmainnet: 'mainnet',\n\t'sui:mainnet': 'mainnet',\n\tdevnet: 'devnet',\n\t'sui:devnet': 'devnet',\n\t'testnet-fork': 'testnet-fork',\n\t'sui:testnet-fork': 'testnet-fork',\n\t'mainnet-fork': 'mainnet-fork',\n\t'sui:mainnet-fork': 'mainnet-fork',\n\t'devnet-fork': 'devnet-fork',\n\t'sui:devnet-fork': 'devnet-fork',\n};\n\nexport class DevstackNetworkParseError extends Error {\n\treadonly _tag = 'DevstackNetworkParseError';\n\treadonly value: string;\n\treadonly source: string;\n\treadonly supported: ReadonlyArray<DevstackNetworkName>;\n\n\tconstructor(args: { readonly value: string; readonly source: string }) {\n\t\tsuper(\n\t\t\t`${args.source} must be one of: ${DEVSTACK_NETWORK_NAMES.join(', ')} (got ${JSON.stringify(args.value)})`,\n\t\t);\n\t\tthis.name = 'DevstackNetworkParseError';\n\t\tthis.value = args.value;\n\t\tthis.source = args.source;\n\t\tthis.supported = DEVSTACK_NETWORK_NAMES;\n\t}\n}\n\nexport const parseDevstackNetwork = (\n\tvalue: string | undefined,\n\tsource = 'DEVSTACK_NETWORK',\n): ParsedDevstackNetwork => {\n\tconst raw = value?.trim();\n\tconst name = raw === undefined || raw.length === 0 ? 'localnet' : NETWORK_ALIASES[raw];\n\tif (name === undefined) {\n\t\tthrow new DevstackNetworkParseError({ value: raw ?? '', source });\n\t}\n\tswitch (name) {\n\t\tcase 'localnet':\n\t\t\treturn { mode: 'local', name };\n\t\tcase 'testnet':\n\t\tcase 'mainnet':\n\t\tcase 'devnet':\n\t\t\treturn { mode: 'live', name, network: name };\n\t\tcase 'testnet-fork':\n\t\tcase 'mainnet-fork':\n\t\tcase 'devnet-fork':\n\t\t\treturn {\n\t\t\t\tmode: 'fork',\n\t\t\t\tname,\n\t\t\t\tupstream: name.replace(/-fork$/, '') as LiveDevstackNetworkName,\n\t\t\t};\n\t}\n};\n\nexport const parseDevstackNetworkName = (\n\tvalue: string | undefined,\n\tsource = 'DEVSTACK_NETWORK',\n): DevstackNetworkName => parseDevstackNetwork(value, source).name;\n"],"mappings":"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"}

package/dist/api/mode-narrowed-factory.d.mts

@@ -0,0 +1,26 @@
+import { NetworkConfig, NetworkMode } from "../substrate/network.mjs";
+
+//#region src/api/mode-narrowed-factory.d.ts
+/** A factories record keyed by network mode. Each branch is an
+ *  arbitrary record of factory functions. */
+type FactoriesByMode<F extends Partial<Record<NetworkMode, unknown>>> = F;
+/** Project the factories record to the branch that matches a network's
+ *  mode. Branches that aren't present collapse to `never`, which makes
+ *  the property access fail at compile time. */
+type FactoriesFor<F extends Partial<Record<NetworkMode, unknown>>, Mode extends NetworkMode> = Mode extends keyof F ? F[Mode] : never;
+/**
+ * Plugin-author entry point. Pass a per-mode factories record; receive
+ * a callable namespace. The returned value type is
+ * narrowed to the matching mode branch — illegal-mode property access
+ * is a compile error.
+ *
+ * Two casts here are the boundary between runtime breadth and type-level
+ * narrowness (type-prototype results §"Where I had to use any/casts"):
+ *  - The runtime returns the full factories record.
+ *  - The type system projects it down to the matching branch.
+ */
+type ModeNamespace<F extends Partial<Record<NetworkMode, unknown>>> = <N extends NetworkConfig>(network: N) => FactoriesFor<F, N['mode']>;
+declare function defineModeNamespace<F extends Partial<Record<NetworkMode, unknown>>>(factoriesPerMode: F): ModeNamespace<F>;
+//#endregion
+export { FactoriesByMode, FactoriesFor, ModeNamespace, defineModeNamespace };
+//# sourceMappingURL=mode-narrowed-factory.d.mts.map

package/dist/api/mode-narrowed-factory.mjs

@@ -0,0 +1,8 @@
+//#region src/api/mode-narrowed-factory.ts
+function defineModeNamespace(factoriesPerMode) {
+	return ((network) => factoriesPerMode[network.mode]);
+}
+//#endregion
+export { defineModeNamespace };
+
+//# sourceMappingURL=mode-narrowed-factory.mjs.map

package/dist/api/mode-narrowed-factory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-narrowed-factory.mjs","names":[],"sources":["../../src/api/mode-narrowed-factory.ts"],"sourcesContent":["// Mode-narrowed factory helper.\n//\n// Architecture Tension 11 + type-prototype finding #4: a plugin's\n// factories are exposed as an object indexed by `NetworkMode`. When a\n// stack passes a typed-narrow network through `defineDevstackWith`, the\n// callback receives a namespace whose accessible properties are exactly\n// those present in the network's mode branch. Asking for the wrong\n// branch is a compile error at the call site.\n//\n// Two surfaces:\n//\n//   - `defineModeNamespace({ local, live, fork })` — plugin authors\n//     declare their per-mode factories once; the helper hands back a\n//     callable namespace that does the narrowing.\n\nimport type { NetworkConfig, NetworkMode } from '../substrate/network.ts';\n\n/** A factories record keyed by network mode. Each branch is an\n *  arbitrary record of factory functions. */\nexport type FactoriesByMode<F extends Partial<Record<NetworkMode, unknown>>> = F;\n\n/** Project the factories record to the branch that matches a network's\n *  mode. Branches that aren't present collapse to `never`, which makes\n *  the property access fail at compile time. */\nexport type FactoriesFor<\n\tF extends Partial<Record<NetworkMode, unknown>>,\n\tMode extends NetworkMode,\n> = Mode extends keyof F ? F[Mode] : never;\n\n/**\n * Plugin-author entry point. Pass a per-mode factories record; receive\n * a callable namespace. The returned value type is\n * narrowed to the matching mode branch — illegal-mode property access\n * is a compile error.\n *\n * Two casts here are the boundary between runtime breadth and type-level\n * narrowness (type-prototype results §\"Where I had to use any/casts\"):\n *  - The runtime returns the full factories record.\n *  - The type system projects it down to the matching branch.\n */\nexport type ModeNamespace<F extends Partial<Record<NetworkMode, unknown>>> = <\n\tN extends NetworkConfig,\n>(\n\tnetwork: N,\n) => FactoriesFor<F, N['mode']>;\n\nexport function defineModeNamespace<F extends Partial<Record<NetworkMode, unknown>>>(\n\tfactoriesPerMode: F,\n): ModeNamespace<F> {\n\treturn (<N extends NetworkConfig>(network: N) =>\n\t\tfactoriesPerMode[network.mode as keyof F] as FactoriesFor<F, N['mode']>) as ModeNamespace<F>;\n}\n"],"mappings":";AA8CA,SAAgB,oBACf,kBACmB;AACnB,UAAkC,YACjC,iBAAiB,QAAQ"}

package/dist/api/plugin-errors.mjs

@@ -0,0 +1,10 @@
+//#region src/api/plugin-errors.ts
+const pluginErrorContributions = (errorTags, formatter) => [{
+	_tag: "PluginErrorContribution",
+	errorTags,
+	...formatter === void 0 ? {} : { formatter }
+}];
+//#endregion
+export { pluginErrorContributions };
+
+//# sourceMappingURL=plugin-errors.mjs.map

package/dist/api/plugin-errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-errors.mjs","names":[],"sources":["../../src/api/plugin-errors.ts"],"sourcesContent":["import type { PluginErrorContribution } from '../substrate/plugin.ts';\n\nexport const pluginErrorContributions = <Tags extends ReadonlyArray<string>>(\n\terrorTags: Tags,\n\tformatter?: PluginErrorContribution['formatter'],\n): readonly [PluginErrorContribution] => [\n\t{\n\t\t_tag: 'PluginErrorContribution',\n\t\terrorTags,\n\t\t...(formatter === undefined ? {} : { formatter }),\n\t},\n];\n"],"mappings":";AAEA,MAAa,4BACZ,WACA,cACwC,CACxC;CACC,MAAM;CACN;CACA,GAAI,cAAc,KAAA,IAAY,EAAE,GAAG,EAAE,WAAW;CAChD,CACD"}

package/dist/api/run-stack.d.mts

@@ -0,0 +1,82 @@
+import { SubscribableState } from "../substrate/projection.mjs";
+import { EngineEvent } from "../substrate/events.mjs";
+import { AnyPlugin } from "../substrate/plugin.mjs";
+import { Stack } from "./define-devstack.mjs";
+import { ProductionCodegenOptions } from "../orchestrators/runtime-composition.mjs";
+import { Cause, Effect, Layer, Stream, SubscriptionRef } from "effect";
+
+//#region src/api/run-stack.d.ts
+/** Identity overrides for `runStack`. App and stack fall back through
+ *  shared package metadata inference after their env overrides. */
+interface RunStackIdentityOptions {
+  readonly app?: string;
+  readonly stack?: string;
+  readonly network?: string;
+}
+interface RunStackOptions {
+  /** Identity overrides — falls back to env + library defaults. */
+  readonly identity?: RunStackIdentityOptions;
+  /** User application root. Codegen defaults to `<appRoot>/src/generated`.
+   *  Defaults to `process.cwd()`. */
+  readonly appRoot?: string;
+  /** Codegen output overrides for embedded tests or custom app layout. */
+  readonly codegen?: Omit<ProductionCodegenOptions, 'appRoot'>;
+  /** Filesystem root under which the substrate stores per-stack
+   *  artifacts (cache, snapshots, manifest, projection, etc.).
+   *  Defaults to `$DEVSTACK_STATE_DIR` then `<cwd>/.devstack`. */
+  readonly runtimeRoot?: string;
+  /** Extra Layer composition. Reserved for plugin-author overlays
+   *  (e.g. custom `CapabilitySinks`, Logger) per ARCHITECTURE.md
+   *  § Plugin-author extension via Layer composition. */
+  readonly layers?: Layer.Layer<never>;
+}
+/** Boot error surfaced by `RunHandle.start`. Wraps the supervisor's
+ *  startup failure tree for cascade-formatter rendering. */
+interface BootError {
+  readonly _tag: 'BootError';
+  readonly cause: Cause.Cause<unknown>;
+}
+/** Programmatic handle. Symmetric with the attached CLI surface:
+ *  `events`, `state`, and `awaitShutdown` are the same primitives the
+ *  TUI consumes in-process. */
+interface RunHandle {
+  /** Boot the supervisor and resolve when every plugin reaches
+   *  `ready`. Fails with `BootError` if any plugin's acquire path
+   *  fails. */
+  readonly start: Effect.Effect<void, BootError, never>;
+  /** Trigger graceful shutdown: enqueues `shutdown.requested` onto
+   *  the supervisor's command channel, then awaits the fiber. */
+  readonly stop: Effect.Effect<void, never, never>;
+  /** Resolve when the supervisor fiber exits. Always succeeds — any
+   *  errors surface via `start`. */
+  readonly awaitShutdown: Effect.Effect<void, never, never>;
+  /** Tail of typed engine events from the supervisor's hub. The
+   *  upstream is a `Queue.Dequeue`; consume via `Stream.run...`. */
+  readonly events: Stream.Stream<EngineEvent, never, never>;
+  /** The supervisor's live projection. Renderers + tests read this
+   *  directly; changes flow through `SubscriptionRef.changes`. */
+  readonly state: SubscriptionRef.SubscriptionRef<SubscribableState>;
+}
+/**
+ * Boot a `Stack` for programmatic embedding. Returns a `RunHandle`
+ * synchronously; the supervisor fiber is forked on `start`.
+ *
+ * Lifecycle:
+ *
+ *   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.
+ *   4. `await Effect.runPromise(handle.stop)` — graceful shutdown.
+ *   5. `handle.awaitShutdown` resolves once finalizers complete.
+ *
+ * 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.
+ */
+declare const runStack: (stack: Stack<ReadonlyArray<AnyPlugin>>, opts?: RunStackOptions) => RunHandle;
+//#endregion
+export { BootError, RunHandle, RunStackIdentityOptions, RunStackOptions, runStack };
+//# sourceMappingURL=run-stack.d.mts.map

package/dist/api/run-stack.mjs

@@ -0,0 +1,127 @@
+import { appName, chainId, stackName } from "../substrate/brand.mjs";
+import { readStackEngine } from "./define-devstack.mjs";
+import { makeProjectionRef } from "../substrate/runtime/projection/state-ref.mjs";
+import { buildSubstrateLayers, superviseStackEffect } from "../substrate/runtime/run.mjs";
+import { buildProductionOrchestratorSinks, buildProductionPostAcquireHook, layerProductionOrchestrators } from "../orchestrators/runtime-composition.mjs";
+import { extendBuiltInPluginContext, layerBuiltInPluginRuntime } from "../runtime/built-in-plugin-layers.mjs";
+import { resolveAppName, resolveStackName } from "./inference-network.mjs";
+import { Deferred, Effect, Exit, Fiber, Layer, Logger, Queue, Stream } from "effect";
+//#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 network = opts?.network ?? process.env.DEVSTACK_NETWORK ?? "sui:local";
+	return {
+		app: appName(app),
+		stack: stackName(stackNameStr),
+		chain: chainId(network)
+	};
+};
+const resolveRuntimeRoot = (override) => {
+	if (override !== void 0) return override;
+	const envRoot = process.env.DEVSTACK_STATE_DIR;
+	if (envRoot !== void 0 && envRoot.length > 0) return envRoot;
+	return `${process.cwd()}/.devstack`;
+};
+const toBootError = (cause) => ({
+	_tag: "BootError",
+	cause
+});
+/**
+* Boot a `Stack` for programmatic embedding. Returns a `RunHandle`
+* synchronously; the supervisor fiber is forked on `start`.
+*
+* Lifecycle:
+*
+*   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.
+*   4. `await Effect.runPromise(handle.stop)` — graceful shutdown.
+*   5. `handle.awaitShutdown` resolves once finalizers complete.
+*
+* 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.
+*/
+const runStack = (stack, opts = {}) => {
+	const engineStack = readStackEngine(stack);
+	const runtimeRoot = resolveRuntimeRoot(opts.runtimeRoot);
+	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 = Effect.runSync(makeProjectionRef());
+	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 substrate = layerProductionOrchestrators({ codegen: {
+		appRoot,
+		outputDir: codegen?.outputDir,
+		stackSubdir: codegen?.stackSubdir ?? null
+	} }).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: extendBuiltInPluginContext,
+			withinScope: (handle) => Effect.gen(function* () {
+				yield* Deferred.succeed(eventQueueRef, handle.events);
+				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));
+				}));
+				yield* Effect.forkScoped(Effect.gen(function* () {
+					yield* Deferred.await(stopRequested);
+					yield* Queue.offer(handle.commands, { tag: "shutdown.requested" });
+				}));
+			})
+		}).pipe(Effect.provide(layerBuiltInPluginRuntime(orchestratorSinks)));
+	});
+	const loggerLayer = Logger.layer([]);
+	const supervisedProgram = (opts.layers === void 0 ? supervised.pipe(Effect.provide(substrate), Effect.provide(loggerLayer)) : supervised.pipe(Effect.provide(substrate), Effect.provide(loggerLayer), Effect.provide(opts.layers))).pipe(Effect.catchCause((cause) => Deferred.fail(bootDeferred, toBootError(cause)).pipe(Effect.asVoid, Effect.catch(() => Effect.void))));
+	return {
+		start: Effect.gen(function* () {
+			if (!(yield* Deferred.isDone(fiberRef))) {
+				const fiber = yield* Effect.forkDetach(supervisedProgram);
+				yield* Deferred.succeed(fiberRef, fiber);
+			}
+			yield* 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);
+		}),
+		events: Stream.unwrap(Effect.gen(function* () {
+			const queue = yield* Deferred.await(eventQueueRef);
+			return Stream.fromQueue(queue);
+		})),
+		state
+	};
+};
+//#endregion
+export { runStack };
+
+//# sourceMappingURL=run-stack.mjs.map

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

@@ -0,0 +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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"}

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

@@ -0,0 +1,92 @@
+import { ResolveStackContextOptions } from "./stack-context.mjs";
+
+//#region src/build-integrations/playwright/config.d.ts
+type PlaywrightReporterShape = [string] | [string, Record<string, unknown>];
+/** 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. */
+interface PlaywrightBaseConfigShape {
+  readonly testDir: string;
+  readonly fullyParallel: boolean;
+  readonly forbidOnly: boolean;
+  readonly retries: number;
+  readonly workers: number;
+  readonly reporter: PlaywrightReporterShape[] | string;
+  readonly globalSetup?: string;
+  readonly globalTeardown?: string;
+}
+type PlaywrightUseConfigShape = {
+  readonly baseURL: string;
+  readonly trace: 'on-first-retry' | 'off' | 'retain-on-failure';
+  readonly screenshot: 'only-on-failure' | 'off' | 'on';
+} & Record<string, unknown>;
+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;
+  /** Path to a global-setup module. Default: not wired. Pass `null`
+   *  to keep the property omitted when composing conditionally. */
+  readonly globalSetup?: string | null;
+}
+interface DevstackPlaywrightEndpointOptions extends ResolveStackContextOptions {
+  /** Endpoint name whose URL becomes `webServer.url` + `use.baseURL`.
+   *  Default: `'dev'` (the host-service dev server endpoint). */
+  readonly endpointName?: string;
+  /** Explicit baseURL override. When set, manifest discovery is
+   *  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. */
+  readonly projects?: ReadonlyArray<PlaywrightProjectShape>;
+}
+interface DevstackPlaywrightUseOptions extends DevstackPlaywrightEndpointOptions {
+  readonly trace?: PlaywrightUseConfigShape['trace'];
+  readonly screenshot?: PlaywrightUseConfigShape['screenshot'];
+  readonly use?: Omit<Partial<PlaywrightUseConfigShape>, 'baseURL'>;
+}
+/**
+ * Resolve the browser app URL Playwright should target. This is the
+ * only helper here that may synchronously read the manifest; callers
+ * can pass `baseURL` to bypass discovery entirely.
+ */
+declare const resolveDevstackPlaywrightBaseURL: (options?: DevstackPlaywrightEndpointOptions) => string;
+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 };
+//# sourceMappingURL=config.d.mts.map

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

@@ -0,0 +1,71 @@
+import { resolveEndpointUrl } from "./stack-context.mjs";
+//#region src/build-integrations/playwright/config.ts
+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";
+/**
+* Resolve the browser app URL Playwright should target. This is the
+* only helper here that may synchronously read the manifest; callers
+* can pass `baseURL` to bypass discovery entirely.
+*/
+const resolveDevstackPlaywrightBaseURL = (options = {}) => {
+	const endpointName = options.endpointName ?? DEFAULT_ENDPOINT_NAME;
+	return options.baseURL ?? resolveEndpointUrl(endpointName, {
+		...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+		...options.manifestPath !== void 0 ? { manifestPath: options.manifestPath } : {},
+		...options.stack !== void 0 ? { stack: options.stack } : {},
+		...options.stateDir !== void 0 ? { stateDir: options.stateDir } : {},
+		...options.env !== void 0 ? { env: options.env } : {}
+	}).url;
+};
+const devstackPlaywrightBaseConfig = (options = {}) => {
+	const ci = Boolean(process.env.CI);
+	return {
+		testDir: options.testDir ?? DEFAULT_TEST_DIR,
+		fullyParallel: false,
+		forbidOnly: ci,
+		retries: ci ? 2 : 0,
+		workers: 1,
+		reporter: ci ? [["github"], ["list"]] : "list",
+		globalSetup: options.globalSetup === null ? void 0 : options.globalSetup ?? void 0
+	};
+};
+const devstackPlaywrightUse = (options = {}) => ({
+	baseURL: resolveDevstackPlaywrightBaseURL(options),
+	trace: options.trace ?? "on-first-retry",
+	screenshot: options.screenshot ?? "only-on-failure",
+	...options.use ?? {}
+});
+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 };
+
+//# sourceMappingURL=config.mjs.map

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

@@ -0,0 +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"}