@open-mercato/shared 0.9.1-develop.7476.1.342138d35e → 0.9.1-develop.7496.1.3346415f94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.9.1-develop.7476.1.342138d35e",
+  "version": "0.9.1-develop.7496.1.3346415f94",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -121,7 +121,7 @@
     "@mikro-orm/core": "^7.1.14",
     "@mikro-orm/decorators": "^7.1.14",
     "@mikro-orm/postgresql": "^7.1.14",
-    "@open-mercato/cache": "0.9.1-develop.7476.1.342138d35e",
+    "@open-mercato/cache": "0.9.1-develop.7496.1.3346415f94",
     "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",

package/src/lib/bootstrap/__tests__/dynamicLoader.appDi.test.ts

@@ -91,9 +91,9 @@ function writeCompiledPair(
   fs.writeFileSync(compiledPath, source.compiled)
   const sourceRelativePath = path.relative(appRoot, sourcePath).split(path.sep).join('/')
   fs.writeFileSync(`${compiledPath}.cache.json`, JSON.stringify({
-    version: 4,
+    version: 5,
     inputHash: hash(JSON.stringify({
-      version: 4,
+      version: 5,
       sourceHash: hash(source.ts),
       tsconfigHashes: {
         'tsconfig.json': hash(APP_TSCONFIG),

package/src/lib/bootstrap/__tests__/dynamicLoader.appModuleOverrides.test.ts

@@ -132,9 +132,9 @@ function writeCompiledPair(
   fs.writeFileSync(compiledPath, source.compiled)
   const sourceRelativePath = path.relative(appRoot, sourcePath).split(path.sep).join('/')
   fs.writeFileSync(`${compiledPath}.cache.json`, JSON.stringify({
-    version: 4,
+    version: 5,
     inputHash: hash(JSON.stringify({
-      version: 4,
+      version: 5,
       sourceHash: hash(source.ts),
       tsconfigHashes: {
         'tsconfig.json': hash(APP_TSCONFIG),

package/src/lib/bootstrap/__tests__/dynamicLoader.cacheRecovery.test.ts

@@ -77,7 +77,7 @@ function writeGeneratedModule(generatedDir: string, baseName: string, source: {
 function writeCompiledSibling(generatedDir: string, baseName: string, compiled: string) {
   const source = fs.readFileSync(path.join(generatedDir, `${baseName}.ts`), 'utf8')
   const inputHash = hash(JSON.stringify({
-    version: 4,
+    version: 5,
     sourceHash: hash(source),
     tsconfigHashes: {
       'tsconfig.json': hash(APP_TSCONFIG),
@@ -90,7 +90,7 @@ function writeCompiledSibling(generatedDir: string, baseName: string, compiled:
   const compiledPath = path.join(generatedDir, `${baseName}.mjs`)
   fs.writeFileSync(compiledPath, compiled)
   fs.writeFileSync(`${compiledPath}.cache.json`, JSON.stringify({
-    version: 4,
+    version: 5,
     inputHash,
     outputHash: hash(compiled),
     dependencies: {

package/src/lib/bootstrap/__tests__/dynamicLoader.commandInterceptors.test.ts

@@ -77,9 +77,9 @@ function writeGeneratedModule(generatedDir: string, baseName: string, source: {
   fs.writeFileSync(sourcePath, source.ts)
   fs.writeFileSync(compiledPath, source.compiled)
   fs.writeFileSync(`${compiledPath}.cache.json`, JSON.stringify({
-    version: 4,
+    version: 5,
     inputHash: hash(JSON.stringify({
-      version: 4,
+      version: 5,
       sourceHash: hash(source.ts),
       tsconfigHashes: {
         'tsconfig.json': hash(APP_TSCONFIG),

package/src/lib/bootstrap/__tests__/dynamicLoader.externalSubpath.test.ts

@@ -0,0 +1,141 @@
+/**
+ * @jest-environment node
+ *
+ * The CLI bundle externalizes every bare package import. Node's ESM resolver only maps an
+ * extensionless subpath such as `next/link` when the package publishes an `exports` map; for a
+ * legacy package (no `exports`, like `next`) it requires the file extension and the bundle
+ * fails with ERR_MODULE_NOT_FOUND (#6993). The external plugin therefore rewrites such
+ * subpaths to the file `require.resolve` finds, and leaves everything else untouched.
+ */
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { compileAppSourceFile, createCliBundlePlugins } from '../dynamicLoader'
+
+function writePackage(appRoot: string, name: string, manifest: Record<string, unknown>, files: Record<string, string>) {
+  const packageDir = path.join(appRoot, 'node_modules', ...name.split('/'))
+  fs.mkdirSync(packageDir, { recursive: true })
+  fs.writeFileSync(path.join(packageDir, 'package.json'), JSON.stringify({ name, version: '1.0.0', ...manifest }))
+  for (const [relativePath, content] of Object.entries(files)) {
+    const filePath = path.join(packageDir, relativePath)
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, content)
+  }
+}
+
+async function bundleWithCliPlugins(appRoot: string, source: string): Promise<{ outfile: string; output: string }> {
+  const esbuild = await import('esbuild')
+  const generatedDir = path.join(appRoot, '.mercato', 'generated')
+  fs.mkdirSync(generatedDir, { recursive: true })
+  const entry = path.join(generatedDir, 'entry.ts')
+  fs.writeFileSync(entry, source)
+  const outfile = path.join(generatedDir, 'entry.mjs')
+  await esbuild.build({
+    entryPoints: [entry],
+    outfile,
+    absWorkingDir: appRoot,
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    target: 'node18',
+    plugins: createCliBundlePlugins(appRoot),
+  })
+  return { outfile, output: fs.readFileSync(outfile, 'utf8') }
+}
+
+describe('createCliBundlePlugins — externalized package subpaths', () => {
+  let appRoot: string
+
+  beforeEach(() => {
+    appRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'om-external-subpath-')))
+    fs.writeFileSync(path.join(appRoot, 'package.json'), JSON.stringify({ name: 'app', type: 'module' }))
+    writePackage(appRoot, 'legacy-pkg', { main: 'index.js' }, {
+      'index.js': "module.exports = 'legacy-root'\n",
+      'link.js': "module.exports = 'legacy-link'\n",
+      'dist/nested/index.js': "module.exports = 'legacy-nested'\n",
+    })
+    writePackage(appRoot, '@scope/legacy-scoped', {}, {
+      'tools.js': "module.exports = 'scoped-tools'\n",
+    })
+    writePackage(appRoot, 'exports-pkg', { exports: { './feature': './lib/feature.js' } }, {
+      'lib/feature.js': "module.exports = 'exports-feature'\n",
+    })
+  })
+
+  afterEach(() => {
+    fs.rmSync(appRoot, { recursive: true, force: true })
+  })
+
+  it('appends the resolved file to extensionless subpaths of packages without an exports map', async () => {
+    const { output } = await bundleWithCliPlugins(appRoot, [
+      "import link from 'legacy-pkg/link'",
+      "import nested from 'legacy-pkg/dist/nested'",
+      "import tools from '@scope/legacy-scoped/tools'",
+      'export const values = [link, nested, tools]',
+      '',
+    ].join('\n'))
+
+    expect(output).toContain('"legacy-pkg/link.js"')
+    expect(output).toContain('"legacy-pkg/dist/nested/index.js"')
+    expect(output).toContain('"@scope/legacy-scoped/tools.js"')
+  })
+
+  it('keeps package roots, exports-mapped subpaths, builtins and unresolvable specifiers unchanged', async () => {
+    const { output } = await bundleWithCliPlugins(appRoot, [
+      "import root from 'legacy-pkg'",
+      "import feature from 'exports-pkg/feature'",
+      "import explicit from 'legacy-pkg/link.js'",
+      "import { readFile } from 'fs/promises'",
+      "import missing from 'missing-pkg/sub'",
+      'export const values = [root, feature, explicit, readFile, missing]',
+      '',
+    ].join('\n'))
+
+    expect(output).toContain('"legacy-pkg"')
+    expect(output).toContain('"exports-pkg/feature"')
+    expect(output).toContain('"legacy-pkg/link.js"')
+    expect(output).toContain('"fs/promises"')
+    expect(output).toContain('"missing-pkg/sub"')
+  })
+
+  it('produces a bundle Node ESM can load', async () => {
+    const { outfile } = await bundleWithCliPlugins(appRoot, [
+      "import link from 'legacy-pkg/link'",
+      "import feature from 'exports-pkg/feature'",
+      'console.log(JSON.stringify([link, feature]))',
+      '',
+    ].join('\n'))
+
+    const result = spawnSync(process.execPath, [outfile], { encoding: 'utf8' })
+
+    expect(result.stderr).not.toContain('ERR_MODULE_NOT_FOUND')
+    expect(result.status).toBe(0)
+    expect(JSON.parse(result.stdout.trim())).toEqual(['legacy-link', 'exports-feature'])
+  })
+
+  it('records the rewritten package manifest so a package upgrade invalidates the cached bundle', async () => {
+    fs.writeFileSync(path.join(appRoot, 'tsconfig.json'), JSON.stringify({ compilerOptions: { target: 'ES2022' } }))
+    const generatedDir = path.join(appRoot, '.mercato', 'generated')
+    fs.mkdirSync(generatedDir, { recursive: true })
+    const entry = path.join(generatedDir, 'registry.generated.ts')
+    fs.writeFileSync(entry, "import link from 'legacy-pkg/link'\nexport const value = link\n")
+    const outFile = path.join(generatedDir, 'registry.generated.mjs')
+
+    await compileAppSourceFile(entry, { appRoot, outFile })
+    const metadata = JSON.parse(fs.readFileSync(`${outFile}.cache.json`, 'utf8')) as {
+      dependencies: Record<string, string>
+    }
+    expect(Object.keys(metadata.dependencies)).toContain('node_modules/legacy-pkg/package.json')
+
+    const firstOutputMtime = fs.statSync(outFile).mtimeMs
+    await compileAppSourceFile(entry, { appRoot, outFile })
+    expect(fs.statSync(outFile).mtimeMs).toBe(firstOutputMtime)
+
+    writePackage(appRoot, 'legacy-pkg', { exports: { './link': './link.js' } }, {})
+    await compileAppSourceFile(entry, { appRoot, outFile })
+    expect(fs.readFileSync(outFile, 'utf8')).toContain('"legacy-pkg/link"')
+    expect(fs.readFileSync(outFile, 'utf8')).not.toContain('"legacy-pkg/link.js"')
+  })
+})

package/src/lib/bootstrap/__tests__/dynamicLoader.tsconfig.test.ts

@@ -133,7 +133,7 @@ describe('dynamic loader app tsconfig and content-addressed cache', () => {
     loadBootstrapDataInNode(appRoot)
     const after = readCacheMetadata(appRoot, 'entities')
 
-    expect(after.version).toBe(4)
+    expect(after.version).toBe(5)
     expect(after.inputHash).not.toBe(before.inputHash)
   })
 
@@ -287,6 +287,6 @@ describe('dynamic loader app tsconfig and content-addressed cache', () => {
 
     loadBootstrapDataInNode(appRoot)
 
-    expect(readCacheMetadata(appRoot, 'entities').version).toBe(4)
+    expect(readCacheMetadata(appRoot, 'entities').version).toBe(5)
   })
 })

package/src/lib/bootstrap/__tests__/next-subpath-resolve-hook.test.ts

@@ -0,0 +1,174 @@
+import {
+  installNextSubpathResolveHook,
+  resetNextSubpathResolveHookForTests,
+  resolveNextSubpath,
+  resolveNextSubpathAsync,
+} from '../next-subpath-resolve-hook'
+
+function notFound(specifier: string): Error & { code: string } {
+  return Object.assign(new Error(`Cannot find module '${specifier}'`), { code: 'ERR_MODULE_NOT_FOUND' })
+}
+
+describe('resolveNextSubpath (#6118)', () => {
+  const context = { parentURL: 'file:///app/route.js' }
+
+  it('leaves specifiers other than next/<subpath> to the default resolver', () => {
+    const nextResolve = jest.fn(() => ({ url: 'file:///app/node_modules/zod/index.js' }))
+
+    const result = resolveNextSubpath('zod', context, nextResolve)
+
+    expect(result.url).toBe('file:///app/node_modules/zod/index.js')
+    expect(nextResolve).toHaveBeenCalledTimes(1)
+    expect(nextResolve).toHaveBeenCalledWith('zod', context)
+  })
+
+  it('does not touch a next/<subpath> that resolves on its own', () => {
+    // The day `next` ships an exports map the hook must step aside.
+    const nextResolve = jest.fn(() => ({ url: 'file:///app/node_modules/next/server.js' }))
+
+    resolveNextSubpath('next/server', context, nextResolve)
+
+    expect(nextResolve).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries a bare next/<subpath> with the .js suffix when Node cannot resolve it', () => {
+    // `next` has no exports map and Node ESM does no extension guessing, so
+    // `next/server` fails while `next/server.js` is a real file.
+    const nextResolve = jest
+      .fn()
+      .mockImplementationOnce(() => { throw notFound('/app/node_modules/next/server') })
+      .mockImplementationOnce(() => ({ url: 'file:///app/node_modules/next/server.js' }))
+
+    const result = resolveNextSubpath('next/server', context, nextResolve)
+
+    expect(result.url).toBe('file:///app/node_modules/next/server.js')
+    expect(nextResolve).toHaveBeenNthCalledWith(1, 'next/server', context)
+    expect(nextResolve).toHaveBeenNthCalledWith(2, 'next/server.js', context)
+  })
+
+  it('covers the other subpaths route modules import', () => {
+    for (const subpath of ['next/headers', 'next/navigation', 'next/cache']) {
+      const nextResolve = jest
+        .fn()
+        .mockImplementationOnce(() => { throw notFound(subpath) })
+        .mockImplementationOnce((resolvedSpecifier: string) => ({
+          url: `file:///app/node_modules/${resolvedSpecifier}`,
+        }))
+      expect(resolveNextSubpath(subpath, context, nextResolve).url).toBe(`file:///app/node_modules/${subpath}.js`)
+    }
+  })
+
+  it('does not retry deeper or already-suffixed specifiers', () => {
+    for (const specifier of ['next/server.js', 'next/dist/server/web/spec-extension/response', 'next']) {
+      const nextResolve = jest.fn(() => { throw notFound(specifier) })
+      expect(() => resolveNextSubpath(specifier, context, nextResolve)).toThrow(/Cannot find module/)
+      expect(nextResolve).toHaveBeenCalledTimes(1)
+    }
+  })
+
+  it('rethrows the original error when the .js form is missing too', () => {
+    const original = notFound('/app/node_modules/next/server')
+    const nextResolve = jest
+      .fn()
+      .mockImplementationOnce(() => { throw original })
+      .mockImplementationOnce(() => { throw notFound('/app/node_modules/next/server.js') })
+
+    expect(() => resolveNextSubpath('next/server', context, nextResolve)).toThrow(original)
+  })
+
+  it('rethrows errors that are not ERR_MODULE_NOT_FOUND without retrying', () => {
+    const syntaxError = Object.assign(new Error('bad package.json'), { code: 'ERR_INVALID_PACKAGE_CONFIG' })
+    const nextResolve = jest.fn(() => { throw syntaxError })
+
+    expect(() => resolveNextSubpath('next/server', context, nextResolve)).toThrow(syntaxError)
+    expect(nextResolve).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('installNextSubpathResolveHook', () => {
+  beforeEach(() => {
+    resetNextSubpathResolveHookForTests()
+  })
+
+  it('registers the resolve hook once per process', () => {
+    const register = jest.fn()
+
+    expect(installNextSubpathResolveHook(register, null)).toBe(true)
+    expect(installNextSubpathResolveHook(register, null)).toBe(false)
+
+    expect(register).toHaveBeenCalledTimes(1)
+    expect(register).toHaveBeenCalledWith({ resolve: resolveNextSubpath })
+  })
+
+  it('registers an asynchronous hook on Node 22.0-22.14', () => {
+    const registerHookModule = jest.fn()
+
+    expect(installNextSubpathResolveHook(null, registerHookModule)).toBe(true)
+    expect(registerHookModule).toHaveBeenCalledWith(
+      expect.objectContaining({ href: expect.stringMatching(/next-subpath-resolve-hook-worker\.js$/) }),
+      expect.stringMatching(/^file:/),
+    )
+  })
+
+  it('is a no-op on a runtime without either registration API', () => {
+    expect(installNextSubpathResolveHook(null, null)).toBe(false)
+  })
+})
+
+describe('resolveNextSubpathAsync', () => {
+  const context = { parentURL: 'file:///app/route.js' }
+
+  it('retries a bare next/<subpath> with the .js suffix', async () => {
+    const nextResolve = jest
+      .fn()
+      .mockRejectedValueOnce(notFound('/app/node_modules/next/server'))
+      .mockResolvedValueOnce({ url: 'file:///app/node_modules/next/server.js' })
+
+    const result = await resolveNextSubpathAsync('next/server', context, nextResolve)
+
+    expect(result.url).toBe('file:///app/node_modules/next/server.js')
+    expect(nextResolve).toHaveBeenNthCalledWith(1, 'next/server', context)
+    expect(nextResolve).toHaveBeenNthCalledWith(2, 'next/server.js', context)
+  })
+})
+
+describe('installNextSubpathResolveHook against the runtime node:module', () => {
+  afterEach(() => {
+    jest.dontMock('node:module')
+    jest.resetModules()
+  })
+
+  it('installs through node:module.register on Node 22.0-22.14', () => {
+    // A named import of `registerHooks` would throw while the module loads on
+    // such a runtime; the helper must load and use the older registration API.
+    jest.resetModules()
+    const register = jest.fn()
+    jest.doMock('node:module', () => ({ register }))
+    let installed: boolean | undefined
+    jest.isolateModules(() => {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const hookModule = require('../next-subpath-resolve-hook') as typeof import('../next-subpath-resolve-hook')
+      installed = hookModule.installNextSubpathResolveHook()
+    })
+    expect(installed).toBe(true)
+    expect(register).toHaveBeenCalledTimes(1)
+    expect(register.mock.calls[0][0]).toEqual(
+      expect.objectContaining({ href: expect.stringMatching(/next-subpath-resolve-hook-worker\.js$/) }),
+    )
+  })
+
+  it('installs through node:module.registerHooks when the runtime has it', () => {
+    jest.resetModules()
+    const register = jest.fn()
+    jest.doMock('node:module', () => ({ registerHooks: register }))
+    let installed: boolean | undefined
+    jest.isolateModules(() => {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const hookModule = require('../next-subpath-resolve-hook') as typeof import('../next-subpath-resolve-hook')
+      installed = hookModule.installNextSubpathResolveHook()
+    })
+    expect(installed).toBe(true)
+    expect(register).toHaveBeenCalledTimes(1)
+    expect(register.mock.calls[0][0]).toEqual({ resolve: expect.any(Function) })
+  })
+})

package/src/lib/bootstrap/dynamicLoader.ts

@@ -16,7 +16,7 @@ import { CLIENT_ONLY_STUB_NAMESPACE, createClientOnlyStubPlugin } from './client
 import path from 'node:path'
 import fs from 'node:fs'
 import crypto from 'node:crypto'
-import { createRequire } from 'node:module'
+import { createRequire, isBuiltin } from 'node:module'
 import { pathToFileURL } from 'node:url'
 
 let activeBootstrapLoads = 0
@@ -77,6 +77,44 @@ class GeneratedFileNotFoundError extends Error {
   }
 }
 
+function splitBareSpecifier(specifier: string): { packageName: string; subpath: string } | null {
+  const segments = specifier.split('/')
+  const nameLength = specifier.startsWith('@') ? 2 : 1
+  if (segments.length <= nameLength || segments.slice(0, nameLength).some((segment) => !segment)) return null
+  return {
+    packageName: segments.slice(0, nameLength).join('/'),
+    subpath: segments.slice(nameLength).join('/'),
+  }
+}
+
+/**
+ * Rewrites an externalized `pkg/subpath` specifier to the file Node's ESM resolver can load
+ * when `pkg` publishes no `exports` map (#6993). Builtins, packages with `exports`, subpaths
+ * that already carry an extension and anything that fails to resolve keep the original
+ * specifier, so the bundle never gets worse than before.
+ */
+function rewriteLegacySubpathSpecifier(
+  specifier: string,
+  appRequire: NodeRequire,
+  onRewrite: (manifestPath: string) => void,
+): string {
+  if (isBuiltin(specifier)) return specifier
+  const parts = splitBareSpecifier(specifier)
+  if (!parts || path.posix.extname(parts.subpath)) return specifier
+  try {
+    const manifestPath = appRequire.resolve(`${parts.packageName}/package.json`)
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as { exports?: unknown }
+    if (manifest.exports != null) return specifier
+    const resolvedFile = appRequire.resolve(specifier)
+    const relativeFile = path.relative(path.dirname(manifestPath), resolvedFile)
+    if (!relativeFile || relativeFile.startsWith('..') || path.isAbsolute(relativeFile)) return specifier
+    onRewrite(manifestPath)
+    return `${parts.packageName}/${relativeFile.split(path.sep).join('/')}`
+  } catch {
+    return specifier
+  }
+}
+
 /**
  * esbuild plugins for the CLI bundle, in resolution order. The client-only stub must come
  * first so it wins over the alias and external plugins for `*.client` dynamic imports.
@@ -85,7 +123,10 @@ class GeneratedFileNotFoundError extends Error {
  * `createClientOnlyStubPlugin` in isolation stays green if the plugin is dropped from this
  * list, which would silently reintroduce #4623.
  */
-export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugin[] {
+export function createCliBundlePlugins(
+  appRoot: string,
+  options: { onLegacySubpathRewrite?: (manifestPath: string) => void } = {},
+): import('esbuild').Plugin[] {
   // Plugin to resolve the @/ alias the way the app tsconfig maps it:
   // `@/.mercato/*` to the app root, every other `@/*` to the app's src/ directory.
   const aliasPlugin: import('esbuild').Plugin = {
@@ -113,6 +154,19 @@ export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugi
     },
   }
 
+  // Node's ESM resolver only maps an extensionless package subpath (`next/link`) when the
+  // package publishes an `exports` map; legacy packages need the real file path instead.
+  const appRequire = createRequire(path.join(appRoot, 'package.json'))
+  const externalSpecifierCache = new Map<string, string>()
+  const onLegacySubpathRewrite = options.onLegacySubpathRewrite ?? (() => undefined)
+  const resolveExternalSpecifier = (specifier: string): string => {
+    const cached = externalSpecifierCache.get(specifier)
+    if (cached !== undefined) return cached
+    const resolved = rewriteLegacySubpathSpecifier(specifier, appRequire, onLegacySubpathRewrite)
+    externalSpecifierCache.set(specifier, resolved)
+    return resolved
+  }
+
   // Plugin to mark non-JSON package imports as external
   const externalNonJsonPlugin: import('esbuild').Plugin = {
     name: 'external-non-json',
@@ -129,7 +183,7 @@ export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugi
           return null // Let esbuild handle it
         }
         // Otherwise mark as external
-        return { path: args.path, external: true }
+        return { path: resolveExternalSpecifier(args.path), external: true }
       })
     },
   }
@@ -137,7 +191,7 @@ export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugi
   return [createClientOnlyStubPlugin(), aliasPlugin, externalNonJsonPlugin]
 }
 
-const DYNAMIC_LOADER_CACHE_VERSION = 4
+const DYNAMIC_LOADER_CACHE_VERSION = 5
 
 type DynamicLoaderCacheMetadata = {
   version: number
@@ -433,6 +487,7 @@ async function compileAppSourceFileWithActiveEsbuild(
   // Dynamically import esbuild only when needed
   const esbuild = await getEsbuildRuntime()
 
+  const rewrittenPackageManifests = new Set<string>()
   // Use esbuild.build with bundling to handle JSON imports
   const result = await esbuild.build({
     entryPoints: [tsPath],
@@ -444,7 +499,9 @@ async function compileAppSourceFileWithActiveEsbuild(
     platform: 'node',
     target: 'node18',
     tsconfig: appTsconfig,
-    plugins: createCliBundlePlugins(appRoot),
+    plugins: createCliBundlePlugins(appRoot, {
+      onLegacySubpathRewrite: (manifestPath) => rewrittenPackageManifests.add(manifestPath),
+    }),
     // Allow JSON imports
     loader: { '.json': 'json' },
   })
@@ -455,6 +512,7 @@ async function compileAppSourceFileWithActiveEsbuild(
     dependencies: {
       ...collectDependencyHashes(appRoot, result.metafile.inputs),
       ...hashFilesRelativeTo(appRoot, tsconfigPaths),
+      ...hashFilesRelativeTo(appRoot, [...rewrittenPackageManifests]),
     },
   }
   fs.writeFileSync(metadataPath, JSON.stringify(metadata))

package/src/lib/bootstrap/next-subpath-resolve-hook-worker.ts

@@ -0,0 +1,3 @@
+import { resolveNextSubpathAsync } from './next-subpath-resolve-hook'
+
+export const resolve = resolveNextSubpathAsync

package/src/lib/bootstrap/next-subpath-resolve-hook.ts

@@ -0,0 +1,130 @@
+/**
+ * Node ESM resolution for `next/<subpath>` outside the Next bundler (#6118, #7102).
+ *
+ * Installed by the `mercato` CLI entry, so every CLI command and worker it
+ * runs can load package dists that import `next/dynamic`, `next/link`,
+ * `next/server` … The `next/dynamic` imports in particular MUST keep the bare
+ * specifier: Next's `next_dynamic` compiler transform only matches it exactly.
+ *
+ * `mercato ai_assistant mcp:serve-http` (and `mcp:serve`, `mcp:dev`,
+ * `mcp:list-tools`) run in plain Node, and the AI API operation runner loads
+ * API route modules with a runtime `import()`. Those modules import
+ * `NextResponse` from `'next/server'`: a bare package subpath that only a
+ * bundler resolves, because `next` ships no `exports` map and Node's ESM
+ * resolver does no extension guessing. Every route with that import (287 of
+ * them on the 0.7.0 packages) therefore fails to load with
+ * `ERR_MODULE_NOT_FOUND … node_modules/next/server`, and every tool backed by
+ * such a route returns "Failed to load route module".
+ *
+ * `next/server.js`, `next/headers.js`, `next/navigation.js` … do exist as files,
+ * which is why `@open-mercato/shared` imports `'next/headers.js'`. Rather than
+ * rewriting several hundred imports across every package (and every
+ * third-party module), this hook retries a failed bare `next/<subpath>` with
+ * the `.js` suffix. It only runs in the processes that install it, only for
+ * `next/*` specifiers, and only after the normal resolution failed, so it
+ * becomes a no-op the day `next` publishes an `exports` map.
+ */
+import * as nodeModule from 'node:module'
+
+type ResolveContext = Record<string, unknown>
+type ResolveResult = { url: string; format?: string | null | undefined; shortCircuit?: boolean }
+type NextResolve = (specifier: string, context?: ResolveContext) => ResolveResult
+type AsyncNextResolve = (specifier: string, context?: ResolveContext) => ResolveResult | Promise<ResolveResult>
+
+/** Bare `next/<one segment>` specifiers, e.g. `next/server`, `next/headers`. */
+const NEXT_BARE_SUBPATH = /^next\/[A-Za-z0-9_-]+$/
+
+let installed = false
+
+function isModuleNotFound(error: unknown): boolean {
+  return Boolean(error) && typeof error === 'object' && (error as { code?: unknown }).code === 'ERR_MODULE_NOT_FOUND'
+}
+
+/**
+ * The resolve hook itself. Exported so it can be tested without touching the
+ * process-global hook chain.
+ */
+export function resolveNextSubpath(
+  specifier: string,
+  context: ResolveContext,
+  nextResolve: NextResolve,
+): ResolveResult {
+  if (!NEXT_BARE_SUBPATH.test(specifier)) return nextResolve(specifier, context)
+  try {
+    return nextResolve(specifier, context)
+  } catch (error) {
+    if (!isModuleNotFound(error)) throw error
+    try {
+      return nextResolve(`${specifier}.js`, context)
+    } catch {
+      // Neither form resolves (Next is not installed at all): surface the
+      // original error, which names the specifier the caller wrote.
+      throw error
+    }
+  }
+}
+
+export async function resolveNextSubpathAsync(
+  specifier: string,
+  context: ResolveContext,
+  nextResolve: AsyncNextResolve,
+): Promise<ResolveResult> {
+  if (!NEXT_BARE_SUBPATH.test(specifier)) return nextResolve(specifier, context)
+  try {
+    return await nextResolve(specifier, context)
+  } catch (error) {
+    if (!isModuleNotFound(error)) throw error
+    try {
+      return await nextResolve(`${specifier}.js`, context)
+    } catch {
+      throw error
+    }
+  }
+}
+
+type RegisterHooks = (hooks: { resolve: typeof resolveNextSubpath }) => unknown
+type RegisterHookModule = (specifier: string | URL, parentURL?: string | URL) => unknown
+
+/**
+ * `module.registerHooks` exists from Node 22.15. It is read off the namespace
+ * rather than imported by name: in the published ESM build a named import of an
+ * export the running Node lacks fails while the module links, before the check
+ * in `installNextSubpathResolveHook` can run, and the package still declares
+ * `node >= 22.0.0`.
+ */
+function runtimeRegisterHooks(): RegisterHooks | undefined {
+  const candidate = (nodeModule as unknown as { registerHooks?: unknown }).registerHooks
+  return typeof candidate === 'function' ? (candidate as RegisterHooks) : undefined
+}
+
+function runtimeRegisterHookModule(): RegisterHookModule | undefined {
+  const candidate = (nodeModule as unknown as { register?: unknown }).register
+  return typeof candidate === 'function' ? (candidate as RegisterHookModule) : undefined
+}
+
+/**
+ * Install the hook once per process. Returns `true` when it was installed by
+ * this call, `false` when it already was or when the runtime has neither
+ * registration API. Node 22.15+ uses the synchronous hook API; earlier
+ * supported Node 22 releases use the asynchronous hook API.
+ */
+export function installNextSubpathResolveHook(
+  registerHooks: RegisterHooks | null | undefined = runtimeRegisterHooks(),
+  registerHookModule: RegisterHookModule | null | undefined = runtimeRegisterHookModule(),
+): boolean {
+  if (installed) return false
+  if (typeof registerHooks === 'function') {
+    registerHooks({ resolve: resolveNextSubpath })
+  } else if (typeof registerHookModule === 'function') {
+    registerHookModule(new URL('./next-subpath-resolve-hook-worker.js', import.meta.url), import.meta.url)
+  } else {
+    return false
+  }
+  installed = true
+  return true
+}
+
+/** Test seam: forget that the hook was installed. */
+export function resetNextSubpathResolveHookForTests(): void {
+  installed = false
+}