@open-mercato/shared 0.9.1-develop.7475.1.28ca93ed97 → 0.9.1-develop.7477.1.64ba865101

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
 [generate-countries] up to date (259 countries)
-[build:shared] found 317 entry points
+[build:shared] found 319 entry points
 [build:shared] built successfully

package/dist/lib/bootstrap/next-subpath-resolve-hook-worker.js

@@ -0,0 +1,6 @@
+import { resolveNextSubpathAsync } from "./next-subpath-resolve-hook.js";
+const resolve = resolveNextSubpathAsync;
+export {
+  resolve
+};
+//# sourceMappingURL=next-subpath-resolve-hook-worker.js.map

package/dist/lib/bootstrap/next-subpath-resolve-hook-worker.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/bootstrap/next-subpath-resolve-hook-worker.ts"],
+  "sourcesContent": ["import { resolveNextSubpathAsync } from './next-subpath-resolve-hook'\n\nexport const resolve = resolveNextSubpathAsync\n"],
+  "mappings": "AAAA,SAAS,+BAA+B;AAEjC,MAAM,UAAU;",
+  "names": []
+}

package/dist/lib/bootstrap/next-subpath-resolve-hook.js

@@ -0,0 +1,62 @@
+import * as nodeModule from "node:module";
+const NEXT_BARE_SUBPATH = /^next\/[A-Za-z0-9_-]+$/;
+let installed = false;
+function isModuleNotFound(error) {
+  return Boolean(error) && typeof error === "object" && error.code === "ERR_MODULE_NOT_FOUND";
+}
+function resolveNextSubpath(specifier, context, nextResolve) {
+  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 {
+      throw error;
+    }
+  }
+}
+async function resolveNextSubpathAsync(specifier, context, nextResolve) {
+  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;
+    }
+  }
+}
+function runtimeRegisterHooks() {
+  const candidate = nodeModule.registerHooks;
+  return typeof candidate === "function" ? candidate : void 0;
+}
+function runtimeRegisterHookModule() {
+  const candidate = nodeModule.register;
+  return typeof candidate === "function" ? candidate : void 0;
+}
+function installNextSubpathResolveHook(registerHooks = runtimeRegisterHooks(), registerHookModule = runtimeRegisterHookModule()) {
+  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;
+}
+function resetNextSubpathResolveHookForTests() {
+  installed = false;
+}
+export {
+  installNextSubpathResolveHook,
+  resetNextSubpathResolveHookForTests,
+  resolveNextSubpath,
+  resolveNextSubpathAsync
+};
+//# sourceMappingURL=next-subpath-resolve-hook.js.map

package/dist/lib/bootstrap/next-subpath-resolve-hook.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/bootstrap/next-subpath-resolve-hook.ts"],
+  "sourcesContent": ["/**\n * Node ESM resolution for `next/<subpath>` outside the Next bundler (#6118, #7102).\n *\n * Installed by the `mercato` CLI entry, so every CLI command and worker it\n * runs can load package dists that import `next/dynamic`, `next/link`,\n * `next/server` \u2026 The `next/dynamic` imports in particular MUST keep the bare\n * specifier: Next's `next_dynamic` compiler transform only matches it exactly.\n *\n * `mercato ai_assistant mcp:serve-http` (and `mcp:serve`, `mcp:dev`,\n * `mcp:list-tools`) run in plain Node, and the AI API operation runner loads\n * API route modules with a runtime `import()`. Those modules import\n * `NextResponse` from `'next/server'`: a bare package subpath that only a\n * bundler resolves, because `next` ships no `exports` map and Node's ESM\n * resolver does no extension guessing. Every route with that import (287 of\n * them on the 0.7.0 packages) therefore fails to load with\n * `ERR_MODULE_NOT_FOUND \u2026 node_modules/next/server`, and every tool backed by\n * such a route returns \"Failed to load route module\".\n *\n * `next/server.js`, `next/headers.js`, `next/navigation.js` \u2026 do exist as files,\n * which is why `@open-mercato/shared` imports `'next/headers.js'`. Rather than\n * rewriting several hundred imports across every package (and every\n * third-party module), this hook retries a failed bare `next/<subpath>` with\n * the `.js` suffix. It only runs in the processes that install it, only for\n * `next/*` specifiers, and only after the normal resolution failed, so it\n * becomes a no-op the day `next` publishes an `exports` map.\n */\nimport * as nodeModule from 'node:module'\n\ntype ResolveContext = Record<string, unknown>\ntype ResolveResult = { url: string; format?: string | null | undefined; shortCircuit?: boolean }\ntype NextResolve = (specifier: string, context?: ResolveContext) => ResolveResult\ntype AsyncNextResolve = (specifier: string, context?: ResolveContext) => ResolveResult | Promise<ResolveResult>\n\n/** Bare `next/<one segment>` specifiers, e.g. `next/server`, `next/headers`. */\nconst NEXT_BARE_SUBPATH = /^next\\/[A-Za-z0-9_-]+$/\n\nlet installed = false\n\nfunction isModuleNotFound(error: unknown): boolean {\n  return Boolean(error) && typeof error === 'object' && (error as { code?: unknown }).code === 'ERR_MODULE_NOT_FOUND'\n}\n\n/**\n * The resolve hook itself. Exported so it can be tested without touching the\n * process-global hook chain.\n */\nexport function resolveNextSubpath(\n  specifier: string,\n  context: ResolveContext,\n  nextResolve: NextResolve,\n): ResolveResult {\n  if (!NEXT_BARE_SUBPATH.test(specifier)) return nextResolve(specifier, context)\n  try {\n    return nextResolve(specifier, context)\n  } catch (error) {\n    if (!isModuleNotFound(error)) throw error\n    try {\n      return nextResolve(`${specifier}.js`, context)\n    } catch {\n      // Neither form resolves (Next is not installed at all): surface the\n      // original error, which names the specifier the caller wrote.\n      throw error\n    }\n  }\n}\n\nexport async function resolveNextSubpathAsync(\n  specifier: string,\n  context: ResolveContext,\n  nextResolve: AsyncNextResolve,\n): Promise<ResolveResult> {\n  if (!NEXT_BARE_SUBPATH.test(specifier)) return nextResolve(specifier, context)\n  try {\n    return await nextResolve(specifier, context)\n  } catch (error) {\n    if (!isModuleNotFound(error)) throw error\n    try {\n      return await nextResolve(`${specifier}.js`, context)\n    } catch {\n      throw error\n    }\n  }\n}\n\ntype RegisterHooks = (hooks: { resolve: typeof resolveNextSubpath }) => unknown\ntype RegisterHookModule = (specifier: string | URL, parentURL?: string | URL) => unknown\n\n/**\n * `module.registerHooks` exists from Node 22.15. It is read off the namespace\n * rather than imported by name: in the published ESM build a named import of an\n * export the running Node lacks fails while the module links, before the check\n * in `installNextSubpathResolveHook` can run, and the package still declares\n * `node >= 22.0.0`.\n */\nfunction runtimeRegisterHooks(): RegisterHooks | undefined {\n  const candidate = (nodeModule as unknown as { registerHooks?: unknown }).registerHooks\n  return typeof candidate === 'function' ? (candidate as RegisterHooks) : undefined\n}\n\nfunction runtimeRegisterHookModule(): RegisterHookModule | undefined {\n  const candidate = (nodeModule as unknown as { register?: unknown }).register\n  return typeof candidate === 'function' ? (candidate as RegisterHookModule) : undefined\n}\n\n/**\n * Install the hook once per process. Returns `true` when it was installed by\n * this call, `false` when it already was or when the runtime has neither\n * registration API. Node 22.15+ uses the synchronous hook API; earlier\n * supported Node 22 releases use the asynchronous hook API.\n */\nexport function installNextSubpathResolveHook(\n  registerHooks: RegisterHooks | null | undefined = runtimeRegisterHooks(),\n  registerHookModule: RegisterHookModule | null | undefined = runtimeRegisterHookModule(),\n): boolean {\n  if (installed) return false\n  if (typeof registerHooks === 'function') {\n    registerHooks({ resolve: resolveNextSubpath })\n  } else if (typeof registerHookModule === 'function') {\n    registerHookModule(new URL('./next-subpath-resolve-hook-worker.js', import.meta.url), import.meta.url)\n  } else {\n    return false\n  }\n  installed = true\n  return true\n}\n\n/** Test seam: forget that the hook was installed. */\nexport function resetNextSubpathResolveHookForTests(): void {\n  installed = false\n}\n"],
+  "mappings": "AA0BA,YAAY,gBAAgB;AAQ5B,MAAM,oBAAoB;AAE1B,IAAI,YAAY;AAEhB,SAAS,iBAAiB,OAAyB;AACjD,SAAO,QAAQ,KAAK,KAAK,OAAO,UAAU,YAAa,MAA6B,SAAS;AAC/F;AAMO,SAAS,mBACd,WACA,SACA,aACe;AACf,MAAI,CAAC,kBAAkB,KAAK,SAAS,EAAG,QAAO,YAAY,WAAW,OAAO;AAC7E,MAAI;AACF,WAAO,YAAY,WAAW,OAAO;AAAA,EACvC,SAAS,OAAO;AACd,QAAI,CAAC,iBAAiB,KAAK,EAAG,OAAM;AACpC,QAAI;AACF,aAAO,YAAY,GAAG,SAAS,OAAO,OAAO;AAAA,IAC/C,QAAQ;AAGN,YAAM;AAAA,IACR;AAAA,EACF;AACF;AAEA,eAAsB,wBACpB,WACA,SACA,aACwB;AACxB,MAAI,CAAC,kBAAkB,KAAK,SAAS,EAAG,QAAO,YAAY,WAAW,OAAO;AAC7E,MAAI;AACF,WAAO,MAAM,YAAY,WAAW,OAAO;AAAA,EAC7C,SAAS,OAAO;AACd,QAAI,CAAC,iBAAiB,KAAK,EAAG,OAAM;AACpC,QAAI;AACF,aAAO,MAAM,YAAY,GAAG,SAAS,OAAO,OAAO;AAAA,IACrD,QAAQ;AACN,YAAM;AAAA,IACR;AAAA,EACF;AACF;AAYA,SAAS,uBAAkD;AACzD,QAAM,YAAa,WAAsD;AACzE,SAAO,OAAO,cAAc,aAAc,YAA8B;AAC1E;AAEA,SAAS,4BAA4D;AACnE,QAAM,YAAa,WAAiD;AACpE,SAAO,OAAO,cAAc,aAAc,YAAmC;AAC/E;AAQO,SAAS,8BACd,gBAAkD,qBAAqB,GACvE,qBAA4D,0BAA0B,GAC7E;AACT,MAAI,UAAW,QAAO;AACtB,MAAI,OAAO,kBAAkB,YAAY;AACvC,kBAAc,EAAE,SAAS,mBAAmB,CAAC;AAAA,EAC/C,WAAW,OAAO,uBAAuB,YAAY;AACnD,uBAAmB,IAAI,IAAI,yCAAyC,YAAY,GAAG,GAAG,YAAY,GAAG;AAAA,EACvG,OAAO;AACL,WAAO;AAAA,EACT;AACA,cAAY;AACZ,SAAO;AACT;AAGO,SAAS,sCAA4C;AAC1D,cAAY;AACd;",
+  "names": []
+}

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.9.1-develop.7475.1.28ca93ed97";
+const APP_VERSION = "0.9.1-develop.7477.1.64ba865101";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.9.1-develop.7475.1.28ca93ed97';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.9.1-develop.7477.1.64ba865101';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.9.1-develop.7475.1.28ca93ed97",
+  "version": "0.9.1-develop.7477.1.64ba865101",
   "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.7475.1.28ca93ed97",
+    "@open-mercato/cache": "0.9.1-develop.7477.1.64ba865101",
     "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",

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/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
+}