@mysten-incubation/devstack 0.0.1 → 0.1.1

package/dist/build-integrations/runtime/cold-start-url.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cold-start-url.mjs","names":[],"sources":["../../../src/build-integrations/runtime/cold-start-url.ts"],"sourcesContent":["// Cold-start URL — conventional-route fallback for callers that need\n// an endpoint URL BEFORE the supervisor has written the manifest.\n//\n// Playwright's config loader runs ahead of the supervisor (it's the\n// process that spawns `pnpm dev`, which boots the supervisor, which\n// then writes the manifest). For `webServer.url` / `use.baseURL` to\n// be resolvable at config-load time, the build-integration needs a\n// derivation that doesn't require the manifest on disk.\n//\n// The derivation:\n//\n//   <service>.<stack-prefix>.<app>.localhost:<port>\n//\n// where:\n//   - `<service>` and `<port>` come from the endpoint's Routable\n//     declaration (its `conventional` hint, populated by the router\n//     plugin).\n//   - `<app>` is the un-scoped app name (from cwd's `package.json` or\n//     an explicit override).\n//   - `<stack-prefix>` comes from an explicit stack, `DEVSTACK_STACK`,\n//     or the `main` default. Package metadata is not a stack selector\n//     for build integrations; it only supplies the app name.\n//   - `<stack-prefix>` is empty for the `main` stack and `.<stack>`\n//     otherwise. Matches the router's hostname-minting rule so\n//     conventional and post-manifest URLs converge.\n//\n// Architecture § invariants: \"conventional URL convergence\" — the\n// fallback this function returns MUST equal the URL the supervisor's\n// router publishes once the manifest exists. The shared invariant is\n// enforced by deriving both from the same Routable declaration.\n//\n// This module does NOT import any service-specific endpoint names.\n// The conventional-route table is supplied by the caller; the router\n// plugin populates it from `RoutableDecl[].upstream` + a hard-coded\n// conventional-port map. (Architecture: \"engine knows zero service\n// names\" — the table is plugin-emitted.)\n\nimport { basename } from 'node:path';\n\nimport { NoConventionalRouteError } from './errors.ts';\nimport { readAppName, resolveBuildIntegrationStack } from './discover.ts';\n\n/** One row of the conventional-route table. The supervisor's router\n *  plugin emits a `Map<endpointName, ConventionalRoute>` from its\n *  Routable contributions; cold-start URL resolution keys off it. */\nexport interface ConventionalRoute {\n\t/** `<service>` segment of the hostname — typically the\n\t *  routable's `dispatchId.role`. */\n\treadonly service: string;\n\t/** Traefik entrypoint port — the router's public-facing port for\n\t *  this endpoint kind. */\n\treadonly port: number;\n\t/** Wire protocol — `http` or `h2c`. Determines the URL scheme. */\n\treadonly wireProtocol: 'http' | 'h2c';\n}\n\nexport interface ColdStartUrlOptions {\n\t/** Conventional-route table to consult. Supplied by the caller\n\t *  (build integration), populated from the router plugin's\n\t *  `RoutableDecl` contributions. Empty by default — calls that\n\t *  don't pass a table will always throw, which is the right\n\t *  behavior for \"no router plugin = no fallback\". */\n\treadonly routes: ReadonlyMap<string, ConventionalRoute>;\n\t/** Stack name. Defaults through `$DEVSTACK_STACK`, then `'main'`. */\n\treadonly stack?: string;\n\t/** App name (un-scoped). Defaults to reading `package.json` at\n\t *  `cwd` (with the `@scope/` prefix stripped) and finally to\n\t *  `basename(cwd)`. Injectable so unit tests don't depend on\n\t *  filesystem state. */\n\treadonly app?: string;\n\t/** Starting directory for the app-name lookup. Defaults to\n\t *  `process.cwd()`. */\n\treadonly cwd?: string;\n\t/** Host suffix owned by the router. Default: `.localhost`. */\n\treadonly hostSuffix?: string;\n}\n\nexport interface ConventionalRouteHostInput {\n\treadonly service: string;\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly hostSuffix?: string;\n}\n\nexport interface ConventionalRouteUrlInput extends ConventionalRouteHostInput {\n\treadonly route: ConventionalRoute;\n\treadonly scheme?: 'http' | 'https';\n\treadonly trailingSlash?: boolean;\n}\n\nexport interface ConventionalRouteHint {\n\treadonly endpoint: string;\n\treadonly service: string;\n\treadonly wireProtocol?: 'http' | 'h2c';\n}\n\nexport const conventionalRouteHost = (input: ConventionalRouteHostInput): string => {\n\tconst hostSuffix = input.hostSuffix ?? '.localhost';\n\treturn input.stack === 'main'\n\t\t? `${input.service}.${input.app}${hostSuffix}`\n\t\t: `${input.service}.${input.stack}.${input.app}${hostSuffix}`;\n};\n\nexport const conventionalRouteUrl = (input: ConventionalRouteUrlInput): string => {\n\tconst scheme = input.scheme ?? 'http';\n\tconst host = conventionalRouteHost(input);\n\tconst url = `${scheme}://${host}:${input.route.port}`;\n\treturn input.trailingSlash === true ? `${url}/` : url;\n};\n\nexport const conventionalRoutesFromHints = (\n\thints: ReadonlyArray<ConventionalRouteHint>,\n\tport: number,\n): ReadonlyMap<string, ConventionalRoute> =>\n\tnew Map(\n\t\thints.map((hint): [string, ConventionalRoute] => [\n\t\t\thint.endpoint,\n\t\t\t{\n\t\t\t\tservice: hint.service,\n\t\t\t\tport,\n\t\t\t\twireProtocol: hint.wireProtocol ?? 'http',\n\t\t\t},\n\t\t]),\n\t);\n\n/**\n * Compute the conventional URL for `endpoint`. Throws\n * `NoConventionalRouteError` when the endpoint isn't in the supplied\n * `routes` table.\n *\n * Callers that prefer a `undefined`-on-miss surface should catch the\n * error or use `tryColdStartUrl` instead.\n */\nexport const coldStartUrl = (endpoint: string, opts: ColdStartUrlOptions): string => {\n\tconst route = opts.routes.get(endpoint);\n\tif (route === undefined) {\n\t\tconst supported = [...opts.routes.keys()].sort();\n\t\tthrow new NoConventionalRouteError({\n\t\t\tendpoint,\n\t\t\tsupported,\n\t\t\tmessage:\n\t\t\t\t`[devstack] endpoint ${JSON.stringify(endpoint)} has no conventional URL fallback. ` +\n\t\t\t\t`Supported endpoints: ${supported.length === 0 ? '(none)' : supported.join(', ')}. ` +\n\t\t\t\t`Check the endpoint name or write the manifest first via \\`devstack up\\`.`,\n\t\t});\n\t}\n\tconst cwd = opts.cwd ?? process.cwd();\n\tconst stack = resolveBuildIntegrationStack(opts.stack);\n\tconst app = opts.app ?? readAppName(cwd) ?? basename(cwd);\n\treturn conventionalRouteUrl({\n\t\troute,\n\t\tservice: route.service,\n\t\tapp,\n\t\tstack,\n\t\t...(opts.hostSuffix !== undefined ? { hostSuffix: opts.hostSuffix } : {}),\n\t\tscheme: route.wireProtocol === 'h2c' ? 'http' : 'http',\n\t});\n};\n\n/** `undefined`-on-miss variant. */\nexport const tryColdStartUrl = (\n\tendpoint: string,\n\topts: ColdStartUrlOptions,\n): string | undefined => {\n\tif (!opts.routes.has(endpoint)) return undefined;\n\treturn coldStartUrl(endpoint, opts);\n};\n"],"mappings":";;;;AAgGA,MAAa,yBAAyB,UAA8C;CACnF,MAAM,aAAa,MAAM,cAAc;AACvC,QAAO,MAAM,UAAU,SACpB,GAAG,MAAM,QAAQ,GAAG,MAAM,MAAM,eAChC,GAAG,MAAM,QAAQ,GAAG,MAAM,MAAM,GAAG,MAAM,MAAM;;AAGnD,MAAa,wBAAwB,UAA6C;CAGjF,MAAM,MAAM,GAFG,MAAM,UAAU,OAET,KADT,sBAAsB,MACJ,CAAC,GAAG,MAAM,MAAM;AAC/C,QAAO,MAAM,kBAAkB,OAAO,GAAG,IAAI,KAAK;;AAGnD,MAAa,+BACZ,OACA,SAEA,IAAI,IACH,MAAM,KAAK,SAAsC,CAChD,KAAK,UACL;CACC,SAAS,KAAK;CACd;CACA,cAAc,KAAK,gBAAgB;CACnC,CACD,CAAC,CACF;;;;;;;;;AAUF,MAAa,gBAAgB,UAAkB,SAAsC;CACpF,MAAM,QAAQ,KAAK,OAAO,IAAI,SAAS;AACvC,KAAI,UAAU,KAAA,GAAW;EACxB,MAAM,YAAY,CAAC,GAAG,KAAK,OAAO,MAAM,CAAC,CAAC,MAAM;AAChD,QAAM,IAAI,yBAAyB;GAClC;GACA;GACA,SACC,uBAAuB,KAAK,UAAU,SAAS,CAAC,0DACxB,UAAU,WAAW,IAAI,WAAW,UAAU,KAAK,KAAK,CAAC;GAElF,CAAC;;CAEH,MAAM,MAAM,KAAK,OAAO,QAAQ,KAAK;CACrC,MAAM,QAAQ,6BAA6B,KAAK,MAAM;CACtD,MAAM,MAAM,KAAK,OAAO,YAAY,IAAI,IAAI,SAAS,IAAI;AACzD,QAAO,qBAAqB;EAC3B;EACA,SAAS,MAAM;EACf;EACA;EACA,GAAI,KAAK,eAAe,KAAA,IAAY,EAAE,YAAY,KAAK,YAAY,GAAG,EAAE;EACxE,QAAQ,MAAM,iBAAiB,QAAQ,SAAS;EAChD,CAAC;;;AAIH,MAAa,mBACZ,UACA,SACwB;AACxB,KAAI,CAAC,KAAK,OAAO,IAAI,SAAS,CAAE,QAAO,KAAA;AACvC,QAAO,aAAa,UAAU,KAAK"}
+{"version":3,"file":"cold-start-url.mjs","names":[],"sources":["../../../src/build-integrations/runtime/cold-start-url.ts"],"sourcesContent":["// Cold-start URL — conventional-route fallback for callers that need\n// an endpoint URL BEFORE the supervisor has written the manifest.\n//\n// Playwright's config loader runs ahead of the supervisor (it's the\n// process that spawns `pnpm dev`, which boots the supervisor, which\n// then writes the manifest). For `webServer.url` / `use.baseURL` to\n// be resolvable at config-load time, the build-integration needs a\n// derivation that doesn't require the manifest on disk.\n//\n// The derivation:\n//\n//   <service>.<stack-prefix>.<app>.localhost:<port>\n//\n// where:\n//   - `<service>` and `<port>` come from the endpoint's Routable\n//     declaration (its `conventional` hint, populated by the router\n//     plugin).\n//   - `<app>` is the un-scoped app name (from cwd's `package.json` or\n//     an explicit override).\n//   - `<stack-prefix>` comes from an explicit stack, `DEVSTACK_STACK`,\n//     or the `main` default. Package metadata is not a stack selector\n//     for build integrations; it only supplies the app name.\n//   - `<stack-prefix>` is empty for the `main` stack and `.<stack>`\n//     otherwise. Matches the router's hostname-minting rule so\n//     conventional and post-manifest URLs converge.\n//\n// Architecture § invariants: \"conventional URL convergence\" — the\n// fallback this function returns MUST equal the URL the supervisor's\n// router publishes once the manifest exists. The shared invariant is\n// enforced by deriving both from the same Routable declaration.\n//\n// This module does NOT import any service-specific endpoint names.\n// The conventional-route table is supplied by the caller; the router\n// plugin populates it from `RoutableDecl[].upstream` + a hard-coded\n// conventional-port map. (Architecture: \"engine knows zero service\n// names\" — the table is plugin-emitted.)\n\nimport { basename } from 'node:path';\n\nimport { NoConventionalRouteError } from './errors.ts';\nimport { readAppName, resolveBuildIntegrationStack } from './discover.ts';\n\n/** One row of the conventional-route table. The supervisor's router\n *  plugin emits a `Map<endpointName, ConventionalRoute>` from its\n *  Routable contributions; cold-start URL resolution keys off it. */\nexport interface ConventionalRoute {\n\t/** `<service>` segment of the hostname — typically the\n\t *  routable's `dispatchId.role`. */\n\treadonly service: string;\n\t/** Traefik entrypoint port — the router's public-facing port for\n\t *  this endpoint kind. */\n\treadonly port: number;\n\t/** Wire protocol — `http` or `h2c`. Determines the URL scheme. */\n\treadonly wireProtocol: 'http' | 'h2c';\n}\n\nexport interface ColdStartUrlOptions {\n\t/** Conventional-route table to consult. Supplied by the caller\n\t *  (build integration), populated from the router plugin's\n\t *  `RoutableDecl` contributions. Empty by default — calls that\n\t *  don't pass a table will always throw, which is the right\n\t *  behavior for \"no router plugin = no fallback\". */\n\treadonly routes: ReadonlyMap<string, ConventionalRoute>;\n\t/** Stack name. Defaults through `$DEVSTACK_STACK`, then `'main'`. */\n\treadonly stack?: string;\n\t/** App name (un-scoped). Defaults to reading `package.json` at\n\t *  `cwd` (with the `@scope/` prefix stripped) and finally to\n\t *  `basename(cwd)`. Injectable so unit tests don't depend on\n\t *  filesystem state. */\n\treadonly app?: string;\n\t/** Starting directory for the app-name lookup. Defaults to\n\t *  `process.cwd()`. */\n\treadonly cwd?: string;\n\t/** Host suffix owned by the router. Default: `.localhost`. */\n\treadonly hostSuffix?: string;\n\t/** Env bag consulted before falling back to `process.env`. Lets\n\t *  callers (build integrations under test) inject a hermetic env\n\t *  so `DEVSTACK_STACK` / `DEVSTACK_APP` are read from the bag\n\t *  rather than leaking through the ambient environment. */\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n}\n\nexport interface ConventionalRouteHostInput {\n\treadonly service: string;\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly hostSuffix?: string;\n}\n\nexport interface ConventionalRouteUrlInput extends ConventionalRouteHostInput {\n\treadonly route: ConventionalRoute;\n\treadonly scheme?: 'http' | 'https';\n\treadonly trailingSlash?: boolean;\n}\n\nexport interface ConventionalRouteHint {\n\treadonly endpoint: string;\n\treadonly service: string;\n\treadonly wireProtocol?: 'http' | 'h2c';\n}\n\nexport const conventionalRouteHost = (input: ConventionalRouteHostInput): string => {\n\tconst hostSuffix = input.hostSuffix ?? '.localhost';\n\treturn input.stack === 'main'\n\t\t? `${input.service}.${input.app}${hostSuffix}`\n\t\t: `${input.service}.${input.stack}.${input.app}${hostSuffix}`;\n};\n\nexport const conventionalRouteUrl = (input: ConventionalRouteUrlInput): string => {\n\tconst scheme = input.scheme ?? 'http';\n\tconst host = conventionalRouteHost(input);\n\tconst url = `${scheme}://${host}:${input.route.port}`;\n\treturn input.trailingSlash === true ? `${url}/` : url;\n};\n\nexport const conventionalRoutesFromHints = (\n\thints: ReadonlyArray<ConventionalRouteHint>,\n\tport: number,\n): ReadonlyMap<string, ConventionalRoute> =>\n\tnew Map(\n\t\thints.map((hint): [string, ConventionalRoute] => [\n\t\t\thint.endpoint,\n\t\t\t{\n\t\t\t\tservice: hint.service,\n\t\t\t\tport,\n\t\t\t\twireProtocol: hint.wireProtocol ?? 'http',\n\t\t\t},\n\t\t]),\n\t);\n\n/**\n * Compute the conventional URL for `endpoint`. Throws\n * `NoConventionalRouteError` when the endpoint isn't in the supplied\n * `routes` table.\n *\n * Callers that prefer a `undefined`-on-miss surface should catch the\n * error or use `tryColdStartUrl` instead.\n */\nexport const coldStartUrl = (endpoint: string, opts: ColdStartUrlOptions): string => {\n\tconst route = opts.routes.get(endpoint);\n\tif (route === undefined) {\n\t\tconst supported = [...opts.routes.keys()].sort();\n\t\tthrow new NoConventionalRouteError({\n\t\t\tendpoint,\n\t\t\tsupported,\n\t\t\tmessage:\n\t\t\t\t`[devstack] endpoint ${JSON.stringify(endpoint)} has no conventional URL fallback. ` +\n\t\t\t\t`Supported endpoints: ${supported.length === 0 ? '(none)' : supported.join(', ')}. ` +\n\t\t\t\t`Check the endpoint name or write the manifest first via \\`devstack up\\`.`,\n\t\t});\n\t}\n\tconst cwd = opts.cwd ?? process.cwd();\n\tconst env = opts.env ?? (process.env as Readonly<Record<string, string | undefined>>);\n\tconst stack = resolveBuildIntegrationStack(opts.stack, env);\n\t// `DEVSTACK_APP` is the caller-injectable app name; `readAppName(cwd)` is\n\t// the package.json walk-up. The env bag wins so test fixtures don't leak\n\t// the host's package metadata into the cold-start URL.\n\tconst app = opts.app ?? env.DEVSTACK_APP ?? readAppName(cwd) ?? basename(cwd);\n\treturn conventionalRouteUrl({\n\t\troute,\n\t\tservice: route.service,\n\t\tapp,\n\t\tstack,\n\t\t...(opts.hostSuffix !== undefined ? { hostSuffix: opts.hostSuffix } : {}),\n\t\t// h2c shares port 80 with HTTP/1 via Traefik; both wire\n\t\t// protocols expose `http://` URLs at the entrypoint.\n\t\tscheme: 'http',\n\t});\n};\n\n/** `undefined`-on-miss variant. */\nexport const tryColdStartUrl = (\n\tendpoint: string,\n\topts: ColdStartUrlOptions,\n): string | undefined => {\n\tif (!opts.routes.has(endpoint)) return undefined;\n\treturn coldStartUrl(endpoint, opts);\n};\n"],"mappings":";;;;AAqGA,MAAa,yBAAyB,UAA8C;CACnF,MAAM,aAAa,MAAM,cAAc;AACvC,QAAO,MAAM,UAAU,SACpB,GAAG,MAAM,QAAQ,GAAG,MAAM,MAAM,eAChC,GAAG,MAAM,QAAQ,GAAG,MAAM,MAAM,GAAG,MAAM,MAAM;;AAGnD,MAAa,wBAAwB,UAA6C;CAGjF,MAAM,MAAM,GAFG,MAAM,UAAU,OAET,KADT,sBAAsB,MACJ,CAAC,GAAG,MAAM,MAAM;AAC/C,QAAO,MAAM,kBAAkB,OAAO,GAAG,IAAI,KAAK;;AAGnD,MAAa,+BACZ,OACA,SAEA,IAAI,IACH,MAAM,KAAK,SAAsC,CAChD,KAAK,UACL;CACC,SAAS,KAAK;CACd;CACA,cAAc,KAAK,gBAAgB;CACnC,CACD,CAAC,CACF;;;;;;;;;AAUF,MAAa,gBAAgB,UAAkB,SAAsC;CACpF,MAAM,QAAQ,KAAK,OAAO,IAAI,SAAS;AACvC,KAAI,UAAU,KAAA,GAAW;EACxB,MAAM,YAAY,CAAC,GAAG,KAAK,OAAO,MAAM,CAAC,CAAC,MAAM;AAChD,QAAM,IAAI,yBAAyB;GAClC;GACA;GACA,SACC,uBAAuB,KAAK,UAAU,SAAS,CAAC,0DACxB,UAAU,WAAW,IAAI,WAAW,UAAU,KAAK,KAAK,CAAC;GAElF,CAAC;;CAEH,MAAM,MAAM,KAAK,OAAO,QAAQ,KAAK;CACrC,MAAM,MAAM,KAAK,OAAQ,QAAQ;CACjC,MAAM,QAAQ,6BAA6B,KAAK,OAAO,IAAI;CAI3D,MAAM,MAAM,KAAK,OAAO,IAAI,gBAAgB,YAAY,IAAI,IAAI,SAAS,IAAI;AAC7E,QAAO,qBAAqB;EAC3B;EACA,SAAS,MAAM;EACf;EACA;EACA,GAAI,KAAK,eAAe,KAAA,IAAY,EAAE,YAAY,KAAK,YAAY,GAAG,EAAE;EAGxE,QAAQ;EACR,CAAC;;;AAIH,MAAa,mBACZ,UACA,SACwB;AACxB,KAAI,CAAC,KAAK,OAAO,IAAI,SAAS,CAAE,QAAO,KAAA;AACvC,QAAO,aAAa,UAAU,KAAK"}

package/dist/build-integrations/runtime/conventional-routes.d.mts

@@ -0,0 +1,51 @@
+import { ConventionalRoute, ConventionalRouteHint } from "./cold-start-url.mjs";
+
+//#region src/build-integrations/runtime/conventional-routes.d.ts
+/**
+ * The Traefik entrypoint port the supervisor's router maps every
+ * conventional endpoint to. All built-in routes share this single port
+ * because Traefik dispatches by Host header, not by port. If a future
+ * plugin requires a distinct entrypoint port it would extend
+ * `BUILT_IN_CONVENTIONAL_HINTS` AND extend the router profile to add
+ * the entrypoint; until then, one port covers every built-in.
+ */
+declare const DEFAULT_ROUTER_ENTRYPOINT_PORT: 5175;
+/**
+ * Endpoint-name aliases the conventional-route resolver folds before
+ * looking up a row. Lets in-spec helpers reach `endpoint('app')` or
+ * `endpoint('wallet')` without knowing the router's canonical
+ * spelling (`'dev'` / `'wallet-app'`). Aliases are bidirectional in
+ * intent — the table key is the alias users type; the value is the
+ * service segment routed in the manifest.
+ *
+ * The wallet entry sources both sides from the name-blind contract
+ * (via the L5 bridge in `wallet-paths.ts`) so there is exactly one
+ * source of truth for the alias/canonical pairing — see
+ * `WALLET_ENDPOINT_KEY` in `contracts/wallet-protocol.ts`.
+ */
+declare const BUILT_IN_ENDPOINT_ALIASES: {
+  readonly app: "dev";
+  readonly wallet: "wallet-app";
+};
+/**
+ * Conventional endpoint→service hints for every built-in plugin that
+ * publishes a Routable. Build integrations consume this through
+ * `builtInConventionalRoutes()` rather than each carrying their own
+ * copy. The substrate stays open: callers may extend by passing extra
+ * hints to `coldStartUrl` directly.
+ */
+declare const BUILT_IN_CONVENTIONAL_HINTS: ReadonlyArray<ConventionalRouteHint>;
+/**
+ * Resolve the built-in conventional route table. `port` overrides the
+ * default entrypoint port (set by env / explicit caller option). The
+ * resulting `Map` is the shape `coldStartUrl({ routes })` consumes.
+ */
+declare const builtInConventionalRoutes: (port?: number) => ReadonlyMap<string, ConventionalRoute>;
+/**
+ * Look up the alias-resolved endpoint key for a user-typed name.
+ * Returns the input unchanged when no alias is registered.
+ */
+declare const resolveBuiltInEndpointAlias: (endpointNameOrAlias: string) => string;
+//#endregion
+export { BUILT_IN_CONVENTIONAL_HINTS, BUILT_IN_ENDPOINT_ALIASES, DEFAULT_ROUTER_ENTRYPOINT_PORT, builtInConventionalRoutes, resolveBuiltInEndpointAlias };
+//# sourceMappingURL=conventional-routes.d.mts.map

package/dist/build-integrations/runtime/conventional-routes.mjs

@@ -0,0 +1,92 @@
+import { WALLET_ENDPOINT_KEY, WALLET_ENDPOINT_NAME } from "../../contracts/wallet-protocol.mjs";
+import { conventionalRoutesFromHints } from "./cold-start-url.mjs";
+import "./wallet-paths.mjs";
+//#region src/build-integrations/runtime/conventional-routes.ts
+/**
+* The Traefik entrypoint port the supervisor's router maps every
+* conventional endpoint to. All built-in routes share this single port
+* because Traefik dispatches by Host header, not by port. If a future
+* plugin requires a distinct entrypoint port it would extend
+* `BUILT_IN_CONVENTIONAL_HINTS` AND extend the router profile to add
+* the entrypoint; until then, one port covers every built-in.
+*/
+const DEFAULT_ROUTER_ENTRYPOINT_PORT = 5175;
+/**
+* Endpoint-name aliases the conventional-route resolver folds before
+* looking up a row. Lets in-spec helpers reach `endpoint('app')` or
+* `endpoint('wallet')` without knowing the router's canonical
+* spelling (`'dev'` / `'wallet-app'`). Aliases are bidirectional in
+* intent — the table key is the alias users type; the value is the
+* service segment routed in the manifest.
+*
+* The wallet entry sources both sides from the name-blind contract
+* (via the L5 bridge in `wallet-paths.ts`) so there is exactly one
+* source of truth for the alias/canonical pairing — see
+* `WALLET_ENDPOINT_KEY` in `contracts/wallet-protocol.ts`.
+*/
+const BUILT_IN_ENDPOINT_ALIASES = {
+	app: "dev",
+	[WALLET_ENDPOINT_KEY]: WALLET_ENDPOINT_NAME
+};
+/**
+* Conventional endpoint→service hints for every built-in plugin that
+* publishes a Routable. Build integrations consume this through
+* `builtInConventionalRoutes()` rather than each carrying their own
+* copy. The substrate stays open: callers may extend by passing extra
+* hints to `coldStartUrl` directly.
+*/
+const BUILT_IN_CONVENTIONAL_HINTS = [
+	{
+		endpoint: "app",
+		service: "dev"
+	},
+	{
+		endpoint: "dev",
+		service: "dev"
+	},
+	{
+		endpoint: "sui-rpc",
+		service: "sui-rpc"
+	},
+	{
+		endpoint: "sui-faucet",
+		service: "sui-faucet"
+	},
+	{
+		endpoint: "walrus-aggregator",
+		service: "walrus-aggregator"
+	},
+	{
+		endpoint: "walrus-publisher",
+		service: "walrus-publisher"
+	},
+	{
+		endpoint: "seal",
+		service: "seal"
+	},
+	{
+		endpoint: WALLET_ENDPOINT_KEY,
+		service: "api"
+	},
+	{
+		endpoint: WALLET_ENDPOINT_NAME,
+		service: "api"
+	}
+];
+/**
+* Resolve the built-in conventional route table. `port` overrides the
+* default entrypoint port (set by env / explicit caller option). The
+* resulting `Map` is the shape `coldStartUrl({ routes })` consumes.
+*/
+const builtInConventionalRoutes = (port = DEFAULT_ROUTER_ENTRYPOINT_PORT) => conventionalRoutesFromHints(BUILT_IN_CONVENTIONAL_HINTS, port);
+/**
+* Look up the alias-resolved endpoint key for a user-typed name.
+* Returns the input unchanged when no alias is registered.
+*/
+const resolveBuiltInEndpointAlias = (endpointNameOrAlias) => {
+	return BUILT_IN_ENDPOINT_ALIASES[endpointNameOrAlias] ?? endpointNameOrAlias;
+};
+//#endregion
+export { BUILT_IN_CONVENTIONAL_HINTS, BUILT_IN_ENDPOINT_ALIASES, DEFAULT_ROUTER_ENTRYPOINT_PORT, builtInConventionalRoutes, resolveBuiltInEndpointAlias };
+
+//# sourceMappingURL=conventional-routes.mjs.map

package/dist/build-integrations/runtime/conventional-routes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventional-routes.mjs","names":["aliases"],"sources":["../../../src/build-integrations/runtime/conventional-routes.ts"],"sourcesContent":["// Conventional-routes table — substrate-owned defaults for the\n// \"config-load before manifest\" cold-start path.\n//\n// Build integrations (Playwright, vitest, …) that need an endpoint URL\n// BEFORE the supervisor has written the manifest go through\n// `coldStartUrl(endpoint, { routes, ... })`. The route table itself is\n// a parameter — `runtime/coldStartUrl` deliberately stays\n// service-name-blind. THIS module supplies the conventional table the\n// router plugin would populate at supervise-time, so build integrations\n// don't each carry their own copy.\n//\n// Add a new built-in service: add one entry here AND ship a Routable\n// plugin that publishes the matching `<service>` hostname at the same\n// port. Architecture invariant \"conventional URL convergence\" — the\n// fallback returned by `coldStartUrl({ routes })` MUST equal the URL\n// the router publishes once the manifest exists.\n//\n// This is the L5 cold-start mirror of the router plugin's runtime\n// table. The L5 surface (Playwright / vitest) consults it once; the\n// runtime table wins as soon as the manifest is on disk.\n\nimport {\n\tconventionalRoutesFromHints,\n\ttype ConventionalRoute,\n\ttype ConventionalRouteHint,\n} from './cold-start-url.ts';\nimport { WALLET_ENDPOINT_KEY, WALLET_ENDPOINT_NAME } from './wallet-paths.ts';\n\n/**\n * The Traefik entrypoint port the supervisor's router maps every\n * conventional endpoint to. All built-in routes share this single port\n * because Traefik dispatches by Host header, not by port. If a future\n * plugin requires a distinct entrypoint port it would extend\n * `BUILT_IN_CONVENTIONAL_HINTS` AND extend the router profile to add\n * the entrypoint; until then, one port covers every built-in.\n */\nexport const DEFAULT_ROUTER_ENTRYPOINT_PORT = 5175 as const;\n\n/**\n * Endpoint-name aliases the conventional-route resolver folds before\n * looking up a row. Lets in-spec helpers reach `endpoint('app')` or\n * `endpoint('wallet')` without knowing the router's canonical\n * spelling (`'dev'` / `'wallet-app'`). Aliases are bidirectional in\n * intent — the table key is the alias users type; the value is the\n * service segment routed in the manifest.\n *\n * The wallet entry sources both sides from the name-blind contract\n * (via the L5 bridge in `wallet-paths.ts`) so there is exactly one\n * source of truth for the alias/canonical pairing — see\n * `WALLET_ENDPOINT_KEY` in `contracts/wallet-protocol.ts`.\n */\nexport const BUILT_IN_ENDPOINT_ALIASES = {\n\tapp: 'dev',\n\t[WALLET_ENDPOINT_KEY]: WALLET_ENDPOINT_NAME,\n} as const;\n\n/**\n * Conventional endpoint→service hints for every built-in plugin that\n * publishes a Routable. Build integrations consume this through\n * `builtInConventionalRoutes()` rather than each carrying their own\n * copy. The substrate stays open: callers may extend by passing extra\n * hints to `coldStartUrl` directly.\n */\nexport const BUILT_IN_CONVENTIONAL_HINTS: ReadonlyArray<ConventionalRouteHint> = [\n\t{ endpoint: 'app', service: 'dev' },\n\t{ endpoint: 'dev', service: 'dev' },\n\t{ endpoint: 'sui-rpc', service: 'sui-rpc' },\n\t{ endpoint: 'sui-faucet', service: 'sui-faucet' },\n\t{ endpoint: 'walrus-aggregator', service: 'walrus-aggregator' },\n\t{ endpoint: 'walrus-publisher', service: 'walrus-publisher' },\n\t{ endpoint: 'seal', service: 'seal' },\n\t{ endpoint: WALLET_ENDPOINT_KEY, service: 'api' },\n\t{ endpoint: WALLET_ENDPOINT_NAME, service: 'api' },\n];\n\n/**\n * Resolve the built-in conventional route table. `port` overrides the\n * default entrypoint port (set by env / explicit caller option). The\n * resulting `Map` is the shape `coldStartUrl({ routes })` consumes.\n */\nexport const builtInConventionalRoutes = (\n\tport: number = DEFAULT_ROUTER_ENTRYPOINT_PORT,\n): ReadonlyMap<string, ConventionalRoute> =>\n\tconventionalRoutesFromHints(BUILT_IN_CONVENTIONAL_HINTS, port);\n\n/**\n * Look up the alias-resolved endpoint key for a user-typed name.\n * Returns the input unchanged when no alias is registered.\n */\nexport const resolveBuiltInEndpointAlias = (endpointNameOrAlias: string): string => {\n\tconst aliases: Readonly<Record<string, string>> = BUILT_IN_ENDPOINT_ALIASES;\n\treturn aliases[endpointNameOrAlias] ?? endpointNameOrAlias;\n};\n"],"mappings":";;;;;;;;;;;;AAoCA,MAAa,iCAAiC;;;;;;;;;;;;;;AAe9C,MAAa,4BAA4B;CACxC,KAAK;EACJ,sBAAsB;CACvB;;;;;;;;AASD,MAAa,8BAAoE;CAChF;EAAE,UAAU;EAAO,SAAS;EAAO;CACnC;EAAE,UAAU;EAAO,SAAS;EAAO;CACnC;EAAE,UAAU;EAAW,SAAS;EAAW;CAC3C;EAAE,UAAU;EAAc,SAAS;EAAc;CACjD;EAAE,UAAU;EAAqB,SAAS;EAAqB;CAC/D;EAAE,UAAU;EAAoB,SAAS;EAAoB;CAC7D;EAAE,UAAU;EAAQ,SAAS;EAAQ;CACrC;EAAE,UAAU;EAAqB,SAAS;EAAO;CACjD;EAAE,UAAU;EAAsB,SAAS;EAAO;CAClD;;;;;;AAOD,MAAa,6BACZ,OAAe,mCAEf,4BAA4B,6BAA6B,KAAK;;;;;AAM/D,MAAa,+BAA+B,wBAAwC;AAEnF,QAAOA,0BAAQ,wBAAwB"}

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

@@ -1,7 +1,8 @@
 //#region src/build-integrations/runtime/discover.d.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. */
+ *  doesn't reach into the substrate package. Re-export of the
+ *  shared-resolver default so this module's public surface is stable. */
 declare const DEFAULT_STATE_DIR = ".devstack";
 /** Default stack name when neither `opts.stack` nor `$DEVSTACK_STACK`
  *  yields a useful value. */
@@ -16,9 +17,10 @@ interface DiscoverManifestPathOptions {
   readonly cwd?: string;
   /** Stack name. Defaults through `$DEVSTACK_STACK`, then `'main'`. */
   readonly stack?: string;
-  /** State-dir name. Defaults to `$DEVSTACK_STATE_DIR ?? '.devstack'`.
-   *  Absolute paths are honored — the walk-up degenerates into a
-   *  single existence check in that case. */
+  /** State-dir name. Defaults through `$DEVSTACK_RUNTIME_ROOT`, then
+   *  the legacy `$DEVSTACK_STATE_DIR`, then `'.devstack'` (see
+   *  `resolveDiscoveryEnv`). Absolute paths are honored — the walk-up
+   *  degenerates into a single existence check in that case. */
   readonly stateDir?: string;
   /** Env bag for the env-precedence step. Defaults to `process.env`.
    *  Tests pass a fixture (often `{}`) to suppress leaks from the
@@ -29,25 +31,6 @@ interface DiscoverManifestPathOptions {
    *  "no manifest" as cold-start branch cleanly). */
   readonly required?: boolean;
 }
-interface BuildIntegrationIdentity {
-  readonly app: string | undefined;
-  readonly stack: string;
-  readonly stateDir: string;
-  readonly manifestPath: string;
-}
-interface DiscoverBuildIntegrationIdentityOptions {
-  /** Resolution cwd. Defaults to `process.cwd()`. */
-  readonly cwd?: string;
-  /** Explicit app name. Overrides env + package.json walk-up. */
-  readonly app?: string;
-  /** Explicit stack name. Overrides `DEVSTACK_STACK`; otherwise
-   *  defaults to `main`. */
-  readonly stack?: string;
-  /** Explicit state-dir name. Overrides `DEVSTACK_STATE_DIR`. */
-  readonly stateDir?: string;
-  /** Env bag for tests and config loaders. Defaults to `process.env`. */
-  readonly env?: Readonly<Record<string, string | undefined>>;
-}
 /** 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. */
@@ -56,12 +39,7 @@ declare const readAppName: (dir: string) => string | undefined;
  *  its un-scoped `name` field. Returns `undefined` if no package.json
  *  is reachable. Bounded to 32 levels — defense against pathological
  *  symlink loops. */
-declare const readAppNameWalkup: (cwd: string) => string | undefined;
-/** 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. */
-declare const discoverBuildIntegrationIdentity: (options?: DiscoverBuildIntegrationIdentityOptions) => BuildIntegrationIdentity;
+declare const readAppNameWalkup: (cwd?: string) => string | undefined;
 /**
  * Locate an existing devstack manifest on disk. Sync — Playwright's
  * config loader and apps' startup paths both depend on this being
@@ -73,6 +51,36 @@ declare const discoverBuildIntegrationIdentity: (options?: DiscoverBuildIntegrat
  * on miss instead.
  */
 declare function discoverManifestPath(opts?: DiscoverManifestPathOptions): string | undefined;
+interface DiscoverSingleStackManifestPathOptions {
+  /** Starting directory for the walk-up. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /** State-dir name. Defaults to `.devstack`. Absolute paths are
+   *  honored — the walk-up degenerates into a single existence check
+   *  in that case. */
+  readonly stateDir?: string;
+}
+/**
+ * Walks up from `cwd` looking for a `<stateDir>` that contains EXACTLY
+ * ONE stack subdirectory; returns that stack's `manifest.json` path.
+ * Returns `null` when zero or >1 stacks are found at every ancestor.
+ *
+ * Used by integrations that need a no-explicit-stack auto-detect mode
+ * (Playwright preset; future Vitest cold-start). The contract:
+ *
+ *   - At each ancestor, list `<ancestor>/<stateDir>/stacks/*`.
+ *   - If exactly one stack dir with a `manifest.json` exists at that
+ *     level: return its path. Stop walking.
+ *   - If >1 stacks exist at that level: ambiguous → return `null` (do
+ *     NOT continue walking past an ambiguous level).
+ *   - If 0 stacks exist at that level: continue walking up.
+ *   - If the filesystem root is reached without resolution: return
+ *     `null`.
+ *
+ * Pure — does not consult env vars. Callers do their own gating (the
+ * Playwright preset only invokes this when no explicit stack was
+ * supplied via option or env).
+ */
+declare const discoverSingleStackManifestPath: (options?: DiscoverSingleStackManifestPathOptions) => string | null;
 //#endregion
-export { BuildIntegrationIdentity, DEFAULT_STACK, DEFAULT_STATE_DIR, DiscoverBuildIntegrationIdentityOptions, DiscoverManifestPathOptions, discoverBuildIntegrationIdentity, discoverManifestPath, readAppName, readAppNameWalkup };
+export { DEFAULT_STACK, DEFAULT_STATE_DIR, DiscoverManifestPathOptions, DiscoverSingleStackManifestPathOptions, discoverManifestPath, discoverSingleStackManifestPath, readAppName, readAppNameWalkup };
 //# sourceMappingURL=discover.d.mts.map

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

@@ -1,70 +1,27 @@
-import { DEFAULT_STACK_NAME } from "../../api/inference-network.mjs";
+import { DEFAULT_DISCOVERY_STACK, DEFAULT_DISCOVERY_STATE_DIR, resolveDiscoveryEnv } from "./resolve-discovery-env.mjs";
+import { inferPackageNameFromCwd, readPackageName } from "../../api/inference-network.mjs";
 import { ManifestDiscoveryError } from "./errors.mjs";
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, isAbsolute, 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";
+*  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. */
-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;
-};
+const DEFAULT_STACK = DEFAULT_DISCOVERY_STACK;
+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`
 *  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;
-	}
-};
+const readAppName = readPackageName;
 /** 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
-	};
-};
+const readAppNameWalkup = inferPackageNameFromCwd;
 /**
 * Locate an existing devstack manifest on disk. Sync — Playwright's
 * config loader and apps' startup paths both depend on this being
@@ -81,36 +38,39 @@ function discoverManifestPath(opts = {}) {
 	if (envOverride !== void 0 && envOverride !== "") {
 		const resolved = resolve(envOverride);
 		if (existsSync(resolved)) return resolved;
-		if (opts.required === true) throw new ManifestDiscoveryError({
+		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({
+		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;
-	}
+	const { stack, stateDir } = resolveDiscoveryEnv(env, {
+		...opts.stack !== void 0 ? { stack: opts.stack } : {},
+		...opts.stateDir !== void 0 ? { stateDir: opts.stateDir } : {}
+	});
+	const candidates = isAbsolute(stateDir) ? [join(stateDir, "stacks", stack, "manifest.json")] : (() => {
+		const acc = [];
+		let dir = resolve(startDir);
+		while (true) {
+			acc.push(join(dir, stateDir, "stacks", stack, "manifest.json"));
+			const parent = dirname(dir);
+			if (parent === dir) return acc;
+			dir = parent;
+		}
+	})();
+	for (const candidate of candidates) if (existsSync(candidate)) return candidate;
 	if (opts.required === true) {
-		const expected = resolve(startDir, stateDir, "stacks", stack, "manifest.json");
+		const expected = isAbsolute(stateDir) ? join(stateDir, "stacks", stack, "manifest.json") : resolve(startDir, stateDir, "stacks", stack, "manifest.json");
 		throw new ManifestDiscoveryError({
 			phase: "walk-up",
 			path: expected,
@@ -118,7 +78,50 @@ function discoverManifestPath(opts = {}) {
 		});
 	}
 }
+/**
+* Walks up from `cwd` looking for a `<stateDir>` that contains EXACTLY
+* ONE stack subdirectory; returns that stack's `manifest.json` path.
+* Returns `null` when zero or >1 stacks are found at every ancestor.
+*
+* Used by integrations that need a no-explicit-stack auto-detect mode
+* (Playwright preset; future Vitest cold-start). The contract:
+*
+*   - At each ancestor, list `<ancestor>/<stateDir>/stacks/*`.
+*   - If exactly one stack dir with a `manifest.json` exists at that
+*     level: return its path. Stop walking.
+*   - If >1 stacks exist at that level: ambiguous → return `null` (do
+*     NOT continue walking past an ambiguous level).
+*   - If 0 stacks exist at that level: continue walking up.
+*   - If the filesystem root is reached without resolution: return
+*     `null`.
+*
+* Pure — does not consult env vars. Callers do their own gating (the
+* Playwright preset only invokes this when no explicit stack was
+* supplied via option or env).
+*/
+const discoverSingleStackManifestPath = (options = {}) => {
+	const cwd = resolve(options.cwd ?? process.cwd());
+	const stateDirName = options.stateDir ?? DEFAULT_STATE_DIR;
+	const startDirs = isAbsolute(stateDirName) ? [stateDirName] : (() => {
+		const dirs = [];
+		let dir = cwd;
+		while (true) {
+			dirs.push(join(dir, stateDirName));
+			const parent = dirname(dir);
+			if (parent === dir) return dirs;
+			dir = parent;
+		}
+	})();
+	for (const stateDir of startDirs) {
+		const stacksDir = join(stateDir, "stacks");
+		if (!existsSync(stacksDir)) continue;
+		const manifests = readdirSync(stacksDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join(stacksDir, entry.name, "manifest.json")).filter((path) => existsSync(path)).sort();
+		if (manifests.length === 1) return manifests[0];
+		if (manifests.length > 1) return null;
+	}
+	return null;
+};
 //#endregion
-export { DEFAULT_STACK, DEFAULT_STATE_DIR, discoverBuildIntegrationIdentity, discoverManifestPath, readAppName, readAppNameWalkup, resolveBuildIntegrationStack };
+export { DEFAULT_STACK, DEFAULT_STATE_DIR, discoverManifestPath, discoverSingleStackManifestPath, readAppName, readAppNameWalkup, resolveBuildIntegrationStack };
 
 //# sourceMappingURL=discover.mjs.map

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, 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":"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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>` 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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"}

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

@@ -13,7 +13,9 @@ declare class EndpointRegistry {
   /** 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`). */
+  /** Filter endpoints by wire protocol — currently `'http' | 'h2c' |
+   *  'tcp'`. Typed as `string` for forward-compat with plugin-added
+   *  protocols; mistyped values just return an empty array. */
   byKind(wireProtocol: string): ReadonlyArray<ResolvedEndpoint>;
   /** All endpoints, alphabetical by name. */
   all(): ReadonlyArray<ResolvedEndpoint>;

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

@@ -21,7 +21,9 @@ var EndpointRegistry = class {
 	byPluginKey(pluginKey) {
 		return this.entries.filter((e) => e.pluginKey === pluginKey);
 	}
-	/** Filter endpoints by wire protocol (`http`, `h2c`). */
+	/** Filter endpoints by wire protocol — currently `'http' | 'h2c' |
+	*  'tcp'`. Typed as `string` for forward-compat with plugin-added
+	*  protocols; mistyped values just return an empty array. */
 	byKind(wireProtocol) {
 		return this.entries.filter((e) => e.wireProtocol === wireProtocol);
 	}

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)`: 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"}
+{"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"}

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

@@ -1,7 +1,12 @@
-import { BuildIntegrationIdentity, DEFAULT_STACK, DEFAULT_STATE_DIR, DiscoverBuildIntegrationIdentityOptions, DiscoverManifestPathOptions, discoverBuildIntegrationIdentity, discoverManifestPath, readAppName, readAppNameWalkup } from "./discover.mjs";
+import { PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY, PlaywrightStackFixture } from "./playwright-stack-context-slot.mjs";
+import { DEFAULT_STACK, DEFAULT_STATE_DIR, DiscoverManifestPathOptions, DiscoverSingleStackManifestPathOptions, discoverManifestPath, discoverSingleStackManifestPath, readAppName, readAppNameWalkup } from "./discover.mjs";
+import { EndpointEntry, ManifestEnvelope, ManifestEnvelopeSchema } from "../../substrate/manifest.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 { DEFAULT_DISCOVERY_STACK, DEFAULT_DISCOVERY_STATE_DIR, DISCOVERY_ENV, ResolveDiscoveryEnvOptions, ResolvedDiscoveryEnv, resolveDiscoveryEnv } from "./resolve-discovery-env.mjs";
 import { ColdStartUrlOptions, ConventionalRoute, ConventionalRouteHint, ConventionalRouteHostInput, ConventionalRouteUrlInput, coldStartUrl, conventionalRouteHost, conventionalRouteUrl, conventionalRoutesFromHints, tryColdStartUrl } from "./cold-start-url.mjs";
+import { BUILT_IN_CONVENTIONAL_HINTS, BUILT_IN_ENDPOINT_ALIASES, DEFAULT_ROUTER_ENTRYPOINT_PORT, builtInConventionalRoutes, resolveBuiltInEndpointAlias } from "./conventional-routes.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 };
+import { WALLET_AUTH_HEADER, WALLET_BEARER_PREFIX, WALLET_ENDPOINT_KEY, WALLET_ENDPOINT_NAME, WALLET_PROTOCOL_PREFIX, WALLET_TOKEN_FRAGMENT_KEY, WALLET_TOKEN_HEX_LENGTH, WalletHttpPath, WalletHttpPathValue } from "../../contracts/wallet-protocol.mjs";
+export { BUILT_IN_CONVENTIONAL_HINTS, BUILT_IN_ENDPOINT_ALIASES, CONSUMER_MANIFEST_VERSION, type ColdStartUrlOptions, type ConventionalRoute, type ConventionalRouteHint, type ConventionalRouteHostInput, type ConventionalRouteUrlInput, DEFAULT_DISCOVERY_STACK, DEFAULT_DISCOVERY_STATE_DIR, DEFAULT_ROUTER_ENTRYPOINT_PORT, DEFAULT_STACK, DEFAULT_STATE_DIR, DISCOVERY_ENV, type DiscoverManifestPathOptions, type DiscoverSingleStackManifestPathOptions, type EndpointEntry, EndpointRegistry, ManifestDiscoveryError, type ManifestDiscoveryPhase, type ManifestEnvelope, ManifestEnvelopeSchema, ManifestShapeError, type ManifestShapePhase, NoConventionalRouteError, PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY, type PlaywrightStackFixture, type ReadStackContextOptions, type ResolveDiscoveryEnvOptions, type ResolvedDiscoveryEnv, type ResolvedEndpoint, type StackContext, type StackIdentity, WALLET_AUTH_HEADER, WALLET_BEARER_PREFIX, WALLET_ENDPOINT_KEY, WALLET_ENDPOINT_NAME, WALLET_PROTOCOL_PREFIX, WALLET_TOKEN_FRAGMENT_KEY, WALLET_TOKEN_HEX_LENGTH, WalletHttpPath, type WalletHttpPathValue, builtInConventionalRoutes, coldStartUrl, conventionalRouteHost, conventionalRouteUrl, conventionalRoutesFromHints, discoverManifestPath, discoverSingleStackManifestPath, manifestEnvelopeFromStackContext, readAppName, readAppNameWalkup, readStackContext, resolveBuiltInEndpointAlias, resolveDiscoveryEnv, tryColdStartUrl };