@open-mercato/cli 0.6.8-develop.6889.1.af4501ca97 → 0.6.8-develop.6892.1.f179677788

package/src/lib/generators/route-manifest-shards.ts

@@ -0,0 +1,146 @@
+export type RouteManifestShardKind = 'api' | 'backend'
+
+export type RouteManifestShardEntry = {
+  path: string
+  declaration: string
+  imports?: string[]
+}
+
+export type RouteManifestShardOutput = {
+  fileName: string
+  content: string
+}
+
+type IndexedRouteManifestShardEntry = RouteManifestShardEntry & {
+  order: number
+}
+
+const DYNAMIC_SHARD_KEY = '__dynamic'
+const ROOT_SHARD_KEY = '__root'
+
+function normalizeRoutePath(kind: RouteManifestShardKind, pathname: string): string[] {
+  const segments = pathname.split('?')[0].split('/').filter(Boolean)
+  if (kind === 'backend' && segments[0]?.toLowerCase() === 'backend') {
+    segments.shift()
+  }
+  return segments
+}
+
+export function getRouteManifestShardKey(kind: RouteManifestShardKind, pathname: string): string {
+  const firstSegment = normalizeRoutePath(kind, pathname)[0]
+  if (!firstSegment) return ROOT_SHARD_KEY
+  if (
+    firstSegment.startsWith('[')
+    || firstSegment.startsWith(':')
+    || firstSegment === '*'
+  ) {
+    return DYNAMIC_SHARD_KEY
+  }
+  return firstSegment.toLowerCase()
+}
+
+function renderArray(entries: RouteManifestShardEntry[]): string {
+  if (entries.length === 0) return '[]'
+  return `[\n${entries.map((entry) => `  ${entry.declaration}`).join(',\n')}\n]`
+}
+
+function uniqueImports(entries: RouteManifestShardEntry[]): string[] {
+  return Array.from(new Set(entries.flatMap((entry) => entry.imports ?? [])))
+}
+
+function shardStem(kind: RouteManifestShardKind, index: number, key: string): string {
+  const safeKey = key.replace(/[^a-zA-Z0-9_-]/g, '_')
+  return `${kind}-route-shard.${String(index).padStart(3, '0')}.${safeKey}.generated`
+}
+
+function renderShardFile(kind: RouteManifestShardKind, entries: IndexedRouteManifestShardEntry[]): string {
+  const typeName = kind === 'api' ? 'ApiRouteManifestEntry' : 'BackendRouteManifestEntry'
+  const helperImport = kind === 'backend' ? 'resolvePageRouteMetadata, ' : ''
+  const imports = uniqueImports(entries)
+  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`
+}
+
+function renderLoaderFile(
+  kind: RouteManifestShardKind,
+  shards: Array<{ key: string; stem: string; orders: number[] }>,
+): string {
+  const isApi = kind === 'api'
+  const typeName = kind === 'api' ? 'ApiRouteManifestEntry' : 'BackendRouteManifestEntry'
+  const functionName = kind === 'api' ? 'loadApiRouteManifestShard' : 'loadBackendRouteManifestShard'
+  const ordinalFunctionName = isApi ? 'loadApiRouteManifestByOrdinal' : 'loadBackendRouteManifestByOrdinal'
+  const facadeExportName = isApi ? 'apiRouteFacades' : 'backendRouteFacades'
+  const metadataExportName = isApi ? 'apiRouteMetadata' : 'backendRouteMetadata'
+  const metadataFileName = isApi ? 'api-route-metadata.generated' : 'backend-route-metadata.generated'
+  const shardCases = shards
+    .map(({ key, stem }) => `    case ${JSON.stringify(key)}:\n      return import('./${stem}').then((entry) => ({ routes: entry.routes, routeOrders: entry.routeOrders }))`)
+    .join('\n')
+  const hasDynamicShard = shards.some(({ key }) => key === DYNAMIC_SHARD_KEY)
+  const routeShardKeys: string[] = []
+  for (const shard of shards) {
+    for (const order of shard.orders) routeShardKeys[order] = shard.key
+  }
+  const prefixNormalization = kind === 'backend'
+    ? `  if (segments[0]?.toLowerCase() === 'backend') segments.shift()\n`
+    : ''
+  const loadDynamic = hasDynamicShard
+    ? `  const dynamicShard = await loadShard(${JSON.stringify(DYNAMIC_SHARD_KEY)})\n`
+    : `  const dynamicShard: LoadedRouteShard = EMPTY_SHARD\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`
+}
+
+export function renderRouteManifestShardOutputs(
+  kind: RouteManifestShardKind,
+  entries: RouteManifestShardEntry[],
+): RouteManifestShardOutput[] {
+  const grouped = new Map<string, IndexedRouteManifestShardEntry[]>()
+  for (const [order, entry] of entries.entries()) {
+    const key = getRouteManifestShardKey(kind, entry.path)
+    const existing = grouped.get(key)
+    const indexedEntry = { ...entry, order }
+    if (existing) existing.push(indexedEntry)
+    else grouped.set(key, [indexedEntry])
+  }
+
+  const sortedGroups = Array.from(grouped.entries()).sort(([a], [b]) => a.localeCompare(b))
+  const shards = sortedGroups.map(([key, shardEntries], index) => {
+    const stem = shardStem(kind, index, key)
+    return {
+      key,
+      stem,
+      orders: shardEntries.map((entry) => entry.order),
+      output: {
+        fileName: `${stem}.ts`,
+        content: renderShardFile(kind, shardEntries),
+      },
+    }
+  })
+  const loaderFileName = kind === 'api'
+    ? 'api-route-shards.generated.ts'
+    : 'backend-route-shards.generated.ts'
+
+  return [
+    ...shards.map(({ output }) => output),
+    {
+      fileName: loaderFileName,
+      content: renderLoaderFile(kind, shards),
+    },
+  ]
+}
+
+export function renderRouteMetadataOutput(
+  kind: RouteManifestShardKind,
+  entries: RouteManifestShardEntry[],
+): RouteManifestShardOutput {
+  const isApi = kind === 'api'
+  const manifestType = isApi ? 'ApiRouteManifestEntry' : 'BackendRouteManifestEntry'
+  const metadataType = isApi ? 'ApiRouteMetadataEntry' : 'BackendRouteMetadataEntry'
+  const exportName = isApi ? 'apiRouteMetadata' : 'backendRouteMetadata'
+  const fileName = isApi ? 'api-route-metadata.generated.ts' : 'backend-route-metadata.generated.ts'
+  const helperImport = isApi ? '' : 'resolvePageRouteMetadata, '
+  const imports = uniqueImports(entries)
+  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`
+  return { fileName, content }
+}
+
+export const routeManifestShardFilePattern = /^(?:api|backend)-route-shard\..+\.generated\.(?:ts|checksum)$/

package/src/lib/queue-worker-supervisor.ts

@@ -32,6 +32,11 @@ import {
 import type { ModuleWorker } from '@open-mercato/shared/modules/registry'
 import type { LazyWorkerSpawnMode } from './auto-spawn-workers'
 
+export type SupervisorWorkerDescriptor = Pick<
+  ModuleWorker,
+  'id' | 'moduleId' | 'queue' | 'concurrency'
+>
+
 export type LazySupervisorSpawnFn = (
   command: string,
   args: readonly string[],
@@ -47,7 +52,7 @@ export type LazyWorkerSupervisorOptions = {
   mercatoBin: string
   appDir: string
   runtimeEnv: NodeJS.ProcessEnv
-  workers: ModuleWorker[]
+  workers: readonly SupervisorWorkerDescriptor[]
   pollMs: number
   restartOnUnexpectedExit: boolean
   spawnMode?: LazyWorkerSpawnMode
@@ -89,7 +94,7 @@ type QueueGroup = {
   workerCount: number
 }
 
-function groupWorkersByQueue(workers: ModuleWorker[]): QueueGroup[] {
+function groupWorkersByQueue(workers: readonly SupervisorWorkerDescriptor[]): QueueGroup[] {
   const groups = new Map<string, QueueGroup>()
   for (const worker of workers) {
     const existing = groups.get(worker.queue)

package/src/lib/resolver.ts

@@ -25,6 +25,7 @@ export type CliEnvironment = {
 export type ModuleEntry = {
   id: string
   from?: '@open-mercato/core' | '@app' | string
+  devSupervisorRequiresFullBootstrap?: boolean
 }
 
 export type PackageInfo = {
@@ -89,18 +90,45 @@ function pkgRootFor(rootDir: string, from?: string, isMonorepo = true): string {
 function parseModuleEntryFromObjectLiteral(node: ts.ObjectLiteralExpression): ModuleEntry | null {
   let id: string | null = null
   let from: string | null = null
+  let devSupervisorRequiresFullBootstrap = false
   for (const property of node.properties) {
-    if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) continue
-    const key = property.name.text
+    if (!ts.isPropertyAssignment(property)) continue
+    const key = ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)
+      ? property.name.text
+      : null
     if (key === 'id' && ts.isStringLiteralLike(property.initializer)) {
       id = property.initializer.text
     }
     if (key === 'from' && ts.isStringLiteralLike(property.initializer)) {
       from = property.initializer.text
     }
+    if (key === 'overrides') {
+      if (!ts.isObjectLiteralExpression(property.initializer)) {
+        devSupervisorRequiresFullBootstrap = true
+        continue
+      }
+      for (const overrideProperty of property.initializer.properties) {
+        if (ts.isSpreadAssignment(overrideProperty)) {
+          devSupervisorRequiresFullBootstrap = true
+          break
+        }
+        if (!ts.isPropertyAssignment(overrideProperty)) continue
+        const overrideKey = ts.isIdentifier(overrideProperty.name) || ts.isStringLiteralLike(overrideProperty.name)
+          ? overrideProperty.name.text
+          : null
+        if (overrideKey === 'workers' || overrideKey === 'cli') {
+          devSupervisorRequiresFullBootstrap = true
+          break
+        }
+      }
+    }
   }
   if (!id) return null
-  return { id, from: from ?? '@open-mercato/core' }
+  return {
+    id,
+    from: from ?? '@open-mercato/core',
+    ...(devSupervisorRequiresFullBootstrap ? { devSupervisorRequiresFullBootstrap: true } : {}),
+  }
 }
 
 function parseProcessEnvAccess(

package/src/lib/utils.ts

@@ -96,18 +96,22 @@ export function writeIfChanged(
       structure: structureChecksum || '',
     }
 
-    const shouldWrite =
-      !existingRecord ||
-      existingRecord.content !== newRecord.content ||
-      (structureChecksum && existingRecord.structure !== newRecord.structure)
-
-    if (shouldWrite) {
+    const outputChanged = !fs.existsSync(filePath) || fs.readFileSync(filePath, 'utf8') !== content
+    if (outputChanged) {
       ensureDir(filePath)
       fs.writeFileSync(filePath, content)
+    }
+
+    const checksumChanged =
+      !existingRecord ||
+      existingRecord.content !== newRecord.content ||
+      existingRecord.structure !== newRecord.structure
+    if (checksumChanged) {
+      ensureDir(checksumPath)
       writeChecksumRecord(checksumPath, newRecord)
-      return true
     }
-    return false
+
+    return outputChanged
   }
 
   // Simple comparison without checksum file
@@ -234,18 +238,22 @@ export function writeGeneratedFile(options: {
   const { outFile, checksumFile, content, structureChecksum, result, quiet } = options
   const checksum = { content: calculateChecksum(content), structure: structureChecksum }
   const existing = readChecksumRecord(checksumFile)
-  const shouldWrite =
-    !fs.existsSync(outFile) ||
-    !existing ||
-    existing.content !== checksum.content ||
-    existing.structure !== checksum.structure
-  if (shouldWrite) {
+  const outputChanged = !fs.existsSync(outFile) || fs.readFileSync(outFile, 'utf8') !== content
+  if (outputChanged) {
     fs.mkdirSync(path.dirname(outFile), { recursive: true })
     fs.writeFileSync(outFile, content)
-    writeChecksumRecord(checksumFile, checksum)
     result.filesWritten.push(outFile)
   } else {
     result.filesUnchanged.push(outFile)
   }
-  if (!quiet) logGenerationResult(path.relative(process.cwd(), outFile), shouldWrite)
+
+  const checksumChanged =
+    !existing ||
+    existing.content !== checksum.content ||
+    existing.structure !== checksum.structure
+  if (checksumChanged) {
+    fs.mkdirSync(path.dirname(checksumFile), { recursive: true })
+    writeChecksumRecord(checksumFile, checksum)
+  }
+  if (!quiet) logGenerationResult(path.relative(process.cwd(), outFile), outputChanged)
 }

package/src/mercato.ts

@@ -43,6 +43,7 @@ import { acquireServerStartLock } from './lib/server-start-lock'
 import { assertSingleInstanceStrategies } from './lib/single-instance-strategy-guard'
 import { createDevEnvReloader, watchDevEnvFiles } from './lib/dev-env-reload'
 import { quotePostgresIdentifier } from './lib/db/identifiers'
+import { getRegisteredDevSupervisorManifest } from './lib/dev-supervisor-manifest'
 // Lazy-imported to avoid pulling in `testcontainers` (devDependency) at startup
 const lazyIntegration = () => import('./lib/testing/integration')
 import type { ChildProcess } from 'node:child_process'
@@ -1999,6 +2000,10 @@ export async function run(argv = process.argv) {
           let lastRestartReason: string | null = null
           const generateWatcherMode: GenerateWatcherMode = resolveGenerateWatcherMode(process.env)
           const envReloader = createDevEnvReloader(appDir, process.env, initialProcessEnvironmentEntries)
+          // The CLI binary registers this primitive manifest before dispatching
+          // `server dev`. Direct `run()` callers keep the existing module-registry
+          // fallback for backward compatibility and focused unit tests.
+          const devSupervisorManifest = getRegisteredDevSupervisorManifest()
 
           function cleanup() {
             console.log('[server] Shutting down...')
@@ -2207,14 +2212,15 @@ export async function run(argv = process.argv) {
               applyEventsSingleDeliveryGuard({ processEnv: process.env, runtimeEnv, autoSpawnWorkersMode })
               const autoSpawnSchedulerMode = resolveAutoSpawnSchedulerMode(process.env)
               const queueStrategy = process.env.QUEUE_STRATEGY || 'local'
-              const schedulerCommand = lookupModuleCommand(getCliModules(), 'scheduler', 'start')
+              const schedulerStartStatus = devSupervisorManifest?.schedulerStartStatus
+                ?? lookupModuleCommand(getCliModules(), 'scheduler', 'start').status
               const embedSchedulerInSharedWorker =
                 shouldEmbedLocalSchedulerInSharedWorker(process.env)
                 && queueStrategy === 'local'
                 && autoSpawnWorkersMode === 'lazy'
                 && resolveLazySpawnMode(process.env) === 'shared'
                 && autoSpawnSchedulerMode !== 'off'
-                && schedulerCommand.status === 'ok'
+                && schedulerStartStatus === 'ok'
               const nextRuntime = startNextDev(runtimeEnv)
               const restartPromise = waitForDevRestart()
               const backgroundStartAbort = new AbortController()
@@ -2248,10 +2254,13 @@ export async function run(argv = process.argv) {
                 }
 
                 if (autoSpawnWorkersMode !== 'off') {
-                  const discoveredWorkers = getRegisteredCliWorkers()
+                  const discoveredWorkers = devSupervisorManifest?.workers ?? getRegisteredCliWorkers()
                   const discoveredWorkerQueues = [...new Set(discoveredWorkers.map((worker) => worker.queue))]
                   if (discoveredWorkerQueues.length === 0) {
-                    console.error('[server] AUTO_SPAWN_WORKERS is enabled, but no queues were discovered from CLI modules. Run `yarn generate` and verify `.mercato/generated/modules.cli.generated.ts` contains worker entries. Continuing without auto-spawned workers.')
+                    const workerRegistryFile = devSupervisorManifest
+                      ? 'dev-supervisor.generated.json'
+                      : 'modules.cli.generated.ts'
+                    console.error(`[server] AUTO_SPAWN_WORKERS is enabled, but no queues were discovered from CLI modules. Run \`yarn generate\` and verify \`.mercato/generated/${workerRegistryFile}\` contains worker entries. Continuing without auto-spawned workers.`)
                   } else if (autoSpawnWorkersMode === 'lazy') {
                     const lazySpawnMode = resolveLazySpawnMode(process.env)
                     const lazyModeHint = lazySpawnMode === 'shared'
@@ -2299,8 +2308,8 @@ export async function run(argv = process.argv) {
                 if (embedSchedulerInSharedWorker && activeLazySupervisor) {
                   console.log('[server] Local scheduler will run inside the lazy shared worker process.')
                 } else if (autoSpawnSchedulerMode !== 'off' && queueStrategy === 'local') {
-                  if (schedulerCommand.status !== 'ok') {
-                    console.log(`[server] Skipping scheduler auto-start — ${describeMissingModuleCommand(schedulerCommand)}`)
+                  if (schedulerStartStatus !== 'ok') {
+                    console.log(`[server] Skipping scheduler auto-start — ${describeMissingModuleCommand({ status: schedulerStartStatus })}`)
                   } else if (autoSpawnSchedulerMode === 'lazy') {
                     console.log('[server] Lazy scheduler auto-spawn enabled - scheduler will start when an enabled schedule exists.')
                     activeLazySchedulerSupervisor = startLazySchedulerSupervisor({