@mysten-incubation/devstack 0.0.1 → 0.1.0

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 or shape drift after a manifestVersion bump. */\nexport class VitestManifestShapeError extends Data.TaggedError('VitestManifestShapeError')<{\n\treadonly message: string;\n\treadonly path: string;\n\treadonly phase: 'parse' | 'shape';\n\treadonly recovery: string;\n\treadonly cause?: unknown;\n}> {}\n\n/** A test-setup precondition was violated. Currently only one case:\n *  the caller asked for `requireDevstack: true` but the manifest wasn't\n *  discoverable. Distinct from the discovery error because the caller\n *  opted IN to the requirement. */\nexport class VitestSetupPreconditionError extends Data.TaggedError('VitestSetupPreconditionError')<{\n\treadonly message: string;\n\treadonly hint?: string;\n}> {}\n\nexport type VitestIntegrationError =\n\t| VitestManifestNotFoundError\n\t| VitestManifestShapeError\n\t| VitestSetupPreconditionError;\n"],"mappings":";;;;;AAoBA,IAAa,8BAAb,cAAiD,KAAK,YAAY,8BAA8B,CAM7F;;;AAIH,IAAa,2BAAb,cAA8C,KAAK,YAAY,2BAA2B,CAMvF;;;;;AAMH,IAAa,+BAAb,cAAkD,KAAK,YAAY,+BAA+B,CAG/F"}
+{"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"}

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

@@ -2,5 +2,5 @@ import { LoadStackContextOptions, StackContext, loadStackContext } from "./stack
 import { TestSetupOptions, VitestLifecycleHooks, getStackContext, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup } from "./setup.mjs";
 import { DevstackVitestTestConfigOptions, devstackVitestServerConfig, devstackVitestTestConfig } from "./config.mjs";
 import { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, RECOMMENDED_TEST_STACK, ResolvedVitestEnv, VITEST_ENV_VARS, VitestEnvVarName, resolveVitestEnv } from "./env.mjs";
-import { VitestIntegrationError, VitestManifestNotFoundError, VitestManifestShapeError, VitestSetupPreconditionError } from "./errors.mjs";
-export { DEFAULT_RUNTIME_ROOT, DEFAULT_STACK_NAME, type DevstackVitestTestConfigOptions, type LoadStackContextOptions, RECOMMENDED_TEST_STACK, type ResolvedVitestEnv, type StackContext, type TestSetupOptions, VITEST_ENV_VARS, type VitestEnvVarName, type VitestIntegrationError, type VitestLifecycleHooks, VitestManifestNotFoundError, VitestManifestShapeError, VitestSetupPreconditionError, devstackVitestServerConfig, devstackVitestTestConfig, getStackContext, loadStackContext, resolveVitestEnv, runDevstackAfterAll, runDevstackBeforeAll, useDevstackTestSetup };
+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 };

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

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

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

@@ -15,8 +15,10 @@ interface TestSetupOptions extends LoadStackContextOptions {
   readonly requireDevstack?: boolean;
   /** Suppress the stack-name advisory. Default `false`. */
   readonly silent?: boolean;
-  /** Custom writer for the advisory line. Defaults to `console.warn`.
-   *  Tests substitute a buffer. */
+  /** Custom writer for the advisory line. Defaults to a stderr
+   *  writer (`process.stderr.write(line + '\n')`) — matches the
+   *  build-integration surface IO discipline (no `console.*` in
+   *  production paths). Tests substitute a buffer. */
   readonly writeAdvisory?: (line: string) => void;
 }
 /** `beforeAll` body. Exported as a plain function so callers can wire

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
@@ -17,7 +17,7 @@ const clearStackContext = () => {
 *  setup-file. */
 const runDevstackBeforeAll = (options = {}) => {
 	const resolved = resolveVitestEnv(options.env ?? process.env);
-	if (!options.silent && !resolved.stackWasExplicit) (options.writeAdvisory ?? ((line) => console.warn(line)))(`[devstack/vitest] ${VITEST_ENV_VARS.STACK} is unset; tests will read the '${resolved.stack}' stack. Set ${VITEST_ENV_VARS.STACK}=${RECOMMENDED_TEST_STACK} in the test script to avoid contention with \`pnpm dev\`.`);
+	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,
 		required: options.requireDevstack === true

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\nimport {\n\tloadStackContext,\n\ttype LoadStackContextOptions,\n\ttype StackContext,\n} from './stack-context.ts';\nimport { resolveVitestEnv, VITEST_ENV_VARS, RECOMMENDED_TEST_STACK } from './env.ts';\nimport { VitestSetupPreconditionError } from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Captured fixture — single shared handle across the test file\n// -----------------------------------------------------------------------------\n\nlet captured: StackContext | undefined;\n\n/** Return the StackContext captured by `runDevstackBeforeAll`. Returns\n *  `undefined` until `beforeAll` has run (or when the suite ran with\n *  `requireDevstack: false` and no manifest exists). */\nexport const getStackContext = (): StackContext | undefined => captured;\n\n/** Reset the captured fixture. Called by `runDevstackAfterAll`; also\n *  exported so test helpers can wipe between describe-block setups. */\nexport const clearStackContext = (): void => {\n\tcaptured = undefined;\n};\n\n// -----------------------------------------------------------------------------\n// Options\n// -----------------------------------------------------------------------------\n\nexport interface TestSetupOptions extends LoadStackContextOptions {\n\t/** When `true`, `beforeAll` throws if no manifest is on disk. Use\n\t *  for suites that depend on a live devstack and would fail\n\t *  confusingly later. Default `false` (manifest is best-effort). */\n\treadonly requireDevstack?: boolean;\n\t/** Suppress the stack-name advisory. Default `false`. */\n\treadonly silent?: boolean;\n\t/** Custom writer for the advisory line. Defaults to `console.warn`.\n\t *  Tests substitute a buffer. */\n\treadonly writeAdvisory?: (line: string) => void;\n}\n\n// -----------------------------------------------------------------------------\n// Hooks\n// -----------------------------------------------------------------------------\n\n/** `beforeAll` body. Exported as a plain function so callers can wire\n *  it into Vitest's hooks directly OR call it inline from a\n *  setup-file. */\nexport const runDevstackBeforeAll = (options: TestSetupOptions = {}): void => {\n\tconst env = options.env ?? (process.env as Readonly<Record<string, string | undefined>>);\n\tconst resolved = resolveVitestEnv(env);\n\n\tif (!options.silent && !resolved.stackWasExplicit) {\n\t\tconst write = options.writeAdvisory ?? ((line: string) => console.warn(line));\n\t\twrite(\n\t\t\t`[devstack/vitest] ${VITEST_ENV_VARS.STACK} is unset; tests will read the '${resolved.stack}' stack. ` +\n\t\t\t\t`Set ${VITEST_ENV_VARS.STACK}=${RECOMMENDED_TEST_STACK} in the test script to avoid contention with \\`pnpm dev\\`.`,\n\t\t);\n\t}\n\n\tconst ctx = loadStackContext({\n\t\t...options,\n\t\trequired: options.requireDevstack === true,\n\t});\n\n\tif (options.requireDevstack === true && ctx === undefined) {\n\t\t// `loadStackContext({required: true})` should have thrown.\n\t\t// Defensive — surfaces a clearer error if a future refactor\n\t\t// changes the required-miss semantics.\n\t\tthrow new VitestSetupPreconditionError({\n\t\t\tmessage: `requireDevstack: true but loadStackContext returned undefined`,\n\t\t\thint: 'this is a devstack bug; please file an issue',\n\t\t});\n\t}\n\n\tcaptured = ctx;\n};\n\n/** `afterAll` body. Currently just clears the captured fixture; the\n *  separate symbol lets us extend later (e.g. snapshot diagnostics)\n *  without touching consumer setup files. */\nexport const runDevstackAfterAll = (): void => {\n\tclearStackContext();\n};\n\n// -----------------------------------------------------------------------------\n// Vitest hook registrar\n// -----------------------------------------------------------------------------\n\n/** Vitest's `beforeAll` / `afterAll` hook signatures. Match the\n *  `vitest`-package shapes without importing the module (so this file\n *  stays consumable by orchestrators that don't ship vitest as a\n *  hard dep). */\nexport interface VitestLifecycleHooks {\n\treadonly beforeAll: (fn: () => void | Promise<void>) => void;\n\treadonly afterAll: (fn: () => void | Promise<void>) => void;\n}\n\n/**\n * Wire the devstack setup/teardown into a vitest test file's hook\n * functions. Typical usage in a `test-setup.ts`:\n *\n *     import { beforeAll, afterAll } from 'vitest';\n *     import { useDevstackTestSetup }\n *       from '@mysten-incubation/devstack/vitest';\n *\n *     useDevstackTestSetup({ beforeAll, afterAll }, { requireDevstack: true });\n *\n * The preset wires this automatically when `opts.testSetup: true`.\n */\nexport const useDevstackTestSetup = (\n\thooks: VitestLifecycleHooks,\n\toptions: TestSetupOptions = {},\n): void => {\n\thooks.beforeAll(() => runDevstackBeforeAll(options));\n\thooks.afterAll(() => runDevstackAfterAll());\n};\n"],"mappings":";;;;AAgDA,IAAI;;;;AAKJ,MAAa,wBAAkD;;;AAI/D,MAAa,0BAAgC;AAC5C,YAAW,KAAA;;;;;AA0BZ,MAAa,wBAAwB,UAA4B,EAAE,KAAW;CAE7E,MAAM,WAAW,iBADL,QAAQ,OAAQ,QAAQ,IACE;AAEtC,KAAI,CAAC,QAAQ,UAAU,CAAC,SAAS,iBAEhC,EADc,QAAQ,mBAAmB,SAAiB,QAAQ,KAAK,KAAK,GAE3E,qBAAqB,gBAAgB,MAAM,kCAAkC,SAAS,MAAM,eACpF,gBAAgB,MAAM,GAAG,uBAAuB,4DACxD;CAGF,MAAM,MAAM,iBAAiB;EAC5B,GAAG;EACH,UAAU,QAAQ,oBAAoB;EACtC,CAAC;AAEF,KAAI,QAAQ,oBAAoB,QAAQ,QAAQ,KAAA,EAI/C,OAAM,IAAI,6BAA6B;EACtC,SAAS;EACT,MAAM;EACN,CAAC;AAGH,YAAW;;;;;AAMZ,MAAa,4BAAkC;AAC9C,oBAAmB;;;;;;;;;;;;;;AA4BpB,MAAa,wBACZ,OACA,UAA4B,EAAE,KACpB;AACV,OAAM,gBAAgB,qBAAqB,QAAQ,CAAC;AACpD,OAAM,eAAe,qBAAqB,CAAC"}
+{"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"}

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

@@ -1,5 +1,4 @@
 import { ManifestEnvelope } from "../../substrate/manifest.mjs";
-
 //#region src/build-integrations/vitest/stack-context.d.ts
 /** Read-only projection over the live manifest, scoped to the vitest
  *  surface's needs. The full envelope is reconstructed (`manifest`)

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

@@ -1,17 +1,20 @@
+import { resolveDiscoveryEnv } from "../runtime/resolve-discovery-env.mjs";
 import { ManifestDiscoveryError, ManifestShapeError } from "../runtime/errors.mjs";
 import { manifestEnvelopeFromStackContext, readStackContext } from "../runtime/read-stack-context.mjs";
-import { VITEST_ENV_VARS } from "./env.mjs";
-import { VitestManifestNotFoundError, VitestManifestShapeError } from "./errors.mjs";
+import { resolveBuiltInEndpointAlias } from "../runtime/conventional-routes.mjs";
+import "../runtime/index.mjs";
+import { VitestManifestNotFoundError, VitestManifestShapeError, VitestManifestVersionMismatchError } from "./errors.mjs";
 //#region src/build-integrations/vitest/stack-context.ts
 const project = (ctx) => {
 	const envelope = manifestEnvelopeFromStackContext(ctx);
+	const lookup = (nameOrAlias) => ctx.endpoints.byName(resolveBuiltInEndpointAlias(nameOrAlias));
 	return {
 		manifestPath: ctx.manifestPath,
 		manifest: envelope,
 		identity: envelope.identity,
-		endpoint: (name) => ctx.endpoints.byName(name)?.url,
+		endpoint: (name) => lookup(name)?.url,
 		displayEndpoint: (name) => {
-			const e = ctx.endpoints.byName(name);
+			const e = lookup(name);
 			if (e === void 0) return void 0;
 			return e.displayUrl ?? e.url;
 		}
@@ -30,8 +33,10 @@ const project = (ctx) => {
 */
 const loadStackContext = (opts = {}) => {
 	const env = opts.env ?? process.env;
-	const stack = opts.stack ?? env[VITEST_ENV_VARS.STACK] ?? "main";
-	const runtimeRoot = opts.runtimeRoot ?? env[VITEST_ENV_VARS.RUNTIME_ROOT] ?? env[VITEST_ENV_VARS.RUNTIME_ROOT_LEGACY] ?? ".devstack";
+	const { stack, stateDir: runtimeRoot } = resolveDiscoveryEnv(env, {
+		...opts.stack !== void 0 ? { stack: opts.stack } : {},
+		...opts.runtimeRoot !== void 0 ? { stateDir: opts.runtimeRoot } : {}
+	});
 	try {
 		return project(readStackContext({
 			...opts.cwd !== void 0 ? { cwd: opts.cwd } : {},
@@ -42,6 +47,13 @@ const loadStackContext = (opts = {}) => {
 		}));
 	} catch (err) {
 		if (err instanceof ManifestDiscoveryError) {
+			if (err.phase === "env-missing" || err.phase === "override-missing") throw new VitestManifestNotFoundError({
+				message: err.message,
+				searchedFrom: opts.cwd ?? process.cwd(),
+				stack,
+				stateDir: runtimeRoot,
+				recovery: `run \`devstack up\` (or unset DEVSTACK_MANIFEST_PATH / pass an existing manifestPath)`
+			});
 			if (opts.required === true) throw new VitestManifestNotFoundError({
 				message: `no devstack manifest found for stack '${stack}' under '${runtimeRoot}'`,
 				searchedFrom: opts.cwd ?? process.cwd(),
@@ -51,13 +63,21 @@ const loadStackContext = (opts = {}) => {
 			});
 			return;
 		}
-		if (err instanceof ManifestShapeError) throw new VitestManifestShapeError({
-			phase: err.phase === "parse" ? "parse" : "shape",
-			path: err.path,
-			message: err.message,
-			recovery: err.phase === "parse" ? `rm ${err.path} && devstack apply  # regenerate from the registries` : `rm -rf <runtimeRoot>/stacks/<stack>/manifest.json && devstack apply  # regenerate`,
-			cause: err
-		});
+		if (err instanceof ManifestShapeError) {
+			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.",
+				cause: err
+			});
+			throw new VitestManifestShapeError({
+				phase: err.phase,
+				path: err.path,
+				message: err.message,
+				recovery: err.phase === "parse" ? `rm ${err.path} && devstack apply  # regenerate from the registries` : `rm -rf <runtimeRoot>/stacks/<stack>/manifest.json && devstack apply  # regenerate`,
+				cause: err
+			});
+		}
 		throw err;
 	}
 };

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\ttype StackContext as RuntimeStackContext,\n} from '../runtime/index.ts';\nimport type { ManifestEnvelope } from '../../substrate/manifest.ts';\nimport { VITEST_ENV_VARS } from './env.ts';\nimport { VitestManifestNotFoundError, VitestManifestShapeError } 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\treturn {\n\t\tmanifestPath: ctx.manifestPath,\n\t\tmanifest: envelope,\n\t\tidentity: envelope.identity,\n\t\tendpoint: (name) => ctx.endpoints.byName(name)?.url,\n\t\tdisplayEndpoint: (name) => {\n\t\t\tconst e = ctx.endpoints.byName(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\tconst stack = opts.stack ?? env[VITEST_ENV_VARS.STACK] ?? 'main';\n\tconst runtimeRoot =\n\t\topts.runtimeRoot ??\n\t\tenv[VITEST_ENV_VARS.RUNTIME_ROOT] ??\n\t\tenv[VITEST_ENV_VARS.RUNTIME_ROOT_LEGACY] ??\n\t\t'.devstack';\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\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 both decode-failure and version-mismatch as\n\t\t\t// `phase: 'parse' | 'shape' | 'version'`. The vitest error\n\t\t\t// union exposes `parse` and `shape`; map `version` onto\n\t\t\t// `shape` with a recovery hint that names the version-bump\n\t\t\t// recipe.\n\t\t\tconst phase: 'parse' | 'shape' = err.phase === 'parse' ? 'parse' : 'shape';\n\t\t\tthrow new VitestManifestShapeError({\n\t\t\t\tphase,\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":";;;;;AAmEA,MAAM,WAAW,QAA2C;CAC3D,MAAM,WAA6B,iCAAiC,IAAI;AACxE,QAAO;EACN,cAAc,IAAI;EAClB,UAAU;EACV,UAAU,SAAS;EACnB,WAAW,SAAS,IAAI,UAAU,OAAO,KAAK,EAAE;EAChD,kBAAkB,SAAS;GAC1B,MAAM,IAAI,IAAI,UAAU,OAAO,KAAK;AACpC,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;CACjC,MAAM,QAAQ,KAAK,SAAS,IAAI,gBAAgB,UAAU;CAC1D,MAAM,cACL,KAAK,eACL,IAAI,gBAAgB,iBACpB,IAAI,gBAAgB,wBACpB;AAED,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;AAC1C,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,mBAOlB,OAAM,IAAI,yBAAyB;GAClC,OAFgC,IAAI,UAAU,UAAU,UAAU;GAGlE,MAAM,IAAI;GACV,SAAS,IAAI;GACb,UACC,IAAI,UAAU,UACX,MAAM,IAAI,KAAK,wDACf;GACJ,OAAO;GACP,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// 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"}

package/dist/cli/bail.mjs

@@ -0,0 +1,23 @@
+import { CliInternalError } from "../surfaces/cli/errors.mjs";
+import { Cause } from "effect";
+//#region src/cli/bail.ts
+/** Project a config-loader `Exit.Failure` cause to the typed `CliError`
+*  the dispatcher expects. The config loader fails with
+*  `CliConfigNotFoundError | CliConfigInvalidError`; defect paths (a
+*  thrown non-Error) bottom out at `CliInternalError`. */
+const cliErrorFromConfigExit = (exit) => {
+	if (exit._tag === "Success") return new CliInternalError({ message: "cliErrorFromConfigExit invoked on a successful exit" });
+	const fail = exit.cause.reasons.find(Cause.isFailReason);
+	if (fail !== void 0) {
+		const err = fail.error;
+		if (err._tag === "CliConfigNotFoundError" || err._tag === "CliConfigInvalidError") return err;
+	}
+	return new CliInternalError({
+		message: "config load failed with an unexpected cause",
+		cause: exit.cause
+	});
+};
+//#endregion
+export { cliErrorFromConfigExit };
+
+//# sourceMappingURL=bail.mjs.map

package/dist/cli/bail.mjs.map

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

package/dist/{surfaces/cli/commands → cli}/doctor-probes.mjs

@@ -1,16 +1,19 @@
-import { checkHolderLiveness } from "../../../substrate/runtime/cross-process/liveness.mjs";
-import { readRoster } from "../../../substrate/runtime/cross-process/roster.mjs";
-import { routerProfileLabelsMatch, uniqueSortedEntrypointPorts } from "../../../orchestrators/router/traefik-container.mjs";
-import { makeDefaultRouterProfile } from "../../../orchestrators/router/profile.mjs";
-import { dispatchFileIdFromFilename, parseDispatchRouteFile } from "../../../orchestrators/router/file-provider.mjs";
-import { BUILT_IN_ENTRYPOINTS } from "../../../plugins/router-entrypoints.mjs";
+import { parseJsonTextSync } from "../substrate/runtime/runtime-decode.mjs";
+import { LivenessProbeScope, layerLivenessProbeScope } from "../substrate/runtime/cross-process/liveness.mjs";
+import { readRoster } from "../substrate/runtime/cross-process/roster.mjs";
+import { routerProfileLabelsMatch, uniqueSortedEntrypointPorts } from "../orchestrators/router/traefik-container.mjs";
+import { makeDefaultRouterProfile } from "../orchestrators/router/profile.mjs";
+import { dispatchFileIdFromFilename, parseDispatchRouteFile } from "../orchestrators/router/file-provider.mjs";
+import "../orchestrators/router/index.mjs";
+import { BUILT_IN_ENTRYPOINTS } from "../plugins/router-entrypoints.mjs";
+import "../substrate/runtime/cross-process/index.mjs";
 import { Effect } from "effect";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { createConnection } from "node:net";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { hostname } from "node:os";
-//#region src/surfaces/cli/commands/doctor-probes.ts
+import { createConnection } from "node:net";
+//#region src/cli/doctor-probes.ts
 const okOutcome = (detail) => detail !== void 0 ? {
 	status: "ok",
 	detail
@@ -67,8 +70,10 @@ const suiCliProbe = {
 		};
 	})
 };
-/** Probe: a TCP port is reachable on localhost. Used to verify the
-*  user's reverse-proxy entrypoint isn't squatting the Traefik port. */
+/** Probe: a TCP port is FREE on localhost (resolves `true` when nothing
+*  is listening — connection refused/timeout — and `false` when a
+*  listener answers). Backs `routerProfileProbe`'s entrypoint-listener
+*  check. */
 const probePortFree = (port, timeoutMs = 500) => new Promise((resolve) => {
 	const socket = createConnection({
 		host: "127.0.0.1",
@@ -101,7 +106,10 @@ const fieldString = (record, key) => typeof record[key] === "string" ? record[ke
 const fieldBoolean = (record, key) => typeof record[key] === "boolean" ? record[key] : null;
 const parseDockerInspectFirst = (out) => {
 	try {
-		const parsed = JSON.parse(out);
+		const parsed = parseJsonTextSync(out, {
+			source: "docker inspect",
+			mkError: (issue) => issue
+		});
 		if (Array.isArray(parsed)) return unknownRecord(parsed[0]);
 		return unknownRecord(parsed);
 	} catch {
@@ -219,6 +227,7 @@ const inspectRouterDispatch = (profile) => Effect.gen(function* () {
 			safeToPrune: false
 		};
 	}
+	const probe = yield* LivenessProbeScope;
 	let routeFiles = 0;
 	let liveRoutes = 0;
 	let staleRoutes = 0;
@@ -249,7 +258,7 @@ const inspectRouterDispatch = (profile) => Effect.gen(function* () {
 			unknownOwnerRoutes += 1;
 			continue;
 		}
-		if ((yield* checkHolderLiveness(parsed.route.lease.owner).pipe(Effect.catch(() => Effect.succeed("alive")))) === "dead") staleRoutes += 1;
+		if ((yield* probe.probeHolderLiveness(parsed.route.lease.owner).pipe(Effect.catch(() => Effect.succeed("alive")))) === "dead") staleRoutes += 1;
 		else liveRoutes += 1;
 	}
 	return {
@@ -262,7 +271,7 @@ const inspectRouterDispatch = (profile) => Effect.gen(function* () {
 		diagnostics,
 		safeToPrune: liveRoutes === 0 && unknownOwnerRoutes === 0 && corruptRouteFiles === 0
 	};
-});
+}).pipe(Effect.provide(layerLivenessProbeScope));
 const inspectRouterStateDir = (profile) => {
 	if (!existsSync(profile.stateDir)) return "absent";
 	try {
@@ -346,6 +355,7 @@ const locksProbe = (appRoot) => ({
 	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;
 		try {
@@ -363,7 +373,7 @@ const locksProbe = (appRoot) => ({
 					version: 1,
 					holders: []
 				})));
-				for (const holder of doc.holders) if ((yield* checkHolderLiveness(holder, ownHost).pipe(Effect.catch(() => Effect.succeed("alive")))) === "alive") totalLive += 1;
+				for (const holder of doc.holders) if ((yield* probe.probeHolderLiveness(holder, ownHost).pipe(Effect.catch(() => Effect.succeed("alive")))) === "alive") totalLive += 1;
 				else orphans += 1;
 			}
 		} catch (cause) {
@@ -377,7 +387,7 @@ const locksProbe = (appRoot) => ({
 			status: "warn",
 			detail: `${orphans} orphan holder(s); rerun with --clean-locks`
 		};
-	})
+	}).pipe(Effect.provide(layerLivenessProbeScope))
 });
 /** Probe: state-dir is writable. Validates DEVSTACK_STATE_DIR resolves
 *  to a usable path (or the default ~/.devstack does). */
@@ -433,7 +443,7 @@ const countTreeSize = (dir, depth = 0) => {
 	}
 	return n;
 };
-/** Default probe set. The dispatcher composes this with the resolved
+/** Default probe set. `cli/main.ts` composes this with the resolved
 *  app root, runtime state dir, router profile, and router entrypoints. */
 const defaultProbes = (params) => [
 	dockerProbe,

package/dist/cli/doctor-probes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-probes.mjs","names":["nodeHostname"],"sources":["../../src/cli/doctor-probes.ts"],"sourcesContent":["// L4-adjacent CLI infrastructure: doctor probe definitions.\n//\n// Per STYLE_GUIDE §7: `cli/*.ts` modules sit alongside the bin entry\n// (`cli/main.ts`) and may import L3 orchestrator + L2 plugin barrels —\n// they are NOT L4 surfaces proper. The router-profile probe needs\n// both the L3 router orchestrator helpers (parsing dispatch files,\n// matching profile labels, sorting entrypoint ports) and the built-in\n// L2 router entrypoint composition; that wiring lives here.\n//\n// The probes themselves are read-only diagnostics: Docker reachable,\n// `sui` CLI on PATH, state-dir writable, router profile state +\n// dispatch leases + entrypoint listeners, orphan cross-process locks,\n// fork-cache health. Each returns a typed `ProbeOutcome` and never\n// throws. `required: true` means a `fail | unavailable` projects to\n// `CliUnavailableError` and exits 69; non-required probes are\n// informational.\n\nimport { execFileSync } from 'node:child_process';\nimport { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';\nimport { hostname as nodeHostname } from 'node:os';\nimport { createConnection } from 'node:net';\nimport { join } from 'node:path';\n\nimport { Effect } from 'effect';\n\nimport {\n\tdispatchFileIdFromFilename,\n\tmakeDefaultRouterProfile,\n\tparseDispatchRouteFile,\n\trouterProfileLabelsMatch,\n\tuniqueSortedEntrypointPorts,\n\ttype Entrypoint,\n\ttype RouterProfile,\n} from '../orchestrators/router/index.ts';\nimport { BUILT_IN_ENTRYPOINTS } from '../plugins/router-entrypoints.ts';\nimport { parseJsonTextSync } from '../substrate/runtime/runtime-decode.ts';\nimport {\n\tlayerLivenessProbeScope,\n\tLivenessProbeScope,\n\treadRoster,\n} from '../substrate/runtime/cross-process/index.ts';\nimport type { RosterHolder } from '../substrate/cross-process.ts';\nimport type { Probe, ProbeOutcome } from '../surfaces/cli/commands/doctor.ts';\n\nconst okOutcome = (detail?: string): ProbeOutcome =>\n\tdetail !== undefined ? { status: 'ok', detail } : { status: 'ok' };\n\ntype CommandResult = { ok: true; out: string } | { ok: false; err: string };\n\nconst captureCommand = (\n\tcmd: string,\n\targs: ReadonlyArray<string>,\n\ttimeoutMs = 3000,\n): CommandResult => {\n\ttry {\n\t\tconst out = execFileSync(cmd, args as string[], {\n\t\t\tencoding: 'utf8',\n\t\t\ttimeout: timeoutMs,\n\t\t\tstdio: ['ignore', 'pipe', 'pipe'],\n\t\t});\n\t\treturn { ok: true, out: out.trim() };\n\t} catch (err) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\terr: err instanceof Error ? err.message : String(err),\n\t\t};\n\t}\n};\n\n/** Probe: `docker version` resolves. */\nexport const dockerProbe: Probe = {\n\tname: 'docker',\n\tdescription: 'Docker daemon reachable',\n\trequired: true,\n\trun: () =>\n\t\tEffect.sync(() => {\n\t\t\tconst result = captureCommand('docker', ['version', '--format', '{{.Server.Version}}']);\n\t\t\tif (!result.ok) {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: 'fail',\n\t\t\t\t\tdetail: `docker version failed: ${result.err}`,\n\t\t\t\t};\n\t\t\t}\n\t\t\treturn okOutcome(`server ${result.out}`);\n\t\t}),\n};\n\n/** Probe: required CLIs on PATH (just sui-cli for fork-aware flows). */\nexport const suiCliProbe: Probe = {\n\tname: 'sui-cli',\n\tdescription: '`sui` CLI on PATH',\n\trequired: false,\n\trun: () =>\n\t\tEffect.sync(() => {\n\t\t\tconst result = captureCommand('sui', ['--version']);\n\t\t\treturn result.ok\n\t\t\t\t? okOutcome(result.out)\n\t\t\t\t: {\n\t\t\t\t\t\tstatus: 'warn',\n\t\t\t\t\t\tdetail: 'sui CLI not on PATH (only needed for live/fork modes)',\n\t\t\t\t\t};\n\t\t}),\n};\n\n/** Probe: a TCP port is FREE on localhost (resolves `true` when nothing\n *  is listening — connection refused/timeout — and `false` when a\n *  listener answers). Backs `routerProfileProbe`'s entrypoint-listener\n *  check. */\nconst probePortFree = (port: number, timeoutMs = 500): Promise<boolean> =>\n\tnew Promise((resolve) => {\n\t\tconst socket = createConnection({ host: '127.0.0.1', port });\n\t\tconst finish = (free: boolean): void => {\n\t\t\tsocket.destroy();\n\t\t\tresolve(free);\n\t\t};\n\t\tconst timer = setTimeout(() => finish(true), timeoutMs);\n\t\tsocket.on('connect', () => {\n\t\t\tclearTimeout(timer);\n\t\t\tfinish(false);\n\t\t});\n\t\tsocket.on('error', () => {\n\t\t\tclearTimeout(timer);\n\t\t\tfinish(true);\n\t\t});\n\t});\n\nexport type DoctorCommandRunner = typeof captureCommand;\nexport type PortAvailabilityProbe = typeof probePortFree;\n\nexport interface RouterProfileProbeOptions {\n\treadonly profile?: RouterProfile;\n\treadonly entrypoints?: ReadonlyArray<Entrypoint>;\n\treadonly command?: DoctorCommandRunner;\n\treadonly probePort?: PortAvailabilityProbe;\n}\n\ninterface RouterDispatchScan {\n\treadonly status: 'absent' | 'ok' | 'not-directory' | 'unreadable';\n\treadonly files: number;\n\treadonly liveRoutes: number;\n\treadonly staleRoutes: number;\n\treadonly unknownOwnerRoutes: number;\n\treadonly corruptRouteFiles: number;\n\treadonly diagnostics: number;\n\treadonly safeToPrune: boolean;\n}\n\ninterface RouterContainerStatus {\n\treadonly status: 'absent' | 'present' | 'invalid' | 'unavailable';\n\treadonly detail?: string;\n\treadonly running?: boolean;\n\treadonly labelsMatch?: boolean;\n\treadonly attachedToNetwork?: boolean;\n\treadonly publishedPorts?: ReadonlyArray<number>;\n}\n\ninterface RouterNetworkStatus {\n\treadonly status: 'absent' | 'present' | 'invalid' | 'unavailable';\n\treadonly detail?: string;\n\treadonly id?: string;\n}\n\nconst unknownRecord = (value: unknown): Record<string, unknown> | null =>\n\ttypeof value === 'object' && value !== null && !Array.isArray(value)\n\t\t? (value as Record<string, unknown>)\n\t\t: null;\n\nconst stringRecord = (value: unknown): Record<string, string> => {\n\tconst rec = unknownRecord(value);\n\tif (rec === null) return {};\n\tconst out: Record<string, string> = {};\n\tfor (const [key, raw] of Object.entries(rec)) {\n\t\tif (typeof raw === 'string') out[key] = raw;\n\t}\n\treturn out;\n};\n\nconst fieldRecord = (\n\trecord: Record<string, unknown>,\n\tkey: string,\n): Record<string, unknown> | null => unknownRecord(record[key]);\n\nconst fieldString = (record: Record<string, unknown>, key: string): string | null =>\n\ttypeof record[key] === 'string' ? (record[key] as string) : null;\n\nconst fieldBoolean = (record: Record<string, unknown>, key: string): boolean | null =>\n\ttypeof record[key] === 'boolean' ? (record[key] as boolean) : null;\n\nconst parseDockerInspectFirst = (out: string): Record<string, unknown> | null => {\n\ttry {\n\t\tconst parsed = parseJsonTextSync(out, {\n\t\t\tsource: 'docker inspect',\n\t\t\tmkError: (issue) => issue,\n\t\t});\n\t\tif (Array.isArray(parsed)) return unknownRecord(parsed[0]);\n\t\treturn unknownRecord(parsed);\n\t} catch {\n\t\treturn null;\n\t}\n};\n\nconst dockerObjectIsAbsent = (err: string): boolean =>\n\t/No such (object|container|network)|not found|No such/i.test(err);\n\nconst uniqueNumbers = (values: ReadonlyArray<number>): ReadonlyArray<number> =>\n\t[...new Set(values)].sort((a, b) => a - b);\n\nconst inspectRouterContainer = (\n\tprofile: RouterProfile,\n\tcommand: DoctorCommandRunner,\n): RouterContainerStatus => {\n\tconst result = command('docker', ['container', 'inspect', profile.containerName]);\n\tif (!result.ok) {\n\t\treturn dockerObjectIsAbsent(result.err)\n\t\t\t? { status: 'absent' }\n\t\t\t: { status: 'unavailable', detail: result.err };\n\t}\n\tconst doc = parseDockerInspectFirst(result.out);\n\tif (doc === null) return { status: 'invalid', detail: 'container inspect JSON was invalid' };\n\tconst state = fieldRecord(doc, 'State') ?? {};\n\tconst config = fieldRecord(doc, 'Config') ?? {};\n\tconst networkSettings = fieldRecord(doc, 'NetworkSettings') ?? {};\n\tconst networks = fieldRecord(networkSettings, 'Networks') ?? {};\n\tconst ports = fieldRecord(networkSettings, 'Ports') ?? {};\n\tconst publishedPorts: Array<number> = [];\n\tfor (const bindings of Object.values(ports)) {\n\t\tif (!Array.isArray(bindings)) continue;\n\t\tfor (const binding of bindings) {\n\t\t\tconst rec = unknownRecord(binding);\n\t\t\tif (rec === null) continue;\n\t\t\tconst rawPort = fieldString(rec, 'HostPort');\n\t\t\tif (rawPort !== null && /^\\d+$/.test(rawPort)) {\n\t\t\t\tpublishedPorts.push(Number.parseInt(rawPort, 10));\n\t\t\t}\n\t\t}\n\t}\n\tconst labels = stringRecord(config.Labels);\n\treturn {\n\t\tstatus: 'present',\n\t\trunning: fieldBoolean(state, 'Running') === true,\n\t\tlabelsMatch: routerProfileLabelsMatch(labels, profile),\n\t\tattachedToNetwork: Object.keys(networks).includes(profile.networkName),\n\t\tpublishedPorts: uniqueNumbers(publishedPorts),\n\t};\n};\n\nconst inspectRouterNetwork = (\n\tprofile: RouterProfile,\n\tcommand: DoctorCommandRunner,\n): RouterNetworkStatus => {\n\tconst result = command('docker', ['network', 'inspect', profile.networkName]);\n\tif (!result.ok) {\n\t\treturn dockerObjectIsAbsent(result.err)\n\t\t\t? { status: 'absent' }\n\t\t\t: { status: 'unavailable', detail: result.err };\n\t}\n\tconst doc = parseDockerInspectFirst(result.out);\n\tif (doc === null) return { status: 'invalid', detail: 'network inspect JSON was invalid' };\n\tconst id = fieldString(doc, 'Id');\n\treturn id === null ? { status: 'present' } : { status: 'present', id };\n};\n\nconst inspectRouterDispatch = (profile: RouterProfile): Effect.Effect<RouterDispatchScan> =>\n\t// Yield a fresh `LivenessProbeScope` so repeated lease owners across\n\t// many dispatch route files fork the OS probe once per pid.\n\tEffect.gen(function* () {\n\t\tif (!existsSync(profile.dispatchDir)) {\n\t\t\treturn {\n\t\t\t\tstatus: 'absent' as const,\n\t\t\t\tfiles: 0,\n\t\t\t\tliveRoutes: 0,\n\t\t\t\tstaleRoutes: 0,\n\t\t\t\tunknownOwnerRoutes: 0,\n\t\t\t\tcorruptRouteFiles: 0,\n\t\t\t\tdiagnostics: 0,\n\t\t\t\tsafeToPrune: true,\n\t\t\t};\n\t\t}\n\t\ttry {\n\t\t\tif (!statSync(profile.dispatchDir).isDirectory()) {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: 'not-directory' as const,\n\t\t\t\t\tfiles: 0,\n\t\t\t\t\tliveRoutes: 0,\n\t\t\t\t\tstaleRoutes: 0,\n\t\t\t\t\tunknownOwnerRoutes: 1,\n\t\t\t\t\tcorruptRouteFiles: 1,\n\t\t\t\t\tdiagnostics: 1,\n\t\t\t\t\tsafeToPrune: false,\n\t\t\t\t};\n\t\t\t}\n\t\t} catch {\n\t\t\treturn {\n\t\t\t\tstatus: 'unreadable' as const,\n\t\t\t\tfiles: 0,\n\t\t\t\tliveRoutes: 0,\n\t\t\t\tstaleRoutes: 0,\n\t\t\t\tunknownOwnerRoutes: 1,\n\t\t\t\tcorruptRouteFiles: 1,\n\t\t\t\tdiagnostics: 1,\n\t\t\t\tsafeToPrune: false,\n\t\t\t};\n\t\t}\n\t\tlet files: ReadonlyArray<string>;\n\t\ttry {\n\t\t\tfiles = readdirSync(profile.dispatchDir);\n\t\t} catch {\n\t\t\treturn {\n\t\t\t\tstatus: 'unreadable' as const,\n\t\t\t\tfiles: 0,\n\t\t\t\tliveRoutes: 0,\n\t\t\t\tstaleRoutes: 0,\n\t\t\t\tunknownOwnerRoutes: 1,\n\t\t\t\tcorruptRouteFiles: 1,\n\t\t\t\tdiagnostics: 1,\n\t\t\t\tsafeToPrune: false,\n\t\t\t};\n\t\t}\n\t\tconst probe = yield* LivenessProbeScope;\n\t\tlet routeFiles = 0;\n\t\tlet liveRoutes = 0;\n\t\tlet staleRoutes = 0;\n\t\tlet unknownOwnerRoutes = 0;\n\t\tlet corruptRouteFiles = 0;\n\t\tlet diagnostics = 0;\n\t\tfor (const filename of files) {\n\t\t\tconst dispatchFileId = dispatchFileIdFromFilename(filename);\n\t\t\tif (dispatchFileId === null) continue;\n\t\t\trouteFiles += 1;\n\t\t\tlet body: string;\n\t\t\ttry {\n\t\t\t\tbody = readFileSync(join(profile.dispatchDir, filename), 'utf8');\n\t\t\t} catch {\n\t\t\t\tcorruptRouteFiles += 1;\n\t\t\t\tunknownOwnerRoutes += 1;\n\t\t\t\tdiagnostics += 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst parsed = parseDispatchRouteFile(body, dispatchFileId);\n\t\t\tdiagnostics += parsed.diagnostics.length;\n\t\t\tif (parsed._tag === 'invalid') {\n\t\t\t\tcorruptRouteFiles += 1;\n\t\t\t\tunknownOwnerRoutes += 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (parsed.route.lease === null) {\n\t\t\t\tunknownOwnerRoutes += 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst leaseStatus = yield* probe\n\t\t\t\t.probeHolderLiveness(parsed.route.lease.owner)\n\t\t\t\t.pipe(Effect.catch(() => Effect.succeed('alive' as const)));\n\t\t\tif (leaseStatus === 'dead') staleRoutes += 1;\n\t\t\telse liveRoutes += 1;\n\t\t}\n\t\tconst safeToPrune = liveRoutes === 0 && unknownOwnerRoutes === 0 && corruptRouteFiles === 0;\n\t\treturn {\n\t\t\tstatus: 'ok' as const,\n\t\t\tfiles: routeFiles,\n\t\t\tliveRoutes,\n\t\t\tstaleRoutes,\n\t\t\tunknownOwnerRoutes,\n\t\t\tcorruptRouteFiles,\n\t\t\tdiagnostics,\n\t\t\tsafeToPrune,\n\t\t};\n\t}).pipe(Effect.provide(layerLivenessProbeScope));\n\nconst inspectRouterStateDir = (profile: RouterProfile): 'absent' | 'present' | 'not-directory' => {\n\tif (!existsSync(profile.stateDir)) return 'absent';\n\ttry {\n\t\treturn statSync(profile.stateDir).isDirectory() ? 'present' : 'not-directory';\n\t} catch {\n\t\treturn 'not-directory';\n\t}\n};\n\nconst summarizeRouterContainer = (container: RouterContainerStatus): string => {\n\tif (container.status !== 'present') return container.status;\n\treturn [\n\t\tcontainer.running === true ? 'running' : 'stopped',\n\t\t`labels=${container.labelsMatch === true ? 'ok' : 'mismatch'}`,\n\t\t`network=${container.attachedToNetwork === true ? 'attached' : 'missing'}`,\n\t\t`ports=${(container.publishedPorts ?? []).join(',') || 'none'}`,\n\t].join('/');\n};\n\nexport const routerProfileProbe = (options: RouterProfileProbeOptions = {}): Probe => ({\n\tname: 'router-profile',\n\tdescription: 'router profile state, dispatch leases, and entrypoint listeners',\n\trequired: false,\n\trun: () =>\n\t\tEffect.gen(function* () {\n\t\t\tconst profile = options.profile ?? makeDefaultRouterProfile();\n\t\t\tconst entrypoints = options.entrypoints ?? BUILT_IN_ENTRYPOINTS;\n\t\t\tconst command = options.command ?? captureCommand;\n\t\t\tconst probePort = options.probePort ?? probePortFree;\n\t\t\tconst ports = uniqueSortedEntrypointPorts(entrypoints);\n\t\t\tconst stateDirStatus = inspectRouterStateDir(profile);\n\t\t\tconst dispatch = yield* inspectRouterDispatch(profile);\n\t\t\tconst container = inspectRouterContainer(profile, command);\n\t\t\tconst network = inspectRouterNetwork(profile, command);\n\t\t\tconst listenerResults = yield* Effect.tryPromise({\n\t\t\t\ttry: () =>\n\t\t\t\t\tPromise.all(\n\t\t\t\t\t\tports.map(async (port) => ({\n\t\t\t\t\t\t\tport,\n\t\t\t\t\t\t\tfree: await probePort(port),\n\t\t\t\t\t\t})),\n\t\t\t\t\t),\n\t\t\t\tcatch: () => 'router entrypoint listener probe failed',\n\t\t\t}).pipe(Effect.catch(() => Effect.succeed(ports.map((port) => ({ port, free: true })))));\n\t\t\tconst freePorts = listenerResults.filter((r) => r.free).map((r) => r.port);\n\t\t\tconst occupiedPorts = listenerResults.filter((r) => !r.free).map((r) => r.port);\n\t\t\tconst protectedRoutes =\n\t\t\t\tdispatch.liveRoutes + dispatch.unknownOwnerRoutes + dispatch.corruptRouteFiles;\n\t\t\tconst problems: string[] = [];\n\t\t\tif (stateDirStatus === 'not-directory')\n\t\t\t\tproblems.push(`${profile.stateDir} is not a directory`);\n\t\t\tif (dispatch.status === 'not-directory' || dispatch.status === 'unreadable') {\n\t\t\t\tproblems.push(`dispatch dir is ${dispatch.status}`);\n\t\t\t}\n\t\t\tif (dispatch.unknownOwnerRoutes > 0 || dispatch.corruptRouteFiles > 0) {\n\t\t\t\tproblems.push(\n\t\t\t\t\t`unknown/corrupt dispatch leases=${dispatch.unknownOwnerRoutes + dispatch.corruptRouteFiles}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (dispatch.staleRoutes > 0) problems.push(`stale dispatch leases=${dispatch.staleRoutes}`);\n\t\t\tif (protectedRoutes > 0 && (container.status !== 'present' || container.running !== true)) {\n\t\t\t\tproblems.push('protected dispatch leases exist without a running router container');\n\t\t\t}\n\t\t\tif (container.status === 'invalid' || container.status === 'unavailable') {\n\t\t\t\tproblems.push(\n\t\t\t\t\t`router container inspect ${container.status}: ${container.detail ?? 'unknown'}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (container.status === 'present') {\n\t\t\t\tif (container.labelsMatch !== true)\n\t\t\t\t\tproblems.push('router container labels do not match profile');\n\t\t\t\tif (container.attachedToNetwork !== true) {\n\t\t\t\t\tproblems.push('router container is not attached to profile network');\n\t\t\t\t}\n\t\t\t\tif (container.running === true && freePorts.length > 0) {\n\t\t\t\t\tproblems.push(`router entrypoint listeners missing: ${freePorts.join(', ')}`);\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (container.status !== 'present' && occupiedPorts.length > 0) {\n\t\t\t\tproblems.push(\n\t\t\t\t\t`router entrypoint ports already in use without profile container: ${occupiedPorts.join(', ')}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (network.status === 'invalid' || network.status === 'unavailable') {\n\t\t\t\tproblems.push(`router network inspect ${network.status}: ${network.detail ?? 'unknown'}`);\n\t\t\t}\n\t\t\tconst detail = [\n\t\t\t\t`profile=${profile.id}`,\n\t\t\t\t`state=${stateDirStatus}`,\n\t\t\t\t`dispatch=${dispatch.status}:files=${dispatch.files},live=${dispatch.liveRoutes},stale=${dispatch.staleRoutes},unknown=${dispatch.unknownOwnerRoutes},corrupt=${dispatch.corruptRouteFiles},diagnostics=${dispatch.diagnostics},pruneSafe=${dispatch.safeToPrune ? 'yes' : 'no'}`,\n\t\t\t\t`container=${summarizeRouterContainer(container)}`,\n\t\t\t\t`network=${network.status}`,\n\t\t\t\t`entrypoints=${ports.join(', ') || 'none'}`,\n\t\t\t].join('; ');\n\t\t\tif (problems.length === 0) return okOutcome(detail);\n\t\t\treturn {\n\t\t\t\tstatus: 'warn' as const,\n\t\t\t\tdetail: `${detail}; ${problems.join('; ')}`,\n\t\t\t};\n\t\t}),\n});\n\n/** Probe: list orphaned stack locks under `<runtimeRoot>/<app>/`. A\n *  stack lock whose owner PID is dead is a stale-lock candidate that\n *  `--clean-locks` would reclaim. */\nexport const locksProbe = (appRoot: string): Probe => ({\n\tname: 'locks',\n\tdescription: 'stale cross-process locks',\n\trequired: false,\n\trun: () =>\n\t\tEffect.gen(function* () {\n\t\t\tif (!existsSync(appRoot)) return okOutcome('(no app root yet)');\n\t\t\tconst ownHost = nodeHostname();\n\t\t\t// Yield a fresh `LivenessProbeScope` so a single pid that\n\t\t\t// shows up in multiple stack rosters under this app root is\n\t\t\t// probed AT MOST once across the full lock scan.\n\t\t\tconst probe = yield* LivenessProbeScope;\n\t\t\tlet orphans = 0;\n\t\t\tlet totalLive = 0;\n\t\t\ttry {\n\t\t\t\tfor (const entry of readdirSync(appRoot)) {\n\t\t\t\t\tif (entry.startsWith('.')) continue;\n\t\t\t\t\tconst stackRoot = join(appRoot, entry);\n\t\t\t\t\ttry {\n\t\t\t\t\t\tif (!statSync(stackRoot).isDirectory()) continue;\n\t\t\t\t\t} catch {\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\tconst rosterFile = join(stackRoot, 'roster.json');\n\t\t\t\t\tif (!existsSync(rosterFile)) continue;\n\t\t\t\t\tconst doc = yield* readRoster(rosterFile).pipe(\n\t\t\t\t\t\tEffect.catch(() =>\n\t\t\t\t\t\t\tEffect.succeed({ version: 1 as const, holders: [] as RosterHolder[] }),\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t\tfor (const holder of doc.holders) {\n\t\t\t\t\t\tconst liveness = yield* probe\n\t\t\t\t\t\t\t.probeHolderLiveness(holder, ownHost)\n\t\t\t\t\t\t\t.pipe(Effect.catch(() => Effect.succeed('alive' as const)));\n\t\t\t\t\t\tif (liveness === 'alive') totalLive += 1;\n\t\t\t\t\t\telse orphans += 1;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} catch (cause) {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: 'warn' as const,\n\t\t\t\t\tdetail: `lock scan failed: ${cause instanceof Error ? cause.message : String(cause)}`,\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (orphans === 0) {\n\t\t\t\treturn okOutcome(`${totalLive} live, 0 orphan`);\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tstatus: 'warn' as const,\n\t\t\t\tdetail: `${orphans} orphan holder(s); rerun with --clean-locks`,\n\t\t\t};\n\t\t}).pipe(Effect.provide(layerLivenessProbeScope)),\n});\n\n/** Probe: state-dir is writable. Validates DEVSTACK_STATE_DIR resolves\n *  to a usable path (or the default ~/.devstack does). */\nexport const stateDirProbe = (stateDir: string): Probe => ({\n\tname: 'state-dir',\n\tdescription: 'state directory',\n\trequired: true,\n\trun: () =>\n\t\tEffect.sync(() => {\n\t\t\tif (!existsSync(stateDir)) {\n\t\t\t\treturn okOutcome(`${stateDir} (will be created)`);\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tconst s = statSync(stateDir);\n\t\t\t\tif (!s.isDirectory()) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tstatus: 'fail',\n\t\t\t\t\t\tdetail: `${stateDir} is not a directory`,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\treturn okOutcome(stateDir);\n\t\t\t} catch (cause) {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: 'fail',\n\t\t\t\t\tdetail: cause instanceof Error ? cause.message : String(cause),\n\t\t\t\t};\n\t\t\t}\n\t\t}),\n});\n\n/** Probe: optional fork-cache directory inspection. Returns the size\n *  of the cache (informational). */\nexport const forkCacheProbe = (appRoot: string): Probe => ({\n\tname: 'fork-cache',\n\tdescription: 'sui-fork cache',\n\trequired: false,\n\trun: () =>\n\t\tEffect.sync(() => {\n\t\t\tconst cacheDir = join(appRoot, '.fork-cache');\n\t\t\tif (!existsSync(cacheDir)) return okOutcome('(absent)');\n\t\t\ttry {\n\t\t\t\tconst size = countTreeSize(cacheDir);\n\t\t\t\treturn okOutcome(`${size} entries`);\n\t\t\t} catch {\n\t\t\t\treturn { status: 'warn', detail: 'fork cache scan failed' };\n\t\t\t}\n\t\t}),\n});\n\nconst countTreeSize = (dir: string, depth = 0): number => {\n\tif (depth > 3) return 0;\n\tlet n = 0;\n\tfor (const entry of readdirSync(dir)) {\n\t\tconst p = join(dir, entry);\n\t\ttry {\n\t\t\tconst s = statSync(p);\n\t\t\tif (s.isFile()) n += 1;\n\t\t\telse if (s.isDirectory()) n += countTreeSize(p, depth + 1);\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t}\n\treturn n;\n};\n\n/** Default probe set. `cli/main.ts` composes this with the resolved\n *  app root, runtime state dir, router profile, and router entrypoints. */\nexport const defaultProbes = (params: {\n\treadonly stateDir: string;\n\treadonly appRoot: string;\n\treadonly routerProfile?: RouterProfile;\n\treadonly routerEntrypoints?: ReadonlyArray<Entrypoint>;\n}): ReadonlyArray<Probe> => [\n\tdockerProbe,\n\tsuiCliProbe,\n\tstateDirProbe(params.stateDir),\n\trouterProfileProbe({\n\t\t...(params.routerProfile === undefined ? {} : { profile: params.routerProfile }),\n\t\t...(params.routerEntrypoints === undefined ? {} : { entrypoints: params.routerEntrypoints }),\n\t}),\n\tlocksProbe(params.appRoot),\n\tforkCacheProbe(params.appRoot),\n];\n"],"mappings":"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"}

package/dist/cli/main.d.mts

@@ -1,5 +1,19 @@
 //#region src/cli/main.d.ts
+/** @internal Exported for tests. Resolves identity flag inputs from a
+ *  `--app <x>` / `--stack <x>` / `--network <x>` / `--state-dir <x>` /
+ *  `--config <x>` argv, falling back to `DEVSTACK_*` env vars. Throws
+ *  on a missing or flag-shaped value so a typo doesn't silently demote
+ *  a downstream flag, and on a duplicate flag (`--app a --app b`) so
+ *  the pre-parser does not silently last-write-wins a value that
+ *  Stricli will later reject outright. */
+declare const identityInputsFromArgv: (argv: ReadonlyArray<string>, env: Readonly<Record<string, string | undefined>>) => {
+  app: string | undefined;
+  stack: string | undefined;
+  network: string | undefined;
+  stateDir: string | undefined;
+  configPath: string | undefined;
+};
 declare const runCli: (argv?: ReadonlyArray<string>) => Promise<void>;
 //#endregion
-export { runCli };
+export { identityInputsFromArgv, runCli };
 //# sourceMappingURL=main.d.mts.map