@open-mercato/cli 0.6.7-develop.6552.1.5208a19369 → 0.6.7-develop.6565.1.1026d85fff

package/src/lib/generators/openapi.ts

@@ -8,10 +8,11 @@
 
 import * as fs from 'node:fs'
 import * as path from 'node:path'
-import type { PackageResolver } from '../resolver'
+import type { ModuleEntry, PackageResolver } from '../resolver'
 import { isModuleRouteFile } from './scanner'
 import {
   calculateChecksum,
+  calculateStructureChecksum,
   readChecksumRecord,
   writeChecksumRecord,
   logGenerationResult,
@@ -32,6 +33,111 @@ interface ApiRouteInfo {
   openApiPath: string
 }
 
+interface OpenApiInputManifest {
+  version: 1
+  inputPaths: string[]
+}
+
+interface OpenApiInputContext {
+  enabled: ModuleEntry[]
+  apiRoots: string[]
+  moduleIdentity: Array<{
+    id: string
+    from: string
+    appBase: string
+    pkgBase: string
+  }>
+}
+
+interface OpenApiBundleResult {
+  doc: Record<string, any> | null
+  inputPaths: string[]
+}
+
+const OPENAPI_INPUT_MANIFEST_VERSION = 1
+
+function createOpenApiInputContext(resolver: PackageResolver): OpenApiInputContext {
+  const enabled = resolver.loadEnabledModules()
+  const apiRoots: string[] = []
+  const moduleIdentity = enabled.map((entry) => {
+    const roots = resolver.getModulePaths(entry)
+    apiRoots.push(path.join(roots.appBase, 'api'), path.join(roots.pkgBase, 'api'))
+    return {
+      id: entry.id,
+      from: entry.from ?? '@open-mercato/core',
+      appBase: path.resolve(roots.appBase),
+      pkgBase: path.resolve(roots.pkgBase),
+    }
+  })
+  return { enabled, apiRoots, moduleIdentity }
+}
+
+function readOpenApiInputManifest(filePath: string): OpenApiInputManifest | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as Partial<OpenApiInputManifest>
+    if (
+      parsed.version !== OPENAPI_INPUT_MANIFEST_VERSION
+      || !Array.isArray(parsed.inputPaths)
+      || parsed.inputPaths.some((entry) => typeof entry !== 'string')
+    ) {
+      return null
+    }
+    return {
+      version: OPENAPI_INPUT_MANIFEST_VERSION,
+      inputPaths: Array.from(new Set(parsed.inputPaths.map((entry) => path.resolve(entry))))
+        .sort((a, b) => a.localeCompare(b)),
+    }
+  } catch {
+    return null
+  }
+}
+
+function trackedPathRecord(filePath: string): string {
+  try {
+    const stat = fs.statSync(filePath)
+    if (stat.isFile()) {
+      return `${path.resolve(filePath)}:${calculateChecksum(fs.readFileSync(filePath, 'utf8'))}`
+    }
+    return `${path.resolve(filePath)}:${stat.size}:${stat.mtimeMs}`
+  } catch {
+    return `missing:${path.resolve(filePath)}`
+  }
+}
+
+function calculateOpenApiInputFingerprint(
+  resolver: PackageResolver,
+  context: OpenApiInputContext,
+  manifest: OpenApiInputManifest,
+): string {
+  const rootDir = resolver.getRootDir()
+  const appDir = resolver.getAppDir()
+  const configPaths = [
+    resolver.getModulesConfigPath(),
+    path.join(rootDir, 'package.json'),
+    path.join(rootDir, 'yarn.lock'),
+    path.join(rootDir, 'package-lock.json'),
+    path.join(rootDir, 'pnpm-lock.yaml'),
+    path.join(rootDir, 'tsconfig.json'),
+    path.join(rootDir, 'tsconfig.base.json'),
+    path.join(appDir, 'package.json'),
+    path.join(appDir, 'tsconfig.json'),
+  ]
+  const trackedRecords = [...manifest.inputPaths, ...configPaths]
+    .map(trackedPathRecord)
+    .sort((a, b) => a.localeCompare(b))
+  return calculateChecksum(JSON.stringify({
+    version: OPENAPI_INPUT_MANIFEST_VERSION,
+    modules: context.moduleIdentity,
+    routeStructure: calculateStructureChecksum(context.apiRoots),
+    trackedRecords,
+    environment: {
+      node: process.version,
+      nodeEnv: process.env.NODE_ENV ?? '',
+      publicAppUrl: process.env.NEXT_PUBLIC_APP_URL ?? '',
+    },
+  }))
+}
+
 function resolveExistingPath(paths: string[]): string | null {
   for (const candidate of paths) {
     if (fs.existsSync(candidate)) return candidate
@@ -42,9 +148,11 @@ function resolveExistingPath(paths: string[]): string | null {
 /**
  * Find all API route files and extract their OpenAPI specs.
  */
-async function findApiRoutes(resolver: PackageResolver): Promise<ApiRouteInfo[]> {
+async function findApiRoutes(
+  resolver: PackageResolver,
+  enabled: ModuleEntry[],
+): Promise<ApiRouteInfo[]> {
   const routes: ApiRouteInfo[] = []
-  const enabled = resolver.loadEnabledModules()
 
   for (const entry of enabled) {
     const modId = entry.id
@@ -198,13 +306,13 @@ async function generateOpenApiViaBundle(
   routes: ApiRouteInfo[],
   resolver: PackageResolver,
   quiet: boolean
-): Promise<Record<string, any> | null> {
+): Promise<OpenApiBundleResult> {
   let esbuild: typeof import('esbuild')
   try {
     esbuild = await import('esbuild')
   } catch {
     if (!quiet) console.log('[OpenAPI] esbuild not available, skipping bundle approach')
-    return null
+    return { doc: null, inputPaths: [] }
   }
 
   const { execFileSync } = await import('node:child_process')
@@ -225,13 +333,14 @@ async function generateOpenApiViaBundle(
     if (!quiet) {
       console.log(`[OpenAPI] Generator source not found at ${generatorPath}, skipping bundle approach`)
     }
-    return null
+    return { doc: null, inputPaths: [] }
   }
 
   const cacheDir = path.join(rootDir, 'node_modules', '.cache')
   if (!fs.existsSync(cacheDir)) fs.mkdirSync(cacheDir, { recursive: true })
 
   const bundlePath = path.join(cacheDir, '_openapi-bundle.mjs')
+  let inputPaths: string[] = []
 
   // Build the entry script that imports all routes and calls buildOpenApiDocument
   const importLines: string[] = [
@@ -418,7 +527,7 @@ process.stdout.write(JSON.stringify(deepClone(doc), (_, v) =>
   }
 
   try {
-    await esbuild.build({
+    const buildResult = await esbuild.build({
       stdin: {
         contents: entryScript,
         resolveDir: appDir,
@@ -426,6 +535,8 @@ process.stdout.write(JSON.stringify(deepClone(doc), (_, v) =>
         loader: 'ts',
       },
       bundle: true,
+      metafile: true,
+      absWorkingDir: rootDir,
       format: 'esm',
       platform: 'node',
       target: 'node18',
@@ -437,6 +548,12 @@ process.stdout.write(JSON.stringify(deepClone(doc), (_, v) =>
       plugins: [stubNextPlugin, resolveProjectImportsPlugin, externalNonWorkspacePlugin],
     })
 
+    inputPaths = Object.keys(buildResult.metafile?.inputs ?? {})
+      .filter((inputPath) => !inputPath.startsWith('<'))
+      .map((inputPath) => path.resolve(rootDir, inputPath))
+      .filter((inputPath) => fs.existsSync(inputPath))
+      .sort((a, b) => a.localeCompare(b))
+
     const stdout = execFileSync(process.execPath, [bundlePath], {
       timeout: 60_000,
       maxBuffer: 20 * 1024 * 1024,
@@ -459,7 +576,7 @@ process.stdout.write(JSON.stringify(deepClone(doc), (_, v) =>
       console.log(`[OpenAPI] Bundle approach: ${pathCount} paths, ${withBody} with requestBody schemas`)
     }
 
-    return doc
+    return { doc, inputPaths }
   } catch (err) {
     const errMsg = err instanceof Error ? err.message : String(err)
     const stderr = (err as any)?.stderr
@@ -483,7 +600,7 @@ process.stdout.write(JSON.stringify(deepClone(doc), (_, v) =>
         }
       }
     }
-    return null
+    return { doc: null, inputPaths }
   } finally {
     // Shut down esbuild's persistent Go service so it does not deadlock at
     // process exit when a plugin request is still in flight.
@@ -552,14 +669,33 @@ export async function generateOpenApi(options: GenerateOpenApiOptions): Promise<
   const outputDir = resolver.getOutputDir()
   const outFile = path.join(outputDir, 'openapi.generated.json')
   const checksumFile = path.join(outputDir, 'openapi.generated.checksum')
+  const inputManifestFile = path.join(outputDir, 'openapi.generated.inputs.json')
 
   // Ensure output directory exists
   if (!fs.existsSync(outputDir)) {
     fs.mkdirSync(outputDir, { recursive: true })
   }
 
+  const inputContext = createOpenApiInputContext(resolver)
+  const existingChecksums = readChecksumRecord(checksumFile)
+  const existingManifest = readOpenApiInputManifest(inputManifestFile)
+
+  if (
+    existingChecksums?.structure
+    && existingManifest
+    && fs.existsSync(outFile)
+    && calculateChecksum(fs.readFileSync(outFile, 'utf8')) === existingChecksums.content
+    && calculateOpenApiInputFingerprint(resolver, inputContext, existingManifest) === existingChecksums.structure
+  ) {
+    result.filesUnchanged.push(outFile)
+    if (!quiet) {
+      console.log(`[OpenAPI] Skipped (inputs unchanged): ${outFile}`)
+    }
+    return result
+  }
+
   // Find all API routes
-  const routes = await findApiRoutes(resolver)
+  const routes = await findApiRoutes(resolver, inputContext.enabled)
 
   if (!quiet) {
     console.log(`[OpenAPI] Found ${routes.length} API route files`)
@@ -567,7 +703,8 @@ export async function generateOpenApi(options: GenerateOpenApiOptions): Promise<
 
   // Determine project root (cli package is at packages/cli/src/lib/generators/)
   // Try esbuild bundle approach first — produces full requestBody/response schemas
-  let doc: Record<string, any> | null = await generateOpenApiViaBundle(routes, resolver, quiet)
+  const bundleResult = await generateOpenApiViaBundle(routes, resolver, quiet)
+  let doc: Record<string, any> | null = bundleResult.doc
 
   // Fallback to static regex approach (extracts operationId/summary/tags but no schemas)
   if (!doc) {
@@ -601,10 +738,26 @@ export async function generateOpenApi(options: GenerateOpenApiOptions): Promise<
 
   const output = JSON.stringify(doc, null, 2)
   const checksum = calculateChecksum(output)
+  let structureChecksum = ''
+
+  if (bundleResult.doc && bundleResult.inputPaths.length > 0) {
+    const manifest: OpenApiInputManifest = {
+      version: OPENAPI_INPUT_MANIFEST_VERSION,
+      inputPaths: Array.from(new Set(bundleResult.inputPaths)).sort((a, b) => a.localeCompare(b)),
+    }
+    fs.writeFileSync(inputManifestFile, `${JSON.stringify(manifest, null, 2)}\n`)
+    structureChecksum = calculateOpenApiInputFingerprint(resolver, inputContext, manifest)
+  } else {
+    try { fs.unlinkSync(inputManifestFile) } catch {}
+  }
 
   // Check if unchanged
-  const existingChecksums = readChecksumRecord(checksumFile)
-  if (existingChecksums && existingChecksums.content === checksum && fs.existsSync(outFile)) {
+  const existingOutputMatches = fs.existsSync(outFile)
+    && calculateChecksum(fs.readFileSync(outFile, 'utf8')) === checksum
+  if (existingChecksums && existingChecksums.content === checksum && existingOutputMatches) {
+    if (existingChecksums.structure !== structureChecksum) {
+      writeChecksumRecord(checksumFile, { content: checksum, structure: structureChecksum })
+    }
     result.filesUnchanged.push(outFile)
     if (!quiet) {
       console.log(`[OpenAPI] Skipped (unchanged): ${outFile}`)
@@ -614,7 +767,7 @@ export async function generateOpenApi(options: GenerateOpenApiOptions): Promise<
 
   // Write the file
   fs.writeFileSync(outFile, output)
-  writeChecksumRecord(checksumFile, { content: checksum, structure: '' })
+  writeChecksumRecord(checksumFile, { content: checksum, structure: structureChecksum })
 
   result.filesWritten.push(outFile)
 

package/src/lib/in-process-generate-watcher.ts

@@ -1,15 +1,16 @@
 /**
  * In-process generate watcher.
  *
- * Polls a structural-fingerprint function on a configurable interval and
- * invokes the supplied generator callback whenever the fingerprint changes.
+ * Coalesces filesystem events on a configurable interval, then verifies them
+ * with the existing structural fingerprint before invoking the generator.
+ * If filesystem watching is unavailable, it falls back to fingerprint polling.
  * The polling loop is identical to the legacy standalone watcher; the only
  * difference is that it now runs inside whatever process calls it
  * (typically `mercato server dev`), so the dev runtime no longer needs a
  * sidecar `mercato generate watch` Node process.
  *
- * Contract preserved 1:1 with the prior standalone watcher:
- *   - Default poll interval 1000 ms (minimum 250 ms).
+ * Contract preserved from the prior standalone watcher:
+ *   - Default debounce/fallback poll interval 1000 ms (minimum 250 ms).
  *   - One initial generator run unless `skipInitial` is true.
  *   - Concurrent regeneration requests are coalesced (running + pending).
  *   - Generator errors are logged but never crash the watcher.
@@ -18,12 +19,25 @@
 
 export type GenerateWatcherLogger = Pick<Console, 'log' | 'error'>
 
+export type GenerateWatcherChangeSignal = {
+  /** Monotonic event generation. Changes indicate that a checksum may be stale. */
+  currentVersion(): number
+  /** Refresh filesystem subscriptions after module configuration changes. */
+  refresh(): Promise<void> | void
+  /** When true, preserve the legacy full-checksum-on-every-poll behavior. */
+  usesPollingFallback(): boolean
+  /** Close filesystem subscriptions. Idempotent. */
+  close(): Promise<void> | void
+}
+
 export type GenerateWatcherOptions = {
   /**
    * Function that returns the current structural fingerprint of the module
    * tree. The watcher re-runs `runGenerators` whenever this value changes.
    */
   computeStructureChecksum: () => Promise<string> | string
+  /** Optional event signal that avoids full checksum work during idle polls. */
+  changeSignal?: GenerateWatcherChangeSignal
   /**
    * Function that performs the actual regeneration work. Called once on
    * startup (unless `skipInitial`) and again whenever the checksum changes.
@@ -69,13 +83,14 @@ export function startInProcessGenerateWatcher(
   const quiet = options.quiet === true
   const pollMs = resolvePollMs(options.pollMs)
   const skipInitial = options.skipInitial === true
-  const { computeStructureChecksum, runGenerators } = options
+  const { changeSignal, computeStructureChecksum, runGenerators } = options
 
   let stopping = false
   let pollTimer: ReturnType<typeof setTimeout> | null = null
   let running = false
   let pendingReason: string | null = null
   let previousChecksum = ''
+  let observedChangeVersion = -1
   let doneResolve: (() => void) | null = null
   const done = new Promise<void>((resolve) => {
     doneResolve = resolve
@@ -114,7 +129,17 @@ export function startInProcessGenerateWatcher(
       void (async () => {
         if (stopping) return
         try {
+          const changeVersion = changeSignal?.currentVersion() ?? 0
+          if (
+            changeSignal
+            && !changeSignal.usesPollingFallback()
+            && changeVersion === observedChangeVersion
+          ) {
+            return
+          }
           const nextChecksum = await computeStructureChecksum()
+          observedChangeVersion = changeVersion
+          await changeSignal?.refresh()
           if (nextChecksum !== previousChecksum) {
             previousChecksum = nextChecksum
             await runOnce('structure change')
@@ -132,15 +157,18 @@ export function startInProcessGenerateWatcher(
 
   void (async () => {
     try {
+      await changeSignal?.refresh()
+      const initialChangeVersion = changeSignal?.currentVersion() ?? 0
       if (!skipInitial) {
         await runOnce('initial')
       }
       previousChecksum = await computeStructureChecksum()
+      observedChangeVersion = initialChangeVersion
       if (!quiet) {
         if (skipInitial) {
           logger.log('[generate:watch] Skipping initial regeneration and watching the current generated state.')
         }
-        logger.log(`[generate:watch] Watching structural module files every ${pollMs}ms (in-process).`)
+        logger.log(`[generate:watch] Watching structural module files with a ${pollMs}ms debounce (in-process).`)
       }
       scheduleNext()
     } catch (error) {
@@ -162,6 +190,7 @@ export function startInProcessGenerateWatcher(
       clearTimeout(pollTimer)
       pollTimer = null
     }
+    await changeSignal?.close()
     if (doneResolve) {
       doneResolve()
       doneResolve = null

package/src/mercato.ts

@@ -750,7 +750,7 @@ async function runPostGenerateStructuralCachePurge(quiet: boolean): Promise<void
  * so the watcher embedded in the server lifecycle can reuse the same closure
  * without re-importing the closure-scoped version inside `buildBaseModules`.
  */
-async function runGeneratorSuite(quiet: boolean): Promise<void> {
+async function runGeneratorSuite(quiet: boolean): Promise<boolean> {
   const { createResolver } = await import('./lib/resolver')
   const {
     generateEntityIds,
@@ -763,35 +763,84 @@ async function runGeneratorSuite(quiet: boolean): Promise<void> {
     generateOpenApi,
   } = await import('./lib/generators')
   const resolver = createResolver()
-  await generateEntityIds({ resolver, quiet })
-  await generateModuleRegistry({ resolver, quiet })
-  await generateModuleRegistryApp({ resolver, quiet })
-  await generateModuleRegistryCli({ resolver, quiet })
-  await generateModuleEntities({ resolver, quiet })
-  await generateModuleDi({ resolver, quiet })
-  await generateModulePackageSources({ resolver, quiet })
-  await generateOpenApi({ resolver, quiet })
+  const results = [
+    await generateEntityIds({ resolver, quiet }),
+    await generateModuleRegistry({ resolver, quiet }),
+    await generateModuleRegistryApp({ resolver, quiet }),
+    await generateModuleRegistryCli({ resolver, quiet }),
+    await generateModuleEntities({ resolver, quiet }),
+    await generateModuleDi({ resolver, quiet }),
+    await generateModulePackageSources({ resolver, quiet }),
+    await generateOpenApi({ resolver, quiet }),
+  ]
+  return results.some((result) => (result?.filesWritten.length ?? 0) > 0)
+}
+
+async function runGeneratorSuiteWithStructuralInvalidation(quiet: boolean): Promise<void> {
+  const generatedFilesChanged = await runGeneratorSuite(quiet)
+  if (!generatedFilesChanged) {
+    if (!quiet) {
+      console.log('[generate] Generated outputs unchanged; skipping structural cache purge.')
+    }
+    return
+  }
+  await runPostGenerateStructuralCachePurge(quiet)
 }
 
 /**
- * Builds the structural-fingerprint function used by the in-process generate
- * watcher. Walks the same module roots the legacy `mercato generate watch`
- * CLI command tracked, so the polling semantics are byte-for-byte identical.
+ * Builds the event-gated structural fingerprint runtime used by generate
+ * watchers. Filesystem events mark the tree dirty; the existing full content
+ * checksum remains the final authority and the fallback when watching fails.
  */
-function createGenerateWatchChecksumFn(): () => Promise<string> {
-  return async () => {
-    const { createResolver } = await import('./lib/resolver')
-    const { calculateGenerateWatchStructureChecksum } = await import('./lib/generate-watch-structure')
+async function createGenerateWatchRuntime() {
+  const [
+    { createResolver },
+    { calculateGenerateWatchStructureChecksum },
+    { createGenerateWatchChangeSignal },
+    { resolveStandaloneSourceMirrorBase },
+  ] = await Promise.all([
+    import('./lib/resolver'),
+    import('./lib/generate-watch-structure'),
+    import('./lib/generate-watch-events'),
+    import('./lib/generators/scanner'),
+  ])
+
+  const collectWatchState = () => {
     const resolver = createResolver()
     const moduleRoots = []
     for (const entry of resolver.loadEnabledModules()) {
       const roots = resolver.getModulePaths(entry)
       moduleRoots.push({ appBase: roots.appBase, pkgBase: roots.pkgBase })
     }
-    return calculateGenerateWatchStructureChecksum({
-      modulesFile: path.join(resolver.getAppDir(), 'src', 'modules.ts'),
+    return {
+      modulesFile: resolver.getModulesConfigPath(),
       moduleRoots,
-    })
+    }
+  }
+
+  return {
+    computeStructureChecksum: async () => {
+      return calculateGenerateWatchStructureChecksum(collectWatchState())
+    },
+    changeSignal: createGenerateWatchChangeSignal({
+      getWatchTargets: () => {
+        const state = collectWatchState()
+        const targets: Array<{ directory: string; recursive: boolean; fileName?: string }> = [{
+          directory: path.dirname(state.modulesFile),
+          recursive: false,
+          fileName: path.basename(state.modulesFile),
+        }]
+        for (const roots of state.moduleRoots) {
+          targets.push({ directory: path.dirname(roots.appBase), recursive: true })
+          targets.push({ directory: path.dirname(roots.pkgBase), recursive: true })
+          const sourceMirror = resolveStandaloneSourceMirrorBase(roots.pkgBase)
+          if (sourceMirror) {
+            targets.push({ directory: path.dirname(sourceMirror), recursive: true })
+          }
+        }
+        return targets
+      },
+    }),
   }
 }
 
@@ -1777,8 +1826,7 @@ export async function run(argv = process.argv) {
           const quiet = args.includes('--quiet') || args.includes('-q')
 
           console.log('Running all generators...')
-          await runGeneratorSuite(quiet)
-          await runPostGenerateStructuralCachePurge(quiet)
+          await runGeneratorSuiteWithStructuralInvalidation(quiet)
           console.log('All generators completed.')
         },
       },
@@ -1791,14 +1839,14 @@ export async function run(argv = process.argv) {
           const parsedInterval = intervalArg ? Number.parseInt(intervalArg.split('=')[1] ?? '', 10) : NaN
           const intervalMs = Number.isFinite(parsedInterval) && parsedInterval >= 250 ? parsedInterval : 1000
 
+          const generateWatchRuntime = await createGenerateWatchRuntime()
           const watcher = startInProcessGenerateWatcher({
             pollMs: intervalMs,
             skipInitial,
             quiet,
-            computeStructureChecksum: createGenerateWatchChecksumFn(),
+            ...generateWatchRuntime,
             runGenerators: async () => {
-              await runGeneratorSuite(true)
-              await runPostGenerateStructuralCachePurge(true)
+              await runGeneratorSuiteWithStructuralInvalidation(true)
             },
           })
 
@@ -2238,6 +2286,7 @@ export async function run(argv = process.argv) {
                 // (measured against the legacy sidecar). Opt back into the
                 // sidecar with `OM_DEV_GENERATE_WATCH_MODE=legacy` if needed.
                 console.log('[server] In-process generate watcher enabled — structural changes will regenerate without a sidecar process.')
+                const generateWatchRuntime = await createGenerateWatchRuntime()
                 activeGenerateWatcher = startInProcessGenerateWatcher({
                   // `--skip-initial` equivalent: `yarn dev` always runs an
                   // initial `mercato generate` before reaching the server
@@ -2246,10 +2295,9 @@ export async function run(argv = process.argv) {
                   // twice in a row.
                   skipInitial: true,
                   quiet: false,
-                  computeStructureChecksum: createGenerateWatchChecksumFn(),
+                  ...generateWatchRuntime,
                   runGenerators: async () => {
-                    await runGeneratorSuite(true)
-                    await runPostGenerateStructuralCachePurge(true)
+                    await runGeneratorSuiteWithStructuralInvalidation(true)
                   },
                 })
               } else {