@open-mercato/cli 0.6.4-develop.3929.1.fcf7afece2 → 0.6.4-develop.3944.1.4100aa7fbe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.4-develop.3929.1.fcf7afece2",
+  "version": "0.6.4-develop.3944.1.4100aa7fbe",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -59,8 +59,8 @@
     "@mikro-orm/decorators": "^7.1.1",
     "@mikro-orm/migrations": "^7.1.1",
     "@mikro-orm/postgresql": "^7.1.1",
-    "@open-mercato/queue": "0.6.4-develop.3929.1.fcf7afece2",
-    "@open-mercato/shared": "0.6.4-develop.3929.1.fcf7afece2",
+    "@open-mercato/queue": "0.6.4-develop.3944.1.4100aa7fbe",
+    "@open-mercato/shared": "0.6.4-develop.3944.1.4100aa7fbe",
     "cross-spawn": "^7.0.6",
     "pg": "8.21.0",
     "semver": "^7.8.1",
@@ -70,10 +70,10 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.4-develop.3929.1.fcf7afece2"
+    "@open-mercato/shared": "0.6.4-develop.3944.1.4100aa7fbe"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.4-develop.3929.1.fcf7afece2",
+    "@open-mercato/shared": "0.6.4-develop.3944.1.4100aa7fbe",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"

package/src/lib/__tests__/dev-env-reload.test.ts

@@ -61,7 +61,7 @@ describe('dev env reload helpers', () => {
     expect(environment.REMOVED_LATER).toBeUndefined()
   })
 
-  it('watches generated runtime files for dev restarts', async () => {
+  it('watches generated runtime files when explicitly requested', async () => {
     const generatedDir = path.join(appDir, '.mercato', 'generated')
     fs.mkdirSync(generatedDir, { recursive: true })
     const generatedFile = path.join(generatedDir, 'backend-routes.generated.ts')

package/src/lib/__tests__/generate-watch-structure.test.ts

@@ -0,0 +1,80 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { calculateGenerateWatchStructureChecksum } from '../generate-watch-structure'
+
+function write(filePath: string, content: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, content)
+}
+
+describe('calculateGenerateWatchStructureChecksum', () => {
+  let root: string
+  let appDir: string
+  let pkgModule: string
+  let appModule: string
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'om-generate-watch-'))
+    appDir = path.join(root, 'apps', 'mercato')
+    pkgModule = path.join(root, 'packages', 'core', 'src', 'modules', 'customers')
+    appModule = path.join(appDir, 'src', 'modules', 'customers')
+    write(path.join(appDir, 'src', 'modules.ts'), 'export const enabledModules = []\n')
+    write(path.join(pkgModule, 'index.ts'), 'export const metadata = { id: "customers" }\n')
+    write(path.join(pkgModule, 'backend', 'customers', 'people', 'page.tsx'), 'export default function Page() { return null }\n')
+    write(path.join(pkgModule, 'components', 'detail', 'PersonDetailTabs.tsx'), 'export function PersonDetailTabs() { return null }\n')
+  })
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true })
+  })
+
+  function currentChecksum(): string {
+    return calculateGenerateWatchStructureChecksum({
+      modulesFile: path.join(appDir, 'src', 'modules.ts'),
+      moduleRoots: [{ appBase: appModule, pkgBase: pkgModule }],
+    })
+  }
+
+  it('ignores ordinary component edits outside generator discovery paths', () => {
+    const before = currentChecksum()
+
+    write(path.join(pkgModule, 'components', 'detail', 'PersonDetailTabs.tsx'), 'export function PersonDetailTabs() { return "changed" }\n')
+
+    expect(currentChecksum()).toBe(before)
+  })
+
+  it('changes when a discovered backend page is added', () => {
+    const before = currentChecksum()
+
+    write(path.join(pkgModule, 'backend', 'customers', 'companies', 'page.tsx'), 'export default function Page() { return null }\n')
+
+    expect(currentChecksum()).not.toBe(before)
+  })
+
+  it('changes when route metadata changes', () => {
+    write(path.join(pkgModule, 'backend', 'customers', 'people', 'page.meta.ts'), 'export const metadata = { nav: { label: "People" } }\n')
+    const before = currentChecksum()
+
+    write(path.join(pkgModule, 'backend', 'customers', 'people', 'page.meta.ts'), 'export const metadata = { nav: { label: "Contacts" } }\n')
+
+    expect(currentChecksum()).not.toBe(before)
+  })
+
+  it('changes when inline page metadata changes', () => {
+    write(path.join(pkgModule, 'backend', 'customers', 'people', 'page.tsx'), 'export const metadata = { nav: { label: "People" } }\nexport default function Page() { return null }\n')
+    const before = currentChecksum()
+
+    write(path.join(pkgModule, 'backend', 'customers', 'people', 'page.tsx'), 'export const metadata = { nav: { label: "Contacts" } }\nexport default function Page() { return null }\n')
+
+    expect(currentChecksum()).not.toBe(before)
+  })
+
+  it('changes when a convention file changes', () => {
+    const before = currentChecksum()
+
+    write(path.join(pkgModule, 'acl.ts'), 'export const features = [{ id: "customers.view" }]\n')
+
+    expect(currentChecksum()).not.toBe(before)
+  })
+})

package/src/lib/generate-watch-structure.ts

@@ -0,0 +1,170 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  MODULE_CODE_EXTENSIONS,
+  SCAN_CONFIGS,
+  scanModuleDir,
+  stripModuleCodeExtension,
+  type ModuleRoots,
+} from './generators/scanner'
+
+const STRUCTURAL_CONVENTION_FILES = [
+  'index.ts',
+  'cli.ts',
+  'di.ts',
+  'acl.ts',
+  'setup.ts',
+  'encryption.ts',
+  'ce.ts',
+  'search.ts',
+  'events.ts',
+  'notifications.ts',
+  'notifications.client.ts',
+  'notifications.handlers.ts',
+  'translations.ts',
+  'generators.ts',
+  'ai-tools.ts',
+  'ai-agents.ts',
+  'analytics.ts',
+  'workflows.ts',
+  'inbox-actions.ts',
+  'message-types.ts',
+  'message-objects.ts',
+  'integration.ts',
+  'security.mfa-providers.ts',
+  'security.sudo.ts',
+  'data/entities.ts',
+  'data/extensions.ts',
+  'data/fields.ts',
+  'data/enrichers.ts',
+  'data/guards.ts',
+  'api/interceptors.ts',
+  'commands/interceptors.ts',
+  'widgets/components.ts',
+  'widgets/injection-table.ts',
+  'frontend/middleware.ts',
+  'backend/middleware.ts',
+] as const
+
+const CONTENT_SENSITIVE_SCAN_CONFIGS = [
+  SCAN_CONFIGS.apiRoutes,
+  SCAN_CONFIGS.apiPlainFiles,
+  SCAN_CONFIGS.subscribers,
+  SCAN_CONFIGS.workers,
+  SCAN_CONFIGS.dashboardWidgets,
+  SCAN_CONFIGS.injectionWidgets,
+] as const
+
+const ROUTE_SHAPE_SCAN_CONFIGS = [
+  SCAN_CONFIGS.frontendPages,
+  SCAN_CONFIGS.backendPages,
+] as const
+
+function checksum(value: string): string {
+  return crypto.createHash('md5').update(value).digest('hex')
+}
+
+function fileRecord(filePath: string, base: string, mode: 'content' | 'shape'): string | null {
+  if (!fs.existsSync(filePath)) return null
+  let stat: fs.Stats
+  try {
+    stat = fs.statSync(filePath)
+  } catch {
+    return null
+  }
+  if (!stat.isFile()) return null
+  const rel = path.relative(base, filePath).replace(/\\/g, '/')
+  if (mode === 'shape') {
+    return `file:${rel}`
+  }
+  try {
+    return `file:${rel}:${stat.size}:${checksum(fs.readFileSync(filePath, 'utf8'))}`
+  } catch {
+    return `file:${rel}:unreadable`
+  }
+}
+
+function resolveCodeFile(base: string, relativePath: string): string | null {
+  const stripped = stripModuleCodeExtension(relativePath)
+  const candidates = MODULE_CODE_EXTENSIONS.map((extension) => `${stripped}${extension}`)
+  for (const candidate of candidates) {
+    const filePath = path.join(base, ...candidate.split('/'))
+    if (fs.existsSync(filePath)) return filePath
+  }
+  return null
+}
+
+function hasInlinePageMetadata(filePath: string): boolean {
+  try {
+    const source = fs.readFileSync(filePath, 'utf8')
+    return /\bexport\s+(?:const|let|var|function|class)\s+metadata\b/.test(source)
+      || /\bexport\s+\{[^}]*\bmetadata\b[^}]*\}/.test(source)
+  } catch {
+    return false
+  }
+}
+
+function addConventionRecords(records: string[], roots: ModuleRoots): void {
+  for (const base of [roots.pkgBase, roots.appBase]) {
+    records.push(`module-root:${base}:${fs.existsSync(base) ? 'present' : 'missing'}`)
+    for (const relativePath of STRUCTURAL_CONVENTION_FILES) {
+      const filePath = resolveCodeFile(base, relativePath)
+      if (!filePath) {
+        records.push(`missing:${base}:${relativePath}`)
+        continue
+      }
+      const record = fileRecord(filePath, base, 'content')
+      if (record) records.push(record)
+    }
+  }
+}
+
+function addScannedRecords(records: string[], roots: ModuleRoots): void {
+  for (const config of CONTENT_SENSITIVE_SCAN_CONFIGS) {
+    for (const scanned of scanModuleDir(roots, config)) {
+      const base = scanned.fromApp ? roots.appBase : roots.pkgBase
+      const filePath = path.join(base, ...config.folder.split('/'), ...scanned.relPath.split('/'))
+      const record = fileRecord(filePath, base, 'content')
+      if (record) records.push(`${config.folder}:${record}`)
+    }
+  }
+
+  for (const config of ROUTE_SHAPE_SCAN_CONFIGS) {
+    for (const scanned of scanModuleDir(roots, config)) {
+      const base = scanned.fromApp ? roots.appBase : roots.pkgBase
+      const folderPath = path.join(base, ...config.folder.split('/'))
+      const filePath = path.join(folderPath, ...scanned.relPath.split('/'))
+      const pageRecord = fileRecord(filePath, base, hasInlinePageMetadata(filePath) ? 'content' : 'shape')
+      if (pageRecord) records.push(`${config.folder}:${pageRecord}`)
+
+      const dir = path.dirname(filePath)
+      const stem = stripModuleCodeExtension(path.basename(filePath))
+      const metaCandidates = stem === 'page'
+        ? ['page.meta', 'meta']
+        : [`${stem}.meta`, 'meta']
+      for (const candidate of metaCandidates) {
+        const metaPath = resolveCodeFile(dir, candidate)
+        if (!metaPath) continue
+        const record = fileRecord(metaPath, base, 'content')
+        if (record) records.push(`${config.folder}:meta:${record}`)
+      }
+    }
+  }
+}
+
+export function calculateGenerateWatchStructureChecksum(options: {
+  modulesFile: string
+  moduleRoots: ModuleRoots[]
+}): string {
+  const records: string[] = []
+  const modulesRecord = fileRecord(options.modulesFile, path.dirname(options.modulesFile), 'content')
+  records.push(modulesRecord ?? `missing:${options.modulesFile}`)
+
+  for (const roots of options.moduleRoots) {
+    addConventionRecords(records, roots)
+    addScannedRecords(records, roots)
+  }
+
+  return checksum(records.sort((a, b) => a.localeCompare(b)).join('\n'))
+}

package/src/mercato.ts

@@ -32,7 +32,7 @@ import {
 import { parseModuleInstallArgs } from './lib/module-install-args'
 import { resolveNextBuildIdCandidate } from './lib/next-build-id'
 import { acquireServerStartLock } from './lib/server-start-lock'
-import { createDevEnvReloader, watchDevEnvFiles, watchDevRuntimeFiles } from './lib/dev-env-reload'
+import { createDevEnvReloader, watchDevEnvFiles } from './lib/dev-env-reload'
 // Lazy-imported to avoid pulling in `testcontainers` (devDependency) at startup
 const lazyIntegration = () => import('./lib/testing/integration')
 import type { ChildProcess } from 'node:child_process'
@@ -341,6 +341,92 @@ type DevServerRestartResult = {
 
 type DevServerExitResult = ManagedProcessExitResult | DevServerRestartResult
 
+function resolveDevRuntimeBaseUrl(environment: NodeJS.ProcessEnv = process.env): string {
+  const configured =
+    environment.APP_URL
+    ?? environment.NEXT_PUBLIC_APP_URL
+    ?? environment.NEXTAUTH_URL
+  if (configured?.trim()) {
+    return configured.trim().replace(/\/+$/, '')
+  }
+  return `http://localhost:${environment.PORT?.trim() || '3000'}`
+}
+
+function writeDevSplashChildState(state: Record<string, unknown>): void {
+  if (process.env.OM_DEV_SPLASH_RUNTIME_WRAPPER === '1') return
+  const stateFile = process.env.OM_DEV_SPLASH_CHILD_STATE_FILE
+  if (!stateFile?.trim()) return
+
+  try {
+    fs.mkdirSync(path.dirname(stateFile), { recursive: true })
+    fs.writeFileSync(stateFile, `${JSON.stringify({
+      mode: process.env.OM_DEV_SPLASH_MODE || 'dev',
+      failed: false,
+      failureLines: [],
+      failureCommand: null,
+      ...state,
+    }, null, 2)}\n`)
+  } catch {
+    // Splash state is best-effort; terminal logs remain authoritative.
+  }
+}
+
+function writeDevSplashRuntimeStarting(detail = 'Starting Next.js dev server'): void {
+  writeDevSplashChildState({
+    phase: 'Preparing app runtime',
+    detail,
+    ready: false,
+    readyUrl: null,
+    loginUrl: null,
+    progressLabel: 'Launching app runtime',
+    activity: detail,
+  })
+}
+
+function resolveSplashProgressFallback(): { current: number; total: number } {
+  const current = Number.parseInt(process.env.OM_DEV_SPLASH_STAGE_CURRENT ?? '', 10)
+  const total = Number.parseInt(process.env.OM_DEV_SPLASH_STAGE_TOTAL ?? '', 10)
+  if (Number.isFinite(current) && Number.isFinite(total) && total > 0) {
+    return { current, total }
+  }
+  if (process.env.OM_DEV_SPLASH_MODE === 'greenfield' || process.env.OM_DEV_SPLASH_MODE === 'setup') {
+    return { current: 5, total: 5 }
+  }
+  return { current: 3, total: 3 }
+}
+
+function writeDevSplashRuntimeRestarting(reason: string): void {
+  const progress = resolveSplashProgressFallback()
+  writeDevSplashChildState({
+    phase: 'App runtime is restarting',
+    detail: `Reason: ${reason}`,
+    ready: false,
+    readyUrl: null,
+    loginUrl: null,
+    progressCurrent: progress.current,
+    progressTotal: progress.total,
+    progressLabel: 'Restarting app runtime',
+    activity: `App runtime restart: ${reason}`,
+  })
+}
+
+function writeDevSplashRuntimeReady(reason?: string): void {
+  const readyUrl = resolveDevRuntimeBaseUrl()
+  const progress = resolveSplashProgressFallback()
+  writeDevSplashChildState({
+    phase: 'App is ready',
+    detail: reason ? `Restart completed after ${reason}` : 'Next.js dev server is ready',
+    ready: true,
+    readyUrl,
+    loginUrl: `${readyUrl}/login`,
+    progressCurrent: progress.current,
+    progressTotal: progress.total,
+    progressPercent: 100,
+    progressLabel: 'App is ready',
+    activity: reason ? `Restart completed after ${reason}` : 'App runtime is ready',
+  })
+}
+
 type ModuleCommandLookupResult =
   | {
       status: 'ok'
@@ -601,18 +687,17 @@ async function runGeneratorSuite(quiet: boolean): Promise<void> {
 function createGenerateWatchChecksumFn(): () => Promise<string> {
   return async () => {
     const { createResolver } = await import('./lib/resolver')
-    const { calculateStructureChecksum } = await import('./lib/utils')
+    const { calculateGenerateWatchStructureChecksum } = await import('./lib/generate-watch-structure')
     const resolver = createResolver()
-    const tracked = new Set<string>([
-      path.join(resolver.getAppDir(), 'src', 'modules.ts'),
-      path.join(resolver.getAppDir(), 'src', 'modules'),
-    ])
+    const moduleRoots = []
     for (const entry of resolver.loadEnabledModules()) {
       const roots = resolver.getModulePaths(entry)
-      tracked.add(roots.appBase)
-      tracked.add(roots.pkgBase)
+      moduleRoots.push({ appBase: roots.appBase, pkgBase: roots.pkgBase })
     }
-    return calculateStructureChecksum(Array.from(tracked))
+    return calculateGenerateWatchStructureChecksum({
+      modulesFile: path.join(resolver.getAppDir(), 'src', 'modules.ts'),
+      moduleRoots,
+    })
   }
 }
 
@@ -1694,6 +1779,7 @@ export async function run(argv = process.argv) {
           let activeLazySupervisor: ReturnType<typeof startLazyWorkerSupervisor> | null = null
           let activeLazySchedulerSupervisor: ReturnType<typeof startLazySchedulerSupervisor> | null = null
           let activeGenerateWatcher: GenerateWatcherHandle | null = null
+          let lastRestartReason: string | null = null
           const generateWatcherMode: GenerateWatcherMode = resolveGenerateWatcherMode(process.env)
           const envReloader = createDevEnvReloader(appDir, process.env, initialProcessEnvironmentEntries)
 
@@ -1787,14 +1873,6 @@ export async function run(argv = process.argv) {
               filePath,
             })
           })
-          const stopRuntimeWatcher = watchDevRuntimeFiles(appDir, (filePath) => {
-            devRestartPromiseResolve?.({
-              label: 'Runtime graph change',
-              restart: true,
-              filePath,
-            })
-          })
-
           const waitForDevRestart = (): Promise<DevServerRestartResult> =>
             new Promise((resolve) => {
               devRestartPromiseResolve = resolve
@@ -1802,6 +1880,11 @@ export async function run(argv = process.argv) {
 
           const startNextDev = (runtimeEnv: NodeJS.ProcessEnv): Promise<ManagedProcessExitResult> =>
             new Promise((resolve) => {
+              writeDevSplashRuntimeStarting(
+                lastRestartReason
+                  ? `Restarting Next.js dev server. Reason: ${lastRestartReason}`
+                  : 'Starting Next.js dev server',
+              )
               const nextProcess = spawn('node', [nextBin, 'dev', '--turbopack'], {
                 stdio: ['inherit', 'pipe', 'pipe'],
                 env: runtimeEnv,
@@ -1810,11 +1893,17 @@ export async function run(argv = process.argv) {
               processes.push(nextProcess)
 
               let combinedOutput = ''
+              let reportedReady = false
               const appendOutput = (chunk: string) => {
                 combinedOutput += chunk
                 if (combinedOutput.length > 32_768) {
                   combinedOutput = combinedOutput.slice(-32_768)
                 }
+                if (!reportedReady && /\bready in\b/i.test(chunk)) {
+                  reportedReady = true
+                  writeDevSplashRuntimeReady(lastRestartReason ?? undefined)
+                  lastRestartReason = null
+                }
               }
 
               nextProcess.stdout?.on('data', (chunk: Buffer | string) => {
@@ -1831,6 +1920,8 @@ export async function run(argv = process.argv) {
               nextProcess.on('exit', async (code, signal) => {
                 if (!didRetryCorruptedTurbopackCache && isTurbopackCacheCorruption(combinedOutput)) {
                   didRetryCorruptedTurbopackCache = true
+                  lastRestartReason = 'corrupted Turbopack dev cache'
+                  writeDevSplashRuntimeRestarting(lastRestartReason)
                   console.log('[server] Detected corrupted Turbopack dev cache. Clearing .mercato/next/dev and restarting Next.js once...')
                   removeTurbopackDevCache(appDir)
                   return resolve(await startNextDev(runtimeEnv))
@@ -1934,6 +2025,10 @@ export async function run(argv = process.argv) {
               }
 
               const firstExit = await Promise.race(managedExitPromises)
+              if (isDevServerRestartResult(firstExit)) {
+                lastRestartReason = `${firstExit.label.toLowerCase()} (${path.basename(firstExit.filePath)})`
+                writeDevSplashRuntimeRestarting(lastRestartReason)
+              }
               await cleanupAndWait()
               devRestartPromiseResolve = null
 
@@ -1950,7 +2045,6 @@ export async function run(argv = process.argv) {
             }
           } finally {
             stopEnvWatcher()
-            stopRuntimeWatcher()
           }
         },
       },