@mysten-incubation/devstack 0.1.1 → 0.2.0

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

@@ -1 +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\nimport { DEFAULT_DISCOVERY_STACK } from '../runtime/resolve-discovery-env.ts';\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. Re-exported from\n *  the discovery ladder's `DEFAULT_DISCOVERY_STACK` (single source of\n *  truth) — but tests should explicitly set `DEVSTACK_STACK=test`\n *  rather than rely on this. */\nexport const DEFAULT_STACK_NAME = DEFAULT_DISCOVERY_STACK;\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":";;;;AA+BA,MAAa,kBAAkB;;;CAG9B,OAAO;;;CAGP,cAAc;;;;CAId,qBAAqB;;;;CAIrB,eAAe;CACf;;;;;AAYD,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"}
+{"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`.\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\nimport { inferPackageNameFromCwd } from '../../api/inference-network.ts';\nimport { DEFAULT_DISCOVERY_STACK } from '../runtime/resolve-discovery-env.ts';\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/** Alias for `RUNTIME_ROOT`. 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. Re-exported from\n *  the discovery ladder's `DEFAULT_DISCOVERY_STACK` (single source of\n *  truth) — but tests should explicitly set `DEVSTACK_STACK=test`\n *  rather than rely on this. */\nexport const DEFAULT_STACK_NAME = DEFAULT_DISCOVERY_STACK;\n\n/** Default runtime root when no runtime-root override 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\nexport interface ResolveVitestEnvOptions {\n\t/** Walk-up start for the package-name rung of the stack ladder,\n\t *  mirroring `resolveDiscoveryEnv` / the CLI's `resolveStackName`:\n\t *  when `DEVSTACK_STACK` is unset, the stack falls back to the\n\t *  nearest package.json `name` above `cwd` before `'main'`. Opt-in —\n\t *  omit it and the resolver stays fs-free with the bare\n\t *  env > `'main'` ladder. The setup hook threads it so the advisory\n\t *  names the stack `loadStackContext` will actually read. */\n\treadonly cwd?: string;\n}\n\n/** Resolve the vitest env contract from an arbitrary env bag.\n *  Side-effect free when `options.cwd` is omitted — tests pass a\n *  fixture; production code passes `process.env`. With `cwd`, the only\n *  fs access is the lazy package.json walk-up on the stack rung, and\n *  only when `DEVSTACK_STACK` is unset. */\nexport const resolveVitestEnv = (\n\tenv: Readonly<Record<string, string | undefined>>,\n\toptions: ResolveVitestEnvOptions = {},\n): ResolvedVitestEnv => {\n\tconst stackRaw = env[VITEST_ENV_VARS.STACK];\n\tconst stackWasExplicit = stackRaw !== undefined && stackRaw !== '';\n\tconst stack = stackWasExplicit\n\t\t? stackRaw\n\t\t: ((options.cwd !== undefined ? inferPackageNameFromCwd(options.cwd) : undefined) ??\n\t\t\tDEFAULT_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,\n\t};\n};\n"],"mappings":";;;;;AA6BA,MAAa,kBAAkB;;;CAG9B,OAAO;;;CAGP,cAAc;;CAEd,qBAAqB;;;;CAIrB,eAAe;AAChB;;;;;AAYA,MAAa,qBAAqB;;AAGlC,MAAa,uBAAuB;;;;;AAMpC,MAAa,yBAAyB;;;;;;AAgCtC,MAAa,oBACZ,KACA,UAAmC,CAAC,MACb;CACvB,MAAM,WAAW,IAAI,gBAAgB;CACrC,MAAM,mBAAmB,aAAa,KAAA,KAAa,aAAa;CAChE,MAAM,QAAQ,mBACX,YACE,QAAQ,QAAQ,KAAA,IAAY,wBAAwB,QAAQ,GAAG,IAAI,KAAA,MACtE;CACF,MAAM,cACL,IAAI,gBAAgB,iBACpB,IAAI,gBAAgB,wBAAA;CAErB,MAAM,uBAAuB,IAAI,gBAAgB;CACjD,OAAO;EACN;EACA,aAAa,gBAAgB,KAAK,uBAAuB;EACzD,sBACC,yBAAyB,KAAA,KAAa,yBAAyB,KAC5D,uBACA,KAAA;EACJ;CACD;AACD"}

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

@@ -1,8 +1,5 @@
-import * as _$effect_Cause0 from "effect/Cause";
-import * as _$effect_Types0 from "effect/Types";
-
 //#region src/build-integrations/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 & {
+declare const VitestManifestNotFoundError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "VitestManifestNotFoundError";
 } & Readonly<A>;
 /** A test-setup hook asked for the manifest but no on-disk file was
@@ -15,7 +12,7 @@ declare class VitestManifestNotFoundError extends VitestManifestNotFoundError_ba
   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 & {
+declare const VitestManifestShapeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "VitestManifestShapeError";
 } & Readonly<A>;
 /** The manifest exists but doesn't decode against the L0 envelope schema
@@ -25,8 +22,8 @@ declare const VitestManifestShapeError_base: new <A extends Record<string, any>
  *  the "manifest looks like garbage / your envelope was wrong" recovery
  *  ("regenerate the manifest"); the version-mismatch tag carries the
  *  "build-integration and supervisor are at different versions"
- *  recovery (upgrade the consumer dependency). Splitting the two lets
- *  callers `catchTag` independently and surface a precise hint. */
+ *  recovery. Splitting the two lets callers `catchTag`
+ *  independently and surface a precise hint. */
 declare class VitestManifestShapeError extends VitestManifestShapeError_base<{
   readonly message: string;
   readonly path: string;
@@ -34,21 +31,20 @@ declare class VitestManifestShapeError extends VitestManifestShapeError_base<{
   readonly recovery: string;
   readonly cause?: unknown;
 }> {}
-declare const VitestManifestVersionMismatchError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+declare const VitestManifestVersionMismatchError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "VitestManifestVersionMismatchError";
 } & Readonly<A>;
 /** The manifest exists, decodes structurally, but its `manifestVersion`
  *  doesn't match what this consumer build was compiled for. Distinct
  *  from `VitestManifestShapeError` so callers can `catchTag` the two
- *  separately — the recovery action is "upgrade your devstack
- *  consumer dependency" rather than "regenerate the manifest". */
+ *  separately. */
 declare class VitestManifestVersionMismatchError extends VitestManifestVersionMismatchError_base<{
   readonly message: string;
   readonly path: string;
   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 & {
+declare const VitestSetupPreconditionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "VitestSetupPreconditionError";
 } & Readonly<A>;
 /** A test-setup precondition was violated. Currently only one case:

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

@@ -11,14 +11,13 @@ var VitestManifestNotFoundError = class extends Data.TaggedError("VitestManifest
 *  the "manifest looks like garbage / your envelope was wrong" recovery
 *  ("regenerate the manifest"); the version-mismatch tag carries the
 *  "build-integration and supervisor are at different versions"
-*  recovery (upgrade the consumer dependency). Splitting the two lets
-*  callers `catchTag` independently and surface a precise hint. */
+*  recovery. Splitting the two lets callers `catchTag`
+*  independently and surface a precise hint. */
 var VitestManifestShapeError = class extends Data.TaggedError("VitestManifestShapeError") {};
 /** The manifest exists, decodes structurally, but its `manifestVersion`
 *  doesn't match what this consumer build was compiled for. Distinct
 *  from `VitestManifestShapeError` so callers can `catchTag` the two
-*  separately — the recovery action is "upgrade your devstack
-*  consumer dependency" rather than "regenerate the manifest". */
+*  separately. */
 var VitestManifestVersionMismatchError = class extends Data.TaggedError("VitestManifestVersionMismatchError") {};
 /** A test-setup precondition was violated. Currently only one case:
 *  the caller asked for `requireDevstack: true` but the manifest wasn't

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

@@ -1 +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 (`parse`) or shape drift (`shape`).\n *\n *  Distinct from `VitestManifestVersionMismatchError`: this tag carries\n *  the \"manifest looks like garbage / your envelope was wrong\" recovery\n *  (\"regenerate the manifest\"); the version-mismatch tag carries the\n *  \"build-integration and supervisor are at different versions\"\n *  recovery (upgrade the consumer dependency). Splitting the two lets\n *  callers `catchTag` independently and surface a precise hint. */\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/** The manifest exists, decodes structurally, but its `manifestVersion`\n *  doesn't match what this consumer build was compiled for. Distinct\n *  from `VitestManifestShapeError` so callers can `catchTag` the two\n *  separately — the recovery action is \"upgrade your devstack\n *  consumer dependency\" rather than \"regenerate the manifest\". */\nexport class VitestManifestVersionMismatchError extends Data.TaggedError(\n\t'VitestManifestVersionMismatchError',\n)<{\n\treadonly message: string;\n\treadonly path: string;\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| VitestManifestVersionMismatchError\n\t| VitestSetupPreconditionError;\n"],"mappings":";;;;;AAoBA,IAAa,8BAAb,cAAiD,KAAK,YAAY,8BAA8B,CAM7F;;;;;;;;;;AAWH,IAAa,2BAAb,cAA8C,KAAK,YAAY,2BAA2B,CAMvF;;;;;;AAOH,IAAa,qCAAb,cAAwD,KAAK,YAC5D,qCACA,CAKE;;;;;AAMH,IAAa,+BAAb,cAAkD,KAAK,YAAY,+BAA+B,CAG/F"}
+{"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 (`parse`) or shape drift (`shape`).\n *\n *  Distinct from `VitestManifestVersionMismatchError`: this tag carries\n *  the \"manifest looks like garbage / your envelope was wrong\" recovery\n *  (\"regenerate the manifest\"); the version-mismatch tag carries the\n *  \"build-integration and supervisor are at different versions\"\n *  recovery. Splitting the two lets callers `catchTag`\n *  independently and surface a precise hint. */\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/** The manifest exists, decodes structurally, but its `manifestVersion`\n *  doesn't match what this consumer build was compiled for. Distinct\n *  from `VitestManifestShapeError` so callers can `catchTag` the two\n *  separately. */\nexport class VitestManifestVersionMismatchError extends Data.TaggedError(\n\t'VitestManifestVersionMismatchError',\n)<{\n\treadonly message: string;\n\treadonly path: string;\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| VitestManifestVersionMismatchError\n\t| VitestSetupPreconditionError;\n"],"mappings":";;;;;AAoBA,IAAa,8BAAb,cAAiD,KAAK,YAAY,6BAA6B,CAAC,CAM7F,CAAC;;;;;;;;;;AAWJ,IAAa,2BAAb,cAA8C,KAAK,YAAY,0BAA0B,CAAC,CAMvF,CAAC;;;;;AAMJ,IAAa,qCAAb,cAAwD,KAAK,YAC5D,oCACD,CAAC,CAKE,CAAC;;;;;AAMJ,IAAa,+BAAb,cAAkD,KAAK,YAAY,8BAA8B,CAAC,CAG/F,CAAC"}

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

@@ -0,0 +1,35 @@
+//#region src/build-integrations/vitest/global-setup.d.ts
+interface DevstackVitestGlobalSetupOptions {
+  /** Stack name to boot. Default: `DEVSTACK_STACK` if set, else
+   *  `RECOMMENDED_TEST_STACK` (`'test'`). The booted identity forces
+   *  this stack, so it coexists with a developer's `main` dev stack. */
+  readonly stack?: string;
+  /** Path to the app's `devstack.config.ts`. Default: walk-up from cwd. */
+  readonly configPath?: string;
+  /** Runtime root holding `stacks/<stack>/manifest.json`. Default:
+   *  `DEVSTACK_RUNTIME_ROOT` / `DEVSTACK_STATE_DIR` / `.devstack`. */
+  readonly runtimeRoot?: string;
+  /** Reuse an already-running stack instead of booting a fresh one (no
+   *  boot, no teardown). Default: `false` — also enabled by
+   *  `DEVSTACK_TEST_REUSE=1`. */
+  readonly reuse?: boolean;
+  /** Hard cap (ms) for the stack to reach ready. Default 300_000 (5 min)
+   *  — accounts for cold supervisor boot under Docker image pulls. */
+  readonly bootTimeoutMs?: number;
+}
+/** Vitest's `globalSetup` contract: a setup function that optionally
+ *  returns a teardown function. */
+type DevstackVitestGlobalSetup = () => Promise<() => Promise<void>>;
+/**
+ * Build a vitest `globalSetup` that boots (or reuses) a dedicated test
+ * stack. Wire it via `devstackVitestTestConfig({ autoBoot: true })`, or
+ * reference the module path directly in `test.globalSetup`.
+ */
+declare const devstackVitestGlobalSetup: (opts?: DevstackVitestGlobalSetupOptions) => DevstackVitestGlobalSetup;
+/** Default export = a ready-to-use vitest `globalSetup`. This is what
+ *  `test.globalSetup: '@mysten-incubation/devstack/vitest/global-setup'`
+ *  resolves to. */
+declare const _default: DevstackVitestGlobalSetup;
+//#endregion
+export { DevstackVitestGlobalSetup, DevstackVitestGlobalSetupOptions, _default as default, devstackVitestGlobalSetup };
+//# sourceMappingURL=global-setup.d.mts.map

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

@@ -0,0 +1,156 @@
+import { runStack } from "../../api/run-stack.mjs";
+import { loadDevstackConfig } from "../../api/load-config.mjs";
+import { VITEST_ENV_VARS } from "./env.mjs";
+import { loadStackContext } from "./stack-context.mjs";
+import { Effect } from "effect";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+//#region src/build-integrations/vitest/global-setup.ts
+const DEFAULT_BOOT_TIMEOUT_MS = 3e5;
+const isTruthyEnv = (value) => value === "1" || value === "true" || value === "yes";
+const resolveRuntimeRoot = (opts, env) => opts.runtimeRoot ?? (env[VITEST_ENV_VARS.RUNTIME_ROOT] || env[VITEST_ENV_VARS.RUNTIME_ROOT_LEGACY] || void 0) ?? ".devstack";
+const resolveStackName = (opts, env) => {
+	const fromEnv = env[VITEST_ENV_VARS.STACK];
+	return opts.stack ?? (fromEnv && fromEnv !== "" ? fromEnv : "test");
+};
+const withTimeout = async (promise, ms, label) => {
+	let timer;
+	const timeout = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`${label} timed out after ${ms}ms`)), ms);
+	});
+	try {
+		return await Promise.race([promise, timeout]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+};
+const safeStop = async (handle) => {
+	try {
+		await Effect.runPromise(handle.stop);
+	} catch {}
+	try {
+		await Effect.runPromise(handle.awaitShutdown);
+	} catch {}
+};
+/** After the in-process supervisor has exited, graceful shutdown only
+*  STOPS the stack's containers (devstack keeps them for warm restarts).
+*  An ephemeral test stack should leave nothing behind, so run the
+*  production `devstack wipe` verb (force-removes containers + networks +
+*  volumes + per-stack on-disk state) for the booted stack. Best-effort:
+*  failure here never fails the test run, and a leftover stopped stack is
+*  force-recreated by the next boot anyway. Skip with `DEVSTACK_TEST_KEEP=1`
+*  to leave the stack up for debugging. */
+const wipeStack = (stack, runtimeRoot, cwd) => new Promise((resolve) => {
+	const cliEntry = fileURLToPath(new URL("../../cli/main.mjs", import.meta.url));
+	if (!existsSync(cliEntry)) {
+		resolve();
+		return;
+	}
+	const child = spawn(process.execPath, [
+		cliEntry,
+		"wipe",
+		"--yes"
+	], {
+		cwd,
+		env: {
+			...process.env,
+			DEVSTACK_STACK: stack,
+			DEVSTACK_RUNTIME_ROOT: runtimeRoot
+		},
+		stdio: "ignore"
+	});
+	child.unref();
+	const done = () => resolve();
+	child.on("error", done);
+	child.on("exit", done);
+	setTimeout(() => {
+		child.kill();
+		resolve();
+	}, 12e4).unref?.();
+});
+/** Best-effort, sync read of the booted stack's `codegen.idsFile` from its
+*  manifest. The generated `config-runtime.ts` resolver reads the injected
+*  `__DEVSTACK_IDS__` Vite `define`, but under vitest the Vite config (and
+*  thus that define) is evaluated BEFORE this `globalSetup` boots the stack,
+*  so the define bakes to `null`. The resolver's Node-only fallback reads
+*  `process.env.DEVSTACK_IDS_FILE` at id-access time instead — we point it at
+*  the freshly-booted stack's live id-config file here. Mirrors the Vite
+*  plugin's `readCodegenField`; degrades to `null` on any miss. */
+const readIdsFileFromManifest = (manifestPath) => {
+	try {
+		if (!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 value = codegen.idsFile;
+		return typeof value === "string" && value.length > 0 ? value : null;
+	} catch {
+		return null;
+	}
+};
+/** Publish the env handoff vitest forwards to test workers, so per-file
+*  `getStackContext()` resolves the stack this setup booted/attached, and the
+*  generated `config-runtime.ts` resolver can read the live ids
+*  (`DEVSTACK_IDS_FILE` — its Node fallback when the Vite `define` is null). */
+const publishHandoff = (stack, runtimeRoot, manifestPath) => {
+	process.env[VITEST_ENV_VARS.STACK] = stack;
+	process.env[VITEST_ENV_VARS.RUNTIME_ROOT] = runtimeRoot;
+	process.env[VITEST_ENV_VARS.MANIFEST_PATH] = manifestPath;
+	const idsFile = readIdsFileFromManifest(manifestPath);
+	if (idsFile !== null) process.env.DEVSTACK_IDS_FILE = idsFile;
+};
+/**
+* Build a vitest `globalSetup` that boots (or reuses) a dedicated test
+* stack. Wire it via `devstackVitestTestConfig({ autoBoot: true })`, or
+* reference the module path directly in `test.globalSetup`.
+*/
+const devstackVitestGlobalSetup = (opts = {}) => async () => {
+	const env = process.env;
+	const stack = resolveStackName(opts, env);
+	const runtimeRoot = resolveRuntimeRoot(opts, env);
+	if (opts.reuse ?? isTruthyEnv(env.DEVSTACK_TEST_REUSE)) {
+		publishHandoff(stack, runtimeRoot, loadStackContext({
+			stack,
+			runtimeRoot,
+			required: true
+		}).manifestPath);
+		return async () => {};
+	}
+	const loaded = await Effect.runPromise(loadDevstackConfig(opts.configPath)).catch((cause) => {
+		throw new Error(`devstack autoBoot: failed to load devstack config — ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	});
+	const handle = runStack(loaded.stack, {
+		identity: { stack },
+		appRoot: dirname(loaded.resolvedConfigPath),
+		runtimeRoot,
+		...loaded.engine.options.codegen !== void 0 ? { codegen: loaded.engine.options.codegen } : {}
+	});
+	try {
+		await withTimeout(Effect.runPromise(handle.start), opts.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS, `devstack autoBoot: '${stack}' stack boot`);
+	} catch (cause) {
+		await safeStop(handle);
+		throw new Error(`devstack autoBoot: failed to boot the '${stack}' stack. If a '${stack}' stack is already running, stop it with \`devstack down ${stack}\` or set DEVSTACK_TEST_REUSE=1 to run tests against it. Cause: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+	publishHandoff(stack, runtimeRoot, loadStackContext({
+		cwd: dirname(loaded.resolvedConfigPath),
+		stack,
+		runtimeRoot,
+		required: true
+	}).manifestPath);
+	const keep = isTruthyEnv(env.DEVSTACK_TEST_KEEP);
+	return async () => {
+		await safeStop(handle);
+		if (!keep) await wipeStack(stack, runtimeRoot, dirname(loaded.resolvedConfigPath));
+	};
+};
+/** Default export = a ready-to-use vitest `globalSetup`. This is what
+*  `test.globalSetup: '@mysten-incubation/devstack/vitest/global-setup'`
+*  resolves to. */
+var global_setup_default = devstackVitestGlobalSetup();
+//#endregion
+export { global_setup_default as default, devstackVitestGlobalSetup };
+
+//# sourceMappingURL=global-setup.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"global-setup.mjs","names":[],"sources":["../../../src/build-integrations/vitest/global-setup.ts"],"sourcesContent":["// Vitest `globalSetup` that boots a dedicated `test` stack for the run\n// and tears it down on completion.\n//\n// Why this exists (distilled/23-build-integrations.md § Vitest): the\n// per-file `setup.ts` preset is a passive manifest READER — it requires\n// a stack someone already started. This module is the missing boot seam:\n// `pnpm test` brings up its OWN isolated `test` stack so tests run in\n// parallel to a developer's `pnpm dev` (`main`) stack without contending\n// for ports / faucet / wallet, and without requiring the dev stack to be\n// up at all.\n//\n// Lifecycle (the locked design — \"boot fresh + teardown each run\"):\n//   setup    → load config, runStack(identity.stack='test'), await ready\n//   handoff  → publish env (DEVSTACK_STACK + DEVSTACK_MANIFEST_PATH) so the\n//              per-file workers' `loadStackContext` resolves THIS stack\n//   teardown → stop + awaitShutdown (robust: still tears down a half-booted\n//              stack so no `devstack.stack=test` containers leak)\n//\n// Escape hatch (reuse an already-running stack — e.g. your dev stack):\n//   set `DEVSTACK_TEST_REUSE=1` (and optionally point `DEVSTACK_STACK` at\n//   the running stack), or pass `{ reuse: true }`. Reuse mode does NOT\n//   boot and does NOT tear down — it only publishes the env handoff to the\n//   existing manifest.\n//\n// CRITICAL: vitest runs `globalSetup` in a SEPARATE process from the test\n// workers, so the handoff is via `process.env` (which vitest forwards to\n// workers), NOT an in-memory stash. We reuse the existing\n// `DEVSTACK_MANIFEST_PATH` top-precedence rung (`env.ts`) that the engine\n// already uses when it spawns child processes.\n//\n// This module imports only the CLI-free `api/` surface (`runStack`,\n// `loadDevstackConfig`) so the vitest entrypoint never pulls the CLI/TUI\n// graph into its bundle.\n\nimport { spawn } from 'node:child_process';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { dirname } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nimport { Effect } from 'effect';\n\nimport { loadDevstackConfig } from '../../api/load-config.ts';\nimport { runStack, type RunHandle } from '../../api/run-stack.ts';\nimport { DEFAULT_RUNTIME_ROOT, RECOMMENDED_TEST_STACK, VITEST_ENV_VARS } from './env.ts';\nimport { loadStackContext } from './stack-context.ts';\n\nexport interface DevstackVitestGlobalSetupOptions {\n\t/** Stack name to boot. Default: `DEVSTACK_STACK` if set, else\n\t *  `RECOMMENDED_TEST_STACK` (`'test'`). The booted identity forces\n\t *  this stack, so it coexists with a developer's `main` dev stack. */\n\treadonly stack?: string;\n\t/** Path to the app's `devstack.config.ts`. Default: walk-up from cwd. */\n\treadonly configPath?: string;\n\t/** Runtime root holding `stacks/<stack>/manifest.json`. Default:\n\t *  `DEVSTACK_RUNTIME_ROOT` / `DEVSTACK_STATE_DIR` / `.devstack`. */\n\treadonly runtimeRoot?: string;\n\t/** Reuse an already-running stack instead of booting a fresh one (no\n\t *  boot, no teardown). Default: `false` — also enabled by\n\t *  `DEVSTACK_TEST_REUSE=1`. */\n\treadonly reuse?: boolean;\n\t/** Hard cap (ms) for the stack to reach ready. Default 300_000 (5 min)\n\t *  — accounts for cold supervisor boot under Docker image pulls. */\n\treadonly bootTimeoutMs?: number;\n}\n\n/** Vitest's `globalSetup` contract: a setup function that optionally\n *  returns a teardown function. */\nexport type DevstackVitestGlobalSetup = () => Promise<() => Promise<void>>;\n\nconst DEFAULT_BOOT_TIMEOUT_MS = 300_000;\n\nconst isTruthyEnv = (value: string | undefined): boolean =>\n\tvalue === '1' || value === 'true' || value === 'yes';\n\nconst resolveRuntimeRoot = (\n\topts: DevstackVitestGlobalSetupOptions,\n\tenv: NodeJS.ProcessEnv,\n): string =>\n\topts.runtimeRoot ??\n\t(env[VITEST_ENV_VARS.RUNTIME_ROOT] || env[VITEST_ENV_VARS.RUNTIME_ROOT_LEGACY] || undefined) ??\n\tDEFAULT_RUNTIME_ROOT;\n\nconst resolveStackName = (\n\topts: DevstackVitestGlobalSetupOptions,\n\tenv: NodeJS.ProcessEnv,\n): string => {\n\tconst fromEnv = env[VITEST_ENV_VARS.STACK];\n\treturn opts.stack ?? (fromEnv && fromEnv !== '' ? fromEnv : RECOMMENDED_TEST_STACK);\n};\n\nconst withTimeout = async <A>(promise: Promise<A>, ms: number, label: string): Promise<A> => {\n\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\tconst timeout = new Promise<never>((_, reject) => {\n\t\ttimer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);\n\t});\n\ttry {\n\t\treturn await Promise.race([promise, timeout]);\n\t} finally {\n\t\tif (timer !== undefined) clearTimeout(timer);\n\t}\n};\n\nconst safeStop = async (handle: RunHandle): Promise<void> => {\n\ttry {\n\t\tawait Effect.runPromise(handle.stop);\n\t} catch {\n\t\t// best-effort — fall through to awaitShutdown\n\t}\n\ttry {\n\t\tawait Effect.runPromise(handle.awaitShutdown);\n\t} catch {\n\t\t// supervisor may have already exited; nothing more to do\n\t}\n};\n\n/** After the in-process supervisor has exited, graceful shutdown only\n *  STOPS the stack's containers (devstack keeps them for warm restarts).\n *  An ephemeral test stack should leave nothing behind, so run the\n *  production `devstack wipe` verb (force-removes containers + networks +\n *  volumes + per-stack on-disk state) for the booted stack. Best-effort:\n *  failure here never fails the test run, and a leftover stopped stack is\n *  force-recreated by the next boot anyway. Skip with `DEVSTACK_TEST_KEEP=1`\n *  to leave the stack up for debugging. */\nconst wipeStack = (stack: string, runtimeRoot: string, cwd: string): Promise<void> =>\n\tnew Promise((resolve) => {\n\t\t// The CLI entry ships beside this module in the built package:\n\t\t// dist/build-integrations/vitest/global-setup.mjs → dist/cli/main.mjs.\n\t\tconst cliEntry = fileURLToPath(new URL('../../cli/main.mjs', import.meta.url));\n\t\tif (!existsSync(cliEntry)) {\n\t\t\tresolve();\n\t\t\treturn;\n\t\t}\n\t\tconst child = spawn(process.execPath, [cliEntry, 'wipe', '--yes'], {\n\t\t\tcwd,\n\t\t\tenv: { ...process.env, DEVSTACK_STACK: stack, DEVSTACK_RUNTIME_ROOT: runtimeRoot },\n\t\t\tstdio: 'ignore',\n\t\t});\n\t\tchild.unref();\n\t\tconst done = () => resolve();\n\t\tchild.on('error', done);\n\t\tchild.on('exit', done);\n\t\tconst timer = setTimeout(() => {\n\t\t\tchild.kill();\n\t\t\tresolve();\n\t\t}, 120_000);\n\t\ttimer.unref?.();\n\t});\n\n/** Best-effort, sync read of the booted stack's `codegen.idsFile` from its\n *  manifest. The generated `config-runtime.ts` resolver reads the injected\n *  `__DEVSTACK_IDS__` Vite `define`, but under vitest the Vite config (and\n *  thus that define) is evaluated BEFORE this `globalSetup` boots the stack,\n *  so the define bakes to `null`. The resolver's Node-only fallback reads\n *  `process.env.DEVSTACK_IDS_FILE` at id-access time instead — we point it at\n *  the freshly-booted stack's live id-config file here. Mirrors the Vite\n *  plugin's `readCodegenField`; degrades to `null` on any miss. */\nconst readIdsFileFromManifest = (manifestPath: string): string | null => {\n\ttry {\n\t\tif (!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 value = (codegen as Record<string, unknown>).idsFile;\n\t\treturn typeof value === 'string' && value.length > 0 ? value : null;\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n/** Publish the env handoff vitest forwards to test workers, so per-file\n *  `getStackContext()` resolves the stack this setup booted/attached, and the\n *  generated `config-runtime.ts` resolver can read the live ids\n *  (`DEVSTACK_IDS_FILE` — its Node fallback when the Vite `define` is null). */\nconst publishHandoff = (stack: string, runtimeRoot: string, manifestPath: string): void => {\n\tprocess.env[VITEST_ENV_VARS.STACK] = stack;\n\tprocess.env[VITEST_ENV_VARS.RUNTIME_ROOT] = runtimeRoot;\n\tprocess.env[VITEST_ENV_VARS.MANIFEST_PATH] = manifestPath;\n\tconst idsFile = readIdsFileFromManifest(manifestPath);\n\tif (idsFile !== null) process.env.DEVSTACK_IDS_FILE = idsFile;\n};\n\n/**\n * Build a vitest `globalSetup` that boots (or reuses) a dedicated test\n * stack. Wire it via `devstackVitestTestConfig({ autoBoot: true })`, or\n * reference the module path directly in `test.globalSetup`.\n */\nexport const devstackVitestGlobalSetup =\n\t(opts: DevstackVitestGlobalSetupOptions = {}): DevstackVitestGlobalSetup =>\n\tasync () => {\n\t\tconst env = process.env;\n\t\tconst stack = resolveStackName(opts, env);\n\t\tconst runtimeRoot = resolveRuntimeRoot(opts, env);\n\t\tconst reuse = opts.reuse ?? isTruthyEnv(env.DEVSTACK_TEST_REUSE);\n\n\t\t// Reuse path: attach to an already-running stack. No boot, no teardown.\n\t\tif (reuse) {\n\t\t\tconst ctx = loadStackContext({ stack, runtimeRoot, required: true });\n\t\t\t// `required: true` throws VitestManifestNotFoundError on miss.\n\t\t\tpublishHandoff(stack, runtimeRoot, ctx!.manifestPath);\n\t\t\treturn async () => {};\n\t\t}\n\n\t\t// Fresh boot (default). Load the app's stack the same way the CLI does.\n\t\tconst loaded = await Effect.runPromise(loadDevstackConfig(opts.configPath)).catch((cause) => {\n\t\t\tthrow new Error(\n\t\t\t\t`devstack autoBoot: failed to load devstack config — ${cause instanceof Error ? cause.message : String(cause)}`,\n\t\t\t\t{ cause },\n\t\t\t);\n\t\t});\n\n\t\tconst handle = runStack(loaded.stack, {\n\t\t\tidentity: { stack },\n\t\t\tappRoot: dirname(loaded.resolvedConfigPath),\n\t\t\truntimeRoot,\n\t\t\t...(loaded.engine.options.codegen !== undefined\n\t\t\t\t? { codegen: loaded.engine.options.codegen }\n\t\t\t\t: {}),\n\t\t});\n\n\t\ttry {\n\t\t\tawait withTimeout(\n\t\t\t\tEffect.runPromise(handle.start),\n\t\t\t\topts.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS,\n\t\t\t\t`devstack autoBoot: '${stack}' stack boot`,\n\t\t\t);\n\t\t} catch (cause) {\n\t\t\tawait safeStop(handle);\n\t\t\tthrow new Error(\n\t\t\t\t`devstack autoBoot: failed to boot the '${stack}' stack. ` +\n\t\t\t\t\t`If a '${stack}' stack is already running, stop it with \\`devstack down ${stack}\\` ` +\n\t\t\t\t\t`or set DEVSTACK_TEST_REUSE=1 to run tests against it. ` +\n\t\t\t\t\t`Cause: ${cause instanceof Error ? cause.message : String(cause)}`,\n\t\t\t\t{ cause },\n\t\t\t);\n\t\t}\n\n\t\t// Resolve the freshly-written manifest the workers will read.\n\t\tconst ctx = loadStackContext({\n\t\t\tcwd: dirname(loaded.resolvedConfigPath),\n\t\t\tstack,\n\t\t\truntimeRoot,\n\t\t\trequired: true,\n\t\t});\n\t\tpublishHandoff(stack, runtimeRoot, ctx!.manifestPath);\n\n\t\tconst keep = isTruthyEnv(env.DEVSTACK_TEST_KEEP);\n\t\treturn async () => {\n\t\t\tawait safeStop(handle);\n\t\t\tif (!keep) {\n\t\t\t\tawait wipeStack(stack, runtimeRoot, dirname(loaded.resolvedConfigPath));\n\t\t\t}\n\t\t};\n\t};\n\n/** Default export = a ready-to-use vitest `globalSetup`. This is what\n *  `test.globalSetup: '@mysten-incubation/devstack/vitest/global-setup'`\n *  resolves to. */\nexport default devstackVitestGlobalSetup();\n"],"mappings":";;;;;;;;;;AAqEA,MAAM,0BAA0B;AAEhC,MAAM,eAAe,UACpB,UAAU,OAAO,UAAU,UAAU,UAAU;AAEhD,MAAM,sBACL,MACA,QAEA,KAAK,gBACJ,IAAI,gBAAgB,iBAAiB,IAAI,gBAAgB,wBAAwB,KAAA,MAAA;AAGnF,MAAM,oBACL,MACA,QACY;CACZ,MAAM,UAAU,IAAI,gBAAgB;CACpC,OAAO,KAAK,UAAU,WAAW,YAAY,KAAK,UAAA;AACnD;AAEA,MAAM,cAAc,OAAU,SAAqB,IAAY,UAA8B;CAC5F,IAAI;CACJ,MAAM,UAAU,IAAI,SAAgB,GAAG,WAAW;EACjD,QAAQ,iBAAiB,uBAAO,IAAI,MAAM,GAAG,MAAM,mBAAmB,GAAG,GAAG,CAAC,GAAG,EAAE;CACnF,CAAC;CACD,IAAI;EACH,OAAO,MAAM,QAAQ,KAAK,CAAC,SAAS,OAAO,CAAC;CAC7C,UAAU;EACT,IAAI,UAAU,KAAA,GAAW,aAAa,KAAK;CAC5C;AACD;AAEA,MAAM,WAAW,OAAO,WAAqC;CAC5D,IAAI;EACH,MAAM,OAAO,WAAW,OAAO,IAAI;CACpC,QAAQ,CAER;CACA,IAAI;EACH,MAAM,OAAO,WAAW,OAAO,aAAa;CAC7C,QAAQ,CAER;AACD;;;;;;;;;AAUA,MAAM,aAAa,OAAe,aAAqB,QACtD,IAAI,SAAS,YAAY;CAGxB,MAAM,WAAW,cAAc,IAAI,IAAI,sBAAsB,OAAO,KAAK,GAAG,CAAC;CAC7E,IAAI,CAAC,WAAW,QAAQ,GAAG;EAC1B,QAAQ;EACR;CACD;CACA,MAAM,QAAQ,MAAM,QAAQ,UAAU;EAAC;EAAU;EAAQ;CAAO,GAAG;EAClE;EACA,KAAK;GAAE,GAAG,QAAQ;GAAK,gBAAgB;GAAO,uBAAuB;EAAY;EACjF,OAAO;CACR,CAAC;CACD,MAAM,MAAM;CACZ,MAAM,aAAa,QAAQ;CAC3B,MAAM,GAAG,SAAS,IAAI;CACtB,MAAM,GAAG,QAAQ,IAAI;CAKrB,iBAJ+B;EAC9B,MAAM,KAAK;EACX,QAAQ;CACT,GAAG,IACC,CAAC,CAAC,QAAQ;AACf,CAAC;;;;;;;;;AAUF,MAAM,2BAA2B,iBAAwC;CACxE,IAAI;EACH,IAAI,CAAC,WAAW,YAAY,GAAG,OAAO;EACtC,MAAM,SAAkB,KAAK,MAAM,aAAa,cAAc,MAAM,CAAC;EACrE,IAAI,OAAO,WAAW,YAAY,WAAW,MAAM,OAAO;EAC1D,MAAM,UAAW,OAA0C;EAC3D,IAAI,OAAO,YAAY,YAAY,YAAY,MAAM,OAAO;EAC5D,MAAM,QAAS,QAAoC;EACnD,OAAO,OAAO,UAAU,YAAY,MAAM,SAAS,IAAI,QAAQ;CAChE,QAAQ;EACP,OAAO;CACR;AACD;;;;;AAMA,MAAM,kBAAkB,OAAe,aAAqB,iBAA+B;CAC1F,QAAQ,IAAI,gBAAgB,SAAS;CACrC,QAAQ,IAAI,gBAAgB,gBAAgB;CAC5C,QAAQ,IAAI,gBAAgB,iBAAiB;CAC7C,MAAM,UAAU,wBAAwB,YAAY;CACpD,IAAI,YAAY,MAAM,QAAQ,IAAI,oBAAoB;AACvD;;;;;;AAOA,MAAa,6BACX,OAAyC,CAAC,MAC3C,YAAY;CACX,MAAM,MAAM,QAAQ;CACpB,MAAM,QAAQ,iBAAiB,MAAM,GAAG;CACxC,MAAM,cAAc,mBAAmB,MAAM,GAAG;CAIhD,IAHc,KAAK,SAAS,YAAY,IAAI,mBAAmB,GAGpD;EAGV,eAAe,OAAO,aAFV,iBAAiB;GAAE;GAAO;GAAa,UAAU;EAAK,CAE7B,CAAC,CAAE,YAAY;EACpD,OAAO,YAAY,CAAC;CACrB;CAGA,MAAM,SAAS,MAAM,OAAO,WAAW,mBAAmB,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,UAAU;EAC5F,MAAM,IAAI,MACT,uDAAuD,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,KAC5G,EAAE,MAAM,CACT;CACD,CAAC;CAED,MAAM,SAAS,SAAS,OAAO,OAAO;EACrC,UAAU,EAAE,MAAM;EAClB,SAAS,QAAQ,OAAO,kBAAkB;EAC1C;EACA,GAAI,OAAO,OAAO,QAAQ,YAAY,KAAA,IACnC,EAAE,SAAS,OAAO,OAAO,QAAQ,QAAQ,IACzC,CAAC;CACL,CAAC;CAED,IAAI;EACH,MAAM,YACL,OAAO,WAAW,OAAO,KAAK,GAC9B,KAAK,iBAAiB,yBACtB,uBAAuB,MAAM,aAC9B;CACD,SAAS,OAAO;EACf,MAAM,SAAS,MAAM;EACrB,MAAM,IAAI,MACT,0CAA0C,MAAM,iBACtC,MAAM,2DAA2D,MAAM,kEAEtE,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,KAChE,EAAE,MAAM,CACT;CACD;CASA,eAAe,OAAO,aANV,iBAAiB;EAC5B,KAAK,QAAQ,OAAO,kBAAkB;EACtC;EACA;EACA,UAAU;CACX,CACqC,CAAC,CAAE,YAAY;CAEpD,MAAM,OAAO,YAAY,IAAI,kBAAkB;CAC/C,OAAO,YAAY;EAClB,MAAM,SAAS,MAAM;EACrB,IAAI,CAAC,MACJ,MAAM,UAAU,OAAO,aAAa,QAAQ,OAAO,kBAAkB,CAAC;CAExE;AACD;;;;AAKD,IAAA,uBAAe,0BAA0B"}

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

@@ -1,6 +1,7 @@
+import { DevstackVitestGlobalSetup, DevstackVitestGlobalSetupOptions, devstackVitestGlobalSetup } from "./global-setup.mjs";
 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 { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, ResolveVitestEnvOptions, ResolvedVitestEnv, VITEST_ENV_VARS, VitestEnvVarName, resolveVitestEnv } from "./env.mjs";
 import { VitestIntegrationError, VitestManifestNotFoundError, VitestManifestShapeError, VitestManifestVersionMismatchError, 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, VitestManifestVersionMismatchError, VitestSetupPreconditionError, devstackVitestServerConfig, devstackVitestTestConfig, getStackContext, loadStackContext, resolveVitestEnv, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup };
+export { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, type DevstackVitestGlobalSetup, type DevstackVitestGlobalSetupOptions, type DevstackVitestTestConfigOptions, type LoadStackContextOptions, RECOMMENDED_TEST_STACK, type ResolveVitestEnvOptions, type ResolvedVitestEnv, type StackContext, type TestSetupOptions, VITEST_ENV_VARS, type VitestEnvVarName, type VitestIntegrationError, type VitestLifecycleHooks, VitestManifestNotFoundError, VitestManifestShapeError, VitestManifestVersionMismatchError, VitestSetupPreconditionError, devstackVitestGlobalSetup, devstackVitestServerConfig, devstackVitestTestConfig, getStackContext, loadStackContext, resolveVitestEnv, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup };

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

@@ -1,6 +1,7 @@
 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, VitestManifestVersionMismatchError, VitestSetupPreconditionError } from "./errors.mjs";
 import { loadStackContext } from "./stack-context.mjs";
-import { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, VITEST_ENV_VARS, resolveVitestEnv } from "./env.mjs";
+import { devstackVitestGlobalSetup } from "./global-setup.mjs";
 import { getStackContext, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup } from "./setup.mjs";
-export { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, VITEST_ENV_VARS, VitestManifestNotFoundError, VitestManifestShapeError, VitestManifestVersionMismatchError, VitestSetupPreconditionError, devstackVitestServerConfig, devstackVitestTestConfig, getStackContext, loadStackContext, resolveVitestEnv, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup };
+export { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, VITEST_ENV_VARS, VitestManifestNotFoundError, VitestManifestShapeError, VitestManifestVersionMismatchError, VitestSetupPreconditionError, devstackVitestGlobalSetup, devstackVitestServerConfig, devstackVitestTestConfig, getStackContext, loadStackContext, resolveVitestEnv, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup };

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

@@ -1,6 +1,6 @@
+import { RECOMMENDED_TEST_STACK, VITEST_ENV_VARS, resolveVitestEnv } from "./env.mjs";
 import { VitestSetupPreconditionError } from "./errors.mjs";
 import { loadStackContext } from "./stack-context.mjs";
-import { RECOMMENDED_TEST_STACK, VITEST_ENV_VARS, resolveVitestEnv } from "./env.mjs";
 //#region src/build-integrations/vitest/setup.ts
 let captured;
 /** Return the StackContext captured by `runDevstackBeforeAll`. Returns
@@ -16,7 +16,7 @@ const clearStackContext = () => {
 *  it into Vitest's hooks directly OR call it inline from a
 *  setup-file. */
 const runDevstackBeforeAll = (options = {}) => {
-	const resolved = resolveVitestEnv(options.env ?? process.env);
+	const resolved = resolveVitestEnv(options.env ?? process.env, { cwd: options.cwd ?? process.cwd() });
 	if (!options.silent && !resolved.stackWasExplicit) (options.writeAdvisory ?? ((line) => void process.stderr.write(`${line}\n`)))(`[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,

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

@@ -1 +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//\n// NOTE: this module must NOT import `vitest` at the top level. The\n// public `./vitest` barrel re-exports this file, and the build is\n// unbundled — so a bare `import … from 'vitest'` here would land a\n// runtime `import { … } from 'vitest'` at barrel module-init. `vitest`\n// is an OPTIONAL peer (declared in package.json's\n// `peerDependenciesMeta`), and the documented way to consume the config\n// helpers is from a `vitest.config.ts`; a consumer who legitimately\n// lacks `vitest` and imports the barrel would otherwise get a hard\n// `Cannot find package 'vitest'` at barrel evaluation. The\n// `VitestLifecycleHooks` shape below is matched STRUCTURALLY for the\n// same reason.\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 per-worker handle\n// -----------------------------------------------------------------------------\n//\n// Vitest workers reuse a single module-level binding across the test\n// files they run, and run those files strictly sequentially\n// (`beforeAll → its → afterAll`, then the next file). The isolation\n// guarantee that matters is therefore narrow: a file's fixture must not\n// bleed into a LATER file that forgot `useDevstackTestSetup`. That is\n// satisfied by `runDevstackAfterAll` clearing the binding at end-of-file\n// — no per-test-path keying is needed (and keying would require reading\n// `expect.getState().testPath`, forcing the forbidden top-level `vitest`\n// import; see the module header). A single binding cleared on `afterAll`\n// is both sufficient and keeps the barrel's transitive graph free of any\n// runtime `vitest` import.\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 a stderr\n\t *  writer (`process.stderr.write(line + '\\n')`) — matches the\n\t *  build-integration surface IO discipline (no `console.*` in\n\t *  production paths). 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 =\n\t\t\toptions.writeAdvisory ?? ((line: string) => void process.stderr.write(`${line}\\n`));\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":";;;;AAwEA,IAAI;;;;AAKJ,MAAa,wBAAkD;;;AAI/D,MAAa,0BAAgC;AAC5C,YAAW,KAAA;;;;;AA4BZ,MAAa,wBAAwB,UAA4B,EAAE,KAAW;CAE7E,MAAM,WAAW,iBADL,QAAQ,OAAQ,QAAQ,IACE;AAEtC,KAAI,CAAC,QAAQ,UAAU,CAAC,SAAS,iBAGhC,EADC,QAAQ,mBAAmB,SAAiB,KAAK,QAAQ,OAAO,MAAM,GAAG,KAAK,IAAI,GAElF,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"}
+{"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): this per-file setup\n// module does NOT boot devstack. Booting is either the test file's job\n// (via `@effect/vitest`'s `it.layer(stack.layer)`) or, for `*.e2e`\n// suites, the separate `global-setup.ts` boot seam wired by\n// `devstackVitestTestConfig({ autoBoot: true })`. This module stays a\n// pure reader either way.\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 (or,\n// under `autoBoot`, the `global-setup.ts` teardown). This per-file setup\n// module is a pure reader.\n//\n// NOTE: this module must NOT import `vitest` at the top level. The\n// public `./vitest` barrel re-exports this file, and the build is\n// unbundled — so a bare `import … from 'vitest'` here would land a\n// runtime `import { … } from 'vitest'` at barrel module-init. `vitest`\n// is an OPTIONAL peer (declared in package.json's\n// `peerDependenciesMeta`), and the documented way to consume the config\n// helpers is from a `vitest.config.ts`; a consumer who legitimately\n// lacks `vitest` and imports the barrel would otherwise get a hard\n// `Cannot find package 'vitest'` at barrel evaluation. The\n// `VitestLifecycleHooks` shape below is matched STRUCTURALLY for the\n// same reason.\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 per-worker handle\n// -----------------------------------------------------------------------------\n//\n// Vitest workers reuse a single module-level binding across the test\n// files they run, and run those files strictly sequentially\n// (`beforeAll → its → afterAll`, then the next file). The isolation\n// guarantee that matters is therefore narrow: a file's fixture must not\n// bleed into a LATER file that forgot `useDevstackTestSetup`. That is\n// satisfied by `runDevstackAfterAll` clearing the binding at end-of-file\n// — no per-test-path keying is needed (and keying would require reading\n// `expect.getState().testPath`, forcing the forbidden top-level `vitest`\n// import; see the module header). A single binding cleared on `afterAll`\n// is both sufficient and keeps the barrel's transitive graph free of any\n// runtime `vitest` import.\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 a stderr\n\t *  writer (`process.stderr.write(line + '\\n')`) — matches the\n\t *  build-integration surface IO discipline (no `console.*` in\n\t *  production paths). 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\t// Thread the loader's walk-up start so the advisory below names the\n\t// stack `loadStackContext` will actually read (package-name rung).\n\tconst resolved = resolveVitestEnv(env, { cwd: options.cwd ?? process.cwd() });\n\n\tif (!options.silent && !resolved.stackWasExplicit) {\n\t\tconst write =\n\t\t\toptions.writeAdvisory ?? ((line: string) => void process.stderr.write(`${line}\\n`));\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":";;;;AA4EA,IAAI;;;;AAKJ,MAAa,wBAAkD;;;AAI/D,MAAa,0BAAgC;CAC5C,WAAW,KAAA;AACZ;;;;AA2BA,MAAa,wBAAwB,UAA4B,CAAC,MAAY;CAI7E,MAAM,WAAW,iBAHL,QAAQ,OAAQ,QAAQ,KAGG,EAAE,KAAK,QAAQ,OAAO,QAAQ,IAAI,EAAE,CAAC;CAE5E,IAAI,CAAC,QAAQ,UAAU,CAAC,SAAS,kBAGhC,CADC,QAAQ,mBAAmB,SAAiB,KAAK,QAAQ,OAAO,MAAM,GAAG,KAAK,GAAG,GAAA,CAEjF,qBAAqB,gBAAgB,MAAM,kCAAkC,SAAS,MAAM,eACpF,gBAAgB,MAAM,GAAG,uBAAuB,2DACzD;CAGD,MAAM,MAAM,iBAAiB;EAC5B,GAAG;EACH,UAAU,QAAQ,oBAAoB;CACvC,CAAC;CAED,IAAI,QAAQ,oBAAoB,QAAQ,QAAQ,KAAA,GAI/C,MAAM,IAAI,6BAA6B;EACtC,SAAS;EACT,MAAM;CACP,CAAC;CAGF,WAAW;AACZ;;;;AAKA,MAAa,4BAAkC;CAC9C,kBAAkB;AACnB;;;;;;;;;;;;;AA2BA,MAAa,wBACZ,OACA,UAA4B,CAAC,MACnB;CACV,MAAM,gBAAgB,qBAAqB,OAAO,CAAC;CACnD,MAAM,eAAe,oBAAoB,CAAC;AAC3C"}

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

@@ -21,10 +21,12 @@ interface StackContext {
 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'`. */
+  /** Stack name override. Defaults to `process.env.DEVSTACK_STACK`,
+   *  then the nearest package.json `name` above `cwd` (matching the
+   *  CLI's `resolveStackName` inference), with a final fallback to
+   *  `'main'`. */
   readonly stack?: string;
-  /** Runtime root override (legacy `.devstack` directory). Defaults
+  /** Runtime root override. Defaults
    *  to `process.env.DEVSTACK_RUNTIME_ROOT` /
    *  `process.env.DEVSTACK_STATE_DIR` with a final fallback to
    *  `'.devstack'`. */

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

@@ -35,7 +35,8 @@ const loadStackContext = (opts = {}) => {
 	const env = opts.env ?? process.env;
 	const { stack, stateDir: runtimeRoot } = resolveDiscoveryEnv(env, {
 		...opts.stack !== void 0 ? { stack: opts.stack } : {},
-		...opts.runtimeRoot !== void 0 ? { stateDir: opts.runtimeRoot } : {}
+		...opts.runtimeRoot !== void 0 ? { stateDir: opts.runtimeRoot } : {},
+		cwd: opts.cwd ?? process.cwd()
 	});
 	try {
 		return project(readStackContext({
@@ -67,7 +68,7 @@ const loadStackContext = (opts = {}) => {
 			if (err.phase === "version") throw new VitestManifestVersionMismatchError({
 				path: err.path,
 				message: err.message,
-				recovery: "upgrade @mysten-incubation/devstack to a build that matches the supervisor's manifestVersion, or run `devstack up` to regenerate the manifest with this consumer's version.",
+				recovery: `run \`devstack up\` to regenerate the manifest.`,
 				cause: err
 			});
 			throw new VitestManifestShapeError({

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

@@ -1 +1 @@
-{"version":3,"file":"stack-context.mjs","names":["readStackContextRuntime"],"sources":["../../../src/build-integrations/vitest/stack-context.ts"],"sourcesContent":["// Stack-context loader for the vitest integration — thin wrapper\n// over `runtime/readStackContext`.\n//\n// The vitest preset is a passive reader of the supervisor's manifest.\n// Discovery, decode, and version-gate live in `runtime/`; this module\n// only:\n//   - resolves the vitest-flavored env contract (`DEVSTACK_RUNTIME_ROOT`\n//     plus legacy `DEVSTACK_STATE_DIR` alias),\n//   - exposes the manifest plus `endpoint(name)` / `displayEndpoint(name)`\n//     convenience accessors test bodies use,\n//   - re-shapes the canonical error tags into the vitest-flavored union\n//     (`VitestManifestNotFoundError` / `VitestManifestShapeError`) so\n//     caller `catchTag` flows stay stable.\n\nimport {\n\tmanifestEnvelopeFromStackContext,\n\tManifestDiscoveryError,\n\tManifestShapeError,\n\treadStackContext as readStackContextRuntime,\n\tresolveBuiltInEndpointAlias,\n\tresolveDiscoveryEnv,\n\ttype ManifestEnvelope,\n\ttype StackContext as RuntimeStackContext,\n} from '../runtime/index.ts';\nimport {\n\tVitestManifestNotFoundError,\n\tVitestManifestShapeError,\n\tVitestManifestVersionMismatchError,\n} from './errors.ts';\n\n/** Read-only projection over the live manifest, scoped to the vitest\n *  surface's needs. The full envelope is reconstructed (`manifest`)\n *  for the test-side helpers that compare deep shapes; the convenience\n *  accessors cover the common case. */\nexport interface StackContext {\n\t/** Absolute path of the manifest file the projection came from. */\n\treadonly manifestPath: string;\n\t/** Reconstructed envelope — same shape downstream consumers had\n\t *  pre-consolidation. */\n\treadonly manifest: ManifestEnvelope;\n\t/** Identity tuple shortcut. */\n\treadonly identity: ManifestEnvelope['identity'];\n\t/** Flat endpoint lookup — returns the URL string or `undefined`. */\n\treadonly endpoint: (name: string) => string | undefined;\n\t/** Display URL variant — falls back to `url` when `displayUrl` is\n\t *  null (the routed-vs-direct distinction the router decides). */\n\treadonly displayEndpoint: (name: string) => string | undefined;\n}\n\nexport interface LoadStackContextOptions {\n\t/** Starting directory for the walk-up. Defaults to `process.cwd()`. */\n\treadonly cwd?: string;\n\t/** Stack name override. Defaults to `process.env.DEVSTACK_STACK`\n\t *  with a final fallback to `'main'`. */\n\treadonly stack?: string;\n\t/** Runtime root override (legacy `.devstack` directory). Defaults\n\t *  to `process.env.DEVSTACK_RUNTIME_ROOT` /\n\t *  `process.env.DEVSTACK_STATE_DIR` with a final fallback to\n\t *  `'.devstack'`. */\n\treadonly runtimeRoot?: string;\n\t/** Explicit absolute manifest path. Bypasses the walk-up but is\n\t *  still validated to exist. Lower precedence than the\n\t *  `DEVSTACK_MANIFEST_PATH` env var. */\n\treadonly manifestPath?: string;\n\t/** Env bag for the resolver. Defaults to `process.env`. Tests pass\n\t *  a fixture. */\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n\t/** When `true`, throw `VitestManifestNotFoundError` on miss instead\n\t *  of returning `undefined`. */\n\treadonly required?: boolean;\n}\n\nconst project = (ctx: RuntimeStackContext): StackContext => {\n\tconst envelope: ManifestEnvelope = manifestEnvelopeFromStackContext(ctx);\n\t// Alias-resolve the user-typed name BEFORE the registry lookup so\n\t// `endpoint('app')` resolves to whatever canonical key the substrate\n\t// emits (`'dev'` today). Mirrors the playwright surface\n\t// (`playwrightEndpointNameFor` in `playwright/stack-context.ts`) so\n\t// both build integrations share one alias table from\n\t// `runtime/conventional-routes.ts`. Without this, the `endpoint(name)`\n\t// accessor silently returns `undefined` for legit aliases the\n\t// playwright fixture happily accepts.\n\tconst lookup = (nameOrAlias: string) =>\n\t\tctx.endpoints.byName(resolveBuiltInEndpointAlias(nameOrAlias));\n\treturn {\n\t\tmanifestPath: ctx.manifestPath,\n\t\tmanifest: envelope,\n\t\tidentity: envelope.identity,\n\t\tendpoint: (name) => lookup(name)?.url,\n\t\tdisplayEndpoint: (name) => {\n\t\t\tconst e = lookup(name);\n\t\t\tif (e === undefined) return undefined;\n\t\t\treturn e.displayUrl ?? e.url;\n\t\t},\n\t};\n};\n\n/**\n * Read the on-disk manifest, decode against the envelope schema, and\n * return a projection. Returns `undefined` on miss; pass\n * `{ required: true }` to throw `VitestManifestNotFoundError`.\n *\n * Precedence ladder (highest → lowest):\n *   1. `env.DEVSTACK_MANIFEST_PATH`\n *   2. `opts.manifestPath`\n *   3. walk-up from `opts.cwd` looking for\n *      `<runtimeRoot>/stacks/<stack>/manifest.json`\n */\nexport const loadStackContext = (opts: LoadStackContextOptions = {}): StackContext | undefined => {\n\tconst env = opts.env ?? (process.env as Readonly<Record<string, string | undefined>>);\n\t// `runtimeRoot` is the vitest-flavored name for the shared resolver's\n\t// `stateDir` rung; the ladder (option > DEVSTACK_RUNTIME_ROOT >\n\t// DEVSTACK_STATE_DIR > '.devstack') lives in `resolveDiscoveryEnv`.\n\tconst { stack, stateDir: runtimeRoot } = resolveDiscoveryEnv(env, {\n\t\t...(opts.stack !== undefined ? { stack: opts.stack } : {}),\n\t\t...(opts.runtimeRoot !== undefined ? { stateDir: opts.runtimeRoot } : {}),\n\t});\n\n\ttry {\n\t\tconst ctx = readStackContextRuntime({\n\t\t\t...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),\n\t\t\tstack,\n\t\t\tstateDir: runtimeRoot,\n\t\t\tenv,\n\t\t\t...(opts.manifestPath !== undefined ? { manifestPath: opts.manifestPath } : {}),\n\t\t});\n\t\treturn project(ctx);\n\t} catch (err) {\n\t\tif (err instanceof ManifestDiscoveryError) {\n\t\t\t// `env-missing` / `override-missing` surface regardless of\n\t\t\t// `required` — the user explicitly pointed at a file that\n\t\t\t// doesn't exist; silently returning `undefined` would\n\t\t\t// quietly fall back to cold-start defaults and hide the typo.\n\t\t\t// `required: false` only suppresses the walk-up-not-found\n\t\t\t// path (`phase: 'walk-up' | 'required-missing'`).\n\t\t\tif (err.phase === 'env-missing' || err.phase === 'override-missing') {\n\t\t\t\tthrow new VitestManifestNotFoundError({\n\t\t\t\t\tmessage: err.message,\n\t\t\t\t\tsearchedFrom: opts.cwd ?? process.cwd(),\n\t\t\t\t\tstack,\n\t\t\t\t\tstateDir: runtimeRoot,\n\t\t\t\t\trecovery: `run \\`devstack up\\` (or unset DEVSTACK_MANIFEST_PATH / pass an existing manifestPath)`,\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (opts.required === true) {\n\t\t\t\tthrow new VitestManifestNotFoundError({\n\t\t\t\t\tmessage: `no devstack manifest found for stack '${stack}' under '${runtimeRoot}'`,\n\t\t\t\t\tsearchedFrom: opts.cwd ?? process.cwd(),\n\t\t\t\t\tstack,\n\t\t\t\t\tstateDir: runtimeRoot,\n\t\t\t\t\trecovery: `run \\`devstack up\\` (or set DEVSTACK_MANIFEST_PATH to an existing file)`,\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn undefined;\n\t\t}\n\t\tif (err instanceof ManifestShapeError) {\n\t\t\t// The runtime tags decode-failure, structural drift, and\n\t\t\t// version-mismatch as `phase: 'parse' | 'shape' | 'version'`.\n\t\t\t// We surface them as TWO distinct error tags so consumers can\n\t\t\t// `catchTag` independently — the recovery actions diverge:\n\t\t\t//\n\t\t\t//   - parse/shape → regenerate the manifest (the file is wrong)\n\t\t\t//   - version     → upgrade the consumer dependency (your\n\t\t\t//                   build and the supervisor are out of sync)\n\t\t\tif (err.phase === 'version') {\n\t\t\t\tthrow new VitestManifestVersionMismatchError({\n\t\t\t\t\tpath: err.path,\n\t\t\t\t\tmessage: err.message,\n\t\t\t\t\trecovery:\n\t\t\t\t\t\t`upgrade @mysten-incubation/devstack to a build that matches the ` +\n\t\t\t\t\t\t`supervisor's manifestVersion, or run \\`devstack up\\` to regenerate ` +\n\t\t\t\t\t\t`the manifest with this consumer's version.`,\n\t\t\t\t\tcause: err,\n\t\t\t\t});\n\t\t\t}\n\t\t\tthrow new VitestManifestShapeError({\n\t\t\t\tphase: err.phase,\n\t\t\t\tpath: err.path,\n\t\t\t\tmessage: err.message,\n\t\t\t\trecovery:\n\t\t\t\t\terr.phase === 'parse'\n\t\t\t\t\t\t? `rm ${err.path} && devstack apply  # regenerate from the registries`\n\t\t\t\t\t\t: `rm -rf <runtimeRoot>/stacks/<stack>/manifest.json && devstack apply  # regenerate`,\n\t\t\t\tcause: err,\n\t\t\t});\n\t\t}\n\t\tthrow err;\n\t}\n};\n"],"mappings":";;;;;;;AAwEA,MAAM,WAAW,QAA2C;CAC3D,MAAM,WAA6B,iCAAiC,IAAI;CASxE,MAAM,UAAU,gBACf,IAAI,UAAU,OAAO,4BAA4B,YAAY,CAAC;AAC/D,QAAO;EACN,cAAc,IAAI;EAClB,UAAU;EACV,UAAU,SAAS;EACnB,WAAW,SAAS,OAAO,KAAK,EAAE;EAClC,kBAAkB,SAAS;GAC1B,MAAM,IAAI,OAAO,KAAK;AACtB,OAAI,MAAM,KAAA,EAAW,QAAO,KAAA;AAC5B,UAAO,EAAE,cAAc,EAAE;;EAE1B;;;;;;;;;;;;;AAcF,MAAa,oBAAoB,OAAgC,EAAE,KAA+B;CACjG,MAAM,MAAM,KAAK,OAAQ,QAAQ;CAIjC,MAAM,EAAE,OAAO,UAAU,gBAAgB,oBAAoB,KAAK;EACjE,GAAI,KAAK,UAAU,KAAA,IAAY,EAAE,OAAO,KAAK,OAAO,GAAG,EAAE;EACzD,GAAI,KAAK,gBAAgB,KAAA,IAAY,EAAE,UAAU,KAAK,aAAa,GAAG,EAAE;EACxE,CAAC;AAEF,KAAI;AAQH,SAAO,QAPKA,iBAAwB;GACnC,GAAI,KAAK,QAAQ,KAAA,IAAY,EAAE,KAAK,KAAK,KAAK,GAAG,EAAE;GACnD;GACA,UAAU;GACV;GACA,GAAI,KAAK,iBAAiB,KAAA,IAAY,EAAE,cAAc,KAAK,cAAc,GAAG,EAAE;GAC9E,CACiB,CAAC;UACX,KAAK;AACb,MAAI,eAAe,wBAAwB;AAO1C,OAAI,IAAI,UAAU,iBAAiB,IAAI,UAAU,mBAChD,OAAM,IAAI,4BAA4B;IACrC,SAAS,IAAI;IACb,cAAc,KAAK,OAAO,QAAQ,KAAK;IACvC;IACA,UAAU;IACV,UAAU;IACV,CAAC;AAEH,OAAI,KAAK,aAAa,KACrB,OAAM,IAAI,4BAA4B;IACrC,SAAS,yCAAyC,MAAM,WAAW,YAAY;IAC/E,cAAc,KAAK,OAAO,QAAQ,KAAK;IACvC;IACA,UAAU;IACV,UAAU;IACV,CAAC;AAEH;;AAED,MAAI,eAAe,oBAAoB;AAStC,OAAI,IAAI,UAAU,UACjB,OAAM,IAAI,mCAAmC;IAC5C,MAAM,IAAI;IACV,SAAS,IAAI;IACb,UACC;IAGD,OAAO;IACP,CAAC;AAEH,SAAM,IAAI,yBAAyB;IAClC,OAAO,IAAI;IACX,MAAM,IAAI;IACV,SAAS,IAAI;IACb,UACC,IAAI,UAAU,UACX,MAAM,IAAI,KAAK,wDACf;IACJ,OAAO;IACP,CAAC;;AAEH,QAAM"}
+{"version":3,"file":"stack-context.mjs","names":["readStackContextRuntime"],"sources":["../../../src/build-integrations/vitest/stack-context.ts"],"sourcesContent":["// Stack-context loader for the vitest integration — thin wrapper\n// over `runtime/readStackContext`.\n//\n// This module is a passive reader of the supervisor's manifest. (Booting\n// a stack for `*.e2e` suites is the separate `global-setup.ts` seam, wired\n// by `devstackVitestTestConfig({ autoBoot: true })`; this reader is\n// unaffected by it.) Discovery, decode, and version-gate live in\n// `runtime/`; this module only:\n//   - resolves the vitest-flavored env contract (`DEVSTACK_RUNTIME_ROOT`\n//     plus `DEVSTACK_STATE_DIR` alias),\n//   - exposes the manifest plus `endpoint(name)` / `displayEndpoint(name)`\n//     convenience accessors test bodies use,\n//   - re-shapes the canonical error tags into the vitest-flavored union\n//     (`VitestManifestNotFoundError` / `VitestManifestShapeError`) so\n//     caller `catchTag` flows stay stable.\n\nimport {\n\tmanifestEnvelopeFromStackContext,\n\tManifestDiscoveryError,\n\tManifestShapeError,\n\treadStackContext as readStackContextRuntime,\n\tresolveBuiltInEndpointAlias,\n\tresolveDiscoveryEnv,\n\ttype ManifestEnvelope,\n\ttype StackContext as RuntimeStackContext,\n} from '../runtime/index.ts';\nimport {\n\tVitestManifestNotFoundError,\n\tVitestManifestShapeError,\n\tVitestManifestVersionMismatchError,\n} from './errors.ts';\n\n/** Read-only projection over the live manifest, scoped to the vitest\n *  surface's needs. The full envelope is reconstructed (`manifest`)\n *  for the test-side helpers that compare deep shapes; the convenience\n *  accessors cover the common case. */\nexport interface StackContext {\n\t/** Absolute path of the manifest file the projection came from. */\n\treadonly manifestPath: string;\n\t/** Reconstructed envelope — same shape downstream consumers had\n\t *  pre-consolidation. */\n\treadonly manifest: ManifestEnvelope;\n\t/** Identity tuple shortcut. */\n\treadonly identity: ManifestEnvelope['identity'];\n\t/** Flat endpoint lookup — returns the URL string or `undefined`. */\n\treadonly endpoint: (name: string) => string | undefined;\n\t/** Display URL variant — falls back to `url` when `displayUrl` is\n\t *  null (the routed-vs-direct distinction the router decides). */\n\treadonly displayEndpoint: (name: string) => string | undefined;\n}\n\nexport interface LoadStackContextOptions {\n\t/** Starting directory for the walk-up. Defaults to `process.cwd()`. */\n\treadonly cwd?: string;\n\t/** Stack name override. Defaults to `process.env.DEVSTACK_STACK`,\n\t *  then the nearest package.json `name` above `cwd` (matching the\n\t *  CLI's `resolveStackName` inference), with a final fallback to\n\t *  `'main'`. */\n\treadonly stack?: string;\n\t/** Runtime root override. Defaults\n\t *  to `process.env.DEVSTACK_RUNTIME_ROOT` /\n\t *  `process.env.DEVSTACK_STATE_DIR` with a final fallback to\n\t *  `'.devstack'`. */\n\treadonly runtimeRoot?: string;\n\t/** Explicit absolute manifest path. Bypasses the walk-up but is\n\t *  still validated to exist. Lower precedence than the\n\t *  `DEVSTACK_MANIFEST_PATH` env var. */\n\treadonly manifestPath?: string;\n\t/** Env bag for the resolver. Defaults to `process.env`. Tests pass\n\t *  a fixture. */\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n\t/** When `true`, throw `VitestManifestNotFoundError` on miss instead\n\t *  of returning `undefined`. */\n\treadonly required?: boolean;\n}\n\nconst project = (ctx: RuntimeStackContext): StackContext => {\n\tconst envelope: ManifestEnvelope = manifestEnvelopeFromStackContext(ctx);\n\t// Alias-resolve the user-typed name BEFORE the registry lookup so\n\t// `endpoint('app')` resolves to whatever canonical key the substrate\n\t// emits (`'dev'` today). Mirrors the playwright surface\n\t// (`playwrightEndpointNameFor` in `playwright/stack-context.ts`) so\n\t// both build integrations share one alias table from\n\t// `runtime/conventional-routes.ts`. Without this, the `endpoint(name)`\n\t// accessor silently returns `undefined` for legit aliases the\n\t// playwright fixture happily accepts.\n\tconst lookup = (nameOrAlias: string) =>\n\t\tctx.endpoints.byName(resolveBuiltInEndpointAlias(nameOrAlias));\n\treturn {\n\t\tmanifestPath: ctx.manifestPath,\n\t\tmanifest: envelope,\n\t\tidentity: envelope.identity,\n\t\tendpoint: (name) => lookup(name)?.url,\n\t\tdisplayEndpoint: (name) => {\n\t\t\tconst e = lookup(name);\n\t\t\tif (e === undefined) return undefined;\n\t\t\treturn e.displayUrl ?? e.url;\n\t\t},\n\t};\n};\n\n/**\n * Read the on-disk manifest, decode against the envelope schema, and\n * return a projection. Returns `undefined` on miss; pass\n * `{ required: true }` to throw `VitestManifestNotFoundError`.\n *\n * Precedence ladder (highest → lowest):\n *   1. `env.DEVSTACK_MANIFEST_PATH`\n *   2. `opts.manifestPath`\n *   3. walk-up from `opts.cwd` looking for\n *      `<runtimeRoot>/stacks/<stack>/manifest.json`\n */\nexport const loadStackContext = (opts: LoadStackContextOptions = {}): StackContext | undefined => {\n\tconst env = opts.env ?? (process.env as Readonly<Record<string, string | undefined>>);\n\t// `runtimeRoot` is the vitest-flavored name for the shared resolver's\n\t// `stateDir` rung; the ladder (option > DEVSTACK_RUNTIME_ROOT >\n\t// DEVSTACK_STATE_DIR > '.devstack') lives in `resolveDiscoveryEnv`.\n\t// The stack rung threads the loader's walk-up start so a bare app's\n\t// package-name-derived stack (the CLI's inference) is found without\n\t// DEVSTACK_STACK being set.\n\tconst { stack, stateDir: runtimeRoot } = resolveDiscoveryEnv(env, {\n\t\t...(opts.stack !== undefined ? { stack: opts.stack } : {}),\n\t\t...(opts.runtimeRoot !== undefined ? { stateDir: opts.runtimeRoot } : {}),\n\t\tcwd: opts.cwd ?? process.cwd(),\n\t});\n\n\ttry {\n\t\tconst ctx = readStackContextRuntime({\n\t\t\t...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),\n\t\t\tstack,\n\t\t\tstateDir: runtimeRoot,\n\t\t\tenv,\n\t\t\t...(opts.manifestPath !== undefined ? { manifestPath: opts.manifestPath } : {}),\n\t\t});\n\t\treturn project(ctx);\n\t} catch (err) {\n\t\tif (err instanceof ManifestDiscoveryError) {\n\t\t\t// `env-missing` / `override-missing` surface regardless of\n\t\t\t// `required` — the user explicitly pointed at a file that\n\t\t\t// doesn't exist; silently returning `undefined` would\n\t\t\t// quietly fall back to cold-start defaults and hide the typo.\n\t\t\t// `required: false` only suppresses the walk-up-not-found\n\t\t\t// path (`phase: 'walk-up' | 'required-missing'`).\n\t\t\tif (err.phase === 'env-missing' || err.phase === 'override-missing') {\n\t\t\t\tthrow new VitestManifestNotFoundError({\n\t\t\t\t\tmessage: err.message,\n\t\t\t\t\tsearchedFrom: opts.cwd ?? process.cwd(),\n\t\t\t\t\tstack,\n\t\t\t\t\tstateDir: runtimeRoot,\n\t\t\t\t\trecovery: `run \\`devstack up\\` (or unset DEVSTACK_MANIFEST_PATH / pass an existing manifestPath)`,\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (opts.required === true) {\n\t\t\t\tthrow new VitestManifestNotFoundError({\n\t\t\t\t\tmessage: `no devstack manifest found for stack '${stack}' under '${runtimeRoot}'`,\n\t\t\t\t\tsearchedFrom: opts.cwd ?? process.cwd(),\n\t\t\t\t\tstack,\n\t\t\t\t\tstateDir: runtimeRoot,\n\t\t\t\t\trecovery: `run \\`devstack up\\` (or set DEVSTACK_MANIFEST_PATH to an existing file)`,\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn undefined;\n\t\t}\n\t\tif (err instanceof ManifestShapeError) {\n\t\t\t// The runtime tags decode-failure, structural drift, and\n\t\t\t// version-mismatch as `phase: 'parse' | 'shape' | 'version'`.\n\t\t\t// We surface them as two distinct error tags so callers can\n\t\t\t// distinguish malformed manifests from version mismatches.\n\t\t\tif (err.phase === 'version') {\n\t\t\t\tthrow new VitestManifestVersionMismatchError({\n\t\t\t\t\tpath: err.path,\n\t\t\t\t\tmessage: err.message,\n\t\t\t\t\trecovery: `run \\`devstack up\\` to regenerate the manifest.`,\n\t\t\t\t\tcause: err,\n\t\t\t\t});\n\t\t\t}\n\t\t\tthrow new VitestManifestShapeError({\n\t\t\t\tphase: err.phase,\n\t\t\t\tpath: err.path,\n\t\t\t\tmessage: err.message,\n\t\t\t\trecovery:\n\t\t\t\t\terr.phase === 'parse'\n\t\t\t\t\t\t? `rm ${err.path} && devstack apply  # regenerate from the registries`\n\t\t\t\t\t\t: `rm -rf <runtimeRoot>/stacks/<stack>/manifest.json && devstack apply  # regenerate`,\n\t\t\t\tcause: err,\n\t\t\t});\n\t\t}\n\t\tthrow err;\n\t}\n};\n"],"mappings":";;;;;;;AA4EA,MAAM,WAAW,QAA2C;CAC3D,MAAM,WAA6B,iCAAiC,GAAG;CASvE,MAAM,UAAU,gBACf,IAAI,UAAU,OAAO,4BAA4B,WAAW,CAAC;CAC9D,OAAO;EACN,cAAc,IAAI;EAClB,UAAU;EACV,UAAU,SAAS;EACnB,WAAW,SAAS,OAAO,IAAI,CAAC,EAAE;EAClC,kBAAkB,SAAS;GAC1B,MAAM,IAAI,OAAO,IAAI;GACrB,IAAI,MAAM,KAAA,GAAW,OAAO,KAAA;GAC5B,OAAO,EAAE,cAAc,EAAE;EAC1B;CACD;AACD;;;;;;;;;;;;AAaA,MAAa,oBAAoB,OAAgC,CAAC,MAAgC;CACjG,MAAM,MAAM,KAAK,OAAQ,QAAQ;CAOjC,MAAM,EAAE,OAAO,UAAU,gBAAgB,oBAAoB,KAAK;EACjE,GAAI,KAAK,UAAU,KAAA,IAAY,EAAE,OAAO,KAAK,MAAM,IAAI,CAAC;EACxD,GAAI,KAAK,gBAAgB,KAAA,IAAY,EAAE,UAAU,KAAK,YAAY,IAAI,CAAC;EACvE,KAAK,KAAK,OAAO,QAAQ,IAAI;CAC9B,CAAC;CAED,IAAI;EAQH,OAAO,QAPKA,iBAAwB;GACnC,GAAI,KAAK,QAAQ,KAAA,IAAY,EAAE,KAAK,KAAK,IAAI,IAAI,CAAC;GAClD;GACA,UAAU;GACV;GACA,GAAI,KAAK,iBAAiB,KAAA,IAAY,EAAE,cAAc,KAAK,aAAa,IAAI,CAAC;EAC9E,CACiB,CAAC;CACnB,SAAS,KAAK;EACb,IAAI,eAAe,wBAAwB;GAO1C,IAAI,IAAI,UAAU,iBAAiB,IAAI,UAAU,oBAChD,MAAM,IAAI,4BAA4B;IACrC,SAAS,IAAI;IACb,cAAc,KAAK,OAAO,QAAQ,IAAI;IACtC;IACA,UAAU;IACV,UAAU;GACX,CAAC;GAEF,IAAI,KAAK,aAAa,MACrB,MAAM,IAAI,4BAA4B;IACrC,SAAS,yCAAyC,MAAM,WAAW,YAAY;IAC/E,cAAc,KAAK,OAAO,QAAQ,IAAI;IACtC;IACA,UAAU;IACV,UAAU;GACX,CAAC;GAEF;EACD;EACA,IAAI,eAAe,oBAAoB;GAKtC,IAAI,IAAI,UAAU,WACjB,MAAM,IAAI,mCAAmC;IAC5C,MAAM,IAAI;IACV,SAAS,IAAI;IACb,UAAU;IACV,OAAO;GACR,CAAC;GAEF,MAAM,IAAI,yBAAyB;IAClC,OAAO,IAAI;IACX,MAAM,IAAI;IACV,SAAS,IAAI;IACb,UACC,IAAI,UAAU,UACX,MAAM,IAAI,KAAK,wDACf;IACJ,OAAO;GACR,CAAC;EACF;EACA,MAAM;CACP;AACD"}

package/dist/cli/bail.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"bail.mjs","names":[],"sources":["../../src/cli/bail.ts"],"sourcesContent":["// Verb-wiring bail helpers — promote raw `process.stderr.write` +\n// `process.exitCode = ...` shortcuts to typed `CliError` failures.\n//\n// Why this exists:\n//   The dispatcher's outer `Effect.catch((error: CliError) =>\n//   emitFailure(...))` in `surfaces/cli/index.ts` already knows how to\n//   render a typed error AS a JSON envelope (when `--json`) or a human\n//   stderr line (otherwise). Wirings that bypass the typed-error path\n//   and write raw bytes to stderr break the JSON-envelope contract:\n//   `devstack up --json` against a live supervisor would emit raw\n//   `error: supervisor live for <app>/<stack>\\n` text on stderr instead\n//   of a structured `{ok:false, error.code:'SUPERVISOR_LIVE'}` envelope\n//   on stdout. The fix is to surface the failure as\n//   `Effect.fail(new CliSupervisorLiveError(...))` and let the\n//   dispatcher's envelope renderer handle the projection.\n//\n// This module exists so the canonical pattern is one import + one\n// function call, not a 6-line `Effect.fail(new …)` boilerplate at every\n// bail site.\n\nimport { Cause, type Exit } from 'effect';\n\nimport {\n\ttype CliConfigInvalidError,\n\ttype CliConfigNotFoundError,\n\ttype CliError,\n\tCliInternalError,\n} from '../surfaces/cli/errors.ts';\n\n/** Project a config-loader `Exit.Failure` cause to the typed `CliError`\n *  the dispatcher expects. The config loader fails with\n *  `CliConfigNotFoundError | CliConfigInvalidError`; defect paths (a\n *  thrown non-Error) bottom out at `CliInternalError`. */\nexport const cliErrorFromConfigExit = (\n\texit: Exit.Exit<unknown, CliConfigNotFoundError | CliConfigInvalidError>,\n): CliError => {\n\tif (exit._tag === 'Success') {\n\t\t// Caller-side contract: only invoke on failure. Defensive\n\t\t// fallback returns an internal error instead of throwing so a\n\t\t// misuse doesn't crash the dispatcher.\n\t\treturn new CliInternalError({\n\t\t\tmessage: 'cliErrorFromConfigExit invoked on a successful exit',\n\t\t});\n\t}\n\tconst fail = exit.cause.reasons.find(Cause.isFailReason);\n\tif (fail !== undefined) {\n\t\tconst err = fail.error;\n\t\tif (err._tag === 'CliConfigNotFoundError' || err._tag === 'CliConfigInvalidError') {\n\t\t\treturn err;\n\t\t}\n\t}\n\treturn new CliInternalError({\n\t\tmessage: 'config load failed with an unexpected cause',\n\t\tcause: exit.cause,\n\t});\n};\n"],"mappings":";;;;;;;AAiCA,MAAa,0BACZ,SACc;AACd,KAAI,KAAK,SAAS,UAIjB,QAAO,IAAI,iBAAiB,EAC3B,SAAS,uDACT,CAAC;CAEH,MAAM,OAAO,KAAK,MAAM,QAAQ,KAAK,MAAM,aAAa;AACxD,KAAI,SAAS,KAAA,GAAW;EACvB,MAAM,MAAM,KAAK;AACjB,MAAI,IAAI,SAAS,4BAA4B,IAAI,SAAS,wBACzD,QAAO;;AAGT,QAAO,IAAI,iBAAiB;EAC3B,SAAS;EACT,OAAO,KAAK;EACZ,CAAC"}
+{"version":3,"file":"bail.mjs","names":[],"sources":["../../src/cli/bail.ts"],"sourcesContent":["// Verb-wiring bail helpers — promote raw `process.stderr.write` +\n// `process.exitCode = ...` shortcuts to typed `CliError` failures.\n//\n// Why this exists:\n//   The dispatcher's outer `Effect.catch((error: CliError) =>\n//   emitFailure(...))` in `surfaces/cli/index.ts` already knows how to\n//   render a typed error AS a JSON envelope (when `--json`) or a human\n//   stderr line (otherwise). Wirings that bypass the typed-error path\n//   and write raw bytes to stderr break the JSON-envelope contract:\n//   `devstack up --json` against a live supervisor would emit raw\n//   `error: supervisor live for <app>/<stack>\\n` text on stderr instead\n//   of a structured `{ok:false, error.code:'SUPERVISOR_LIVE'}` envelope\n//   on stdout. The fix is to surface the failure as\n//   `Effect.fail(new CliSupervisorLiveError(...))` and let the\n//   dispatcher's envelope renderer handle the projection.\n//\n// This module exists so the canonical pattern is one import + one\n// function call, not a 6-line `Effect.fail(new …)` boilerplate at every\n// bail site.\n\nimport { Cause, type Exit } from 'effect';\n\nimport {\n\ttype CliConfigInvalidError,\n\ttype CliConfigNotFoundError,\n\ttype CliError,\n\tCliInternalError,\n} from '../surfaces/cli/errors.ts';\n\n/** Project a config-loader `Exit.Failure` cause to the typed `CliError`\n *  the dispatcher expects. The config loader fails with\n *  `CliConfigNotFoundError | CliConfigInvalidError`; defect paths (a\n *  thrown non-Error) bottom out at `CliInternalError`. */\nexport const cliErrorFromConfigExit = (\n\texit: Exit.Exit<unknown, CliConfigNotFoundError | CliConfigInvalidError>,\n): CliError => {\n\tif (exit._tag === 'Success') {\n\t\t// Caller-side contract: only invoke on failure. Defensive\n\t\t// fallback returns an internal error instead of throwing so a\n\t\t// misuse doesn't crash the dispatcher.\n\t\treturn new CliInternalError({\n\t\t\tmessage: 'cliErrorFromConfigExit invoked on a successful exit',\n\t\t});\n\t}\n\tconst fail = exit.cause.reasons.find(Cause.isFailReason);\n\tif (fail !== undefined) {\n\t\tconst err = fail.error;\n\t\tif (err._tag === 'CliConfigNotFoundError' || err._tag === 'CliConfigInvalidError') {\n\t\t\treturn err;\n\t\t}\n\t}\n\treturn new CliInternalError({\n\t\tmessage: 'config load failed with an unexpected cause',\n\t\tcause: exit.cause,\n\t});\n};\n"],"mappings":";;;;;;;AAiCA,MAAa,0BACZ,SACc;CACd,IAAI,KAAK,SAAS,WAIjB,OAAO,IAAI,iBAAiB,EAC3B,SAAS,sDACV,CAAC;CAEF,MAAM,OAAO,KAAK,MAAM,QAAQ,KAAK,MAAM,YAAY;CACvD,IAAI,SAAS,KAAA,GAAW;EACvB,MAAM,MAAM,KAAK;EACjB,IAAI,IAAI,SAAS,4BAA4B,IAAI,SAAS,yBACzD,OAAO;CAET;CACA,OAAO,IAAI,iBAAiB;EAC3B,SAAS;EACT,OAAO,KAAK;CACb,CAAC;AACF"}

package/dist/cli/doctor-probes.mjs

@@ -11,7 +11,6 @@ import { Effect } from "effect";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
-import { hostname } from "node:os";
 import { createConnection } from "node:net";
 //#region src/cli/doctor-probes.ts
 const okOutcome = (detail) => detail !== void 0 ? {
@@ -354,7 +353,6 @@ const locksProbe = (appRoot) => ({
 	required: false,
 	run: () => Effect.gen(function* () {
 		if (!existsSync(appRoot)) return okOutcome("(no app root yet)");
-		const ownHost = hostname();
 		const probe = yield* LivenessProbeScope;
 		let orphans = 0;
 		let totalLive = 0;
@@ -373,7 +371,7 @@ const locksProbe = (appRoot) => ({
 					version: 1,
 					holders: []
 				})));
-				for (const holder of doc.holders) if ((yield* probe.probeHolderLiveness(holder, ownHost).pipe(Effect.catch(() => Effect.succeed("alive")))) === "alive") totalLive += 1;
+				for (const holder of doc.holders) if ((yield* probe.probeHolderLiveness(holder).pipe(Effect.catch(() => Effect.succeed("alive")))) === "alive") totalLive += 1;
 				else orphans += 1;
 			}
 		} catch (cause) {