@mysten-incubation/devstack 0.0.1 → 0.1.0

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

@@ -1,6 +1,13 @@
+import { WALLET_AUTH_HEADER, WALLET_BEARER_PREFIX, WALLET_ENDPOINT_KEY, WALLET_ENDPOINT_NAME, WALLET_PROTOCOL_PREFIX, WALLET_TOKEN_FRAGMENT_KEY, WALLET_TOKEN_HEX_LENGTH, WalletHttpPath } from "../../contracts/wallet-protocol.mjs";
+import { ManifestEnvelopeSchema } from "../../substrate/manifest.mjs";
+import { DEFAULT_DISCOVERY_STACK, DEFAULT_DISCOVERY_STATE_DIR, DISCOVERY_ENV, resolveDiscoveryEnv } from "./resolve-discovery-env.mjs";
 import { ManifestDiscoveryError, ManifestShapeError, NoConventionalRouteError } from "./errors.mjs";
-import { DEFAULT_STACK, DEFAULT_STATE_DIR, discoverBuildIntegrationIdentity, discoverManifestPath, readAppName, readAppNameWalkup } from "./discover.mjs";
+import { DEFAULT_STACK, DEFAULT_STATE_DIR, discoverManifestPath, discoverSingleStackManifestPath, readAppName, readAppNameWalkup } from "./discover.mjs";
+import "./manifest-types.mjs";
 import { EndpointRegistry } from "./endpoint-registry.mjs";
 import { CONSUMER_MANIFEST_VERSION, manifestEnvelopeFromStackContext, readStackContext } from "./read-stack-context.mjs";
 import { coldStartUrl, conventionalRouteHost, conventionalRouteUrl, conventionalRoutesFromHints, tryColdStartUrl } from "./cold-start-url.mjs";
-export { CONSUMER_MANIFEST_VERSION, DEFAULT_STACK, DEFAULT_STATE_DIR, EndpointRegistry, ManifestDiscoveryError, ManifestShapeError, NoConventionalRouteError, coldStartUrl, conventionalRouteHost, conventionalRouteUrl, conventionalRoutesFromHints, discoverBuildIntegrationIdentity, discoverManifestPath, manifestEnvelopeFromStackContext, readAppName, readAppNameWalkup, readStackContext, tryColdStartUrl };
+import "./wallet-paths.mjs";
+import { BUILT_IN_CONVENTIONAL_HINTS, BUILT_IN_ENDPOINT_ALIASES, DEFAULT_ROUTER_ENTRYPOINT_PORT, builtInConventionalRoutes, resolveBuiltInEndpointAlias } from "./conventional-routes.mjs";
+import { PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY } from "./playwright-stack-context-slot.mjs";
+export { BUILT_IN_CONVENTIONAL_HINTS, BUILT_IN_ENDPOINT_ALIASES, CONSUMER_MANIFEST_VERSION, DEFAULT_DISCOVERY_STACK, DEFAULT_DISCOVERY_STATE_DIR, DEFAULT_ROUTER_ENTRYPOINT_PORT, DEFAULT_STACK, DEFAULT_STATE_DIR, DISCOVERY_ENV, EndpointRegistry, ManifestDiscoveryError, ManifestEnvelopeSchema, ManifestShapeError, NoConventionalRouteError, PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY, WALLET_AUTH_HEADER, WALLET_BEARER_PREFIX, WALLET_ENDPOINT_KEY, WALLET_ENDPOINT_NAME, WALLET_PROTOCOL_PREFIX, WALLET_TOKEN_FRAGMENT_KEY, WALLET_TOKEN_HEX_LENGTH, WalletHttpPath, builtInConventionalRoutes, coldStartUrl, conventionalRouteHost, conventionalRouteUrl, conventionalRoutesFromHints, discoverManifestPath, discoverSingleStackManifestPath, manifestEnvelopeFromStackContext, readAppName, readAppNameWalkup, readStackContext, resolveBuiltInEndpointAlias, resolveDiscoveryEnv, tryColdStartUrl };

package/dist/build-integrations/runtime/manifest-types.d.mts

@@ -0,0 +1,2 @@
+import { EndpointEntry, ManifestEnvelope, ManifestEnvelopeSchema } from "../../substrate/manifest.mjs";
+import { decodeUnknownSync, parseJsonTextSync } from "../../substrate/runtime/runtime-decode.mjs";

package/dist/build-integrations/runtime/manifest-types.mjs

@@ -0,0 +1,3 @@
+import "../../substrate/runtime/runtime-decode.mjs";
+import "../../substrate/manifest.mjs";
+export {};

package/dist/build-integrations/runtime/playwright-stack-context-slot.d.mts

@@ -0,0 +1,29 @@
+//#region src/build-integrations/runtime/playwright-stack-context-slot.d.ts
+/** The literal property name on `globalThis` that global-setup writes
+ *  the prewarmed stack fixture to. In-spec helpers read from here when
+ *  present; absent => global-setup didn't run (user opted out via
+ *  `globalSetup: null`). */
+declare const PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY: "__devstackPlaywrightStackContext__";
+/** Prewarmed stack fixture shape. Mirrors what global-setup builds from
+ *  the manifest read; in-spec helpers consume it as a frozen view.
+ *
+ *  `generation` is a monotonically-increasing token stamped each time
+ *  global-setup populates the slot. Downstream readers can compare
+ *  against a previously-cached generation to detect a stale view (e.g.
+ *  Playwright retried with `reuseExistingServer:false`, which re-runs
+ *  global-setup; helpers caching the fixture across spec files would
+ *  otherwise hold a fixture pointing at a torn-down stack). */
+interface PlaywrightStackFixture {
+  readonly endpoints: Readonly<Record<string, string>>;
+  readonly walletEndpoint: string | null;
+  readonly manifestPath: string;
+  readonly stack: string;
+  readonly app: string;
+  readonly generation: number;
+}
+declare global {
+  var __devstackPlaywrightStackContext__: PlaywrightStackFixture | undefined;
+}
+//#endregion
+export { PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY, PlaywrightStackFixture };
+//# sourceMappingURL=playwright-stack-context-slot.d.mts.map

package/dist/build-integrations/runtime/playwright-stack-context-slot.mjs

@@ -0,0 +1,10 @@
+//#region src/build-integrations/runtime/playwright-stack-context-slot.ts
+/** The literal property name on `globalThis` that global-setup writes
+*  the prewarmed stack fixture to. In-spec helpers read from here when
+*  present; absent => global-setup didn't run (user opted out via
+*  `globalSetup: null`). */
+const PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY = "__devstackPlaywrightStackContext__";
+//#endregion
+export { PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY };
+
+//# sourceMappingURL=playwright-stack-context-slot.mjs.map

package/dist/build-integrations/runtime/playwright-stack-context-slot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-stack-context-slot.mjs","names":[],"sources":["../../../src/build-integrations/runtime/playwright-stack-context-slot.ts"],"sourcesContent":["// Typed contract for the `globalThis.__devstackPlaywrightStackContext__`\n// fixture slot Playwright global-setup populates.\n//\n// Sibling to `dapp-kit-slot.ts` — one slot ownership per consumer keeps\n// the typed `declare global` block minimal and lets the playwright\n// surface import only what it needs.\n//\n// The slot's NAME is part of the cross-process contract: in-spec helpers\n// (`wallet-context.ts`, fixture readers) look up `globalThis[KEY]` to\n// avoid repeating the manifest disk read in every worker. Renames cascade\n// through every consumer.\n//\n// This module evaluates in Node build-integration callers only — Playwright\n// global-setup runs server-side. No `node:*` imports here so it stays\n// importable from any TS context.\n\n/** The literal property name on `globalThis` that global-setup writes\n *  the prewarmed stack fixture to. In-spec helpers read from here when\n *  present; absent => global-setup didn't run (user opted out via\n *  `globalSetup: null`). */\nexport const PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY = '__devstackPlaywrightStackContext__' as const;\n\n/** Prewarmed stack fixture shape. Mirrors what global-setup builds from\n *  the manifest read; in-spec helpers consume it as a frozen view.\n *\n *  `generation` is a monotonically-increasing token stamped each time\n *  global-setup populates the slot. Downstream readers can compare\n *  against a previously-cached generation to detect a stale view (e.g.\n *  Playwright retried with `reuseExistingServer:false`, which re-runs\n *  global-setup; helpers caching the fixture across spec files would\n *  otherwise hold a fixture pointing at a torn-down stack). */\nexport interface PlaywrightStackFixture {\n\treadonly endpoints: Readonly<Record<string, string>>;\n\treadonly walletEndpoint: string | null;\n\treadonly manifestPath: string;\n\treadonly stack: string;\n\treadonly app: string;\n\treadonly generation: number;\n}\n\ndeclare global {\n\t// eslint-disable-next-line no-var\n\tvar __devstackPlaywrightStackContext__: PlaywrightStackFixture | undefined;\n}\n"],"mappings":";;;;;AAoBA,MAAa,oCAAoC"}

package/dist/build-integrations/runtime/read-stack-context.d.mts

@@ -1,5 +1,5 @@
-import { ManifestEnvelope } from "../../substrate/manifest.mjs";
 import { DiscoverManifestPathOptions } from "./discover.mjs";
+import { ManifestEnvelope } from "../../substrate/manifest.mjs";
 import { StackContext } from "./stack-context.mjs";
 
 //#region src/build-integrations/runtime/read-stack-context.d.ts

package/dist/build-integrations/runtime/read-stack-context.mjs

@@ -1,8 +1,9 @@
+import { decodeUnknownSync, parseJsonTextSync } from "../../substrate/runtime/runtime-decode.mjs";
 import { ManifestEnvelopeSchema } from "../../substrate/manifest.mjs";
 import { ManifestDiscoveryError, ManifestShapeError } from "./errors.mjs";
 import { discoverManifestPath } from "./discover.mjs";
+import "./manifest-types.mjs";
 import { EndpointRegistry } from "./endpoint-registry.mjs";
-import { Schema } from "effect";
 import { readFileSync } from "node:fs";
 //#region src/build-integrations/runtime/read-stack-context.ts
 /** Pinned manifest-envelope version this consumer build was compiled
@@ -12,7 +13,6 @@ import { readFileSync } from "node:fs";
 *  bumps, the consumer must bump in lockstep — the version mismatch
 *  error message names the recovery recipe. */
 const CONSUMER_MANIFEST_VERSION = 1;
-const decodeEnvelope = Schema.decodeUnknownSync(ManifestEnvelopeSchema);
 const resolveManifestPath = (opts) => {
 	const override = opts.manifestPath ?? opts.override;
 	const resolved = discoverManifestPath({
@@ -29,7 +29,10 @@ const resolveManifestPath = (opts) => {
 const parseAndDecode = (raw, manifestPath) => {
 	let parsed;
 	try {
-		parsed = JSON.parse(raw);
+		parsed = parseJsonTextSync(raw, {
+			source: manifestPath,
+			mkError: (issue) => issue
+		});
 	} catch (cause) {
 		throw new ManifestShapeError({
 			phase: "parse",
@@ -40,7 +43,10 @@ const parseAndDecode = (raw, manifestPath) => {
 	}
 	let decoded;
 	try {
-		decoded = decodeEnvelope(parsed);
+		decoded = decodeUnknownSync(ManifestEnvelopeSchema, parsed, {
+			source: manifestPath,
+			mkError: (issue) => issue
+		});
 	} catch (cause) {
 		throw new ManifestShapeError({
 			phase: "shape",

package/dist/build-integrations/runtime/read-stack-context.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"read-stack-context.mjs","names":[],"sources":["../../../src/build-integrations/runtime/read-stack-context.ts"],"sourcesContent":["// Sync manifest reader + projection.\n//\n// Read-side L5 surface. Loads the manifest envelope from disk,\n// validates it via the substrate's `ManifestEnvelopeSchema`, and\n// projects it to a plain TS `StackContext` consumer code can use\n// without depending on Effect or Schema.\n//\n// Sync — apps and Playwright config-load are sync surfaces. The cost\n// is one `readFileSync` and one synchronous Schema decode.\n//\n// Error contract:\n//\n//   - Missing manifest → `ManifestDiscoveryError` (with `phase`).\n//   - Manifest exists but `JSON.parse` rejected the bytes →\n//     `ManifestShapeError(phase: 'parse')`.\n//   - Manifest parsed but failed schema validation →\n//     `ManifestShapeError(phase: 'shape')`.\n//   - Manifest decoded but `manifestVersion` doesn't match the\n//     consumer's pinned `CURRENT_MANIFEST_VERSION` →\n//     `ManifestShapeError(phase: 'version')`.\n//\n// All three are plain `Error` subclasses (see `./errors.ts`) so the\n// caller's try / catch / instanceof flow works without importing\n// Effect. The CLI / codegen surfaces can still wrap this function in\n// `Effect.try` to lift the failure channel.\n//\n// Implementation detail: we use Effect Schema INTERNALLY for the\n// envelope decode (`ManifestEnvelopeSchema` lives in the substrate),\n// but the API surface is plain TS. Schema is a validation tool here,\n// not an exposed type.\n\nimport { Schema } from 'effect';\nimport { readFileSync } from 'node:fs';\n\nimport { ManifestEnvelopeSchema, type ManifestEnvelope } from '../../substrate/manifest.ts';\nimport { discoverManifestPath, type DiscoverManifestPathOptions } from './discover.ts';\nimport { EndpointRegistry } from './endpoint-registry.ts';\nimport { ManifestDiscoveryError, ManifestShapeError } from './errors.ts';\nimport type { ResolvedEndpoint, StackContext } from './stack-context.ts';\n\n/** Pinned manifest-envelope version this consumer build was compiled\n *  against. Must match the substrate's `CURRENT_MANIFEST_VERSION`\n *  (kept as a literal here so the read path doesn't reach into the\n *  substrate's writer module just for a number). When the substrate\n *  bumps, the consumer must bump in lockstep — the version mismatch\n *  error message names the recovery recipe. */\nexport const CONSUMER_MANIFEST_VERSION = 1 as const;\n\nexport interface ReadStackContextOptions extends DiscoverManifestPathOptions {\n\t/** Caller-supplied explicit manifest path. When set, bypasses the\n\t *  walk-up (still existence-checked). Named `manifestPath` for\n\t *  ergonomic parity with the CLI's `--manifest-path` flag. */\n\treadonly manifestPath?: string;\n}\n\n// Pre-build the decoder so each read isn't paying the Schema-build\n// cost. `decodeUnknownSync` throws on shape failure; we catch + rewrap.\nconst decodeEnvelope = Schema.decodeUnknownSync(ManifestEnvelopeSchema);\n\nconst resolveManifestPath = (opts: ReadStackContextOptions): string => {\n\tconst override = opts.manifestPath ?? opts.override;\n\tconst resolved = discoverManifestPath({\n\t\t...opts,\n\t\t...(override !== undefined ? { override } : {}),\n\t\trequired: true,\n\t});\n\t// `required: true` throws on miss; this branch is unreachable but\n\t// keeps the type narrow without an `!`.\n\tif (resolved === undefined) {\n\t\tthrow new ManifestDiscoveryError({\n\t\t\tphase: 'required-missing',\n\t\t\tmessage: '[devstack] manifest discovery returned undefined despite required: true',\n\t\t});\n\t}\n\treturn resolved;\n};\n\nconst parseAndDecode = (raw: string, manifestPath: string): ManifestEnvelope => {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch (cause) {\n\t\tthrow new ManifestShapeError({\n\t\t\tphase: 'parse',\n\t\t\tpath: manifestPath,\n\t\t\tmessage:\n\t\t\t\t`[devstack] manifest at ${manifestPath} is not valid JSON ` +\n\t\t\t\t`(truncation or hand-edit). ` +\n\t\t\t\t`RECOVERY: \\`rm ${manifestPath} && devstack up\\` to regenerate.`,\n\t\t\tcause,\n\t\t});\n\t}\n\tlet decoded: ManifestEnvelope;\n\ttry {\n\t\tdecoded = decodeEnvelope(parsed) as ManifestEnvelope;\n\t} catch (cause) {\n\t\tthrow new ManifestShapeError({\n\t\t\tphase: 'shape',\n\t\t\tpath: manifestPath,\n\t\t\tmessage:\n\t\t\t\t`[devstack] manifest at ${manifestPath} does not match the manifest envelope schema ` +\n\t\t\t\t`(stale shape or hand-edit). ` +\n\t\t\t\t`RECOVERY: \\`rm ${manifestPath} && devstack up\\` to regenerate.`,\n\t\t\tcause,\n\t\t});\n\t}\n\tif (decoded.manifestVersion !== CONSUMER_MANIFEST_VERSION) {\n\t\tthrow new ManifestShapeError({\n\t\t\tphase: 'version',\n\t\t\tpath: manifestPath,\n\t\t\tmessage:\n\t\t\t\t`[devstack] manifest at ${manifestPath} has version ${decoded.manifestVersion}, ` +\n\t\t\t\t`but this consumer was built for version ${CONSUMER_MANIFEST_VERSION}. ` +\n\t\t\t\t`RECOVERY: upgrade your devstack consumer dependency, or \\`rm ${manifestPath} && devstack up\\` ` +\n\t\t\t\t`to regenerate against the new version.`,\n\t\t});\n\t}\n\treturn decoded;\n};\n\n/** Project the decoded envelope to a plain `StackContext`. */\nconst project = (envelope: ManifestEnvelope, manifestPath: string): StackContext => {\n\tconst entries: ResolvedEndpoint[] = [];\n\tfor (const raw of Object.values(envelope.endpoints)) {\n\t\tentries.push({\n\t\t\tname: raw.name,\n\t\t\turl: raw.url,\n\t\t\tdisplayUrl: raw.displayUrl,\n\t\t\twireProtocol: raw.wireProtocol,\n\t\t\tpluginKey: raw.pluginKey as string,\n\t\t\tendpointKey: raw.endpointKey as string,\n\t\t});\n\t}\n\treturn {\n\t\tidentity: {\n\t\t\tapp: envelope.identity.app,\n\t\t\tstack: envelope.identity.stack,\n\t\t\tchain: envelope.identity.chain,\n\t\t},\n\t\tmanifestPath,\n\t\tmanifestVersion: envelope.manifestVersion,\n\t\tendpoints: new EndpointRegistry(entries),\n\t\tservices: envelope.services,\n\t\textras: envelope.extras,\n\t};\n};\n\n/** Reconstruct the manifest envelope from the runtime projection.\n *  Integration adapters that preserve their older envelope-shaped\n *  surfaces use this instead of duplicating endpoint-registry\n *  projection logic. */\nexport const manifestEnvelopeFromStackContext = (ctx: StackContext): ManifestEnvelope => ({\n\tidentity: ctx.identity as ManifestEnvelope['identity'],\n\tmanifestVersion: ctx.manifestVersion,\n\tservices: ctx.services,\n\tendpoints: Object.fromEntries(\n\t\tctx.endpoints.all().map((e) => [\n\t\t\te.endpointKey,\n\t\t\t{\n\t\t\t\tname: e.name,\n\t\t\t\turl: e.url,\n\t\t\t\tdisplayUrl: e.displayUrl,\n\t\t\t\twireProtocol: e.wireProtocol,\n\t\t\t\tpluginKey: e.pluginKey as never,\n\t\t\t\tendpointKey: e.endpointKey as never,\n\t\t\t},\n\t\t]),\n\t) as ManifestEnvelope['endpoints'],\n\textras: ctx.extras,\n});\n\n/**\n * Sync read + decode + project. Throws `ManifestDiscoveryError` (no\n * manifest located) or `ManifestShapeError` (manifest found but\n * malformed / wrong version).\n *\n * Used by:\n *   - Apps' generated `stack-handle.ts` at startup.\n *   - Playwright config-load (`baseURL`, `webServer.url`).\n *   - CLI surfaces that prefer sync-then-Effect.try over a native\n *     Effect read.\n */\nexport const readStackContext = (opts: ReadStackContextOptions = {}): StackContext => {\n\tconst manifestPath = resolveManifestPath(opts);\n\tlet raw: string;\n\ttry {\n\t\traw = readFileSync(manifestPath, 'utf8');\n\t} catch (cause) {\n\t\t// File existed at discovery time but is unreadable now — race\n\t\t// with the supervisor's atomic-write would be a parse failure on\n\t\t// the next read; a true EACCES / disk-disconnect surfaces here.\n\t\tthrow new ManifestShapeError({\n\t\t\tphase: 'parse',\n\t\t\tpath: manifestPath,\n\t\t\tmessage: `[devstack] failed to read manifest at ${manifestPath}: ${String(cause)}`,\n\t\t\tcause,\n\t\t});\n\t}\n\tconst envelope = parseAndDecode(raw, manifestPath);\n\treturn project(envelope, manifestPath);\n};\n"],"mappings":";;;;;;;;;;;;;AA8CA,MAAa,4BAA4B;AAWzC,MAAM,iBAAiB,OAAO,kBAAkB,uBAAuB;AAEvE,MAAM,uBAAuB,SAA0C;CACtE,MAAM,WAAW,KAAK,gBAAgB,KAAK;CAC3C,MAAM,WAAW,qBAAqB;EACrC,GAAG;EACH,GAAI,aAAa,KAAA,IAAY,EAAE,UAAU,GAAG,EAAE;EAC9C,UAAU;EACV,CAAC;AAGF,KAAI,aAAa,KAAA,EAChB,OAAM,IAAI,uBAAuB;EAChC,OAAO;EACP,SAAS;EACT,CAAC;AAEH,QAAO;;AAGR,MAAM,kBAAkB,KAAa,iBAA2C;CAC/E,IAAI;AACJ,KAAI;AACH,WAAS,KAAK,MAAM,IAAI;UAChB,OAAO;AACf,QAAM,IAAI,mBAAmB;GAC5B,OAAO;GACP,MAAM;GACN,SACC,0BAA0B,aAAa,+DAErB,aAAa;GAChC;GACA,CAAC;;CAEH,IAAI;AACJ,KAAI;AACH,YAAU,eAAe,OAAO;UACxB,OAAO;AACf,QAAM,IAAI,mBAAmB;GAC5B,OAAO;GACP,MAAM;GACN,SACC,0BAA0B,aAAa,0FAErB,aAAa;GAChC;GACA,CAAC;;AAEH,KAAI,QAAQ,oBAAA,EACX,OAAM,IAAI,mBAAmB;EAC5B,OAAO;EACP,MAAM;EACN,SACC,0BAA0B,aAAa,eAAe,QAAQ,gBAAgB,4GAEd,aAAa;EAE9E,CAAC;AAEH,QAAO;;;AAIR,MAAM,WAAW,UAA4B,iBAAuC;CACnF,MAAM,UAA8B,EAAE;AACtC,MAAK,MAAM,OAAO,OAAO,OAAO,SAAS,UAAU,CAClD,SAAQ,KAAK;EACZ,MAAM,IAAI;EACV,KAAK,IAAI;EACT,YAAY,IAAI;EAChB,cAAc,IAAI;EAClB,WAAW,IAAI;EACf,aAAa,IAAI;EACjB,CAAC;AAEH,QAAO;EACN,UAAU;GACT,KAAK,SAAS,SAAS;GACvB,OAAO,SAAS,SAAS;GACzB,OAAO,SAAS,SAAS;GACzB;EACD;EACA,iBAAiB,SAAS;EAC1B,WAAW,IAAI,iBAAiB,QAAQ;EACxC,UAAU,SAAS;EACnB,QAAQ,SAAS;EACjB;;;;;;AAOF,MAAa,oCAAoC,SAAyC;CACzF,UAAU,IAAI;CACd,iBAAiB,IAAI;CACrB,UAAU,IAAI;CACd,WAAW,OAAO,YACjB,IAAI,UAAU,KAAK,CAAC,KAAK,MAAM,CAC9B,EAAE,aACF;EACC,MAAM,EAAE;EACR,KAAK,EAAE;EACP,YAAY,EAAE;EACd,cAAc,EAAE;EAChB,WAAW,EAAE;EACb,aAAa,EAAE;EACf,CACD,CAAC,CACF;CACD,QAAQ,IAAI;CACZ;;;;;;;;;;;;AAaD,MAAa,oBAAoB,OAAgC,EAAE,KAAmB;CACrF,MAAM,eAAe,oBAAoB,KAAK;CAC9C,IAAI;AACJ,KAAI;AACH,QAAM,aAAa,cAAc,OAAO;UAChC,OAAO;AAIf,QAAM,IAAI,mBAAmB;GAC5B,OAAO;GACP,MAAM;GACN,SAAS,yCAAyC,aAAa,IAAI,OAAO,MAAM;GAChF;GACA,CAAC;;AAGH,QAAO,QADU,eAAe,KAAK,aACd,EAAE,aAAa"}
+{"version":3,"file":"read-stack-context.mjs","names":[],"sources":["../../../src/build-integrations/runtime/read-stack-context.ts"],"sourcesContent":["// Sync manifest reader + projection.\n//\n// Read-side L5 surface. Loads the manifest envelope from disk,\n// validates it via the substrate's `ManifestEnvelopeSchema`, and\n// projects it to a plain TS `StackContext` consumer code can use\n// without depending on Effect or Schema.\n//\n// Sync — apps and Playwright config-load are sync surfaces. The cost\n// is one `readFileSync` and one synchronous Schema decode.\n//\n// Error contract:\n//\n//   - Missing manifest → `ManifestDiscoveryError` (with `phase`).\n//   - Manifest exists but `JSON.parse` rejected the bytes →\n//     `ManifestShapeError(phase: 'parse')`.\n//   - Manifest parsed but failed schema validation →\n//     `ManifestShapeError(phase: 'shape')`.\n//   - Manifest decoded but `manifestVersion` doesn't match the\n//     consumer's pinned `CURRENT_MANIFEST_VERSION` →\n//     `ManifestShapeError(phase: 'version')`.\n//\n// All three are plain `Error` subclasses (see `./errors.ts`) so the\n// caller's try / catch / instanceof flow works without importing\n// Effect. The CLI / codegen surfaces can still wrap this function in\n// `Effect.try` to lift the failure channel.\n//\n// Implementation detail: we use Effect Schema INTERNALLY for the\n// envelope decode (`ManifestEnvelopeSchema` lives in the substrate),\n// but the API surface is plain TS. Schema is a validation tool here,\n// not an exposed type.\n\nimport { readFileSync } from 'node:fs';\n\nimport {\n\tdecodeUnknownSync,\n\tManifestEnvelopeSchema,\n\tparseJsonTextSync,\n\ttype ManifestEnvelope,\n\ttype EndpointEntry,\n} from './manifest-types.ts';\nimport { discoverManifestPath, type DiscoverManifestPathOptions } from './discover.ts';\nimport { EndpointRegistry } from './endpoint-registry.ts';\nimport { ManifestDiscoveryError, ManifestShapeError } from './errors.ts';\nimport type { ResolvedEndpoint, StackContext } from './stack-context.ts';\n\n/** Pinned manifest-envelope version this consumer build was compiled\n *  against. Must match the substrate's `CURRENT_MANIFEST_VERSION`\n *  (kept as a literal here so the read path doesn't reach into the\n *  substrate's writer module just for a number). When the substrate\n *  bumps, the consumer must bump in lockstep — the version mismatch\n *  error message names the recovery recipe. */\nexport const CONSUMER_MANIFEST_VERSION = 1 as const;\n\nexport interface ReadStackContextOptions extends DiscoverManifestPathOptions {\n\t/** Caller-supplied explicit manifest path. When set, bypasses the\n\t *  walk-up (still existence-checked). Named `manifestPath` for\n\t *  ergonomic parity with the CLI's `--manifest-path` flag. */\n\treadonly manifestPath?: string;\n}\n\nconst resolveManifestPath = (opts: ReadStackContextOptions): string => {\n\tconst override = opts.manifestPath ?? opts.override;\n\tconst resolved = discoverManifestPath({\n\t\t...opts,\n\t\t...(override !== undefined ? { override } : {}),\n\t\trequired: true,\n\t});\n\t// `required: true` throws on miss; this branch is unreachable but\n\t// keeps the type narrow without an `!`.\n\tif (resolved === undefined) {\n\t\tthrow new ManifestDiscoveryError({\n\t\t\tphase: 'required-missing',\n\t\t\tmessage: '[devstack] manifest discovery returned undefined despite required: true',\n\t\t});\n\t}\n\treturn resolved;\n};\n\nconst parseAndDecode = (raw: string, manifestPath: string): ManifestEnvelope => {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = parseJsonTextSync(raw, {\n\t\t\tsource: manifestPath,\n\t\t\tmkError: (issue) => issue,\n\t\t});\n\t} catch (cause) {\n\t\tthrow new ManifestShapeError({\n\t\t\tphase: 'parse',\n\t\t\tpath: manifestPath,\n\t\t\tmessage:\n\t\t\t\t`[devstack] manifest at ${manifestPath} is not valid JSON ` +\n\t\t\t\t`(truncation or hand-edit). ` +\n\t\t\t\t`RECOVERY: \\`rm ${manifestPath} && devstack up\\` to regenerate.`,\n\t\t\tcause,\n\t\t});\n\t}\n\tlet decoded: ManifestEnvelope;\n\ttry {\n\t\tdecoded = decodeUnknownSync(ManifestEnvelopeSchema, parsed, {\n\t\t\tsource: manifestPath,\n\t\t\tmkError: (issue) => issue,\n\t\t});\n\t} catch (cause) {\n\t\tthrow new ManifestShapeError({\n\t\t\tphase: 'shape',\n\t\t\tpath: manifestPath,\n\t\t\tmessage:\n\t\t\t\t`[devstack] manifest at ${manifestPath} does not match the manifest envelope schema ` +\n\t\t\t\t`(stale shape or hand-edit). ` +\n\t\t\t\t`RECOVERY: \\`rm ${manifestPath} && devstack up\\` to regenerate.`,\n\t\t\tcause,\n\t\t});\n\t}\n\tif (decoded.manifestVersion !== CONSUMER_MANIFEST_VERSION) {\n\t\tthrow new ManifestShapeError({\n\t\t\tphase: 'version',\n\t\t\tpath: manifestPath,\n\t\t\tmessage:\n\t\t\t\t`[devstack] manifest at ${manifestPath} has version ${decoded.manifestVersion}, ` +\n\t\t\t\t`but this consumer was built for version ${CONSUMER_MANIFEST_VERSION}. ` +\n\t\t\t\t`RECOVERY: upgrade your devstack consumer dependency, or \\`rm ${manifestPath} && devstack up\\` ` +\n\t\t\t\t`to regenerate against the new version.`,\n\t\t});\n\t}\n\treturn decoded;\n};\n\n/** Project the decoded envelope to a plain `StackContext`. */\nconst project = (envelope: ManifestEnvelope, manifestPath: string): StackContext => {\n\tconst entries: ResolvedEndpoint[] = [];\n\tfor (const raw of Object.values(envelope.endpoints)) {\n\t\tentries.push({\n\t\t\tname: raw.name,\n\t\t\turl: raw.url,\n\t\t\tdisplayUrl: raw.displayUrl,\n\t\t\twireProtocol: raw.wireProtocol,\n\t\t\tpluginKey: raw.pluginKey,\n\t\t\tendpointKey: raw.endpointKey,\n\t\t});\n\t}\n\treturn {\n\t\tidentity: {\n\t\t\tapp: envelope.identity.app,\n\t\t\tstack: envelope.identity.stack,\n\t\t\tchain: envelope.identity.chain,\n\t\t},\n\t\tmanifestPath,\n\t\tmanifestVersion: envelope.manifestVersion,\n\t\tendpoints: new EndpointRegistry(entries),\n\t\tservices: envelope.services,\n\t\textras: envelope.extras,\n\t};\n};\n\n/** Reconstruct the manifest envelope from the runtime projection.\n *  Integration adapters that preserve their older envelope-shaped\n *  surfaces use this instead of duplicating endpoint-registry\n *  projection logic. */\nexport const manifestEnvelopeFromStackContext = (ctx: StackContext): ManifestEnvelope => ({\n\tidentity: ctx.identity,\n\tmanifestVersion: ctx.manifestVersion,\n\tservices: ctx.services,\n\tendpoints: Object.fromEntries(\n\t\tctx.endpoints.all().map((e): [string, EndpointEntry] => [\n\t\t\te.endpointKey,\n\t\t\t{\n\t\t\t\tname: e.name,\n\t\t\t\turl: e.url,\n\t\t\t\tdisplayUrl: e.displayUrl,\n\t\t\t\twireProtocol: e.wireProtocol,\n\t\t\t\tpluginKey: e.pluginKey,\n\t\t\t\tendpointKey: e.endpointKey,\n\t\t\t},\n\t\t]),\n\t),\n\textras: ctx.extras,\n});\n\n/**\n * Sync read + decode + project. Throws `ManifestDiscoveryError` (no\n * manifest located) or `ManifestShapeError` (manifest found but\n * malformed / wrong version).\n *\n * Used by:\n *   - Apps' generated `stack-handle.ts` at startup.\n *   - Playwright config-load (`baseURL`, `webServer.url`).\n *   - CLI surfaces that prefer sync-then-Effect.try over a native\n *     Effect read.\n */\nexport const readStackContext = (opts: ReadStackContextOptions = {}): StackContext => {\n\tconst manifestPath = resolveManifestPath(opts);\n\tlet raw: string;\n\ttry {\n\t\traw = readFileSync(manifestPath, 'utf8');\n\t} catch (cause) {\n\t\t// File existed at discovery time but is unreadable now — race\n\t\t// with the supervisor's atomic-write would be a parse failure on\n\t\t// the next read; a true EACCES / disk-disconnect surfaces here.\n\t\tthrow new ManifestShapeError({\n\t\t\tphase: 'parse',\n\t\t\tpath: manifestPath,\n\t\t\tmessage: `[devstack] failed to read manifest at ${manifestPath}: ${String(cause)}`,\n\t\t\tcause,\n\t\t});\n\t}\n\tconst envelope = parseAndDecode(raw, manifestPath);\n\treturn project(envelope, manifestPath);\n};\n"],"mappings":";;;;;;;;;;;;;;AAmDA,MAAa,4BAA4B;AASzC,MAAM,uBAAuB,SAA0C;CACtE,MAAM,WAAW,KAAK,gBAAgB,KAAK;CAC3C,MAAM,WAAW,qBAAqB;EACrC,GAAG;EACH,GAAI,aAAa,KAAA,IAAY,EAAE,UAAU,GAAG,EAAE;EAC9C,UAAU;EACV,CAAC;AAGF,KAAI,aAAa,KAAA,EAChB,OAAM,IAAI,uBAAuB;EAChC,OAAO;EACP,SAAS;EACT,CAAC;AAEH,QAAO;;AAGR,MAAM,kBAAkB,KAAa,iBAA2C;CAC/E,IAAI;AACJ,KAAI;AACH,WAAS,kBAAkB,KAAK;GAC/B,QAAQ;GACR,UAAU,UAAU;GACpB,CAAC;UACM,OAAO;AACf,QAAM,IAAI,mBAAmB;GAC5B,OAAO;GACP,MAAM;GACN,SACC,0BAA0B,aAAa,+DAErB,aAAa;GAChC;GACA,CAAC;;CAEH,IAAI;AACJ,KAAI;AACH,YAAU,kBAAkB,wBAAwB,QAAQ;GAC3D,QAAQ;GACR,UAAU,UAAU;GACpB,CAAC;UACM,OAAO;AACf,QAAM,IAAI,mBAAmB;GAC5B,OAAO;GACP,MAAM;GACN,SACC,0BAA0B,aAAa,0FAErB,aAAa;GAChC;GACA,CAAC;;AAEH,KAAI,QAAQ,oBAAA,EACX,OAAM,IAAI,mBAAmB;EAC5B,OAAO;EACP,MAAM;EACN,SACC,0BAA0B,aAAa,eAAe,QAAQ,gBAAgB,4GAEd,aAAa;EAE9E,CAAC;AAEH,QAAO;;;AAIR,MAAM,WAAW,UAA4B,iBAAuC;CACnF,MAAM,UAA8B,EAAE;AACtC,MAAK,MAAM,OAAO,OAAO,OAAO,SAAS,UAAU,CAClD,SAAQ,KAAK;EACZ,MAAM,IAAI;EACV,KAAK,IAAI;EACT,YAAY,IAAI;EAChB,cAAc,IAAI;EAClB,WAAW,IAAI;EACf,aAAa,IAAI;EACjB,CAAC;AAEH,QAAO;EACN,UAAU;GACT,KAAK,SAAS,SAAS;GACvB,OAAO,SAAS,SAAS;GACzB,OAAO,SAAS,SAAS;GACzB;EACD;EACA,iBAAiB,SAAS;EAC1B,WAAW,IAAI,iBAAiB,QAAQ;EACxC,UAAU,SAAS;EACnB,QAAQ,SAAS;EACjB;;;;;;AAOF,MAAa,oCAAoC,SAAyC;CACzF,UAAU,IAAI;CACd,iBAAiB,IAAI;CACrB,UAAU,IAAI;CACd,WAAW,OAAO,YACjB,IAAI,UAAU,KAAK,CAAC,KAAK,MAA+B,CACvD,EAAE,aACF;EACC,MAAM,EAAE;EACR,KAAK,EAAE;EACP,YAAY,EAAE;EACd,cAAc,EAAE;EAChB,WAAW,EAAE;EACb,aAAa,EAAE;EACf,CACD,CAAC,CACF;CACD,QAAQ,IAAI;CACZ;;;;;;;;;;;;AAaD,MAAa,oBAAoB,OAAgC,EAAE,KAAmB;CACrF,MAAM,eAAe,oBAAoB,KAAK;CAC9C,IAAI;AACJ,KAAI;AACH,QAAM,aAAa,cAAc,OAAO;UAChC,OAAO;AAIf,QAAM,IAAI,mBAAmB;GAC5B,OAAO;GACP,MAAM;GACN,SAAS,yCAAyC,aAAa,IAAI,OAAO,MAAM;GAChF;GACA,CAAC;;AAGH,QAAO,QADU,eAAe,KAAK,aACd,EAAE,aAAa"}

package/dist/build-integrations/runtime/resolve-discovery-env.d.mts

@@ -0,0 +1,48 @@
+//#region src/build-integrations/runtime/resolve-discovery-env.d.ts
+/** Default state-dir / runtime-root name when neither an explicit
+ *  option nor any env override is present. Mirrors `DEFAULT_STATE_DIR`
+ *  in `discover.ts` (same literal `.devstack`). */
+declare const DEFAULT_DISCOVERY_STATE_DIR = ".devstack";
+/** Default stack name when neither an explicit option nor
+ *  `$DEVSTACK_STACK` yields a value. */
+declare const DEFAULT_DISCOVERY_STACK = "main";
+/** Env-var names the discovery ladder consults for the stack +
+ *  state-dir rungs. `MANIFEST_PATH` lives here for documentation parity
+ *  with the integration env tables but is resolved by
+ *  `discoverManifestPath`, not this ladder. */
+declare const DISCOVERY_ENV: {
+  readonly STACK: "DEVSTACK_STACK";
+  readonly RUNTIME_ROOT: "DEVSTACK_RUNTIME_ROOT"; /** Legacy alias for `RUNTIME_ROOT`; lower precedence. */
+  readonly STATE_DIR: "DEVSTACK_STATE_DIR";
+  readonly MANIFEST_PATH: "DEVSTACK_MANIFEST_PATH";
+};
+interface ResolveDiscoveryEnvOptions {
+  /** Explicit stack name. Wins over `$DEVSTACK_STACK`. */
+  readonly stack?: string;
+  /** Explicit state-dir / runtime-root. Wins over both env vars. */
+  readonly stateDir?: string;
+}
+interface ResolvedDiscoveryEnv {
+  /** Resolved stack name (never empty). */
+  readonly stack: string;
+  /** Resolved state-dir / runtime-root (never empty). May be absolute
+   *  — `discoverManifestPath` degenerates the walk-up to a single
+   *  existence check in that case. */
+  readonly stateDir: string;
+}
+/**
+ * Resolve the canonical stack + state-dir ladder.
+ *
+ * Precedence (highest → lowest), identical for both rungs:
+ *   - stack:     `options.stack` > `$DEVSTACK_STACK` > `'main'`
+ *   - stateDir:  `options.stateDir` > `$DEVSTACK_RUNTIME_ROOT`
+ *                > `$DEVSTACK_STATE_DIR` > `'.devstack'`
+ *
+ * Empty-string env values are treated as unset (a blank
+ * `DEVSTACK_STATE_DIR=` must not pin the state root to the cwd). Pure —
+ * no `process.env` read; callers pass the bag (a fixture in tests).
+ */
+declare const resolveDiscoveryEnv: (env: Readonly<Record<string, string | undefined>>, options?: ResolveDiscoveryEnvOptions) => ResolvedDiscoveryEnv;
+//#endregion
+export { DEFAULT_DISCOVERY_STACK, DEFAULT_DISCOVERY_STATE_DIR, DISCOVERY_ENV, ResolveDiscoveryEnvOptions, ResolvedDiscoveryEnv, resolveDiscoveryEnv };
+//# sourceMappingURL=resolve-discovery-env.d.mts.map

package/dist/build-integrations/runtime/resolve-discovery-env.mjs

@@ -0,0 +1,42 @@
+//#region src/build-integrations/runtime/resolve-discovery-env.ts
+/** Default state-dir / runtime-root name when neither an explicit
+*  option nor any env override is present. Mirrors `DEFAULT_STATE_DIR`
+*  in `discover.ts` (same literal `.devstack`). */
+const DEFAULT_DISCOVERY_STATE_DIR = ".devstack";
+/** Default stack name when neither an explicit option nor
+*  `$DEVSTACK_STACK` yields a value. */
+const DEFAULT_DISCOVERY_STACK = "main";
+/** Env-var names the discovery ladder consults for the stack +
+*  state-dir rungs. `MANIFEST_PATH` lives here for documentation parity
+*  with the integration env tables but is resolved by
+*  `discoverManifestPath`, not this ladder. */
+const DISCOVERY_ENV = {
+	STACK: "DEVSTACK_STACK",
+	RUNTIME_ROOT: "DEVSTACK_RUNTIME_ROOT",
+	/** Legacy alias for `RUNTIME_ROOT`; lower precedence. */
+	STATE_DIR: "DEVSTACK_STATE_DIR",
+	MANIFEST_PATH: "DEVSTACK_MANIFEST_PATH"
+};
+const firstNonEmpty = (...candidates) => {
+	for (const candidate of candidates) if (candidate !== void 0 && candidate !== "") return candidate;
+};
+/**
+* Resolve the canonical stack + state-dir ladder.
+*
+* Precedence (highest → lowest), identical for both rungs:
+*   - stack:     `options.stack` > `$DEVSTACK_STACK` > `'main'`
+*   - stateDir:  `options.stateDir` > `$DEVSTACK_RUNTIME_ROOT`
+*                > `$DEVSTACK_STATE_DIR` > `'.devstack'`
+*
+* Empty-string env values are treated as unset (a blank
+* `DEVSTACK_STATE_DIR=` must not pin the state root to the cwd). Pure —
+* no `process.env` read; callers pass the bag (a fixture in tests).
+*/
+const resolveDiscoveryEnv = (env, options = {}) => ({
+	stack: firstNonEmpty(options.stack?.trim(), env[DISCOVERY_ENV.STACK]?.trim()) ?? "main",
+	stateDir: firstNonEmpty(options.stateDir, env[DISCOVERY_ENV.RUNTIME_ROOT], env[DISCOVERY_ENV.STATE_DIR]) ?? ".devstack"
+});
+//#endregion
+export { DEFAULT_DISCOVERY_STACK, DEFAULT_DISCOVERY_STATE_DIR, DISCOVERY_ENV, resolveDiscoveryEnv };
+
+//# sourceMappingURL=resolve-discovery-env.mjs.map

package/dist/build-integrations/runtime/resolve-discovery-env.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-discovery-env.mjs","names":[],"sources":["../../../src/build-integrations/runtime/resolve-discovery-env.ts"],"sourcesContent":["// Shared discovery env-ladder resolver.\n//\n// ONE place that turns (caller options + env bag) into the resolved\n// `{ stack, stateDir }` tuple every build integration discovers a\n// manifest with. Before this existed the ladder was copy-pasted in\n// `discover.ts`, the vitest loader, the playwright stack-context, and\n// the playwright global-setup single-stack fallback — and the two\n// playwright sites had drifted: they read only `DEVSTACK_STATE_DIR`\n// and silently ignored `DEVSTACK_RUNTIME_ROOT`. Consolidating here\n// makes that omission impossible and matches STYLE_GUIDE §7: \"L5 build\n// integrations use `build-integrations/runtime/` as the canonical\n// substrate; per-integration reimplementations of manifest discovery\n// consolidate there.\"\n//\n// `DEVSTACK_MANIFEST_PATH` is deliberately NOT resolved here — it is a\n// whole-path escape hatch handled inside `discoverManifestPath`\n// (env-miss must throw, not fall through to the walk-up), so threading\n// it through this stateDir/stack ladder would be the wrong layer.\n\n/** Default state-dir / runtime-root name when neither an explicit\n *  option nor any env override is present. Mirrors `DEFAULT_STATE_DIR`\n *  in `discover.ts` (same literal `.devstack`). */\nexport const DEFAULT_DISCOVERY_STATE_DIR = '.devstack';\n\n/** Default stack name when neither an explicit option nor\n *  `$DEVSTACK_STACK` yields a value. */\nexport const DEFAULT_DISCOVERY_STACK = 'main';\n\n/** Env-var names the discovery ladder consults for the stack +\n *  state-dir rungs. `MANIFEST_PATH` lives here for documentation parity\n *  with the integration env tables but is resolved by\n *  `discoverManifestPath`, not this ladder. */\nexport const DISCOVERY_ENV = {\n\tSTACK: 'DEVSTACK_STACK',\n\tRUNTIME_ROOT: 'DEVSTACK_RUNTIME_ROOT',\n\t/** Legacy alias for `RUNTIME_ROOT`; lower precedence. */\n\tSTATE_DIR: 'DEVSTACK_STATE_DIR',\n\tMANIFEST_PATH: 'DEVSTACK_MANIFEST_PATH',\n} as const;\n\nexport interface ResolveDiscoveryEnvOptions {\n\t/** Explicit stack name. Wins over `$DEVSTACK_STACK`. */\n\treadonly stack?: string;\n\t/** Explicit state-dir / runtime-root. Wins over both env vars. */\n\treadonly stateDir?: string;\n}\n\nexport interface ResolvedDiscoveryEnv {\n\t/** Resolved stack name (never empty). */\n\treadonly stack: string;\n\t/** Resolved state-dir / runtime-root (never empty). May be absolute\n\t *  — `discoverManifestPath` degenerates the walk-up to a single\n\t *  existence check in that case. */\n\treadonly stateDir: string;\n}\n\nconst firstNonEmpty = (\n\t...candidates: ReadonlyArray<string | undefined>\n): string | undefined => {\n\tfor (const candidate of candidates) {\n\t\tif (candidate !== undefined && candidate !== '') return candidate;\n\t}\n\treturn undefined;\n};\n\n/**\n * Resolve the canonical stack + state-dir ladder.\n *\n * Precedence (highest → lowest), identical for both rungs:\n *   - stack:     `options.stack` > `$DEVSTACK_STACK` > `'main'`\n *   - stateDir:  `options.stateDir` > `$DEVSTACK_RUNTIME_ROOT`\n *                > `$DEVSTACK_STATE_DIR` > `'.devstack'`\n *\n * Empty-string env values are treated as unset (a blank\n * `DEVSTACK_STATE_DIR=` must not pin the state root to the cwd). Pure —\n * no `process.env` read; callers pass the bag (a fixture in tests).\n */\nexport const resolveDiscoveryEnv = (\n\tenv: Readonly<Record<string, string | undefined>>,\n\toptions: ResolveDiscoveryEnvOptions = {},\n): ResolvedDiscoveryEnv => ({\n\tstack:\n\t\tfirstNonEmpty(options.stack?.trim(), env[DISCOVERY_ENV.STACK]?.trim()) ??\n\t\tDEFAULT_DISCOVERY_STACK,\n\tstateDir:\n\t\tfirstNonEmpty(\n\t\t\toptions.stateDir,\n\t\t\tenv[DISCOVERY_ENV.RUNTIME_ROOT],\n\t\t\tenv[DISCOVERY_ENV.STATE_DIR],\n\t\t) ?? DEFAULT_DISCOVERY_STATE_DIR,\n});\n"],"mappings":";;;;AAsBA,MAAa,8BAA8B;;;AAI3C,MAAa,0BAA0B;;;;;AAMvC,MAAa,gBAAgB;CAC5B,OAAO;CACP,cAAc;;CAEd,WAAW;CACX,eAAe;CACf;AAkBD,MAAM,iBACL,GAAG,eACqB;AACxB,MAAK,MAAM,aAAa,WACvB,KAAI,cAAc,KAAA,KAAa,cAAc,GAAI,QAAO;;;;;;;;;;;;;;AAiB1D,MAAa,uBACZ,KACA,UAAsC,EAAE,MACb;CAC3B,OACC,cAAc,QAAQ,OAAO,MAAM,EAAE,IAAI,cAAc,QAAQ,MAAM,CAAC,IAAA;CAEvE,UACC,cACC,QAAQ,UACR,IAAI,cAAc,eAClB,IAAI,cAAc,WAClB,IAAA;CACF"}

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

@@ -16,7 +16,7 @@ interface ResolvedEndpoint {
   readonly name: string;
   readonly url: string;
   readonly displayUrl: string | null;
-  readonly wireProtocol: string;
+  readonly wireProtocol: 'http' | 'h2c' | 'tcp';
   readonly pluginKey: string;
   readonly endpointKey: string;
 }

package/dist/build-integrations/runtime/wallet-paths.mjs

@@ -0,0 +1,2 @@
+import "../../contracts/wallet-protocol.mjs";
+export {};

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

@@ -0,0 +1,51 @@
+//#region src/build-integrations/vite/index.d.ts
+/** Default import-alias prefix. Customizable via `options.alias` (some
+ *  apps prefer `@gen`, `~generated`, …). The app MUST use the SAME
+ *  prefix in three derivable places: this plugin option, the
+ *  `tsconfig` `paths` entry, and its import specifiers. */
+declare const DEFAULT_GENERATED_ALIAS = "@generated";
+interface DevstackVitePluginOptions {
+  /** Import-alias prefix. Default `'@generated'`. */
+  readonly alias?: string;
+  /** Explicit generated dir — bypasses manifest discovery entirely
+   *  (escape hatch for unusual layouts / tests). Relative paths
+   *  resolve against the Vite root. */
+  readonly generatedDir?: string;
+}
+/** A `vite` `Plugin`'s `config` hook receives the partial user config.
+ *  We only ever read `config.root` and return a `resolve.alias` patch,
+ *  so a one-field structural subset is enough — this keeps the module
+ *  loadable without `vite` types (mirroring how the playwright/vitest
+ *  presets avoid importing their optional peer at module init). */
+interface ViteUserConfigLike {
+  readonly root?: string;
+}
+/** The structural `Plugin` shape we return — `name` + a `config` hook.
+ *  Typed as the loose object Vite accepts (Vite's `Plugin` is
+ *  structurally compatible) so callers spread it into `plugins: []`
+ *  without devstack depending on `vite`. */
+interface DevstackVitePlugin {
+  readonly name: string;
+  readonly config: (config: ViteUserConfigLike) => {
+    readonly resolve: {
+      readonly alias: Record<string, string>;
+    };
+  };
+}
+/**
+ * Build the devstack Vite plugin that aliases `options.alias`
+ * (default `@generated`) at the active stack's codegen output dir.
+ *
+ *     // vite.config.ts
+ *     import { devstackVitePlugin } from '@mysten-incubation/devstack/vite';
+ *     export default defineConfig({ plugins: [devstackVitePlugin()] });
+ *     // or devstackVitePlugin({ alias: '@gen' })
+ *
+ * The plugin's `config` hook merges `resolve.alias[<prefix>] = <dir>`
+ * into the user config (Vite deep-merges the returned partial). Sync;
+ * reads `process.env` + the manifest once at config-load.
+ */
+declare const devstackVitePlugin: (options?: DevstackVitePluginOptions) => DevstackVitePlugin;
+//#endregion
+export { DEFAULT_GENERATED_ALIAS, DevstackVitePlugin, DevstackVitePluginOptions, devstackVitePlugin };
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +1,73 @@
+import { resolveDiscoveryEnv } from "../runtime/resolve-discovery-env.mjs";
+import { discoverManifestPath } from "../runtime/discover.mjs";
+import "../runtime/index.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+//#region src/build-integrations/vite/index.ts
+/** Default import-alias prefix. Customizable via `options.alias` (some
+*  apps prefer `@gen`, `~generated`, …). The app MUST use the SAME
+*  prefix in three derivable places: this plugin option, the
+*  `tsconfig` `paths` entry, and its import specifiers. */
+const DEFAULT_GENERATED_ALIAS = "@generated";
+/** Default home-stack output subpath, relative to the Vite root. The
+*  cold-start fallback when no manifest / `codegen.generatedDir` is on
+*  disk yet. Mirrors `output-location.ts`'s home rule. */
+const FALLBACK_GENERATED_SUBPATH = "src/generated";
+/** Best-effort, SYNC read of the manifest-recorded `codegen.generatedDir`
+*  for the active stack. Returns the absolute dir, or `null` on any
+*  miss (no manifest yet, no `codegen` field, unreadable/corrupt file).
+*  Never throws — the caller falls back to `src/generated/`. We read +
+*  `JSON.parse` directly (rather than the schema-decoding
+*  `readStackContext`, which (a) drops the `codegen` field in its
+*  projection and (b) throws on a version mismatch) so an out-of-date
+*  or partially-written manifest degrades to the cold-start fallback
+*  instead of crashing the dev server. */
+const readGeneratedDirFromManifest = (env, cwd) => {
+	try {
+		const { stack, stateDir } = resolveDiscoveryEnv(env);
+		const manifestPath = discoverManifestPath({
+			env,
+			stack,
+			stateDir,
+			cwd
+		});
+		if (manifestPath === void 0 || !existsSync(manifestPath)) return null;
+		const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const codegen = parsed.codegen;
+		if (typeof codegen !== "object" || codegen === null) return null;
+		const generatedDir = codegen.generatedDir;
+		return typeof generatedDir === "string" && generatedDir.length > 0 ? generatedDir : null;
+	} catch {
+		return null;
+	}
+};
+/**
+* Build the devstack Vite plugin that aliases `options.alias`
+* (default `@generated`) at the active stack's codegen output dir.
+*
+*     // vite.config.ts
+*     import { devstackVitePlugin } from '@mysten-incubation/devstack/vite';
+*     export default defineConfig({ plugins: [devstackVitePlugin()] });
+*     // or devstackVitePlugin({ alias: '@gen' })
+*
+* The plugin's `config` hook merges `resolve.alias[<prefix>] = <dir>`
+* into the user config (Vite deep-merges the returned partial). Sync;
+* reads `process.env` + the manifest once at config-load.
+*/
+const devstackVitePlugin = (options = {}) => {
+	const alias = options.alias ?? "@generated";
+	return {
+		name: "devstack:generated-alias",
+		config: (config) => {
+			const root = config.root ?? process.cwd();
+			const explicit = options.generatedDir;
+			const generatedDir = explicit !== void 0 ? resolve(root, explicit) : readGeneratedDirFromManifest(process.env, root) ?? resolve(root, FALLBACK_GENERATED_SUBPATH);
+			return { resolve: { alias: { [alias]: generatedDir } } };
+		}
+	};
+};
+//#endregion
+export { DEFAULT_GENERATED_ALIAS, devstackVitePlugin };
+
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/build-integrations/vite/index.ts"],"sourcesContent":["// Vite build-integration — `@generated` alias plugin.\n//\n// notes/per-stack-codegen-design.md §\"Import mapping via a customizable\n// alias\": app source imports its Move codegen through a configurable\n// alias prefix (default `@generated`) instead of `./generated`. This\n// plugin points that alias at the ACTIVE stack's output dir — the EXACT\n// dir codegen wrote to for the current stack — so two stacks of the\n// same app (`pnpm dev` on the home stack + `pnpm test:e2e` on a\n// `--stack e2e` override) resolve `@generated/*` to different\n// directories and never read each other's clobbered package-id /\n// wallet-pair-token literals.\n//\n// The target is the manifest-recorded `codegen.generatedDir` (the\n// single source of truth — the supervisor wrote it at flush time; see\n// `orchestrators/codegen/output-location.ts` +\n// `runtime-composition.ts`). Resolution:\n//   1. `options.generatedDir` — explicit escape hatch, used verbatim.\n//   2. `resolveDiscoveryEnv(process.env)` → `{ stack, stateDir }`\n//      (single source of truth; honors `DEVSTACK_STACK` +\n//      `DEVSTACK_RUNTIME_ROOT`/`DEVSTACK_STATE_DIR`), then\n//      `discoverManifestPath(...)` locates `<stateDir>/stacks/<stack>/manifest.json`,\n//      and we read its `codegen.generatedDir`.\n//   3. Cold-start fallback — no manifest / no field yet → `<root>/src/generated`.\n//      (In the supervised flow Vite starts AFTER post-acquire codegen,\n//      so the field is present; the fallback is the pre-`up` window.)\n//\n// Because Playwright's `webServer` runs the app's OWN Vite as a child\n// inheriting `DEVSTACK_STACK`, the same plugin serves both `pnpm dev`\n// and the e2e dev server automatically. Vitest has its own Vite\n// pipeline, so apps add this plugin to `vitest.config.ts` too.\n//\n// SYNC + dependency-light, mirroring the playwright/vitest helpers: NO\n// heavy imports at module top-level, and `vite` is NOT imported (it is\n// an app-side dev dependency, not a devstack runtime dep). The return\n// value is a STRUCTURAL Vite `Plugin` — a `{ name, config }` object —\n// typed loosely so this module loads without `vite` installed. The\n// manifest read goes through the same `build-integrations/runtime`\n// machinery the playwright/vitest integrations use.\n\nimport { existsSync, readFileSync } from 'node:fs';\nimport { resolve } from 'node:path';\n\nimport { discoverManifestPath, resolveDiscoveryEnv } from '../runtime/index.ts';\n\n/** Default import-alias prefix. Customizable via `options.alias` (some\n *  apps prefer `@gen`, `~generated`, …). The app MUST use the SAME\n *  prefix in three derivable places: this plugin option, the\n *  `tsconfig` `paths` entry, and its import specifiers. */\nexport const DEFAULT_GENERATED_ALIAS = '@generated';\n\n/** Default home-stack output subpath, relative to the Vite root. The\n *  cold-start fallback when no manifest / `codegen.generatedDir` is on\n *  disk yet. Mirrors `output-location.ts`'s home rule. */\nconst FALLBACK_GENERATED_SUBPATH = 'src/generated';\n\nexport interface DevstackVitePluginOptions {\n\t/** Import-alias prefix. Default `'@generated'`. */\n\treadonly alias?: string;\n\t/** Explicit generated dir — bypasses manifest discovery entirely\n\t *  (escape hatch for unusual layouts / tests). Relative paths\n\t *  resolve against the Vite root. */\n\treadonly generatedDir?: string;\n}\n\n/** A `vite` `Plugin`'s `config` hook receives the partial user config.\n *  We only ever read `config.root` and return a `resolve.alias` patch,\n *  so a one-field structural subset is enough — this keeps the module\n *  loadable without `vite` types (mirroring how the playwright/vitest\n *  presets avoid importing their optional peer at module init). */\ninterface ViteUserConfigLike {\n\treadonly root?: string;\n}\n\n/** The structural `Plugin` shape we return — `name` + a `config` hook.\n *  Typed as the loose object Vite accepts (Vite's `Plugin` is\n *  structurally compatible) so callers spread it into `plugins: []`\n *  without devstack depending on `vite`. */\nexport interface DevstackVitePlugin {\n\treadonly name: string;\n\treadonly config: (config: ViteUserConfigLike) => {\n\t\treadonly resolve: { readonly alias: Record<string, string> };\n\t};\n}\n\n/** Best-effort, SYNC read of the manifest-recorded `codegen.generatedDir`\n *  for the active stack. Returns the absolute dir, or `null` on any\n *  miss (no manifest yet, no `codegen` field, unreadable/corrupt file).\n *  Never throws — the caller falls back to `src/generated/`. We read +\n *  `JSON.parse` directly (rather than the schema-decoding\n *  `readStackContext`, which (a) drops the `codegen` field in its\n *  projection and (b) throws on a version mismatch) so an out-of-date\n *  or partially-written manifest degrades to the cold-start fallback\n *  instead of crashing the dev server. */\nconst readGeneratedDirFromManifest = (\n\tenv: Readonly<Record<string, string | undefined>>,\n\tcwd: string,\n): string | null => {\n\ttry {\n\t\tconst { stack, stateDir } = resolveDiscoveryEnv(env);\n\t\tconst manifestPath = discoverManifestPath({ env, stack, stateDir, cwd });\n\t\tif (manifestPath === undefined || !existsSync(manifestPath)) return null;\n\t\tconst parsed: unknown = JSON.parse(readFileSync(manifestPath, 'utf8'));\n\t\tif (typeof parsed !== 'object' || parsed === null) return null;\n\t\tconst codegen = (parsed as { readonly codegen?: unknown }).codegen;\n\t\tif (typeof codegen !== 'object' || codegen === null) return null;\n\t\tconst generatedDir = (codegen as { readonly generatedDir?: unknown }).generatedDir;\n\t\treturn typeof generatedDir === 'string' && generatedDir.length > 0 ? generatedDir : null;\n\t} catch {\n\t\t// Discovery / read / parse failure → cold-start fallback. A\n\t\t// best-effort alias resolver must never fail the Vite config load.\n\t\treturn null;\n\t}\n};\n\n/**\n * Build the devstack Vite plugin that aliases `options.alias`\n * (default `@generated`) at the active stack's codegen output dir.\n *\n *     // vite.config.ts\n *     import { devstackVitePlugin } from '@mysten-incubation/devstack/vite';\n *     export default defineConfig({ plugins: [devstackVitePlugin()] });\n *     // or devstackVitePlugin({ alias: '@gen' })\n *\n * The plugin's `config` hook merges `resolve.alias[<prefix>] = <dir>`\n * into the user config (Vite deep-merges the returned partial). Sync;\n * reads `process.env` + the manifest once at config-load.\n */\nexport const devstackVitePlugin = (options: DevstackVitePluginOptions = {}): DevstackVitePlugin => {\n\tconst alias = options.alias ?? DEFAULT_GENERATED_ALIAS;\n\treturn {\n\t\tname: 'devstack:generated-alias',\n\t\tconfig: (config: ViteUserConfigLike) => {\n\t\t\tconst root = config.root ?? process.cwd();\n\t\t\t// Explicit `generatedDir` wins (relative → resolved against the\n\t\t\t// Vite root). Otherwise consult the manifest-recorded dir, then\n\t\t\t// fall back to the home-stack `src/generated/` for the\n\t\t\t// pre-supervisor cold-start window.\n\t\t\tconst explicit = options.generatedDir;\n\t\t\tconst generatedDir =\n\t\t\t\texplicit !== undefined\n\t\t\t\t\t? resolve(root, explicit)\n\t\t\t\t\t: (readGeneratedDirFromManifest(\n\t\t\t\t\t\t\tprocess.env as Readonly<Record<string, string | undefined>>,\n\t\t\t\t\t\t\troot,\n\t\t\t\t\t\t) ?? resolve(root, FALLBACK_GENERATED_SUBPATH));\n\t\t\t// Return a partial config; Vite merges `resolve.alias` into the\n\t\t\t// existing alias map. A bare-prefix alias (no trailing `/`)\n\t\t\t// matches both `@generated` and `@generated/foo.js` under Vite's\n\t\t\t// default string-alias resolution.\n\t\t\treturn { resolve: { alias: { [alias]: generatedDir } } };\n\t\t},\n\t};\n};\n"],"mappings":";;;;;;;;;;AAgDA,MAAa,0BAA0B;;;;AAKvC,MAAM,6BAA6B;;;;;;;;;;AAwCnC,MAAM,gCACL,KACA,QACmB;AACnB,KAAI;EACH,MAAM,EAAE,OAAO,aAAa,oBAAoB,IAAI;EACpD,MAAM,eAAe,qBAAqB;GAAE;GAAK;GAAO;GAAU;GAAK,CAAC;AACxE,MAAI,iBAAiB,KAAA,KAAa,CAAC,WAAW,aAAa,CAAE,QAAO;EACpE,MAAM,SAAkB,KAAK,MAAM,aAAa,cAAc,OAAO,CAAC;AACtE,MAAI,OAAO,WAAW,YAAY,WAAW,KAAM,QAAO;EAC1D,MAAM,UAAW,OAA0C;AAC3D,MAAI,OAAO,YAAY,YAAY,YAAY,KAAM,QAAO;EAC5D,MAAM,eAAgB,QAAgD;AACtE,SAAO,OAAO,iBAAiB,YAAY,aAAa,SAAS,IAAI,eAAe;SAC7E;AAGP,SAAO;;;;;;;;;;;;;;;;AAiBT,MAAa,sBAAsB,UAAqC,EAAE,KAAyB;CAClG,MAAM,QAAQ,QAAQ,SAAA;AACtB,QAAO;EACN,MAAM;EACN,SAAS,WAA+B;GACvC,MAAM,OAAO,OAAO,QAAQ,QAAQ,KAAK;GAKzC,MAAM,WAAW,QAAQ;GACzB,MAAM,eACL,aAAa,KAAA,IACV,QAAQ,MAAM,SAAS,GACtB,6BACD,QAAQ,KACR,KACA,IAAI,QAAQ,MAAM,2BAA2B;AAKjD,UAAO,EAAE,SAAS,EAAE,OAAO,GAAG,QAAQ,cAAc,EAAE,EAAE;;EAEzD"}

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

@@ -18,9 +18,10 @@ declare const VITEST_ENV_VARS: {
   readonly MANIFEST_PATH: "DEVSTACK_MANIFEST_PATH";
 };
 type VitestEnvVarName = (typeof VITEST_ENV_VARS)[keyof typeof VITEST_ENV_VARS];
-/** Default stack name when `DEVSTACK_STACK` is unset. Mirrors the
- *  engine's "main" default — but tests should explicitly set
- *  `DEVSTACK_STACK=test` rather than rely on this. */
+/** Default stack name when `DEVSTACK_STACK` is unset. Re-exported from
+ *  the discovery ladder's `DEFAULT_DISCOVERY_STACK` (single source of
+ *  truth) — but tests should explicitly set `DEVSTACK_STACK=test`
+ *  rather than rely on this. */
 declare const DEFAULT_STACK_NAME = "main";
 /** Default runtime root when neither `DEVSTACK_RUNTIME_ROOT` nor the
  *  legacy `DEVSTACK_STATE_DIR` is set. */

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

@@ -1,3 +1,4 @@
+import { DEFAULT_DISCOVERY_STACK } from "../runtime/resolve-discovery-env.mjs";
 //#region src/build-integrations/vitest/env.ts
 /** Env-var names the vitest integration consults. Centralized so
 *  test-setup printouts can name the var the caller forgot to set. */
@@ -17,10 +18,11 @@ const VITEST_ENV_VARS = {
 	*  by hand. */
 	MANIFEST_PATH: "DEVSTACK_MANIFEST_PATH"
 };
-/** Default stack name when `DEVSTACK_STACK` is unset. Mirrors the
-*  engine's "main" default — but tests should explicitly set
-*  `DEVSTACK_STACK=test` rather than rely on this. */
-const DEFAULT_STACK_NAME = "main";
+/** Default stack name when `DEVSTACK_STACK` is unset. Re-exported from
+*  the discovery ladder's `DEFAULT_DISCOVERY_STACK` (single source of
+*  truth) — but tests should explicitly set `DEVSTACK_STACK=test`
+*  rather than rely on this. */
+const DEFAULT_STACK_NAME = DEFAULT_DISCOVERY_STACK;
 /** Default runtime root when neither `DEVSTACK_RUNTIME_ROOT` nor the
 *  legacy `DEVSTACK_STATE_DIR` is set. */
 const DEFAULT_RUNTIME_ROOT = ".devstack";

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\n// -----------------------------------------------------------------------------\n// Canonical env-var names\n// -----------------------------------------------------------------------------\n\n/** Env-var names the vitest integration consults. Centralized so\n *  test-setup printouts can name the var the caller forgot to set. */\nexport const VITEST_ENV_VARS = {\n\t/** Stack name; the canonical signal for \"isolate this test run\n\t *  from other stacks\". Tests SHOULD set this to `'test'`. */\n\tSTACK: 'DEVSTACK_STACK',\n\t/** Override for the runtime root that holds\n\t *  `stacks/<stack>/manifest.json`. Defaults to `.devstack`. */\n\tRUNTIME_ROOT: 'DEVSTACK_RUNTIME_ROOT',\n\t/** Legacy alias for `RUNTIME_ROOT`. Accepted on read so the\n\t *  rewrite can coexist with example apps that still set the\n\t *  pre-rewrite name. New callers should use `RUNTIME_ROOT`. */\n\tRUNTIME_ROOT_LEGACY: 'DEVSTACK_STATE_DIR',\n\t/** Top-precedence absolute path to a specific manifest file. The\n\t *  engine sets this when it spawns child processes; rarely set\n\t *  by hand. */\n\tMANIFEST_PATH: 'DEVSTACK_MANIFEST_PATH',\n} as const;\n\nexport type VitestEnvVarName = (typeof VITEST_ENV_VARS)[keyof typeof VITEST_ENV_VARS];\n\n// -----------------------------------------------------------------------------\n// Defaults\n// -----------------------------------------------------------------------------\n\n/** Default stack name when `DEVSTACK_STACK` is unset. Mirrors the\n *  engine's \"main\" default — but tests should explicitly set\n *  `DEVSTACK_STACK=test` rather than rely on this. */\nexport const DEFAULT_STACK_NAME = 'main';\n\n/** Default runtime root when neither `DEVSTACK_RUNTIME_ROOT` nor the\n *  legacy `DEVSTACK_STATE_DIR` is set. */\nexport const DEFAULT_RUNTIME_ROOT = '.devstack';\n\n/** The recommended stack name for test runs — the value the\n *  `test`-script env should set. Exported as a constant so example\n *  apps' `package.json` can wire it from one symbol if a future\n *  scaffolder lands. */\nexport const RECOMMENDED_TEST_STACK = 'test';\n\n// -----------------------------------------------------------------------------\n// Pure resolvers — no module-init side effects\n// -----------------------------------------------------------------------------\n\nexport interface ResolvedVitestEnv {\n\treadonly stack: string;\n\treadonly runtimeRoot: string;\n\treadonly manifestPathOverride: string | undefined;\n\t/** True when the caller's env explicitly set `DEVSTACK_STACK`. The\n\t *  test-setup hook uses this to print a louder advisory when a\n\t *  user runs `pnpm test` without the recommended wiring. */\n\treadonly stackWasExplicit: boolean;\n}\n\n/** Resolve the vitest env contract from an arbitrary env bag.\n *  Side-effect free — tests pass a fixture; production code passes\n *  `process.env`. */\nexport const resolveVitestEnv = (\n\tenv: Readonly<Record<string, string | undefined>>,\n): ResolvedVitestEnv => {\n\tconst stackRaw = env[VITEST_ENV_VARS.STACK];\n\tconst stack = stackRaw !== undefined && stackRaw !== '' ? stackRaw : DEFAULT_STACK_NAME;\n\tconst runtimeRoot =\n\t\tenv[VITEST_ENV_VARS.RUNTIME_ROOT] ??\n\t\tenv[VITEST_ENV_VARS.RUNTIME_ROOT_LEGACY] ??\n\t\tDEFAULT_RUNTIME_ROOT;\n\tconst manifestPathOverride = env[VITEST_ENV_VARS.MANIFEST_PATH];\n\treturn {\n\t\tstack,\n\t\truntimeRoot: runtimeRoot === '' ? DEFAULT_RUNTIME_ROOT : runtimeRoot,\n\t\tmanifestPathOverride:\n\t\t\tmanifestPathOverride !== undefined && manifestPathOverride !== ''\n\t\t\t\t? manifestPathOverride\n\t\t\t\t: undefined,\n\t\tstackWasExplicit: stackRaw !== undefined && stackRaw !== '',\n\t};\n};\n"],"mappings":";;;AA6BA,MAAa,kBAAkB;;;CAG9B,OAAO;;;CAGP,cAAc;;;;CAId,qBAAqB;;;;CAIrB,eAAe;CACf;;;;AAWD,MAAa,qBAAqB;;;AAIlC,MAAa,uBAAuB;;;;;AAMpC,MAAa,yBAAyB;;;;AAmBtC,MAAa,oBACZ,QACuB;CACvB,MAAM,WAAW,IAAI,gBAAgB;CACrC,MAAM,QAAQ,aAAa,KAAA,KAAa,aAAa,KAAK,WAAW;CACrE,MAAM,cACL,IAAI,gBAAgB,iBACpB,IAAI,gBAAgB,wBAAA;CAErB,MAAM,uBAAuB,IAAI,gBAAgB;AACjD,QAAO;EACN;EACA,aAAa,gBAAgB,KAAK,uBAAuB;EACzD,sBACC,yBAAyB,KAAA,KAAa,yBAAyB,KAC5D,uBACA,KAAA;EACJ,kBAAkB,aAAa,KAAA,KAAa,aAAa;EACzD"}
+{"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"}

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

@@ -1,5 +1,5 @@
-import * as _$effect_Types0 from "effect/Types";
 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 & {
@@ -19,7 +19,14 @@ declare const VitestManifestShapeError_base: new <A extends Record<string, any>
   readonly _tag: "VitestManifestShapeError";
 } & Readonly<A>;
 /** The manifest exists but doesn't decode against the L0 envelope schema
- *  — either malformed JSON or shape drift after a manifestVersion bump. */
+ *  — either malformed JSON (`parse`) or shape drift (`shape`).
+ *
+ *  Distinct from `VitestManifestVersionMismatchError`: this tag carries
+ *  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. */
 declare class VitestManifestShapeError extends VitestManifestShapeError_base<{
   readonly message: string;
   readonly path: string;
@@ -27,6 +34,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 & {
+  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". */
+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 & {
   readonly _tag: "VitestSetupPreconditionError";
 } & Readonly<A>;
@@ -38,7 +59,7 @@ declare class VitestSetupPreconditionError extends VitestSetupPreconditionError_
   readonly message: string;
   readonly hint?: string;
 }> {}
-type VitestIntegrationError = VitestManifestNotFoundError | VitestManifestShapeError | VitestSetupPreconditionError;
+type VitestIntegrationError = VitestManifestNotFoundError | VitestManifestShapeError | VitestManifestVersionMismatchError | VitestSetupPreconditionError;
 //#endregion
-export { VitestIntegrationError, VitestManifestNotFoundError, VitestManifestShapeError, VitestSetupPreconditionError };
+export { VitestIntegrationError, VitestManifestNotFoundError, VitestManifestShapeError, VitestManifestVersionMismatchError, VitestSetupPreconditionError };
 //# sourceMappingURL=errors.d.mts.map

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

@@ -5,14 +5,27 @@ import { Data } from "effect";
 *  run yet or the wrong stack/state-dir is configured. */
 var VitestManifestNotFoundError = class extends Data.TaggedError("VitestManifestNotFoundError") {};
 /** The manifest exists but doesn't decode against the L0 envelope schema
-*  — either malformed JSON or shape drift after a manifestVersion bump. */
+*  — either malformed JSON (`parse`) or shape drift (`shape`).
+*
+*  Distinct from `VitestManifestVersionMismatchError`: this tag carries
+*  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. */
 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". */
+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
 *  discoverable. Distinct from the discovery error because the caller
 *  opted IN to the requirement. */
 var VitestSetupPreconditionError = class extends Data.TaggedError("VitestSetupPreconditionError") {};
 //#endregion
-export { VitestManifestNotFoundError, VitestManifestShapeError, VitestSetupPreconditionError };
+export { VitestManifestNotFoundError, VitestManifestShapeError, VitestManifestVersionMismatchError, VitestSetupPreconditionError };
 
 //# sourceMappingURL=errors.mjs.map