@mysten-incubation/devstack 0.3.0 → 0.4.0

package/dist/orchestrators/codegen/config-runtime.mjs

@@ -7,28 +7,29 @@ const CONFIG_RUNTIME_SOURCE = `// THIS FILE IS AUTO-GENERATED BY @mysten/devstac
 // \`devstack codegen\`. Apps consume codegen output; codegen output never
 // imports from devstack.
 //
-// Loud-failing on-chain id resolver. The committed \`config.ts\` carries no
-// ids; it resolves each id through \`resolveId(...)\` here, which reads the
-// build-time-injected \`__DEVSTACK_IDS__\` global. Run \`devstack up\` for
-// local dev (the Vite plugin injects the live ids), or point the build at a
-// committed id-config file for a real deployment.
+// On-chain deployment resolver. The committed \`config.ts\`
+// carries no ids; it resolves each id through the deployment API here
+// (\`loadDeployment()\` / \`requireId(dep, ...)\`), which reads the build-time-
+// injected \`__DEVSTACK_DEPLOYMENT__\` envelope. Run \`devstack up\` for local
+// dev (the Vite plugin injects the live deployment), or commit a per-network
+// \`deployments/<net>.ts\` for a real deployment.
 
 const UNRESOLVED_ID =
 	'0x0000000000000000000000000000000000000000000000000000000000000000';
 
-// Node-only runtime fallback for the on-chain ids. The browser/dev/prod
-// path injects \`__DEVSTACK_IDS__\` via the Vite \`define\` (replaced at
+// Node-only runtime fallback for the injected deployment. The browser/dev/prod
+// path injects \`__DEVSTACK_DEPLOYMENT__\` via the Vite \`define\` (replaced at
 // transform time); this fallback ONLY engages when that define is absent —
 // i.e. under Node/vitest, where the \`define\` bakes to \`null\` because the
 // test stack is booted by the vitest \`globalSetup\` AFTER the Vite config
 // (and so this module) is evaluated. The devstack vitest \`globalSetup\`
-// publishes the booted stack's id-config FILE path as
-// \`process.env.DEVSTACK_IDS_FILE\`; we read+parse it lazily here. Guarded so
-// browser bundles (no \`process\`, no \`node:fs\`) never touch it. Returns
-// \`null\` on any miss, so \`ids()\` throws its actionable error as before.
-// Minimal LOCAL shapes (no \`@types/node\` dependency — this file is also
-// type-checked in browser tsconfigs that don't load node types). We reach
-// \`process\` through \`globalThis\` and feature-test every member.
+// publishes the booted stack's deployment FILE path as
+// \`process.env.DEVSTACK_DEPLOYMENT_FILE\`; we read+parse the ENVELOPE lazily
+// here. Guarded so browser bundles (no \`process\`, no \`node:fs\`) never touch
+// it. Returns \`null\` on any miss, so the resolvers throw their actionable
+// error as before. Minimal LOCAL shapes (no \`@types/node\` dependency — this
+// file is also type-checked in browser tsconfigs that don't load node types).
+// We reach \`process\` through \`globalThis\` and feature-test every member.
 interface NodeProcessLike {
 	readonly env?: { readonly [k: string]: string | undefined };
 	readonly getBuiltinModule?: (id: string) => unknown;
@@ -37,15 +38,15 @@ interface NodeFsLike {
 	readonly existsSync: (p: string) => boolean;
 	readonly readFileSync: (p: string, enc: 'utf8') => string;
 }
-let nodeFallbackCache: DevstackIds | null | undefined;
-const readNodeFallbackIds = (): DevstackIds | null => {
+let nodeFallbackCache: DevstackDeployment | null | undefined;
+const readNodeFallbackDeployment = (): DevstackDeployment | null => {
 	if (nodeFallbackCache !== undefined) return nodeFallbackCache;
 	nodeFallbackCache = null;
 	try {
 		const proc = (globalThis as { process?: NodeProcessLike }).process;
 		if (proc === undefined) return null;
-		const idsFile = proc.env?.DEVSTACK_IDS_FILE;
-		if (idsFile === undefined || idsFile.length === 0) return null;
+		const file = proc.env?.DEVSTACK_DEPLOYMENT_FILE;
+		if (file === undefined || file.length === 0) return null;
 		// \`process.getBuiltinModule\` (Node >=22.3) loads \`node:fs\`
 		// synchronously without an \`import\`/\`require\` literal a browser
 		// bundler would try to resolve — this whole branch is unreachable in
@@ -53,153 +54,177 @@ const readNodeFallbackIds = (): DevstackIds | null => {
 		const getBuiltin = proc.getBuiltinModule;
 		if (typeof getBuiltin !== 'function') return null;
 		const fs = getBuiltin('node:fs') as NodeFsLike;
-		if (!fs.existsSync(idsFile)) return null;
-		nodeFallbackCache = JSON.parse(fs.readFileSync(idsFile, 'utf8')) as DevstackIds;
+		if (!fs.existsSync(file)) return null;
+		nodeFallbackCache = JSON.parse(fs.readFileSync(file, 'utf8')) as DevstackDeployment;
 		return nodeFallbackCache;
 	} catch {
 		return null;
 	}
 };
 
-/** The injected ids, or — under Node with no injected define — the
- *  \`DEVSTACK_IDS_FILE\` fallback. \`null\` when neither is available. */
-const injectedIds = (): DevstackIds | null => {
-	const injected = typeof __DEVSTACK_IDS__ === 'undefined' ? null : __DEVSTACK_IDS__;
+/** The injected deployment envelope, or — under Node with no injected define —
+ *  the \`DEVSTACK_DEPLOYMENT_FILE\` fallback. \`null\` when neither is
+ *  available. */
+const injectedDeployment = (): DevstackDeployment | null => {
+	const injected =
+		typeof __DEVSTACK_DEPLOYMENT__ === 'undefined' ? null : __DEVSTACK_DEPLOYMENT__;
 	if (injected !== null && injected !== undefined) return injected;
-	return readNodeFallbackIds();
+	return readNodeFallbackDeployment();
 };
 
-/** One network connection entry — \`rpc\` is the load-bearing field the app
- *  reads synchronously; \`chainId\`/\`faucet\`/\`graphql\` are optional
- *  diagnostics (mirrors \`IdConfigNetworkSchema\`). */
-export interface DevstackNetworkEntry {
+/** One network's full resolved deployment — connection fields (\`rpc\` is the
+ *  load-bearing one the app reads synchronously; \`chainId\`/\`faucet\`/
+ *  \`graphql\` are optional diagnostics) plus the on-chain ids/values for that
+ *  network. The per-network UNIT of the multi-network envelope; hand-writable
+ *  for production. */
+export interface NetworkDeployment {
+	readonly network?: string;
 	readonly rpc: string;
 	readonly chainId?: string;
 	readonly faucet?: string | null;
 	readonly graphql?: string | null;
-}
-
-/** Shape of the injected ids. \`null\` when no stack is running and no
- *  id-config file was supplied at build time. */
-export interface DevstackIds {
-	readonly network: string;
-	readonly networks: { readonly [name: string]: DevstackNetworkEntry };
+	/** Marks a live LOCAL network (a \`devstack up\` stack). Production builds
+	 *  ship only non-local networks. */
+	readonly local?: boolean;
 	readonly packages: {
 		readonly [name: string]: { readonly id: string; readonly objects?: { readonly [k: string]: string } };
 	};
-	readonly accounts: { readonly [name: string]: string };
-	readonly mvrOverrides: { readonly [mvrPlaceholder: string]: string };
-	/** Generic resolver channel: \`values[namespace][key]\` carries
-	 *  arbitrary plugin JSON the typed fields above can't (deepbook pool
-	 *  ids, coin types, walrus/seal endpoints). Optional — an older
-	 *  injected blob (no \`values\`) still satisfies the typed resolvers. */
+	readonly mvrOverrides: {
+		readonly packages: { readonly [mvrPlaceholder: string]: string };
+		readonly types: { readonly [namedType: string]: string };
+	};
+	/** Generic resolver channel: \`values[namespace][key]\` carries arbitrary
+	 *  plugin JSON the typed fields above can't (deepbook pool ids, coin
+	 *  types, walrus/seal endpoints). Optional — an older injected unit (no
+	 *  \`values\`) still satisfies the typed resolvers. */
 	readonly values?: { readonly [namespace: string]: { readonly [key: string]: unknown } };
 }
 
+/** The injected multi-network ENVELOPE: every network this build supports,
+ *  keyed by name, plus the default the app opens on. \`null\` when no stack is
+ *  running and no committed deployment was supplied at build time. */
+export interface DevstackDeployment {
+	readonly defaultNetwork: string;
+	readonly networks: { readonly [name: string]: NetworkDeployment };
+	/** DEV-only account name → address map. Network-AGNOSTIC (keypair gen
+	 *  needs no network), so it lives on the envelope, NOT per-network. Only
+	 *  present when running THROUGH devstack (dev serve); a real prod
+	 *  deployment carries none. Optional — \`resolveAccounts()\` defaults to
+	 *  \`{}\` when absent. */
+	readonly accounts?: { readonly [name: string]: string };
+}
+
+/** Accessor returned by \`loadDeployment()\` — the default network, the set of
+ *  available network names (for dapp-kit's network list), and a per-network
+ *  lookup that throws when the network is unknown. */
+export interface LoadedDeployment {
+	readonly defaultNetwork: string;
+	readonly networkNames: readonly string[];
+	readonly forNetwork: (network: string) => NetworkDeployment;
+}
+
 declare global {
 	// Injected by the devstack Vite plugin via \`define\`. \`null\` when no
-	// ids are available (no stack up + no id-config file).
-	const __DEVSTACK_IDS__: DevstackIds | null | undefined;
+	// deployment is available (no stack up + no committed deployment).
+	const __DEVSTACK_DEPLOYMENT__: DevstackDeployment | null | undefined;
 }
 
 /** Thrown when a generated config value needs an on-chain id but none was
- *  injected — actionable, not a silent zero. */
+ *  injected. */
 export class DevstackConfigMissingError extends Error {
 	constructor(detail: string) {
 		super(
 			\`[devstack] \${detail}\\n\` +
-				\`No on-chain ids are available. For local dev, run \\\`devstack up\\\` \` +
-				\`(the Vite dev server injects the live ids). For a production build, \` +
-				\`point the build at the known deployment's committed id-config file \` +
-				\`(the Vite plugin \\\`ids\\\` option, or \\\`DEVSTACK_IDS_FILE\\\`) before \` +
-				\`\\\`pnpm build\\\`. See your example README's "Deploy to a real network" \` +
-				\`section.\`,
+				\`No on-chain deployment is available. For local dev, run \\\`devstack up\\\` \` +
+				\`(the Vite dev server injects the live deployment). For a production build, \` +
+				\`commit the known deployment's per-network \\\`deployments/<net>.ts\\\` \` +
+				\`(wired into the Vite plugin's \\\`deployments\\\` option, or pointed at via \` +
+				\`\\\`DEVSTACK_DEPLOYMENT_FILE\\\`) before \\\`pnpm build\\\`. See your example \` +
+				\`README's "Deploy to a real network" section.\`,
 		);
 		this.name = 'DevstackConfigMissingError';
 	}
 }
 
-const ids = (): DevstackIds => {
-	const injected = injectedIds();
+/** Wrap a resolved \`DevstackDeployment\` envelope in the \`LoadedDeployment\`
+ *  accessor the app consumes. */
+const loadedFrom = (deployment: DevstackDeployment): LoadedDeployment => ({
+	defaultNetwork: deployment.defaultNetwork,
+	networkNames: Object.keys(deployment.networks),
+	forNetwork: (network) => {
+		const entry = deployment.networks[network];
+		if (entry === undefined) {
+			throw new DevstackConfigMissingError(\`network "\${network}" has no deployment\`);
+		}
+		return entry;
+	},
+});
+
+/** Load the injected deployment envelope. Throws once here when nothing
+ *  was injected; the app then reads typed fields off \`forNetwork(net)\`. */
+export const loadDeployment = (): LoadedDeployment => {
+	const injected = injectedDeployment();
 	if (injected === null || injected === undefined) {
-		throw new DevstackConfigMissingError('on-chain ids were never injected');
+		throw new DevstackConfigMissingError('no deployment was ever injected');
 	}
-	return injected;
+	return loadedFrom(injected);
 };
 
-/** Resolve the active-network id for an MVR placeholder (\`@local/<slug>\`).
- *  Throws \`DevstackConfigMissingError\` when the id is absent or the
- *  all-zero sentinel. */
-export const resolveId = (mvrPlaceholder: string): string => {
-	const id = ids().mvrOverrides[mvrPlaceholder];
+/** Non-throwing sibling of \`loadDeployment\` — returns \`null\` instead of
+ *  throwing when nothing was injected. For dev-only consumers (e.g. the dev
+ *  wallet) that must no-op gracefully when no stack is running. */
+export const loadDeploymentOptional = (): LoadedDeployment | null => {
+	const injected = injectedDeployment();
+	if (injected === null || injected === undefined) return null;
+	return loadedFrom(injected);
+};
+
+/** The DEV-only account name → address map off the injected envelope.
+ *  Accounts are network-AGNOSTIC dev identities (envelope-level, never
+ *  per-network), injected only when running THROUGH devstack. Returns \`{}\`
+ *  — without throwing — when no deployment was injected or none carries
+ *  accounts (a pure prod build), so a dev-only consumer (e.g. the dev
+ *  wallet) no-ops gracefully. */
+export const resolveAccounts = (): { readonly [name: string]: string } => {
+	const injected = injectedDeployment();
+	return injected?.accounts ?? {};
+};
+
+/** Resolve a package id for an MVR placeholder off a loaded deployment.
+ *  Throws when the id is missing or unresolved. */
+export const requireId = (deployment: NetworkDeployment, mvrPlaceholder: string): string => {
+	const id = deployment.mvrOverrides.packages[mvrPlaceholder];
 	if (id === undefined || id === UNRESOLVED_ID) {
 		throw new DevstackConfigMissingError(\`id for "\${mvrPlaceholder}" is unresolved\`);
 	}
 	return id;
 };
 
-/** Resolve the active network name (the \`networks.<name>\` key the app
- *  reads). Environment/live data — the local stack picks a dynamic value
- *  and a real deployment names a different network — so it is injected,
- *  never baked into the committed tree. Throws when no ids were injected. */
-export const resolveNetwork = (): string => ids().network;
-
-/** Resolve the network connection map (\`{ [name]: DevstackNetworkEntry }\`).
- *  The local rpc carries a dynamic port; a real deployment supplies its own —
- *  so this is injected, never baked. Throws when no ids were injected. */
-export const resolveNetworks = (): { readonly [name: string]: DevstackNetworkEntry } =>
-	ids().networks;
-
-/** Resolve the ACTIVE network's connection entry —
- *  \`resolveNetworks()[resolveNetwork()]\` with a non-undefined return type and
- *  a loud throw. Removes the \`config.networks[config.network]\` index-signature
- *  footgun: the app reads \`.rpc\` etc. off a guaranteed entry instead of
- *  threading an \`undefined\` past the index lookup. Throws
- *  \`DevstackConfigMissingError\` when no ids were injected or the active
- *  network has no entry in the injected map. */
-export const resolveActiveNetwork = (): DevstackNetworkEntry => {
-	const network = resolveNetwork();
-	const entry = resolveNetworks()[network];
-	if (entry === undefined) {
-		throw new DevstackConfigMissingError(\`active network "\${network}" has no entry\`);
-	}
-	return entry;
-};
-
-/** Resolve a generic plugin value (\`values[namespace][key]\`). The committed
- *  \`config.ts\` calls this for any live plugin value that isn't a package id
- *  or the network — deepbook pool ids, coin types, walrus/seal endpoints.
- *  Throws \`DevstackConfigMissingError\` when no ids were injected, the value
- *  is missing, or it is the all-zero sentinel. */
-export const resolveValue = <T = unknown>(namespace: string, key: string): T => {
-	const values = ids().values ?? {};
-	const namespaceValues = values[namespace];
+/** Resolve a generic plugin value (\`values[namespace][key]\`) off a loaded
+ *  deployment. Throws when the value is missing or unresolved. */
+export const requireValue = <T = unknown>(
+	deployment: NetworkDeployment,
+	namespace: string,
+	key: string,
+): T => {
+	const namespaceValues = deployment.values?.[namespace];
 	const value = namespaceValues === undefined ? undefined : namespaceValues[key];
 	if (value === undefined || value === UNRESOLVED_ID) {
-		throw new DevstackConfigMissingError(
-			\`value "\${namespace}.\${key}" is unresolved\`,
-		);
+		throw new DevstackConfigMissingError(\`value "\${namespace}.\${key}" is unresolved\`);
 	}
 	return value as T;
 };
 
-/** Non-throwing variant of \`resolveValue\`: returns \`undefined\` instead of
- *  throwing \`DevstackConfigMissingError\` when no ids were injected, the value
- *  is missing, or it is the all-zero sentinel. For discovery-only ids the app
- *  GATES on (e.g. a coin's \`treasuryCapId\`/\`metadataId\`, only known after a
- *  live publish) rather than the load-bearing fields that should fail loud. */
-export const resolveValueOptional = <T = unknown>(
+/** Non-throwing sibling of \`requireValue\` for discovery-only fields the app
+ *  gates on (returns \`undefined\` when missing, unresolved, or absent). */
+export const optionalValue = <T = unknown>(
+	deployment: NetworkDeployment,
 	namespace: string,
 	key: string,
 ): T | undefined => {
-	const injected = injectedIds();
-	const values = injected?.values ?? {};
-	const namespaceValues = values[namespace];
+	const namespaceValues = deployment.values?.[namespace];
 	const value = namespaceValues === undefined ? undefined : namespaceValues[key];
-	if (value === undefined || value === UNRESOLVED_ID) {
-		return undefined;
-	}
-	return value as T;
+	return value === undefined || value === UNRESOLVED_ID ? undefined : (value as T);
 };
 `;
 //#endregion

package/dist/orchestrators/codegen/config-runtime.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config-runtime.mjs","names":[],"sources":["../../../src/orchestrators/codegen/config-runtime.ts"],"sourcesContent":["// The FIXED `config-runtime.ts` source the codegen verb emits into the\n// committed `src/generated` tree.\n//\n// This is NOT routed through the literal renderer (`format.ts`) — it is a\n// constant string, emitted verbatim. It is the loud-failing id resolver\n// the committed `config.ts` calls: `config.ts` carries NO on-chain id\n// (those are LOADED CONFIG DATA, not codegen output), so each id is a\n// `resolveId('@local/<slug>')` call into this module, which reads the\n// build-time-injected `__DEVSTACK_IDS__` global and THROWS a clear,\n// actionable error when the id is absent or the all-zero sentinel.\n//\n// `__DEVSTACK_IDS__` is injected synchronously by the devstack Vite plugin\n// (`build-integrations/vite/index.ts`) via `define`:\n//   - dev (stack up): the live `.devstack/stacks/<stack>/devstack-ids.json`.\n//   - prod build:     a committed id-config FILE (same schema) — the Vite\n//                     plugin `ids` option or a `DEVSTACK_IDS_FILE` path.\n//   - neither:        `null` → `resolveId` throws at access time.\n\n/** Output path (relative to the generated tree) of the emitted resolver. */\nexport const CONFIG_RUNTIME_OUTPUT_PATH = 'config-runtime.ts';\n\n/** The verbatim source emitted as `src/generated/config-runtime.ts`. */\nexport const CONFIG_RUNTIME_SOURCE = `// THIS FILE IS AUTO-GENERATED BY @mysten/devstack.\n// Do not edit by hand — your changes will be overwritten by the next\n// \\`devstack codegen\\`. Apps consume codegen output; codegen output never\n// imports from devstack.\n//\n// Loud-failing on-chain id resolver. The committed \\`config.ts\\` carries no\n// ids; it resolves each id through \\`resolveId(...)\\` here, which reads the\n// build-time-injected \\`__DEVSTACK_IDS__\\` global. Run \\`devstack up\\` for\n// local dev (the Vite plugin injects the live ids), or point the build at a\n// committed id-config file for a real deployment.\n\nconst UNRESOLVED_ID =\n\t'0x0000000000000000000000000000000000000000000000000000000000000000';\n\n// Node-only runtime fallback for the on-chain ids. The browser/dev/prod\n// path injects \\`__DEVSTACK_IDS__\\` via the Vite \\`define\\` (replaced at\n// transform time); this fallback ONLY engages when that define is absent —\n// i.e. under Node/vitest, where the \\`define\\` bakes to \\`null\\` because the\n// test stack is booted by the vitest \\`globalSetup\\` AFTER the Vite config\n// (and so this module) is evaluated. The devstack vitest \\`globalSetup\\`\n// publishes the booted stack's id-config FILE path as\n// \\`process.env.DEVSTACK_IDS_FILE\\`; we read+parse it lazily here. Guarded so\n// browser bundles (no \\`process\\`, no \\`node:fs\\`) never touch it. Returns\n// \\`null\\` on any miss, so \\`ids()\\` throws its actionable error as before.\n// Minimal LOCAL shapes (no \\`@types/node\\` dependency — this file is also\n// type-checked in browser tsconfigs that don't load node types). We reach\n// \\`process\\` through \\`globalThis\\` and feature-test every member.\ninterface NodeProcessLike {\n\treadonly env?: { readonly [k: string]: string | undefined };\n\treadonly getBuiltinModule?: (id: string) => unknown;\n}\ninterface NodeFsLike {\n\treadonly existsSync: (p: string) => boolean;\n\treadonly readFileSync: (p: string, enc: 'utf8') => string;\n}\nlet nodeFallbackCache: DevstackIds | null | undefined;\nconst readNodeFallbackIds = (): DevstackIds | null => {\n\tif (nodeFallbackCache !== undefined) return nodeFallbackCache;\n\tnodeFallbackCache = null;\n\ttry {\n\t\tconst proc = (globalThis as { process?: NodeProcessLike }).process;\n\t\tif (proc === undefined) return null;\n\t\tconst idsFile = proc.env?.DEVSTACK_IDS_FILE;\n\t\tif (idsFile === undefined || idsFile.length === 0) return null;\n\t\t// \\`process.getBuiltinModule\\` (Node >=22.3) loads \\`node:fs\\`\n\t\t// synchronously without an \\`import\\`/\\`require\\` literal a browser\n\t\t// bundler would try to resolve — this whole branch is unreachable in\n\t\t// the browser (no \\`process\\`), so node:fs never enters the bundle.\n\t\tconst getBuiltin = proc.getBuiltinModule;\n\t\tif (typeof getBuiltin !== 'function') return null;\n\t\tconst fs = getBuiltin('node:fs') as NodeFsLike;\n\t\tif (!fs.existsSync(idsFile)) return null;\n\t\tnodeFallbackCache = JSON.parse(fs.readFileSync(idsFile, 'utf8')) as DevstackIds;\n\t\treturn nodeFallbackCache;\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n/** The injected ids, or — under Node with no injected define — the\n *  \\`DEVSTACK_IDS_FILE\\` fallback. \\`null\\` when neither is available. */\nconst injectedIds = (): DevstackIds | null => {\n\tconst injected = typeof __DEVSTACK_IDS__ === 'undefined' ? null : __DEVSTACK_IDS__;\n\tif (injected !== null && injected !== undefined) return injected;\n\treturn readNodeFallbackIds();\n};\n\n/** One network connection entry — \\`rpc\\` is the load-bearing field the app\n *  reads synchronously; \\`chainId\\`/\\`faucet\\`/\\`graphql\\` are optional\n *  diagnostics (mirrors \\`IdConfigNetworkSchema\\`). */\nexport interface DevstackNetworkEntry {\n\treadonly rpc: string;\n\treadonly chainId?: string;\n\treadonly faucet?: string | null;\n\treadonly graphql?: string | null;\n}\n\n/** Shape of the injected ids. \\`null\\` when no stack is running and no\n *  id-config file was supplied at build time. */\nexport interface DevstackIds {\n\treadonly network: string;\n\treadonly networks: { readonly [name: string]: DevstackNetworkEntry };\n\treadonly packages: {\n\t\treadonly [name: string]: { readonly id: string; readonly objects?: { readonly [k: string]: string } };\n\t};\n\treadonly accounts: { readonly [name: string]: string };\n\treadonly mvrOverrides: { readonly [mvrPlaceholder: string]: string };\n\t/** Generic resolver channel: \\`values[namespace][key]\\` carries\n\t *  arbitrary plugin JSON the typed fields above can't (deepbook pool\n\t *  ids, coin types, walrus/seal endpoints). Optional — an older\n\t *  injected blob (no \\`values\\`) still satisfies the typed resolvers. */\n\treadonly values?: { readonly [namespace: string]: { readonly [key: string]: unknown } };\n}\n\ndeclare global {\n\t// Injected by the devstack Vite plugin via \\`define\\`. \\`null\\` when no\n\t// ids are available (no stack up + no id-config file).\n\tconst __DEVSTACK_IDS__: DevstackIds | null | undefined;\n}\n\n/** Thrown when a generated config value needs an on-chain id but none was\n *  injected — actionable, not a silent zero. */\nexport class DevstackConfigMissingError extends Error {\n\tconstructor(detail: string) {\n\t\tsuper(\n\t\t\t\\`[devstack] \\${detail}\\\\n\\` +\n\t\t\t\t\\`No on-chain ids are available. For local dev, run \\\\\\`devstack up\\\\\\` \\` +\n\t\t\t\t\\`(the Vite dev server injects the live ids). For a production build, \\` +\n\t\t\t\t\\`point the build at the known deployment's committed id-config file \\` +\n\t\t\t\t\\`(the Vite plugin \\\\\\`ids\\\\\\` option, or \\\\\\`DEVSTACK_IDS_FILE\\\\\\`) before \\` +\n\t\t\t\t\\`\\\\\\`pnpm build\\\\\\`. See your example README's \"Deploy to a real network\" \\` +\n\t\t\t\t\\`section.\\`,\n\t\t);\n\t\tthis.name = 'DevstackConfigMissingError';\n\t}\n}\n\nconst ids = (): DevstackIds => {\n\tconst injected = injectedIds();\n\tif (injected === null || injected === undefined) {\n\t\tthrow new DevstackConfigMissingError('on-chain ids were never injected');\n\t}\n\treturn injected;\n};\n\n/** Resolve the active-network id for an MVR placeholder (\\`@local/<slug>\\`).\n *  Throws \\`DevstackConfigMissingError\\` when the id is absent or the\n *  all-zero sentinel. */\nexport const resolveId = (mvrPlaceholder: string): string => {\n\tconst id = ids().mvrOverrides[mvrPlaceholder];\n\tif (id === undefined || id === UNRESOLVED_ID) {\n\t\tthrow new DevstackConfigMissingError(\\`id for \"\\${mvrPlaceholder}\" is unresolved\\`);\n\t}\n\treturn id;\n};\n\n/** Resolve the active network name (the \\`networks.<name>\\` key the app\n *  reads). Environment/live data — the local stack picks a dynamic value\n *  and a real deployment names a different network — so it is injected,\n *  never baked into the committed tree. Throws when no ids were injected. */\nexport const resolveNetwork = (): string => ids().network;\n\n/** Resolve the network connection map (\\`{ [name]: DevstackNetworkEntry }\\`).\n *  The local rpc carries a dynamic port; a real deployment supplies its own —\n *  so this is injected, never baked. Throws when no ids were injected. */\nexport const resolveNetworks = (): { readonly [name: string]: DevstackNetworkEntry } =>\n\tids().networks;\n\n/** Resolve the ACTIVE network's connection entry —\n *  \\`resolveNetworks()[resolveNetwork()]\\` with a non-undefined return type and\n *  a loud throw. Removes the \\`config.networks[config.network]\\` index-signature\n *  footgun: the app reads \\`.rpc\\` etc. off a guaranteed entry instead of\n *  threading an \\`undefined\\` past the index lookup. Throws\n *  \\`DevstackConfigMissingError\\` when no ids were injected or the active\n *  network has no entry in the injected map. */\nexport const resolveActiveNetwork = (): DevstackNetworkEntry => {\n\tconst network = resolveNetwork();\n\tconst entry = resolveNetworks()[network];\n\tif (entry === undefined) {\n\t\tthrow new DevstackConfigMissingError(\\`active network \"\\${network}\" has no entry\\`);\n\t}\n\treturn entry;\n};\n\n/** Resolve a generic plugin value (\\`values[namespace][key]\\`). The committed\n *  \\`config.ts\\` calls this for any live plugin value that isn't a package id\n *  or the network — deepbook pool ids, coin types, walrus/seal endpoints.\n *  Throws \\`DevstackConfigMissingError\\` when no ids were injected, the value\n *  is missing, or it is the all-zero sentinel. */\nexport const resolveValue = <T = unknown>(namespace: string, key: string): T => {\n\tconst values = ids().values ?? {};\n\tconst namespaceValues = values[namespace];\n\tconst value = namespaceValues === undefined ? undefined : namespaceValues[key];\n\tif (value === undefined || value === UNRESOLVED_ID) {\n\t\tthrow new DevstackConfigMissingError(\n\t\t\t\\`value \"\\${namespace}.\\${key}\" is unresolved\\`,\n\t\t);\n\t}\n\treturn value as T;\n};\n\n/** Non-throwing variant of \\`resolveValue\\`: returns \\`undefined\\` instead of\n *  throwing \\`DevstackConfigMissingError\\` when no ids were injected, the value\n *  is missing, or it is the all-zero sentinel. For discovery-only ids the app\n *  GATES on (e.g. a coin's \\`treasuryCapId\\`/\\`metadataId\\`, only known after a\n *  live publish) rather than the load-bearing fields that should fail loud. */\nexport const resolveValueOptional = <T = unknown>(\n\tnamespace: string,\n\tkey: string,\n): T | undefined => {\n\tconst injected = injectedIds();\n\tconst values = injected?.values ?? {};\n\tconst namespaceValues = values[namespace];\n\tconst value = namespaceValues === undefined ? undefined : namespaceValues[key];\n\tif (value === undefined || value === UNRESOLVED_ID) {\n\t\treturn undefined;\n\t}\n\treturn value as T;\n};\n`;\n"],"mappings":";;AAmBA,MAAa,6BAA6B;;AAG1C,MAAa,wBAAwB"}
+{"version":3,"file":"config-runtime.mjs","names":[],"sources":["../../../src/orchestrators/codegen/config-runtime.ts"],"sourcesContent":["// The FIXED `config-runtime.ts` source the codegen verb emits into the\n// committed `src/generated` tree.\n//\n// This is NOT routed through the literal renderer (`format.ts`) — it is a\n// constant string, emitted verbatim. It is the deployment\n// resolver the committed `config.ts` calls: `config.ts` carries NO on-chain\n// id (those are LOADED CONFIG DATA, not codegen output), so each id resolves\n// through `requireId(dep, '@local/<slug>')` / `loadDeployment()` here, which\n// reads the build-time-injected `__DEVSTACK_DEPLOYMENT__` global and throws a\n// clear, actionable error when the id is absent or unresolved.\n//\n// `__DEVSTACK_DEPLOYMENT__` is the multi-network ENVELOPE\n// `{ defaultNetwork, networks: { <net>: NetworkDeployment } }`, injected\n// synchronously by the devstack Vite plugin (`build-integrations/vite/index.ts`)\n// via `define`:\n//   - dev (stack up): the live local network OVERLAID on any committed\n//                     networks (the live network is the default).\n//   - prod build:     the committed, non-local networks only (the per-network\n//                     `deployments/<net>.ts` thunks the plugin merges).\n//   - neither:        `null` → the resolvers throw at access time.\n\n/** Output path (relative to the generated tree) of the emitted resolver. */\nexport const CONFIG_RUNTIME_OUTPUT_PATH = 'config-runtime.ts';\n\n/** The verbatim source emitted as `src/generated/config-runtime.ts`. */\nexport const CONFIG_RUNTIME_SOURCE = `// THIS FILE IS AUTO-GENERATED BY @mysten/devstack.\n// Do not edit by hand — your changes will be overwritten by the next\n// \\`devstack codegen\\`. Apps consume codegen output; codegen output never\n// imports from devstack.\n//\n// On-chain deployment resolver. The committed \\`config.ts\\`\n// carries no ids; it resolves each id through the deployment API here\n// (\\`loadDeployment()\\` / \\`requireId(dep, ...)\\`), which reads the build-time-\n// injected \\`__DEVSTACK_DEPLOYMENT__\\` envelope. Run \\`devstack up\\` for local\n// dev (the Vite plugin injects the live deployment), or commit a per-network\n// \\`deployments/<net>.ts\\` for a real deployment.\n\nconst UNRESOLVED_ID =\n\t'0x0000000000000000000000000000000000000000000000000000000000000000';\n\n// Node-only runtime fallback for the injected deployment. The browser/dev/prod\n// path injects \\`__DEVSTACK_DEPLOYMENT__\\` via the Vite \\`define\\` (replaced at\n// transform time); this fallback ONLY engages when that define is absent —\n// i.e. under Node/vitest, where the \\`define\\` bakes to \\`null\\` because the\n// test stack is booted by the vitest \\`globalSetup\\` AFTER the Vite config\n// (and so this module) is evaluated. The devstack vitest \\`globalSetup\\`\n// publishes the booted stack's deployment FILE path as\n// \\`process.env.DEVSTACK_DEPLOYMENT_FILE\\`; we read+parse the ENVELOPE lazily\n// here. Guarded so browser bundles (no \\`process\\`, no \\`node:fs\\`) never touch\n// it. Returns \\`null\\` on any miss, so the resolvers throw their actionable\n// error as before. Minimal LOCAL shapes (no \\`@types/node\\` dependency — this\n// file is also type-checked in browser tsconfigs that don't load node types).\n// We reach \\`process\\` through \\`globalThis\\` and feature-test every member.\ninterface NodeProcessLike {\n\treadonly env?: { readonly [k: string]: string | undefined };\n\treadonly getBuiltinModule?: (id: string) => unknown;\n}\ninterface NodeFsLike {\n\treadonly existsSync: (p: string) => boolean;\n\treadonly readFileSync: (p: string, enc: 'utf8') => string;\n}\nlet nodeFallbackCache: DevstackDeployment | null | undefined;\nconst readNodeFallbackDeployment = (): DevstackDeployment | null => {\n\tif (nodeFallbackCache !== undefined) return nodeFallbackCache;\n\tnodeFallbackCache = null;\n\ttry {\n\t\tconst proc = (globalThis as { process?: NodeProcessLike }).process;\n\t\tif (proc === undefined) return null;\n\t\tconst file = proc.env?.DEVSTACK_DEPLOYMENT_FILE;\n\t\tif (file === undefined || file.length === 0) return null;\n\t\t// \\`process.getBuiltinModule\\` (Node >=22.3) loads \\`node:fs\\`\n\t\t// synchronously without an \\`import\\`/\\`require\\` literal a browser\n\t\t// bundler would try to resolve — this whole branch is unreachable in\n\t\t// the browser (no \\`process\\`), so node:fs never enters the bundle.\n\t\tconst getBuiltin = proc.getBuiltinModule;\n\t\tif (typeof getBuiltin !== 'function') return null;\n\t\tconst fs = getBuiltin('node:fs') as NodeFsLike;\n\t\tif (!fs.existsSync(file)) return null;\n\t\tnodeFallbackCache = JSON.parse(fs.readFileSync(file, 'utf8')) as DevstackDeployment;\n\t\treturn nodeFallbackCache;\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n/** The injected deployment envelope, or — under Node with no injected define —\n *  the \\`DEVSTACK_DEPLOYMENT_FILE\\` fallback. \\`null\\` when neither is\n *  available. */\nconst injectedDeployment = (): DevstackDeployment | null => {\n\tconst injected =\n\t\ttypeof __DEVSTACK_DEPLOYMENT__ === 'undefined' ? null : __DEVSTACK_DEPLOYMENT__;\n\tif (injected !== null && injected !== undefined) return injected;\n\treturn readNodeFallbackDeployment();\n};\n\n/** One network's full resolved deployment — connection fields (\\`rpc\\` is the\n *  load-bearing one the app reads synchronously; \\`chainId\\`/\\`faucet\\`/\n *  \\`graphql\\` are optional diagnostics) plus the on-chain ids/values for that\n *  network. The per-network UNIT of the multi-network envelope; hand-writable\n *  for production. */\nexport interface NetworkDeployment {\n\treadonly network?: string;\n\treadonly rpc: string;\n\treadonly chainId?: string;\n\treadonly faucet?: string | null;\n\treadonly graphql?: string | null;\n\t/** Marks a live LOCAL network (a \\`devstack up\\` stack). Production builds\n\t *  ship only non-local networks. */\n\treadonly local?: boolean;\n\treadonly packages: {\n\t\treadonly [name: string]: { readonly id: string; readonly objects?: { readonly [k: string]: string } };\n\t};\n\treadonly mvrOverrides: {\n\t\treadonly packages: { readonly [mvrPlaceholder: string]: string };\n\t\treadonly types: { readonly [namedType: string]: string };\n\t};\n\t/** Generic resolver channel: \\`values[namespace][key]\\` carries arbitrary\n\t *  plugin JSON the typed fields above can't (deepbook pool ids, coin\n\t *  types, walrus/seal endpoints). Optional — an older injected unit (no\n\t *  \\`values\\`) still satisfies the typed resolvers. */\n\treadonly values?: { readonly [namespace: string]: { readonly [key: string]: unknown } };\n}\n\n/** The injected multi-network ENVELOPE: every network this build supports,\n *  keyed by name, plus the default the app opens on. \\`null\\` when no stack is\n *  running and no committed deployment was supplied at build time. */\nexport interface DevstackDeployment {\n\treadonly defaultNetwork: string;\n\treadonly networks: { readonly [name: string]: NetworkDeployment };\n\t/** DEV-only account name → address map. Network-AGNOSTIC (keypair gen\n\t *  needs no network), so it lives on the envelope, NOT per-network. Only\n\t *  present when running THROUGH devstack (dev serve); a real prod\n\t *  deployment carries none. Optional — \\`resolveAccounts()\\` defaults to\n\t *  \\`{}\\` when absent. */\n\treadonly accounts?: { readonly [name: string]: string };\n}\n\n/** Accessor returned by \\`loadDeployment()\\` — the default network, the set of\n *  available network names (for dapp-kit's network list), and a per-network\n *  lookup that throws when the network is unknown. */\nexport interface LoadedDeployment {\n\treadonly defaultNetwork: string;\n\treadonly networkNames: readonly string[];\n\treadonly forNetwork: (network: string) => NetworkDeployment;\n}\n\ndeclare global {\n\t// Injected by the devstack Vite plugin via \\`define\\`. \\`null\\` when no\n\t// deployment is available (no stack up + no committed deployment).\n\tconst __DEVSTACK_DEPLOYMENT__: DevstackDeployment | null | undefined;\n}\n\n/** Thrown when a generated config value needs an on-chain id but none was\n *  injected. */\nexport class DevstackConfigMissingError extends Error {\n\tconstructor(detail: string) {\n\t\tsuper(\n\t\t\t\\`[devstack] \\${detail}\\\\n\\` +\n\t\t\t\t\\`No on-chain deployment is available. For local dev, run \\\\\\`devstack up\\\\\\` \\` +\n\t\t\t\t\\`(the Vite dev server injects the live deployment). For a production build, \\` +\n\t\t\t\t\\`commit the known deployment's per-network \\\\\\`deployments/<net>.ts\\\\\\` \\` +\n\t\t\t\t\\`(wired into the Vite plugin's \\\\\\`deployments\\\\\\` option, or pointed at via \\` +\n\t\t\t\t\\`\\\\\\`DEVSTACK_DEPLOYMENT_FILE\\\\\\`) before \\\\\\`pnpm build\\\\\\`. See your example \\` +\n\t\t\t\t\\`README's \"Deploy to a real network\" section.\\`,\n\t\t);\n\t\tthis.name = 'DevstackConfigMissingError';\n\t}\n}\n\n/** Wrap a resolved \\`DevstackDeployment\\` envelope in the \\`LoadedDeployment\\`\n *  accessor the app consumes. */\nconst loadedFrom = (deployment: DevstackDeployment): LoadedDeployment => ({\n\tdefaultNetwork: deployment.defaultNetwork,\n\tnetworkNames: Object.keys(deployment.networks),\n\tforNetwork: (network) => {\n\t\tconst entry = deployment.networks[network];\n\t\tif (entry === undefined) {\n\t\t\tthrow new DevstackConfigMissingError(\\`network \"\\${network}\" has no deployment\\`);\n\t\t}\n\t\treturn entry;\n\t},\n});\n\n/** Load the injected deployment envelope. Throws once here when nothing\n *  was injected; the app then reads typed fields off \\`forNetwork(net)\\`. */\nexport const loadDeployment = (): LoadedDeployment => {\n\tconst injected = injectedDeployment();\n\tif (injected === null || injected === undefined) {\n\t\tthrow new DevstackConfigMissingError('no deployment was ever injected');\n\t}\n\treturn loadedFrom(injected);\n};\n\n/** Non-throwing sibling of \\`loadDeployment\\` — returns \\`null\\` instead of\n *  throwing when nothing was injected. For dev-only consumers (e.g. the dev\n *  wallet) that must no-op gracefully when no stack is running. */\nexport const loadDeploymentOptional = (): LoadedDeployment | null => {\n\tconst injected = injectedDeployment();\n\tif (injected === null || injected === undefined) return null;\n\treturn loadedFrom(injected);\n};\n\n/** The DEV-only account name → address map off the injected envelope.\n *  Accounts are network-AGNOSTIC dev identities (envelope-level, never\n *  per-network), injected only when running THROUGH devstack. Returns \\`{}\\`\n *  — without throwing — when no deployment was injected or none carries\n *  accounts (a pure prod build), so a dev-only consumer (e.g. the dev\n *  wallet) no-ops gracefully. */\nexport const resolveAccounts = (): { readonly [name: string]: string } => {\n\tconst injected = injectedDeployment();\n\treturn injected?.accounts ?? {};\n};\n\n/** Resolve a package id for an MVR placeholder off a loaded deployment.\n *  Throws when the id is missing or unresolved. */\nexport const requireId = (deployment: NetworkDeployment, mvrPlaceholder: string): string => {\n\tconst id = deployment.mvrOverrides.packages[mvrPlaceholder];\n\tif (id === undefined || id === UNRESOLVED_ID) {\n\t\tthrow new DevstackConfigMissingError(\\`id for \"\\${mvrPlaceholder}\" is unresolved\\`);\n\t}\n\treturn id;\n};\n\n/** Resolve a generic plugin value (\\`values[namespace][key]\\`) off a loaded\n *  deployment. Throws when the value is missing or unresolved. */\nexport const requireValue = <T = unknown>(\n\tdeployment: NetworkDeployment,\n\tnamespace: string,\n\tkey: string,\n): T => {\n\tconst namespaceValues = deployment.values?.[namespace];\n\tconst value = namespaceValues === undefined ? undefined : namespaceValues[key];\n\tif (value === undefined || value === UNRESOLVED_ID) {\n\t\tthrow new DevstackConfigMissingError(\\`value \"\\${namespace}.\\${key}\" is unresolved\\`);\n\t}\n\treturn value as T;\n};\n\n/** Non-throwing sibling of \\`requireValue\\` for discovery-only fields the app\n *  gates on (returns \\`undefined\\` when missing, unresolved, or absent). */\nexport const optionalValue = <T = unknown>(\n\tdeployment: NetworkDeployment,\n\tnamespace: string,\n\tkey: string,\n): T | undefined => {\n\tconst namespaceValues = deployment.values?.[namespace];\n\tconst value = namespaceValues === undefined ? undefined : namespaceValues[key];\n\treturn value === undefined || value === UNRESOLVED_ID ? undefined : (value as T);\n};\n`;\n"],"mappings":";;AAsBA,MAAa,6BAA6B;;AAG1C,MAAa,wBAAwB"}

package/dist/orchestrators/codegen/deployment-network-file.mjs

@@ -0,0 +1,130 @@
+import { CodegenRenderError } from "./errors.mjs";
+//#region src/orchestrators/codegen/deployment-network-file.ts
+/** Canonical directory (relative to the project root) committed per-network
+*  deployments live under — the convention the Vite plugin auto-discovers. */
+const DEPLOYMENTS_DIRNAME = "deployments";
+/** The header every emitted `deployments/<net>.ts` carries. Hand-editable —
+*  this is an authoring surface — so it is NOT marked auto-generated. */
+const HEADER = [
+	"// Committed per-network deployment for a real-network deploy.",
+	"//",
+	"// Emitted by `devstack dump-deployment --network <net>` from a resolved",
+	"// stack, then committed. Hand-editable: the `satisfies AppNetworkDeployment`",
+	"// type-checks it against this app declared packages + MVR placeholders, so a",
+	"// missing or mistyped id fails `tsc`. No dev `accounts` (those ride the",
+	"// runtime envelope, never the committed authoring surface)."
+].join("\n");
+const INDENT = "	";
+const IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** A single-quoted TS string literal (prettier `singleQuote: true`). Falls
+*  back to a double-quoted literal only when the value itself contains a
+*  single quote but no double quote (prettier's own preference), else escapes
+*  within single quotes.
+*
+*  Escaping is derived from `JSON.stringify`, which already produces a valid
+*  double-quoted JS string literal for ANY input — escaping backslash, the
+*  double quote, and all control characters (newline, CR, tab, etc.) — so a
+*  `values`-channel blob with literal newlines (PEM/cert text, multi-line
+*  descriptions) can never emit an unterminated literal. The result is then
+*  rephrased into prettier's quote preference. `U+2028`/`U+2029` are valid in
+*  JS string literals (and `JSON.stringify` leaves them unescaped), but are
+*  escaped here defensively so the emitted file is robust under tools that
+*  treat them as line terminators. */
+const LINE_SEP = /* @__PURE__ */ new RegExp("\\u2028", "g");
+const PARA_SEP = /* @__PURE__ */ new RegExp("\\u2029", "g");
+const quote = (s) => {
+	const json = JSON.stringify(s).replace(LINE_SEP, "\\u2028").replace(PARA_SEP, "\\u2029");
+	if (s.includes("'") && !s.includes("\"")) return json;
+	return `'${json.slice(1, -1).replace(/\\"/g, "\"").replace(/'/g, "\\'")}'`;
+};
+const key = (k) => IDENT_RE.test(k) ? k : quote(k);
+/** Render a JSON value to a prettier-compatible, SINGLE-quoted TS literal at
+*  the given indent `depth`. The deployment value space is exactly JSON
+*  (strings/numbers/booleans/null/arrays/objects), so no function/bigint/
+*  symbol handling is needed. */
+const renderValue = (value, depth) => {
+	if (value === null) return "null";
+	const t = typeof value;
+	if (t === "string") return quote(value);
+	if (t === "number" || t === "boolean") return String(value);
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "[]";
+		return `[\n${value.map((v) => INDENT.repeat(depth) + renderValue(v, depth + 1)).join(",\n")},\n${INDENT.repeat(depth - 1)}]`;
+	}
+	if (t === "object") {
+		const obj = value;
+		const keys = Object.keys(obj).sort();
+		if (keys.length === 0) return "{}";
+		return `{\n${keys.map((k) => `${INDENT.repeat(depth)}${key(k)}: ${renderValue(obj[k], depth + 1)}`).join(",\n")},\n${INDENT.repeat(depth - 1)}}`;
+	}
+	throw new CodegenRenderError({
+		emitterName: "dump-deployment",
+		outputPath: `${DEPLOYMENTS_DIRNAME}/<net>.ts`,
+		detail: `value of type ${t} is not JSON-serialisable`
+	});
+};
+/** The ordered, JSON-ish object the file body renders. Built explicitly (NOT a
+*  spread of the decoded unit) so the field order is stable and the dev-only
+*  `local` marker is dropped. Optional connection diagnostics are omitted when
+*  absent. `accounts` is structurally absent from `NetworkDeployment`, so it
+*  can never leak in.
+*
+*  Exported as the SHARED normalize seam: `dump-deployment --network`'s JSON
+*  `data` reflects this same shape (network re-derived from the arg, `local`
+*  dropped) so a `--json` consumer never sees a shape that diverges from the
+*  committed file actually written. */
+const deploymentBody = (network, unit) => {
+	const body = {
+		network,
+		rpc: unit.rpc
+	};
+	if (unit.chainId !== void 0) body.chainId = unit.chainId;
+	if (unit.faucet !== void 0) body.faucet = unit.faucet;
+	if (unit.graphql !== void 0) body.graphql = unit.graphql;
+	body.packages = unit.packages;
+	body.mvrOverrides = unit.mvrOverrides;
+	if (unit.values !== void 0) body.values = unit.values;
+	return body;
+};
+/**
+* Render a typed `deployments/<net>.ts` for `network` from its resolved
+* `NetworkDeployment` unit.
+*
+* `importPath` is the module specifier the emitted `import type` points at —
+* the app's generated `deployment.js` relative to the `deployments/` dir
+* (default `../src/generated/deployment.js`). Output is prettier-compatible
+* (tab indent, single quotes, trailing commas) so a prettier-on-write hook is
+* a no-op.
+*/
+const renderNetworkDeploymentFile = (network, unit, importPath = "../src/generated/deployment.js") => {
+	try {
+		const body = renderValue(deploymentBody(network, unit), 1);
+		return {
+			ok: true,
+			text: `${HEADER}
+
+import type { AppNetworkDeployment } from ${quote(importPath)};
+
+export const deployment = ${body} satisfies AppNetworkDeployment;
+`
+		};
+	} catch (cause) {
+		if (cause instanceof CodegenRenderError) return {
+			ok: false,
+			error: cause
+		};
+		return {
+			ok: false,
+			error: new CodegenRenderError({
+				emitterName: "dump-deployment",
+				outputPath: `${DEPLOYMENTS_DIRNAME}/${network}.ts`,
+				detail: "failed to render network deployment file",
+				cause
+			})
+		};
+	}
+};
+//#endregion
+export { DEPLOYMENTS_DIRNAME, deploymentBody, renderNetworkDeploymentFile };
+
+//# sourceMappingURL=deployment-network-file.mjs.map

package/dist/orchestrators/codegen/deployment-network-file.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-network-file.mjs","names":[],"sources":["../../../src/orchestrators/codegen/deployment-network-file.ts"],"sourcesContent":["// The typed per-network deployment file `dump-deployment --network <net>`\n// emits — a committed `deployments/<net>.ts` a prod build / dev serve loads.\n//\n// Unlike the boot-written `deployment.json` (the untyped multi-network\n// ENVELOPE), this is the SINGLE-network, hand-editable, type-checked authoring\n// surface: `export const deployment = {…} satisfies AppNetworkDeployment`. The\n// `satisfies` ties it to the app's strict generated `deployment.ts`, so a\n// missing/typo'd package id or MVR placeholder fails `tsc` against the app's\n// own `AppNetworkDeployment`.\n//\n// Sourced from one `networks.<net>` entry of the resolved envelope (the same\n// data `assembleDeployment` produces). The dev-only `accounts` are NOT part of\n// a `NetworkDeployment` (they live on the envelope), so they never appear here;\n// the `local` marker (a dev-stack flag) is also dropped — a committed\n// deployment is non-local by definition.\n//\n// This file is COMMITTED (not under `generated/`), so unlike the codegen\n// renderer (`format.ts`, double-quoted JSON literals in a prettier-IGNORED\n// tree) the output must be prettier-clean: SINGLE-quoted strings, tab indent,\n// trailing commas, sorted keys. A prettier-on-write hook is then a no-op.\n\nimport type { NetworkDeployment } from './deployment.ts';\nimport { CodegenRenderError } from './errors.ts';\n\n/** Canonical directory (relative to the project root) committed per-network\n *  deployments live under — the convention the Vite plugin auto-discovers. */\nexport const DEPLOYMENTS_DIRNAME = 'deployments';\n\n/** The header every emitted `deployments/<net>.ts` carries. Hand-editable —\n *  this is an authoring surface — so it is NOT marked auto-generated. */\nconst HEADER = [\n\t'// Committed per-network deployment for a real-network deploy.',\n\t'//',\n\t'// Emitted by `devstack dump-deployment --network <net>` from a resolved',\n\t'// stack, then committed. Hand-editable: the `satisfies AppNetworkDeployment`',\n\t'// type-checks it against this app declared packages + MVR placeholders, so a',\n\t'// missing or mistyped id fails `tsc`. No dev `accounts` (those ride the',\n\t'// runtime envelope, never the committed authoring surface).',\n].join('\\n');\n\nconst INDENT = '\\t';\nconst IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\n\n/** A single-quoted TS string literal (prettier `singleQuote: true`). Falls\n *  back to a double-quoted literal only when the value itself contains a\n *  single quote but no double quote (prettier's own preference), else escapes\n *  within single quotes.\n *\n *  Escaping is derived from `JSON.stringify`, which already produces a valid\n *  double-quoted JS string literal for ANY input — escaping backslash, the\n *  double quote, and all control characters (newline, CR, tab, etc.) — so a\n *  `values`-channel blob with literal newlines (PEM/cert text, multi-line\n *  descriptions) can never emit an unterminated literal. The result is then\n *  rephrased into prettier's quote preference. `U+2028`/`U+2029` are valid in\n *  JS string literals (and `JSON.stringify` leaves them unescaped), but are\n *  escaped here defensively so the emitted file is robust under tools that\n *  treat them as line terminators. */\n// JS line/paragraph separators: valid in string literals but treated as line\n// terminators by some tooling. Built from escape sequences so this SOURCE file\n// stays pure-ASCII (no raw separator bytes).\nconst LINE_SEP = new RegExp('\\\\u2028', 'g');\nconst PARA_SEP = new RegExp('\\\\u2029', 'g');\nconst quote = (s: string): string => {\n\t// `JSON.stringify` yields `\"…\"` with `\\\\`, `\\\"`, and all control chars\n\t// escaped; the body (sans surrounding quotes) is then a safe double-quoted\n\t// payload we can re-quote. Escape the JS line/paragraph separators too.\n\tconst json = JSON.stringify(s).replace(LINE_SEP, '\\\\u2028').replace(PARA_SEP, '\\\\u2029');\n\t// Prefer single quotes (prettier `singleQuote: true`). The JSON body escapes\n\t// `\"` as `\\\"`; to single-quote we unescape `\\\"` → `\"` and escape any literal\n\t// `'` instead. Keep the double-quoted form when the value has a single quote\n\t// but no double quote (prettier's own preference: fewer escapes).\n\tif (s.includes(\"'\") && !s.includes('\"')) return json;\n\tconst body = json.slice(1, -1).replace(/\\\\\"/g, '\"').replace(/'/g, \"\\\\'\");\n\treturn `'${body}'`;\n};\n\nconst key = (k: string): string => (IDENT_RE.test(k) ? k : quote(k));\n\n/** Render a JSON value to a prettier-compatible, SINGLE-quoted TS literal at\n *  the given indent `depth`. The deployment value space is exactly JSON\n *  (strings/numbers/booleans/null/arrays/objects), so no function/bigint/\n *  symbol handling is needed. */\nconst renderValue = (value: unknown, depth: number): string => {\n\tif (value === null) return 'null';\n\tconst t = typeof value;\n\tif (t === 'string') return quote(value as string);\n\tif (t === 'number' || t === 'boolean') return String(value);\n\tif (Array.isArray(value)) {\n\t\tif (value.length === 0) return '[]';\n\t\tconst inner = value.map((v) => INDENT.repeat(depth) + renderValue(v, depth + 1)).join(',\\n');\n\t\treturn `[\\n${inner},\\n${INDENT.repeat(depth - 1)}]`;\n\t}\n\tif (t === 'object') {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tconst keys = Object.keys(obj).sort();\n\t\tif (keys.length === 0) return '{}';\n\t\tconst lines = keys\n\t\t\t.map((k) => `${INDENT.repeat(depth)}${key(k)}: ${renderValue(obj[k], depth + 1)}`)\n\t\t\t.join(',\\n');\n\t\treturn `{\\n${lines},\\n${INDENT.repeat(depth - 1)}}`;\n\t}\n\t// `undefined` / symbol / function — not JSON. The deployment schema admits\n\t// only JSON, so this is unreachable for a schema-decoded unit; throw rather\n\t// than emit a broken file.\n\tthrow new CodegenRenderError({\n\t\temitterName: 'dump-deployment',\n\t\toutputPath: `${DEPLOYMENTS_DIRNAME}/<net>.ts`,\n\t\tdetail: `value of type ${t} is not JSON-serialisable`,\n\t});\n};\n\n/** The ordered, JSON-ish object the file body renders. Built explicitly (NOT a\n *  spread of the decoded unit) so the field order is stable and the dev-only\n *  `local` marker is dropped. Optional connection diagnostics are omitted when\n *  absent. `accounts` is structurally absent from `NetworkDeployment`, so it\n *  can never leak in.\n *\n *  Exported as the SHARED normalize seam: `dump-deployment --network`'s JSON\n *  `data` reflects this same shape (network re-derived from the arg, `local`\n *  dropped) so a `--json` consumer never sees a shape that diverges from the\n *  committed file actually written. */\nexport const deploymentBody = (\n\tnetwork: string,\n\tunit: NetworkDeployment,\n): Record<string, unknown> => {\n\tconst body: Record<string, unknown> = { network, rpc: unit.rpc };\n\tif (unit.chainId !== undefined) body.chainId = unit.chainId;\n\tif (unit.faucet !== undefined) body.faucet = unit.faucet;\n\tif (unit.graphql !== undefined) body.graphql = unit.graphql;\n\tbody.packages = unit.packages;\n\tbody.mvrOverrides = unit.mvrOverrides;\n\tif (unit.values !== undefined) body.values = unit.values;\n\treturn body;\n};\n\n/** Result of rendering — discriminated so the caller dispatches on `ok`\n *  without `instanceof` (STYLE_GUIDE §2). */\nexport type NetworkFileRenderResult =\n\t| { readonly ok: true; readonly text: string }\n\t| { readonly ok: false; readonly error: CodegenRenderError };\n\n/**\n * Render a typed `deployments/<net>.ts` for `network` from its resolved\n * `NetworkDeployment` unit.\n *\n * `importPath` is the module specifier the emitted `import type` points at —\n * the app's generated `deployment.js` relative to the `deployments/` dir\n * (default `../src/generated/deployment.js`). Output is prettier-compatible\n * (tab indent, single quotes, trailing commas) so a prettier-on-write hook is\n * a no-op.\n */\nexport const renderNetworkDeploymentFile = (\n\tnetwork: string,\n\tunit: NetworkDeployment,\n\timportPath = '../src/generated/deployment.js',\n): NetworkFileRenderResult => {\n\ttry {\n\t\tconst body = renderValue(deploymentBody(network, unit), 1);\n\t\tconst text = `${HEADER}\n\nimport type { AppNetworkDeployment } from ${quote(importPath)};\n\nexport const deployment = ${body} satisfies AppNetworkDeployment;\n`;\n\t\treturn { ok: true, text };\n\t} catch (cause) {\n\t\tif (cause instanceof CodegenRenderError) return { ok: false, error: cause };\n\t\treturn {\n\t\t\tok: false,\n\t\t\terror: new CodegenRenderError({\n\t\t\t\temitterName: 'dump-deployment',\n\t\t\t\toutputPath: `${DEPLOYMENTS_DIRNAME}/${network}.ts`,\n\t\t\t\tdetail: 'failed to render network deployment file',\n\t\t\t\tcause,\n\t\t\t}),\n\t\t};\n\t}\n};\n"],"mappings":";;;;AA0BA,MAAa,sBAAsB;;;AAInC,MAAM,SAAS;CACd;CACA;CACA;CACA;CACA;CACA;CACA;AACD,CAAC,CAAC,KAAK,IAAI;AAEX,MAAM,SAAS;AACf,MAAM,WAAW;;;;;;;;;;;;;;;AAmBjB,MAAM,2BAAW,IAAI,OAAO,WAAW,GAAG;AAC1C,MAAM,2BAAW,IAAI,OAAO,WAAW,GAAG;AAC1C,MAAM,SAAS,MAAsB;CAIpC,MAAM,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,UAAU,SAAS,CAAC,CAAC,QAAQ,UAAU,SAAS;CAKvF,IAAI,EAAE,SAAS,GAAG,KAAK,CAAC,EAAE,SAAS,IAAG,GAAG,OAAO;CAEhD,OAAO,IADM,KAAK,MAAM,GAAG,EAAE,CAAC,CAAC,QAAQ,QAAQ,IAAG,CAAC,CAAC,QAAQ,MAAM,KACpD,EAAE;AACjB;AAEA,MAAM,OAAO,MAAuB,SAAS,KAAK,CAAC,IAAI,IAAI,MAAM,CAAC;;;;;AAMlE,MAAM,eAAe,OAAgB,UAA0B;CAC9D,IAAI,UAAU,MAAM,OAAO;CAC3B,MAAM,IAAI,OAAO;CACjB,IAAI,MAAM,UAAU,OAAO,MAAM,KAAe;CAChD,IAAI,MAAM,YAAY,MAAM,WAAW,OAAO,OAAO,KAAK;CAC1D,IAAI,MAAM,QAAQ,KAAK,GAAG;EACzB,IAAI,MAAM,WAAW,GAAG,OAAO;EAE/B,OAAO,MADO,MAAM,KAAK,MAAM,OAAO,OAAO,KAAK,IAAI,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,KACrE,EAAE,KAAK,OAAO,OAAO,QAAQ,CAAC,EAAE;CAClD;CACA,IAAI,MAAM,UAAU;EACnB,MAAM,MAAM;EACZ,MAAM,OAAO,OAAO,KAAK,GAAG,CAAC,CAAC,KAAK;EACnC,IAAI,KAAK,WAAW,GAAG,OAAO;EAI9B,OAAO,MAHO,KACZ,KAAK,MAAM,GAAG,OAAO,OAAO,KAAK,IAAI,IAAI,CAAC,EAAE,IAAI,YAAY,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,CACjF,KAAK,KACU,EAAE,KAAK,OAAO,OAAO,QAAQ,CAAC,EAAE;CAClD;CAIA,MAAM,IAAI,mBAAmB;EAC5B,aAAa;EACb,YAAY,GAAG,oBAAoB;EACnC,QAAQ,iBAAiB,EAAE;CAC5B,CAAC;AACF;;;;;;;;;;;AAYA,MAAa,kBACZ,SACA,SAC6B;CAC7B,MAAM,OAAgC;EAAE;EAAS,KAAK,KAAK;CAAI;CAC/D,IAAI,KAAK,YAAY,KAAA,GAAW,KAAK,UAAU,KAAK;CACpD,IAAI,KAAK,WAAW,KAAA,GAAW,KAAK,SAAS,KAAK;CAClD,IAAI,KAAK,YAAY,KAAA,GAAW,KAAK,UAAU,KAAK;CACpD,KAAK,WAAW,KAAK;CACrB,KAAK,eAAe,KAAK;CACzB,IAAI,KAAK,WAAW,KAAA,GAAW,KAAK,SAAS,KAAK;CAClD,OAAO;AACR;;;;;;;;;;;AAkBA,MAAa,+BACZ,SACA,MACA,aAAa,qCACgB;CAC7B,IAAI;EACH,MAAM,OAAO,YAAY,eAAe,SAAS,IAAI,GAAG,CAAC;EAOzD,OAAO;GAAE,IAAI;GAAM,MAAA,GANH,OAAO;;4CAEmB,MAAM,UAAU,EAAE;;4BAElC,KAAK;;EAEP;CACzB,SAAS,OAAO;EACf,IAAI,iBAAiB,oBAAoB,OAAO;GAAE,IAAI;GAAO,OAAO;EAAM;EAC1E,OAAO;GACN,IAAI;GACJ,OAAO,IAAI,mBAAmB;IAC7B,aAAa;IACb,YAAY,GAAG,oBAAoB,GAAG,QAAQ;IAC9C,QAAQ;IACR;GACD,CAAC;EACF;CACD;AACD"}

package/dist/orchestrators/codegen/deployment-strict.mjs

@@ -0,0 +1,77 @@
+//#region src/orchestrators/codegen/deployment-strict.ts
+/** Output path (relative to the generated tree) of the emitted strict type. */
+const DEPLOYMENT_STRICT_OUTPUT_PATH = "deployment.ts";
+/** Render the app-specific strict deployment type from data. Pure +
+*  deterministic (stable key ordering), types-only output. */
+const renderDeploymentStrict = (input) => {
+	const { localNetworkName, packageNames, mvrPlaceholders, mvrTypeTags } = input;
+	const providedNetworks = [...new Set(input.providedNetworks)].filter((n) => n !== localNetworkName);
+	const packagesBody = packageNames.length > 0 ? packageNames.map((name) => `\treadonly ${JSON.stringify(name)}: { readonly id: string; readonly objects?: Record<string, string> };`).join("\n") : "	readonly [packageName: string]: never;";
+	const mvrPackagesBody = mvrPlaceholders.length > 0 ? mvrPlaceholders.map((mvr) => `\t\t\t${JSON.stringify(mvr)}: string;`).join("\n") : "			// (this app declares no MVR placeholders)";
+	const hasMvrTypes = mvrTypeTags.length > 0;
+	const mvrTypesBody = hasMvrTypes ? mvrTypeTags.map((tag) => `\t\t\t${JSON.stringify(tag)}: string;`).join("\n") : "";
+	const mvrTypesField = hasMvrTypes ? `\t\treadonly types: {\n${mvrTypesBody}\n\t\t} & { readonly [namedType: string]: string };` : `\t\treadonly types?: { readonly [namedType: string]: string };`;
+	const valueNamespaces = Object.keys(input.serviceValues).sort();
+	const hasServiceValues = valueNamespaces.length > 0;
+	const valuesBody = hasServiceValues ? valueNamespaces.map((ns) => {
+		const fields = Object.keys(input.serviceValues[ns]).sort().map((k) => `\t\t\t${JSON.stringify(k)}: ${input.serviceValues[ns][k]};`).join("\n");
+		return `\t\t${JSON.stringify(ns)}: {\n${fields}\n\t\t};`;
+	}).join("\n") : "";
+	return `// THIS FILE IS AUTO-GENERATED BY @mysten/devstack.
+// Do not edit by hand — your changes will be overwritten by the next
+// \`devstack codegen\`. Apps consume codegen output; codegen output never
+// imports from devstack.
+//
+// The APP-SPECIFIC strict deployment type. A prod author writes a
+// \`deployments/<net>.ts\` that \`satisfies AppNetworkDeployment\` — the type
+// is exhaustive over this app's declared packages + MVR placeholders, so a
+// missing/typo'd id fails \`tsc\`. The live network set
+// (\`ProvidedNetwork\` / \`NETWORK_NAMES\`) is derived from the
+// \`deployments/*.ts\` filenames. Types-only — zero runtime — except the
+// \`NETWORK_NAMES\` literal tuple (for dapp-kit's typed \`switchNetwork\`).
+
+import type { NetworkDeployment } from './config-runtime.js';
+
+/** Exhaustive over THIS app's declared package names. */
+export interface AppPackages {
+${packagesBody}
+}
+
+/** The per-network shape a prod author hand-writes in
+ *  \`deployments/<net>.ts\`: a \`NetworkDeployment\` narrowed so \`packages\` is
+ *  exhaustive over this app's packages, \`mvrOverrides\` is the @mysten MVR
+ *  override surface (\`{ packages, types }\`) requiring every declared
+ *  \`@local/<slug>\` placeholder + named-type tag, and \`values\` requires every
+ *  service value namespace/key (when the app declares any). NO \`accounts\` —
+ *  dev accounts ride the runtime envelope, never the per-network authoring
+ *  surface. */
+export interface AppNetworkDeployment
+	extends Omit<NetworkDeployment, 'packages' | 'mvrOverrides' | 'values'> {
+	readonly packages: AppPackages;
+	readonly mvrOverrides: {
+		readonly packages: {
+${mvrPackagesBody}
+		} & { readonly [mvrPlaceholder: string]: string };
+${mvrTypesField}
+	};
+${hasServiceValues ? `\treadonly values: {\n${valuesBody}\n\t} & {\n\t\treadonly [namespace: string]: { readonly [key: string]: unknown };\n\t};` : `\treadonly values?: NetworkDeployment['values'];`}
+}
+
+/** The LIVE network names this app ships — the \`deployments/*.ts\` filenames
+ *  (local excluded). \`never\` when the app ships no committed deployments. */
+export type ProvidedNetwork = ${providedNetworks.length > 0 ? providedNetworks.map((n) => JSON.stringify(n)).join(" | ") : "never"};
+
+/** The committed per-network deployments map a prod build / dev serve loads.
+ *  Partial — an app need not ship every live network at once. */
+export type ProvidedDeployments = Partial<Record<ProvidedNetwork, AppNetworkDeployment>>;
+
+/** The full network-name set, local-first: \`[<local>, ...<provided>]\`.
+ *  dapp-kit's \`networks\` / \`switchNetwork\` type-check against this tuple
+ *  (D2). */
+export const NETWORK_NAMES = [${[localNetworkName, ...providedNetworks].map((n) => JSON.stringify(n)).join(", ")}] as const;
+`;
+};
+//#endregion
+export { DEPLOYMENT_STRICT_OUTPUT_PATH, renderDeploymentStrict };
+
+//# sourceMappingURL=deployment-strict.mjs.map