@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +1,124 @@
+import { DEFAULT_STACK_NAME } from "../../api/inference-network.mjs";
+import { ManifestDiscoveryError } from "./errors.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+//#region src/build-integrations/runtime/discover.ts
+/** Default name of the supervisor's per-user state directory. Mirrors
+*  the L0 path resolver. Held here as a literal so the discover walk
+*  doesn't reach into the substrate package. */
+const DEFAULT_STATE_DIR = ".devstack";
+/** Default stack name when neither `opts.stack` nor `$DEVSTACK_STACK`
+*  yields a useful value. */
+const DEFAULT_STACK = DEFAULT_STACK_NAME;
+const resolveBuildIntegrationStack = (explicit, env = process.env) => {
+	const trimmed = (explicit ?? env.DEVSTACK_STACK)?.trim();
+	return trimmed !== void 0 && trimmed.length > 0 ? trimmed : DEFAULT_STACK;
+};
+/** Read `name` out of `<dir>/package.json`, strip the `@scope/`
+*  prefix and any leading non-alphanumerics. Returns `undefined`
+*  when the file is missing / unreadable / has no name field. */
+const readAppName = (dir) => {
+	try {
+		const pkg = JSON.parse(readFileSync(resolve(dir, "package.json"), "utf8"));
+		if (typeof pkg.name !== "string") return void 0;
+		const stripped = pkg.name.replace(/^@[^/]+\//, "").replace(/^[^a-zA-Z0-9]+/, "");
+		return stripped.length > 0 ? stripped : void 0;
+	} catch {
+		return;
+	}
+};
+/** Walk up from `cwd` to find the closest `package.json` and return
+*  its un-scoped `name` field. Returns `undefined` if no package.json
+*  is reachable. Bounded to 32 levels — defense against pathological
+*  symlink loops. */
+const readAppNameWalkup = (cwd) => {
+	let dir = resolve(cwd);
+	for (let i = 0; i < 32; i += 1) {
+		const name = readAppName(dir);
+		if (name !== void 0) return name;
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+};
+/** Resolve the framework-neutral identity tuple build integrations
+*  need at config-load time. The manifest path is returned even when
+*  it does not exist yet so cold-start callers can still compute
+*  conventional URLs and watch-ignore paths. */
+const discoverBuildIntegrationIdentity = (options = {}) => {
+	const env = options.env ?? process.env;
+	const cwd = options.cwd ?? process.cwd();
+	const stack = resolveBuildIntegrationStack(options.stack, env);
+	const stateDirName = options.stateDir ?? env.DEVSTACK_STATE_DIR ?? ".devstack";
+	const discovered = discoverManifestPath({
+		cwd,
+		stack,
+		stateDir: stateDirName,
+		env
+	});
+	const manifestPath = discovered ?? resolve(cwd, stateDirName, "stacks", stack, "manifest.json");
+	const stateDir = discovered !== void 0 ? dirname(dirname(dirname(discovered))) : resolve(cwd, stateDirName);
+	return {
+		app: options.app ?? env.DEVSTACK_APP ?? readAppNameWalkup(cwd),
+		stack,
+		stateDir,
+		manifestPath
+	};
+};
+/**
+* Locate an existing devstack manifest on disk. Sync — Playwright's
+* config loader and apps' startup paths both depend on this being
+* synchronous.
+*
+* Returns the absolute path of the first match per the precedence
+* documented at the top of this module, or `undefined` if no candidate
+* exists. Pass `{ required: true }` to throw `ManifestDiscoveryError`
+* on miss instead.
+*/
+function discoverManifestPath(opts = {}) {
+	const env = opts.env ?? process.env;
+	const envOverride = env.DEVSTACK_MANIFEST_PATH;
+	if (envOverride !== void 0 && envOverride !== "") {
+		const resolved = resolve(envOverride);
+		if (existsSync(resolved)) return resolved;
+		if (opts.required === true) throw new ManifestDiscoveryError({
+			phase: "env-missing",
+			path: resolved,
+			message: `[devstack] DEVSTACK_MANIFEST_PATH points at ${resolved}, but no file exists there. Unset the env var or run \`devstack up\` to write the manifest.`
+		});
+		return;
+	}
+	if (opts.override !== void 0 && opts.override !== "") {
+		const resolved = resolve(opts.override);
+		if (existsSync(resolved)) return resolved;
+		if (opts.required === true) throw new ManifestDiscoveryError({
+			phase: "override-missing",
+			path: resolved,
+			message: `[devstack] explicit manifest path ${resolved} does not exist. Run \`devstack up\` to write the manifest first.`
+		});
+		return;
+	}
+	const startDir = opts.cwd ?? process.cwd();
+	const stack = resolveBuildIntegrationStack(opts.stack, env);
+	const stateDir = opts.stateDir ?? env.DEVSTACK_STATE_DIR ?? ".devstack";
+	let dir = resolve(startDir);
+	while (true) {
+		const candidate = join(dir, stateDir, "stacks", stack, "manifest.json");
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	if (opts.required === true) {
+		const expected = resolve(startDir, stateDir, "stacks", stack, "manifest.json");
+		throw new ManifestDiscoveryError({
+			phase: "walk-up",
+			path: expected,
+			message: `[devstack] no manifest.json found walking up from ${startDir} (looked for ${stateDir}/stacks/${stack}/manifest.json at each level). Run \`devstack up\` — it writes the manifest at ${expected}.`
+		});
+	}
+}
+//#endregion
+export { DEFAULT_STACK, DEFAULT_STATE_DIR, discoverBuildIntegrationIdentity, discoverManifestPath, readAppName, readAppNameWalkup, resolveBuildIntegrationStack };
+
+//# sourceMappingURL=discover.mjs.map

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

@@ -0,0 +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, readFileSync } from 'node:fs';\nimport { dirname, join, resolve } from 'node:path';\n\nimport { ManifestDiscoveryError } from './errors.ts';\nimport { DEFAULT_STACK_NAME } 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. */\nexport const DEFAULT_STATE_DIR = '.devstack';\n\n/** Default stack name when neither `opts.stack` nor `$DEVSTACK_STACK`\n *  yields a useful value. */\nexport const DEFAULT_STACK = DEFAULT_STACK_NAME;\n\nexport const resolveBuildIntegrationStack = (\n\texplicit: string | undefined,\n\tenv: Readonly<Record<string, string | undefined>> = process.env,\n): string => {\n\tconst selected = explicit ?? env.DEVSTACK_STACK;\n\tconst trimmed = selected?.trim();\n\treturn trimmed !== undefined && trimmed.length > 0 ? trimmed : DEFAULT_STACK;\n};\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 to `$DEVSTACK_STATE_DIR ?? '.devstack'`.\n\t *  Absolute paths are honored — the walk-up degenerates into a\n\t *  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\nexport interface BuildIntegrationIdentity {\n\treadonly app: string | undefined;\n\treadonly stack: string;\n\treadonly stateDir: string;\n\treadonly manifestPath: string;\n}\n\nexport interface DiscoverBuildIntegrationIdentityOptions {\n\t/** Resolution cwd. Defaults to `process.cwd()`. */\n\treadonly cwd?: string;\n\t/** Explicit app name. Overrides env + package.json walk-up. */\n\treadonly app?: string;\n\t/** Explicit stack name. Overrides `DEVSTACK_STACK`; otherwise\n\t *  defaults to `main`. */\n\treadonly stack?: string;\n\t/** Explicit state-dir name. Overrides `DEVSTACK_STATE_DIR`. */\n\treadonly stateDir?: string;\n\t/** Env bag for tests and config loaders. Defaults to `process.env`. */\n\treadonly env?: Readonly<Record<string, string | undefined>>;\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 = (dir: string): string | undefined => {\n\ttry {\n\t\tconst pkg = JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf8')) as {\n\t\t\tname?: string;\n\t\t};\n\t\tif (typeof pkg.name !== 'string') return undefined;\n\t\tconst stripped = pkg.name.replace(/^@[^/]+\\//, '').replace(/^[^a-zA-Z0-9]+/, '');\n\t\treturn stripped.length > 0 ? stripped : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n};\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 = (cwd: string): string | undefined => {\n\tlet dir = resolve(cwd);\n\tfor (let i = 0; i < 32; i += 1) {\n\t\tconst name = readAppName(dir);\n\t\tif (name !== undefined) return name;\n\t\tconst parent = dirname(dir);\n\t\tif (parent === dir) return undefined;\n\t\tdir = parent;\n\t}\n\treturn undefined;\n};\n\n/** Resolve the framework-neutral identity tuple build integrations\n *  need at config-load time. The manifest path is returned even when\n *  it does not exist yet so cold-start callers can still compute\n *  conventional URLs and watch-ignore paths. */\nexport const discoverBuildIntegrationIdentity = (\n\toptions: DiscoverBuildIntegrationIdentityOptions = {},\n): BuildIntegrationIdentity => {\n\tconst env = options.env ?? (process.env as Readonly<Record<string, string | undefined>>);\n\tconst cwd = options.cwd ?? process.cwd();\n\tconst stack = resolveBuildIntegrationStack(options.stack, env);\n\tconst stateDirName = options.stateDir ?? env.DEVSTACK_STATE_DIR ?? DEFAULT_STATE_DIR;\n\n\tconst discovered = discoverManifestPath({ cwd, stack, stateDir: stateDirName, env });\n\tconst manifestPath = discovered ?? resolve(cwd, stateDirName, 'stacks', stack, 'manifest.json');\n\tconst stateDir =\n\t\tdiscovered !== undefined ? dirname(dirname(dirname(discovered))) : resolve(cwd, stateDirName);\n\tconst app = options.app ?? env.DEVSTACK_APP ?? readAppNameWalkup(cwd);\n\n\treturn { app, stack, stateDir, manifestPath };\n};\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\tif (envOverride !== undefined && envOverride !== '') {\n\t\tconst resolved = resolve(envOverride);\n\t\tif (existsSync(resolved)) return resolved;\n\t\tif (opts.required === true) {\n\t\t\tthrow new ManifestDiscoveryError({\n\t\t\t\tphase: 'env-missing',\n\t\t\t\tpath: resolved,\n\t\t\t\tmessage:\n\t\t\t\t\t`[devstack] DEVSTACK_MANIFEST_PATH points at ${resolved}, but no file exists there. ` +\n\t\t\t\t\t`Unset the env var or run \\`devstack up\\` to write the manifest.`,\n\t\t\t});\n\t\t}\n\t\treturn undefined;\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\tif (opts.required === true) {\n\t\t\tthrow new ManifestDiscoveryError({\n\t\t\t\tphase: 'override-missing',\n\t\t\t\tpath: resolved,\n\t\t\t\tmessage:\n\t\t\t\t\t`[devstack] explicit manifest path ${resolved} does not exist. ` +\n\t\t\t\t\t`Run \\`devstack up\\` to write the manifest first.`,\n\t\t\t});\n\t\t}\n\t\treturn undefined;\n\t}\n\tconst startDir = opts.cwd ?? process.cwd();\n\tconst stack = resolveBuildIntegrationStack(opts.stack, env);\n\tconst stateDir = opts.stateDir ?? env.DEVSTACK_STATE_DIR ?? DEFAULT_STATE_DIR;\n\tlet dir = resolve(startDir);\n\twhile (true) {\n\t\tconst candidate = join(dir, stateDir, 'stacks', stack, 'manifest.json');\n\t\tif (existsSync(candidate)) return candidate;\n\t\tconst parent = dirname(dir);\n\t\tif (parent === dir) break;\n\t\tdir = parent;\n\t}\n\tif (opts.required === true) {\n\t\tconst expected = 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"],"mappings":";;;;;;;;AAuCA,MAAa,oBAAoB;;;AAIjC,MAAa,gBAAgB;AAE7B,MAAa,gCACZ,UACA,MAAoD,QAAQ,QAChD;CAEZ,MAAM,WADW,YAAY,IAAI,iBACP,MAAM;AAChC,QAAO,YAAY,KAAA,KAAa,QAAQ,SAAS,IAAI,UAAU;;;;;AAmDhE,MAAa,eAAe,QAAoC;AAC/D,KAAI;EACH,MAAM,MAAM,KAAK,MAAM,aAAa,QAAQ,KAAK,eAAe,EAAE,OAAO,CAAC;AAG1E,MAAI,OAAO,IAAI,SAAS,SAAU,QAAO,KAAA;EACzC,MAAM,WAAW,IAAI,KAAK,QAAQ,aAAa,GAAG,CAAC,QAAQ,kBAAkB,GAAG;AAChF,SAAO,SAAS,SAAS,IAAI,WAAW,KAAA;SACjC;AACP;;;;;;;AAQF,MAAa,qBAAqB,QAAoC;CACrE,IAAI,MAAM,QAAQ,IAAI;AACtB,MAAK,IAAI,IAAI,GAAG,IAAI,IAAI,KAAK,GAAG;EAC/B,MAAM,OAAO,YAAY,IAAI;AAC7B,MAAI,SAAS,KAAA,EAAW,QAAO;EAC/B,MAAM,SAAS,QAAQ,IAAI;AAC3B,MAAI,WAAW,IAAK,QAAO,KAAA;AAC3B,QAAM;;;;;;;AASR,MAAa,oCACZ,UAAmD,EAAE,KACvB;CAC9B,MAAM,MAAM,QAAQ,OAAQ,QAAQ;CACpC,MAAM,MAAM,QAAQ,OAAO,QAAQ,KAAK;CACxC,MAAM,QAAQ,6BAA6B,QAAQ,OAAO,IAAI;CAC9D,MAAM,eAAe,QAAQ,YAAY,IAAI,sBAAA;CAE7C,MAAM,aAAa,qBAAqB;EAAE;EAAK;EAAO,UAAU;EAAc;EAAK,CAAC;CACpF,MAAM,eAAe,cAAc,QAAQ,KAAK,cAAc,UAAU,OAAO,gBAAgB;CAC/F,MAAM,WACL,eAAe,KAAA,IAAY,QAAQ,QAAQ,QAAQ,WAAW,CAAC,CAAC,GAAG,QAAQ,KAAK,aAAa;AAG9F,QAAO;EAAE,KAFG,QAAQ,OAAO,IAAI,gBAAgB,kBAAkB,IAAI;EAEvD;EAAO;EAAU;EAAc;;;;;;;;;;;;AAa9C,SAAgB,qBAAqB,OAAoC,EAAE,EAAsB;CAChG,MAAM,MAAM,KAAK,OAAQ,QAAQ;CACjC,MAAM,cAAc,IAAI;AACxB,KAAI,gBAAgB,KAAA,KAAa,gBAAgB,IAAI;EACpD,MAAM,WAAW,QAAQ,YAAY;AACrC,MAAI,WAAW,SAAS,CAAE,QAAO;AACjC,MAAI,KAAK,aAAa,KACrB,OAAM,IAAI,uBAAuB;GAChC,OAAO;GACP,MAAM;GACN,SACC,+CAA+C,SAAS;GAEzD,CAAC;AAEH;;AAED,KAAI,KAAK,aAAa,KAAA,KAAa,KAAK,aAAa,IAAI;EACxD,MAAM,WAAW,QAAQ,KAAK,SAAS;AACvC,MAAI,WAAW,SAAS,CAAE,QAAO;AACjC,MAAI,KAAK,aAAa,KACrB,OAAM,IAAI,uBAAuB;GAChC,OAAO;GACP,MAAM;GACN,SACC,qCAAqC,SAAS;GAE/C,CAAC;AAEH;;CAED,MAAM,WAAW,KAAK,OAAO,QAAQ,KAAK;CAC1C,MAAM,QAAQ,6BAA6B,KAAK,OAAO,IAAI;CAC3D,MAAM,WAAW,KAAK,YAAY,IAAI,sBAAA;CACtC,IAAI,MAAM,QAAQ,SAAS;AAC3B,QAAO,MAAM;EACZ,MAAM,YAAY,KAAK,KAAK,UAAU,UAAU,OAAO,gBAAgB;AACvE,MAAI,WAAW,UAAU,CAAE,QAAO;EAClC,MAAM,SAAS,QAAQ,IAAI;AAC3B,MAAI,WAAW,IAAK;AACpB,QAAM;;AAEP,KAAI,KAAK,aAAa,MAAM;EAC3B,MAAM,WAAW,QAAQ,UAAU,UAAU,UAAU,OAAO,gBAAgB;AAC9E,QAAM,IAAI,uBAAuB;GAChC,OAAO;GACP,MAAM;GACN,SACC,qDAAqD,SAAS,eAC/C,SAAS,UAAU,MAAM,iFACW,SAAS;GAC7D,CAAC"}

package/dist/build-integrations/runtime/endpoint-registry.d.mts

@@ -0,0 +1,26 @@
+import { ResolvedEndpoint } from "./stack-context.mjs";
+
+//#region src/build-integrations/runtime/endpoint-registry.d.ts
+/** Read-only registry over the manifest's `endpoints` map. */
+declare class EndpointRegistry {
+  private readonly entries;
+  private readonly byNameIndex;
+  constructor(entries: ReadonlyArray<ResolvedEndpoint>);
+  /** Look up an endpoint by its declared name. Returns `undefined`
+   *  when the name isn't in the manifest — callers that want a hard
+   *  fail should `??` to a thrown error. */
+  byName(name: string): ResolvedEndpoint | undefined;
+  /** Group endpoints by the plugin that emitted them. Used by the
+   *  CLI status output. */
+  byPluginKey(pluginKey: string): ReadonlyArray<ResolvedEndpoint>;
+  /** Filter endpoints by wire protocol (`http`, `h2c`). */
+  byKind(wireProtocol: string): ReadonlyArray<ResolvedEndpoint>;
+  /** All endpoints, alphabetical by name. */
+  all(): ReadonlyArray<ResolvedEndpoint>;
+  /** Names of every endpoint, alphabetical. Convenience for error
+   *  messages that want to list "the supported names are: ...". */
+  names(): ReadonlyArray<string>;
+}
+//#endregion
+export { EndpointRegistry };
+//# sourceMappingURL=endpoint-registry.d.mts.map

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

@@ -0,0 +1,41 @@
+//#region src/build-integrations/runtime/endpoint-registry.ts
+/** Read-only registry over the manifest's `endpoints` map. */
+var EndpointRegistry = class {
+	entries;
+	byNameIndex;
+	constructor(entries) {
+		const sorted = [...entries].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+		this.entries = sorted;
+		const map = /* @__PURE__ */ new Map();
+		for (const entry of sorted) map.set(entry.name, entry);
+		this.byNameIndex = map;
+	}
+	/** Look up an endpoint by its declared name. Returns `undefined`
+	*  when the name isn't in the manifest — callers that want a hard
+	*  fail should `??` to a thrown error. */
+	byName(name) {
+		return this.byNameIndex.get(name);
+	}
+	/** Group endpoints by the plugin that emitted them. Used by the
+	*  CLI status output. */
+	byPluginKey(pluginKey) {
+		return this.entries.filter((e) => e.pluginKey === pluginKey);
+	}
+	/** Filter endpoints by wire protocol (`http`, `h2c`). */
+	byKind(wireProtocol) {
+		return this.entries.filter((e) => e.wireProtocol === wireProtocol);
+	}
+	/** All endpoints, alphabetical by name. */
+	all() {
+		return this.entries;
+	}
+	/** Names of every endpoint, alphabetical. Convenience for error
+	*  messages that want to list "the supported names are: ...". */
+	names() {
+		return this.entries.map((e) => e.name);
+	}
+};
+//#endregion
+export { EndpointRegistry };
+
+//# sourceMappingURL=endpoint-registry.mjs.map

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

@@ -0,0 +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)`: kind is currently `wireProtocol` (`http` vs\n//     `h2c`). Cheap projection; lets callers filter the gRPC endpoints\n//     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 (`http`, `h2c`). */\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;;;CAI7D,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"}

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

@@ -0,0 +1,64 @@
+//#region src/build-integrations/runtime/errors.d.ts
+/** Phase of a `ManifestDiscoveryError`. `walk-up` means the resolver
+ *  walked from cwd to root without finding a stack-scoped manifest;
+ *  `env-missing` means `DEVSTACK_MANIFEST_PATH` (top-precedence
+ *  override) pointed at a file that doesn't exist; `override-missing`
+ *  means a caller-supplied `manifestPath` / `override` doesn't exist;
+ *  `required-missing` is the catch-all for the `required: true`
+ *  branches. */
+type ManifestDiscoveryPhase = 'walk-up' | 'env-missing' | 'override-missing' | 'required-missing';
+/** Thrown when the manifest cannot be located on disk. The message
+ *  embeds the candidate path and the canonical recovery recipe
+ *  (`run devstack up`); the field shape is stable so structured-log
+ *  consumers can pattern-match without parsing strings. */
+declare class ManifestDiscoveryError extends Error {
+  readonly name = "ManifestDiscoveryError";
+  readonly phase: ManifestDiscoveryPhase;
+  readonly path: string | undefined;
+  readonly cause?: unknown;
+  constructor(args: {
+    readonly phase: ManifestDiscoveryPhase;
+    readonly message: string;
+    readonly path?: string;
+    readonly cause?: unknown;
+  });
+}
+/** Phase of a `ManifestShapeError`. `parse` means `JSON.parse` rejected
+ *  the bytes (truncation mid-write, hand-edit); `shape` means the bytes
+ *  parsed but the decoded value failed schema validation (wrong / stale
+ *  envelope shape); `version` means the manifest's `manifestVersion`
+ *  doesn't match the version this consumer was built against. */
+type ManifestShapePhase = 'parse' | 'shape' | 'version';
+/** Thrown when a discovered manifest exists but fails to parse / decode
+ *  / version-match. Carries the offending path so the recovery recipe
+ *  (`rm <path> && devstack up`) is actionable. */
+declare class ManifestShapeError extends Error {
+  readonly name = "ManifestShapeError";
+  readonly phase: ManifestShapePhase;
+  readonly path: string;
+  readonly cause?: unknown;
+  constructor(args: {
+    readonly phase: ManifestShapePhase;
+    readonly message: string;
+    readonly path: string;
+    readonly cause?: unknown;
+  });
+}
+/** Thrown by `coldStartUrl(endpoint)` when the endpoint name is not
+ *  registered in the conventional-routes table and no manifest is
+ *  available either. The message lists the supported endpoint names
+ *  (derived from the registry, not hard-coded) so typos surface
+ *  obviously. */
+declare class NoConventionalRouteError extends Error {
+  readonly name = "NoConventionalRouteError";
+  readonly endpoint: string;
+  readonly supported: ReadonlyArray<string>;
+  constructor(args: {
+    readonly endpoint: string;
+    readonly supported: ReadonlyArray<string>;
+    readonly message: string;
+  });
+}
+//#endregion
+export { ManifestDiscoveryError, ManifestDiscoveryPhase, ManifestShapeError, ManifestShapePhase, NoConventionalRouteError };
+//# sourceMappingURL=errors.d.mts.map

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

@@ -0,0 +1,51 @@
+//#region src/build-integrations/runtime/errors.ts
+/** Thrown when the manifest cannot be located on disk. The message
+*  embeds the candidate path and the canonical recovery recipe
+*  (`run devstack up`); the field shape is stable so structured-log
+*  consumers can pattern-match without parsing strings. */
+var ManifestDiscoveryError = class extends Error {
+	name = "ManifestDiscoveryError";
+	phase;
+	path;
+	cause;
+	constructor(args) {
+		super(args.message);
+		this.phase = args.phase;
+		this.path = args.path;
+		if (args.cause !== void 0) this.cause = args.cause;
+	}
+};
+/** Thrown when a discovered manifest exists but fails to parse / decode
+*  / version-match. Carries the offending path so the recovery recipe
+*  (`rm <path> && devstack up`) is actionable. */
+var ManifestShapeError = class extends Error {
+	name = "ManifestShapeError";
+	phase;
+	path;
+	cause;
+	constructor(args) {
+		super(args.message);
+		this.phase = args.phase;
+		this.path = args.path;
+		if (args.cause !== void 0) this.cause = args.cause;
+	}
+};
+/** Thrown by `coldStartUrl(endpoint)` when the endpoint name is not
+*  registered in the conventional-routes table and no manifest is
+*  available either. The message lists the supported endpoint names
+*  (derived from the registry, not hard-coded) so typos surface
+*  obviously. */
+var NoConventionalRouteError = class extends Error {
+	name = "NoConventionalRouteError";
+	endpoint;
+	supported;
+	constructor(args) {
+		super(args.message);
+		this.endpoint = args.endpoint;
+		this.supported = args.supported;
+	}
+};
+//#endregion
+export { ManifestDiscoveryError, ManifestShapeError, NoConventionalRouteError };
+
+//# sourceMappingURL=errors.mjs.map

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

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

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

@@ -0,0 +1,7 @@
+import { BuildIntegrationIdentity, DEFAULT_STACK, DEFAULT_STATE_DIR, DiscoverBuildIntegrationIdentityOptions, DiscoverManifestPathOptions, discoverBuildIntegrationIdentity, discoverManifestPath, readAppName, readAppNameWalkup } from "./discover.mjs";
+import { EndpointRegistry } from "./endpoint-registry.mjs";
+import { ResolvedEndpoint, StackContext, StackIdentity } from "./stack-context.mjs";
+import { CONSUMER_MANIFEST_VERSION, ReadStackContextOptions, manifestEnvelopeFromStackContext, readStackContext } from "./read-stack-context.mjs";
+import { ColdStartUrlOptions, ConventionalRoute, ConventionalRouteHint, ConventionalRouteHostInput, ConventionalRouteUrlInput, coldStartUrl, conventionalRouteHost, conventionalRouteUrl, conventionalRoutesFromHints, tryColdStartUrl } from "./cold-start-url.mjs";
+import { ManifestDiscoveryError, ManifestDiscoveryPhase, ManifestShapeError, ManifestShapePhase, NoConventionalRouteError } from "./errors.mjs";
+export { type BuildIntegrationIdentity, CONSUMER_MANIFEST_VERSION, type ColdStartUrlOptions, type ConventionalRoute, type ConventionalRouteHint, type ConventionalRouteHostInput, type ConventionalRouteUrlInput, DEFAULT_STACK, DEFAULT_STATE_DIR, type DiscoverBuildIntegrationIdentityOptions, type DiscoverManifestPathOptions, EndpointRegistry, ManifestDiscoveryError, type ManifestDiscoveryPhase, ManifestShapeError, type ManifestShapePhase, NoConventionalRouteError, type ReadStackContextOptions, type ResolvedEndpoint, type StackContext, type StackIdentity, coldStartUrl, conventionalRouteHost, conventionalRouteUrl, conventionalRoutesFromHints, discoverBuildIntegrationIdentity, discoverManifestPath, manifestEnvelopeFromStackContext, readAppName, readAppNameWalkup, readStackContext, tryColdStartUrl };

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

@@ -0,0 +1,6 @@
+import { ManifestDiscoveryError, ManifestShapeError, NoConventionalRouteError } from "./errors.mjs";
+import { DEFAULT_STACK, DEFAULT_STATE_DIR, discoverBuildIntegrationIdentity, discoverManifestPath, readAppName, readAppNameWalkup } from "./discover.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 };

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

@@ -0,0 +1,38 @@
+import { ManifestEnvelope } from "../../substrate/manifest.mjs";
+import { DiscoverManifestPathOptions } from "./discover.mjs";
+import { StackContext } from "./stack-context.mjs";
+
+//#region src/build-integrations/runtime/read-stack-context.d.ts
+/** Pinned manifest-envelope version this consumer build was compiled
+ *  against. Must match the substrate's `CURRENT_MANIFEST_VERSION`
+ *  (kept as a literal here so the read path doesn't reach into the
+ *  substrate's writer module just for a number). When the substrate
+ *  bumps, the consumer must bump in lockstep — the version mismatch
+ *  error message names the recovery recipe. */
+declare const CONSUMER_MANIFEST_VERSION: 1;
+interface ReadStackContextOptions extends DiscoverManifestPathOptions {
+  /** Caller-supplied explicit manifest path. When set, bypasses the
+   *  walk-up (still existence-checked). Named `manifestPath` for
+   *  ergonomic parity with the CLI's `--manifest-path` flag. */
+  readonly manifestPath?: string;
+}
+/** Reconstruct the manifest envelope from the runtime projection.
+ *  Integration adapters that preserve their older envelope-shaped
+ *  surfaces use this instead of duplicating endpoint-registry
+ *  projection logic. */
+declare const manifestEnvelopeFromStackContext: (ctx: StackContext) => ManifestEnvelope;
+/**
+ * Sync read + decode + project. Throws `ManifestDiscoveryError` (no
+ * manifest located) or `ManifestShapeError` (manifest found but
+ * malformed / wrong version).
+ *
+ * Used by:
+ *   - Apps' generated `stack-handle.ts` at startup.
+ *   - Playwright config-load (`baseURL`, `webServer.url`).
+ *   - CLI surfaces that prefer sync-then-Effect.try over a native
+ *     Effect read.
+ */
+declare const readStackContext: (opts?: ReadStackContextOptions) => StackContext;
+//#endregion
+export { CONSUMER_MANIFEST_VERSION, ReadStackContextOptions, manifestEnvelopeFromStackContext, readStackContext };
+//# sourceMappingURL=read-stack-context.d.mts.map

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

@@ -0,0 +1,130 @@
+import { ManifestEnvelopeSchema } from "../../substrate/manifest.mjs";
+import { ManifestDiscoveryError, ManifestShapeError } from "./errors.mjs";
+import { discoverManifestPath } from "./discover.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
+*  against. Must match the substrate's `CURRENT_MANIFEST_VERSION`
+*  (kept as a literal here so the read path doesn't reach into the
+*  substrate's writer module just for a number). When the substrate
+*  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({
+		...opts,
+		...override !== void 0 ? { override } : {},
+		required: true
+	});
+	if (resolved === void 0) throw new ManifestDiscoveryError({
+		phase: "required-missing",
+		message: "[devstack] manifest discovery returned undefined despite required: true"
+	});
+	return resolved;
+};
+const parseAndDecode = (raw, manifestPath) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (cause) {
+		throw new ManifestShapeError({
+			phase: "parse",
+			path: manifestPath,
+			message: `[devstack] manifest at ${manifestPath} is not valid JSON (truncation or hand-edit). RECOVERY: \`rm ${manifestPath} && devstack up\` to regenerate.`,
+			cause
+		});
+	}
+	let decoded;
+	try {
+		decoded = decodeEnvelope(parsed);
+	} catch (cause) {
+		throw new ManifestShapeError({
+			phase: "shape",
+			path: manifestPath,
+			message: `[devstack] manifest at ${manifestPath} does not match the manifest envelope schema (stale shape or hand-edit). RECOVERY: \`rm ${manifestPath} && devstack up\` to regenerate.`,
+			cause
+		});
+	}
+	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.`
+	});
+	return decoded;
+};
+/** Project the decoded envelope to a plain `StackContext`. */
+const project = (envelope, manifestPath) => {
+	const entries = [];
+	for (const raw of Object.values(envelope.endpoints)) entries.push({
+		name: raw.name,
+		url: raw.url,
+		displayUrl: raw.displayUrl,
+		wireProtocol: raw.wireProtocol,
+		pluginKey: raw.pluginKey,
+		endpointKey: raw.endpointKey
+	});
+	return {
+		identity: {
+			app: envelope.identity.app,
+			stack: envelope.identity.stack,
+			chain: envelope.identity.chain
+		},
+		manifestPath,
+		manifestVersion: envelope.manifestVersion,
+		endpoints: new EndpointRegistry(entries),
+		services: envelope.services,
+		extras: envelope.extras
+	};
+};
+/** Reconstruct the manifest envelope from the runtime projection.
+*  Integration adapters that preserve their older envelope-shaped
+*  surfaces use this instead of duplicating endpoint-registry
+*  projection logic. */
+const manifestEnvelopeFromStackContext = (ctx) => ({
+	identity: ctx.identity,
+	manifestVersion: ctx.manifestVersion,
+	services: ctx.services,
+	endpoints: Object.fromEntries(ctx.endpoints.all().map((e) => [e.endpointKey, {
+		name: e.name,
+		url: e.url,
+		displayUrl: e.displayUrl,
+		wireProtocol: e.wireProtocol,
+		pluginKey: e.pluginKey,
+		endpointKey: e.endpointKey
+	}])),
+	extras: ctx.extras
+});
+/**
+* Sync read + decode + project. Throws `ManifestDiscoveryError` (no
+* manifest located) or `ManifestShapeError` (manifest found but
+* malformed / wrong version).
+*
+* Used by:
+*   - Apps' generated `stack-handle.ts` at startup.
+*   - Playwright config-load (`baseURL`, `webServer.url`).
+*   - CLI surfaces that prefer sync-then-Effect.try over a native
+*     Effect read.
+*/
+const readStackContext = (opts = {}) => {
+	const manifestPath = resolveManifestPath(opts);
+	let raw;
+	try {
+		raw = readFileSync(manifestPath, "utf8");
+	} catch (cause) {
+		throw new ManifestShapeError({
+			phase: "parse",
+			path: manifestPath,
+			message: `[devstack] failed to read manifest at ${manifestPath}: ${String(cause)}`,
+			cause
+		});
+	}
+	return project(parseAndDecode(raw, manifestPath), manifestPath);
+};
+//#endregion
+export { CONSUMER_MANIFEST_VERSION, manifestEnvelopeFromStackContext, readStackContext };
+
+//# sourceMappingURL=read-stack-context.mjs.map

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

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

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

@@ -0,0 +1,53 @@
+import { EndpointRegistry } from "./endpoint-registry.mjs";
+
+//#region src/build-integrations/runtime/stack-context.d.ts
+/** Identity tuple — mirrors `ManifestEnvelope['identity']` from the
+ *  substrate. Re-stated here so consumer code doesn't reach into the
+ *  substrate package. */
+interface StackIdentity {
+  readonly app: string;
+  readonly stack: string;
+  readonly chain: string;
+}
+/** Flat endpoint entry exposed to consumers. Mirrors the substrate's
+ *  `EndpointEntry` but uses plain strings (no `Brand<>`) so callers
+ *  don't need to import the substrate's branded types. */
+interface ResolvedEndpoint {
+  readonly name: string;
+  readonly url: string;
+  readonly displayUrl: string | null;
+  readonly wireProtocol: string;
+  readonly pluginKey: string;
+  readonly endpointKey: string;
+}
+/** Read-only projection of the manifest. Consumers — Playwright
+ *  `baseURL` / `webServer`, codegen emitters that read their own
+ *  slice, the CLI's `status` command — key off the fields here.
+ *
+ *  Field shape is deliberately a SUPER-SET of "what the substrate
+ *  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. */
+  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
+   *  the file. */
+  readonly manifestPath: string;
+  /** Envelope schema version pinned by the substrate. Consumers
+   *  forwarding to per-version migration paths gate on this. */
+  readonly manifestVersion: number;
+  /** Typed endpoint registry — `byName(name)` returns the
+   *  `ResolvedEndpoint` (or `undefined`); `all()` lists them; group
+   *  helpers (`byPluginKey`, `byKind`) live on the registry too. */
+  readonly endpoints: EndpointRegistry;
+  /** Per-plugin opaque service slices — keyed by `pluginKey`. The
+   *  typed per-service shape lives in each plugin's Codegenable
+   *  output, not here. */
+  readonly services: Readonly<Record<string, unknown>>;
+  /** Per-plugin opaque extras — keyed by `pluginKey`. */
+  readonly extras: Readonly<Record<string, unknown>>;
+}
+//#endregion
+export { ResolvedEndpoint, StackContext, StackIdentity };
+//# sourceMappingURL=stack-context.d.mts.map