@mysten-incubation/devstack 0.1.1 → 0.3.0

package/dist/build-integrations/vite/index.mjs

@@ -1,30 +1,51 @@
+import { decodeIdConfig } from "../../orchestrators/codegen/id-config.mjs";
+import { resolveNetworkOptions } from "../../orchestrators/network-options.mjs";
 import { resolveDiscoveryEnv } from "../runtime/resolve-discovery-env.mjs";
 import { discoverManifestPath } from "../runtime/discover.mjs";
 import "../runtime/index.mjs";
 import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { isAbsolute, resolve } from "node:path";
 //#region src/build-integrations/vite/index.ts
 /** Default import-alias prefix. Customizable via `options.alias` (some
 *  apps prefer `@gen`, `~generated`, …). The app MUST use the SAME
 *  prefix in three derivable places: this plugin option, the
 *  `tsconfig` `paths` entry, and its import specifiers. */
 const DEFAULT_GENERATED_ALIAS = "@generated";
-/** Default primary-stack output subpath, relative to the Vite root. The
-*  cold-start fallback when no manifest / `codegen.generatedDir` is on
-*  disk yet. Mirrors `output-location.ts`'s primary rule. */
-const FALLBACK_GENERATED_SUBPATH = "src/generated";
-/** Best-effort, SYNC read of the manifest-recorded `codegen.generatedDir`
-*  for the active stack. Returns the absolute dir, or `null` on any
-*  miss (no manifest yet, no `codegen` field, unreadable/corrupt file).
-*  Never throws — the caller falls back to `src/generated/`. We read +
-*  `JSON.parse` directly (rather than the schema-decoding
-*  `readStackContext`, which (a) drops the `codegen` field in its
-*  projection and (b) throws on a version mismatch) so an out-of-date
-*  or partially-written manifest degrades to the cold-start fallback
-*  instead of crashing the dev server. */
-const readGeneratedDirFromManifest = (env, cwd) => {
+/** Default dev-extras import-alias prefix. Resolves the PRIMARY stack's
+*  `.devstack/stacks/<stack>/generated-extras` tree (dev-only / secret
+*  artifacts — `accounts.ts`, `dev-wallet.ts`). Mirror the `@generated`
+*  three-place discipline: this option, the `tsconfig` `paths` entry,
+*  and the import specifiers. */
+const DEFAULT_DEV_EXTRAS_ALIAS = "@devstack-dev";
+/** The committed generated-bindings subpath, relative to the Vite root.
+*  The single source of bindings — written by `devstack codegen` — that
+*  `@generated` always resolves to (absent the `options.generatedDir`
+*  escape hatch). */
+const GENERATED_SUBPATH = "src/generated";
+/** Virtual module id the dev-only HTML injection imports. Vite convention:
+*  a `virtual:` specifier resolved to a `\0`-prefixed id in `resolveId`. */
+const VIRTUAL_DEV_WALLET_ID = "virtual:devstack-dev-wallet";
+const RESOLVED_VIRTUAL_DEV_WALLET_ID = "\0virtual:devstack-dev-wallet";
+/** The `/@id/` URL form Vite's middleware understands for a `\0`-prefixed
+*  virtual id: the NUL byte is encoded as the literal `__x00__` token (a
+*  raw `\0` in an HTML attribute is mangled to a space, which Vite then
+*  misroutes to the SPA fallback). Used for the injected `<script src>`. */
+const VIRTUAL_DEV_WALLET_SCRIPT_SRC = `/@id/__x00__${VIRTUAL_DEV_WALLET_ID}`;
+/** Best-effort, SYNC read of a string-valued field at `dottedPath` (e.g.
+*  `'codegen.idsFile'`, `'identity.network'`) from the active stack's
+*  manifest. Walks each path segment as a nested object, returning the leaf
+*  value, or `null` on ANY miss (absent / partially-written / version-
+*  mismatched manifest, a non-object hop, a missing or non-string/empty
+*  leaf). We read + `JSON.parse` directly (rather than the schema-decoding
+*  `readStackContext`, which drops the `codegen` field in its projection
+*  and throws on a version mismatch) so an out-of-date or partially-written
+*  manifest degrades gracefully instead of crashing the dev server. Never
+*  throws — the single discover→parse→guard→degrade-to-null reader every
+*  manifest field above (`codegen.idsFile`, `codegen.extrasDir`,
+*  `identity.network`) routes through. */
+const readManifestField = (env, cwd, dottedPath) => {
 	try {
-		const { stack, stateDir } = resolveDiscoveryEnv(env);
+		const { stack, stateDir } = resolveDiscoveryEnv(env, { cwd });
 		const manifestPath = discoverManifestPath({
 			env,
 			stack,
@@ -32,19 +53,52 @@ const readGeneratedDirFromManifest = (env, cwd) => {
 			cwd
 		});
 		if (manifestPath === void 0 || !existsSync(manifestPath)) return null;
-		const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
-		if (typeof parsed !== "object" || parsed === null) return null;
-		const codegen = parsed.codegen;
-		if (typeof codegen !== "object" || codegen === null) return null;
-		const generatedDir = codegen.generatedDir;
-		return typeof generatedDir === "string" && generatedDir.length > 0 ? generatedDir : null;
+		let node = JSON.parse(readFileSync(manifestPath, "utf8"));
+		for (const segment of dottedPath.split(".")) {
+			if (typeof node !== "object" || node === null) return null;
+			node = node[segment];
+		}
+		return typeof node === "string" && node.length > 0 ? node : null;
 	} catch {
 		return null;
 	}
 };
+/** The gitignored `devstack-ids.json` path the boot wrote for the active
+*  stack (`codegen.idsFile`), or `null` on any miss. */
+const readIdsFileFromManifest = (env, cwd) => readManifestField(env, cwd, "codegen.idsFile");
+/** SYNC read + schema-decode of an id-config FILE. The MISSING-file case
+*  (absent path, no file on disk) collapses to `null` so the Vite config
+*  load degrades gracefully when no stack has booted / no committed file is
+*  wired. A PRESENT-but-malformed file is NOT swallowed: it flows through
+*  the shared {@link decodeIdConfig}, which THROWS on bad JSON or a shape
+*  that violates `IdConfigSchema` — surfacing a genuinely broken committed
+*  id-config at config-load instead of silently injecting `null`. */
+const readIdConfigFile = (idsFile) => {
+	if (idsFile === null || !existsSync(idsFile)) return null;
+	return decodeIdConfig(readFileSync(idsFile, "utf8"));
+};
+/** Resolve the on-chain ids to inject as the `__DEVSTACK_IDS__` global —
+*  ALWAYS from an id-config FILE (same schema in dev and prod), never a
+*  JSON env blob. Dev (`serve`): the live `devstack-ids.json` (via the
+*  manifest `codegen.idsFile`). Prod (`build`): the committed known-
+*  deployment file — the plugin `ids` option, else the `DEVSTACK_IDS_FILE`
+*  env (a PATH pointer, not data). Neither ⇒ `null`, so the generated
+*  resolver throws loudly at id-access time. */
+const resolveInjectedIds = (env, root, command, idsOption) => {
+	if (command === "build") {
+		const pointer = idsOption ?? env["DEVSTACK_IDS_FILE"];
+		if (pointer === void 0 || pointer.length === 0) return null;
+		return readIdConfigFile(isAbsolute(pointer) ? pointer : resolve(root, pointer));
+	}
+	return readIdConfigFile(readIdsFileFromManifest(env, root));
+};
+/** The manifest-recorded dev-extras tree (`codegen.extrasDir`) the
+*  `@devstack-dev` alias points at for the active stack, or `null` on any
+*  miss. */
+const readExtrasDirFromManifest = (env, cwd) => readManifestField(env, cwd, "codegen.extrasDir");
 /**
 * Build the devstack Vite plugin that aliases `options.alias`
-* (default `@generated`) at the active stack's codegen output dir.
+* (default `@generated`) at the committed `<root>/src/generated` tree.
 *
 *     // vite.config.ts
 *     import { devstackVitePlugin } from '@mysten-incubation/devstack/vite';
@@ -53,21 +107,178 @@ const readGeneratedDirFromManifest = (env, cwd) => {
 *
 * The plugin's `config` hook merges `resolve.alias[<prefix>] = <dir>`
 * into the user config (Vite deep-merges the returned partial). Sync;
-* reads `process.env` + the manifest once at config-load.
+* reads `process.env` + the manifest (for `__DEVSTACK_IDS__` / the
+* `@devstack-dev` extras dir) once at config-load.
 */
+/** Derive the cold-start fallback dev-extras dir
+*  (`<root>/.devstack/stacks/<stack>/generated-extras`) for the active
+*  stack — used when no manifest / `codegen.extrasDir` is on disk yet.
+*  Mirrors `output-location.ts`'s `extrasDirFor`. Best-effort: a
+*  discovery failure collapses to the `default` stack name. */
+const fallbackExtrasDir = (env, root) => {
+	let stack = "default";
+	try {
+		stack = resolveDiscoveryEnv(env, { cwd: root }).stack;
+	} catch {}
+	return resolve(root, ".devstack", "stacks", stack, "generated-extras");
+};
+/** Resolve the dev-extras dir for the active stack (shared by the alias
+*  config and the dev-wallet virtual module). Explicit option wins, else
+*  manifest `codegen.extrasDir`, else the derived cold-start path. */
+const resolveExtrasDir = (options, root, env) => {
+	const explicitExtras = options.extrasDir;
+	return explicitExtras !== void 0 ? resolve(root, explicitExtras) : readExtrasDirFromManifest(env, root) ?? fallbackExtrasDir(env, root);
+};
+/** Read the `DEVSTACK_AUTO_APPROVE` env (`'1'`/`'true'`, case-insensitive). */
+const autoApproveFromEnv = (env) => {
+	const raw = env["DEVSTACK_AUTO_APPROVE"];
+	return raw === "1" || raw?.toLowerCase() === "true";
+};
+/** Lit packages deduped to a single instance. The injected dev-wallet UI and
+*  the app's dapp-kit UI are both Lit-based; if Vite loads two Lit copies they
+*  register custom elements in separate realms, and the second realm's element
+*  classes are unknown to the global `customElements` registry — so re-rendering
+*  the dev-wallet UI (e.g. on disconnect/reconnect) throws `Illegal constructor`
+*  and leaves the app in an unusable connection state. */
+const LIT_DEDUPE = [
+	"lit",
+	"lit-html",
+	"lit-element",
+	"@lit/reactive-element"
+];
+/** Filter {@link LIT_DEDUPE} to the packages actually installed at the app
+*  root (`<root>/node_modules/<pkg>`). `resolve.dedupe` forces Vite to
+*  resolve each listed package from the ROOT copy — but under pnpm's strict
+*  layout a package is only surfaced at the root when the app declares it as
+*  a direct dependency. Listing a package that is merely a phantom
+*  (transitive-only, reachable solely under `@mysten/dapp-kit-core`'s nested
+*  store dir) makes Vite's resolver look for a root copy that does not exist
+*  and FAIL the production build with `Rollup failed to resolve import
+*  "lit"`. So we dedupe only what the app truly hoists: the `app` template
+*  declares `lit` (all dapp-kit-core Lit usage routes through the `lit`
+*  meta-package, so one `lit` ⇒ one nested `@lit/reactive-element`); the
+*  sub-packages stay phantom and are correctly dropped here. */
+const resolvableLitDedupe = (root) => LIT_DEDUPE.filter((pkg) => existsSync(resolve(root, "node_modules", ...pkg.split("/"))));
+/** The dev-wallet entry points the injected virtual module imports. They are
+*  reached only through the `<script>` this plugin adds in `transformIndexHtml`,
+*  so Vite's initial dep scan never sees them and re-optimizes mid-session the
+*  first time the page loads them — and that late, separate optimize pass pulls
+*  a SECOND Lit instance (see {@link LIT_DEDUPE}). Pre-bundling them up front via
+*  `optimizeDeps.include` keeps the whole dev-wallet UI graph in the initial pass,
+*  sharing one Lit. */
+const DEV_WALLET_OPTIMIZE_ENTRIES = ["@mysten-incubation/dev-wallet/inject", "@mysten-incubation/dev-wallet/adapters"];
+/** True when `@mysten-incubation/dev-wallet` is installed at the app root —
+*  i.e. the app actually depends on the dev wallet (the `app` template does;
+*  the headless `ts` template does not). Checked by package presence rather
+*  than `require.resolve('.../inject')`, whose `exports` entry declares only an
+*  `import` condition (the CJS resolver throws `ERR_PACKAGE_PATH_NOT_EXPORTED`).
+*  Best-effort: if it's absent we never hand Vite an `optimizeDeps.include` it
+*  can't resolve (which would fail the dep scan). */
+const devWalletInstalled = (root) => existsSync(resolve(root, "node_modules", "@mysten-incubation", "dev-wallet", "package.json"));
 const devstackVitePlugin = (options = {}) => {
 	const alias = options.alias ?? "@generated";
+	const devExtrasAlias = options.devExtrasAlias ?? "@devstack-dev";
+	const injectDevWallet = options.injectDevWallet ?? true;
+	let resolvedRoot = process.cwd();
+	let resolvedExtrasDir = null;
+	let isServe = false;
 	return {
 		name: "devstack:generated-alias",
-		config: (config) => {
+		config: (config, configEnv) => {
 			const root = config.root ?? process.cwd();
+			resolvedRoot = root;
+			const env = process.env;
+			const command = configEnv?.command ?? config.command ?? "build";
 			const explicit = options.generatedDir;
-			const generatedDir = explicit !== void 0 ? resolve(root, explicit) : readGeneratedDirFromManifest(process.env, root) ?? resolve(root, FALLBACK_GENERATED_SUBPATH);
-			return { resolve: { alias: { [alias]: generatedDir } } };
+			const generatedDir = explicit !== void 0 ? resolve(root, explicit) : resolve(root, GENERATED_SUBPATH);
+			const extrasDir = resolveExtrasDir(options, root, env);
+			resolvedExtrasDir = extrasDir;
+			const includeDevWallet = injectDevWallet && devWalletInstalled(root);
+			const injectedIds = resolveInjectedIds(env, root, command, options.ids);
+			const isVitest = env["VITEST"] !== void 0;
+			const idsDefine = command === "serve" && !isVitest ? "globalThis.__DEVSTACK_IDS_LIVE__" : JSON.stringify(injectedIds ?? null);
+			return {
+				resolve: {
+					alias: {
+						[alias]: generatedDir,
+						[devExtrasAlias]: extrasDir
+					},
+					dedupe: resolvableLitDedupe(root)
+				},
+				define: { __DEVSTACK_IDS__: idsDefine },
+				...includeDevWallet ? { optimizeDeps: { include: [...DEV_WALLET_OPTIMIZE_ENTRIES] } } : {}
+			};
+		},
+		configResolved: (config) => {
+			isServe = config.command !== "build";
+		},
+		resolveId: (id) => {
+			if (id === VIRTUAL_DEV_WALLET_ID) return RESOLVED_VIRTUAL_DEV_WALLET_ID;
+		},
+		load: (id) => {
+			if (id !== RESOLVED_VIRTUAL_DEV_WALLET_ID) return void 0;
+			const extrasDir = resolvedExtrasDir ?? resolveExtrasDir(options, resolvedRoot, process.env);
+			const devWalletFile = resolve(extrasDir, "dev-wallet.ts");
+			const accountsFile = resolve(extrasDir, "accounts.ts");
+			if (!injectDevWallet || !isServe || !existsSync(devWalletFile) || !existsSync(accountsFile)) return "export {};";
+			const env = process.env;
+			const netOpts = resolveNetworkOptions(readManifestField(env, resolvedRoot, "identity.network") ?? "mainnet", options.networkOptions);
+			const autoApprove = options.autoApprove ?? (autoApproveFromEnv(env) || netOpts.autoApproveSigning);
+			return [
+				`import { registerDevstackDevWallet } from '@mysten-incubation/dev-wallet/inject';`,
+				`import { parseDevstackToken } from '@mysten-incubation/dev-wallet/adapters';`,
+				`import { devWallet } from '${devExtrasAlias}/dev-wallet.js';`,
+				`import { accounts } from '${devExtrasAlias}/accounts.js';`,
+				`import { config as __devstackConfig } from '${alias}/config.js';`,
+				`registerDevstackDevWallet({`,
+				`  serverOrigin: devWallet.walletUrl,`,
+				`  token: parseDevstackToken(devWallet.pairUrl),`,
+				`  accounts,`,
+				`  rpcUrl: __devstackConfig.networks[__devstackConfig.network].rpc,`,
+				`  network: devWallet.network,`,
+				`  autoApprove: ${autoApprove ? "true" : "false"},`,
+				`  mountUI: true,`,
+				`}).catch((err) => console.error('[devstack] dev-wallet injection failed:', err));`
+			].join("\n");
+		},
+		configureServer: (server) => {
+			if (!isServe) return;
+			const env = process.env;
+			const idsFile = readIdsFileFromManifest(env, resolvedRoot);
+			if (idsFile === null) return;
+			server.watcher.add(idsFile);
+			const reloadOnIdsChange = (changed) => {
+				if (resolve(resolvedRoot, changed) !== resolve(idsFile)) return;
+				(server.hot ?? server.ws)?.send({ type: "full-reload" });
+			};
+			server.watcher.on("change", reloadOnIdsChange);
+			server.watcher.on("add", reloadOnIdsChange);
+		},
+		transformIndexHtml: (html) => {
+			if (!isServe) return void 0;
+			const env = process.env;
+			const liveIds = resolveInjectedIds(env, resolvedRoot, "serve", options.ids);
+			const tags = [{
+				tag: "script",
+				children: `globalThis.__DEVSTACK_IDS_LIVE__ = ${JSON.stringify(liveIds ?? null)};`,
+				injectTo: "head-prepend"
+			}];
+			if (injectDevWallet && devWalletInstalled(resolvedRoot)) tags.push({
+				tag: "script",
+				attrs: {
+					type: "module",
+					src: VIRTUAL_DEV_WALLET_SCRIPT_SRC
+				},
+				injectTo: "head"
+			});
+			return {
+				html,
+				tags
+			};
 		}
 	};
 };
 //#endregion
-export { DEFAULT_GENERATED_ALIAS, devstackVitePlugin };
+export { DEFAULT_DEV_EXTRAS_ALIAS, DEFAULT_GENERATED_ALIAS, devstackVitePlugin };
 
 //# sourceMappingURL=index.mjs.map

package/dist/build-integrations/vite/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/build-integrations/vite/index.ts"],"sourcesContent":["// Vite build-integration — `@generated` alias plugin.\n//\n// notes/per-stack-codegen-design.md §\"Import mapping via a customizable\n// alias\": app source imports its Move codegen through a configurable\n// alias prefix (default `@generated`) instead of `./generated`. This\n// plugin points that alias at the ACTIVE stack's output dir — the EXACT\n// dir codegen wrote to for the current stack — so two stacks of the\n// same app (`pnpm dev` on the primary stack + `pnpm test:e2e` on a\n// `--stack e2e` override) resolve `@generated/*` to different\n// directories and never read each other's clobbered package-id /\n// wallet-pair-token literals.\n//\n// The target is the manifest-recorded `codegen.generatedDir` (the\n// single source of truth — the supervisor wrote it at flush time; see\n// `orchestrators/codegen/output-location.ts` +\n// `runtime-composition.ts`). Resolution:\n//   1. `options.generatedDir` — explicit escape hatch, used verbatim.\n//   2. `resolveDiscoveryEnv(process.env)` → `{ stack, stateDir }`\n//      (single source of truth; honors `DEVSTACK_STACK` +\n//      `DEVSTACK_RUNTIME_ROOT`/`DEVSTACK_STATE_DIR`), then\n//      `discoverManifestPath(...)` locates `<stateDir>/stacks/<stack>/manifest.json`,\n//      and we read its `codegen.generatedDir`.\n//   3. Cold-start fallback — no manifest / no field yet → `<root>/src/generated`.\n//      (In the supervised flow Vite starts AFTER post-acquire codegen,\n//      so the field is present; the fallback is the pre-`up` window.)\n//\n// Because Playwright's `webServer` runs the app's OWN Vite as a child\n// inheriting `DEVSTACK_STACK`, the same plugin serves both `pnpm dev`\n// and the e2e dev server automatically. Vitest has its own Vite\n// pipeline, so apps add this plugin to `vitest.config.ts` too.\n//\n// SYNC + dependency-light, mirroring the playwright/vitest helpers: NO\n// heavy imports at module top-level, and `vite` is NOT imported (it is\n// an app-side dev dependency, not a devstack runtime dep). The return\n// value is a STRUCTURAL Vite `Plugin` — a `{ name, config }` object —\n// typed loosely so this module loads without `vite` installed. The\n// manifest read goes through the same `build-integrations/runtime`\n// machinery the playwright/vitest integrations use.\n\nimport { existsSync, readFileSync } from 'node:fs';\nimport { resolve } from 'node:path';\n\nimport { discoverManifestPath, resolveDiscoveryEnv } from '../runtime/index.ts';\n\n/** Default import-alias prefix. Customizable via `options.alias` (some\n *  apps prefer `@gen`, `~generated`, …). The app MUST use the SAME\n *  prefix in three derivable places: this plugin option, the\n *  `tsconfig` `paths` entry, and its import specifiers. */\nexport const DEFAULT_GENERATED_ALIAS = '@generated';\n\n/** Default primary-stack output subpath, relative to the Vite root. The\n *  cold-start fallback when no manifest / `codegen.generatedDir` is on\n *  disk yet. Mirrors `output-location.ts`'s primary rule. */\nconst FALLBACK_GENERATED_SUBPATH = 'src/generated';\n\nexport interface DevstackVitePluginOptions {\n\t/** Import-alias prefix. Default `'@generated'`. */\n\treadonly alias?: string;\n\t/** Explicit generated dir — bypasses manifest discovery entirely\n\t *  (escape hatch for unusual layouts / tests). Relative paths\n\t *  resolve against the Vite root. */\n\treadonly generatedDir?: string;\n}\n\n/** A `vite` `Plugin`'s `config` hook receives the partial user config.\n *  We only ever read `config.root` and return a `resolve.alias` patch,\n *  so a one-field structural subset is enough — this keeps the module\n *  loadable without `vite` types (mirroring how the playwright/vitest\n *  presets avoid importing their optional peer at module init). */\ninterface ViteUserConfigLike {\n\treadonly root?: string;\n}\n\n/** The structural `Plugin` shape we return — `name` + a `config` hook.\n *  Typed as the loose object Vite accepts (Vite's `Plugin` is\n *  structurally compatible) so callers spread it into `plugins: []`\n *  without devstack depending on `vite`. */\nexport interface DevstackVitePlugin {\n\treadonly name: string;\n\treadonly config: (config: ViteUserConfigLike) => {\n\t\treadonly resolve: { readonly alias: Record<string, string> };\n\t};\n}\n\n/** Best-effort, SYNC read of the manifest-recorded `codegen.generatedDir`\n *  for the active stack. Returns the absolute dir, or `null` on any\n *  miss (no manifest yet, no `codegen` field, unreadable/corrupt file).\n *  Never throws — the caller falls back to `src/generated/`. We read +\n *  `JSON.parse` directly (rather than the schema-decoding\n *  `readStackContext`, which (a) drops the `codegen` field in its\n *  projection and (b) throws on a version mismatch) so an out-of-date\n *  or partially-written manifest degrades to the cold-start fallback\n *  instead of crashing the dev server. */\nconst readGeneratedDirFromManifest = (\n\tenv: Readonly<Record<string, string | undefined>>,\n\tcwd: string,\n): string | null => {\n\ttry {\n\t\tconst { stack, stateDir } = resolveDiscoveryEnv(env);\n\t\tconst manifestPath = discoverManifestPath({ env, stack, stateDir, cwd });\n\t\tif (manifestPath === undefined || !existsSync(manifestPath)) return null;\n\t\tconst parsed: unknown = JSON.parse(readFileSync(manifestPath, 'utf8'));\n\t\tif (typeof parsed !== 'object' || parsed === null) return null;\n\t\tconst codegen = (parsed as { readonly codegen?: unknown }).codegen;\n\t\tif (typeof codegen !== 'object' || codegen === null) return null;\n\t\tconst generatedDir = (codegen as { readonly generatedDir?: unknown }).generatedDir;\n\t\treturn typeof generatedDir === 'string' && generatedDir.length > 0 ? generatedDir : null;\n\t} catch {\n\t\t// Discovery / read / parse failure → cold-start fallback. A\n\t\t// best-effort alias resolver must never fail the Vite config load.\n\t\treturn null;\n\t}\n};\n\n/**\n * Build the devstack Vite plugin that aliases `options.alias`\n * (default `@generated`) at the active stack's codegen output dir.\n *\n *     // vite.config.ts\n *     import { devstackVitePlugin } from '@mysten-incubation/devstack/vite';\n *     export default defineConfig({ plugins: [devstackVitePlugin()] });\n *     // or devstackVitePlugin({ alias: '@gen' })\n *\n * The plugin's `config` hook merges `resolve.alias[<prefix>] = <dir>`\n * into the user config (Vite deep-merges the returned partial). Sync;\n * reads `process.env` + the manifest once at config-load.\n */\nexport const devstackVitePlugin = (options: DevstackVitePluginOptions = {}): DevstackVitePlugin => {\n\tconst alias = options.alias ?? DEFAULT_GENERATED_ALIAS;\n\treturn {\n\t\tname: 'devstack:generated-alias',\n\t\tconfig: (config: ViteUserConfigLike) => {\n\t\t\tconst root = config.root ?? process.cwd();\n\t\t\t// Explicit `generatedDir` wins (relative → resolved against the\n\t\t\t// Vite root). Otherwise consult the manifest-recorded dir, then\n\t\t\t// fall back to the primary-stack `src/generated/` for the\n\t\t\t// pre-supervisor cold-start window.\n\t\t\tconst explicit = options.generatedDir;\n\t\t\tconst generatedDir =\n\t\t\t\texplicit !== undefined\n\t\t\t\t\t? resolve(root, explicit)\n\t\t\t\t\t: (readGeneratedDirFromManifest(\n\t\t\t\t\t\t\tprocess.env as Readonly<Record<string, string | undefined>>,\n\t\t\t\t\t\t\troot,\n\t\t\t\t\t\t) ?? resolve(root, FALLBACK_GENERATED_SUBPATH));\n\t\t\t// Return a partial config; Vite merges `resolve.alias` into the\n\t\t\t// existing alias map. A bare-prefix alias (no trailing `/`)\n\t\t\t// matches both `@generated` and `@generated/foo.js` under Vite's\n\t\t\t// default string-alias resolution.\n\t\t\treturn { resolve: { alias: { [alias]: generatedDir } } };\n\t\t},\n\t};\n};\n"],"mappings":";;;;;;;;;;AAgDA,MAAa,0BAA0B;;;;AAKvC,MAAM,6BAA6B;;;;;;;;;;AAwCnC,MAAM,gCACL,KACA,QACmB;AACnB,KAAI;EACH,MAAM,EAAE,OAAO,aAAa,oBAAoB,IAAI;EACpD,MAAM,eAAe,qBAAqB;GAAE;GAAK;GAAO;GAAU;GAAK,CAAC;AACxE,MAAI,iBAAiB,KAAA,KAAa,CAAC,WAAW,aAAa,CAAE,QAAO;EACpE,MAAM,SAAkB,KAAK,MAAM,aAAa,cAAc,OAAO,CAAC;AACtE,MAAI,OAAO,WAAW,YAAY,WAAW,KAAM,QAAO;EAC1D,MAAM,UAAW,OAA0C;AAC3D,MAAI,OAAO,YAAY,YAAY,YAAY,KAAM,QAAO;EAC5D,MAAM,eAAgB,QAAgD;AACtE,SAAO,OAAO,iBAAiB,YAAY,aAAa,SAAS,IAAI,eAAe;SAC7E;AAGP,SAAO;;;;;;;;;;;;;;;;AAiBT,MAAa,sBAAsB,UAAqC,EAAE,KAAyB;CAClG,MAAM,QAAQ,QAAQ,SAAA;AACtB,QAAO;EACN,MAAM;EACN,SAAS,WAA+B;GACvC,MAAM,OAAO,OAAO,QAAQ,QAAQ,KAAK;GAKzC,MAAM,WAAW,QAAQ;GACzB,MAAM,eACL,aAAa,KAAA,IACV,QAAQ,MAAM,SAAS,GACtB,6BACD,QAAQ,KACR,KACA,IAAI,QAAQ,MAAM,2BAA2B;AAKjD,UAAO,EAAE,SAAS,EAAE,OAAO,GAAG,QAAQ,cAAc,EAAE,EAAE;;EAEzD"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/build-integrations/vite/index.ts"],"sourcesContent":["// Vite build-integration — `@generated` alias plugin.\n//\n// App source imports Move codegen through a configurable alias prefix\n// (default `@generated`) instead of `./generated`. This plugin points\n// that alias at the committed `<root>/src/generated` tree — the ONE\n// source of bindings, written only by the stack-free `devstack codegen`\n// verb. On-chain ids are NOT baked into that tree; they resolve at\n// runtime via the `__DEVSTACK_IDS__` global (see `resolveInjectedIds`),\n// so the same generated source serves every stack. Resolution:\n//   1. `options.generatedDir` — explicit escape hatch (relative → root).\n//   2. `<root>/src/generated` — the committed tree, always.\n//\n// Because Playwright's `webServer` runs the app's OWN Vite as a child,\n// the same plugin serves both `pnpm dev` and the e2e dev server\n// automatically. Vitest has its own Vite pipeline, so apps add this\n// plugin to `vitest.config.ts` too — and resolve `@generated` to the\n// same committed tree (the per-stack live tree no longer exists).\n//\n// SYNC + dependency-light, mirroring the playwright/vitest helpers: NO\n// heavy imports at module top-level, and `vite` is NOT imported (it is\n// an app-side dev dependency, not a devstack runtime dep). The return\n// value is a STRUCTURAL Vite `Plugin` — a `{ name, config }` object —\n// typed loosely so this module loads without `vite` installed. The\n// manifest read goes through the same `build-integrations/runtime`\n// machinery the playwright/vitest integrations use.\n\nimport { existsSync, readFileSync } from 'node:fs';\nimport { isAbsolute, resolve } from 'node:path';\n\nimport { discoverManifestPath, resolveDiscoveryEnv } from '../runtime/index.ts';\nimport { resolveNetworkOptions } from '../../orchestrators/network-options.ts';\nimport { decodeIdConfig } from '../../orchestrators/codegen/id-config.ts';\n\n/** Default import-alias prefix. Customizable via `options.alias` (some\n *  apps prefer `@gen`, `~generated`, …). The app MUST use the SAME\n *  prefix in three derivable places: this plugin option, the\n *  `tsconfig` `paths` entry, and its import specifiers. */\nexport const DEFAULT_GENERATED_ALIAS = '@generated';\n\n/** Default dev-extras import-alias prefix. Resolves the PRIMARY stack's\n *  `.devstack/stacks/<stack>/generated-extras` tree (dev-only / secret\n *  artifacts — `accounts.ts`, `dev-wallet.ts`). Mirror the `@generated`\n *  three-place discipline: this option, the `tsconfig` `paths` entry,\n *  and the import specifiers. */\nexport const DEFAULT_DEV_EXTRAS_ALIAS = '@devstack-dev';\n\n/** The committed generated-bindings subpath, relative to the Vite root.\n *  The single source of bindings — written by `devstack codegen` — that\n *  `@generated` always resolves to (absent the `options.generatedDir`\n *  escape hatch). */\nconst GENERATED_SUBPATH = 'src/generated';\n\nexport interface DevstackVitePluginOptions {\n\t/** Import-alias prefix. Default `'@generated'`. */\n\treadonly alias?: string;\n\t/** Dev-extras import-alias prefix. Default `'@devstack-dev'`. */\n\treadonly devExtrasAlias?: string;\n\t/** Explicit generated dir — bypasses manifest discovery entirely\n\t *  (escape hatch for unusual layouts / tests). Relative paths\n\t *  resolve against the Vite root. */\n\treadonly generatedDir?: string;\n\t/** Explicit dev-extras dir — bypasses manifest discovery. Relative\n\t *  paths resolve against the Vite root. */\n\treadonly extrasDir?: string;\n\t/** Inject + register the devstack dev wallet on the page in DEV\n\t *  (wallet-standard, so dApp Kit auto-discovers it). Defaults to\n\t *  `true`. Production builds (`command === 'build'`) inject nothing\n\t *  regardless. */\n\treadonly injectDevWallet?: boolean;\n\t/** Auto-approve all dev-wallet signing requests (headless Playwright /\n\t *  in-app \"Open/Join as\" buttons). Defaults to the `DEVSTACK_AUTO_APPROVE`\n\t *  env (`'1'`/`'true'`), then to the active network's `autoApproveSigning`\n\t *  per-network policy (ON for every network except live `mainnet`). A\n\t *  single switch, replacing per-app `VITE_*_AUTO_APPROVE`.\n\t *\n\t *  HARD-CLAMP: on live `mainnet` the per-network policy forces\n\t *  auto-approve OFF — a real-funds signature is NEVER granted without a\n\t *  human in the loop. An explicit `autoApprove: true` here, or\n\t *  `DEVSTACK_AUTO_APPROVE`, still take precedence (the author opted in\n\t *  deliberately), but the policy default never silently auto-approves on\n\t *  mainnet. */\n\treadonly autoApprove?: boolean;\n\t/** Per-network overrides for the dev-convenience policy (the same\n\t *  `networkOptions` shape `defineDevstack` takes, forwarded verbatim).\n\t *  Only the `autoApproveSigning` field is read here, to resolve the\n\t *  auto-approve default for the active network. Omitted ⇒ the built-in\n\t *  policy (ON except live `mainnet`) applies. The override RECORD is not\n\t *  otherwise on disk, so an app that customizes per-network signing must\n\t *  thread it here explicitly; the mainnet hard-clamp holds regardless. */\n\treadonly networkOptions?: Readonly<Record<string, unknown>>;\n\t/** Production id-config FILE — the known deployment's `devstack-ids.json`\n\t *  (same schema the dev stack writes), committed at e.g.\n\t *  `config/<network>.ids.json`. Used only for `command === 'build'` to\n\t *  inject `__DEVSTACK_IDS__`. Relative paths resolve against the Vite\n\t *  root. If omitted, the `DEVSTACK_IDS_FILE` env (a path pointer) is used.\n\t *  Neither ⇒ no ids baked, and the generated resolver throws loudly at\n\t *  id-access time. We deliberately take a FILE, not a JSON env blob: a\n\t *  real deployment's ids are many + nested. */\n\treadonly ids?: string;\n}\n\n/** A `vite` `Plugin`'s `config` hook receives the partial user config.\n *  We only ever read `config.root` and return a `resolve.alias` patch,\n *  so a one-field structural subset is enough — this keeps the module\n *  loadable without `vite` types (mirroring how the playwright/vitest\n *  presets avoid importing their optional peer at module init). */\ninterface ViteUserConfigLike {\n\treadonly root?: string;\n\treadonly command?: 'build' | 'serve';\n}\n\n/** Virtual module id the dev-only HTML injection imports. Vite convention:\n *  a `virtual:` specifier resolved to a `\\0`-prefixed id in `resolveId`. */\nconst VIRTUAL_DEV_WALLET_ID = 'virtual:devstack-dev-wallet';\nconst RESOLVED_VIRTUAL_DEV_WALLET_ID = '\\0virtual:devstack-dev-wallet';\n/** The `/@id/` URL form Vite's middleware understands for a `\\0`-prefixed\n *  virtual id: the NUL byte is encoded as the literal `__x00__` token (a\n *  raw `\\0` in an HTML attribute is mangled to a space, which Vite then\n *  misroutes to the SPA fallback). Used for the injected `<script src>`. */\nconst VIRTUAL_DEV_WALLET_SCRIPT_SRC = `/@id/__x00__${VIRTUAL_DEV_WALLET_ID}`;\n\n/** The structural `Plugin` shape we return — `name`, a `config` hook, and\n *  the DEV-only dev-wallet-injection hooks. Typed as the loose object Vite\n *  accepts (Vite's `Plugin` is structurally compatible) so callers spread\n *  it into `plugins: []` without devstack depending on `vite`. */\n/** Vite's `config` hook second arg — `{ command, mode }`. We read only\n *  `command` to pick the dev vs prod id-injection source. */\ninterface ViteConfigEnvLike {\n\treadonly command?: 'build' | 'serve';\n}\n\n/** The structural subset of Vite's `ViteDevServer` the `configureServer`\n *  hook uses: the chokidar `watcher` (to track the ids file) and the HMR\n *  channel (to push a full reload). `ws` is Vite's long-stable channel;\n *  `hot` is the newer alias — we use whichever the running Vite exposes. */\ninterface ViteDevServerLike {\n\treadonly watcher: {\n\t\tadd: (paths: string | ReadonlyArray<string>) => void;\n\t\ton: (event: 'change' | 'add', listener: (path: string) => void) => void;\n\t};\n\treadonly ws?: { send: (payload: { type: 'full-reload' }) => void };\n\treadonly hot?: { send: (payload: { type: 'full-reload' }) => void };\n}\n\nexport interface DevstackVitePlugin {\n\treadonly name: string;\n\treadonly config: (\n\t\tconfig: ViteUserConfigLike,\n\t\tenv?: ViteConfigEnvLike,\n\t) => {\n\t\treadonly resolve: {\n\t\t\treadonly alias: Record<string, string>;\n\t\t\t// Mutable `string[]` (NOT `readonly`): Vite's `ResolveOptions.dedupe`\n\t\t\t// and `DepOptimizationConfig.include` are both `string[] | undefined`,\n\t\t\t// and a `readonly string[]` return makes the whole `config` hook\n\t\t\t// unassignable to Vite's `Plugin` type in a consuming app's\n\t\t\t// `vite.config.ts`/`vitest.config.ts`. The value we return\n\t\t\t// (`resolvableLitDedupe(root)`, a freshly built array) is already\n\t\t\t// mutable.\n\t\t\treadonly dedupe?: string[];\n\t\t};\n\t\treadonly optimizeDeps?: { readonly include: string[] };\n\t\t/** `define` injecting the on-chain ids as `__DEVSTACK_IDS__`. In a\n\t\t *  prod `build` this is the static id literal; in dev `serve` it is a\n\t\t *  reference to the `globalThis.__DEVSTACK_IDS_LIVE__` runtime global\n\t\t *  the `transformIndexHtml` hook sets fresh per page load, so a\n\t\t *  republished id reaches the app on reload (`define` is fixed for the\n\t\t *  dev server's lifetime and could never hot-update). */\n\t\treadonly define: Record<string, string>;\n\t};\n\t/** Capture the resolved command so injection is DEV-only. */\n\treadonly configResolved: (config: ViteUserConfigLike) => void;\n\t/** Dev-only: watch the live `devstack-ids.json` and full-reload the page\n\t *  when it changes, so a republished package id (rewritten by the\n\t *  supervisor's post-acquire hook) reaches the running app. */\n\treadonly configureServer: (server: ViteDevServerLike) => void;\n\t/** Resolve the dev-wallet virtual module. */\n\treadonly resolveId: (id: string) => string | undefined;\n\t/** Emit the dev-wallet register module (or a no-op when not applicable). */\n\treadonly load: (id: string) => string | undefined;\n\t/** Inject the dev-only HTML tags: the `__DEVSTACK_IDS_LIVE__` global\n\t *  (read fresh from the ids file per request) and, when the app carries\n\t *  the dev wallet, the `<script type=\"module\">` importing the virtual\n\t *  module. The return shape mirrors a structural subset of Vite's\n\t *  `IndexHtmlTransformResult` so the plugin stays assignable to Vite's\n\t *  `Plugin` without devstack importing `vite`. */\n\treadonly transformIndexHtml: (html: string) =>\n\t\t| {\n\t\t\t\thtml: string;\n\t\t\t\ttags: Array<{\n\t\t\t\t\ttag: string;\n\t\t\t\t\tattrs?: Record<string, string | boolean>;\n\t\t\t\t\tchildren?: string;\n\t\t\t\t\tinjectTo: 'head' | 'head-prepend';\n\t\t\t\t}>;\n\t\t  }\n\t\t| undefined;\n}\n\n/** Best-effort, SYNC read of a string-valued field at `dottedPath` (e.g.\n *  `'codegen.idsFile'`, `'identity.network'`) from the active stack's\n *  manifest. Walks each path segment as a nested object, returning the leaf\n *  value, or `null` on ANY miss (absent / partially-written / version-\n *  mismatched manifest, a non-object hop, a missing or non-string/empty\n *  leaf). We read + `JSON.parse` directly (rather than the schema-decoding\n *  `readStackContext`, which drops the `codegen` field in its projection\n *  and throws on a version mismatch) so an out-of-date or partially-written\n *  manifest degrades gracefully instead of crashing the dev server. Never\n *  throws — the single discover→parse→guard→degrade-to-null reader every\n *  manifest field above (`codegen.idsFile`, `codegen.extrasDir`,\n *  `identity.network`) routes through. */\nconst readManifestField = (\n\tenv: Readonly<Record<string, string | undefined>>,\n\tcwd: string,\n\tdottedPath: string,\n): string | null => {\n\ttry {\n\t\tconst { stack, stateDir } = resolveDiscoveryEnv(env, { cwd });\n\t\tconst manifestPath = discoverManifestPath({ env, stack, stateDir, cwd });\n\t\tif (manifestPath === undefined || !existsSync(manifestPath)) return null;\n\t\tlet node: unknown = JSON.parse(readFileSync(manifestPath, 'utf8'));\n\t\tfor (const segment of dottedPath.split('.')) {\n\t\t\tif (typeof node !== 'object' || node === null) return null;\n\t\t\tnode = (node as Record<string, unknown>)[segment];\n\t\t}\n\t\treturn typeof node === 'string' && node.length > 0 ? node : null;\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n/** The gitignored `devstack-ids.json` path the boot wrote for the active\n *  stack (`codegen.idsFile`), or `null` on any miss. */\nconst readIdsFileFromManifest = (\n\tenv: Readonly<Record<string, string | undefined>>,\n\tcwd: string,\n): string | null => readManifestField(env, cwd, 'codegen.idsFile');\n\n/** SYNC read + schema-decode of an id-config FILE. The MISSING-file case\n *  (absent path, no file on disk) collapses to `null` so the Vite config\n *  load degrades gracefully when no stack has booted / no committed file is\n *  wired. A PRESENT-but-malformed file is NOT swallowed: it flows through\n *  the shared {@link decodeIdConfig}, which THROWS on bad JSON or a shape\n *  that violates `IdConfigSchema` — surfacing a genuinely broken committed\n *  id-config at config-load instead of silently injecting `null`. */\nconst readIdConfigFile = (idsFile: string | null): unknown => {\n\tif (idsFile === null || !existsSync(idsFile)) return null;\n\treturn decodeIdConfig(readFileSync(idsFile, 'utf8'));\n};\n\n/** Resolve the on-chain ids to inject as the `__DEVSTACK_IDS__` global —\n *  ALWAYS from an id-config FILE (same schema in dev and prod), never a\n *  JSON env blob. Dev (`serve`): the live `devstack-ids.json` (via the\n *  manifest `codegen.idsFile`). Prod (`build`): the committed known-\n *  deployment file — the plugin `ids` option, else the `DEVSTACK_IDS_FILE`\n *  env (a PATH pointer, not data). Neither ⇒ `null`, so the generated\n *  resolver throws loudly at id-access time. */\nconst resolveInjectedIds = (\n\tenv: Readonly<Record<string, string | undefined>>,\n\troot: string,\n\tcommand: 'build' | 'serve' | undefined,\n\tidsOption: string | undefined,\n): unknown => {\n\t// Prod build: the known deployment's committed id-config file. Option\n\t// wins; else a `DEVSTACK_IDS_FILE` path pointer. Relative → Vite root.\n\tif (command === 'build') {\n\t\tconst pointer = idsOption ?? env['DEVSTACK_IDS_FILE'];\n\t\tif (pointer === undefined || pointer.length === 0) return null;\n\t\treturn readIdConfigFile(isAbsolute(pointer) ? pointer : resolve(root, pointer));\n\t}\n\t// Dev serve (and config-load default): the live id-config file.\n\treturn readIdConfigFile(readIdsFileFromManifest(env, root));\n};\n\n/** The manifest-recorded dev-extras tree (`codegen.extrasDir`) the\n *  `@devstack-dev` alias points at for the active stack, or `null` on any\n *  miss. */\nconst readExtrasDirFromManifest = (\n\tenv: Readonly<Record<string, string | undefined>>,\n\tcwd: string,\n): string | null => readManifestField(env, cwd, 'codegen.extrasDir');\n\n/**\n * Build the devstack Vite plugin that aliases `options.alias`\n * (default `@generated`) at the committed `<root>/src/generated` tree.\n *\n *     // vite.config.ts\n *     import { devstackVitePlugin } from '@mysten-incubation/devstack/vite';\n *     export default defineConfig({ plugins: [devstackVitePlugin()] });\n *     // or devstackVitePlugin({ alias: '@gen' })\n *\n * The plugin's `config` hook merges `resolve.alias[<prefix>] = <dir>`\n * into the user config (Vite deep-merges the returned partial). Sync;\n * reads `process.env` + the manifest (for `__DEVSTACK_IDS__` / the\n * `@devstack-dev` extras dir) once at config-load.\n */\n/** Derive the cold-start fallback dev-extras dir\n *  (`<root>/.devstack/stacks/<stack>/generated-extras`) for the active\n *  stack — used when no manifest / `codegen.extrasDir` is on disk yet.\n *  Mirrors `output-location.ts`'s `extrasDirFor`. Best-effort: a\n *  discovery failure collapses to the `default` stack name. */\nconst fallbackExtrasDir = (\n\tenv: Readonly<Record<string, string | undefined>>,\n\troot: string,\n): string => {\n\tlet stack = 'default';\n\ttry {\n\t\tstack = resolveDiscoveryEnv(env, { cwd: root }).stack;\n\t} catch {\n\t\t// keep the `default` fallback.\n\t}\n\treturn resolve(root, '.devstack', 'stacks', stack, 'generated-extras');\n};\n\n/** Resolve the dev-extras dir for the active stack (shared by the alias\n *  config and the dev-wallet virtual module). Explicit option wins, else\n *  manifest `codegen.extrasDir`, else the derived cold-start path. */\nconst resolveExtrasDir = (\n\toptions: DevstackVitePluginOptions,\n\troot: string,\n\tenv: Readonly<Record<string, string | undefined>>,\n): string => {\n\tconst explicitExtras = options.extrasDir;\n\treturn explicitExtras !== undefined\n\t\t? resolve(root, explicitExtras)\n\t\t: (readExtrasDirFromManifest(env, root) ?? fallbackExtrasDir(env, root));\n};\n\n/** Read the `DEVSTACK_AUTO_APPROVE` env (`'1'`/`'true'`, case-insensitive). */\nconst autoApproveFromEnv = (env: Readonly<Record<string, string | undefined>>): boolean => {\n\tconst raw = env['DEVSTACK_AUTO_APPROVE'];\n\treturn raw === '1' || raw?.toLowerCase() === 'true';\n};\n\n/** Lit packages deduped to a single instance. The injected dev-wallet UI and\n *  the app's dapp-kit UI are both Lit-based; if Vite loads two Lit copies they\n *  register custom elements in separate realms, and the second realm's element\n *  classes are unknown to the global `customElements` registry — so re-rendering\n *  the dev-wallet UI (e.g. on disconnect/reconnect) throws `Illegal constructor`\n *  and leaves the app in an unusable connection state. */\nconst LIT_DEDUPE = ['lit', 'lit-html', 'lit-element', '@lit/reactive-element'] as const;\n\n/** Filter {@link LIT_DEDUPE} to the packages actually installed at the app\n *  root (`<root>/node_modules/<pkg>`). `resolve.dedupe` forces Vite to\n *  resolve each listed package from the ROOT copy — but under pnpm's strict\n *  layout a package is only surfaced at the root when the app declares it as\n *  a direct dependency. Listing a package that is merely a phantom\n *  (transitive-only, reachable solely under `@mysten/dapp-kit-core`'s nested\n *  store dir) makes Vite's resolver look for a root copy that does not exist\n *  and FAIL the production build with `Rollup failed to resolve import\n *  \"lit\"`. So we dedupe only what the app truly hoists: the `app` template\n *  declares `lit` (all dapp-kit-core Lit usage routes through the `lit`\n *  meta-package, so one `lit` ⇒ one nested `@lit/reactive-element`); the\n *  sub-packages stay phantom and are correctly dropped here. */\nconst resolvableLitDedupe = (root: string): string[] =>\n\tLIT_DEDUPE.filter((pkg) => existsSync(resolve(root, 'node_modules', ...pkg.split('/'))));\n\n/** The dev-wallet entry points the injected virtual module imports. They are\n *  reached only through the `<script>` this plugin adds in `transformIndexHtml`,\n *  so Vite's initial dep scan never sees them and re-optimizes mid-session the\n *  first time the page loads them — and that late, separate optimize pass pulls\n *  a SECOND Lit instance (see {@link LIT_DEDUPE}). Pre-bundling them up front via\n *  `optimizeDeps.include` keeps the whole dev-wallet UI graph in the initial pass,\n *  sharing one Lit. */\nconst DEV_WALLET_OPTIMIZE_ENTRIES = [\n\t'@mysten-incubation/dev-wallet/inject',\n\t'@mysten-incubation/dev-wallet/adapters',\n] as const;\n\n/** True when `@mysten-incubation/dev-wallet` is installed at the app root —\n *  i.e. the app actually depends on the dev wallet (the `app` template does;\n *  the headless `ts` template does not). Checked by package presence rather\n *  than `require.resolve('.../inject')`, whose `exports` entry declares only an\n *  `import` condition (the CJS resolver throws `ERR_PACKAGE_PATH_NOT_EXPORTED`).\n *  Best-effort: if it's absent we never hand Vite an `optimizeDeps.include` it\n *  can't resolve (which would fail the dep scan). */\nconst devWalletInstalled = (root: string): boolean =>\n\texistsSync(resolve(root, 'node_modules', '@mysten-incubation', 'dev-wallet', 'package.json'));\n\nexport const devstackVitePlugin = (options: DevstackVitePluginOptions = {}): DevstackVitePlugin => {\n\tconst alias = options.alias ?? DEFAULT_GENERATED_ALIAS;\n\tconst devExtrasAlias = options.devExtrasAlias ?? DEFAULT_DEV_EXTRAS_ALIAS;\n\tconst injectDevWallet = options.injectDevWallet ?? true;\n\n\t// Captured across hooks. `config` runs first (alias resolution),\n\t// `configResolved` records the command (DEV-gate), and `load` re-reads\n\t// the dev-wallet config off `extrasDir`.\n\tlet resolvedRoot = process.cwd();\n\tlet resolvedExtrasDir: string | null = null;\n\tlet isServe = false;\n\n\treturn {\n\t\tname: 'devstack:generated-alias',\n\t\tconfig: (config: ViteUserConfigLike, configEnv?: ViteConfigEnvLike) => {\n\t\t\tconst root = config.root ?? process.cwd();\n\t\t\tresolvedRoot = root;\n\t\t\tconst env = process.env as Readonly<Record<string, string | undefined>>;\n\t\t\t// `command` comes from the second hook arg (`{ command, mode }`);\n\t\t\t// fall back to `config.command` (some callers pass it on the\n\t\t\t// config). Default the UNKNOWN case to `build` (build-safe): only an\n\t\t\t// EXPLICIT `serve` takes the live local-stack id-injection path, so a\n\t\t\t// programmatic `vite.build()` that omits the env arg never bakes\n\t\t\t// dev-stack ids into a production bundle.\n\t\t\tconst command = configEnv?.command ?? config.command ?? 'build';\n\t\t\t// Explicit `generatedDir` wins (relative → resolved against the\n\t\t\t// Vite root). Otherwise always the committed `<root>/src/generated`\n\t\t\t// tree — the single source of bindings written by `devstack\n\t\t\t// codegen`; ids resolve at runtime via `__DEVSTACK_IDS__`, so the\n\t\t\t// same tree serves every stack.\n\t\t\tconst explicit = options.generatedDir;\n\t\t\tconst generatedDir =\n\t\t\t\texplicit !== undefined ? resolve(root, explicit) : resolve(root, GENERATED_SUBPATH);\n\t\t\t// `@devstack-dev` mirrors `@generated` exactly.\n\t\t\tconst extrasDir = resolveExtrasDir(options, root, env);\n\t\t\tresolvedExtrasDir = extrasDir;\n\t\t\t// Return a partial config; Vite deep-merges it. `resolve.dedupe`\n\t\t\t// pins a single Lit copy, and — when this app carries the dev\n\t\t\t// wallet — we pre-bundle the injected dev-wallet entries so Vite\n\t\t\t// never re-optimizes them mid-session into a second Lit realm\n\t\t\t// (see the constants above).\n\t\t\tconst includeDevWallet = injectDevWallet && devWalletInstalled(root);\n\t\t\t// Inject the on-chain ids the generated `config-runtime.ts` resolver\n\t\t\t// reads as `__DEVSTACK_IDS__`.\n\t\t\t//   - PROD build: bake the static literal.\n\t\t\t//   - DEV server (`vite dev`): point the identifier at the\n\t\t\t//     `__DEVSTACK_IDS_LIVE__` runtime global the `transformIndexHtml`\n\t\t\t//     hook sets fresh per page load — `define` is fixed for the dev\n\t\t\t//     server's lifetime, so baking the value would pin the FIRST id\n\t\t\t//     forever and a republish would never reach the app. A distinct\n\t\t\t//     global name avoids a single-pass `define` token collision with\n\t\t\t//     `__DEVSTACK_IDS__`.\n\t\t\t//   - VITEST: vitest ALSO reports `command === 'serve'`, but it runs\n\t\t\t//     no `transformIndexHtml` (no HTML), so the live global is never\n\t\t\t//     set — and esbuild's stricter `define` rejects an operator\n\t\t\t//     expression anyway. Bake a literal instead: the Vite config loads\n\t\t\t//     BEFORE the test stack boots, so `injectedIds` is null and the\n\t\t\t//     resolver falls back to the `DEVSTACK_IDS_FILE` env the vitest\n\t\t\t//     globalSetup points at the freshly-booted stack (see\n\t\t\t//     vitest/global-setup.ts).\n\t\t\t// The define VALUE must be esbuild-valid (a JSON literal or a\n\t\t\t// member-access chain) — note the bare `globalThis.…`, NOT a\n\t\t\t// parenthesised `(… ?? null)`; `config-runtime.ts` already guards the\n\t\t\t// `typeof … === 'undefined'` case.\n\t\t\tconst injectedIds = resolveInjectedIds(env, root, command, options.ids);\n\t\t\tconst isVitest = env['VITEST'] !== undefined;\n\t\t\tconst idsDefine =\n\t\t\t\tcommand === 'serve' && !isVitest\n\t\t\t\t\t? 'globalThis.__DEVSTACK_IDS_LIVE__'\n\t\t\t\t\t: JSON.stringify(injectedIds ?? null);\n\t\t\treturn {\n\t\t\t\tresolve: {\n\t\t\t\t\t// A bare-prefix alias (no trailing `/`) matches both\n\t\t\t\t\t// `@generated` and `@generated/foo.js` under Vite's default\n\t\t\t\t\t// string-alias resolution.\n\t\t\t\t\talias: {\n\t\t\t\t\t\t[alias]: generatedDir,\n\t\t\t\t\t\t[devExtrasAlias]: extrasDir,\n\t\t\t\t\t},\n\t\t\t\t\tdedupe: resolvableLitDedupe(root),\n\t\t\t\t},\n\t\t\t\tdefine: {\n\t\t\t\t\t__DEVSTACK_IDS__: idsDefine,\n\t\t\t\t},\n\t\t\t\t...(includeDevWallet\n\t\t\t\t\t? { optimizeDeps: { include: [...DEV_WALLET_OPTIMIZE_ENTRIES] } }\n\t\t\t\t\t: {}),\n\t\t\t};\n\t\t},\n\n\t\tconfigResolved: (config: ViteUserConfigLike) => {\n\t\t\t// DEV-gate: only a `serve` command injects the dev wallet. A\n\t\t\t// production `vite build` injects nothing.\n\t\t\tisServe = config.command !== 'build';\n\t\t},\n\n\t\tresolveId: (id: string) => {\n\t\t\tif (id === VIRTUAL_DEV_WALLET_ID) return RESOLVED_VIRTUAL_DEV_WALLET_ID;\n\t\t\treturn undefined;\n\t\t},\n\n\t\tload: (id: string): string | undefined => {\n\t\t\tif (id !== RESOLVED_VIRTUAL_DEV_WALLET_ID) return undefined;\n\t\t\t// Graceful no-op when injection is off, not a dev serve, or the\n\t\t\t// dev-extras config is absent (no `devstack apply` yet).\n\t\t\tconst extrasDir = resolvedExtrasDir ?? resolveExtrasDir(options, resolvedRoot, process.env);\n\t\t\tconst devWalletFile = resolve(extrasDir, 'dev-wallet.ts');\n\t\t\tconst accountsFile = resolve(extrasDir, 'accounts.ts');\n\t\t\tif (!injectDevWallet || !isServe || !existsSync(devWalletFile) || !existsSync(accountsFile)) {\n\t\t\t\treturn 'export {};';\n\t\t\t}\n\t\t\tconst env = process.env as Readonly<Record<string, string | undefined>>;\n\t\t\t// Auto-approve resolution (highest precedence first): explicit\n\t\t\t// `options.autoApprove`, then the `DEVSTACK_AUTO_APPROVE` env, then\n\t\t\t// the active network's `autoApproveSigning` per-network policy. The\n\t\t\t// policy is ON for every network EXCEPT live `mainnet`, so a stack\n\t\t\t// booted against real mainnet never silently auto-approves a\n\t\t\t// real-funds signature. The active network comes from the manifest\n\t\t\t// boot wrote (`identity.network`); absent that we conservatively\n\t\t\t// resolve as `mainnet` (auto-approve OFF) rather than assuming a\n\t\t\t// dev network. The override RECORD isn't on disk — `networkOptions`\n\t\t\t// is read from the plugin option when the app threads it.\n\t\t\tconst network = readManifestField(env, resolvedRoot, 'identity.network') ?? 'mainnet';\n\t\t\tconst netOpts = resolveNetworkOptions(network, options.networkOptions);\n\t\t\tconst autoApprove =\n\t\t\t\toptions.autoApprove ?? (autoApproveFromEnv(env) || netOpts.autoApproveSigning);\n\t\t\t// Re-export the generated config through the `@devstack-dev`\n\t\t\t// alias (already wired in `config`), parse the token, and\n\t\t\t// register the page wallet on load. Kept as source the dev\n\t\t\t// server transpiles — it imports `@mysten-incubation/dev-wallet`\n\t\t\t// + the generated extras, both resolvable in the app graph.\n\t\t\treturn [\n\t\t\t\t`import { registerDevstackDevWallet } from '@mysten-incubation/dev-wallet/inject';`,\n\t\t\t\t`import { parseDevstackToken } from '@mysten-incubation/dev-wallet/adapters';`,\n\t\t\t\t`import { devWallet } from '${devExtrasAlias}/dev-wallet.js';`,\n\t\t\t\t`import { accounts } from '${devExtrasAlias}/accounts.js';`,\n\t\t\t\t// The wallet EXECUTES (and simulates) against the same routed\n\t\t\t\t// RPC the app's dApp Kit client uses — a raw 127.0.0.1 RPC is\n\t\t\t\t// CORS-blocked from the routed page origin. Sourced from the\n\t\t\t\t// generated runtime config (active network's `rpc`).\n\t\t\t\t`import { config as __devstackConfig } from '${alias}/config.js';`,\n\t\t\t\t`registerDevstackDevWallet({`,\n\t\t\t\t`  serverOrigin: devWallet.walletUrl,`,\n\t\t\t\t`  token: parseDevstackToken(devWallet.pairUrl),`,\n\t\t\t\t`  accounts,`,\n\t\t\t\t`  rpcUrl: __devstackConfig.networks[__devstackConfig.network].rpc,`,\n\t\t\t\t`  network: devWallet.network,`,\n\t\t\t\t`  autoApprove: ${autoApprove ? 'true' : 'false'},`,\n\t\t\t\t`  mountUI: true,`,\n\t\t\t\t`}).catch((err) => console.error('[devstack] dev-wallet injection failed:', err));`,\n\t\t\t].join('\\n');\n\t\t},\n\n\t\tconfigureServer: (server: ViteDevServerLike) => {\n\t\t\tif (!isServe) return;\n\t\t\tconst env = process.env as Readonly<Record<string, string | undefined>>;\n\t\t\tconst idsFile = readIdsFileFromManifest(env, resolvedRoot);\n\t\t\tif (idsFile === null) return;\n\t\t\t// Watch the live id-config and full-reload on change. The supervisor's\n\t\t\t// post-acquire hook rewrites this file whenever a package (re)publishes\n\t\t\t// (e.g. after a Move-source edit fires the file watcher → selective\n\t\t\t// restart); a reload re-runs `transformIndexHtml`, which re-reads the\n\t\t\t// file into `__DEVSTACK_IDS_LIVE__`, so the app picks up the new id.\n\t\t\tserver.watcher.add(idsFile);\n\t\t\tconst reloadOnIdsChange = (changed: string): void => {\n\t\t\t\t// Chokidar fires absolute paths for an absolute `watcher.add`, so\n\t\t\t\t// `resolve(changed)` is normally a no-op; resolve against the Vite\n\t\t\t\t// root anyway so a relative event path can't silently miss.\n\t\t\t\tif (resolve(resolvedRoot, changed) !== resolve(idsFile)) return;\n\t\t\t\tconst channel = server.hot ?? server.ws;\n\t\t\t\tchannel?.send({ type: 'full-reload' });\n\t\t\t};\n\t\t\tserver.watcher.on('change', reloadOnIdsChange);\n\t\t\tserver.watcher.on('add', reloadOnIdsChange);\n\t\t},\n\n\t\ttransformIndexHtml: (html: string) => {\n\t\t\tif (!isServe) return undefined;\n\t\t\tconst env = process.env as Readonly<Record<string, string | undefined>>;\n\t\t\t// Read the live ids FRESH per request so a full-reload after a\n\t\t\t// republish injects the new id. Set on a distinct global\n\t\t\t// (`__DEVSTACK_IDS_LIVE__`) the `config` hook's `define` points\n\t\t\t// `__DEVSTACK_IDS__` at; `head-prepend` runs it before any app module.\n\t\t\tconst liveIds = resolveInjectedIds(env, resolvedRoot, 'serve', options.ids);\n\t\t\tconst tags: Array<{\n\t\t\t\ttag: string;\n\t\t\t\tattrs?: Record<string, string | boolean>;\n\t\t\t\tchildren?: string;\n\t\t\t\tinjectTo: 'head' | 'head-prepend';\n\t\t\t}> = [\n\t\t\t\t{\n\t\t\t\t\ttag: 'script',\n\t\t\t\t\tchildren: `globalThis.__DEVSTACK_IDS_LIVE__ = ${JSON.stringify(liveIds ?? null)};`,\n\t\t\t\t\tinjectTo: 'head-prepend',\n\t\t\t\t},\n\t\t\t];\n\t\t\t// Gate the script tag on the app actually carrying the wallet (same\n\t\t\t// condition as the `config` hook's `optimizeDeps` include), so a\n\t\t\t// headless app emits zero dev-wallet plumbing rather than a tag that\n\t\t\t// resolves to the no-op virtual module.\n\t\t\tif (injectDevWallet && devWalletInstalled(resolvedRoot)) {\n\t\t\t\ttags.push({\n\t\t\t\t\ttag: 'script',\n\t\t\t\t\tattrs: { type: 'module', src: VIRTUAL_DEV_WALLET_SCRIPT_SRC },\n\t\t\t\t\tinjectTo: 'head',\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn { html, tags };\n\t\t},\n\t};\n};\n"],"mappings":"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"}

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

@@ -11,6 +11,21 @@ interface DevstackVitestTestConfigOptions {
    *  uses defaults; an options object configures the captured
    *  fixture (e.g. `{ requireDevstack: true }`). Default: not wired. */
   readonly testSetup?: boolean | TestSetupOptions;
+  /** Marks this as the E2E (full-stack) config: boots a dedicated `test`
+   *  stack for the run via vitest `globalSetup` (tearing it down on
+   *  completion), AND scopes the run to `*.e2e.{test,spec}` files only. A
+   *  plain `devstackVitestTestConfig()` is the UNIT config — it runs the
+   *  other suites and excludes the `*.e2e` ones. So `pnpm test` (unit) never
+   *  touches Docker, and `pnpm test:e2e` boots an isolated stack that runs
+   *  in parallel to a developer's `pnpm dev` without contending.
+   *  Default: not wired (unit config).
+   *
+   *  The injected boot module reads its knobs from the environment
+   *  (`DEVSTACK_STACK`, `DEVSTACK_RUNTIME_ROOT`, `DEVSTACK_TEST_REUSE`).
+   *  For programmatic options (custom stack name, reuse, timeout), author a
+   *  one-line `globalSetup` module calling `devstackVitestGlobalSetup(opts)`
+   *  and pass its path via `test.globalSetup` instead. */
+  readonly autoBoot?: boolean;
   /** Enable vitest's typecheck pass. Default `false` — most apps
    *  run `tsc` outside vitest. */
   readonly typecheck?: boolean;
@@ -39,8 +54,11 @@ interface DevstackVitestTestConfigOptions {
  *
  * For chain-mode integration tests against a real devstack, build a
  * devstack handle and pass `handle.layer` to `@effect/vitest`'s
- * `it.layer(...)` directly. This helper does not boot devstack — the
- * test file owns its lifecycle.
+ * `it.layer(...)` directly — here the test file owns its lifecycle.
+ * Alternatively, `autoBoot: true` wires the `global-setup.ts` boot seam
+ * that boots a dedicated stack for the `*.e2e` run and tears it down
+ * after (so `pnpm test:e2e` is self-contained); a plain call boots
+ * nothing and just builds the `test` block below.
  *
  * For suites that need a shared StackContext fixture (manifest read
  * once per file), opt into the setup file:

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

@@ -6,6 +6,11 @@
 *  package's `./vitest/setup` subpath (added to package.json
 *  `exports` alongside the integration). */
 const DEVSTACK_SETUP_MODULE = "@mysten-incubation/devstack/vitest/setup";
+/** Path to the bundled devstack `globalSetup` module. Injected into
+*  `test.globalSetup` when `opts.autoBoot` is set — it boots a `test`
+*  stack before the run and tears it down after. Resolved like any npm
+*  package via the `./vitest/global-setup` subpath in package.json. */
+const DEVSTACK_GLOBAL_SETUP_MODULE = "@mysten-incubation/devstack/vitest/global-setup";
 /** Runtime-root prefix the watcher MUST ignore — per architecture §
 *  Invariants → "No-restart on harmless changes". The 500ms manifest
 *  tick would otherwise re-trigger reloads. */
@@ -29,8 +34,11 @@ const WATCH_IGNORED_PATTERNS = [
 *
 * For chain-mode integration tests against a real devstack, build a
 * devstack handle and pass `handle.layer` to `@effect/vitest`'s
-* `it.layer(...)` directly. This helper does not boot devstack — the
-* test file owns its lifecycle.
+* `it.layer(...)` directly — here the test file owns its lifecycle.
+* Alternatively, `autoBoot: true` wires the `global-setup.ts` boot seam
+* that boots a dedicated stack for the `*.e2e` run and tears it down
+* after (so `pnpm test:e2e` is self-contained); a plain call boots
+* nothing and just builds the `test` block below.
 *
 * For suites that need a shared StackContext fixture (manifest read
 * once per file), opt into the setup file:
@@ -54,10 +62,12 @@ const devstackVitestTestConfig = (options = {}) => {
 		fileParallelism: true
 	} : {};
 	const typecheckOverride = options.typecheck === true ? { typecheck: { enabled: true } } : {};
+	const isE2e = Boolean(options.autoBoot);
+	const autoBootOverride = isE2e ? { globalSetup: [DEVSTACK_GLOBAL_SETUP_MODULE] } : {};
 	return {
-		include: ["src/**/*.{test,spec}.ts?(x)", "test/**/*.{test,spec}.ts?(x)"],
+		include: isE2e ? ["tests/e2e/**/*.{test,spec}.ts?(x)"] : ["tests/unit/**/*.{test,spec}.ts?(x)"],
 		exclude: [
-			"e2e/**",
+			"tests/browser/**",
 			"node_modules",
 			"dist",
 			".turbo",
@@ -67,6 +77,7 @@ const devstackVitestTestConfig = (options = {}) => {
 		...setupFiles.length > 0 ? { setupFiles } : {},
 		...threadOverride,
 		...typecheckOverride,
+		...autoBootOverride,
 		...options.test
 	};
 };

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

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":[],"sources":["../../../src/build-integrations/vitest/config.ts"],"sourcesContent":["// Vitest build-integration config helpers.\n//\n// Architecture (distilled/23-build-integrations.md § Per-integration\n// requirements → Vitest, § Outputs / capabilities, § Invariants):\n//   - Canonical include/exclude: src globs in, e2e/dist/node_modules\n//     out (`e2e/**` runs through the Playwright integration).\n//   - `passWithNoTests: true` so codegen-derived stacks without unit\n//     tests yet don't fail CI.\n//   - `@effect/vitest` is declared as an optional peer — the preset\n//     itself does not import it. Suites using `it.layer(stack.layer)`\n//     bring it in directly.\n//   - No-restart on harmless changes: watch ignores `<runtimeRoot>/**`\n//     so the ~500ms manifest tick doesn't trigger a reload loop.\n//\n// Optional knobs:\n//   - `testSetup: true | TestSetupOptions` wires the devstack\n//     setup file (`./setup.ts`) automatically via `test.setupFiles`.\n//   - `typecheck: true` opts INTO vitest's typecheck pass (off by\n//     default — apps typically run `tsc` separately).\n//   - `threads: 'single' | 'multi'` picks `pool: 'threads'` and toggles\n//     `fileParallelism` (vitest 4: top-level `fileParallelism: false`\n//     replaces the v3 `poolOptions.threads.singleThread`) for\n//     stack-shared-state suites that can't safely parallelize.\n//   - Caller-provided `test` fields win over the preset's defaults.\n//\n// No I/O happens at config-build time (per architecture § Lifecycle\n// states: vitest preset call is synchronous + side-effect free).\n\nimport type { ViteUserConfig } from 'vitest/config';\n\nimport type { TestSetupOptions } from './setup.ts';\n\n// -----------------------------------------------------------------------------\n// Public options\n// -----------------------------------------------------------------------------\n\nexport interface DevstackVitestTestConfigOptions {\n\t/** Extra `test` fields. Caller-provided keys win over the preset's\n\t *  defaults; the preset's include/exclude/passWithNoTests are the\n\t *  start, the caller's fields are merged shallowly. */\n\treadonly test?: NonNullable<ViteUserConfig['test']>;\n\t/** Wire the devstack `beforeAll` / `afterAll` setup file. `true`\n\t *  uses defaults; an options object configures the captured\n\t *  fixture (e.g. `{ requireDevstack: true }`). Default: not wired. */\n\treadonly testSetup?: boolean | TestSetupOptions;\n\t/** Enable vitest's typecheck pass. Default `false` — most apps\n\t *  run `tsc` outside vitest. */\n\treadonly typecheck?: boolean;\n\t/** Threading mode. `'single'` forces a single thread (needed when\n\t *  tests share devstack state); `'multi'` keeps vitest's default\n\t *  worker pool. Default: vitest default (`undefined`). */\n\treadonly threads?: 'single' | 'multi';\n\t/** Absolute path to a user-authored setup file. When set, it is\n\t *  appended to `test.setupFiles` AFTER the devstack setup file (so\n\t *  the user file sees the captured StackContext via\n\t *  `getStackContext()`). */\n\treadonly setupFile?: string;\n}\n\n// -----------------------------------------------------------------------------\n// Internals\n// -----------------------------------------------------------------------------\n\n/** Path to the bundled devstack setup file. The preset injects this\n *  via `test.setupFiles` when `opts.testSetup` is truthy. The literal\n *  string is the module's import specifier so vitest resolves it like\n *  any other npm package; an apps-level resolver finds it via the\n *  package's `./vitest/setup` subpath (added to package.json\n *  `exports` alongside the integration). */\nconst DEVSTACK_SETUP_MODULE = '@mysten-incubation/devstack/vitest/setup';\n\n/** Runtime-root prefix the watcher MUST ignore — per architecture §\n *  Invariants → \"No-restart on harmless changes\". The 500ms manifest\n *  tick would otherwise re-trigger reloads. */\nconst WATCH_IGNORED_PATTERNS = ['**/.devstack/**', '**/node_modules/**', '**/dist/**'];\n\n// -----------------------------------------------------------------------------\n// Public surface\n// -----------------------------------------------------------------------------\n\n/**\n * Build the devstack-owned part of Vitest's `test` block. Apps keep a\n * normal `defineConfig(...)` call and compose this value into it:\n *\n *     import { defineConfig } from 'vitest/config';\n *     import { devstackVitestServerConfig, devstackVitestTestConfig }\n *       from '@mysten-incubation/devstack/vitest';\n *\n *     export default defineConfig({\n *       server: devstackVitestServerConfig(),\n *       test: devstackVitestTestConfig(),\n *     });\n *\n * For chain-mode integration tests against a real devstack, build a\n * devstack handle and pass `handle.layer` to `@effect/vitest`'s\n * `it.layer(...)` directly. This helper does not boot devstack — the\n * test file owns its lifecycle.\n *\n * For suites that need a shared StackContext fixture (manifest read\n * once per file), opt into the setup file:\n *\n *     test: devstackVitestTestConfig({\n *       testSetup: { requireDevstack: true },\n *     })\n *\n * The setup file's `beforeAll` populates a captured fixture readable\n * via `getStackContext()` from inside `it`/`test` bodies.\n */\nexport const devstackVitestTestConfig = (\n\toptions: DevstackVitestTestConfigOptions = {},\n): NonNullable<ViteUserConfig['test']> => {\n\tconst setupFiles: Array<string> = [];\n\tif (options.testSetup) {\n\t\tsetupFiles.push(DEVSTACK_SETUP_MODULE);\n\t}\n\tif (options.setupFile !== undefined) {\n\t\tsetupFiles.push(options.setupFile);\n\t}\n\n\t// Vitest 4 removed `poolOptions.threads.singleThread`. Top-level\n\t// `fileParallelism: false` is the replacement for single-threaded\n\t// runs (also pins `maxWorkers` to 1 per vitest's docs). Both\n\t// branches set `pool: 'threads'` explicitly so we don't depend on\n\t// vitest's default pool (which is `forks` in v4).\n\tconst threadOverride =\n\t\toptions.threads === 'single'\n\t\t\t? { pool: 'threads' as const, fileParallelism: false }\n\t\t\t: options.threads === 'multi'\n\t\t\t\t? { pool: 'threads' as const, fileParallelism: true }\n\t\t\t\t: {};\n\n\tconst typecheckOverride = options.typecheck === true ? { typecheck: { enabled: true } } : {};\n\n\treturn {\n\t\tinclude: ['src/**/*.{test,spec}.ts?(x)', 'test/**/*.{test,spec}.ts?(x)'],\n\t\texclude: ['e2e/**', 'node_modules', 'dist', '.turbo', '**/.devstack/**'],\n\t\tpassWithNoTests: true,\n\t\t...(setupFiles.length > 0 ? { setupFiles } : {}),\n\t\t...threadOverride,\n\t\t...typecheckOverride,\n\t\t// Caller overrides last. Shallow merge.\n\t\t...options.test,\n\t};\n};\n\n/** Build the devstack-owned part of Vitest's Vite server config.\n *  Callers that need additional server options should merge them in\n *  their own `defineConfig(...)` file. */\nexport const devstackVitestServerConfig = (): NonNullable<ViteUserConfig['server']> => ({\n\twatch: {\n\t\t// vite's chokidar watcher honors `ignored` even in test mode.\n\t\tignored: WATCH_IGNORED_PATTERNS,\n\t},\n});\n\n// -----------------------------------------------------------------------------\n// Test-visible internals (do not re-export from the integration barrel)\n// -----------------------------------------------------------------------------\n\n/** @internal — used by `test/build-integrations/vitest/config.test.ts`\n *  to assert the watcher ignored set without depending on a built\n *  config snapshot. */\nexport const _internal = {\n\tDEVSTACK_SETUP_MODULE,\n\tWATCH_IGNORED_PATTERNS,\n} as const;\n"],"mappings":";;;;;;;AAqEA,MAAM,wBAAwB;;;;AAK9B,MAAM,yBAAyB;CAAC;CAAmB;CAAsB;CAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCtF,MAAa,4BACZ,UAA2C,EAAE,KACJ;CACzC,MAAM,aAA4B,EAAE;AACpC,KAAI,QAAQ,UACX,YAAW,KAAK,sBAAsB;AAEvC,KAAI,QAAQ,cAAc,KAAA,EACzB,YAAW,KAAK,QAAQ,UAAU;CAQnC,MAAM,iBACL,QAAQ,YAAY,WACjB;EAAE,MAAM;EAAoB,iBAAiB;EAAO,GACpD,QAAQ,YAAY,UACnB;EAAE,MAAM;EAAoB,iBAAiB;EAAM,GACnD,EAAE;CAEP,MAAM,oBAAoB,QAAQ,cAAc,OAAO,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,EAAE;AAE5F,QAAO;EACN,SAAS,CAAC,+BAA+B,+BAA+B;EACxE,SAAS;GAAC;GAAU;GAAgB;GAAQ;GAAU;GAAkB;EACxE,iBAAiB;EACjB,GAAI,WAAW,SAAS,IAAI,EAAE,YAAY,GAAG,EAAE;EAC/C,GAAG;EACH,GAAG;EAEH,GAAG,QAAQ;EACX;;;;;AAMF,MAAa,oCAA2E,EACvF,OAAO,EAEN,SAAS,wBACT,EACD"}
+{"version":3,"file":"config.mjs","names":[],"sources":["../../../src/build-integrations/vitest/config.ts"],"sourcesContent":["// Vitest build-integration config helpers.\n//\n// Architecture (distilled/23-build-integrations.md § Per-integration\n// requirements → Vitest, § Outputs / capabilities, § Invariants):\n//   - Canonical include/exclude by DIRECTORY: `tests/unit/**` for the\n//     unit config, `tests/e2e/**` for the autoBoot (full-stack) config;\n//     `tests/browser/**` (Playwright specs) and dist/node_modules out.\n//   - `passWithNoTests: true` so codegen-derived stacks without unit\n//     tests yet don't fail CI.\n//   - `@effect/vitest` is declared as an optional peer — the preset\n//     itself does not import it. Suites using `it.layer(stack.layer)`\n//     bring it in directly.\n//   - No-restart on harmless changes: watch ignores `<runtimeRoot>/**`\n//     so the ~500ms manifest tick doesn't trigger a reload loop.\n//\n// Optional knobs:\n//   - `testSetup: true | TestSetupOptions` wires the devstack\n//     setup file (`./setup.ts`) automatically via `test.setupFiles`.\n//   - `typecheck: true` opts INTO vitest's typecheck pass (off by\n//     default — apps typically run `tsc` separately).\n//   - `threads: 'single' | 'multi'` picks `pool: 'threads'` and toggles\n//     `fileParallelism` (vitest 4 uses a top-level\n//     `fileParallelism: false`) for stack-shared-state suites that\n//     can't safely parallelize.\n//   - Caller-provided `test` fields win over the preset's defaults.\n//\n// No I/O happens at config-build time (per architecture § Lifecycle\n// states: vitest preset call is synchronous + side-effect free).\n\nimport type { ViteUserConfig } from 'vitest/config';\n\nimport type { TestSetupOptions } from './setup.ts';\n\n// -----------------------------------------------------------------------------\n// Public options\n// -----------------------------------------------------------------------------\n\nexport interface DevstackVitestTestConfigOptions {\n\t/** Extra `test` fields. Caller-provided keys win over the preset's\n\t *  defaults; the preset's include/exclude/passWithNoTests are the\n\t *  start, the caller's fields are merged shallowly. */\n\treadonly test?: NonNullable<ViteUserConfig['test']>;\n\t/** Wire the devstack `beforeAll` / `afterAll` setup file. `true`\n\t *  uses defaults; an options object configures the captured\n\t *  fixture (e.g. `{ requireDevstack: true }`). Default: not wired. */\n\treadonly testSetup?: boolean | TestSetupOptions;\n\t/** Marks this as the E2E (full-stack) config: boots a dedicated `test`\n\t *  stack for the run via vitest `globalSetup` (tearing it down on\n\t *  completion), AND scopes the run to `*.e2e.{test,spec}` files only. A\n\t *  plain `devstackVitestTestConfig()` is the UNIT config — it runs the\n\t *  other suites and excludes the `*.e2e` ones. So `pnpm test` (unit) never\n\t *  touches Docker, and `pnpm test:e2e` boots an isolated stack that runs\n\t *  in parallel to a developer's `pnpm dev` without contending.\n\t *  Default: not wired (unit config).\n\t *\n\t *  The injected boot module reads its knobs from the environment\n\t *  (`DEVSTACK_STACK`, `DEVSTACK_RUNTIME_ROOT`, `DEVSTACK_TEST_REUSE`).\n\t *  For programmatic options (custom stack name, reuse, timeout), author a\n\t *  one-line `globalSetup` module calling `devstackVitestGlobalSetup(opts)`\n\t *  and pass its path via `test.globalSetup` instead. */\n\treadonly autoBoot?: boolean;\n\t/** Enable vitest's typecheck pass. Default `false` — most apps\n\t *  run `tsc` outside vitest. */\n\treadonly typecheck?: boolean;\n\t/** Threading mode. `'single'` forces a single thread (needed when\n\t *  tests share devstack state); `'multi'` keeps vitest's default\n\t *  worker pool. Default: vitest default (`undefined`). */\n\treadonly threads?: 'single' | 'multi';\n\t/** Absolute path to a user-authored setup file. When set, it is\n\t *  appended to `test.setupFiles` AFTER the devstack setup file (so\n\t *  the user file sees the captured StackContext via\n\t *  `getStackContext()`). */\n\treadonly setupFile?: string;\n}\n\n// -----------------------------------------------------------------------------\n// Internals\n// -----------------------------------------------------------------------------\n\n/** Path to the bundled devstack setup file. The preset injects this\n *  via `test.setupFiles` when `opts.testSetup` is truthy. The literal\n *  string is the module's import specifier so vitest resolves it like\n *  any other npm package; an apps-level resolver finds it via the\n *  package's `./vitest/setup` subpath (added to package.json\n *  `exports` alongside the integration). */\nconst DEVSTACK_SETUP_MODULE = '@mysten-incubation/devstack/vitest/setup';\n\n/** Path to the bundled devstack `globalSetup` module. Injected into\n *  `test.globalSetup` when `opts.autoBoot` is set — it boots a `test`\n *  stack before the run and tears it down after. Resolved like any npm\n *  package via the `./vitest/global-setup` subpath in package.json. */\nconst DEVSTACK_GLOBAL_SETUP_MODULE = '@mysten-incubation/devstack/vitest/global-setup';\n\n/** Runtime-root prefix the watcher MUST ignore — per architecture §\n *  Invariants → \"No-restart on harmless changes\". The 500ms manifest\n *  tick would otherwise re-trigger reloads. */\nconst WATCH_IGNORED_PATTERNS = ['**/.devstack/**', '**/node_modules/**', '**/dist/**'];\n\n// -----------------------------------------------------------------------------\n// Public surface\n// -----------------------------------------------------------------------------\n\n/**\n * Build the devstack-owned part of Vitest's `test` block. Apps keep a\n * normal `defineConfig(...)` call and compose this value into it:\n *\n *     import { defineConfig } from 'vitest/config';\n *     import { devstackVitestServerConfig, devstackVitestTestConfig }\n *       from '@mysten-incubation/devstack/vitest';\n *\n *     export default defineConfig({\n *       server: devstackVitestServerConfig(),\n *       test: devstackVitestTestConfig(),\n *     });\n *\n * For chain-mode integration tests against a real devstack, build a\n * devstack handle and pass `handle.layer` to `@effect/vitest`'s\n * `it.layer(...)` directly — here the test file owns its lifecycle.\n * Alternatively, `autoBoot: true` wires the `global-setup.ts` boot seam\n * that boots a dedicated stack for the `*.e2e` run and tears it down\n * after (so `pnpm test:e2e` is self-contained); a plain call boots\n * nothing and just builds the `test` block below.\n *\n * For suites that need a shared StackContext fixture (manifest read\n * once per file), opt into the setup file:\n *\n *     test: devstackVitestTestConfig({\n *       testSetup: { requireDevstack: true },\n *     })\n *\n * The setup file's `beforeAll` populates a captured fixture readable\n * via `getStackContext()` from inside `it`/`test` bodies.\n */\nexport const devstackVitestTestConfig = (\n\toptions: DevstackVitestTestConfigOptions = {},\n): NonNullable<ViteUserConfig['test']> => {\n\tconst setupFiles: Array<string> = [];\n\tif (options.testSetup) {\n\t\tsetupFiles.push(DEVSTACK_SETUP_MODULE);\n\t}\n\tif (options.setupFile !== undefined) {\n\t\tsetupFiles.push(options.setupFile);\n\t}\n\n\t// Vitest 4 removed `poolOptions.threads.singleThread`. Top-level\n\t// `fileParallelism: false` is the replacement for single-threaded\n\t// runs (also pins `maxWorkers` to 1 per vitest's docs). Both\n\t// branches set `pool: 'threads'` explicitly so we don't depend on\n\t// vitest's default pool (which is `forks` in v4).\n\tconst threadOverride =\n\t\toptions.threads === 'single'\n\t\t\t? { pool: 'threads' as const, fileParallelism: false }\n\t\t\t: options.threads === 'multi'\n\t\t\t\t? { pool: 'threads' as const, fileParallelism: true }\n\t\t\t\t: {};\n\n\tconst typecheckOverride = options.typecheck === true ? { typecheck: { enabled: true } } : {};\n\n\t// `autoBoot` marks the E2E (full-stack) config: it both wires the boot\n\t// `globalSetup` AND scopes the run to the `tests/e2e/` directory. A plain\n\t// `devstackVitestTestConfig()` is the UNIT config — it scopes the run to\n\t// `tests/unit/`. Directory layout (not a filename infix) separates the two\n\t// suites: `tests/unit/` (fast, no Docker), `tests/e2e/` (boots a stack),\n\t// and `tests/browser/` (Playwright browser specs, run by the Playwright\n\t// integration — never by vitest). So `pnpm test` never touches Docker, and\n\t// `pnpm test:e2e` boots an isolated stack for the `tests/e2e/` suites only.\n\tconst isE2e = Boolean(options.autoBoot);\n\tconst autoBootOverride = isE2e ? { globalSetup: [DEVSTACK_GLOBAL_SETUP_MODULE] } : {};\n\n\tconst include = isE2e\n\t\t? ['tests/e2e/**/*.{test,spec}.ts?(x)']\n\t\t: ['tests/unit/**/*.{test,spec}.ts?(x)'];\n\tconst exclude = [\n\t\t// `tests/browser/**` are Playwright browser specs — run by the\n\t\t// Playwright integration, never the vitest run.\n\t\t'tests/browser/**',\n\t\t'node_modules',\n\t\t'dist',\n\t\t'.turbo',\n\t\t'**/.devstack/**',\n\t];\n\n\treturn {\n\t\tinclude,\n\t\texclude,\n\t\tpassWithNoTests: true,\n\t\t...(setupFiles.length > 0 ? { setupFiles } : {}),\n\t\t...threadOverride,\n\t\t...typecheckOverride,\n\t\t...autoBootOverride,\n\t\t// Caller overrides last. Shallow merge.\n\t\t...options.test,\n\t};\n};\n\n/** Build the devstack-owned part of Vitest's Vite server config.\n *  Callers that need additional server options should merge them in\n *  their own `defineConfig(...)` file. */\nexport const devstackVitestServerConfig = (): NonNullable<ViteUserConfig['server']> => ({\n\twatch: {\n\t\t// vite's chokidar watcher honors `ignored` even in test mode.\n\t\tignored: WATCH_IGNORED_PATTERNS,\n\t},\n});\n\n// -----------------------------------------------------------------------------\n// Test-visible internals (do not re-export from the integration barrel)\n// -----------------------------------------------------------------------------\n\n/** @internal — used by `test/build-integrations/vitest/config.test.ts`\n *  to assert the watcher ignored set without depending on a built\n *  config snapshot. */\nexport const _internal = {\n\tDEVSTACK_SETUP_MODULE,\n\tDEVSTACK_GLOBAL_SETUP_MODULE,\n\tWATCH_IGNORED_PATTERNS,\n} as const;\n"],"mappings":";;;;;;;AAqFA,MAAM,wBAAwB;;;;;AAM9B,MAAM,+BAA+B;;;;AAKrC,MAAM,yBAAyB;CAAC;CAAmB;CAAsB;AAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCrF,MAAa,4BACZ,UAA2C,CAAC,MACH;CACzC,MAAM,aAA4B,CAAC;CACnC,IAAI,QAAQ,WACX,WAAW,KAAK,qBAAqB;CAEtC,IAAI,QAAQ,cAAc,KAAA,GACzB,WAAW,KAAK,QAAQ,SAAS;CAQlC,MAAM,iBACL,QAAQ,YAAY,WACjB;EAAE,MAAM;EAAoB,iBAAiB;CAAM,IACnD,QAAQ,YAAY,UACnB;EAAE,MAAM;EAAoB,iBAAiB;CAAK,IAClD,CAAC;CAEN,MAAM,oBAAoB,QAAQ,cAAc,OAAO,EAAE,WAAW,EAAE,SAAS,KAAK,EAAE,IAAI,CAAC;CAU3F,MAAM,QAAQ,QAAQ,QAAQ,QAAQ;CACtC,MAAM,mBAAmB,QAAQ,EAAE,aAAa,CAAC,4BAA4B,EAAE,IAAI,CAAC;CAepF,OAAO;EACN,SAde,QACb,CAAC,mCAAmC,IACpC,CAAC,oCAAoC;EAavC,SAAA;GATA;GACA;GACA;GACA;GACA;EAKM;EACN,iBAAiB;EACjB,GAAI,WAAW,SAAS,IAAI,EAAE,WAAW,IAAI,CAAC;EAC9C,GAAG;EACH,GAAG;EACH,GAAG;EAEH,GAAG,QAAQ;CACZ;AACD;;;;AAKA,MAAa,oCAA2E,EACvF,OAAO,EAEN,SAAS,uBACV,EACD"}

package/dist/build-integrations/vitest/env.d.mts

@@ -7,10 +7,7 @@ declare const VITEST_ENV_VARS: {
   readonly STACK: "DEVSTACK_STACK";
   /** Override for the runtime root that holds
    *  `stacks/<stack>/manifest.json`. Defaults to `.devstack`. */
-  readonly RUNTIME_ROOT: "DEVSTACK_RUNTIME_ROOT";
-  /** Legacy alias for `RUNTIME_ROOT`. Accepted on read so the
-   *  rewrite can coexist with example apps that still set the
-   *  pre-rewrite name. New callers should use `RUNTIME_ROOT`. */
+  readonly RUNTIME_ROOT: "DEVSTACK_RUNTIME_ROOT"; /** Alias for `RUNTIME_ROOT`. New callers should use `RUNTIME_ROOT`. */
   readonly RUNTIME_ROOT_LEGACY: "DEVSTACK_STATE_DIR";
   /** Top-precedence absolute path to a specific manifest file. The
    *  engine sets this when it spawns child processes; rarely set
@@ -23,8 +20,7 @@ type VitestEnvVarName = (typeof VITEST_ENV_VARS)[keyof typeof VITEST_ENV_VARS];
  *  truth) — but tests should explicitly set `DEVSTACK_STACK=test`
  *  rather than rely on this. */
 declare const DEFAULT_STACK_NAME = "main";
-/** Default runtime root when neither `DEVSTACK_RUNTIME_ROOT` nor the
- *  legacy `DEVSTACK_STATE_DIR` is set. */
+/** Default runtime root when no runtime-root override is set. */
 declare const DEFAULT_RUNTIME_ROOT = ".devstack";
 /** The recommended stack name for test runs — the value the
  *  `test`-script env should set. Exported as a constant so example
@@ -40,10 +36,22 @@ interface ResolvedVitestEnv {
    *  user runs `pnpm test` without the recommended wiring. */
   readonly stackWasExplicit: boolean;
 }
+interface ResolveVitestEnvOptions {
+  /** Walk-up start for the package-name rung of the stack ladder,
+   *  mirroring `resolveDiscoveryEnv` / the CLI's `resolveStackName`:
+   *  when `DEVSTACK_STACK` is unset, the stack falls back to the
+   *  nearest package.json `name` above `cwd` before `'main'`. Opt-in —
+   *  omit it and the resolver stays fs-free with the bare
+   *  env > `'main'` ladder. The setup hook threads it so the advisory
+   *  names the stack `loadStackContext` will actually read. */
+  readonly cwd?: string;
+}
 /** Resolve the vitest env contract from an arbitrary env bag.
- *  Side-effect free — tests pass a fixture; production code passes
- *  `process.env`. */
-declare const resolveVitestEnv: (env: Readonly<Record<string, string | undefined>>) => ResolvedVitestEnv;
+ *  Side-effect free when `options.cwd` is omitted — tests pass a
+ *  fixture; production code passes `process.env`. With `cwd`, the only
+ *  fs access is the lazy package.json walk-up on the stack rung, and
+ *  only when `DEVSTACK_STACK` is unset. */
+declare const resolveVitestEnv: (env: Readonly<Record<string, string | undefined>>, options?: ResolveVitestEnvOptions) => ResolvedVitestEnv;
 //#endregion
-export { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, ResolvedVitestEnv, VITEST_ENV_VARS, VitestEnvVarName, resolveVitestEnv };
+export { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, ResolveVitestEnvOptions, ResolvedVitestEnv, VITEST_ENV_VARS, VitestEnvVarName, resolveVitestEnv };
 //# sourceMappingURL=env.d.mts.map