@open-mercato/cli 0.7.0 → 0.7.1-develop.7103.1.41ff100d93

package/dist/lib/generators/route-manifest-shards.js

@@ -15,10 +15,13 @@ function getRouteManifestShardKey(kind, pathname) {
   }
   return firstSegment.toLowerCase();
 }
+function indentDeclaration(declaration) {
+  return declaration.split("\n").map((line) => line.length > 0 ? `  ${line}` : line).join("\n");
+}
 function renderArray(entries) {
   if (entries.length === 0) return "[]";
   return `[
-${entries.map((entry) => `  ${entry.declaration}`).join(",\n")}
+${entries.map((entry) => indentDeclaration(entry.declaration)).join(",\n")}
 ]`;
 }
 function uniqueImports(entries) {

package/dist/lib/generators/route-manifest-shards.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/generators/route-manifest-shards.ts"],
-  "sourcesContent": ["export type RouteManifestShardKind = 'api' | 'backend'\n\nexport type RouteManifestShardEntry = {\n  path: string\n  declaration: string\n  imports?: string[]\n}\n\nexport type RouteManifestShardOutput = {\n  fileName: string\n  content: string\n}\n\ntype IndexedRouteManifestShardEntry = RouteManifestShardEntry & {\n  order: number\n}\n\nconst DYNAMIC_SHARD_KEY = '__dynamic'\nconst ROOT_SHARD_KEY = '__root'\n\nfunction normalizeRoutePath(kind: RouteManifestShardKind, pathname: string): string[] {\n  const segments = pathname.split('?')[0].split('/').filter(Boolean)\n  if (kind === 'backend' && segments[0]?.toLowerCase() === 'backend') {\n    segments.shift()\n  }\n  return segments\n}\n\nexport function getRouteManifestShardKey(kind: RouteManifestShardKind, pathname: string): string {\n  const firstSegment = normalizeRoutePath(kind, pathname)[0]\n  if (!firstSegment) return ROOT_SHARD_KEY\n  if (\n    firstSegment.startsWith('[')\n    || firstSegment.startsWith(':')\n    || firstSegment === '*'\n  ) {\n    return DYNAMIC_SHARD_KEY\n  }\n  return firstSegment.toLowerCase()\n}\n\nfunction renderArray(entries: RouteManifestShardEntry[]): string {\n  if (entries.length === 0) return '[]'\n  return `[\\n${entries.map((entry) => `  ${entry.declaration}`).join(',\\n')}\\n]`\n}\n\nfunction uniqueImports(entries: RouteManifestShardEntry[]): string[] {\n  return Array.from(new Set(entries.flatMap((entry) => entry.imports ?? [])))\n}\n\nfunction shardStem(kind: RouteManifestShardKind, index: number, key: string): string {\n  const safeKey = key.replace(/[^a-zA-Z0-9_-]/g, '_')\n  return `${kind}-route-shard.${String(index).padStart(3, '0')}.${safeKey}.generated`\n}\n\nfunction renderShardFile(kind: RouteManifestShardKind, entries: IndexedRouteManifestShardEntry[]): string {\n  const typeName = kind === 'api' ? 'ApiRouteManifestEntry' : 'BackendRouteManifestEntry'\n  const helperImport = kind === 'backend' ? 'resolvePageRouteMetadata, ' : ''\n  const imports = uniqueImports(entries)\n  return `// AUTO-GENERATED by mercato generate registry (request-scoped route shard)\\nimport { ${helperImport}type ${typeName} } from '@open-mercato/shared/modules/registry'\\n${imports.length ? `${imports.join('\\n')}\\n` : ''}\\nexport const routes: ${typeName}[] = ${renderArray(entries)}\\nexport const routeOrders = [${entries.map((entry) => entry.order).join(', ')}]\\n\\nexport default routes\\n`\n}\n\nfunction renderLoaderFile(\n  kind: RouteManifestShardKind,\n  shards: Array<{ key: string; stem: string; orders: number[] }>,\n): string {\n  const isApi = kind === 'api'\n  const typeName = kind === 'api' ? 'ApiRouteManifestEntry' : 'BackendRouteManifestEntry'\n  const functionName = kind === 'api' ? 'loadApiRouteManifestShard' : 'loadBackendRouteManifestShard'\n  const ordinalFunctionName = isApi ? 'loadApiRouteManifestByOrdinal' : 'loadBackendRouteManifestByOrdinal'\n  const facadeExportName = isApi ? 'apiRouteFacades' : 'backendRouteFacades'\n  const metadataExportName = isApi ? 'apiRouteMetadata' : 'backendRouteMetadata'\n  const metadataFileName = isApi ? 'api-route-metadata.generated' : 'backend-route-metadata.generated'\n  const shardCases = shards\n    .map(({ key, stem }) => `    case ${JSON.stringify(key)}:\\n      return import('./${stem}').then((entry) => ({ routes: entry.routes, routeOrders: entry.routeOrders }))`)\n    .join('\\n')\n  const hasDynamicShard = shards.some(({ key }) => key === DYNAMIC_SHARD_KEY)\n  const routeShardKeys: string[] = []\n  for (const shard of shards) {\n    for (const order of shard.orders) routeShardKeys[order] = shard.key\n  }\n  const prefixNormalization = kind === 'backend'\n    ? `  if (segments[0]?.toLowerCase() === 'backend') segments.shift()\\n`\n    : ''\n  const loadDynamic = hasDynamicShard\n    ? `  const dynamicShard = await loadShard(${JSON.stringify(DYNAMIC_SHARD_KEY)})\\n`\n    : `  const dynamicShard: LoadedRouteShard = EMPTY_SHARD\\n`\n\n  return `// AUTO-GENERATED by mercato generate registry (request-scoped route loader)\\nimport type { ${typeName} } from '@open-mercato/shared/modules/registry'\\nimport { ${metadataExportName} } from './${metadataFileName}'\\n\\ntype LoadedRouteShard = { routes: ${typeName}[]; routeOrders: number[] }\\nconst EMPTY_SHARD: LoadedRouteShard = { routes: [], routeOrders: [] }\\nconst ROUTE_SHARD_KEYS = ${JSON.stringify(routeShardKeys)}\\n\\nfunction resolveShardKey(pathname: string): string {\\n  const segments = pathname.split('?')[0].split('/').filter(Boolean)\\n${prefixNormalization}  return segments[0]?.toLowerCase() ?? ${JSON.stringify(ROOT_SHARD_KEY)}\\n}\\n\\nasync function loadShard(key: string): Promise<LoadedRouteShard> {\\n  switch (key) {\\n${shardCases ? `${shardCases}\\n` : ''}    default:\\n      return EMPTY_SHARD\\n  }\\n}\\n\\nexport async function ${ordinalFunctionName}(ordinal: number): Promise<${typeName}> {\\n  const shardKey = ROUTE_SHARD_KEYS[ordinal]\\n  if (shardKey === undefined) throw new Error('Unknown generated route manifest ordinal: ' + ordinal)\\n  const shard = await loadShard(shardKey)\\n  const index = shard.routeOrders.indexOf(ordinal)\\n  if (index < 0 || !shard.routes[index]) throw new Error('Generated route manifest ordinal is missing from its shard: ' + ordinal)\\n  return shard.routes[index]\\n}\\n\\nexport const ${facadeExportName}: ${typeName}[] = ${metadataExportName}.map((metadata, ordinal) => ({\\n  ...metadata,\\n  load: async () => {\\n    const route = await ${ordinalFunctionName}(ordinal)\\n    return route.load()\\n  },\\n}))\\n\\nexport async function ${functionName}(pathname: string): Promise<${typeName}[]> {\\n  const exactShard = await loadShard(resolveShardKey(pathname))\\n${loadDynamic}  return [\\n    ...exactShard.routes.map((route, index) => ({ route, order: exactShard.routeOrders[index] })),\\n    ...dynamicShard.routes.map((route, index) => ({ route, order: dynamicShard.routeOrders[index] })),\\n  ].sort((a, b) => a.order - b.order).map(({ route }) => route)\\n}\\n`\n}\n\nexport function renderRouteManifestShardOutputs(\n  kind: RouteManifestShardKind,\n  entries: RouteManifestShardEntry[],\n): RouteManifestShardOutput[] {\n  const grouped = new Map<string, IndexedRouteManifestShardEntry[]>()\n  for (const [order, entry] of entries.entries()) {\n    const key = getRouteManifestShardKey(kind, entry.path)\n    const existing = grouped.get(key)\n    const indexedEntry = { ...entry, order }\n    if (existing) existing.push(indexedEntry)\n    else grouped.set(key, [indexedEntry])\n  }\n\n  const sortedGroups = Array.from(grouped.entries()).sort(([a], [b]) => a.localeCompare(b))\n  const shards = sortedGroups.map(([key, shardEntries], index) => {\n    const stem = shardStem(kind, index, key)\n    return {\n      key,\n      stem,\n      orders: shardEntries.map((entry) => entry.order),\n      output: {\n        fileName: `${stem}.ts`,\n        content: renderShardFile(kind, shardEntries),\n      },\n    }\n  })\n  const loaderFileName = kind === 'api'\n    ? 'api-route-shards.generated.ts'\n    : 'backend-route-shards.generated.ts'\n\n  return [\n    ...shards.map(({ output }) => output),\n    {\n      fileName: loaderFileName,\n      content: renderLoaderFile(kind, shards),\n    },\n  ]\n}\n\nexport function renderRouteMetadataOutput(\n  kind: RouteManifestShardKind,\n  entries: RouteManifestShardEntry[],\n): RouteManifestShardOutput {\n  const isApi = kind === 'api'\n  const manifestType = isApi ? 'ApiRouteManifestEntry' : 'BackendRouteManifestEntry'\n  const metadataType = isApi ? 'ApiRouteMetadataEntry' : 'BackendRouteMetadataEntry'\n  const exportName = isApi ? 'apiRouteMetadata' : 'backendRouteMetadata'\n  const fileName = isApi ? 'api-route-metadata.generated.ts' : 'backend-route-metadata.generated.ts'\n  const helperImport = isApi ? '' : 'resolvePageRouteMetadata, '\n  const imports = uniqueImports(entries)\n  const content = `// AUTO-GENERATED by mercato generate registry (route metadata without component loaders)\\nimport { ${helperImport}type ${manifestType} } from '@open-mercato/shared/modules/registry'\\n${imports.length ? `${imports.join('\\n')}\\n` : ''}\\nexport type ${metadataType} = Omit<${manifestType}, 'load'>\\n\\nexport const ${exportName}: ${metadataType}[] = ${renderArray(entries)}\\n\\nexport default ${exportName}\\n`\n  return { fileName, content }\n}\n\nexport const routeManifestShardFilePattern = /^(?:api|backend)-route-shard\\..+\\.generated\\.(?:ts|checksum)$/\n"],
-  "mappings": "AAiBA,MAAM,oBAAoB;AAC1B,MAAM,iBAAiB;AAEvB,SAAS,mBAAmB,MAA8B,UAA4B;AACpF,QAAM,WAAW,SAAS,MAAM,GAAG,EAAE,CAAC,EAAE,MAAM,GAAG,EAAE,OAAO,OAAO;AACjE,MAAI,SAAS,aAAa,SAAS,CAAC,GAAG,YAAY,MAAM,WAAW;AAClE,aAAS,MAAM;AAAA,EACjB;AACA,SAAO;AACT;AAEO,SAAS,yBAAyB,MAA8B,UAA0B;AAC/F,QAAM,eAAe,mBAAmB,MAAM,QAAQ,EAAE,CAAC;AACzD,MAAI,CAAC,aAAc,QAAO;AAC1B,MACE,aAAa,WAAW,GAAG,KACxB,aAAa,WAAW,GAAG,KAC3B,iBAAiB,KACpB;AACA,WAAO;AAAA,EACT;AACA,SAAO,aAAa,YAAY;AAClC;AAEA,SAAS,YAAY,SAA4C;AAC/D,MAAI,QAAQ,WAAW,EAAG,QAAO;AACjC,SAAO;AAAA,EAAM,QAAQ,IAAI,CAAC,UAAU,KAAK,MAAM,WAAW,EAAE,EAAE,KAAK,KAAK,CAAC;AAAA;AAC3E;AAEA,SAAS,cAAc,SAA8C;AACnE,SAAO,MAAM,KAAK,IAAI,IAAI,QAAQ,QAAQ,CAAC,UAAU,MAAM,WAAW,CAAC,CAAC,CAAC,CAAC;AAC5E;AAEA,SAAS,UAAU,MAA8B,OAAe,KAAqB;AACnF,QAAM,UAAU,IAAI,QAAQ,mBAAmB,GAAG;AAClD,SAAO,GAAG,IAAI,gBAAgB,OAAO,KAAK,EAAE,SAAS,GAAG,GAAG,CAAC,IAAI,OAAO;AACzE;AAEA,SAAS,gBAAgB,MAA8B,SAAmD;AACxG,QAAM,WAAW,SAAS,QAAQ,0BAA0B;AAC5D,QAAM,eAAe,SAAS,YAAY,+BAA+B;AACzE,QAAM,UAAU,cAAc,OAAO;AACrC,SAAO;AAAA,WAAyF,YAAY,QAAQ,QAAQ;AAAA,EAAoD,QAAQ,SAAS,GAAG,QAAQ,KAAK,IAAI,CAAC;AAAA,IAAO,EAAE;AAAA,uBAA0B,QAAQ,QAAQ,YAAY,OAAO,CAAC;AAAA,8BAAiC,QAAQ,IAAI,CAAC,UAAU,MAAM,KAAK,EAAE,KAAK,IAAI,CAAC;AAAA;AAAA;AAAA;AAC9W;AAEA,SAAS,iBACP,MACA,QACQ;AACR,QAAM,QAAQ,SAAS;AACvB,QAAM,WAAW,SAAS,QAAQ,0BAA0B;AAC5D,QAAM,eAAe,SAAS,QAAQ,8BAA8B;AACpE,QAAM,sBAAsB,QAAQ,kCAAkC;AACtE,QAAM,mBAAmB,QAAQ,oBAAoB;AACrD,QAAM,qBAAqB,QAAQ,qBAAqB;AACxD,QAAM,mBAAmB,QAAQ,iCAAiC;AAClE,QAAM,aAAa,OAChB,IAAI,CAAC,EAAE,KAAK,KAAK,MAAM,YAAY,KAAK,UAAU,GAAG,CAAC;AAAA,yBAA6B,IAAI,gFAAgF,EACvK,KAAK,IAAI;AACZ,QAAM,kBAAkB,OAAO,KAAK,CAAC,EAAE,IAAI,MAAM,QAAQ,iBAAiB;AAC1E,QAAM,iBAA2B,CAAC;AAClC,aAAW,SAAS,QAAQ;AAC1B,eAAW,SAAS,MAAM,OAAQ,gBAAe,KAAK,IAAI,MAAM;AAAA,EAClE;AACA,QAAM,sBAAsB,SAAS,YACjC;AAAA,IACA;AACJ,QAAM,cAAc,kBAChB,0CAA0C,KAAK,UAAU,iBAAiB,CAAC;AAAA,IAC3E;AAAA;AAEJ,SAAO;AAAA,gBAA+F,QAAQ;AAAA,WAA6D,kBAAkB,cAAc,gBAAgB;AAAA;AAAA,oCAA0C,QAAQ;AAAA;AAAA,2BAAgI,KAAK,UAAU,cAAc,CAAC;AAAA;AAAA;AAAA;AAAA,EAAmI,mBAAmB,0CAA0C,KAAK,UAAU,cAAc,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA,EAAgG,aAAa,GAAG,UAAU;AAAA,IAAO,EAAE;AAAA;AAAA;AAAA;AAAA;AAAA,wBAA2E,mBAAmB,8BAA8B,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,eAAgb,gBAAgB,KAAK,QAAQ,QAAQ,kBAAkB;AAAA;AAAA;AAAA,0BAAkG,mBAAmB;AAAA;AAAA;AAAA;AAAA;AAAA,wBAA0E,YAAY,+BAA+B,QAAQ;AAAA;AAAA,EAA2E,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AACjsD;AAEO,SAAS,gCACd,MACA,SAC4B;AAC5B,QAAM,UAAU,oBAAI,IAA8C;AAClE,aAAW,CAAC,OAAO,KAAK,KAAK,QAAQ,QAAQ,GAAG;AAC9C,UAAM,MAAM,yBAAyB,MAAM,MAAM,IAAI;AACrD,UAAM,WAAW,QAAQ,IAAI,GAAG;AAChC,UAAM,eAAe,EAAE,GAAG,OAAO,MAAM;AACvC,QAAI,SAAU,UAAS,KAAK,YAAY;AAAA,QACnC,SAAQ,IAAI,KAAK,CAAC,YAAY,CAAC;AAAA,EACtC;AAEA,QAAM,eAAe,MAAM,KAAK,QAAQ,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACxF,QAAM,SAAS,aAAa,IAAI,CAAC,CAAC,KAAK,YAAY,GAAG,UAAU;AAC9D,UAAM,OAAO,UAAU,MAAM,OAAO,GAAG;AACvC,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,QAAQ,aAAa,IAAI,CAAC,UAAU,MAAM,KAAK;AAAA,MAC/C,QAAQ;AAAA,QACN,UAAU,GAAG,IAAI;AAAA,QACjB,SAAS,gBAAgB,MAAM,YAAY;AAAA,MAC7C;AAAA,IACF;AAAA,EACF,CAAC;AACD,QAAM,iBAAiB,SAAS,QAC5B,kCACA;AAEJ,SAAO;AAAA,IACL,GAAG,OAAO,IAAI,CAAC,EAAE,OAAO,MAAM,MAAM;AAAA,IACpC;AAAA,MACE,UAAU;AAAA,MACV,SAAS,iBAAiB,MAAM,MAAM;AAAA,IACxC;AAAA,EACF;AACF;AAEO,SAAS,0BACd,MACA,SAC0B;AAC1B,QAAM,QAAQ,SAAS;AACvB,QAAM,eAAe,QAAQ,0BAA0B;AACvD,QAAM,eAAe,QAAQ,0BAA0B;AACvD,QAAM,aAAa,QAAQ,qBAAqB;AAChD,QAAM,WAAW,QAAQ,oCAAoC;AAC7D,QAAM,eAAe,QAAQ,KAAK;AAClC,QAAM,UAAU,cAAc,OAAO;AACrC,QAAM,UAAU;AAAA,WAAuG,YAAY,QAAQ,YAAY;AAAA,EAAoD,QAAQ,SAAS,GAAG,QAAQ,KAAK,IAAI,CAAC;AAAA,IAAO,EAAE;AAAA,cAAiB,YAAY,WAAW,YAAY;AAAA;AAAA,eAA6B,UAAU,KAAK,YAAY,QAAQ,YAAY,OAAO,CAAC;AAAA;AAAA,iBAAsB,UAAU;AAAA;AACla,SAAO,EAAE,UAAU,QAAQ;AAC7B;AAEO,MAAM,gCAAgC;",
+  "sourcesContent": ["export type RouteManifestShardKind = 'api' | 'backend'\n\nexport type RouteManifestShardEntry = {\n  path: string\n  declaration: string\n  imports?: string[]\n}\n\nexport type RouteManifestShardOutput = {\n  fileName: string\n  content: string\n}\n\ntype IndexedRouteManifestShardEntry = RouteManifestShardEntry & {\n  order: number\n}\n\nconst DYNAMIC_SHARD_KEY = '__dynamic'\nconst ROOT_SHARD_KEY = '__root'\n\nfunction normalizeRoutePath(kind: RouteManifestShardKind, pathname: string): string[] {\n  const segments = pathname.split('?')[0].split('/').filter(Boolean)\n  if (kind === 'backend' && segments[0]?.toLowerCase() === 'backend') {\n    segments.shift()\n  }\n  return segments\n}\n\nexport function getRouteManifestShardKey(kind: RouteManifestShardKind, pathname: string): string {\n  const firstSegment = normalizeRoutePath(kind, pathname)[0]\n  if (!firstSegment) return ROOT_SHARD_KEY\n  if (\n    firstSegment.startsWith('[')\n    || firstSegment.startsWith(':')\n    || firstSegment === '*'\n  ) {\n    return DYNAMIC_SHARD_KEY\n  }\n  return firstSegment.toLowerCase()\n}\n\nfunction indentDeclaration(declaration: string): string {\n  return declaration\n    .split('\\n')\n    .map((line) => (line.length > 0 ? `  ${line}` : line))\n    .join('\\n')\n}\n\nfunction renderArray(entries: RouteManifestShardEntry[]): string {\n  if (entries.length === 0) return '[]'\n  return `[\\n${entries.map((entry) => indentDeclaration(entry.declaration)).join(',\\n')}\\n]`\n}\n\nfunction uniqueImports(entries: RouteManifestShardEntry[]): string[] {\n  return Array.from(new Set(entries.flatMap((entry) => entry.imports ?? [])))\n}\n\nfunction shardStem(kind: RouteManifestShardKind, index: number, key: string): string {\n  const safeKey = key.replace(/[^a-zA-Z0-9_-]/g, '_')\n  return `${kind}-route-shard.${String(index).padStart(3, '0')}.${safeKey}.generated`\n}\n\nfunction renderShardFile(kind: RouteManifestShardKind, entries: IndexedRouteManifestShardEntry[]): string {\n  const typeName = kind === 'api' ? 'ApiRouteManifestEntry' : 'BackendRouteManifestEntry'\n  const helperImport = kind === 'backend' ? 'resolvePageRouteMetadata, ' : ''\n  const imports = uniqueImports(entries)\n  return `// AUTO-GENERATED by mercato generate registry (request-scoped route shard)\\nimport { ${helperImport}type ${typeName} } from '@open-mercato/shared/modules/registry'\\n${imports.length ? `${imports.join('\\n')}\\n` : ''}\\nexport const routes: ${typeName}[] = ${renderArray(entries)}\\nexport const routeOrders = [${entries.map((entry) => entry.order).join(', ')}]\\n\\nexport default routes\\n`\n}\n\nfunction renderLoaderFile(\n  kind: RouteManifestShardKind,\n  shards: Array<{ key: string; stem: string; orders: number[] }>,\n): string {\n  const isApi = kind === 'api'\n  const typeName = kind === 'api' ? 'ApiRouteManifestEntry' : 'BackendRouteManifestEntry'\n  const functionName = kind === 'api' ? 'loadApiRouteManifestShard' : 'loadBackendRouteManifestShard'\n  const ordinalFunctionName = isApi ? 'loadApiRouteManifestByOrdinal' : 'loadBackendRouteManifestByOrdinal'\n  const facadeExportName = isApi ? 'apiRouteFacades' : 'backendRouteFacades'\n  const metadataExportName = isApi ? 'apiRouteMetadata' : 'backendRouteMetadata'\n  const metadataFileName = isApi ? 'api-route-metadata.generated' : 'backend-route-metadata.generated'\n  const shardCases = shards\n    .map(({ key, stem }) => `    case ${JSON.stringify(key)}:\\n      return import('./${stem}').then((entry) => ({ routes: entry.routes, routeOrders: entry.routeOrders }))`)\n    .join('\\n')\n  const hasDynamicShard = shards.some(({ key }) => key === DYNAMIC_SHARD_KEY)\n  const routeShardKeys: string[] = []\n  for (const shard of shards) {\n    for (const order of shard.orders) routeShardKeys[order] = shard.key\n  }\n  const prefixNormalization = kind === 'backend'\n    ? `  if (segments[0]?.toLowerCase() === 'backend') segments.shift()\\n`\n    : ''\n  const loadDynamic = hasDynamicShard\n    ? `  const dynamicShard = await loadShard(${JSON.stringify(DYNAMIC_SHARD_KEY)})\\n`\n    : `  const dynamicShard: LoadedRouteShard = EMPTY_SHARD\\n`\n\n  return `// AUTO-GENERATED by mercato generate registry (request-scoped route loader)\\nimport type { ${typeName} } from '@open-mercato/shared/modules/registry'\\nimport { ${metadataExportName} } from './${metadataFileName}'\\n\\ntype LoadedRouteShard = { routes: ${typeName}[]; routeOrders: number[] }\\nconst EMPTY_SHARD: LoadedRouteShard = { routes: [], routeOrders: [] }\\nconst ROUTE_SHARD_KEYS = ${JSON.stringify(routeShardKeys)}\\n\\nfunction resolveShardKey(pathname: string): string {\\n  const segments = pathname.split('?')[0].split('/').filter(Boolean)\\n${prefixNormalization}  return segments[0]?.toLowerCase() ?? ${JSON.stringify(ROOT_SHARD_KEY)}\\n}\\n\\nasync function loadShard(key: string): Promise<LoadedRouteShard> {\\n  switch (key) {\\n${shardCases ? `${shardCases}\\n` : ''}    default:\\n      return EMPTY_SHARD\\n  }\\n}\\n\\nexport async function ${ordinalFunctionName}(ordinal: number): Promise<${typeName}> {\\n  const shardKey = ROUTE_SHARD_KEYS[ordinal]\\n  if (shardKey === undefined) throw new Error('Unknown generated route manifest ordinal: ' + ordinal)\\n  const shard = await loadShard(shardKey)\\n  const index = shard.routeOrders.indexOf(ordinal)\\n  if (index < 0 || !shard.routes[index]) throw new Error('Generated route manifest ordinal is missing from its shard: ' + ordinal)\\n  return shard.routes[index]\\n}\\n\\nexport const ${facadeExportName}: ${typeName}[] = ${metadataExportName}.map((metadata, ordinal) => ({\\n  ...metadata,\\n  load: async () => {\\n    const route = await ${ordinalFunctionName}(ordinal)\\n    return route.load()\\n  },\\n}))\\n\\nexport async function ${functionName}(pathname: string): Promise<${typeName}[]> {\\n  const exactShard = await loadShard(resolveShardKey(pathname))\\n${loadDynamic}  return [\\n    ...exactShard.routes.map((route, index) => ({ route, order: exactShard.routeOrders[index] })),\\n    ...dynamicShard.routes.map((route, index) => ({ route, order: dynamicShard.routeOrders[index] })),\\n  ].sort((a, b) => a.order - b.order).map(({ route }) => route)\\n}\\n`\n}\n\nexport function renderRouteManifestShardOutputs(\n  kind: RouteManifestShardKind,\n  entries: RouteManifestShardEntry[],\n): RouteManifestShardOutput[] {\n  const grouped = new Map<string, IndexedRouteManifestShardEntry[]>()\n  for (const [order, entry] of entries.entries()) {\n    const key = getRouteManifestShardKey(kind, entry.path)\n    const existing = grouped.get(key)\n    const indexedEntry = { ...entry, order }\n    if (existing) existing.push(indexedEntry)\n    else grouped.set(key, [indexedEntry])\n  }\n\n  const sortedGroups = Array.from(grouped.entries()).sort(([a], [b]) => a.localeCompare(b))\n  const shards = sortedGroups.map(([key, shardEntries], index) => {\n    const stem = shardStem(kind, index, key)\n    return {\n      key,\n      stem,\n      orders: shardEntries.map((entry) => entry.order),\n      output: {\n        fileName: `${stem}.ts`,\n        content: renderShardFile(kind, shardEntries),\n      },\n    }\n  })\n  const loaderFileName = kind === 'api'\n    ? 'api-route-shards.generated.ts'\n    : 'backend-route-shards.generated.ts'\n\n  return [\n    ...shards.map(({ output }) => output),\n    {\n      fileName: loaderFileName,\n      content: renderLoaderFile(kind, shards),\n    },\n  ]\n}\n\nexport function renderRouteMetadataOutput(\n  kind: RouteManifestShardKind,\n  entries: RouteManifestShardEntry[],\n): RouteManifestShardOutput {\n  const isApi = kind === 'api'\n  const manifestType = isApi ? 'ApiRouteManifestEntry' : 'BackendRouteManifestEntry'\n  const metadataType = isApi ? 'ApiRouteMetadataEntry' : 'BackendRouteMetadataEntry'\n  const exportName = isApi ? 'apiRouteMetadata' : 'backendRouteMetadata'\n  const fileName = isApi ? 'api-route-metadata.generated.ts' : 'backend-route-metadata.generated.ts'\n  const helperImport = isApi ? '' : 'resolvePageRouteMetadata, '\n  const imports = uniqueImports(entries)\n  const content = `// AUTO-GENERATED by mercato generate registry (route metadata without component loaders)\\nimport { ${helperImport}type ${manifestType} } from '@open-mercato/shared/modules/registry'\\n${imports.length ? `${imports.join('\\n')}\\n` : ''}\\nexport type ${metadataType} = Omit<${manifestType}, 'load'>\\n\\nexport const ${exportName}: ${metadataType}[] = ${renderArray(entries)}\\n\\nexport default ${exportName}\\n`\n  return { fileName, content }\n}\n\nexport const routeManifestShardFilePattern = /^(?:api|backend)-route-shard\\..+\\.generated\\.(?:ts|checksum)$/\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/lib/spawn.js

@@ -21,11 +21,12 @@ function resolveSpawnCommand(command, commandArgs = [], options = {}) {
   const platform = options.platform ?? process.platform;
   const safeCommand = assertProcessSafeValue(command, "Process command");
   const safeArgs = commandArgs.map((arg, index) => assertProcessSafeValue(arg, `Process argument #${index + 1}`));
+  const detachedSpawnOptions = options.detached ? { detached: true } : {};
   if (!isWindowsCmdScript(safeCommand, platform)) {
     return {
       command: safeCommand,
       args: safeArgs,
-      spawnOptions: {}
+      spawnOptions: { ...detachedSpawnOptions }
     };
   }
   return {
@@ -33,7 +34,7 @@ function resolveSpawnCommand(command, commandArgs = [], options = {}) {
     args: safeArgs.map(
       (arg, index) => assertWindowsCmdSafeValue(arg, `Windows command argument #${index + 1}`)
     ),
-    spawnOptions: {}
+    spawnOptions: { ...detachedSpawnOptions }
   };
 }
 export {

package/dist/lib/spawn.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/spawn.ts"],
-  "sourcesContent": ["export function isWindowsCmdScript(command: string, platform = process.platform): boolean {\n  return platform === 'win32' && /\\.(cmd|bat)$/i.test(String(command))\n}\n\nconst PROCESS_VALUE_UNSAFE_CHAR_PATTERN = /[\\u0000-\\u001f\\u007f]/\nconst WINDOWS_CMD_UNSAFE_CHAR_PATTERN = /[\\u0000-\\u001f\\u007f%!]/\n\nfunction assertProcessSafeValue(value: string, label: string): string {\n  const stringValue = String(value)\n\n  if (PROCESS_VALUE_UNSAFE_CHAR_PATTERN.test(stringValue)) {\n    throw new Error(`${label} contains unsupported control characters.`)\n  }\n\n  return stringValue\n}\n\nfunction assertWindowsCmdSafeValue(value: string, label: string): string {\n  const stringValue = assertProcessSafeValue(value, label)\n\n  if (WINDOWS_CMD_UNSAFE_CHAR_PATTERN.test(stringValue)) {\n    throw new Error(`${label} contains unsupported characters for Windows command execution.`)\n  }\n\n  return stringValue\n}\n\nexport function resolveSpawnCommand(\n  command: string,\n  commandArgs: string[] = [],\n  options: { platform?: NodeJS.Platform } = {},\n): {\n  command: string\n  args: string[]\n  spawnOptions: { shell?: boolean; windowsVerbatimArguments?: boolean }\n} {\n  const platform = options.platform ?? process.platform\n  const safeCommand = assertProcessSafeValue(command, 'Process command')\n  const safeArgs = commandArgs.map((arg, index) => assertProcessSafeValue(arg, `Process argument #${index + 1}`))\n\n  if (!isWindowsCmdScript(safeCommand, platform)) {\n    return {\n      command: safeCommand,\n      args: safeArgs,\n      spawnOptions: {},\n    }\n  }\n\n  return {\n    command: assertWindowsCmdSafeValue(safeCommand, 'Windows command path'),\n    args: safeArgs.map((arg, index) =>\n      assertWindowsCmdSafeValue(arg, `Windows command argument #${index + 1}`),\n    ),\n    spawnOptions: {},\n  }\n}\n"],
-  "mappings": "AAAO,SAAS,mBAAmB,SAAiB,WAAW,QAAQ,UAAmB;AACxF,SAAO,aAAa,WAAW,gBAAgB,KAAK,OAAO,OAAO,CAAC;AACrE;AAEA,MAAM,oCAAoC;AAC1C,MAAM,kCAAkC;AAExC,SAAS,uBAAuB,OAAe,OAAuB;AACpE,QAAM,cAAc,OAAO,KAAK;AAEhC,MAAI,kCAAkC,KAAK,WAAW,GAAG;AACvD,UAAM,IAAI,MAAM,GAAG,KAAK,2CAA2C;AAAA,EACrE;AAEA,SAAO;AACT;AAEA,SAAS,0BAA0B,OAAe,OAAuB;AACvE,QAAM,cAAc,uBAAuB,OAAO,KAAK;AAEvD,MAAI,gCAAgC,KAAK,WAAW,GAAG;AACrD,UAAM,IAAI,MAAM,GAAG,KAAK,iEAAiE;AAAA,EAC3F;AAEA,SAAO;AACT;AAEO,SAAS,oBACd,SACA,cAAwB,CAAC,GACzB,UAA0C,CAAC,GAK3C;AACA,QAAM,WAAW,QAAQ,YAAY,QAAQ;AAC7C,QAAM,cAAc,uBAAuB,SAAS,iBAAiB;AACrE,QAAM,WAAW,YAAY,IAAI,CAAC,KAAK,UAAU,uBAAuB,KAAK,qBAAqB,QAAQ,CAAC,EAAE,CAAC;AAE9G,MAAI,CAAC,mBAAmB,aAAa,QAAQ,GAAG;AAC9C,WAAO;AAAA,MACL,SAAS;AAAA,MACT,MAAM;AAAA,MACN,cAAc,CAAC;AAAA,IACjB;AAAA,EACF;AAEA,SAAO;AAAA,IACL,SAAS,0BAA0B,aAAa,sBAAsB;AAAA,IACtE,MAAM,SAAS;AAAA,MAAI,CAAC,KAAK,UACvB,0BAA0B,KAAK,6BAA6B,QAAQ,CAAC,EAAE;AAAA,IACzE;AAAA,IACA,cAAc,CAAC;AAAA,EACjB;AACF;",
+  "sourcesContent": ["export function isWindowsCmdScript(command: string, platform = process.platform): boolean {\n  return platform === 'win32' && /\\.(cmd|bat)$/i.test(String(command))\n}\n\nconst PROCESS_VALUE_UNSAFE_CHAR_PATTERN = /[\\u0000-\\u001f\\u007f]/\nconst WINDOWS_CMD_UNSAFE_CHAR_PATTERN = /[\\u0000-\\u001f\\u007f%!]/\n\nfunction assertProcessSafeValue(value: string, label: string): string {\n  const stringValue = String(value)\n\n  if (PROCESS_VALUE_UNSAFE_CHAR_PATTERN.test(stringValue)) {\n    throw new Error(`${label} contains unsupported control characters.`)\n  }\n\n  return stringValue\n}\n\nfunction assertWindowsCmdSafeValue(value: string, label: string): string {\n  const stringValue = assertProcessSafeValue(value, label)\n\n  if (WINDOWS_CMD_UNSAFE_CHAR_PATTERN.test(stringValue)) {\n    throw new Error(`${label} contains unsupported characters for Windows command execution.`)\n  }\n\n  return stringValue\n}\n\nexport function resolveSpawnCommand(\n  command: string,\n  commandArgs: string[] = [],\n  options: { platform?: NodeJS.Platform; detached?: boolean } = {},\n): {\n  command: string\n  args: string[]\n  spawnOptions: { shell?: boolean; windowsVerbatimArguments?: boolean; detached?: boolean }\n} {\n  const platform = options.platform ?? process.platform\n  const safeCommand = assertProcessSafeValue(command, 'Process command')\n  const safeArgs = commandArgs.map((arg, index) => assertProcessSafeValue(arg, `Process argument #${index + 1}`))\n  const detachedSpawnOptions = options.detached ? { detached: true } : {}\n\n  if (!isWindowsCmdScript(safeCommand, platform)) {\n    return {\n      command: safeCommand,\n      args: safeArgs,\n      spawnOptions: { ...detachedSpawnOptions },\n    }\n  }\n\n  return {\n    command: assertWindowsCmdSafeValue(safeCommand, 'Windows command path'),\n    args: safeArgs.map((arg, index) =>\n      assertWindowsCmdSafeValue(arg, `Windows command argument #${index + 1}`),\n    ),\n    spawnOptions: { ...detachedSpawnOptions },\n  }\n}\n"],
+  "mappings": "AAAO,SAAS,mBAAmB,SAAiB,WAAW,QAAQ,UAAmB;AACxF,SAAO,aAAa,WAAW,gBAAgB,KAAK,OAAO,OAAO,CAAC;AACrE;AAEA,MAAM,oCAAoC;AAC1C,MAAM,kCAAkC;AAExC,SAAS,uBAAuB,OAAe,OAAuB;AACpE,QAAM,cAAc,OAAO,KAAK;AAEhC,MAAI,kCAAkC,KAAK,WAAW,GAAG;AACvD,UAAM,IAAI,MAAM,GAAG,KAAK,2CAA2C;AAAA,EACrE;AAEA,SAAO;AACT;AAEA,SAAS,0BAA0B,OAAe,OAAuB;AACvE,QAAM,cAAc,uBAAuB,OAAO,KAAK;AAEvD,MAAI,gCAAgC,KAAK,WAAW,GAAG;AACrD,UAAM,IAAI,MAAM,GAAG,KAAK,iEAAiE;AAAA,EAC3F;AAEA,SAAO;AACT;AAEO,SAAS,oBACd,SACA,cAAwB,CAAC,GACzB,UAA8D,CAAC,GAK/D;AACA,QAAM,WAAW,QAAQ,YAAY,QAAQ;AAC7C,QAAM,cAAc,uBAAuB,SAAS,iBAAiB;AACrE,QAAM,WAAW,YAAY,IAAI,CAAC,KAAK,UAAU,uBAAuB,KAAK,qBAAqB,QAAQ,CAAC,EAAE,CAAC;AAC9G,QAAM,uBAAuB,QAAQ,WAAW,EAAE,UAAU,KAAK,IAAI,CAAC;AAEtE,MAAI,CAAC,mBAAmB,aAAa,QAAQ,GAAG;AAC9C,WAAO;AAAA,MACL,SAAS;AAAA,MACT,MAAM;AAAA,MACN,cAAc,EAAE,GAAG,qBAAqB;AAAA,IAC1C;AAAA,EACF;AAEA,SAAO;AAAA,IACL,SAAS,0BAA0B,aAAa,sBAAsB;AAAA,IACtE,MAAM,SAAS;AAAA,MAAI,CAAC,KAAK,UACvB,0BAA0B,KAAK,6BAA6B,QAAQ,CAAC,EAAE;AAAA,IACzE;AAAA,IACA,cAAc,EAAE,GAAG,qBAAqB;AAAA,EAC1C;AACF;",
   "names": []
 }

package/dist/lib/testing/integration.js

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { createServer } from "node:net";
 import { existsSync, readFileSync } from "node:fs";
 import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
@@ -452,9 +453,31 @@ function runNpxCommand(args, environment) {
     });
   });
 }
+const CAPTURED_OUTPUT_MAX_LENGTH = 64 * 1024;
+function createBoundedOutputBuffer() {
+  let buffered = "";
+  return {
+    append: (chunk) => {
+      buffered += chunk.toString();
+      if (buffered.length > CAPTURED_OUTPUT_MAX_LENGTH) {
+        buffered = `\u2026(truncated)\u2026${buffered.slice(-CAPTURED_OUTPUT_MAX_LENGTH)}`;
+      }
+    },
+    read: () => buffered
+  };
+}
+function formatCapturedOutput(stderrText, stdoutText) {
+  if (stderrText && stdoutText) {
+    return `--- stderr ---
+${stderrText}
+--- stdout ---
+${stdoutText}`;
+  }
+  return stderrText || stdoutText;
+}
 function startYarnRawCommand(commandArgs, environment, opts = {}, cwd = projectRootDirectory) {
   const outputMode = opts.silent ? ["ignore", "pipe", "pipe"] : "inherit";
-  const resolvedSpawn = resolveSpawnCommand(resolveYarnBinary(), commandArgs);
+  const resolvedSpawn = resolveSpawnCommand(resolveYarnBinary(), commandArgs, { detached: opts.detached });
   const processHandle = spawn(resolvedSpawn.command, resolvedSpawn.args, {
     cwd,
     env: environment,
@@ -462,10 +485,11 @@ function startYarnRawCommand(commandArgs, environment, opts = {}, cwd = projectR
     ...resolvedSpawn.spawnOptions
   });
   if (opts.silent) {
-    processHandle.stdout?.on("data", () => {
-    });
-    processHandle.stderr?.on("data", () => {
-    });
+    const stdoutBuffer = createBoundedOutputBuffer();
+    const stderrBuffer = createBoundedOutputBuffer();
+    processHandle.stdout?.on("data", (chunk) => stdoutBuffer.append(chunk));
+    processHandle.stderr?.on("data", (chunk) => stderrBuffer.append(chunk));
+    processHandle.readCapturedOutput = () => formatCapturedOutput(stderrBuffer.read().trim(), stdoutBuffer.read().trim());
   }
   return processHandle;
 }
@@ -1305,6 +1329,97 @@ function isProcessRunning(processId) {
     return error.code !== "ESRCH";
   }
 }
+function defaultKillPosixProcessGroup(pid, signal) {
+  process.kill(-pid, signal);
+}
+function defaultKillWindowsProcessTree(pid, options) {
+  spawnSync("taskkill", ["/pid", String(pid), "/t", ...options.forced ? ["/f"] : []]);
+}
+function killProcessTree(pid, signal, dependencies = {}) {
+  const platform = dependencies.platform ?? process.platform;
+  if (platform === "win32") {
+    const killWindowsProcessTree = dependencies.killWindowsProcessTree ?? defaultKillWindowsProcessTree;
+    killWindowsProcessTree(pid, { forced: signal === "SIGKILL" });
+    return;
+  }
+  const killPosixProcessGroup = dependencies.killPosixProcessGroup ?? defaultKillPosixProcessGroup;
+  killPosixProcessGroup(pid, signal);
+}
+const PROCESS_TREE_KILL_GRACE_PERIOD_MS = 3e3;
+function killProcessTreeIfRunning(pid, signal, dependencies) {
+  try {
+    killProcessTree(pid, signal, dependencies);
+  } catch (error) {
+    if (error.code !== "ESRCH") {
+      throw error;
+    }
+  }
+}
+function waitForProcessExitWithin(childProcess, timeoutMs) {
+  return new Promise((resolve) => {
+    const settle = (exited) => {
+      clearTimeout(gracePeriodTimer);
+      childProcess.off("exit", onExit);
+      childProcess.off("error", onError);
+      resolve(exited);
+    };
+    const onExit = () => settle(true);
+    const onError = () => settle(false);
+    const gracePeriodTimer = setTimeout(() => settle(false), timeoutMs);
+    childProcess.on("exit", onExit);
+    childProcess.on("error", onError);
+  });
+}
+function hasProcessAlreadyExited(childProcess) {
+  return (childProcess.exitCode ?? null) !== null || (childProcess.signalCode ?? null) !== null;
+}
+async function terminateProcessTree(childProcess, dependencies = {}) {
+  const pid = childProcess.pid;
+  if (!pid) return;
+  if (hasProcessAlreadyExited(childProcess)) {
+    killProcessTreeIfRunning(pid, "SIGKILL", dependencies);
+    return;
+  }
+  killProcessTreeIfRunning(pid, "SIGTERM", dependencies);
+  const gracePeriodMs = dependencies.gracePeriodMs ?? PROCESS_TREE_KILL_GRACE_PERIOD_MS;
+  const exitedBeforeGracePeriod = await waitForProcessExitWithin(childProcess, gracePeriodMs);
+  if (!exitedBeforeGracePeriod && isProcessRunning(pid)) {
+    killProcessTreeIfRunning(pid, "SIGKILL", dependencies);
+  }
+}
+const EPHEMERAL_SHUTDOWN_SIGNALS = ["SIGINT", "SIGTERM"];
+function registerEphemeralShutdownHandlers(options) {
+  const processRef = options.processRef ?? process;
+  const onProcessExit = () => options.killApplicationTree();
+  const signalHandlers = /* @__PURE__ */ new Map();
+  const dispose = () => {
+    processRef.off("exit", onProcessExit);
+    for (const [signal, handler] of signalHandlers) {
+      processRef.off(signal, handler);
+    }
+    signalHandlers.clear();
+  };
+  for (const signal of EPHEMERAL_SHUTDOWN_SIGNALS) {
+    const handler = () => {
+      void (async () => {
+        options.onSignal?.(signal);
+        try {
+          await options.stop();
+        } catch (error) {
+          console.error(`Failed to stop the ephemeral environment on ${signal}:`, error);
+        } finally {
+          dispose();
+          processRef.removeAllListeners(signal);
+          processRef.kill(processRef.pid, signal);
+        }
+      })();
+    };
+    signalHandlers.set(signal, handler);
+    processRef.once(signal, handler);
+  }
+  processRef.once("exit", onProcessExit);
+  return { dispose };
+}
 async function getPathAgeMilliseconds(targetPath) {
   try {
     const stats = await stat(targetPath);
@@ -1595,7 +1710,15 @@ async function waitForApplicationReadiness(baseUrl, appProcess, options) {
       return { exited: true };
     }
   );
-  const exitError = () => new Error(`Application process exited before readiness check (exit ${exitCode ?? "unknown"})`);
+  const exitError = () => {
+    const capturedOutput = appProcess.readCapturedOutput?.().trim();
+    const capturedOutputTail = capturedOutput ? `
+Captured output:
+${capturedOutput.split("\n").slice(-20).join("\n")}` : "";
+    return new Error(
+      `Application process exited before readiness check (exit ${exitCode ?? "unknown"})${capturedOutputTail}`
+    );
+  };
   while (Date.now() - startTimestamp < options.timeoutMs) {
     const cycle = await Promise.race([
       probeApplicationReadiness(baseUrl).then((probe) => ({ probe })),
@@ -2736,19 +2859,40 @@ async function startEphemeralEnvironment(options) {
     const runtimeLock = await acquireEphemeralRuntimeLock(options.logPrefix);
     let applicationProcess = null;
     let isStopped = false;
+    let shutdownHandlers = null;
     const stop = async () => {
       if (isStopped) return;
       isStopped = true;
       try {
         if (applicationProcess && !applicationProcess.killed) {
-          applicationProcess.kill("SIGTERM");
+          try {
+            await terminateProcessTree(applicationProcess);
+          } catch (error) {
+            console.error(`[${options.logPrefix}] Failed to terminate the application process tree:`, error);
+          }
         }
         await databaseContainer.stop();
         await clearEphemeralEnvironmentState();
       } finally {
         await runtimeLock.release();
+        shutdownHandlers?.dispose();
       }
     };
+    shutdownHandlers = registerEphemeralShutdownHandlers({
+      stop,
+      onSignal: (signal) => console.log(`[${options.logPrefix}] Received ${signal}, stopping ephemeral environment...`),
+      // Deliberately not guarded on `isStopped`: `startEphemeralEnvironment`'s own catch already ran
+      // `stop()` before rethrowing, so the guard made the sweep dead on exactly the paths that need
+      // it. After a successful `stop()` the extra group kill is a harmless `ESRCH` this swallows.
+      killApplicationTree: () => {
+        const pid = applicationProcess?.pid;
+        if (!pid) return;
+        try {
+          killProcessTree(pid, "SIGKILL");
+        } catch {
+        }
+      }
+    });
     try {
       const appReadyTimeoutMs = resolveAppReadyTimeoutMs(options.logPrefix);
       const buildCacheTtlSeconds = resolveBuildCacheTtlSeconds(options.logPrefix);
@@ -2818,7 +2962,8 @@ async function startEphemeralEnvironment(options) {
       }
       console.log(`[${options.logPrefix}] Starting application on ${applicationBaseUrl}...`);
       const startedAppProcess = startYarnCommand(["start"], commandEnvironment, {
-        silent: !options.verbose
+        silent: !options.verbose,
+        detached: true
       }, appDirectory);
       applicationProcess = startedAppProcess;
       await runTimedStep(
@@ -2854,14 +2999,7 @@ async function startEphemeralEnvironment(options) {
     await setupLock.release();
   }
 }
-async function keepEnvironmentRunningForever(options) {
-  const onSignal = async (signal) => {
-    console.log(`[${options.logPrefix}] Received ${signal}, stopping ephemeral environment...`);
-    await options.stop();
-    process.exit(0);
-  };
-  process.once("SIGINT", () => void onSignal("SIGINT"));
-  process.once("SIGTERM", () => void onSignal("SIGTERM"));
+async function keepEnvironmentRunningForever() {
   await new Promise(() => {
   });
 }
@@ -2907,10 +3045,7 @@ async function runIntegrationTestsInEphemeralEnvironment(rawArgs) {
     }
     if (options.keep) {
       console.log("[integration] --keep enabled: leaving app and database running. Press Ctrl+C to stop.");
-      await keepEnvironmentRunningForever({
-        logPrefix: "integration",
-        stop: environment.stop
-      });
+      await keepEnvironmentRunningForever();
     }
   } finally {
     if (!options.keep) {
@@ -2935,10 +3070,7 @@ async function runEphemeralAppForQa(rawArgs) {
   } else {
     console.log("[ephemeral] Reused existing environment. Press Ctrl+C to exit without stopping the shared runtime.");
   }
-  await keepEnvironmentRunningForever({
-    logPrefix: "ephemeral",
-    stop: environment.stop
-  });
+  await keepEnvironmentRunningForever();
 }
 async function runInteractiveIntegrationInEphemeralEnvironment(rawArgs) {
   const options = parseInteractiveIntegrationOptions(rawArgs);
@@ -3085,14 +3217,19 @@ async function runInteractiveIntegrationInEphemeralEnvironment(rawArgs) {
   }
 }
 export {
+  CAPTURED_OUTPUT_MAX_LENGTH,
   acquireEphemeralRuntimeLock,
   clearEphemeralEnvironmentState,
+  createBoundedOutputBuffer,
   ephemeralPostgresInitSql,
+  formatCapturedOutput,
+  killProcessTree,
   parseEphemeralAppOptions,
   parseIntegrationCoverageOptions,
   parseInteractiveIntegrationOptions,
   parseOptions,
   readEphemeralEnvironmentState,
+  registerEphemeralShutdownHandlers,
   resolveAppReadyTimeoutMs,
   resolveBuildCacheTtlSeconds,
   resolveEphemeralPostgresImage,
@@ -3105,6 +3242,7 @@ export {
   shouldReuseBuildArtifacts,
   shouldUseIsolatedPortForFreshEnvironment,
   startEphemeralEnvironment,
+  terminateProcessTree,
   tryReuseExistingEnvironment,
   waitForApplicationReadiness,
   writeEphemeralEnvironmentState