@mysten-incubation/devstack 0.1.0 → 0.2.0

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

@@ -1,5 +1,5 @@
-import { DEFAULT_DISCOVERY_STACK, DEFAULT_DISCOVERY_STATE_DIR, resolveDiscoveryEnv } from "./resolve-discovery-env.mjs";
 import { inferPackageNameFromCwd, readPackageName } from "../../api/inference-network.mjs";
+import { DEFAULT_DISCOVERY_STACK, DEFAULT_DISCOVERY_STATE_DIR, resolveDiscoveryEnv } from "./resolve-discovery-env.mjs";
 import { ManifestDiscoveryError } from "./errors.mjs";
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
@@ -9,9 +9,19 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 *  doesn't reach into the substrate package. Re-export of the
 *  shared-resolver default so this module's public surface is stable. */
 const DEFAULT_STATE_DIR = DEFAULT_DISCOVERY_STATE_DIR;
-/** Default stack name when neither `opts.stack` nor `$DEVSTACK_STACK`
-*  yields a useful value. */
+/** Default stack name when neither `opts.stack`, `$DEVSTACK_STACK`,
+*  nor the package-name walk-up yields a useful value. */
 const DEFAULT_STACK = DEFAULT_DISCOVERY_STACK;
+/** Explicit > `$DEVSTACK_STACK` > `'main'` — deliberately WITHOUT the
+*  package-name rung (no `cwd`). The sole production caller is the
+*  cold-start URL path (`cold-start-url.ts`), where package metadata
+*  supplies the APP name; deriving the stack from it too would double
+*  the package name into every minted hostname
+*  (`<service>.<pkg>.<pkg>.localhost`) — a separate decision, pinned by
+*  the cold-start tests. Manifest discovery, which must agree with the
+*  CLI about which stack a bare app runs, goes through
+*  `discoverManifestPath` below, which threads its walk-up cwd into the
+*  package rung. */
 const resolveBuildIntegrationStack = (explicit, env = process.env) => resolveDiscoveryEnv(env, explicit !== void 0 ? { stack: explicit } : {}).stack;
 /** Read `name` out of `<dir>/package.json`, strip the `@scope/`
 *  prefix and any leading non-alphanumerics. Returns `undefined`
@@ -56,7 +66,8 @@ function discoverManifestPath(opts = {}) {
 	const startDir = opts.cwd ?? process.cwd();
 	const { stack, stateDir } = resolveDiscoveryEnv(env, {
 		...opts.stack !== void 0 ? { stack: opts.stack } : {},
-		...opts.stateDir !== void 0 ? { stateDir: opts.stateDir } : {}
+		...opts.stateDir !== void 0 ? { stateDir: opts.stateDir } : {},
+		cwd: startDir
 	});
 	const candidates = isAbsolute(stateDir) ? [join(stateDir, "stacks", stack, "manifest.json")] : (() => {
 		const acc = [];

package/dist/build-integrations/runtime/discover.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"discover.mjs","names":[],"sources":["../../../src/build-integrations/runtime/discover.ts"],"sourcesContent":["// Manifest discovery — sync walk-up resolver.\n//\n// Read-side L5 (consumer) bridge between the on-disk manifest the\n// supervisor writes and the apps / build tools that need to find it.\n//\n// Precedence (top to bottom):\n//\n//   1. `DEVSTACK_MANIFEST_PATH` env var — top-level escape hatch. Wins\n//      over every other input. If set to a missing file, returns\n//      `undefined` (or throws when `required: true`).\n//   2. `override` argument — caller-explicit path. Same precedence\n//      semantics as the env var, one rung lower.\n//   3. Walk up from `opts.cwd ?? process.cwd()`. At each directory,\n//      check `<stateDir>/stacks/<stack>/manifest.json`. Build\n//      integrations resolve `<stack>` from explicit option, then\n//      `DEVSTACK_STACK`, then `main`; package metadata is app identity,\n//      not an implicit manifest stack selector. The walk stops at the\n//      filesystem root.\n//\n// Stack-scoped ONLY. The supervisor writes to\n// `<stateDir>/stacks/<stack>/manifest.json` exclusively; a hit at a\n// flat `<stateDir>/manifest.json` would be stale data from a deleted\n// stack, which would silently steer consumers at the wrong URLs /\n// package ids. Architecture § invariants: \"stack-scoped paths only —\n// a stale flat manifest must NOT be returned.\"\n//\n// Sync because the only host-process that drives this resolver is\n// Playwright config-load, and Playwright's loader API is sync. Cost is\n// a handful of `existsSync` calls — cheap.\n\nimport { existsSync, readdirSync } from 'node:fs';\nimport { dirname, isAbsolute, join, resolve } from 'node:path';\n\nimport { ManifestDiscoveryError } from './errors.ts';\nimport {\n\tDEFAULT_DISCOVERY_STACK,\n\tDEFAULT_DISCOVERY_STATE_DIR,\n\tresolveDiscoveryEnv,\n} from './resolve-discovery-env.ts';\nimport { inferPackageNameFromCwd, readPackageName } from '../../api/inference-network.ts';\n\n/** Default name of the supervisor's per-user state directory. Mirrors\n *  the L0 path resolver. Held here as a literal so the discover walk\n *  doesn't reach into the substrate package. Re-export of the\n *  shared-resolver default so this module's public surface is stable. */\nexport const DEFAULT_STATE_DIR = DEFAULT_DISCOVERY_STATE_DIR;\n\n/** Default stack name when neither `opts.stack` nor `$DEVSTACK_STACK`\n *  yields a useful value. */\nexport const DEFAULT_STACK = DEFAULT_DISCOVERY_STACK;\n\nexport const resolveBuildIntegrationStack = (\n\texplicit: string | undefined,\n\tenv: Readonly<Record<string, string | undefined>> = process.env,\n): string => resolveDiscoveryEnv(env, explicit !== undefined ? { stack: explicit } : {}).stack;\n\nexport interface DiscoverManifestPathOptions {\n\t/** Caller-supplied override path. Bypasses the walk-up but is still\n\t *  existence-checked. Lower precedence than\n\t *  `DEVSTACK_MANIFEST_PATH`. */\n\treadonly override?: string;\n\t/** Starting directory for the walk-up. Defaults to\n\t *  `process.cwd()`. */\n\treadonly cwd?: string;\n\t/** Stack name. Defaults through `$DEVSTACK_STACK`, then `'main'`. */\n\treadonly stack?: string;\n\t/** State-dir name. Defaults through `$DEVSTACK_RUNTIME_ROOT`, then\n\t *  the legacy `$DEVSTACK_STATE_DIR`, then `'.devstack'` (see\n\t *  `resolveDiscoveryEnv`). Absolute paths are honored — the walk-up\n\t *  degenerates into a single existence check in that case. */\n\treadonly stateDir?: string;\n\t/** Env bag for the env-precedence step. Defaults to `process.env`.\n\t *  Tests pass a fixture (often `{}`) to suppress leaks from the\n\t *  ambient environment. */\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n\t/** When `true`, throw `ManifestDiscoveryError` on miss instead of\n\t *  returning `undefined`. Default `false` (lets callers that treat\n\t *  \"no manifest\" as cold-start branch cleanly). */\n\treadonly required?: boolean;\n}\n\n/** Read `name` out of `<dir>/package.json`, strip the `@scope/`\n *  prefix and any leading non-alphanumerics. Returns `undefined`\n *  when the file is missing / unreadable / has no name field. */\nexport const readAppName = readPackageName;\n\n/** Walk up from `cwd` to find the closest `package.json` and return\n *  its un-scoped `name` field. Returns `undefined` if no package.json\n *  is reachable. Bounded to 32 levels — defense against pathological\n *  symlink loops. */\nexport const readAppNameWalkup = inferPackageNameFromCwd;\n\n/**\n * Locate an existing devstack manifest on disk. Sync — Playwright's\n * config loader and apps' startup paths both depend on this being\n * synchronous.\n *\n * Returns the absolute path of the first match per the precedence\n * documented at the top of this module, or `undefined` if no candidate\n * exists. Pass `{ required: true }` to throw `ManifestDiscoveryError`\n * on miss instead.\n */\nexport function discoverManifestPath(opts: DiscoverManifestPathOptions = {}): string | undefined {\n\tconst env = opts.env ?? (process.env as Readonly<Record<string, string | undefined>>);\n\tconst envOverride = env.DEVSTACK_MANIFEST_PATH;\n\t// Env + override misses ALWAYS throw — the `required: false` knob\n\t// only suppresses walk-up-not-found, not \"the user explicitly\n\t// pointed at a missing file.\" Silently falling back to walk-up on\n\t// a typo'd env var would steer callers at a stale ancestor manifest.\n\tif (envOverride !== undefined && envOverride !== '') {\n\t\tconst resolved = resolve(envOverride);\n\t\tif (existsSync(resolved)) return resolved;\n\t\tthrow new ManifestDiscoveryError({\n\t\t\tphase: 'env-missing',\n\t\t\tpath: resolved,\n\t\t\tmessage:\n\t\t\t\t`[devstack] DEVSTACK_MANIFEST_PATH points at ${resolved}, but no file exists there. ` +\n\t\t\t\t`Unset the env var or run \\`devstack up\\` to write the manifest.`,\n\t\t});\n\t}\n\tif (opts.override !== undefined && opts.override !== '') {\n\t\tconst resolved = resolve(opts.override);\n\t\tif (existsSync(resolved)) return resolved;\n\t\tthrow new ManifestDiscoveryError({\n\t\t\tphase: 'override-missing',\n\t\t\tpath: resolved,\n\t\t\tmessage:\n\t\t\t\t`[devstack] explicit manifest path ${resolved} does not exist. ` +\n\t\t\t\t`Run \\`devstack up\\` to write the manifest first.`,\n\t\t});\n\t}\n\tconst startDir = opts.cwd ?? process.cwd();\n\tconst { stack, stateDir } = resolveDiscoveryEnv(env, {\n\t\t...(opts.stack !== undefined ? { stack: opts.stack } : {}),\n\t\t...(opts.stateDir !== undefined ? { stateDir: opts.stateDir } : {}),\n\t});\n\t// An absolute `stateDir` / `DEVSTACK_RUNTIME_ROOT` pins the state\n\t// root, so the cwd walk-up is meaningless — `path.join` would also\n\t// drop the leading `dir` segment and mis-resolve the candidate.\n\t// Degenerate to a single existence check, mirroring\n\t// `discoverSingleStackManifestPath`.\n\tconst candidates = isAbsolute(stateDir)\n\t\t? [join(stateDir, 'stacks', stack, 'manifest.json')]\n\t\t: (() => {\n\t\t\t\tconst acc: string[] = [];\n\t\t\t\tlet dir = resolve(startDir);\n\t\t\t\twhile (true) {\n\t\t\t\t\tacc.push(join(dir, stateDir, 'stacks', stack, 'manifest.json'));\n\t\t\t\t\tconst parent = dirname(dir);\n\t\t\t\t\tif (parent === dir) return acc;\n\t\t\t\t\tdir = parent;\n\t\t\t\t}\n\t\t\t})();\n\tfor (const candidate of candidates) {\n\t\tif (existsSync(candidate)) return candidate;\n\t}\n\tif (opts.required === true) {\n\t\tconst expected = isAbsolute(stateDir)\n\t\t\t? join(stateDir, 'stacks', stack, 'manifest.json')\n\t\t\t: resolve(startDir, stateDir, 'stacks', stack, 'manifest.json');\n\t\tthrow new ManifestDiscoveryError({\n\t\t\tphase: 'walk-up',\n\t\t\tpath: expected,\n\t\t\tmessage:\n\t\t\t\t`[devstack] no manifest.json found walking up from ${startDir} ` +\n\t\t\t\t`(looked for ${stateDir}/stacks/${stack}/manifest.json at each level). ` +\n\t\t\t\t`Run \\`devstack up\\` — it writes the manifest at ${expected}.`,\n\t\t});\n\t}\n\treturn undefined;\n}\n\nexport interface DiscoverSingleStackManifestPathOptions {\n\t/** Starting directory for the walk-up. Defaults to `process.cwd()`. */\n\treadonly cwd?: string;\n\t/** State-dir name. Defaults to `.devstack`. Absolute paths are\n\t *  honored — the walk-up degenerates into a single existence check\n\t *  in that case. */\n\treadonly stateDir?: string;\n}\n\n/**\n * Walks up from `cwd` looking for a `<stateDir>` that contains EXACTLY\n * ONE stack subdirectory; returns that stack's `manifest.json` path.\n * Returns `null` when zero or >1 stacks are found at every ancestor.\n *\n * Used by integrations that need a no-explicit-stack auto-detect mode\n * (Playwright preset; future Vitest cold-start). The contract:\n *\n *   - At each ancestor, list `<ancestor>/<stateDir>/stacks/*`.\n *   - If exactly one stack dir with a `manifest.json` exists at that\n *     level: return its path. Stop walking.\n *   - If >1 stacks exist at that level: ambiguous → return `null` (do\n *     NOT continue walking past an ambiguous level).\n *   - If 0 stacks exist at that level: continue walking up.\n *   - If the filesystem root is reached without resolution: return\n *     `null`.\n *\n * Pure — does not consult env vars. Callers do their own gating (the\n * Playwright preset only invokes this when no explicit stack was\n * supplied via option or env).\n */\nexport const discoverSingleStackManifestPath = (\n\toptions: DiscoverSingleStackManifestPathOptions = {},\n): string | null => {\n\tconst cwd = resolve(options.cwd ?? process.cwd());\n\tconst stateDirName = options.stateDir ?? DEFAULT_STATE_DIR;\n\tconst startDirs = isAbsolute(stateDirName)\n\t\t? [stateDirName]\n\t\t: (() => {\n\t\t\t\tconst dirs: string[] = [];\n\t\t\t\tlet dir = cwd;\n\t\t\t\twhile (true) {\n\t\t\t\t\tdirs.push(join(dir, stateDirName));\n\t\t\t\t\tconst parent = dirname(dir);\n\t\t\t\t\tif (parent === dir) return dirs;\n\t\t\t\t\tdir = parent;\n\t\t\t\t}\n\t\t\t})();\n\n\tfor (const stateDir of startDirs) {\n\t\tconst stacksDir = join(stateDir, 'stacks');\n\t\tif (!existsSync(stacksDir)) continue;\n\t\tconst manifests = readdirSync(stacksDir, { withFileTypes: true })\n\t\t\t.filter((entry) => entry.isDirectory())\n\t\t\t.map((entry) => join(stacksDir, entry.name, 'manifest.json'))\n\t\t\t.filter((path) => existsSync(path))\n\t\t\t.sort();\n\t\tif (manifests.length === 1) return manifests[0]!;\n\t\tif (manifests.length > 1) return null;\n\t}\n\treturn null;\n};\n"],"mappings":"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"}
+{"version":3,"file":"discover.mjs","names":[],"sources":["../../../src/build-integrations/runtime/discover.ts"],"sourcesContent":["// Manifest discovery — sync walk-up resolver.\n//\n// Read-side L5 (consumer) bridge between the on-disk manifest the\n// supervisor writes and the apps / build tools that need to find it.\n//\n// Precedence (top to bottom):\n//\n//   1. `DEVSTACK_MANIFEST_PATH` env var — top-level escape hatch. Wins\n//      over every other input. If set to a missing file, returns\n//      `undefined` (or throws when `required: true`).\n//   2. `override` argument — caller-explicit path. Same precedence\n//      semantics as the env var, one rung lower.\n//   3. Walk up from `opts.cwd ?? process.cwd()`. At each directory,\n//      check `<stateDir>/stacks/<stack>/manifest.json`. Build\n//      integrations resolve `<stack>` with the same ladder as the CLI's\n//      `resolveStackName`: explicit option, then `DEVSTACK_STACK`, then\n//      the nearest package.json `name` above the walk-up start, then\n//      `main`. The package rung exists because `devstack up` in a bare\n//      app names the stack after the package — without it, discovery\n//      (and therefore `pnpm test`) would look for a `main` manifest the\n//      supervisor never wrote. The walk stops at the filesystem root.\n//\n// Stack-scoped ONLY. The supervisor writes to\n// `<stateDir>/stacks/<stack>/manifest.json` exclusively; a hit at a\n// flat `<stateDir>/manifest.json` would be stale data from a deleted\n// stack, which would silently steer consumers at the wrong URLs /\n// package ids. Architecture § invariants: \"stack-scoped paths only —\n// a stale flat manifest must NOT be returned.\"\n//\n// Sync because the only host-process that drives this resolver is\n// Playwright config-load, and Playwright's loader API is sync. Cost is\n// a handful of `existsSync` calls — cheap.\n\nimport { existsSync, readdirSync } from 'node:fs';\nimport { dirname, isAbsolute, join, resolve } from 'node:path';\n\nimport { ManifestDiscoveryError } from './errors.ts';\nimport {\n\tDEFAULT_DISCOVERY_STACK,\n\tDEFAULT_DISCOVERY_STATE_DIR,\n\tresolveDiscoveryEnv,\n} from './resolve-discovery-env.ts';\nimport { inferPackageNameFromCwd, readPackageName } from '../../api/inference-network.ts';\n\n/** Default name of the supervisor's per-user state directory. Mirrors\n *  the L0 path resolver. Held here as a literal so the discover walk\n *  doesn't reach into the substrate package. Re-export of the\n *  shared-resolver default so this module's public surface is stable. */\nexport const DEFAULT_STATE_DIR = DEFAULT_DISCOVERY_STATE_DIR;\n\n/** Default stack name when neither `opts.stack`, `$DEVSTACK_STACK`,\n *  nor the package-name walk-up yields a useful value. */\nexport const DEFAULT_STACK = DEFAULT_DISCOVERY_STACK;\n\n/** Explicit > `$DEVSTACK_STACK` > `'main'` — deliberately WITHOUT the\n *  package-name rung (no `cwd`). The sole production caller is the\n *  cold-start URL path (`cold-start-url.ts`), where package metadata\n *  supplies the APP name; deriving the stack from it too would double\n *  the package name into every minted hostname\n *  (`<service>.<pkg>.<pkg>.localhost`) — a separate decision, pinned by\n *  the cold-start tests. Manifest discovery, which must agree with the\n *  CLI about which stack a bare app runs, goes through\n *  `discoverManifestPath` below, which threads its walk-up cwd into the\n *  package rung. */\nexport const resolveBuildIntegrationStack = (\n\texplicit: string | undefined,\n\tenv: Readonly<Record<string, string | undefined>> = process.env,\n): string => resolveDiscoveryEnv(env, explicit !== undefined ? { stack: explicit } : {}).stack;\n\nexport interface DiscoverManifestPathOptions {\n\t/** Caller-supplied override path. Bypasses the walk-up but is still\n\t *  existence-checked. Lower precedence than\n\t *  `DEVSTACK_MANIFEST_PATH`. */\n\treadonly override?: string;\n\t/** Starting directory for the walk-up. Defaults to\n\t *  `process.cwd()`. */\n\treadonly cwd?: string;\n\t/** Stack name. Defaults through `$DEVSTACK_STACK`, then the nearest\n\t *  package.json `name` above `cwd` (the CLI's stack-inference rung),\n\t *  then `'main'`. */\n\treadonly stack?: string;\n\t/** State-dir name. Defaults through `$DEVSTACK_RUNTIME_ROOT`, then\n\t *  `$DEVSTACK_STATE_DIR`, then `'.devstack'` (see\n\t *  `resolveDiscoveryEnv`). Absolute paths are honored — the walk-up\n\t *  degenerates into a single existence check in that case. */\n\treadonly stateDir?: string;\n\t/** Env bag for the env-precedence step. Defaults to `process.env`.\n\t *  Tests pass a fixture (often `{}`) to suppress leaks from the\n\t *  ambient environment. */\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n\t/** When `true`, throw `ManifestDiscoveryError` on miss instead of\n\t *  returning `undefined`. Default `false` (lets callers that treat\n\t *  \"no manifest\" as cold-start branch cleanly). */\n\treadonly required?: boolean;\n}\n\n/** Read `name` out of `<dir>/package.json`, strip the `@scope/`\n *  prefix and any leading non-alphanumerics. Returns `undefined`\n *  when the file is missing / unreadable / has no name field. */\nexport const readAppName = readPackageName;\n\n/** Walk up from `cwd` to find the closest `package.json` and return\n *  its un-scoped `name` field. Returns `undefined` if no package.json\n *  is reachable. Bounded to 32 levels — defense against pathological\n *  symlink loops. */\nexport const readAppNameWalkup = inferPackageNameFromCwd;\n\n/**\n * Locate an existing devstack manifest on disk. Sync — Playwright's\n * config loader and apps' startup paths both depend on this being\n * synchronous.\n *\n * Returns the absolute path of the first match per the precedence\n * documented at the top of this module, or `undefined` if no candidate\n * exists. Pass `{ required: true }` to throw `ManifestDiscoveryError`\n * on miss instead.\n */\nexport function discoverManifestPath(opts: DiscoverManifestPathOptions = {}): string | undefined {\n\tconst env = opts.env ?? (process.env as Readonly<Record<string, string | undefined>>);\n\tconst envOverride = env.DEVSTACK_MANIFEST_PATH;\n\t// Env + override misses ALWAYS throw — the `required: false` knob\n\t// only suppresses walk-up-not-found, not \"the user explicitly\n\t// pointed at a missing file.\" Silently falling back to walk-up on\n\t// a typo'd env var would steer callers at a stale ancestor manifest.\n\tif (envOverride !== undefined && envOverride !== '') {\n\t\tconst resolved = resolve(envOverride);\n\t\tif (existsSync(resolved)) return resolved;\n\t\tthrow new ManifestDiscoveryError({\n\t\t\tphase: 'env-missing',\n\t\t\tpath: resolved,\n\t\t\tmessage:\n\t\t\t\t`[devstack] DEVSTACK_MANIFEST_PATH points at ${resolved}, but no file exists there. ` +\n\t\t\t\t`Unset the env var or run \\`devstack up\\` to write the manifest.`,\n\t\t});\n\t}\n\tif (opts.override !== undefined && opts.override !== '') {\n\t\tconst resolved = resolve(opts.override);\n\t\tif (existsSync(resolved)) return resolved;\n\t\tthrow new ManifestDiscoveryError({\n\t\t\tphase: 'override-missing',\n\t\t\tpath: resolved,\n\t\t\tmessage:\n\t\t\t\t`[devstack] explicit manifest path ${resolved} does not exist. ` +\n\t\t\t\t`Run \\`devstack up\\` to write the manifest first.`,\n\t\t});\n\t}\n\tconst startDir = opts.cwd ?? process.cwd();\n\tconst { stack, stateDir } = resolveDiscoveryEnv(env, {\n\t\t...(opts.stack !== undefined ? { stack: opts.stack } : {}),\n\t\t...(opts.stateDir !== undefined ? { stateDir: opts.stateDir } : {}),\n\t\t// Package-name rung: infer from the same dir the manifest walk-up\n\t\t// starts at, so \"which stack\" and \"where to look\" always agree.\n\t\tcwd: startDir,\n\t});\n\t// An absolute `stateDir` / `DEVSTACK_RUNTIME_ROOT` pins the state\n\t// root, so the cwd walk-up is meaningless — `path.join` would also\n\t// drop the leading `dir` segment and mis-resolve the candidate.\n\t// Degenerate to a single existence check, mirroring\n\t// `discoverSingleStackManifestPath`.\n\tconst candidates = isAbsolute(stateDir)\n\t\t? [join(stateDir, 'stacks', stack, 'manifest.json')]\n\t\t: (() => {\n\t\t\t\tconst acc: string[] = [];\n\t\t\t\tlet dir = resolve(startDir);\n\t\t\t\twhile (true) {\n\t\t\t\t\tacc.push(join(dir, stateDir, 'stacks', stack, 'manifest.json'));\n\t\t\t\t\tconst parent = dirname(dir);\n\t\t\t\t\tif (parent === dir) return acc;\n\t\t\t\t\tdir = parent;\n\t\t\t\t}\n\t\t\t})();\n\tfor (const candidate of candidates) {\n\t\tif (existsSync(candidate)) return candidate;\n\t}\n\tif (opts.required === true) {\n\t\tconst expected = isAbsolute(stateDir)\n\t\t\t? join(stateDir, 'stacks', stack, 'manifest.json')\n\t\t\t: resolve(startDir, stateDir, 'stacks', stack, 'manifest.json');\n\t\tthrow new ManifestDiscoveryError({\n\t\t\tphase: 'walk-up',\n\t\t\tpath: expected,\n\t\t\tmessage:\n\t\t\t\t`[devstack] no manifest.json found walking up from ${startDir} ` +\n\t\t\t\t`(looked for ${stateDir}/stacks/${stack}/manifest.json at each level). ` +\n\t\t\t\t`Run \\`devstack up\\` — it writes the manifest at ${expected}.`,\n\t\t});\n\t}\n\treturn undefined;\n}\n\nexport interface DiscoverSingleStackManifestPathOptions {\n\t/** Starting directory for the walk-up. Defaults to `process.cwd()`. */\n\treadonly cwd?: string;\n\t/** State-dir name. Defaults to `.devstack`. Absolute paths are\n\t *  honored — the walk-up degenerates into a single existence check\n\t *  in that case. */\n\treadonly stateDir?: string;\n}\n\n/**\n * Walks up from `cwd` looking for a `<stateDir>` that contains EXACTLY\n * ONE stack subdirectory; returns that stack's `manifest.json` path.\n * Returns `null` when zero or >1 stacks are found at every ancestor.\n *\n * Used by integrations that need a no-explicit-stack auto-detect mode\n * (Playwright preset; future Vitest cold-start). The contract:\n *\n *   - At each ancestor, list `<ancestor>/<stateDir>/stacks/*`.\n *   - If exactly one stack dir with a `manifest.json` exists at that\n *     level: return its path. Stop walking.\n *   - If >1 stacks exist at that level: ambiguous → return `null` (do\n *     NOT continue walking past an ambiguous level).\n *   - If 0 stacks exist at that level: continue walking up.\n *   - If the filesystem root is reached without resolution: return\n *     `null`.\n *\n * Pure — does not consult env vars. Callers do their own gating (the\n * Playwright preset only invokes this when no explicit stack was\n * supplied via option or env).\n */\nexport const discoverSingleStackManifestPath = (\n\toptions: DiscoverSingleStackManifestPathOptions = {},\n): string | null => {\n\tconst cwd = resolve(options.cwd ?? process.cwd());\n\tconst stateDirName = options.stateDir ?? DEFAULT_STATE_DIR;\n\tconst startDirs = isAbsolute(stateDirName)\n\t\t? [stateDirName]\n\t\t: (() => {\n\t\t\t\tconst dirs: string[] = [];\n\t\t\t\tlet dir = cwd;\n\t\t\t\twhile (true) {\n\t\t\t\t\tdirs.push(join(dir, stateDirName));\n\t\t\t\t\tconst parent = dirname(dir);\n\t\t\t\t\tif (parent === dir) return dirs;\n\t\t\t\t\tdir = parent;\n\t\t\t\t}\n\t\t\t})();\n\n\tfor (const stateDir of startDirs) {\n\t\tconst stacksDir = join(stateDir, 'stacks');\n\t\tif (!existsSync(stacksDir)) continue;\n\t\tconst manifests = readdirSync(stacksDir, { withFileTypes: true })\n\t\t\t.filter((entry) => entry.isDirectory())\n\t\t\t.map((entry) => join(stacksDir, entry.name, 'manifest.json'))\n\t\t\t.filter((path) => existsSync(path))\n\t\t\t.sort();\n\t\tif (manifests.length === 1) return manifests[0]!;\n\t\tif (manifests.length > 1) return null;\n\t}\n\treturn null;\n};\n"],"mappings":"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"}

package/dist/build-integrations/runtime/endpoint-registry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"endpoint-registry.mjs","names":[],"sources":["../../../src/build-integrations/runtime/endpoint-registry.ts"],"sourcesContent":["// Typed endpoint lookup.\n//\n// `EndpointRegistry` wraps the manifest's flat `endpoints` map with\n// the small set of queries every consumer asks of it:\n//\n//   - `byName(name)`: the load-bearing lookup. Playwright `baseURL`\n//     and codegen emitters all key off endpoint name.\n//   - `byPluginKey(key)`: group endpoints by the plugin that emitted\n//     them. The CLI `status` command uses this to print one block\n//     per plugin.\n//   - `byKind(kind)`: filter on `wireProtocol` — currently one of\n//     `'http' | 'h2c' | 'tcp'`. Cheap projection; lets callers filter\n//     the gRPC or raw-TCP endpoints out of an HTTP-only health check.\n//   - `all()`: stable-ordered iteration. Order is alphabetical by\n//     endpoint name — the manifest writer emits in input-order, but\n//     consumer iteration shouldn't depend on plugin registration\n//     order.\n//\n// Plain class — no Effect, no Schema. Callable from any consumer\n// runtime (Node, browser bundle that imported the manifest via the\n// build-integration alias).\n\nimport type { ResolvedEndpoint } from './stack-context.ts';\n\n/** Read-only registry over the manifest's `endpoints` map. */\nexport class EndpointRegistry {\n\tprivate readonly entries: ReadonlyArray<ResolvedEndpoint>;\n\tprivate readonly byNameIndex: ReadonlyMap<string, ResolvedEndpoint>;\n\n\tconstructor(entries: ReadonlyArray<ResolvedEndpoint>) {\n\t\t// Defensive: sort by name so iteration is stable across\n\t\t// supervisor runs even if the writer hashed plugins in a\n\t\t// different order this time.\n\t\tconst sorted = [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));\n\t\tthis.entries = sorted;\n\t\tconst map = new Map<string, ResolvedEndpoint>();\n\t\tfor (const entry of sorted) map.set(entry.name, entry);\n\t\tthis.byNameIndex = map;\n\t}\n\n\t/** Look up an endpoint by its declared name. Returns `undefined`\n\t *  when the name isn't in the manifest — callers that want a hard\n\t *  fail should `??` to a thrown error. */\n\tbyName(name: string): ResolvedEndpoint | undefined {\n\t\treturn this.byNameIndex.get(name);\n\t}\n\n\t/** Group endpoints by the plugin that emitted them. Used by the\n\t *  CLI status output. */\n\tbyPluginKey(pluginKey: string): ReadonlyArray<ResolvedEndpoint> {\n\t\treturn this.entries.filter((e) => e.pluginKey === pluginKey);\n\t}\n\n\t/** Filter endpoints by wire protocol — currently `'http' | 'h2c' |\n\t *  'tcp'`. Typed as `string` for forward-compat with plugin-added\n\t *  protocols; mistyped values just return an empty array. */\n\tbyKind(wireProtocol: string): ReadonlyArray<ResolvedEndpoint> {\n\t\treturn this.entries.filter((e) => e.wireProtocol === wireProtocol);\n\t}\n\n\t/** All endpoints, alphabetical by name. */\n\tall(): ReadonlyArray<ResolvedEndpoint> {\n\t\treturn this.entries;\n\t}\n\n\t/** Names of every endpoint, alphabetical. Convenience for error\n\t *  messages that want to list \"the supported names are: ...\". */\n\tnames(): ReadonlyArray<string> {\n\t\treturn this.entries.map((e) => e.name);\n\t}\n}\n"],"mappings":";;AAyBA,IAAa,mBAAb,MAA8B;CAC7B;CACA;CAEA,YAAY,SAA0C;EAIrD,MAAM,SAAS,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,MAAO,EAAE,OAAO,EAAE,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,IAAI,EAAG;AAC5F,OAAK,UAAU;EACf,MAAM,sBAAM,IAAI,KAA+B;AAC/C,OAAK,MAAM,SAAS,OAAQ,KAAI,IAAI,MAAM,MAAM,MAAM;AACtD,OAAK,cAAc;;;;;CAMpB,OAAO,MAA4C;AAClD,SAAO,KAAK,YAAY,IAAI,KAAK;;;;CAKlC,YAAY,WAAoD;AAC/D,SAAO,KAAK,QAAQ,QAAQ,MAAM,EAAE,cAAc,UAAU;;;;;CAM7D,OAAO,cAAuD;AAC7D,SAAO,KAAK,QAAQ,QAAQ,MAAM,EAAE,iBAAiB,aAAa;;;CAInE,MAAuC;AACtC,SAAO,KAAK;;;;CAKb,QAA+B;AAC9B,SAAO,KAAK,QAAQ,KAAK,MAAM,EAAE,KAAK"}
+{"version":3,"file":"endpoint-registry.mjs","names":[],"sources":["../../../src/build-integrations/runtime/endpoint-registry.ts"],"sourcesContent":["// Typed endpoint lookup.\n//\n// `EndpointRegistry` wraps the manifest's flat `endpoints` map with\n// the small set of queries every consumer asks of it:\n//\n//   - `byName(name)`: the load-bearing lookup. Playwright `baseURL`\n//     and codegen emitters all key off endpoint name.\n//   - `byPluginKey(key)`: group endpoints by the plugin that emitted\n//     them. The CLI `status` command uses this to print one block\n//     per plugin.\n//   - `byKind(kind)`: filter on `wireProtocol` — currently one of\n//     `'http' | 'h2c' | 'tcp'`. Cheap projection; lets callers filter\n//     the gRPC or raw-TCP endpoints out of an HTTP-only health check.\n//   - `all()`: stable-ordered iteration. Order is alphabetical by\n//     endpoint name — the manifest writer emits in input-order, but\n//     consumer iteration shouldn't depend on plugin registration\n//     order.\n//\n// Plain class — no Effect, no Schema. Callable from any consumer\n// runtime (Node, browser bundle that imported the manifest via the\n// build-integration alias).\n\nimport type { ResolvedEndpoint } from './stack-context.ts';\n\n/** Read-only registry over the manifest's `endpoints` map. */\nexport class EndpointRegistry {\n\tprivate readonly entries: ReadonlyArray<ResolvedEndpoint>;\n\tprivate readonly byNameIndex: ReadonlyMap<string, ResolvedEndpoint>;\n\n\tconstructor(entries: ReadonlyArray<ResolvedEndpoint>) {\n\t\t// Defensive: sort by name so iteration is stable across\n\t\t// supervisor runs even if the writer hashed plugins in a\n\t\t// different order this time.\n\t\tconst sorted = [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));\n\t\tthis.entries = sorted;\n\t\tconst map = new Map<string, ResolvedEndpoint>();\n\t\tfor (const entry of sorted) map.set(entry.name, entry);\n\t\tthis.byNameIndex = map;\n\t}\n\n\t/** Look up an endpoint by its declared name. Returns `undefined`\n\t *  when the name isn't in the manifest — callers that want a hard\n\t *  fail should `??` to a thrown error. */\n\tbyName(name: string): ResolvedEndpoint | undefined {\n\t\treturn this.byNameIndex.get(name);\n\t}\n\n\t/** Group endpoints by the plugin that emitted them. Used by the\n\t *  CLI status output. */\n\tbyPluginKey(pluginKey: string): ReadonlyArray<ResolvedEndpoint> {\n\t\treturn this.entries.filter((e) => e.pluginKey === pluginKey);\n\t}\n\n\t/** Filter endpoints by wire protocol — currently `'http' | 'h2c' |\n\t *  'tcp'`. Typed as `string` for forward-compat with plugin-added\n\t *  protocols; mistyped values just return an empty array. */\n\tbyKind(wireProtocol: string): ReadonlyArray<ResolvedEndpoint> {\n\t\treturn this.entries.filter((e) => e.wireProtocol === wireProtocol);\n\t}\n\n\t/** All endpoints, alphabetical by name. */\n\tall(): ReadonlyArray<ResolvedEndpoint> {\n\t\treturn this.entries;\n\t}\n\n\t/** Names of every endpoint, alphabetical. Convenience for error\n\t *  messages that want to list \"the supported names are: ...\". */\n\tnames(): ReadonlyArray<string> {\n\t\treturn this.entries.map((e) => e.name);\n\t}\n}\n"],"mappings":";;AAyBA,IAAa,mBAAb,MAA8B;CAC7B;CACA;CAEA,YAAY,SAA0C;EAIrD,MAAM,SAAS,CAAC,GAAG,OAAO,CAAC,CAAC,MAAM,GAAG,MAAO,EAAE,OAAO,EAAE,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,IAAI,CAAE;EAC3F,KAAK,UAAU;EACf,MAAM,sBAAM,IAAI,IAA8B;EAC9C,KAAK,MAAM,SAAS,QAAQ,IAAI,IAAI,MAAM,MAAM,KAAK;EACrD,KAAK,cAAc;CACpB;;;;CAKA,OAAO,MAA4C;EAClD,OAAO,KAAK,YAAY,IAAI,IAAI;CACjC;;;CAIA,YAAY,WAAoD;EAC/D,OAAO,KAAK,QAAQ,QAAQ,MAAM,EAAE,cAAc,SAAS;CAC5D;;;;CAKA,OAAO,cAAuD;EAC7D,OAAO,KAAK,QAAQ,QAAQ,MAAM,EAAE,iBAAiB,YAAY;CAClE;;CAGA,MAAuC;EACtC,OAAO,KAAK;CACb;;;CAIA,QAA+B;EAC9B,OAAO,KAAK,QAAQ,KAAK,MAAM,EAAE,IAAI;CACtC;AACD"}

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

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/build-integrations/runtime/errors.ts"],"sourcesContent":["// Build-integrations / runtime errors.\n//\n// The read-side surface for consumer code (apps, build tools). Two\n// failure shapes that callers care about distinguishing:\n//\n//   - `ManifestDiscoveryError`: no manifest could be located. Includes\n//     a recovery hint (\"run `devstack up`\") and the candidate path the\n//     resolver expected.\n//   - `ManifestShapeError`: a manifest was found but failed to parse\n//     or decode. The two phases (`parse` vs `shape`) drive distinct\n//     recovery recipes the caller can print.\n//\n// These are PLAIN classes (no Effect tags) because the read surface is\n// sync-blocking — apps load the manifest at startup and rely on plain\n// `try` / `catch`. The Effect-flavored read path (CLI / codegen) wraps\n// these into structured failure channels.\n\n/** Phase of a `ManifestDiscoveryError`. `walk-up` means the resolver\n *  walked from cwd to root without finding a stack-scoped manifest;\n *  `env-missing` means `DEVSTACK_MANIFEST_PATH` (top-precedence\n *  override) pointed at a file that doesn't exist; `override-missing`\n *  means a caller-supplied `manifestPath` / `override` doesn't exist;\n *  `required-missing` is the catch-all for the `required: true`\n *  branches. */\nexport type ManifestDiscoveryPhase =\n\t| 'walk-up'\n\t| 'env-missing'\n\t| 'override-missing'\n\t| 'required-missing';\n\n/** Thrown when the manifest cannot be located on disk. The message\n *  embeds the candidate path and the canonical recovery recipe\n *  (`run devstack up`); the field shape is stable so structured-log\n *  consumers can pattern-match without parsing strings. */\nexport class ManifestDiscoveryError extends Error {\n\toverride readonly name = 'ManifestDiscoveryError';\n\treadonly phase: ManifestDiscoveryPhase;\n\treadonly path: string | undefined;\n\toverride readonly cause?: unknown;\n\tconstructor(args: {\n\t\treadonly phase: ManifestDiscoveryPhase;\n\t\treadonly message: string;\n\t\treadonly path?: string;\n\t\treadonly cause?: unknown;\n\t}) {\n\t\tsuper(args.message);\n\t\tthis.phase = args.phase;\n\t\tthis.path = args.path;\n\t\tif (args.cause !== undefined) this.cause = args.cause;\n\t}\n}\n\n/** Phase of a `ManifestShapeError`. `parse` means `JSON.parse` rejected\n *  the bytes (truncation mid-write, hand-edit); `shape` means the bytes\n *  parsed but the decoded value failed schema validation (wrong / stale\n *  envelope shape); `version` means the manifest's `manifestVersion`\n *  doesn't match the version this consumer was built against. */\nexport type ManifestShapePhase = 'parse' | 'shape' | 'version';\n\n/** Thrown when a discovered manifest exists but fails to parse / decode\n *  / version-match. Carries the offending path so the recovery recipe\n *  (`rm <path> && devstack up`) is actionable. */\nexport class ManifestShapeError extends Error {\n\toverride readonly name = 'ManifestShapeError';\n\treadonly phase: ManifestShapePhase;\n\treadonly path: string;\n\toverride readonly cause?: unknown;\n\tconstructor(args: {\n\t\treadonly phase: ManifestShapePhase;\n\t\treadonly message: string;\n\t\treadonly path: string;\n\t\treadonly cause?: unknown;\n\t}) {\n\t\tsuper(args.message);\n\t\tthis.phase = args.phase;\n\t\tthis.path = args.path;\n\t\tif (args.cause !== undefined) this.cause = args.cause;\n\t}\n}\n\n/** Thrown by `coldStartUrl(endpoint)` when the endpoint name is not\n *  registered in the conventional-routes table and no manifest is\n *  available either. The message lists the supported endpoint names\n *  (derived from the registry, not hard-coded) so typos surface\n *  obviously. */\nexport class NoConventionalRouteError extends Error {\n\toverride readonly name = 'NoConventionalRouteError';\n\treadonly endpoint: string;\n\treadonly supported: ReadonlyArray<string>;\n\tconstructor(args: {\n\t\treadonly endpoint: string;\n\t\treadonly supported: ReadonlyArray<string>;\n\t\treadonly message: string;\n\t}) {\n\t\tsuper(args.message);\n\t\tthis.endpoint = args.endpoint;\n\t\tthis.supported = args.supported;\n\t}\n}\n"],"mappings":";;;;;AAkCA,IAAa,yBAAb,cAA4C,MAAM;CACjD,OAAyB;CACzB;CACA;CACA;CACA,YAAY,MAKT;AACF,QAAM,KAAK,QAAQ;AACnB,OAAK,QAAQ,KAAK;AAClB,OAAK,OAAO,KAAK;AACjB,MAAI,KAAK,UAAU,KAAA,EAAW,MAAK,QAAQ,KAAK;;;;;;AAclD,IAAa,qBAAb,cAAwC,MAAM;CAC7C,OAAyB;CACzB;CACA;CACA;CACA,YAAY,MAKT;AACF,QAAM,KAAK,QAAQ;AACnB,OAAK,QAAQ,KAAK;AAClB,OAAK,OAAO,KAAK;AACjB,MAAI,KAAK,UAAU,KAAA,EAAW,MAAK,QAAQ,KAAK;;;;;;;;AASlD,IAAa,2BAAb,cAA8C,MAAM;CACnD,OAAyB;CACzB;CACA;CACA,YAAY,MAIT;AACF,QAAM,KAAK,QAAQ;AACnB,OAAK,WAAW,KAAK;AACrB,OAAK,YAAY,KAAK"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/build-integrations/runtime/errors.ts"],"sourcesContent":["// Build-integrations / runtime errors.\n//\n// The read-side surface for consumer code (apps, build tools). Two\n// failure shapes that callers care about distinguishing:\n//\n//   - `ManifestDiscoveryError`: no manifest could be located. Includes\n//     a recovery hint (\"run `devstack up`\") and the candidate path the\n//     resolver expected.\n//   - `ManifestShapeError`: a manifest was found but failed to parse\n//     or decode. The two phases (`parse` vs `shape`) drive distinct\n//     recovery recipes the caller can print.\n//\n// These are PLAIN classes (no Effect tags) because the read surface is\n// sync-blocking — apps load the manifest at startup and rely on plain\n// `try` / `catch`. The Effect-flavored read path (CLI / codegen) wraps\n// these into structured failure channels.\n\n/** Phase of a `ManifestDiscoveryError`. `walk-up` means the resolver\n *  walked from cwd to root without finding a stack-scoped manifest;\n *  `env-missing` means `DEVSTACK_MANIFEST_PATH` (top-precedence\n *  override) pointed at a file that doesn't exist; `override-missing`\n *  means a caller-supplied `manifestPath` / `override` doesn't exist;\n *  `required-missing` is the catch-all for the `required: true`\n *  branches. */\nexport type ManifestDiscoveryPhase =\n\t| 'walk-up'\n\t| 'env-missing'\n\t| 'override-missing'\n\t| 'required-missing';\n\n/** Thrown when the manifest cannot be located on disk. The message\n *  embeds the candidate path and the canonical recovery recipe\n *  (`run devstack up`); the field shape is stable so structured-log\n *  consumers can pattern-match without parsing strings. */\nexport class ManifestDiscoveryError extends Error {\n\toverride readonly name = 'ManifestDiscoveryError';\n\treadonly phase: ManifestDiscoveryPhase;\n\treadonly path: string | undefined;\n\toverride readonly cause?: unknown;\n\tconstructor(args: {\n\t\treadonly phase: ManifestDiscoveryPhase;\n\t\treadonly message: string;\n\t\treadonly path?: string;\n\t\treadonly cause?: unknown;\n\t}) {\n\t\tsuper(args.message);\n\t\tthis.phase = args.phase;\n\t\tthis.path = args.path;\n\t\tif (args.cause !== undefined) this.cause = args.cause;\n\t}\n}\n\n/** Phase of a `ManifestShapeError`. `parse` means `JSON.parse` rejected\n *  the bytes (truncation mid-write, hand-edit); `shape` means the bytes\n *  parsed but the decoded value failed schema validation (wrong / stale\n *  envelope shape); `version` means the manifest's `manifestVersion`\n *  doesn't match the version this consumer was built against. */\nexport type ManifestShapePhase = 'parse' | 'shape' | 'version';\n\n/** Thrown when a discovered manifest exists but fails to parse / decode\n *  / version-match. Carries the offending path so the recovery recipe\n *  (`rm <path> && devstack up`) is actionable. */\nexport class ManifestShapeError extends Error {\n\toverride readonly name = 'ManifestShapeError';\n\treadonly phase: ManifestShapePhase;\n\treadonly path: string;\n\toverride readonly cause?: unknown;\n\tconstructor(args: {\n\t\treadonly phase: ManifestShapePhase;\n\t\treadonly message: string;\n\t\treadonly path: string;\n\t\treadonly cause?: unknown;\n\t}) {\n\t\tsuper(args.message);\n\t\tthis.phase = args.phase;\n\t\tthis.path = args.path;\n\t\tif (args.cause !== undefined) this.cause = args.cause;\n\t}\n}\n\n/** Thrown by `coldStartUrl(endpoint)` when the endpoint name is not\n *  registered in the conventional-routes table and no manifest is\n *  available either. The message lists the supported endpoint names\n *  (derived from the registry, not hard-coded) so typos surface\n *  obviously. */\nexport class NoConventionalRouteError extends Error {\n\toverride readonly name = 'NoConventionalRouteError';\n\treadonly endpoint: string;\n\treadonly supported: ReadonlyArray<string>;\n\tconstructor(args: {\n\t\treadonly endpoint: string;\n\t\treadonly supported: ReadonlyArray<string>;\n\t\treadonly message: string;\n\t}) {\n\t\tsuper(args.message);\n\t\tthis.endpoint = args.endpoint;\n\t\tthis.supported = args.supported;\n\t}\n}\n"],"mappings":";;;;;AAkCA,IAAa,yBAAb,cAA4C,MAAM;CACjD,OAAyB;CACzB;CACA;CACA;CACA,YAAY,MAKT;EACF,MAAM,KAAK,OAAO;EAClB,KAAK,QAAQ,KAAK;EAClB,KAAK,OAAO,KAAK;EACjB,IAAI,KAAK,UAAU,KAAA,GAAW,KAAK,QAAQ,KAAK;CACjD;AACD;;;;AAYA,IAAa,qBAAb,cAAwC,MAAM;CAC7C,OAAyB;CACzB;CACA;CACA;CACA,YAAY,MAKT;EACF,MAAM,KAAK,OAAO;EAClB,KAAK,QAAQ,KAAK;EAClB,KAAK,OAAO,KAAK;EACjB,IAAI,KAAK,UAAU,KAAA,GAAW,KAAK,QAAQ,KAAK;CACjD;AACD;;;;;;AAOA,IAAa,2BAAb,cAA8C,MAAM;CACnD,OAAyB;CACzB;CACA;CACA,YAAY,MAIT;EACF,MAAM,KAAK,OAAO;EAClB,KAAK,WAAW,KAAK;EACrB,KAAK,YAAY,KAAK;CACvB;AACD"}

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

@@ -58,7 +58,7 @@ const parseAndDecode = (raw, manifestPath) => {
 	if (decoded.manifestVersion !== 1) throw new ManifestShapeError({
 		phase: "version",
 		path: manifestPath,
-		message: `[devstack] manifest at ${manifestPath} has version ${decoded.manifestVersion}, but this consumer was built for version 1. RECOVERY: upgrade your devstack consumer dependency, or \`rm ${manifestPath} && devstack up\` to regenerate against the new version.`
+		message: `[devstack] manifest at ${manifestPath} has version ${decoded.manifestVersion}, but this consumer was built for version 1. RECOVERY: \`rm ${manifestPath} && devstack up\` to regenerate.`
 	});
 	return decoded;
 };
@@ -77,12 +77,12 @@ const project = (envelope, manifestPath) => {
 		identity: {
 			app: envelope.identity.app,
 			stack: envelope.identity.stack,
-			chain: envelope.identity.chain
+			network: envelope.identity.network
 		},
 		manifestPath,
 		manifestVersion: envelope.manifestVersion,
 		endpoints: new EndpointRegistry(entries),
-		services: envelope.services,
+		services: envelope.services ?? {},
 		extras: envelope.extras
 	};
 };

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 { 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"}
+{"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: \\`rm ${manifestPath} && devstack up\\` to regenerate.`,\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\tnetwork: envelope.identity.network,\n\t\t},\n\t\tmanifestPath,\n\t\tmanifestVersion: envelope.manifestVersion,\n\t\tendpoints: new EndpointRegistry(entries),\n\t\t// Default to an empty record when the manifest omits services.\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,SAAS,IAAI,CAAC;EAC7C,UAAU;CACX,CAAC;CAGD,IAAI,aAAa,KAAA,GAChB,MAAM,IAAI,uBAAuB;EAChC,OAAO;EACP,SAAS;CACV,CAAC;CAEF,OAAO;AACR;AAEA,MAAM,kBAAkB,KAAa,iBAA2C;CAC/E,IAAI;CACJ,IAAI;EACH,SAAS,kBAAkB,KAAK;GAC/B,QAAQ;GACR,UAAU,UAAU;EACrB,CAAC;CACF,SAAS,OAAO;EACf,MAAM,IAAI,mBAAmB;GAC5B,OAAO;GACP,MAAM;GACN,SACC,0BAA0B,aAAa,+DAErB,aAAa;GAChC;EACD,CAAC;CACF;CACA,IAAI;CACJ,IAAI;EACH,UAAU,kBAAkB,wBAAwB,QAAQ;GAC3D,QAAQ;GACR,UAAU,UAAU;EACrB,CAAC;CACF,SAAS,OAAO;EACf,MAAM,IAAI,mBAAmB;GAC5B,OAAO;GACP,MAAM;GACN,SACC,0BAA0B,aAAa,0FAErB,aAAa;GAChC;EACD,CAAC;CACF;CACA,IAAI,QAAQ,oBAAA,GACX,MAAM,IAAI,mBAAmB;EAC5B,OAAO;EACP,MAAM;EACN,SACC,0BAA0B,aAAa,eAAe,QAAQ,gBAAgB,8DAE5D,aAAa;CACjC,CAAC;CAEF,OAAO;AACR;;AAGA,MAAM,WAAW,UAA4B,iBAAuC;CACnF,MAAM,UAA8B,CAAC;CACrC,KAAK,MAAM,OAAO,OAAO,OAAO,SAAS,SAAS,GACjD,QAAQ,KAAK;EACZ,MAAM,IAAI;EACV,KAAK,IAAI;EACT,YAAY,IAAI;EAChB,cAAc,IAAI;EAClB,WAAW,IAAI;EACf,aAAa,IAAI;CAClB,CAAC;CAEF,OAAO;EACN,UAAU;GACT,KAAK,SAAS,SAAS;GACvB,OAAO,SAAS,SAAS;GACzB,SAAS,SAAS,SAAS;EAC5B;EACA;EACA,iBAAiB,SAAS;EAC1B,WAAW,IAAI,iBAAiB,OAAO;EAEvC,UAAU,SAAS,YAAY,CAAC;EAChC,QAAQ,SAAS;CAClB;AACD;;;;;AAMA,MAAa,oCAAoC,SAAyC;CACzF,UAAU,IAAI;CACd,iBAAiB,IAAI;CACrB,UAAU,IAAI;CACd,WAAW,OAAO,YACjB,IAAI,UAAU,IAAI,CAAC,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;CAChB,CACD,CAAC,CACF;CACA,QAAQ,IAAI;AACb;;;;;;;;;;;;AAaA,MAAa,oBAAoB,OAAgC,CAAC,MAAoB;CACrF,MAAM,eAAe,oBAAoB,IAAI;CAC7C,IAAI;CACJ,IAAI;EACH,MAAM,aAAa,cAAc,MAAM;CACxC,SAAS,OAAO;EAIf,MAAM,IAAI,mBAAmB;GAC5B,OAAO;GACP,MAAM;GACN,SAAS,yCAAyC,aAAa,IAAI,OAAO,KAAK;GAC/E;EACD,CAAC;CACF;CAEA,OAAO,QADU,eAAe,KAAK,YACf,GAAG,YAAY;AACtC"}

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

@@ -3,8 +3,11 @@
  *  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. */
+/** Default stack name when neither an explicit option, `$DEVSTACK_STACK`,
+ *  nor the (opt-in) package-name rung yields a value. Re-export of the
+ *  CLI resolver's `DEFAULT_STACK_NAME` literal — the literal lives in
+ *  `inference-network.ts` because this module imports its inference
+ *  helper (see the module-cycle note there). */
 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
@@ -21,6 +24,12 @@ interface ResolveDiscoveryEnvOptions {
   readonly stack?: string;
   /** Explicit state-dir / runtime-root. Wins over both env vars. */
   readonly stateDir?: string;
+  /** Walk-up start for the package-name rung of the stack ladder,
+   *  mirroring the CLI's `resolveStackName`. Opt-in: omit it and the
+   *  resolver stays side-effect-free (no fs reads). When provided,
+   *  the `package.json` walk-up runs LAZILY — only when both the
+   *  explicit and `$DEVSTACK_STACK` rungs miss. */
+  readonly cwd?: string;
 }
 interface ResolvedDiscoveryEnv {
   /** Resolved stack name (never empty). */
@@ -33,14 +42,21 @@ interface ResolvedDiscoveryEnv {
 /**
  * Resolve the canonical stack + state-dir ladder.
  *
- * Precedence (highest → lowest), identical for both rungs:
- *   - stack:     `options.stack` > `$DEVSTACK_STACK` > `'main'`
+ * Precedence (highest → lowest):
+ *   - stack:     `options.stack` > `$DEVSTACK_STACK`
+ *                > nearest package.json `name` above `options.cwd`
+ *                  (rung skipped when `cwd` is omitted)
+ *                > `'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).
+ * The stack ladder matches the CLI's `resolveStackName`, so discovery
+ * agrees with `devstack up` about which stack a bare app runs (see the
+ * module header). Empty-string env values are treated as unset (a blank
+ * `DEVSTACK_STATE_DIR=` must not pin the state root to the cwd). No
+ * `process.env` read — callers pass the bag (a fixture in tests) — and
+ * no fs access unless `options.cwd` is provided AND the first two stack
+ * rungs miss (the package.json walk-up is lazy).
  */
 declare const resolveDiscoveryEnv: (env: Readonly<Record<string, string | undefined>>, options?: ResolveDiscoveryEnvOptions) => ResolvedDiscoveryEnv;
 //#endregion

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

@@ -1,11 +1,15 @@
+import { DEFAULT_STACK_NAME, inferPackageNameFromCwd } from "../../api/inference-network.mjs";
 //#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";
+/** Default stack name when neither an explicit option, `$DEVSTACK_STACK`,
+*  nor the (opt-in) package-name rung yields a value. Re-export of the
+*  CLI resolver's `DEFAULT_STACK_NAME` literal — the literal lives in
+*  `inference-network.ts` because this module imports its inference
+*  helper (see the module-cycle note there). */
+const DEFAULT_DISCOVERY_STACK = DEFAULT_STACK_NAME;
 /** 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
@@ -23,19 +27,28 @@ const firstNonEmpty = (...candidates) => {
 /**
 * Resolve the canonical stack + state-dir ladder.
 *
-* Precedence (highest → lowest), identical for both rungs:
-*   - stack:     `options.stack` > `$DEVSTACK_STACK` > `'main'`
+* Precedence (highest → lowest):
+*   - stack:     `options.stack` > `$DEVSTACK_STACK`
+*                > nearest package.json `name` above `options.cwd`
+*                  (rung skipped when `cwd` is omitted)
+*                > `'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).
+* The stack ladder matches the CLI's `resolveStackName`, so discovery
+* agrees with `devstack up` about which stack a bare app runs (see the
+* module header). Empty-string env values are treated as unset (a blank
+* `DEVSTACK_STATE_DIR=` must not pin the state root to the cwd). No
+* `process.env` read — callers pass the bag (a fixture in tests) — and
+* no fs access unless `options.cwd` is provided AND the first two stack
+* rungs miss (the package.json walk-up is lazy).
 */
-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"
-});
+const resolveDiscoveryEnv = (env, options = {}) => {
+	return {
+		stack: firstNonEmpty(options.stack?.trim(), env[DISCOVERY_ENV.STACK]?.trim()) ?? (options.cwd !== void 0 ? inferPackageNameFromCwd(options.cwd) : void 0) ?? DEFAULT_DISCOVERY_STACK,
+		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 };
 

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

@@ -1 +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"}
+{"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// The stack ladder mirrors the CLI's `resolveStackName`\n// (`api/inference-network.ts`): explicit > `$DEVSTACK_STACK` > nearest\n// package.json `name` > `'main'`. The package-name rung is opt-in via\n// `options.cwd` and exists because `devstack up` in a bare app (no\n// `stackName` in config, no env) names the stack after the package —\n// a discovery ladder that hard-defaulted to `'main'` would look for a\n// manifest the supervisor never wrote, so `pnpm test` (vitest loader),\n// the playwright stack-context, and the vite plugin's cold start all\n// missed a live stack.\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\nimport { DEFAULT_STACK_NAME, inferPackageNameFromCwd } from '../../api/inference-network.ts';\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, `$DEVSTACK_STACK`,\n *  nor the (opt-in) package-name rung yields a value. Re-export of the\n *  CLI resolver's `DEFAULT_STACK_NAME` literal — the literal lives in\n *  `inference-network.ts` because this module imports its inference\n *  helper (see the module-cycle note there). */\nexport const DEFAULT_DISCOVERY_STACK = DEFAULT_STACK_NAME;\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\t/** Walk-up start for the package-name rung of the stack ladder,\n\t *  mirroring the CLI's `resolveStackName`. Opt-in: omit it and the\n\t *  resolver stays side-effect-free (no fs reads). When provided,\n\t *  the `package.json` walk-up runs LAZILY — only when both the\n\t *  explicit and `$DEVSTACK_STACK` rungs miss. */\n\treadonly cwd?: 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 = (...candidates: ReadonlyArray<string | undefined>): 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):\n *   - stack:     `options.stack` > `$DEVSTACK_STACK`\n *                > nearest package.json `name` above `options.cwd`\n *                  (rung skipped when `cwd` is omitted)\n *                > `'main'`\n *   - stateDir:  `options.stateDir` > `$DEVSTACK_RUNTIME_ROOT`\n *                > `$DEVSTACK_STATE_DIR` > `'.devstack'`\n *\n * The stack ladder matches the CLI's `resolveStackName`, so discovery\n * agrees with `devstack up` about which stack a bare app runs (see the\n * module header). Empty-string env values are treated as unset (a blank\n * `DEVSTACK_STATE_DIR=` must not pin the state root to the cwd). No\n * `process.env` read — callers pass the bag (a fixture in tests) — and\n * no fs access unless `options.cwd` is provided AND the first two stack\n * rungs miss (the package.json walk-up is lazy).\n */\nexport const resolveDiscoveryEnv = (\n\tenv: Readonly<Record<string, string | undefined>>,\n\toptions: ResolveDiscoveryEnvOptions = {},\n): ResolvedDiscoveryEnv => {\n\tconst stackFromInputs = firstNonEmpty(options.stack?.trim(), env[DISCOVERY_ENV.STACK]?.trim());\n\treturn {\n\t\tstack:\n\t\t\tstackFromInputs ??\n\t\t\t(options.cwd !== undefined ? inferPackageNameFromCwd(options.cwd) : undefined) ??\n\t\t\tDEFAULT_DISCOVERY_STACK,\n\t\tstateDir:\n\t\t\tfirstNonEmpty(\n\t\t\t\toptions.stateDir,\n\t\t\t\tenv[DISCOVERY_ENV.RUNTIME_ROOT],\n\t\t\t\tenv[DISCOVERY_ENV.STATE_DIR],\n\t\t\t) ?? DEFAULT_DISCOVERY_STATE_DIR,\n\t};\n};\n"],"mappings":";;;;;AAkCA,MAAa,8BAA8B;;;;;;AAO3C,MAAa,0BAA0B;;;;;AAMvC,MAAa,gBAAgB;CAC5B,OAAO;CACP,cAAc;;CAEd,WAAW;CACX,eAAe;AAChB;AAwBA,MAAM,iBAAiB,GAAG,eAAsE;CAC/F,KAAK,MAAM,aAAa,YACvB,IAAI,cAAc,KAAA,KAAa,cAAc,IAAI,OAAO;AAG1D;;;;;;;;;;;;;;;;;;;;AAqBA,MAAa,uBACZ,KACA,UAAsC,CAAC,MACb;CAE1B,OAAO;EACN,OAFuB,cAAc,QAAQ,OAAO,KAAK,GAAG,IAAI,cAAc,MAAM,EAAE,KAAK,CAG5E,MACb,QAAQ,QAAQ,KAAA,IAAY,wBAAwB,QAAQ,GAAG,IAAI,KAAA,MACpE;EACD,UACC,cACC,QAAQ,UACR,IAAI,cAAc,eAClB,IAAI,cAAc,UACnB,KAAA;CACF;AACD"}

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

@@ -7,7 +7,7 @@ import { EndpointRegistry } from "./endpoint-registry.mjs";
 interface StackIdentity {
   readonly app: string;
   readonly stack: string;
-  readonly chain: string;
+  readonly network: string;
 }
 /** Flat endpoint entry exposed to consumers. Mirrors the substrate's
  *  `EndpointEntry` but uses plain strings (no `Brand<>`) so callers
@@ -28,7 +28,7 @@ interface ResolvedEndpoint {
  *  schema decoded": discovery surfaces add the resolved `manifestPath`
  *  and the typed `endpoints` registry that wraps the flat map. */
 interface StackContext {
-  /** Stack identity — name / app / chain. */
+  /** Stack identity — name / app / network. */
   readonly identity: StackIdentity;
   /** Absolute path to the on-disk manifest the projection derives
    *  from. Used by error messages and by callers that want to watch

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

@@ -4,13 +4,59 @@
  *  prefix in three derivable places: this plugin option, the
  *  `tsconfig` `paths` entry, and its import specifiers. */
 declare const DEFAULT_GENERATED_ALIAS = "@generated";
+/** Default dev-extras import-alias prefix. Resolves the PRIMARY stack's
+ *  `.devstack/stacks/<stack>/generated-extras` tree (dev-only / secret
+ *  artifacts — `accounts.ts`, `dev-wallet.ts`). Mirror the `@generated`
+ *  three-place discipline: this option, the `tsconfig` `paths` entry,
+ *  and the import specifiers. */
+declare const DEFAULT_DEV_EXTRAS_ALIAS = "@devstack-dev";
 interface DevstackVitePluginOptions {
   /** Import-alias prefix. Default `'@generated'`. */
   readonly alias?: string;
+  /** Dev-extras import-alias prefix. Default `'@devstack-dev'`. */
+  readonly devExtrasAlias?: string;
   /** Explicit generated dir — bypasses manifest discovery entirely
    *  (escape hatch for unusual layouts / tests). Relative paths
    *  resolve against the Vite root. */
   readonly generatedDir?: string;
+  /** Explicit dev-extras dir — bypasses manifest discovery. Relative
+   *  paths resolve against the Vite root. */
+  readonly extrasDir?: string;
+  /** Inject + register the devstack dev wallet on the page in DEV
+   *  (wallet-standard, so dApp Kit auto-discovers it). Defaults to
+   *  `true`. Production builds (`command === 'build'`) inject nothing
+   *  regardless. */
+  readonly injectDevWallet?: boolean;
+  /** Auto-approve all dev-wallet signing requests (headless Playwright /
+   *  in-app "Open/Join as" buttons). Defaults to the `DEVSTACK_AUTO_APPROVE`
+   *  env (`'1'`/`'true'`), then to the active network's `autoApproveSigning`
+   *  per-network policy (ON for every network except live `mainnet`). A
+   *  single switch, replacing per-app `VITE_*_AUTO_APPROVE`.
+   *
+   *  HARD-CLAMP: on live `mainnet` the per-network policy forces
+   *  auto-approve OFF — a real-funds signature is NEVER granted without a
+   *  human in the loop. An explicit `autoApprove: true` here, or
+   *  `DEVSTACK_AUTO_APPROVE`, still take precedence (the author opted in
+   *  deliberately), but the policy default never silently auto-approves on
+   *  mainnet. */
+  readonly autoApprove?: boolean;
+  /** Per-network overrides for the dev-convenience policy (the same
+   *  `networkOptions` shape `defineDevstack` takes, forwarded verbatim).
+   *  Only the `autoApproveSigning` field is read here, to resolve the
+   *  auto-approve default for the active network. Omitted ⇒ the built-in
+   *  policy (ON except live `mainnet`) applies. The override RECORD is not
+   *  otherwise on disk, so an app that customizes per-network signing must
+   *  thread it here explicitly; the mainnet hard-clamp holds regardless. */
+  readonly networkOptions?: Readonly<Record<string, unknown>>;
+  /** Production id-config FILE — the known deployment's `devstack-ids.json`
+   *  (same schema the dev stack writes), committed at e.g.
+   *  `config/<network>.ids.json`. Used only for `command === 'build'` to
+   *  inject `__DEVSTACK_IDS__`. Relative paths resolve against the Vite
+   *  root. If omitted, the `DEVSTACK_IDS_FILE` env (a path pointer) is used.
+   *  Neither ⇒ no ids baked, and the generated resolver throws loudly at
+   *  id-access time. We deliberately take a FILE, not a JSON env blob: a
+   *  real deployment's ids are many + nested. */
+  readonly ids?: string;
 }
 /** A `vite` `Plugin`'s `config` hook receives the partial user config.
  *  We only ever read `config.root` and return a `resolve.alias` patch,
@@ -19,33 +65,52 @@ interface DevstackVitePluginOptions {
  *  presets avoid importing their optional peer at module init). */
 interface ViteUserConfigLike {
   readonly root?: string;
+  readonly command?: 'build' | 'serve';
+}
+/** The structural `Plugin` shape we return — `name`, a `config` hook, and
+ *  the DEV-only dev-wallet-injection hooks. Typed as the loose object Vite
+ *  accepts (Vite's `Plugin` is structurally compatible) so callers spread
+ *  it into `plugins: []` without devstack depending on `vite`. */
+/** Vite's `config` hook second arg — `{ command, mode }`. We read only
+ *  `command` to pick the dev vs prod id-injection source. */
+interface ViteConfigEnvLike {
+  readonly command?: 'build' | 'serve';
 }
-/** 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 config: (config: ViteUserConfigLike, env?: ViteConfigEnvLike) => {
     readonly resolve: {
       readonly alias: Record<string, string>;
+      readonly dedupe?: string[];
+    };
+    readonly optimizeDeps?: {
+      readonly include: string[];
     };
+    /** Build-time `define` injecting the on-chain ids as the
+     *  `__DEVSTACK_IDS__` global (the generated resolver reads it). */
+    readonly define: Record<string, string>;
   };
+  /** Capture the resolved command so injection is DEV-only. */
+  readonly configResolved: (config: ViteUserConfigLike) => void;
+  /** Resolve the dev-wallet virtual module. */
+  readonly resolveId: (id: string) => string | undefined;
+  /** Emit the dev-wallet register module (or a no-op when not applicable). */
+  readonly load: (id: string) => string | undefined;
+  /** Inject a `<script type="module">` importing the virtual module into
+   *  the dev page's HTML. DEV-only. The return shape mirrors a structural
+   *  subset of Vite's `IndexHtmlTransformResult` (mutable `tags`,
+   *  `injectTo` as the literal `'head'`) so the plugin stays assignable to
+   *  Vite's `Plugin` without devstack importing `vite`. */
+  readonly transformIndexHtml: (html: string) => {
+    html: string;
+    tags: Array<{
+      tag: string;
+      attrs: Record<string, string | boolean>;
+      injectTo: 'head';
+    }>;
+  } | undefined;
 }
-/**
- * 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 };
+export { DEFAULT_DEV_EXTRAS_ALIAS, DEFAULT_GENERATED_ALIAS, DevstackVitePlugin, DevstackVitePluginOptions, devstackVitePlugin };
 //# sourceMappingURL=index.d.mts.map