@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +1,62 @@
+import { TestSetupOptions } from "./setup.mjs";
+import { ViteUserConfig } from "vitest/config";
+
+//#region src/build-integrations/vitest/config.d.ts
+interface DevstackVitestTestConfigOptions {
+  /** Extra `test` fields. Caller-provided keys win over the preset's
+   *  defaults; the preset's include/exclude/passWithNoTests are the
+   *  start, the caller's fields are merged shallowly. */
+  readonly test?: NonNullable<ViteUserConfig['test']>;
+  /** Wire the devstack `beforeAll` / `afterAll` setup file. `true`
+   *  uses defaults; an options object configures the captured
+   *  fixture (e.g. `{ requireDevstack: true }`). Default: not wired. */
+  readonly testSetup?: boolean | TestSetupOptions;
+  /** Enable vitest's typecheck pass. Default `false` — most apps
+   *  run `tsc` outside vitest. */
+  readonly typecheck?: boolean;
+  /** Threading mode. `'single'` forces a single thread (needed when
+   *  tests share devstack state); `'multi'` keeps vitest's default
+   *  worker pool. Default: vitest default (`undefined`). */
+  readonly threads?: 'single' | 'multi';
+  /** Absolute path to a user-authored setup file. When set, it is
+   *  appended to `test.setupFiles` AFTER the devstack setup file (so
+   *  the user file sees the captured StackContext via
+   *  `getStackContext()`). */
+  readonly setupFile?: string;
+}
+/**
+ * Build the devstack-owned part of Vitest's `test` block. Apps keep a
+ * normal `defineConfig(...)` call and compose this value into it:
+ *
+ *     import { defineConfig } from 'vitest/config';
+ *     import { devstackVitestServerConfig, devstackVitestTestConfig }
+ *       from '@mysten-incubation/devstack/vitest';
+ *
+ *     export default defineConfig({
+ *       server: devstackVitestServerConfig(),
+ *       test: devstackVitestTestConfig(),
+ *     });
+ *
+ * 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.
+ *
+ * For suites that need a shared StackContext fixture (manifest read
+ * once per file), opt into the setup file:
+ *
+ *     test: devstackVitestTestConfig({
+ *       testSetup: { requireDevstack: true },
+ *     })
+ *
+ * The setup file's `beforeAll` populates a captured fixture readable
+ * via `getStackContext()` from inside `it`/`test` bodies.
+ */
+declare const devstackVitestTestConfig: (options?: DevstackVitestTestConfigOptions) => NonNullable<ViteUserConfig["test"]>;
+/** Build the devstack-owned part of Vitest's Vite server config.
+ *  Callers that need additional server options should merge them in
+ *  their own `defineConfig(...)` file. */
+declare const devstackVitestServerConfig: () => NonNullable<ViteUserConfig["server"]>;
+//#endregion
+export { DevstackVitestTestConfigOptions, devstackVitestServerConfig, devstackVitestTestConfig };
+//# sourceMappingURL=config.d.mts.map

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

@@ -0,0 +1,80 @@
+//#region src/build-integrations/vitest/config.ts
+/** Path to the bundled devstack setup file. The preset injects this
+*  via `test.setupFiles` when `opts.testSetup` is truthy. The literal
+*  string is the module's import specifier so vitest resolves it like
+*  any other npm package; an apps-level resolver finds it via the
+*  package's `./vitest/setup` subpath (added to package.json
+*  `exports` alongside the integration). */
+const DEVSTACK_SETUP_MODULE = "@mysten-incubation/devstack/vitest/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. */
+const WATCH_IGNORED_PATTERNS = [
+	"**/.devstack/**",
+	"**/node_modules/**",
+	"**/dist/**"
+];
+/**
+* Build the devstack-owned part of Vitest's `test` block. Apps keep a
+* normal `defineConfig(...)` call and compose this value into it:
+*
+*     import { defineConfig } from 'vitest/config';
+*     import { devstackVitestServerConfig, devstackVitestTestConfig }
+*       from '@mysten-incubation/devstack/vitest';
+*
+*     export default defineConfig({
+*       server: devstackVitestServerConfig(),
+*       test: devstackVitestTestConfig(),
+*     });
+*
+* 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.
+*
+* For suites that need a shared StackContext fixture (manifest read
+* once per file), opt into the setup file:
+*
+*     test: devstackVitestTestConfig({
+*       testSetup: { requireDevstack: true },
+*     })
+*
+* The setup file's `beforeAll` populates a captured fixture readable
+* via `getStackContext()` from inside `it`/`test` bodies.
+*/
+const devstackVitestTestConfig = (options = {}) => {
+	const setupFiles = [];
+	if (options.testSetup) setupFiles.push(DEVSTACK_SETUP_MODULE);
+	if (options.setupFile !== void 0) setupFiles.push(options.setupFile);
+	const threadOverride = options.threads === "single" ? {
+		pool: "threads",
+		fileParallelism: false
+	} : options.threads === "multi" ? {
+		pool: "threads",
+		fileParallelism: true
+	} : {};
+	const typecheckOverride = options.typecheck === true ? { typecheck: { enabled: true } } : {};
+	return {
+		include: ["src/**/*.{test,spec}.ts?(x)", "test/**/*.{test,spec}.ts?(x)"],
+		exclude: [
+			"e2e/**",
+			"node_modules",
+			"dist",
+			".turbo",
+			"**/.devstack/**"
+		],
+		passWithNoTests: true,
+		...setupFiles.length > 0 ? { setupFiles } : {},
+		...threadOverride,
+		...typecheckOverride,
+		...options.test
+	};
+};
+/** Build the devstack-owned part of Vitest's Vite server config.
+*  Callers that need additional server options should merge them in
+*  their own `defineConfig(...)` file. */
+const devstackVitestServerConfig = () => ({ watch: { ignored: WATCH_IGNORED_PATTERNS } });
+//#endregion
+export { devstackVitestServerConfig, devstackVitestTestConfig };
+
+//# sourceMappingURL=config.mjs.map

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

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

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

@@ -0,0 +1,48 @@
+//#region src/build-integrations/vitest/env.d.ts
+/** Env-var names the vitest integration consults. Centralized so
+ *  test-setup printouts can name the var the caller forgot to set. */
+declare const VITEST_ENV_VARS: {
+  /** Stack name; the canonical signal for "isolate this test run
+   *  from other stacks". Tests SHOULD set this to `'test'`. */
+  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_LEGACY: "DEVSTACK_STATE_DIR";
+  /** Top-precedence absolute path to a specific manifest file. The
+   *  engine sets this when it spawns child processes; rarely set
+   *  by hand. */
+  readonly MANIFEST_PATH: "DEVSTACK_MANIFEST_PATH";
+};
+type VitestEnvVarName = (typeof VITEST_ENV_VARS)[keyof typeof VITEST_ENV_VARS];
+/** Default stack name when `DEVSTACK_STACK` is unset. Mirrors the
+ *  engine's "main" default — 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. */
+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
+ *  apps' `package.json` can wire it from one symbol if a future
+ *  scaffolder lands. */
+declare const RECOMMENDED_TEST_STACK = "test";
+interface ResolvedVitestEnv {
+  readonly stack: string;
+  readonly runtimeRoot: string;
+  readonly manifestPathOverride: string | undefined;
+  /** True when the caller's env explicitly set `DEVSTACK_STACK`. The
+   *  test-setup hook uses this to print a louder advisory when a
+   *  user runs `pnpm test` without the recommended wiring. */
+  readonly stackWasExplicit: boolean;
+}
+/** 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;
+//#endregion
+export { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, ResolvedVitestEnv, VITEST_ENV_VARS, VitestEnvVarName, resolveVitestEnv };
+//# sourceMappingURL=env.d.mts.map

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

@@ -0,0 +1,50 @@
+//#region src/build-integrations/vitest/env.ts
+/** Env-var names the vitest integration consults. Centralized so
+*  test-setup printouts can name the var the caller forgot to set. */
+const VITEST_ENV_VARS = {
+	/** Stack name; the canonical signal for "isolate this test run
+	*  from other stacks". Tests SHOULD set this to `'test'`. */
+	STACK: "DEVSTACK_STACK",
+	/** Override for the runtime root that holds
+	*  `stacks/<stack>/manifest.json`. Defaults to `.devstack`. */
+	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`. */
+	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
+	*  by hand. */
+	MANIFEST_PATH: "DEVSTACK_MANIFEST_PATH"
+};
+/** Default stack name when `DEVSTACK_STACK` is unset. Mirrors the
+*  engine's "main" default — but tests should explicitly set
+*  `DEVSTACK_STACK=test` rather than rely on this. */
+const DEFAULT_STACK_NAME = "main";
+/** Default runtime root when neither `DEVSTACK_RUNTIME_ROOT` nor the
+*  legacy `DEVSTACK_STATE_DIR` is set. */
+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
+*  apps' `package.json` can wire it from one symbol if a future
+*  scaffolder lands. */
+const RECOMMENDED_TEST_STACK = "test";
+/** Resolve the vitest env contract from an arbitrary env bag.
+*  Side-effect free — tests pass a fixture; production code passes
+*  `process.env`. */
+const resolveVitestEnv = (env) => {
+	const stackRaw = env[VITEST_ENV_VARS.STACK];
+	const stack = stackRaw !== void 0 && stackRaw !== "" ? stackRaw : DEFAULT_STACK_NAME;
+	const runtimeRoot = env[VITEST_ENV_VARS.RUNTIME_ROOT] ?? env[VITEST_ENV_VARS.RUNTIME_ROOT_LEGACY] ?? ".devstack";
+	const manifestPathOverride = env[VITEST_ENV_VARS.MANIFEST_PATH];
+	return {
+		stack,
+		runtimeRoot: runtimeRoot === "" ? DEFAULT_RUNTIME_ROOT : runtimeRoot,
+		manifestPathOverride: manifestPathOverride !== void 0 && manifestPathOverride !== "" ? manifestPathOverride : void 0,
+		stackWasExplicit: stackRaw !== void 0 && stackRaw !== ""
+	};
+};
+//#endregion
+export { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, VITEST_ENV_VARS, resolveVitestEnv };
+
+//# sourceMappingURL=env.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env.mjs","names":[],"sources":["../../../src/build-integrations/vitest/env.ts"],"sourcesContent":["// Vitest build-integration — env-var contract.\n//\n// Architecture (distilled/23-build-integrations.md § Inputs /\n// dependencies, distilled/24-examples.md § Lifecycle / invocation\n// patterns): test runs MUST set `DEVSTACK_STACK=test` so they don't\n// contend with a parallel `pnpm dev` on the `main` stack. The\n// supervisor's port allocator + manifest discovery key off this var\n// to keep two stacks coexisting.\n//\n// `DEVSTACK_RUNTIME_ROOT` is the optional override for the on-disk\n// state root that contains `stacks/<stack>/manifest.json`. It maps to\n// the legacy `DEVSTACK_STATE_DIR` env var; both names are accepted on\n// read so the rewrite can roll out without coordinated env-var\n// renames across every example app.\n//\n// `DEVSTACK_MANIFEST_PATH` is the top-of-the-precedence-ladder escape\n// hatch the engine writes; build integrations also honor it. Listed\n// here for completeness — the typical vitest run does not set it.\n//\n// NOTE: this module is a pure declaration of names + defaults. No env\n// reads happen at module import time; readers fetch on demand so\n// tests can stub `process.env` per-case.\n\n// -----------------------------------------------------------------------------\n// Canonical env-var names\n// -----------------------------------------------------------------------------\n\n/** Env-var names the vitest integration consults. Centralized so\n *  test-setup printouts can name the var the caller forgot to set. */\nexport const VITEST_ENV_VARS = {\n\t/** Stack name; the canonical signal for \"isolate this test run\n\t *  from other stacks\". Tests SHOULD set this to `'test'`. */\n\tSTACK: 'DEVSTACK_STACK',\n\t/** Override for the runtime root that holds\n\t *  `stacks/<stack>/manifest.json`. Defaults to `.devstack`. */\n\tRUNTIME_ROOT: 'DEVSTACK_RUNTIME_ROOT',\n\t/** Legacy alias for `RUNTIME_ROOT`. Accepted on read so the\n\t *  rewrite can coexist with example apps that still set the\n\t *  pre-rewrite name. New callers should use `RUNTIME_ROOT`. */\n\tRUNTIME_ROOT_LEGACY: 'DEVSTACK_STATE_DIR',\n\t/** Top-precedence absolute path to a specific manifest file. The\n\t *  engine sets this when it spawns child processes; rarely set\n\t *  by hand. */\n\tMANIFEST_PATH: 'DEVSTACK_MANIFEST_PATH',\n} as const;\n\nexport type VitestEnvVarName = (typeof VITEST_ENV_VARS)[keyof typeof VITEST_ENV_VARS];\n\n// -----------------------------------------------------------------------------\n// Defaults\n// -----------------------------------------------------------------------------\n\n/** Default stack name when `DEVSTACK_STACK` is unset. Mirrors the\n *  engine's \"main\" default — but tests should explicitly set\n *  `DEVSTACK_STACK=test` rather than rely on this. */\nexport const DEFAULT_STACK_NAME = 'main';\n\n/** Default runtime root when neither `DEVSTACK_RUNTIME_ROOT` nor the\n *  legacy `DEVSTACK_STATE_DIR` is set. */\nexport const DEFAULT_RUNTIME_ROOT = '.devstack';\n\n/** The recommended stack name for test runs — the value the\n *  `test`-script env should set. Exported as a constant so example\n *  apps' `package.json` can wire it from one symbol if a future\n *  scaffolder lands. */\nexport const RECOMMENDED_TEST_STACK = 'test';\n\n// -----------------------------------------------------------------------------\n// Pure resolvers — no module-init side effects\n// -----------------------------------------------------------------------------\n\nexport interface ResolvedVitestEnv {\n\treadonly stack: string;\n\treadonly runtimeRoot: string;\n\treadonly manifestPathOverride: string | undefined;\n\t/** True when the caller's env explicitly set `DEVSTACK_STACK`. The\n\t *  test-setup hook uses this to print a louder advisory when a\n\t *  user runs `pnpm test` without the recommended wiring. */\n\treadonly stackWasExplicit: boolean;\n}\n\n/** Resolve the vitest env contract from an arbitrary env bag.\n *  Side-effect free — tests pass a fixture; production code passes\n *  `process.env`. */\nexport const resolveVitestEnv = (\n\tenv: Readonly<Record<string, string | undefined>>,\n): ResolvedVitestEnv => {\n\tconst stackRaw = env[VITEST_ENV_VARS.STACK];\n\tconst stack = stackRaw !== undefined && stackRaw !== '' ? stackRaw : DEFAULT_STACK_NAME;\n\tconst runtimeRoot =\n\t\tenv[VITEST_ENV_VARS.RUNTIME_ROOT] ??\n\t\tenv[VITEST_ENV_VARS.RUNTIME_ROOT_LEGACY] ??\n\t\tDEFAULT_RUNTIME_ROOT;\n\tconst manifestPathOverride = env[VITEST_ENV_VARS.MANIFEST_PATH];\n\treturn {\n\t\tstack,\n\t\truntimeRoot: runtimeRoot === '' ? DEFAULT_RUNTIME_ROOT : runtimeRoot,\n\t\tmanifestPathOverride:\n\t\t\tmanifestPathOverride !== undefined && manifestPathOverride !== ''\n\t\t\t\t? manifestPathOverride\n\t\t\t\t: undefined,\n\t\tstackWasExplicit: stackRaw !== undefined && stackRaw !== '',\n\t};\n};\n"],"mappings":";;;AA6BA,MAAa,kBAAkB;;;CAG9B,OAAO;;;CAGP,cAAc;;;;CAId,qBAAqB;;;;CAIrB,eAAe;CACf;;;;AAWD,MAAa,qBAAqB;;;AAIlC,MAAa,uBAAuB;;;;;AAMpC,MAAa,yBAAyB;;;;AAmBtC,MAAa,oBACZ,QACuB;CACvB,MAAM,WAAW,IAAI,gBAAgB;CACrC,MAAM,QAAQ,aAAa,KAAA,KAAa,aAAa,KAAK,WAAW;CACrE,MAAM,cACL,IAAI,gBAAgB,iBACpB,IAAI,gBAAgB,wBAAA;CAErB,MAAM,uBAAuB,IAAI,gBAAgB;AACjD,QAAO;EACN;EACA,aAAa,gBAAgB,KAAK,uBAAuB;EACzD,sBACC,yBAAyB,KAAA,KAAa,yBAAyB,KAC5D,uBACA,KAAA;EACJ,kBAAkB,aAAa,KAAA,KAAa,aAAa;EACzD"}

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

@@ -0,0 +1,44 @@
+import * as _$effect_Types0 from "effect/Types";
+import * as _$effect_Cause0 from "effect/Cause";
+
+//#region src/build-integrations/vitest/errors.d.ts
+declare const VitestManifestNotFoundError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "VitestManifestNotFoundError";
+} & Readonly<A>;
+/** A test-setup hook asked for the manifest but no on-disk file was
+ *  found by the walk-up or override path. The supervisor either hasn't
+ *  run yet or the wrong stack/state-dir is configured. */
+declare class VitestManifestNotFoundError extends VitestManifestNotFoundError_base<{
+  readonly message: string;
+  readonly searchedFrom: string;
+  readonly stack: string;
+  readonly stateDir: string;
+  readonly recovery: string;
+}> {}
+declare const VitestManifestShapeError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "VitestManifestShapeError";
+} & Readonly<A>;
+/** The manifest exists but doesn't decode against the L0 envelope schema
+ *  — either malformed JSON or shape drift after a manifestVersion bump. */
+declare class VitestManifestShapeError extends VitestManifestShapeError_base<{
+  readonly message: string;
+  readonly path: string;
+  readonly phase: 'parse' | 'shape';
+  readonly recovery: string;
+  readonly cause?: unknown;
+}> {}
+declare const VitestSetupPreconditionError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "VitestSetupPreconditionError";
+} & Readonly<A>;
+/** A test-setup precondition was violated. Currently only one case:
+ *  the caller asked for `requireDevstack: true` but the manifest wasn't
+ *  discoverable. Distinct from the discovery error because the caller
+ *  opted IN to the requirement. */
+declare class VitestSetupPreconditionError extends VitestSetupPreconditionError_base<{
+  readonly message: string;
+  readonly hint?: string;
+}> {}
+type VitestIntegrationError = VitestManifestNotFoundError | VitestManifestShapeError | VitestSetupPreconditionError;
+//#endregion
+export { VitestIntegrationError, VitestManifestNotFoundError, VitestManifestShapeError, VitestSetupPreconditionError };
+//# sourceMappingURL=errors.d.mts.map

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

@@ -0,0 +1,18 @@
+import { Data } from "effect";
+//#region src/build-integrations/vitest/errors.ts
+/** A test-setup hook asked for the manifest but no on-disk file was
+*  found by the walk-up or override path. The supervisor either hasn't
+*  run yet or the wrong stack/state-dir is configured. */
+var VitestManifestNotFoundError = class extends Data.TaggedError("VitestManifestNotFoundError") {};
+/** The manifest exists but doesn't decode against the L0 envelope schema
+*  — either malformed JSON or shape drift after a manifestVersion bump. */
+var VitestManifestShapeError = class extends Data.TaggedError("VitestManifestShapeError") {};
+/** A test-setup precondition was violated. Currently only one case:
+*  the caller asked for `requireDevstack: true` but the manifest wasn't
+*  discoverable. Distinct from the discovery error because the caller
+*  opted IN to the requirement. */
+var VitestSetupPreconditionError = class extends Data.TaggedError("VitestSetupPreconditionError") {};
+//#endregion
+export { VitestManifestNotFoundError, VitestManifestShapeError, VitestSetupPreconditionError };
+
+//# sourceMappingURL=errors.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/build-integrations/vitest/errors.ts"],"sourcesContent":["// Vitest build-integration — typed errors.\n//\n// Architecture (distilled/23-build-integrations.md § Per-integration\n// requirements → Vitest, § Edge cases): the vitest preset is a pure\n// reader of files + env vars. The two failure modes it surfaces are\n//   (a) manifest discovery failed when a test-setup hook asked for it,\n//   (b) manifest exists but its shape doesn't match.\n// Both errors carry a `recovery` string so the test-setup printout is\n// actionable instead of a generic schema-decode trace.\n//\n// These tags mirror the engine's `ManifestDiscoveryError` /\n// `ManifestShapeError` (substrate-side; see `runtime/` once it lands)\n// but stay local to the vitest surface so consumers can `catchTag`\n// without importing from substrate.\n\nimport { Data } from 'effect';\n\n/** A test-setup hook asked for the manifest but no on-disk file was\n *  found by the walk-up or override path. The supervisor either hasn't\n *  run yet or the wrong stack/state-dir is configured. */\nexport class VitestManifestNotFoundError extends Data.TaggedError('VitestManifestNotFoundError')<{\n\treadonly message: string;\n\treadonly searchedFrom: string;\n\treadonly stack: string;\n\treadonly stateDir: string;\n\treadonly recovery: string;\n}> {}\n\n/** The manifest exists but doesn't decode against the L0 envelope schema\n *  — either malformed JSON or shape drift after a manifestVersion bump. */\nexport class VitestManifestShapeError extends Data.TaggedError('VitestManifestShapeError')<{\n\treadonly message: string;\n\treadonly path: string;\n\treadonly phase: 'parse' | 'shape';\n\treadonly recovery: string;\n\treadonly cause?: unknown;\n}> {}\n\n/** A test-setup precondition was violated. Currently only one case:\n *  the caller asked for `requireDevstack: true` but the manifest wasn't\n *  discoverable. Distinct from the discovery error because the caller\n *  opted IN to the requirement. */\nexport class VitestSetupPreconditionError extends Data.TaggedError('VitestSetupPreconditionError')<{\n\treadonly message: string;\n\treadonly hint?: string;\n}> {}\n\nexport type VitestIntegrationError =\n\t| VitestManifestNotFoundError\n\t| VitestManifestShapeError\n\t| VitestSetupPreconditionError;\n"],"mappings":";;;;;AAoBA,IAAa,8BAAb,cAAiD,KAAK,YAAY,8BAA8B,CAM7F;;;AAIH,IAAa,2BAAb,cAA8C,KAAK,YAAY,2BAA2B,CAMvF;;;;;AAMH,IAAa,+BAAb,cAAkD,KAAK,YAAY,+BAA+B,CAG/F"}

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

@@ -0,0 +1,6 @@
+import { LoadStackContextOptions, StackContext, loadStackContext } from "./stack-context.mjs";
+import { TestSetupOptions, VitestLifecycleHooks, getStackContext, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup } from "./setup.mjs";
+import { DevstackVitestTestConfigOptions, devstackVitestServerConfig, devstackVitestTestConfig } from "./config.mjs";
+import { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, ResolvedVitestEnv, VITEST_ENV_VARS, VitestEnvVarName, resolveVitestEnv } from "./env.mjs";
+import { VitestIntegrationError, VitestManifestNotFoundError, VitestManifestShapeError, VitestSetupPreconditionError } from "./errors.mjs";
+export { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, type DevstackVitestTestConfigOptions, type LoadStackContextOptions, RECOMMENDED_TEST_STACK, type ResolvedVitestEnv, type StackContext, type TestSetupOptions, VITEST_ENV_VARS, type VitestEnvVarName, type VitestIntegrationError, type VitestLifecycleHooks, VitestManifestNotFoundError, VitestManifestShapeError, VitestSetupPreconditionError, devstackVitestServerConfig, devstackVitestTestConfig, getStackContext, loadStackContext, resolveVitestEnv, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup };

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

@@ -0,0 +1,6 @@
+import { devstackVitestServerConfig, devstackVitestTestConfig } from "./config.mjs";
+import { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, VITEST_ENV_VARS, resolveVitestEnv } from "./env.mjs";
+import { VitestManifestNotFoundError, VitestManifestShapeError, VitestSetupPreconditionError } from "./errors.mjs";
+import { loadStackContext } from "./stack-context.mjs";
+import { getStackContext, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup } from "./setup.mjs";
+export { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, VITEST_ENV_VARS, VitestManifestNotFoundError, VitestManifestShapeError, VitestSetupPreconditionError, devstackVitestServerConfig, devstackVitestTestConfig, getStackContext, loadStackContext, resolveVitestEnv, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup };

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

@@ -0,0 +1,53 @@
+import { LoadStackContextOptions, StackContext } from "./stack-context.mjs";
+
+//#region src/build-integrations/vitest/setup.d.ts
+/** Return the StackContext captured by `runDevstackBeforeAll`. Returns
+ *  `undefined` until `beforeAll` has run (or when the suite ran with
+ *  `requireDevstack: false` and no manifest exists). */
+declare const getStackContext: () => StackContext | undefined;
+/** Reset the captured fixture. Called by `runDevstackAfterAll`; also
+ *  exported so test helpers can wipe between describe-block setups. */
+declare const clearStackContext: () => void;
+interface TestSetupOptions extends LoadStackContextOptions {
+  /** When `true`, `beforeAll` throws if no manifest is on disk. Use
+   *  for suites that depend on a live devstack and would fail
+   *  confusingly later. Default `false` (manifest is best-effort). */
+  readonly requireDevstack?: boolean;
+  /** Suppress the stack-name advisory. Default `false`. */
+  readonly silent?: boolean;
+  /** Custom writer for the advisory line. Defaults to `console.warn`.
+   *  Tests substitute a buffer. */
+  readonly writeAdvisory?: (line: string) => void;
+}
+/** `beforeAll` body. Exported as a plain function so callers can wire
+ *  it into Vitest's hooks directly OR call it inline from a
+ *  setup-file. */
+declare const runDevstackBeforeAll: (options?: TestSetupOptions) => void;
+/** `afterAll` body. Currently just clears the captured fixture; the
+ *  separate symbol lets us extend later (e.g. snapshot diagnostics)
+ *  without touching consumer setup files. */
+declare const runDevstackAfterAll: () => void;
+/** Vitest's `beforeAll` / `afterAll` hook signatures. Match the
+ *  `vitest`-package shapes without importing the module (so this file
+ *  stays consumable by orchestrators that don't ship vitest as a
+ *  hard dep). */
+interface VitestLifecycleHooks {
+  readonly beforeAll: (fn: () => void | Promise<void>) => void;
+  readonly afterAll: (fn: () => void | Promise<void>) => void;
+}
+/**
+ * Wire the devstack setup/teardown into a vitest test file's hook
+ * functions. Typical usage in a `test-setup.ts`:
+ *
+ *     import { beforeAll, afterAll } from 'vitest';
+ *     import { useDevstackTestSetup }
+ *       from '@mysten-incubation/devstack/vitest';
+ *
+ *     useDevstackTestSetup({ beforeAll, afterAll }, { requireDevstack: true });
+ *
+ * The preset wires this automatically when `opts.testSetup: true`.
+ */
+declare const useDevstackTestSetup: (hooks: VitestLifecycleHooks, options?: TestSetupOptions) => void;
+//#endregion
+export { TestSetupOptions, VitestLifecycleHooks, clearStackContext, getStackContext, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup };
+//# sourceMappingURL=setup.d.mts.map

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

@@ -0,0 +1,56 @@
+import { RECOMMENDED_TEST_STACK, VITEST_ENV_VARS, resolveVitestEnv } from "./env.mjs";
+import { VitestSetupPreconditionError } from "./errors.mjs";
+import { loadStackContext } from "./stack-context.mjs";
+//#region src/build-integrations/vitest/setup.ts
+let captured;
+/** Return the StackContext captured by `runDevstackBeforeAll`. Returns
+*  `undefined` until `beforeAll` has run (or when the suite ran with
+*  `requireDevstack: false` and no manifest exists). */
+const getStackContext = () => captured;
+/** Reset the captured fixture. Called by `runDevstackAfterAll`; also
+*  exported so test helpers can wipe between describe-block setups. */
+const clearStackContext = () => {
+	captured = void 0;
+};
+/** `beforeAll` body. Exported as a plain function so callers can wire
+*  it into Vitest's hooks directly OR call it inline from a
+*  setup-file. */
+const runDevstackBeforeAll = (options = {}) => {
+	const resolved = resolveVitestEnv(options.env ?? process.env);
+	if (!options.silent && !resolved.stackWasExplicit) (options.writeAdvisory ?? ((line) => console.warn(line)))(`[devstack/vitest] ${VITEST_ENV_VARS.STACK} is unset; tests will read the '${resolved.stack}' stack. Set ${VITEST_ENV_VARS.STACK}=${RECOMMENDED_TEST_STACK} in the test script to avoid contention with \`pnpm dev\`.`);
+	const ctx = loadStackContext({
+		...options,
+		required: options.requireDevstack === true
+	});
+	if (options.requireDevstack === true && ctx === void 0) throw new VitestSetupPreconditionError({
+		message: `requireDevstack: true but loadStackContext returned undefined`,
+		hint: "this is a devstack bug; please file an issue"
+	});
+	captured = ctx;
+};
+/** `afterAll` body. Currently just clears the captured fixture; the
+*  separate symbol lets us extend later (e.g. snapshot diagnostics)
+*  without touching consumer setup files. */
+const runDevstackAfterAll = () => {
+	clearStackContext();
+};
+/**
+* Wire the devstack setup/teardown into a vitest test file's hook
+* functions. Typical usage in a `test-setup.ts`:
+*
+*     import { beforeAll, afterAll } from 'vitest';
+*     import { useDevstackTestSetup }
+*       from '@mysten-incubation/devstack/vitest';
+*
+*     useDevstackTestSetup({ beforeAll, afterAll }, { requireDevstack: true });
+*
+* The preset wires this automatically when `opts.testSetup: true`.
+*/
+const useDevstackTestSetup = (hooks, options = {}) => {
+	hooks.beforeAll(() => runDevstackBeforeAll(options));
+	hooks.afterAll(() => runDevstackAfterAll());
+};
+//#endregion
+export { clearStackContext, getStackContext, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup };
+
+//# sourceMappingURL=setup.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"setup.mjs","names":[],"sources":["../../../src/build-integrations/vitest/setup.ts"],"sourcesContent":["// Vitest build-integration — test-setup hooks.\n//\n// Architecture (distilled/23-build-integrations.md § Per-integration\n// requirements → Vitest, § Lifecycle states): the preset itself does\n// NOT boot devstack; it is the test file's job (via\n// `@effect/vitest`'s `it.layer(stack.layer)`) to drive the lifecycle.\n//\n// But suites that talk to a LIVE devstack still need a small\n// before/after surface to:\n//   - Print a one-line advisory when `DEVSTACK_STACK` is unset (the\n//     test would otherwise run against `main`, contending with\n//     `pnpm dev`).\n//   - Optionally verify the manifest is on disk before the first\n//     `it.effect` fires (cheap probe, friendly error).\n//   - Optionally project the manifest into a shared fixture handle\n//     suites can `import { stackContext } from './setup-fixture.ts'`.\n//\n// This module is OPT-IN. A suite wires it via Vitest's `setupFiles`\n// (or via the `useTestSetup` registrar below for programmatic\n// composition). The preset wires it automatically when\n// `opts.testSetup` is truthy.\n//\n// Hook firing order:\n//   beforeAll  (once per file)\n//     1. resolveVitestEnv → print stack/runtimeRoot advisory if needed\n//     2. if requireDevstack: loadStackContext({required: true})\n//        else:               loadStackContext() (may be undefined)\n//     3. publish to the captured fixture so `getStackContext()` works\n//        synchronously inside `it`/`test` bodies\n//   afterAll   (once per file)\n//     4. clear the captured fixture (so a stale handle doesn't survive\n//        between watch runs)\n//\n// No teardown of the devstack itself — that's the supervisor's job;\n// the preset is a pure reader.\n\nimport {\n\tloadStackContext,\n\ttype LoadStackContextOptions,\n\ttype StackContext,\n} from './stack-context.ts';\nimport { resolveVitestEnv, VITEST_ENV_VARS, RECOMMENDED_TEST_STACK } from './env.ts';\nimport { VitestSetupPreconditionError } from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Captured fixture — single shared handle across the test file\n// -----------------------------------------------------------------------------\n\nlet captured: StackContext | undefined;\n\n/** Return the StackContext captured by `runDevstackBeforeAll`. Returns\n *  `undefined` until `beforeAll` has run (or when the suite ran with\n *  `requireDevstack: false` and no manifest exists). */\nexport const getStackContext = (): StackContext | undefined => captured;\n\n/** Reset the captured fixture. Called by `runDevstackAfterAll`; also\n *  exported so test helpers can wipe between describe-block setups. */\nexport const clearStackContext = (): void => {\n\tcaptured = undefined;\n};\n\n// -----------------------------------------------------------------------------\n// Options\n// -----------------------------------------------------------------------------\n\nexport interface TestSetupOptions extends LoadStackContextOptions {\n\t/** When `true`, `beforeAll` throws if no manifest is on disk. Use\n\t *  for suites that depend on a live devstack and would fail\n\t *  confusingly later. Default `false` (manifest is best-effort). */\n\treadonly requireDevstack?: boolean;\n\t/** Suppress the stack-name advisory. Default `false`. */\n\treadonly silent?: boolean;\n\t/** Custom writer for the advisory line. Defaults to `console.warn`.\n\t *  Tests substitute a buffer. */\n\treadonly writeAdvisory?: (line: string) => void;\n}\n\n// -----------------------------------------------------------------------------\n// Hooks\n// -----------------------------------------------------------------------------\n\n/** `beforeAll` body. Exported as a plain function so callers can wire\n *  it into Vitest's hooks directly OR call it inline from a\n *  setup-file. */\nexport const runDevstackBeforeAll = (options: TestSetupOptions = {}): void => {\n\tconst env = options.env ?? (process.env as Readonly<Record<string, string | undefined>>);\n\tconst resolved = resolveVitestEnv(env);\n\n\tif (!options.silent && !resolved.stackWasExplicit) {\n\t\tconst write = options.writeAdvisory ?? ((line: string) => console.warn(line));\n\t\twrite(\n\t\t\t`[devstack/vitest] ${VITEST_ENV_VARS.STACK} is unset; tests will read the '${resolved.stack}' stack. ` +\n\t\t\t\t`Set ${VITEST_ENV_VARS.STACK}=${RECOMMENDED_TEST_STACK} in the test script to avoid contention with \\`pnpm dev\\`.`,\n\t\t);\n\t}\n\n\tconst ctx = loadStackContext({\n\t\t...options,\n\t\trequired: options.requireDevstack === true,\n\t});\n\n\tif (options.requireDevstack === true && ctx === undefined) {\n\t\t// `loadStackContext({required: true})` should have thrown.\n\t\t// Defensive — surfaces a clearer error if a future refactor\n\t\t// changes the required-miss semantics.\n\t\tthrow new VitestSetupPreconditionError({\n\t\t\tmessage: `requireDevstack: true but loadStackContext returned undefined`,\n\t\t\thint: 'this is a devstack bug; please file an issue',\n\t\t});\n\t}\n\n\tcaptured = ctx;\n};\n\n/** `afterAll` body. Currently just clears the captured fixture; the\n *  separate symbol lets us extend later (e.g. snapshot diagnostics)\n *  without touching consumer setup files. */\nexport const runDevstackAfterAll = (): void => {\n\tclearStackContext();\n};\n\n// -----------------------------------------------------------------------------\n// Vitest hook registrar\n// -----------------------------------------------------------------------------\n\n/** Vitest's `beforeAll` / `afterAll` hook signatures. Match the\n *  `vitest`-package shapes without importing the module (so this file\n *  stays consumable by orchestrators that don't ship vitest as a\n *  hard dep). */\nexport interface VitestLifecycleHooks {\n\treadonly beforeAll: (fn: () => void | Promise<void>) => void;\n\treadonly afterAll: (fn: () => void | Promise<void>) => void;\n}\n\n/**\n * Wire the devstack setup/teardown into a vitest test file's hook\n * functions. Typical usage in a `test-setup.ts`:\n *\n *     import { beforeAll, afterAll } from 'vitest';\n *     import { useDevstackTestSetup }\n *       from '@mysten-incubation/devstack/vitest';\n *\n *     useDevstackTestSetup({ beforeAll, afterAll }, { requireDevstack: true });\n *\n * The preset wires this automatically when `opts.testSetup: true`.\n */\nexport const useDevstackTestSetup = (\n\thooks: VitestLifecycleHooks,\n\toptions: TestSetupOptions = {},\n): void => {\n\thooks.beforeAll(() => runDevstackBeforeAll(options));\n\thooks.afterAll(() => runDevstackAfterAll());\n};\n"],"mappings":";;;;AAgDA,IAAI;;;;AAKJ,MAAa,wBAAkD;;;AAI/D,MAAa,0BAAgC;AAC5C,YAAW,KAAA;;;;;AA0BZ,MAAa,wBAAwB,UAA4B,EAAE,KAAW;CAE7E,MAAM,WAAW,iBADL,QAAQ,OAAQ,QAAQ,IACE;AAEtC,KAAI,CAAC,QAAQ,UAAU,CAAC,SAAS,iBAEhC,EADc,QAAQ,mBAAmB,SAAiB,QAAQ,KAAK,KAAK,GAE3E,qBAAqB,gBAAgB,MAAM,kCAAkC,SAAS,MAAM,eACpF,gBAAgB,MAAM,GAAG,uBAAuB,4DACxD;CAGF,MAAM,MAAM,iBAAiB;EAC5B,GAAG;EACH,UAAU,QAAQ,oBAAoB;EACtC,CAAC;AAEF,KAAI,QAAQ,oBAAoB,QAAQ,QAAQ,KAAA,EAI/C,OAAM,IAAI,6BAA6B;EACtC,SAAS;EACT,MAAM;EACN,CAAC;AAGH,YAAW;;;;;AAMZ,MAAa,4BAAkC;AAC9C,oBAAmB;;;;;;;;;;;;;;AA4BpB,MAAa,wBACZ,OACA,UAA4B,EAAE,KACpB;AACV,OAAM,gBAAgB,qBAAqB,QAAQ,CAAC;AACpD,OAAM,eAAe,qBAAqB,CAAC"}

package/dist/build-integrations/vitest/stack-context.d.mts

@@ -0,0 +1,58 @@
+import { ManifestEnvelope } from "../../substrate/manifest.mjs";
+
+//#region src/build-integrations/vitest/stack-context.d.ts
+/** Read-only projection over the live manifest, scoped to the vitest
+ *  surface's needs. The full envelope is reconstructed (`manifest`)
+ *  for the test-side helpers that compare deep shapes; the convenience
+ *  accessors cover the common case. */
+interface StackContext {
+  /** Absolute path of the manifest file the projection came from. */
+  readonly manifestPath: string;
+  /** Reconstructed envelope — same shape downstream consumers had
+   *  pre-consolidation. */
+  readonly manifest: ManifestEnvelope;
+  /** Identity tuple shortcut. */
+  readonly identity: ManifestEnvelope['identity'];
+  /** Flat endpoint lookup — returns the URL string or `undefined`. */
+  readonly endpoint: (name: string) => string | undefined;
+  /** Display URL variant — falls back to `url` when `displayUrl` is
+   *  null (the routed-vs-direct distinction the router decides). */
+  readonly displayEndpoint: (name: string) => string | undefined;
+}
+interface LoadStackContextOptions {
+  /** Starting directory for the walk-up. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /** Stack name override. Defaults to `process.env.DEVSTACK_STACK`
+   *  with a final fallback to `'main'`. */
+  readonly stack?: string;
+  /** Runtime root override (legacy `.devstack` directory). Defaults
+   *  to `process.env.DEVSTACK_RUNTIME_ROOT` /
+   *  `process.env.DEVSTACK_STATE_DIR` with a final fallback to
+   *  `'.devstack'`. */
+  readonly runtimeRoot?: string;
+  /** Explicit absolute manifest path. Bypasses the walk-up but is
+   *  still validated to exist. Lower precedence than the
+   *  `DEVSTACK_MANIFEST_PATH` env var. */
+  readonly manifestPath?: string;
+  /** Env bag for the resolver. Defaults to `process.env`. Tests pass
+   *  a fixture. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** When `true`, throw `VitestManifestNotFoundError` on miss instead
+   *  of returning `undefined`. */
+  readonly required?: boolean;
+}
+/**
+ * Read the on-disk manifest, decode against the envelope schema, and
+ * return a projection. Returns `undefined` on miss; pass
+ * `{ required: true }` to throw `VitestManifestNotFoundError`.
+ *
+ * Precedence ladder (highest → lowest):
+ *   1. `env.DEVSTACK_MANIFEST_PATH`
+ *   2. `opts.manifestPath`
+ *   3. walk-up from `opts.cwd` looking for
+ *      `<runtimeRoot>/stacks/<stack>/manifest.json`
+ */
+declare const loadStackContext: (opts?: LoadStackContextOptions) => StackContext | undefined;
+//#endregion
+export { LoadStackContextOptions, StackContext, loadStackContext };
+//# sourceMappingURL=stack-context.d.mts.map

package/dist/build-integrations/vitest/stack-context.mjs

@@ -0,0 +1,67 @@
+import { ManifestDiscoveryError, ManifestShapeError } from "../runtime/errors.mjs";
+import { manifestEnvelopeFromStackContext, readStackContext } from "../runtime/read-stack-context.mjs";
+import { VITEST_ENV_VARS } from "./env.mjs";
+import { VitestManifestNotFoundError, VitestManifestShapeError } from "./errors.mjs";
+//#region src/build-integrations/vitest/stack-context.ts
+const project = (ctx) => {
+	const envelope = manifestEnvelopeFromStackContext(ctx);
+	return {
+		manifestPath: ctx.manifestPath,
+		manifest: envelope,
+		identity: envelope.identity,
+		endpoint: (name) => ctx.endpoints.byName(name)?.url,
+		displayEndpoint: (name) => {
+			const e = ctx.endpoints.byName(name);
+			if (e === void 0) return void 0;
+			return e.displayUrl ?? e.url;
+		}
+	};
+};
+/**
+* Read the on-disk manifest, decode against the envelope schema, and
+* return a projection. Returns `undefined` on miss; pass
+* `{ required: true }` to throw `VitestManifestNotFoundError`.
+*
+* Precedence ladder (highest → lowest):
+*   1. `env.DEVSTACK_MANIFEST_PATH`
+*   2. `opts.manifestPath`
+*   3. walk-up from `opts.cwd` looking for
+*      `<runtimeRoot>/stacks/<stack>/manifest.json`
+*/
+const loadStackContext = (opts = {}) => {
+	const env = opts.env ?? process.env;
+	const stack = opts.stack ?? env[VITEST_ENV_VARS.STACK] ?? "main";
+	const runtimeRoot = opts.runtimeRoot ?? env[VITEST_ENV_VARS.RUNTIME_ROOT] ?? env[VITEST_ENV_VARS.RUNTIME_ROOT_LEGACY] ?? ".devstack";
+	try {
+		return project(readStackContext({
+			...opts.cwd !== void 0 ? { cwd: opts.cwd } : {},
+			stack,
+			stateDir: runtimeRoot,
+			env,
+			...opts.manifestPath !== void 0 ? { manifestPath: opts.manifestPath } : {}
+		}));
+	} catch (err) {
+		if (err instanceof ManifestDiscoveryError) {
+			if (opts.required === true) throw new VitestManifestNotFoundError({
+				message: `no devstack manifest found for stack '${stack}' under '${runtimeRoot}'`,
+				searchedFrom: opts.cwd ?? process.cwd(),
+				stack,
+				stateDir: runtimeRoot,
+				recovery: `run \`devstack up\` (or set DEVSTACK_MANIFEST_PATH to an existing file)`
+			});
+			return;
+		}
+		if (err instanceof ManifestShapeError) throw new VitestManifestShapeError({
+			phase: err.phase === "parse" ? "parse" : "shape",
+			path: err.path,
+			message: err.message,
+			recovery: err.phase === "parse" ? `rm ${err.path} && devstack apply  # regenerate from the registries` : `rm -rf <runtimeRoot>/stacks/<stack>/manifest.json && devstack apply  # regenerate`,
+			cause: err
+		});
+		throw err;
+	}
+};
+//#endregion
+export { loadStackContext };
+
+//# sourceMappingURL=stack-context.mjs.map