@open-mercato/cli 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.8.1-develop.7296.1.2111d779db",
+  "version": "0.9.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,9 +60,10 @@
     "@mikro-orm/decorators": "^7.1.14",
     "@mikro-orm/migrations": "^7.1.14",
     "@mikro-orm/postgresql": "^7.1.14",
-    "@open-mercato/queue": "0.8.1-develop.7296.1.2111d779db",
-    "@open-mercato/shared": "0.8.1-develop.7296.1.2111d779db",
-    "@open-mercato/telemetry": "0.8.1-develop.7296.1.2111d779db",
+    "@open-mercato/events": "0.9.0",
+    "@open-mercato/queue": "0.9.0",
+    "@open-mercato/shared": "0.9.0",
+    "@open-mercato/telemetry": "0.9.0",
     "cross-spawn": "^7.0.6",
     "pg": "8.23.0",
     "semver": "^7.8.5",
@@ -73,10 +74,10 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.8.1-develop.7296.1.2111d779db"
+    "@open-mercato/shared": "0.9.0"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.8.1-develop.7296.1.2111d779db",
+    "@open-mercato/shared": "0.9.0",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12"
@@ -88,6 +89,5 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/cli"
-  },
-  "stableVersion": "0.8.0"
+  }
 }

package/src/bin.ts

@@ -6,7 +6,7 @@
  */
 import { isTelemetryBackendEnabled } from '@open-mercato/shared/lib/telemetry/runtime'
 import { resolveCliBootstrapMode, type CliBootstrapMode } from './lib/cli-bootstrap-mode.js'
-import { flushTelemetry } from './lib/flush-telemetry.js'
+import { flushBeforeExit } from './lib/flush-before-exit.js'
 // `run` is imported dynamically inside `main()` so telemetry can initialize
 // before the mercato entry (and its Postgres driver) loads — see main().
 
@@ -114,9 +114,9 @@ async function main(): Promise<void> {
   // Postgres driver it pulls in — loads only after initTelemetry() above.
   const { run } = await import('./mercato.js')
   const code = await run(process.argv)
-  // Flush spans/logs for commands that return (workers block forever and flush via
-  // their own shutdown handler instead).
-  await flushTelemetry()
+  // Flush the coalesced browser broadcasts, then spans/logs, for commands that
+  // return (workers block forever and flush via their own shutdown handler instead).
+  await flushBeforeExit()
   process.exit(code ?? 0)
 }
 

package/src/lib/__tests__/flush-before-exit.test.ts

@@ -0,0 +1,32 @@
+import { flushBeforeExit } from '../flush-before-exit'
+
+describe('flushBeforeExit', () => {
+  let warn: jest.SpyInstance
+
+  beforeEach(() => {
+    warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    warn.mockRestore()
+  })
+
+  it('flushes coalesced broadcasts before telemetry so the final pg_notify is still exported', async () => {
+    const order: string[] = []
+    await flushBeforeExit({
+      flushBroadcasts: async () => { order.push('broadcasts') },
+      flushTelemetry: async () => { order.push('telemetry') },
+    })
+    expect(order).toEqual(['broadcasts', 'telemetry'])
+  })
+
+  it('still flushes telemetry, with a warning, when the broadcast flush fails', async () => {
+    const flushTelemetry = jest.fn().mockResolvedValue(undefined)
+    await expect(flushBeforeExit({
+      flushBroadcasts: async () => { throw new Error('connection terminated') },
+      flushTelemetry,
+    })).resolves.toBeUndefined()
+    expect(flushTelemetry).toHaveBeenCalledTimes(1)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('connection terminated'))
+  })
+})

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

@@ -29,13 +29,35 @@ describe('calculateGenerateWatchStructureChecksum', () => {
     fs.rmSync(root, { recursive: true, force: true })
   })
 
-  function currentChecksum(): string {
+  function checksumModule(modulesFile: string, appBase: string, packageBase: string): string {
     return calculateGenerateWatchStructureChecksum({
-      modulesFile: path.join(appDir, 'src', 'modules.ts'),
-      moduleRoots: [{ appBase: appModule, pkgBase: pkgModule }],
+      modulesFile,
+      moduleRoots: [{ appBase, pkgBase: packageBase }],
     })
   }
 
+  function currentChecksum(): string {
+    return checksumModule(path.join(appDir, 'src', 'modules.ts'), appModule, pkgModule)
+  }
+
+  function createStandaloneModule() {
+    const standaloneRoot = path.join(root, 'standalone')
+    const packageRoot = path.join(standaloneRoot, 'node_modules', '@open-mercato', 'core')
+    const sourceModule = path.join(packageRoot, 'src', 'modules', 'customers')
+    const distModule = path.join(packageRoot, 'dist', 'modules', 'customers')
+    const standaloneAppModule = path.join(standaloneRoot, 'src', 'modules', 'customers')
+    const modulesFile = path.join(standaloneRoot, 'src', 'modules.ts')
+    write(modulesFile, 'export const enabledModules = ["customers"]\n')
+    write(path.join(sourceModule, 'index.ts'), 'export const metadata = { id: "customers" }\n')
+    write(path.join(distModule, 'index.js'), 'export const metadata = { id: "customers" }\n')
+    return {
+      sourceModule,
+      distModule,
+      appModule: standaloneAppModule,
+      modulesFile,
+    }
+  }
+
   it('ignores ordinary component edits outside generator discovery paths', () => {
     const before = currentChecksum()
 
@@ -78,6 +100,32 @@ describe('calculateGenerateWatchStructureChecksum', () => {
     expect(currentChecksum()).not.toBe(before)
   })
 
+  it('changes when an identical convention file moves between module roots', () => {
+    const ordersPkgModule = path.join(root, 'packages', 'core', 'src', 'modules', 'orders')
+    const ordersAppModule = path.join(appDir, 'src', 'modules', 'orders')
+    const customersCli = path.join(pkgModule, 'cli.ts')
+    const ordersCli = path.join(ordersPkgModule, 'cli.ts')
+    const cliSource = 'export default function registerCli() {}\n'
+    const moduleRoots = [
+      { appBase: appModule, pkgBase: pkgModule },
+      { appBase: ordersAppModule, pkgBase: ordersPkgModule },
+    ]
+    write(path.join(ordersPkgModule, 'index.ts'), 'export const metadata = { id: "orders" }\n')
+    write(customersCli, cliSource)
+    const before = calculateGenerateWatchStructureChecksum({
+      modulesFile: path.join(appDir, 'src', 'modules.ts'),
+      moduleRoots,
+    })
+
+    fs.rmSync(customersCli)
+    write(ordersCli, cliSource)
+
+    expect(calculateGenerateWatchStructureChecksum({
+      modulesFile: path.join(appDir, 'src', 'modules.ts'),
+      moduleRoots,
+    })).not.toBe(before)
+  })
+
   // A runtime.ts the watcher cannot see is the failure SPEC-072 exists to remove, reappearing in
   // the dev loop: the registry is not regenerated, `Module.runtime` stays undefined, and the
   // runtime never starts — with no error and no warning.
@@ -115,4 +163,214 @@ describe('calculateGenerateWatchStructureChecksum', () => {
 
     expect(currentChecksum()).not.toBe(before)
   })
+
+  it('tracks generator-relevant API route changes from a standalone source mirror', () => {
+    const standalone = createStandaloneModule()
+    const sourceRoute = path.join(standalone.sourceModule, 'api', 'records', 'route.ts')
+    const distRoute = path.join(standalone.distModule, 'api', 'records', 'route.js')
+    write(
+      sourceRoute,
+      'export const metadata = { path: "/records" }\nexport async function GET() { return null }\n',
+    )
+    write(
+      distRoute,
+      'export const metadata = { path: "/records" };\nexport async function GET() { return null; }\n',
+    )
+    const before = checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule)
+
+    write(
+      sourceRoute,
+      'export const metadata = { path: "/contacts" }\nexport async function GET() { return null }\n',
+    )
+    const afterSourceMetadata = checksumModule(
+      standalone.modulesFile,
+      standalone.appModule,
+      standalone.distModule,
+    )
+    expect(afterSourceMetadata).not.toBe(before)
+
+    write(
+      distRoute,
+      'export const metadata = { path: "/contacts" };\nexport async function GET() { return null; }\n',
+    )
+    const afterDistMetadata = checksumModule(
+      standalone.modulesFile,
+      standalone.appModule,
+      standalone.distModule,
+    )
+    expect(afterDistMetadata).not.toBe(afterSourceMetadata)
+
+    write(
+      sourceRoute,
+      'export const metadata = { path: "/contacts" }\nexport async function POST() { return null }\n',
+    )
+    const afterSourceMethod = checksumModule(
+      standalone.modulesFile,
+      standalone.appModule,
+      standalone.distModule,
+    )
+    expect(afterSourceMethod).not.toBe(afterDistMetadata)
+
+    write(
+      distRoute,
+      'export const metadata = { path: "/contacts" };\nexport async function POST() { return null; }\n',
+    )
+    expect(checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule))
+      .not.toBe(afterSourceMethod)
+  })
+
+  it('tracks standalone source-mirror page metadata but ignores ordinary page implementation edits', () => {
+    const standalone = createStandaloneModule()
+    const sourcePage = path.join(standalone.sourceModule, 'backend', 'customers', 'people', 'page.tsx')
+    const sourceMeta = path.join(standalone.sourceModule, 'backend', 'customers', 'people', 'page.meta.ts')
+    write(sourcePage, 'export default function Page() { return null }\n')
+    write(sourceMeta, 'export const metadata = { nav: { label: "People" } }\n')
+    write(
+      path.join(standalone.distModule, 'backend', 'customers', 'people', 'page.js'),
+      'export default function Page() { return null; }\n',
+    )
+    write(
+      path.join(standalone.distModule, 'backend', 'customers', 'people', 'page.meta.js'),
+      'export const metadata = { nav: { label: "People" } };\n',
+    )
+    const before = checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule)
+
+    write(sourcePage, 'export default function Page() { return "implementation changed" }\n')
+    expect(checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule)).toBe(before)
+
+    write(sourceMeta, 'export const metadata = { nav: { label: "Contacts" } }\n')
+    const afterSourceMetadata = checksumModule(
+      standalone.modulesFile,
+      standalone.appModule,
+      standalone.distModule,
+    )
+    expect(afterSourceMetadata).not.toBe(before)
+
+    write(
+      path.join(standalone.distModule, 'backend', 'customers', 'people', 'page.meta.js'),
+      'export const metadata = { nav: { label: "Contacts" } };\n',
+    )
+    expect(checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule))
+      .not.toBe(afterSourceMetadata)
+  })
+
+  it('tracks additions and deletions enumerated from a standalone source mirror', () => {
+    const standalone = createStandaloneModule()
+    const before = checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule)
+    const sourceWorker = path.join(standalone.sourceModule, 'workers', 'sync-customers.ts')
+    write(sourceWorker, 'export default async function syncCustomers() {}\n')
+    write(
+      path.join(standalone.distModule, 'workers', 'sync-customers.js'),
+      'export default async function syncCustomers() {}\n',
+    )
+
+    expect(checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule)).not.toBe(before)
+
+    fs.rmSync(sourceWorker)
+    expect(checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule)).toBe(before)
+  })
+
+  it('tracks stale compiled entities after the source-mirror convention is deleted', () => {
+    const standalone = createStandaloneModule()
+    const sourceEntities = path.join(standalone.sourceModule, 'data', 'entities.ts')
+    const distEntities = path.join(standalone.distModule, 'data', 'entities.js')
+    const before = checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule)
+
+    write(sourceEntities, 'export class Customer {}\n')
+    const afterSourceAdd = checksumModule(
+      standalone.modulesFile,
+      standalone.appModule,
+      standalone.distModule,
+    )
+    expect(afterSourceAdd).not.toBe(before)
+
+    write(distEntities, 'export class Customer {}\n')
+    const afterDistAdd = checksumModule(
+      standalone.modulesFile,
+      standalone.appModule,
+      standalone.distModule,
+    )
+    expect(afterDistAdd).not.toBe(afterSourceAdd)
+
+    write(sourceEntities, 'export class CustomerAccount {}\n')
+    const afterSourceEdit = checksumModule(
+      standalone.modulesFile,
+      standalone.appModule,
+      standalone.distModule,
+    )
+    expect(afterSourceEdit).not.toBe(afterDistAdd)
+
+    write(distEntities, 'export class CustomerAccount {}\n')
+    const afterDistEdit = checksumModule(
+      standalone.modulesFile,
+      standalone.appModule,
+      standalone.distModule,
+    )
+    expect(afterDistEdit).not.toBe(afterSourceEdit)
+
+    fs.rmSync(sourceEntities)
+    const afterSourceDelete = checksumModule(
+      standalone.modulesFile,
+      standalone.appModule,
+      standalone.distModule,
+    )
+    expect(afterSourceDelete).not.toBe(afterDistEdit)
+    expect(afterSourceDelete).not.toBe(before)
+
+    fs.rmSync(distEntities)
+    expect(checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule))
+      .toBe(before)
+  })
+
+  it('fingerprints the selected app override instead of the shadowed package route', () => {
+    const standalone = createStandaloneModule()
+    const routeSource = 'export const metadata = { path: "/records" }\nexport async function GET() { return null }\n'
+    const packageRoute = path.join(standalone.sourceModule, 'api', 'records', 'route.js')
+    const appRoute = path.join(standalone.appModule, 'api', 'records', 'route.js')
+    write(packageRoute, routeSource)
+    write(path.join(standalone.distModule, 'api', 'records', 'route.js'), routeSource)
+    const beforeOverride = checksumModule(
+      standalone.modulesFile,
+      standalone.appModule,
+      standalone.distModule,
+    )
+
+    write(appRoute, routeSource)
+    const withOverride = checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule)
+    expect(withOverride).not.toBe(beforeOverride)
+
+    write(
+      packageRoute,
+      'export const metadata = { path: "/shadowed" }\nexport async function POST() { return null }\n',
+    )
+    expect(checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule))
+      .toBe(withOverride)
+
+    fs.rmSync(appRoute)
+    expect(checksumModule(standalone.modulesFile, standalone.appModule, standalone.distModule))
+      .not.toBe(withOverride)
+  })
+
+  it('keeps content-sensitive fingerprinting for dist-only installed packages', () => {
+    const standaloneRoot = path.join(root, 'dist-only')
+    const distModule = path.join(
+      standaloneRoot,
+      'node_modules',
+      '@open-mercato',
+      'core',
+      'dist',
+      'modules',
+      'customers',
+    )
+    const modulesFile = path.join(standaloneRoot, 'src', 'modules.ts')
+    const routePath = path.join(distModule, 'api', 'records', 'route.js')
+    write(modulesFile, 'export const enabledModules = ["customers"]\n')
+    write(path.join(distModule, 'index.js'), 'export const metadata = { id: "customers" }\n')
+    write(routePath, 'export const metadata = { path: "/records" };\nexport async function GET() {}\n')
+    const appModule = path.join(standaloneRoot, 'src', 'modules', 'customers')
+    const before = checksumModule(modulesFile, appModule, distModule)
+
+    write(routePath, 'export const metadata = { path: "/contacts" };\nexport async function GET() {}\n')
+    expect(checksumModule(modulesFile, appModule, distModule)).not.toBe(before)
+  })
 })

package/src/lib/__tests__/telemetry-init.test.ts

@@ -99,6 +99,33 @@ async function handleRequest(method: string, req: NextRequest): Promise<Response
 }
 `
 
+const LEGACY_INSTRUMENTATION = `import { isTelemetryBackendEnabled } from '@open-mercato/shared/lib/telemetry/runtime'
+
+export async function register(): Promise<void> {
+  if (
+    process.env.NEXT_RUNTIME === 'nodejs'
+    && process.env.NEXT_PHASE !== 'phase-production-build'
+  ) {
+    const { assertJwtSecretPolicy } = await import('@open-mercato/shared/lib/auth/jwt')
+    try {
+      assertJwtSecretPolicy()
+    } catch (err) {
+      const nodeProcess = process
+      nodeProcess.stderr.write(\`\${err instanceof Error ? err.message : String(err)}\\n\`)
+      nodeProcess.exit(1)
+    }
+  }
+
+  if (
+    process.env.NEXT_RUNTIME === 'nodejs'
+    && isTelemetryBackendEnabled()
+  ) {
+    const { registerTelemetryForNextjs } = await import('@open-mercato/telemetry/nextjs')
+    await registerTelemetryForNextjs()
+  }
+}
+`
+
 describe('mercato telemetry init', () => {
   let tmpDir: string
   let cwd: string
@@ -142,6 +169,8 @@ describe('mercato telemetry init', () => {
     expect(read('.env.example')).toContain('TELEMETRY_BACKEND')
     expect(read('.env.example')).toContain('OTEL_EXPORTER_OTLP_ENDPOINT')
     expect(read('src/instrumentation.ts')).toContain('registerTelemetryForNextjs')
+    expect(read('src/instrumentation.ts')).toContain('nodeProcess.stderr.write')
+    expect(read('src/instrumentation.ts')).toContain('nodeProcess.exit(1)')
 
     const nextConfig = read('next.config.ts')
     expect(nextConfig).toContain('@open-mercato/telemetry/nextjs-config')
@@ -277,9 +306,69 @@ describe('mercato telemetry init', () => {
     const instrumentation = read('src/instrumentation.ts')
     assertParses(instrumentation, 'custom-instrumentation')
     expect(instrumentation).toContain('registerTelemetryForNextjs')
+    expect(instrumentation).toContain('nodeProcess.stderr.write')
+    expect(instrumentation).toContain('nodeProcess.exit(1)')
     expect(instrumentation).toContain("console.log('custom warmup')") // preserved
   })
 
+  it('upgrades the legacy generated instrumentation and stays idempotent', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    fs.writeFileSync(path.join(tmpDir, 'src', 'instrumentation.ts'), LEGACY_INSTRUMENTATION)
+
+    await runTelemetryInit([])
+    const migrated = read('src/instrumentation.ts')
+    assertParses(migrated, 'legacy-instrumentation-migration')
+    expect(migrated).toContain('nodeProcess.stderr.write')
+    expect(migrated).toContain('nodeProcess.exit(1)')
+    expect((migrated.match(/registerTelemetryForNextjs\(\)/g) ?? []).length).toBe(1)
+    expect((migrated.match(/nodeProcess\.exit\(1\)/g) ?? []).length).toBe(2)
+
+    await runTelemetryInit([])
+    expect(read('src/instrumentation.ts')).toBe(migrated)
+  })
+
+  it('upgrades the older Node-only generated bootstrap', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'instrumentation.ts'),
+      `export async function register(): Promise<void> {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { registerTelemetryForNextjs } = await import('@open-mercato/telemetry/nextjs')
+    await registerTelemetryForNextjs()
+  }
+}
+`,
+    )
+
+    await runTelemetryInit([])
+    const migrated = read('src/instrumentation.ts')
+
+    assertParses(migrated, 'node-only-instrumentation-migration')
+    expect(migrated).toContain("import { isTelemetryBackendEnabled }")
+    expect(migrated).toContain("process.env.NEXT_RUNTIME === 'nodejs' && isTelemetryBackendEnabled()")
+    expect(migrated).toContain('nodeProcess.exit(1)')
+  })
+
+  it('leaves an unrecognized custom telemetry bootstrap for a manual update', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    const customInstrumentation = `export async function register(): Promise<void> {
+  const { registerTelemetryForNextjs } = await import('@open-mercato/telemetry/nextjs')
+  if (process.env.NEXT_RUNTIME === 'nodejs') await registerTelemetryForNextjs()
+  const nodeProcess = process
+  nodeProcess.exit(1)
+}
+`
+    fs.writeFileSync(path.join(tmpDir, 'src', 'instrumentation.ts'), customInstrumentation)
+
+    await runTelemetryInit([])
+
+    expect(read('src/instrumentation.ts')).toBe(customInstrumentation)
+    expect(logSpy.mock.calls.flat().join('\n')).toContain('manual step for src/instrumentation.ts')
+  })
+
   it('is idempotent — a second run changes nothing and does not double-insert', async () => {
     baseFixture(tmpDir)
     fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)

package/src/lib/db/__tests__/commands.test.ts

@@ -7,6 +7,7 @@ import {
   resolveGeneratedMigrationPath,
   dbGenerate,
   dbGreenfield,
+  warnAboutMissingEncryptionMapBackfills,
 } from '../commands'
 import { MetadataStorage } from '@mikro-orm/core'
 import fs from 'node:fs'
@@ -399,3 +400,45 @@ describe('dbGenerate metadata isolation (issue #1911)', () => {
     expect(Object.keys(MetadataStorage.getMetadata())).toHaveLength(0)
   })
 })
+
+describe('warnAboutMissingEncryptionMapBackfills', () => {
+  const tempDirs: string[] = []
+
+  afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+      try { fs.rmSync(dir, { recursive: true, force: true }) } catch {}
+    }
+    jest.restoreAllMocks()
+  })
+
+  function createResolver(dir: string): PackageResolver {
+    return {
+      isMonorepo: () => true,
+      getRootDir: () => dir,
+      getAppDir: () => dir,
+      getOutputDir: () => dir,
+      getModulesConfigPath: () => path.join(dir, 'modules.ts'),
+      discoverPackages: () => [],
+      loadEnabledModules: () => [{ id: 'demo', from: '@app' }],
+      getModulePaths: () => ({ appBase: dir, pkgBase: dir }),
+      getModuleImportBase: () => ({ appBase: '@/modules/demo', pkgBase: '@open-mercato/core/modules/demo' }),
+      getPackageOutputDir: () => dir,
+      getPackageRoot: () => dir,
+    }
+  }
+
+  function createModule(): string {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-enc-'))
+    tempDirs.push(dir)
+    return dir
+  }
+
+  it('stays silent without declared encryption maps', async () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation()
+    const resolver = createResolver(createModule())
+
+    await warnAboutMissingEncryptionMapBackfills(resolver.loadEnabledModules(), resolver)
+
+    expect(warn).not.toHaveBeenCalled()
+  })
+})

package/src/lib/db/__tests__/dynamic-import-specifier.test.ts

@@ -0,0 +1,36 @@
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { toImportableModuleSpecifier } from '../commands'
+
+describe('toImportableModuleSpecifier (#6238)', () => {
+  it('converts cwd-relative node_modules migration paths to file: URLs', () => {
+    const relative = path.join('node_modules', '@open-mercato', 'core', 'dist', 'modules', 'customers', 'migrations', 'Migration20250101000000.js')
+    const result = toImportableModuleSpecifier(relative)
+
+    expect(result.startsWith('file:')).toBe(true)
+    expect(result).toBe(pathToFileURL(path.resolve(relative)).href)
+  })
+
+  it('converts absolute filesystem paths to file: URLs on every platform', () => {
+    const absolute = path.resolve('migrations', 'Migration20250101000000.js')
+    expect(toImportableModuleSpecifier(absolute)).toBe(pathToFileURL(absolute).href)
+  })
+
+  it('converts ./ and ../ relative paths to file: URLs', () => {
+    expect(toImportableModuleSpecifier('./Migration.js')).toBe(pathToFileURL(path.resolve('./Migration.js')).href)
+    expect(toImportableModuleSpecifier('../migrations/Migration.js')).toBe(
+      pathToFileURL(path.resolve('../migrations/Migration.js')).href,
+    )
+  })
+
+  it('leaves bare package names and package subpaths alone', () => {
+    expect(toImportableModuleSpecifier('zod')).toBe('zod')
+    expect(toImportableModuleSpecifier('@mikro-orm/core')).toBe('@mikro-orm/core')
+    expect(toImportableModuleSpecifier('next/server')).toBe('next/server')
+  })
+
+  it('leaves existing file: and node: URLs alone', () => {
+    expect(toImportableModuleSpecifier('file:///tmp/Migration.js')).toBe('file:///tmp/Migration.js')
+    expect(toImportableModuleSpecifier('node:fs')).toBe('node:fs')
+  })
+})