@open-mercato/cli 0.6.8-develop.6891.1.4dca3f1ad3 → 0.6.8-develop.6892.1.f179677788

package/src/lib/dev-supervisor-manifest.ts

@@ -0,0 +1,142 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { ModuleWorker } from '@open-mercato/shared/modules/registry'
+
+export const DEV_SUPERVISOR_MANIFEST_FILE = 'dev-supervisor.generated.json'
+export const DEV_SUPERVISOR_MANIFEST_VERSION = 1
+
+export type DevSupervisorWorkerDescriptor = Pick<
+  ModuleWorker,
+  'id' | 'moduleId' | 'queue' | 'concurrency'
+>
+
+export type DevSupervisorSchedulerStartStatus =
+  | 'ok'
+  | 'missing-module'
+  | 'missing-cli'
+  | 'missing-command'
+
+export type DevSupervisorManifest = {
+  version: typeof DEV_SUPERVISOR_MANIFEST_VERSION
+  workers: DevSupervisorWorkerDescriptor[]
+  schedulerStartStatus: DevSupervisorSchedulerStartStatus
+  requiresFullBootstrap: boolean
+}
+
+let registeredManifest: DevSupervisorManifest | null = null
+
+function manifestError(filePath: string, detail: string): Error {
+  return new Error(
+    `Invalid generated dev supervisor manifest at ${filePath}: ${detail}. ` +
+      'Run `yarn generate` and retry.',
+  )
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function parseWorkerDescriptor(
+  value: unknown,
+  index: number,
+  filePath: string,
+): DevSupervisorWorkerDescriptor {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw manifestError(filePath, `workers[${index}] must be an object`)
+  }
+
+  const worker = value as Record<string, unknown>
+  if (!isNonEmptyString(worker.id)) {
+    throw manifestError(filePath, `workers[${index}].id must be a non-empty string`)
+  }
+  if (!isNonEmptyString(worker.queue)) {
+    throw manifestError(filePath, `workers[${index}].queue must be a non-empty string`)
+  }
+  if (typeof worker.concurrency !== 'number' || !Number.isFinite(worker.concurrency)) {
+    throw manifestError(filePath, `workers[${index}].concurrency must be a finite number`)
+  }
+  if (worker.moduleId !== undefined && !isNonEmptyString(worker.moduleId)) {
+    throw manifestError(filePath, `workers[${index}].moduleId must be a non-empty string when present`)
+  }
+
+  return {
+    id: worker.id,
+    ...(worker.moduleId === undefined ? {} : { moduleId: worker.moduleId }),
+    queue: worker.queue,
+    concurrency: worker.concurrency,
+  }
+}
+
+function parseManifest(value: unknown, filePath: string): DevSupervisorManifest {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw manifestError(filePath, 'root value must be an object')
+  }
+
+  const manifest = value as Record<string, unknown>
+  if (manifest.version !== DEV_SUPERVISOR_MANIFEST_VERSION) {
+    throw manifestError(
+      filePath,
+      `unsupported version ${String(manifest.version)} (expected ${DEV_SUPERVISOR_MANIFEST_VERSION})`,
+    )
+  }
+  if (!Array.isArray(manifest.workers)) {
+    throw manifestError(filePath, 'workers must be an array')
+  }
+
+  const schedulerStartStatus = manifest.schedulerStartStatus
+  if (
+    schedulerStartStatus !== 'ok' &&
+    schedulerStartStatus !== 'missing-module' &&
+    schedulerStartStatus !== 'missing-cli' &&
+    schedulerStartStatus !== 'missing-command'
+  ) {
+    throw manifestError(filePath, 'schedulerStartStatus is invalid')
+  }
+
+  return {
+    version: DEV_SUPERVISOR_MANIFEST_VERSION,
+    workers: manifest.workers.map((worker, index) => parseWorkerDescriptor(worker, index, filePath)),
+    schedulerStartStatus,
+    // Version-1 manifests produced before this safety marker existed cannot
+    // prove that worker/CLI overrides were accounted for. Preserve the old
+    // full-bootstrap behavior until `yarn generate` writes an explicit false.
+    requiresFullBootstrap: manifest.requiresFullBootstrap !== false,
+  }
+}
+
+export function canUseLightweightDevSupervisor(manifest: DevSupervisorManifest): boolean {
+  return manifest.requiresFullBootstrap === false
+}
+
+export function loadDevSupervisorManifest(appDir: string): DevSupervisorManifest {
+  const filePath = path.join(appDir, '.mercato', 'generated', DEV_SUPERVISOR_MANIFEST_FILE)
+  let source: string
+  try {
+    source = fs.readFileSync(filePath, 'utf8')
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    throw manifestError(filePath, `file could not be read (${detail})`)
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(source)
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    throw manifestError(filePath, `JSON could not be parsed (${detail})`)
+  }
+
+  return parseManifest(parsed, filePath)
+}
+
+export function registerDevSupervisorManifest(manifest: DevSupervisorManifest): void {
+  registeredManifest = manifest
+}
+
+export function getRegisteredDevSupervisorManifest(): DevSupervisorManifest | null {
+  return registeredManifest
+}
+
+export function resetDevSupervisorManifestForTests(): void {
+  registeredManifest = null
+}

package/src/lib/generators/__tests__/entity-ids.test.ts

@@ -201,6 +201,38 @@ describe('generateEntityIds', () => {
     expect(registry).not.toContain("import * as sales_order from './entities/sales_order/index'")
   })
 
+  it('preserves every generated entity output mtime when the output bytes are unchanged', async () => {
+    const moduleEntry: ModuleEntry = { id: 'orders', from: '@open-mercato/core' }
+    const entitiesFile = path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'orders', 'data', 'entities.ts')
+    fs.mkdirSync(path.dirname(entitiesFile), { recursive: true })
+    fs.writeFileSync(entitiesFile, 'export class SalesOrder { id!: string; totalGross!: number }\n')
+
+    const resolver = createMockResolver(tmpDir, [moduleEntry])
+    const firstResult = await generateEntityIds({ resolver, quiet: true })
+    const outputDir = resolver.getOutputDir()
+    const generatedFiles = [
+      path.join(outputDir, 'entities.ids.generated.ts'),
+      path.join(outputDir, 'entity-fields-registry.ts'),
+      path.join(outputDir, 'entities', 'sales_order', 'index.ts'),
+    ]
+    const oldTime = new Date(Date.now() - 60_000)
+    for (const filePath of generatedFiles) {
+      fs.utimesSync(filePath, oldTime, oldTime)
+    }
+    const mtimesBefore = new Map(
+      generatedFiles.map((filePath) => [filePath, fs.statSync(filePath).mtimeMs]),
+    )
+
+    const secondResult = await generateEntityIds({ resolver, quiet: true })
+
+    expect(firstResult.filesWritten).toEqual(expect.arrayContaining(generatedFiles))
+    expect(secondResult.filesWritten).toEqual([])
+    expect(secondResult.filesUnchanged).toEqual(expect.arrayContaining(generatedFiles))
+    for (const filePath of generatedFiles) {
+      expect(fs.statSync(filePath).mtimeMs).toBe(mtimesBefore.get(filePath))
+    }
+  })
+
   it('reuses package generated entity metadata in standalone mode', async () => {
     const moduleEntry: ModuleEntry = { id: 'directory', from: '@open-mercato/core' }
     const packageRoot = path.join(tmpDir, 'node_modules', '@open-mercato', 'core')

package/src/lib/generators/__tests__/module-subset.test.ts

@@ -578,6 +578,66 @@ export { POST, PUT, DELETE }
     expect(apiRoutes).toContain('methods: ["GET", "POST", "PUT", "DELETE"]')
   })
 
+  it('partitions API and backend loader graphs while preserving legacy manifests', async () => {
+    scaffoldModule(tmpDir, 'customers', 'pkg', ['api/people/route.ts', 'backend/people/page.tsx'])
+    scaffoldModule(tmpDir, 'sales', 'pkg', ['api/orders/route.ts', 'backend/orders/page.tsx'])
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'customers', 'api', 'people', 'route.ts'),
+      `export const metadata = { path: '/customers/people' }\nexport function GET() { return null }\n`,
+    )
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'customers', 'backend', 'people', 'page.tsx'),
+      `export const metadata = { pageTitle: 'People' }\nexport default function Page() { return null }\n`,
+    )
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'sales', 'api', 'orders', 'route.ts'),
+      `export const metadata = { path: '/sales/orders' }\nexport function POST() { return null }\n`,
+    )
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'sales', 'backend', 'orders', 'page.tsx'),
+      `export const metadata = { pageTitle: 'Orders' }\nexport default function Page() { return null }\n`,
+    )
+
+    const resolver = createMockResolver(tmpDir, [
+      { id: 'customers', from: '@open-mercato/core' },
+      { id: 'sales', from: '@open-mercato/core' },
+    ])
+    await generateModuleRegistry({ resolver, quiet: true })
+
+    const outputDir = path.join(tmpDir, 'output', 'generated')
+    const generatedNames = fs.readdirSync(outputDir)
+    const apiShardNames = generatedNames.filter((name) => /^api-route-shard\..+\.generated\.ts$/.test(name))
+    const backendShardNames = generatedNames.filter((name) => /^backend-route-shard\..+\.generated\.ts$/.test(name))
+    const apiShards = apiShardNames.map((name) => fs.readFileSync(path.join(outputDir, name), 'utf8'))
+    const backendShards = backendShardNames.map((name) => fs.readFileSync(path.join(outputDir, name), 'utf8'))
+
+    expect(apiShardNames).toHaveLength(2)
+    expect(backendShardNames).toHaveLength(2)
+    expect(apiShards.filter((source) => source.includes('/customers/people'))).toHaveLength(1)
+    expect(apiShards.filter((source) => source.includes('/sales/orders'))).toHaveLength(1)
+    expect(backendShards.filter((source) => source.includes('/backend/people'))).toHaveLength(1)
+    expect(backendShards.filter((source) => source.includes('/backend/orders'))).toHaveLength(1)
+
+    const apiLoader = readGenerated(tmpDir, 'api-route-shards.generated.ts')!
+    const backendLoader = readGenerated(tmpDir, 'backend-route-shards.generated.ts')!
+    expect(apiLoader).not.toContain('@open-mercato/core/modules/customers/api')
+    expect(backendLoader).not.toContain('@open-mercato/core/modules/customers/backend')
+
+    const apiMetadata = readGenerated(tmpDir, 'api-route-metadata.generated.ts')!
+    const backendMetadata = readGenerated(tmpDir, 'backend-route-metadata.generated.ts')!
+    expect(apiMetadata).not.toContain('load: async')
+    expect(backendMetadata).not.toContain('load: async')
+    expect(readGenerated(tmpDir, 'api-routes.generated.ts')).toContain('/customers/people')
+    expect(readGenerated(tmpDir, 'backend-routes.generated.ts')).toContain('/backend/orders')
+
+    const customersOnlyResolver = createMockResolver(tmpDir, [
+      { id: 'customers', from: '@open-mercato/core' },
+    ])
+    await generateModuleRegistry({ resolver: customersOnlyResolver, quiet: true })
+    const remainingApiShards = fs.readdirSync(outputDir).filter((name) => /^api-route-shard\..+\.generated\.ts$/.test(name))
+    expect(remainingApiShards).toHaveLength(1)
+  })
+
   it('keeps all HTTP methods for route.ts files that destructure-export crud handlers', async () => {
     scaffoldModule(tmpDir, 'example', 'pkg', ['api/todos/route.ts'])
     touchFile(
@@ -1062,6 +1122,85 @@ export default async function handle(): Promise<void> {}
     expect(output).toContain("workers:")
   })
 
+  it('writes a content-stable primitive dev supervisor manifest', async () => {
+    scaffoldModule(tmpDir, 'events', 'pkg', ['workers/dispatch.ts'])
+    scaffoldModule(tmpDir, 'scheduler', 'pkg', ['cli.ts'])
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'events', 'workers', 'dispatch.ts'),
+      `export const metadata = { id: 'events:dispatch', queue: 'events', concurrency: 3 }\nexport default async function dispatch() {}\n`,
+    )
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'scheduler', 'cli.ts'),
+      `export default [{ command: 'start', run() {} }]\n`,
+    )
+    const resolver = createMockResolver(tmpDir, [
+      { id: 'events', from: '@open-mercato/core' },
+      { id: 'scheduler', from: '@open-mercato/core' },
+    ])
+
+    const first = await generateModuleRegistryCli({ resolver, quiet: true })
+    const manifestPath = path.join(tmpDir, 'output', 'generated', 'dev-supervisor.generated.json')
+    expect(JSON.parse(fs.readFileSync(manifestPath, 'utf8'))).toEqual({
+      version: 1,
+      workers: [{
+        id: 'events:dispatch',
+        moduleId: 'events',
+        queue: 'events',
+        concurrency: 3,
+      }],
+      schedulerStartStatus: 'ok',
+      requiresFullBootstrap: false,
+    })
+    expect(first.filesWritten).toContain(manifestPath)
+
+    const second = await generateModuleRegistryCli({ resolver, quiet: true })
+    expect(second.filesUnchanged).toContain(manifestPath)
+    expect(second.filesWritten).not.toContain(manifestPath)
+  })
+
+  it('falls back to full bootstrap for worker overrides and computed scheduler commands', async () => {
+    scaffoldModule(tmpDir, 'events', 'pkg', ['workers/dispatch.ts'])
+    scaffoldModule(tmpDir, 'scheduler', 'pkg', ['cli.ts'])
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'events', 'workers', 'dispatch.ts'),
+      `export const metadata = { id: 'events:dispatch', queue: 'events', concurrency: 3 }\nexport default async function dispatch() {}\n`,
+    )
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'scheduler', 'cli.ts'),
+      `const command = 'start'\nexport default [{ command, run() {} }]\n`,
+    )
+    const resolver = createMockResolver(tmpDir, [
+      { id: 'events', from: '@open-mercato/core', devSupervisorRequiresFullBootstrap: true },
+      { id: 'scheduler', from: '@open-mercato/core' },
+    ])
+
+    await generateModuleRegistryCli({ resolver, quiet: true })
+    const manifestPath = path.join(tmpDir, 'output', 'generated', 'dev-supervisor.generated.json')
+    expect(JSON.parse(fs.readFileSync(manifestPath, 'utf8'))).toMatchObject({
+      schedulerStartStatus: 'missing-command',
+      requiresFullBootstrap: true,
+    })
+  })
+
+  it('falls back to full bootstrap when app code registers programmatic worker overrides', async () => {
+    scaffoldModule(tmpDir, 'events', 'pkg', ['workers/dispatch.ts'])
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'events', 'workers', 'dispatch.ts'),
+      `export const metadata = { id: 'events:dispatch', queue: 'events', concurrency: 3 }\nexport default async function dispatch() {}\n`,
+    )
+    touchFile(
+      path.join(tmpDir, 'app', 'src', 'bootstrap-overrides.ts'),
+      `import { applyWorkerOverrides as overrideWorkers } from '@open-mercato/shared/modules/overrides'\noverrideWorkers({ 'events:dispatch': null })\n`,
+    )
+    const resolver = createMockResolver(tmpDir, [
+      { id: 'events', from: '@open-mercato/core' },
+    ])
+
+    await generateModuleRegistryCli({ resolver, quiet: true })
+    const manifestPath = path.join(tmpDir, 'output', 'generated', 'dev-supervisor.generated.json')
+    expect(JSON.parse(fs.readFileSync(manifestPath, 'utf8')).requiresFullBootstrap).toBe(true)
+  })
+
   it('handles disabling a module that was previously enabled', async () => {
     scaffoldModule(tmpDir, 'keep_mod', 'pkg', [
       'subscribers/handler.ts',
@@ -1480,6 +1619,115 @@ describe('generateModuleRegistryApp with module subsets', () => {
     const bootstrapOutput = readGenerated(tmpDir, 'modules.bootstrap.generated.ts')
     expect(bootstrapOutput).not.toBeNull()
     expect(bootstrapOutput).toContain('export const modules: Module[] = [')
+
+    const i18nLoadersOutput = readGenerated(tmpDir, 'modules.i18n.loaders.generated.ts')
+    expect(i18nLoadersOutput).toContain('export async function loadI18nModules')
+    expect(i18nLoadersOutput).toContain('default:')
+    expect(i18nLoadersOutput).toContain('return []')
+  })
+
+  it('keeps the legacy i18n registry while emitting deterministic locale-specific shards', async () => {
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'localized', 'i18n', 'en.json'),
+      JSON.stringify({ localized: { title: 'Core title' } }),
+    )
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'localized', 'i18n', 'pl.json'),
+      JSON.stringify({ localized: { title: 'Tytuł' } }),
+    )
+    touchFile(
+      path.join(tmpDir, 'app', 'src', 'modules', 'localized', 'i18n', 'en.json'),
+      JSON.stringify({ localized: { title: 'App title' } }),
+    )
+    touchFile(
+      path.join(tmpDir, 'packages', 'core', 'src', 'modules', 'localized', 'i18n', '.hardcoded-allowlist.json'),
+      JSON.stringify({ allow: ['framework chrome'] }),
+    )
+
+    const resolver = createMockResolver(tmpDir, [
+      { id: 'localized', from: '@open-mercato/core' },
+    ])
+    const result = await generateModuleRegistryApp({ resolver, quiet: true })
+
+    expect(result.errors).toEqual([])
+
+    const legacyI18nOutput = readGenerated(tmpDir, 'modules.i18n.generated.ts')!
+    expect(legacyI18nOutput).toContain('@open-mercato/core/modules/localized/i18n/en.json')
+    expect(legacyI18nOutput).toContain('@/modules/localized/i18n/en.json')
+    expect(legacyI18nOutput).toContain('@open-mercato/core/modules/localized/i18n/pl.json')
+    expect(legacyI18nOutput).toContain('export const modules: Module[] = [')
+
+    const bootstrapOutput = readGenerated(tmpDir, 'modules.bootstrap.generated.ts')!
+    expect(bootstrapOutput).not.toContain('/i18n/')
+    expect(bootstrapOutput).not.toContain('translations:')
+
+    const loadersOutput = readGenerated(tmpDir, 'modules.i18n.loaders.generated.ts')!
+    expect(loadersOutput).not.toContain('.json')
+    expect(loadersOutput).toContain('case "en":')
+    expect(loadersOutput).toContain('import("./modules.i18n.en.generated")')
+    expect(loadersOutput).toContain('case "pl":')
+    expect(loadersOutput).not.toContain('hardcoded-allowlist')
+    expect(loadersOutput.indexOf('case "en":')).toBeLessThan(loadersOutput.indexOf('case "pl":'))
+
+    const enShard = readGenerated(tmpDir, 'modules.i18n.en.generated.ts')!
+    expect(enShard).toContain('@open-mercato/core/modules/localized/i18n/en.json')
+    expect(enShard).toContain('@/modules/localized/i18n/en.json')
+    expect(enShard).not.toContain('/i18n/pl.json')
+    expect(enShard).toContain('id: "localized"')
+    expect(enShard).toContain('translations:')
+
+    const plShard = readGenerated(tmpDir, 'modules.i18n.pl.generated.ts')!
+    expect(plShard).toContain('@open-mercato/core/modules/localized/i18n/pl.json')
+    expect(plShard).not.toContain('/i18n/en.json')
+    expect(plShard).not.toContain('@/modules/localized/i18n/pl.json')
+    expect(readGenerated(tmpDir, 'modules.i18n._hardcoded-allowlist.generated.ts')).toBeNull()
+
+    const secondResult = await generateModuleRegistryApp({ resolver, quiet: true })
+    expect(secondResult.filesWritten).toEqual([])
+
+    fs.rmSync(path.join(
+      tmpDir,
+      'packages',
+      'core',
+      'src',
+      'modules',
+      'localized',
+      'i18n',
+      'pl.json',
+    ))
+    await generateModuleRegistryApp({ resolver, quiet: true })
+    expect(readGenerated(tmpDir, 'modules.i18n.pl.generated.ts')).toBeNull()
+    expect(fs.existsSync(path.join(
+      tmpDir,
+      'output',
+      'generated',
+      'modules.i18n.pl.generated.checksum',
+    ))).toBe(false)
+    expect(readGenerated(tmpDir, 'modules.i18n.loaders.generated.ts')).not.toContain('case "pl":')
+  })
+
+  it('uses standalone source-mirror translations in locale-specific shards', async () => {
+    touchFile(
+      path.join(tmpDir, 'node_modules', 'pkg', 'src', 'modules', 'customers', 'i18n', 'en.json'),
+      JSON.stringify({ customers: { people: { title: 'People' } } }),
+    )
+    touchFile(
+      path.join(tmpDir, 'node_modules', 'pkg', 'dist', 'modules', 'customers', 'index.js'),
+      'export const metadata = { id: "customers" }\n',
+    )
+
+    const resolver = createStandaloneMockResolver(tmpDir, [
+      { id: 'customers', from: '@open-mercato/core' },
+    ])
+    const result = await generateModuleRegistryApp({ resolver, quiet: true })
+
+    expect(result.errors).toEqual([])
+    const shard = fs.readFileSync(
+      path.join(tmpDir, '.mercato', 'generated', 'modules.i18n.en.generated.ts'),
+      'utf8',
+    )
+    expect(shard).toContain('@open-mercato/core/modules/customers/i18n/en.json')
+    expect(shard).toContain('id: "customers"')
   })
 
   it('app output excludes CLI commands and keeps lazy workers/subscribers', async () => {

package/src/lib/generators/__tests__/output-snapshots.test.ts

@@ -829,12 +829,12 @@ describe('generator output compatibility', () => {
 
     const content = readGenerated('bootstrap-registrations.generated.ts')
     expect(content).not.toBeNull()
-    expect(content).toContain(`import { backendRoutes } from "./backend-routes.generated"`)
+    expect(content).toContain(`import { backendRouteFacades } from "./backend-route-shards.generated"`)
     expect(content).toContain(`import { frontendRoutes } from "./frontend-routes.generated"`)
     expect(content).toContain(
       `import { registerBackendRouteManifests, registerFrontendRouteManifests } from '@open-mercato/shared/modules/registry'`,
     )
-    expect(content).toMatch(/export function runBootstrapRegistrations\(\): void \{[\s\S]*registerBackendRouteManifests\(backendRoutes\)[\s\S]*\}/)
+    expect(content).toMatch(/export function runBootstrapRegistrations\(\): void \{[\s\S]*registerBackendRouteManifests\(backendRouteFacades\)[\s\S]*\}/)
     expect(content).toMatch(/export function runBootstrapRegistrations\(\): void \{[\s\S]*registerFrontendRouteManifests\(frontendRoutes\)[\s\S]*\}/)
   })
 
@@ -846,6 +846,6 @@ describe('generator output compatibility', () => {
 
     const content = readGenerated('bootstrap-registrations.generated.ts')
     expect(content).not.toBeNull()
-    expect(content).toContain(`registerBackendRouteManifests(backendRoutes)`)
+    expect(content).toContain(`registerBackendRouteManifests(backendRouteFacades)`)
   })
 })

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

@@ -0,0 +1,62 @@
+import {
+  getRouteManifestShardKey,
+  renderRouteManifestShardOutputs,
+  renderRouteMetadataOutput,
+} from '../route-manifest-shards'
+
+describe('route manifest shards', () => {
+  it('groups static request prefixes and preserves dynamic-prefix fallbacks', () => {
+    expect(getRouteManifestShardKey('api', '/customers/[id]')).toBe('customers')
+    expect(getRouteManifestShardKey('backend', '/backend/sales/orders')).toBe('sales')
+    expect(getRouteManifestShardKey('backend', '/backend/[tenant]/settings')).toBe('__dynamic')
+    expect(getRouteManifestShardKey('api', '/')).toBe('__root')
+  })
+
+  it('renders a small loader graph with exact and dynamic shards', () => {
+    const outputs = renderRouteManifestShardOutputs('api', [
+      { path: '/customers', declaration: `{ moduleId: 'customers' } as any` },
+      { path: '/sales/orders', declaration: `{ moduleId: 'sales' } as any` },
+      { path: '/[module]/health', declaration: `{ moduleId: 'dynamic' } as any` },
+    ])
+    const loader = outputs.find((entry) => entry.fileName === 'api-route-shards.generated.ts')?.content ?? ''
+
+    expect(outputs.filter((entry) => entry.fileName.includes('route-shard.'))).toHaveLength(3)
+    expect(loader).toContain(`case "customers":`)
+    expect(loader).toContain(`case "sales":`)
+    expect(loader).toContain(`const dynamicShard = await loadShard("__dynamic")`)
+    expect(loader).toContain(`export const apiRouteFacades`)
+    expect(loader).toContain(`loadApiRouteManifestByOrdinal(ordinal)`)
+    expect(loader).not.toContain("moduleId: 'customers'")
+  })
+
+  it('retains global route order when exact and dynamic entries interleave', () => {
+    const outputs = renderRouteManifestShardOutputs('api', [
+      { path: '/customers/new', declaration: `{ path: '/customers/new' } as any` },
+      { path: '/[module]/health', declaration: `{ path: '/[module]/health' } as any` },
+      { path: '/customers/[id]', declaration: `{ path: '/customers/[id]' } as any` },
+      { path: '/', declaration: `{ path: '/' } as any` },
+    ])
+    const customerShard = outputs.find((entry) => entry.content.includes(`/customers/new`))?.content ?? ''
+    const dynamicShard = outputs.find((entry) => entry.content.includes(`/[module]/health`))?.content ?? ''
+    const loader = outputs.find((entry) => entry.fileName === 'api-route-shards.generated.ts')?.content ?? ''
+
+    expect(customerShard).toContain('export const routeOrders = [0, 2]')
+    expect(dynamicShard).toContain('export const routeOrders = [1]')
+    expect(loader).toContain(`case "__root":`)
+    expect(loader).toContain(`.sort((a, b) => a.order - b.order)`)
+    expect(loader).toContain(`const ROUTE_SHARD_KEYS = ["customers","__dynamic","customers","__root"]`)
+  })
+
+  it('renders metadata without load functions while retaining metadata imports', () => {
+    const output = renderRouteMetadataOutput('backend', [{
+      path: '/backend/settings',
+      declaration: `{ moduleId: 'settings', ...resolvePageRouteMetadata('/backend/settings', META.metadata) }`,
+      imports: [`import * as META from '@app/settings/meta'`],
+    }])
+
+    expect(output.fileName).toBe('backend-route-metadata.generated.ts')
+    expect(output.content).toContain(`import * as META from '@app/settings/meta'`)
+    expect(output.content).toContain(`Omit<BackendRouteManifestEntry, 'load'>`)
+    expect(output.content).not.toContain('load: async')
+  })
+})

package/src/lib/generators/entity-ids.ts

@@ -5,17 +5,13 @@ import { VariableDeclarationKind } from 'ts-morph'
 import type { PackageResolver, ModuleEntry } from '../resolver'
 import { MODULE_CODE_EXTENSIONS } from './scanner'
 import {
-  calculateChecksum,
-  readChecksumRecord,
-  writeChecksumRecord,
-  ensureDir,
   toVar,
   toSnake,
   rimrafDir,
-  logGenerationResult,
-  writeIfChanged,
   type GeneratorResult,
   createGeneratorResult,
+  writeGeneratedFile,
+  writeIfChanged,
 } from '../utils'
 import { addAutoGeneratedComment, createGeneratedSourceFile, elementAccess, getSourceText, identifier, returnStatement } from './ast'
 
@@ -438,26 +434,14 @@ export async function generateEntityIds(options: EntityIdsOptions): Promise<Gene
   })
   const consolidatedSrc = getSourceText(consolidatedSourceFile)
 
-  // Check if content has changed
-  const newChecksum = calculateChecksum(consolidatedSrc)
-  let shouldWrite = true
-
-  const existingRecord = readChecksumRecord(checksumFile)
-  if (existingRecord && existingRecord.content === newChecksum) {
-    shouldWrite = false
-  }
-
-  if (shouldWrite) {
-    ensureDir(outFile)
-    fs.writeFileSync(outFile, consolidatedSrc)
-    writeChecksumRecord(checksumFile, { content: newChecksum, structure: '' })
-    result.filesWritten.push(outFile)
-    if (!quiet) {
-      logGenerationResult(path.relative(process.cwd(), outFile), true)
-    }
-  } else {
-    result.filesUnchanged.push(outFile)
-  }
+  writeGeneratedFile({
+    outFile,
+    checksumFile,
+    content: consolidatedSrc,
+    structureChecksum: '',
+    result,
+    quiet,
+  })
 
   // Write per-group outputs
   const groups = Object.keys(grouped) as GroupKey[]

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

@@ -4,14 +4,10 @@ import { StructureKind, VariableDeclarationKind } from 'ts-morph'
 import type { PackageResolver } from '../resolver'
 import { MODULE_CODE_EXTENSIONS } from './scanner'
 import {
-  calculateChecksum,
-  readChecksumRecord,
-  writeChecksumRecord,
-  ensureDir,
   toVar,
-  logGenerationResult,
   type GeneratorResult,
   createGeneratorResult,
+  writeGeneratedFile,
 } from '../utils'
 import {
   addAutoGeneratedComment,
@@ -96,26 +92,14 @@ export async function generateModuleDi(options: ModuleDiOptions): Promise<Genera
   })
   const output = getSourceText(sourceFile)
 
-  // Check if content has changed
-  const newChecksum = calculateChecksum(output)
-  let shouldWrite = true
-
-  const existingRecord = readChecksumRecord(checksumFile)
-  if (existingRecord && existingRecord.content === newChecksum) {
-    shouldWrite = false
-  }
-
-  if (shouldWrite) {
-    ensureDir(outFile)
-    fs.writeFileSync(outFile, output)
-    writeChecksumRecord(checksumFile, { content: newChecksum, structure: '' })
-    result.filesWritten.push(outFile)
-    if (!quiet) {
-      logGenerationResult(path.relative(process.cwd(), outFile), true)
-    }
-  } else {
-    result.filesUnchanged.push(outFile)
-  }
+  writeGeneratedFile({
+    outFile,
+    checksumFile,
+    content: output,
+    structureChecksum: '',
+    result,
+    quiet,
+  })
 
   return result
 }