@open-mercato/cli 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/lib/generators/extensions/index.ts

@@ -1,4 +1,5 @@
 import type { GeneratorExtension } from '../extension'
+import { createAgentFilesExtension } from './agent-files'
 import { createAiAgentsExtension } from './ai-agents'
 import { createAiToolsExtension } from './ai-tools'
 import { createAnalyticsExtension } from './analytics'
@@ -25,6 +26,7 @@ export function loadGeneratorExtensions(): GeneratorExtension[] {
     createMessagesExtension(),
     createAiToolsExtension(),
     createAiAgentsExtension(),
+    createAgentFilesExtension(),
     createEventsExtension(),
     createAnalyticsExtension(),
     createTranslatableFieldsExtension(),

package/src/lib/generators/index.ts

@@ -10,3 +10,4 @@ export { generateModuleEntities, type ModuleEntitiesOptions } from './module-ent
 export { generateModuleDi, type ModuleDiOptions } from './module-di'
 export { generateModulePackageSources, type ModulePackageSourcesOptions } from './module-package-sources'
 export { generateOpenApi, type GenerateOpenApiOptions } from './openapi'
+export { generateWebResearchAdapters, type WebResearchAdaptersOptions } from './web-research-adapters'

package/src/lib/generators/module-registry.ts

@@ -59,6 +59,7 @@ import {
   namespaceFallback,
   namespaceImportSpec,
 } from './extensions/shared'
+import { detectBackendRouteCollisions, type BackendRouteRegistration } from './route-collisions'
 import {
   scanModuleDir,
   resolveModuleFile,
@@ -118,6 +119,7 @@ type ModuleRegistryDiscoveryEntry = {
   roots: ModuleRoots
   imps: ModuleImports
   appImportBase: string
+  isAppModule: boolean
   resolve: (relativePath: string) => ResolvedFile | null
   frontendFiles: ScannedFile[]
   backendFiles: ScannedFile[]
@@ -171,22 +173,39 @@ type PageRouteGenerationResult = {
 // patterns collide only when a page is left un-namespaced (e.g. `backend/[id]`
 // instead of `backend/<mod>/[id]`), silently shadowing another module at runtime.
 // Mirrors the existing duplicate-command-id guard.
+type BackendRoutePatternOwner = { moduleId: string; isAppModule: boolean }
+
 function assertUniqueBackendRoutePattern(
-  seen: Map<string, string>,
+  seen: Map<string, BackendRoutePatternOwner>,
   moduleId: string,
   pattern: string,
+  isAppModule: boolean,
 ): void {
   if (!pattern.startsWith('/backend/')) return
   const previous = seen.get(pattern)
-  if (previous && previous !== moduleId) {
-    throw new Error(
-      `[generate] Duplicate backend route pattern "${pattern}" generated by modules ` +
-      `"${previous}" and "${moduleId}". Each backend page must resolve to a unique URL — ` +
-      `nest the page under a module-specific folder (e.g. backend/${moduleId}/...) so it ` +
-      `does not silently shadow another module.`,
-    )
-  }
-  seen.set(pattern, moduleId)
+  if (previous && previous.moduleId !== moduleId) {
+    // An app-local module shadowing a package module's page is a supported
+    // override — the app entry wins at runtime, which is the whole point of
+    // putting a module in `apps/<app>/src/modules/`. Only a collision where
+    // neither side can predictably win is fatal: package-vs-package (no
+    // precedence between them) or app-vs-app (the same app twice).
+    const isIntentionalAppShadow = previous.isAppModule !== isAppModule
+    if (!isIntentionalAppShadow) {
+      const message =
+        `[generate] Duplicate backend route pattern "${pattern}" generated by modules ` +
+        `"${previous.moduleId}" and "${moduleId}". Each backend page must resolve to a unique URL — ` +
+        `nest the page under a module-specific folder (e.g. backend/${moduleId}/...) so it ` +
+        `does not silently shadow another module.`
+      // Print before throwing: this guard short-circuits the aggregate collision
+      // sweep that would otherwise report the offending path and modules, and an
+      // operator needs the detail whichever guard fires first.
+      console.error(message)
+      throw new Error(message)
+    }
+  }
+  // The app module owns the pattern once it shadows, so a package module seen
+  // afterwards is measured against the app entry rather than replacing it.
+  if (!previous || isAppModule) seen.set(pattern, { moduleId, isAppModule })
 }
 
 type ApiRouteGenerationResult = {
@@ -2056,6 +2075,7 @@ async function createModuleRegistryDiscovery(
       roots,
       imps,
       appImportBase,
+      isAppModule: entry.from === '@app',
       resolve,
       frontendFiles: scanModuleDir(roots, SCAN_CONFIGS.frontendPages),
       backendFiles: scanModuleDir(roots, SCAN_CONFIGS.backendPages),
@@ -2121,9 +2141,10 @@ async function processPageFiles(options: {
   runtimeImports: string[]
   manifestImports?: string[]
   importIdRef: { value: number }
+  collectRoute?: (registration: { routePath: string; fromApp: boolean }) => void
   quiet?: boolean
 }): Promise<PageRouteGenerationResult> {
-  const { files, type, modId, appDir, pkgDir, appImportBase, pkgImportBase, eagerImports, runtimeImports, manifestImports, importIdRef, quiet } = options
+  const { files, type, modId, appDir, pkgDir, appImportBase, pkgImportBase, eagerImports, runtimeImports, manifestImports, importIdRef, collectRoute, quiet } = options
   const metaPrefix = type === 'frontend' ? 'M' : 'BM'
   const eagerRoutes: string[] = []
   const runtimeRoutes: string[] = []
@@ -2148,6 +2169,7 @@ async function processPageFiles(options: {
     const moduleBaseDir = path.join(fromApp ? appDir : pkgDir, ...segs)
     const sourceFile = findExistingModuleFile(moduleBaseDir, pageFile)
     if (!sourceFile || !hasDefaultExport(sourceFile)) continue
+    collectRoute?.({ routePath, fromApp })
     const metaPath = findExistingModuleFileByBaseNames(moduleBaseDir, ['page.meta', 'meta'])
     warnIfPageMetaMissingMetadataExport(metaPath, quiet)
     let metaExpr = 'undefined'
@@ -2245,6 +2267,7 @@ async function processPageFiles(options: {
     const moduleBaseDir = path.join(fromApp ? appDir : pkgDir, ...segs)
     const sourceFile = findExistingModuleFile(moduleBaseDir, file)
     if (!sourceFile || !hasDefaultExport(sourceFile)) continue
+    collectRoute?.({ routePath, fromApp })
     const metaPath = findExistingModuleFileByBaseNames(moduleBaseDir, [`${name}.meta`, 'meta'])
     let metaExpr = 'undefined'
     let runtimeMetaExpr = 'undefined'
@@ -3609,6 +3632,7 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
   const importIdRef = { value: 0 }
   const requiresByModule = new Map<string, string[]>()
   const commandLoaderEntries: CommandLoaderGenerationEntry[] = []
+  const backendRouteRegistrations: BackendRouteRegistration[] = []
   let hasRouteComponents = false
   let hasAbandonHookWorkers = false
 
@@ -3620,10 +3644,10 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
     aclPath?: string
   }> = []
 
-  const seenBackendRoutePatterns = new Map<string, string>()
+  const seenBackendRoutePatterns = new Map<string, BackendRoutePatternOwner>()
 
   for (const discovered of discovery.modules) {
-    const { modId, roots, imps, appImportBase } = discovered
+    const { modId, roots, imps, appImportBase, isAppModule } = discovered
     commandLoaderEntries.push(...discovered.commandLoaderEntries)
 
     const frontendRoutes: string[] = []
@@ -3814,6 +3838,13 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
           runtimeImports,
           manifestImports: backendRouteManifestImports,
           importIdRef,
+          collectRoute: ({ routePath, fromApp }) => {
+            backendRouteRegistrations.push({
+              routePath,
+              moduleId: modId,
+              packageSourced: !fromApp && !isAppModule,
+            })
+          },
           quiet,
         })
         backendRoutes.push(...generatedBackendRoutes.eagerRoutes)
@@ -3822,7 +3853,7 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
         backendRouteShardEntries.push(...generatedBackendRoutes.manifestShardRoutes)
         backendRouteMetadataEntries.push(...generatedBackendRoutes.metadataRoutes)
         for (const pattern of generatedBackendRoutes.routePatterns) {
-          assertUniqueBackendRoutePattern(seenBackendRoutePatterns, modId, pattern)
+          assertUniqueBackendRoutePattern(seenBackendRoutePatterns, modId, pattern, isAppModule)
         }
         hasRouteComponents = true
       }
@@ -4111,6 +4142,24 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
     }
   }
 
+  // Backend route collision detection: duplicate paths between package modules are
+  // always a bug (one silently shadows the other at runtime); app-module shadowing
+  // of a package page is the supported override mechanism and only logs a note.
+  {
+    const collisionResult = detectBackendRouteCollisions(backendRouteRegistrations)
+    for (const note of collisionResult.notes) {
+      if (!quiet) console.log(`[Route Shadow] ${note}`)
+    }
+    if (collisionResult.errors.length > 0) {
+      for (const error of collisionResult.errors) {
+        console.error(`\x1b[31m[Route Collision]\x1b[0m ${error}`)
+      }
+      throw new Error(
+        `Backend route collision detection found ${collisionResult.errors.length} duplicate path(s) registered by multiple package modules. Rename the colliding page directories before proceeding.`
+      )
+    }
+  }
+
   const output = renderAstModuleRegistryFile({
     fileName: 'modules.generated.ts',
     generator: 'registry',
@@ -4326,10 +4375,10 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
   const commandLoaderEntries: CommandLoaderGenerationEntry[] = []
   let hasRouteComponents = false
   let hasAbandonHookWorkers = false
-  const seenBackendRoutePatterns = new Map<string, string>()
+  const seenBackendRoutePatterns = new Map<string, BackendRoutePatternOwner>()
 
   for (const discovered of discovery.modules) {
-    const { modId, roots, imps, appImportBase } = discovered
+    const { modId, roots, imps, appImportBase, isAppModule } = discovered
     commandLoaderEntries.push(...discovered.commandLoaderEntries)
 
     const frontendRoutes: WriterFunction[] = []
@@ -4460,7 +4509,7 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
         })
         backendRoutes.push(...beAst.routes)
         for (const pattern of beAst.routePatterns) {
-          assertUniqueBackendRoutePattern(seenBackendRoutePatterns, modId, pattern)
+          assertUniqueBackendRoutePattern(seenBackendRoutePatterns, modId, pattern, isAppModule)
         }
         hasRouteComponents = true
       }

package/src/lib/generators/route-collisions.ts

@@ -0,0 +1,57 @@
+export type BackendRouteRegistration = {
+  routePath: string
+  moduleId: string
+  packageSourced: boolean
+}
+
+export type BackendRouteCollisionResult = {
+  errors: string[]
+  notes: string[]
+}
+
+export function detectBackendRouteCollisions(
+  registrations: BackendRouteRegistration[],
+): BackendRouteCollisionResult {
+  const byPath = new Map<string, BackendRouteRegistration[]>()
+  for (const registration of registrations) {
+    const existing = byPath.get(registration.routePath)
+    if (existing) existing.push(registration)
+    else byPath.set(registration.routePath, [registration])
+  }
+
+  const errors: string[] = []
+  const notes: string[] = []
+  for (const [routePath, entries] of byPath) {
+    const moduleIds = new Set(entries.map((entry) => entry.moduleId))
+    if (moduleIds.size < 2) continue
+
+    const packageModuleIds = Array.from(
+      new Set(entries.filter((entry) => entry.packageSourced).map((entry) => entry.moduleId)),
+    ).sort((a, b) => a.localeCompare(b))
+
+    if (packageModuleIds.length >= 2) {
+      errors.push(
+        `Backend route "${routePath}" is registered by ${packageModuleIds.length} package modules: ${packageModuleIds
+          .map((id) => `"${id}"`)
+          .join(', ')}. Duplicate backend paths between package modules are always a bug — rename one module's page directory.`,
+      )
+      continue
+    }
+
+    const appModuleIds = Array.from(
+      new Set(entries.filter((entry) => !entry.packageSourced).map((entry) => entry.moduleId)),
+    ).sort((a, b) => a.localeCompare(b))
+    const shadowedId = packageModuleIds[0]
+    notes.push(
+      shadowedId
+        ? `Backend route "${routePath}" from package module "${shadowedId}" is shadowed by app module(s) ${appModuleIds
+            .map((id) => `"${id}"`)
+            .join(', ')} (intentional override mechanism).`
+        : `Backend route "${routePath}" is registered by multiple app modules: ${appModuleIds
+            .map((id) => `"${id}"`)
+            .join(', ')}.`,
+    )
+  }
+
+  return { errors, notes }
+}

package/src/lib/generators/web-research-adapters.ts

@@ -0,0 +1,133 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { PackageResolver } from '../resolver'
+import { calculateStructureChecksum, createGeneratorResult, type GeneratorResult, writeGeneratedFile } from '../utils'
+
+export interface WebResearchAdaptersOptions {
+  resolver: PackageResolver
+  quiet?: boolean
+}
+
+/**
+ * Mirrors `openMercato.webResearchAdapter` in `@open-mercato/web-research`. It is
+ * duplicated rather than imported because the CLI must not depend on the engine
+ * package to run its generators.
+ */
+const MANIFEST_NAMESPACE = 'openMercato'
+const ADAPTER_MANIFEST_KEY = 'webResearchAdapter'
+
+type DiscoveredAdapter = {
+  packageName: string
+  adapterId: string
+  sourceRoot: string
+}
+
+function readJson(file: string): unknown {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function readManifest(packageJsonPath: string): DiscoveredAdapter | null {
+  const parsed = readJson(packageJsonPath)
+  if (typeof parsed !== 'object' || parsed === null) return null
+  const pkg = parsed as Record<string, unknown>
+  const namespace = pkg[MANIFEST_NAMESPACE]
+  if (typeof namespace !== 'object' || namespace === null) return null
+  const manifest = (namespace as Record<string, unknown>)[ADAPTER_MANIFEST_KEY]
+  if (typeof manifest !== 'object' || manifest === null) return null
+  const adapterId = (manifest as Record<string, unknown>).id
+  const packageName = pkg.name
+  if (typeof packageName !== 'string' || packageName.length === 0) return null
+  if (typeof adapterId !== 'string' || adapterId.length === 0) return null
+  return { packageName, adapterId, sourceRoot: path.dirname(packageJsonPath) }
+}
+
+function scanDirectory(root: string, results: Map<string, DiscoveredAdapter>): void {
+  if (!fs.existsSync(root)) return
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+    if (entry.name === '.bin' || entry.name === '.cache') continue
+    const child = path.join(root, entry.name)
+    // Scoped packages nest one level deeper (`@scope/name`).
+    if (entry.name.startsWith('@')) {
+      scanDirectory(child, results)
+      continue
+    }
+    const discovered = readManifest(path.join(child, 'package.json'))
+    if (discovered && !results.has(discovered.packageName)) results.set(discovered.packageName, discovered)
+  }
+}
+
+function identifierFor(index: number): string {
+  return `adapter${index}`
+}
+
+/**
+ * Emits the statically imported adapter registry. Discovery happens here, at
+ * build time, because a bundler cannot follow `import()` with a runtime-computed
+ * specifier — a dynamic registry would resolve to nothing under Turbopack.
+ */
+export async function generateWebResearchAdapters(
+  options: WebResearchAdaptersOptions,
+): Promise<GeneratorResult> {
+  const { resolver, quiet } = options
+  const result = createGeneratorResult()
+  const outputDir = resolver.getOutputDir()
+  const outFile = path.join(outputDir, 'web-research-adapters.generated.ts')
+  const checksumFile = path.join(outputDir, 'web-research-adapters.checksum')
+
+  const appDir = resolver.getAppDir()
+  const repoRoot = path.resolve(appDir, '..', '..')
+  const discovered = new Map<string, DiscoveredAdapter>()
+  const scanRoots = [
+    path.join(repoRoot, 'packages'),
+    path.join(repoRoot, 'node_modules'),
+    path.join(appDir, 'node_modules'),
+  ]
+  for (const root of scanRoots) scanDirectory(root, discovered)
+
+  const adapters = [...discovered.values()].sort((left, right) =>
+    left.packageName.localeCompare(right.packageName),
+  )
+
+  const imports = adapters
+    .map((adapter, index) => `import * as ${identifierFor(index)} from '${adapter.packageName}'`)
+    .join('\n')
+  const entries = adapters
+    .map(
+      (adapter, index) =>
+        `  { packageName: '${adapter.packageName}', module: ${identifierFor(index)} },`,
+    )
+    .join('\n')
+
+  const content = `// AUTO-GENERATED — do not edit by hand.
+// Source: packages declaring \`${MANIFEST_NAMESPACE}.${ADAPTER_MANIFEST_KEY}\` in package.json.
+// Regenerate with: yarn generate
+import type { AdapterRegistryEntry } from '@open-mercato/web-research'
+${imports}
+
+export const webResearchAdapterEntries: AdapterRegistryEntry[] = [
+${entries}
+]
+`
+
+  writeGeneratedFile({
+    outFile,
+    checksumFile,
+    content,
+    structureChecksum: calculateStructureChecksum(adapters.map((adapter) => adapter.sourceRoot)),
+    result,
+    quiet,
+  })
+
+  return result
+}

package/src/mercato.ts

@@ -790,6 +790,7 @@ async function runGeneratorSuite(quiet: boolean): Promise<boolean> {
     generateModuleDi,
     generateModulePackageSources,
     generateOpenApi,
+    generateWebResearchAdapters,
   } = await import('./lib/generators')
   const resolver = createResolver()
   const results = [
@@ -798,6 +799,7 @@ async function runGeneratorSuite(quiet: boolean): Promise<boolean> {
     await generateModuleEntities({ resolver, quiet }),
     await generateModuleDi({ resolver, quiet }),
     await generateModulePackageSources({ resolver, quiet }),
+    await generateWebResearchAdapters({ resolver, quiet }),
     await generateOpenApi({ resolver, quiet }),
   ]
   return results.some((result) => (result?.filesWritten.length ?? 0) > 0)
@@ -1089,13 +1091,14 @@ export async function run(argv = process.argv) {
       // Step 1: Run generators directly (no process spawn)
       console.log('🔧 Preparing modules (registry, entities, DI)...')
       const { createResolver } = await import('./lib/resolver')
-      const { generateEntityIds, generateModuleRegistries, generateModuleEntities, generateModuleDi, generateModulePackageSources, generateOpenApi } = await import('./lib/generators')
+      const { generateEntityIds, generateModuleRegistries, generateModuleEntities, generateModuleDi, generateModulePackageSources, generateOpenApi, generateWebResearchAdapters } = await import('./lib/generators')
       const resolver = createResolver()
       await generateEntityIds({ resolver, quiet: true })
       await generateModuleRegistries({ resolver, quiet: true })
       await generateModuleEntities({ resolver, quiet: true })
       await generateModuleDi({ resolver, quiet: true })
       await generateModulePackageSources({ resolver, quiet: true })
+      await generateWebResearchAdapters({ resolver, quiet: true })
       await generateOpenApi({ resolver, quiet: true })
       console.log('✅ Modules prepared\n')