@nifrajs/cli 4.0.2 → 5.1.0

package/src/cli.ts

@@ -24,7 +24,7 @@ import { formatShadowedPages, shadowedPages } from "@nifrajs/web/route-manifest"
 import type { BunPlugin } from "bun"
 import { adapterFile, BACKEND_APP_FILE } from "./app-files.ts"
 import { bindCommandArgv, findCommandSpec, renderCommandCatalogHelp } from "./command-catalog.ts"
-import { applyEnvFiles, forgetAutoLoadedEnv, takeEnvFileFlags } from "./env-file.ts"
+import { applyEnvFiles, forgetAutoLoadedEnv, REFLECT_ENV, takeEnvFileFlags } from "./env-file.ts"
 import { FRAMEWORK_WEB_OPTIONS, type LoadedApp, loadApp, type NifraFramework } from "./load.ts"
 import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 import {
@@ -126,6 +126,9 @@ Usage:
                                          one left. Exits 1 while current-code errors are open.
   nifra logs    [--since <n>] [--level <l>] [--grep <s>]  The dev server's console, server and
                                          browser, each line tagged with its request.
+  nifra explain [<message>] [--stack <s>] [--name <n>]  A structured diagnostic for an error: its
+                                         code, the frame in your source, and the cause and fix when
+                                         nifra knows them. No message: the dev server's latest error.
   nifra cdn-check <url>                  Check a deployed page behind a CDN: served from cache, no
                                          internal or CDN-only headers reaching the visitor, and soft
                                          navigations get page data, not the cached document. Exits 1
@@ -165,6 +168,10 @@ Usage:
                                          against it: a route the target can't honour (an ssr route on a
                                          static build, ISR where there's no revalidation) exits nonzero
                                          with the consequence - run in CI so it fails the build, not prod.
+  nifra routes --hooks [--json]          List the hooks each backend route and each prefix's unmatched
+               [--since <file>]          paths actually run: kind, plugin name, and where it was
+                                         registered (app, group, merge, mount). --since diffs against a
+                                         saved --json report.
   nifra init-agents [--force] [--json]   Retrofit an EXISTING app with the agent files a new app ships:
                                          .mcp.json + .cursor/mcp.json (register this project's nifra MCP),
                                          each agent's pointer to AGENTS.md (CLAUDE.md, GEMINI.md,
@@ -201,6 +208,8 @@ Usage:
                                          backend code in browser code). Run as "done"; --json for agents;
                                          --sarif emits the same stable diagnostics as SARIF 2.1.0 for external
                                          review tools; --lints-only skips tsc for a near-instant inner-loop pass.
+                                         With a contracts.lock.json, both modes import backend/app.ts
+                                         (running its top-level code) to compare the routes it serves.
   nifra verify   [--release] [--json]    Run the shared repository verification gate. --release runs the
                                          full build, test, coverage, corpus, consumer, and cross-runtime gate.
   nifra fix     [--code <NF-code>]       Apply a registered diagnostic recipe, then print the remaining
@@ -262,20 +271,28 @@ Usage:
                 [--list] [--json]        apply exact imports, pin every matching dependency (keeping
                 [--exact]                ^/~, or exact with --exact), then verify with nifra check.
                 [--allow-downgrade]      Dry-run by default; --write applies then verifies (--no-verify
-                                         to skip). --list shows available targets. A version newer than
+                [--no-hooks]             to skip), then prints how hook scope changed (--no-hooks to
+                                         skip). --list shows available targets. A version newer than
                                          this CLI prints the command for that release's CLI. Fail-closed
                                          on an unknown version or a rollback (--allow-downgrade
                                          overrides). Deterministic + idempotent.
-  nifra migrate layout [--write] [--json]
+  nifra migrate layout [--write] [--zones] [--json]
                                          Move an app onto the frontend/backend split: split each route
                                          into x.tsx + x.backend.ts, fold _middleware.ts into
                                          _layout.backend.ts, move backend.ts/framework.ts under backend/,
-                                         and zone the other modules into frontend/, backend/ or shared/.
-                                         Dry-run by default; --write applies.
+                                         and zone the other modules into frontend/, backend/ or shared/
+                                         (--zones keeps them in place and lists them in package.json
+                                         "nifra.zones"). Dry-run by default; --write applies.
   nifra types   [--check] [--json]       Generate each route's ./+types module under .nifra/types: its
                                          params, the data its output schemas let through, and api typed
                                          by backend/app.ts. dev, build and check refresh them too;
                                          --check fails when one is stale.
+  nifra schemas [--write] [--check] [--json]
+                                         Draft loaderOutput/actionOutput from each loader's and
+                                         action's return type for review; --write adds the missing
+                                         ones (marked nifra:generated) and refreshes generated ones.
+                                         Lists the returned fields a hand-written schema drops;
+                                         --check fails on a missing, stale or any-typed one.
   nifra port    [--target <t>] [--json]  Portability linter: print a feature × deploy-target capability
                 [--ci] [--strict]        matrix (in-memory stores, in-process cron/WebSocket, Bun/Deno
                                          globals, node: builtins) with file:line evidence. --target auto-
@@ -304,12 +321,23 @@ set in the process environment is never overwritten by a file.
 ${renderCommandCatalogHelp()}`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "4.0.2"
+const CLI_VERSION = "5.1.0"
 
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v: unknown): RenderAdapter => v as RenderAdapter
 const asBunPlugins = (v: readonly unknown[]): BunPlugin[] => v as BunPlugin[]
 
+// biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Trusted application configuration supplies native Vite plugins; the pinned pipeline validates their hooks.
+const asComponentPlugins = (
+  value: readonly unknown[],
+): NonNullable<
+  import("@nifrajs/web/server-components/build").ComponentPipelineOptions["plugins"]
+> =>
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Trusted config forwards the pinned Vite plugin ABI; this does not accept request data.
+  value as NonNullable<
+    import("@nifrajs/web/server-components/build").ComponentPipelineOptions["plugins"]
+  >
+
 /**
  * Render an error for the CLI, unwrapping the detail a bare `.message` drops.
  *
@@ -344,7 +372,36 @@ export function formatCliError(err: unknown): string {
   return String(err)
 }
 
+/** A failed command's message on stderr and, for a `--json` caller parsing stdout, as JSON there. */
+function reportFailure(err: unknown, argv: readonly string[]): void {
+  const message = formatCliError(err)
+  console.error(message)
+  if (argv.includes("--json") || argv.includes("--json=true"))
+    console.log(JSON.stringify({ ok: false, error: message }, null, 2))
+}
+
 async function dev(app: LoadedApp, flags: Flags): Promise<void> {
+  if (app.framework.componentPipeline !== undefined) {
+    if (flags.bun)
+      throw new Error(
+        "[nifra/components] Components require the Vite 8 pipeline; Bun remains a server runtime",
+      )
+    const { devServerComponents } = await import("@nifrajs/web/server-components/build")
+    if (
+      app.resolvedPlugins.clientPlugins.length > 0 ||
+      app.resolvedPlugins.serverPlugins.length > 0
+    )
+      throw new Error(
+        "[nifra/components] Use Vite equivalents for client/server Bun plugins in the component pipeline",
+      )
+    await devServerComponents({
+      ...app.framework.componentPipeline,
+      root: app.cwd,
+      port: flags.port,
+      plugins: asComponentPlugins(app.resolvedPlugins.vitePlugins),
+    })
+    return
+  }
   if (flags.vite && flags.bun) {
     throw new Error("[nifra] `nifra dev` takes `--vite` or `--bun`, not both.")
   }
@@ -511,6 +568,7 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
       ...(fw.conditions ? { conditions: fw.conditions } : {}),
       ...(fw.define ? { define: fw.define } : {}),
       indicator: showsIndicator(flags, fw),
+      allowedHosts: fw.dev?.allowedHosts ?? [],
       createApp: (clientEntry, importQuery, dev) =>
         createWebApp({
           adapter: asAdapter(fw.adapter),
@@ -693,7 +751,7 @@ async function assertFreshWorkspaceDists(cwd: string): Promise<void> {
   let rootPackage: Record<string, unknown>
   try {
     rootPackage = JSON.parse(readFileSync(pkgPath, "utf8")) as Record<string, unknown>
-    // @nifra-gate-reviewed: not a security gate. An unreadable/non-JSON package.json is a separate
+    // nifra-expect NF-S001: not a security gate. An unreadable/non-JSON package.json is a separate
     // build problem; returning here skips the freshness check rather than masking a denial.
   } catch {
     return // an unreadable/!JSON package.json is a separate problem; don't mask it as a stale-dist failure
@@ -727,6 +785,40 @@ async function buildForTarget(
     throw new Error("[nifra] `nifra build` takes `--vite` or `--bun`, not both.")
   }
   const { framework: fw } = app
+  if (fw.componentPipeline !== undefined) {
+    if (flags.bun)
+      throw new Error(
+        "[nifra/components] Components require the Vite 8 pipeline; Bun remains a server runtime",
+      )
+    if (target === "static")
+      throw new Error(
+        "[nifra/components] Component owners require private per-request execution; choose bun, node, deno, cloudflare, or vercel",
+      )
+    if (
+      app.resolvedPlugins.clientPlugins.length > 0 ||
+      app.resolvedPlugins.serverPlugins.length > 0
+    )
+      throw new Error(
+        "[nifra/components] Use Vite equivalents for client/server Bun plugins in the component pipeline",
+      )
+    const { buildServerComponents } = await import("@nifrajs/web/server-components/build")
+    const outDir =
+      target === "vercel" && flags.out === undefined
+        ? resolve(app.cwd, ".vercel/output")
+        : app.outDir
+    const result = await buildServerComponents({
+      ...fw.componentPipeline,
+      target,
+      root: app.cwd,
+      outDir,
+      plugins: asComponentPlugins(app.resolvedPlugins.vitePlugins),
+    })
+    await assertFreshWorkspaceDists(app.cwd)
+    console.log(
+      `[nifra/components] Built ${fw.componentPipeline.adapter} for ${target} (${result.build}) in ${outDir}`,
+    )
+    return
+  }
   const cssCodeSplitRequested = fw.cssCodeSplit === false
   const hasBunTransforms =
     app.resolvedPlugins.clientPlugins.length > 0 || app.resolvedPlugins.serverPlugins.length > 0
@@ -876,35 +968,73 @@ async function start(app: LoadedApp, flags: Flags): Promise<void> {
   await import(serverFile)
 }
 
+const VALUE_FLAGS: Readonly<Record<string, "port" | "out" | "target">> = {
+  "--port": "port",
+  "-p": "port",
+  "--out": "out",
+  "--target": "target",
+}
+
+type SwitchField = "poll" | "report" | "vite" | "bun" | "allowDuplicateIdentity" | "noIndicator"
+
+const SWITCH_FLAGS: Readonly<Record<string, SwitchField>> = {
+  "--poll": "poll",
+  "--report": "report",
+  "--vite": "vite",
+  "--bun": "bun",
+  "--allow-duplicate-identity": "allowDuplicateIdentity",
+  "--no-indicator": "noIndicator",
+}
+
+/** The flags of `nifra dev`, `build` and `start`, as `--flag value` or `--flag=value`. Anything else is
+ * refused: an ignored `--target=vercel` would build the default target and exit 0. */
 export function parseFlags(args: readonly string[]): Flags {
   // Port precedence: `--port`/`-p` (most specific) > `PORT` env > the framework default. The default is
   // the SAME uncommon port for `nifra dev` and `nifra start` (DEFAULT_DEV_PORT) so a project's URL is
   // stable across commands and doesn't collide with the usual 3000/5173/8080 crowd.
   let port = Number(Bun.env.PORT ?? DEFAULT_DEV_PORT)
   let out: string | undefined
-  let poll = Bun.env.CHOKIDAR_USEPOLLING === "1"
   let target: string | undefined
-  let report = false
-  let vite = false
-  let bun = false
-  let allowDuplicateIdentity = false
-  let noIndicator = false
+  const switches: Record<SwitchField, boolean> = {
+    poll: Bun.env.CHOKIDAR_USEPOLLING === "1",
+    report: false,
+    vite: false,
+    bun: false,
+    allowDuplicateIdentity: false,
+    noIndicator: false,
+  }
   for (let i = 0; i < args.length; i++) {
-    const a = args[i]
-    if ((a === "--port" || a === "-p") && args[i + 1]) port = Number(args[++i])
-    else if (a === "--out" && args[i + 1]) out = args[++i] as string
-    else if (a === "--poll") poll = true
-    else if (a === "--target" && args[i + 1]) target = args[++i] as string
-    else if (a === "--report") report = true
-    else if (a === "--vite") vite = true
-    else if (a === "--bun") bun = true
-    else if (a === "--allow-duplicate-identity") allowDuplicateIdentity = true
-    else if (a === "--no-indicator") noIndicator = true
+    const arg = args[i] as string
+    const equals = arg.startsWith("--") ? arg.indexOf("=") : -1
+    const name = equals === -1 ? arg : arg.slice(0, equals)
+    const valueField = Object.hasOwn(VALUE_FLAGS, name) ? VALUE_FLAGS[name] : undefined
+    if (valueField !== undefined) {
+      const value = equals === -1 ? args[++i] : arg.slice(equals + 1)
+      if (value === undefined || value === "" || (equals === -1 && value.startsWith("-")))
+        throw new Error(`[nifra] ${name} needs a value`)
+      if (valueField === "port") port = Number(value)
+      else if (valueField === "out") out = value
+      else target = value
+      continue
+    }
+    const switchField = Object.hasOwn(SWITCH_FLAGS, name) ? SWITCH_FLAGS[name] : undefined
+    if (switchField !== undefined) {
+      const value = equals === -1 ? "true" : arg.slice(equals + 1)
+      if (value !== "true" && value !== "false")
+        throw new Error(`[nifra] ${name} takes no value (or =true / =false)`)
+      switches[switchField] = value === "true"
+      continue
+    }
+    throw new Error(
+      arg.startsWith("-")
+        ? `[nifra] unknown option: ${arg} - see \`nifra help\``
+        : `[nifra] unexpected argument: ${arg} - see \`nifra help\``,
+    )
   }
   if (!Number.isFinite(port) || port < 0 || port > 65535) {
     throw new Error(`[nifra] invalid --port: ${port}`)
   }
-  return { port, out, poll, target, report, vite, bun, allowDuplicateIdentity, noIndicator }
+  return { port, out, target, ...switches }
 }
 
 /**
@@ -945,6 +1075,42 @@ function installReflectionExitHint(): (command: string | undefined) => void {
   }
 }
 
+/** Commands that import the app only to read what it declares, never sending it a request, so the
+ * app may skip connecting to its services. `assure` qualifies without its bundle lane, which renders. */
+const READ_ONLY_COMMANDS: ReadonlySet<string> = new Set([
+  "capabilities",
+  "check",
+  "context",
+  "contracts",
+  "diff",
+  "doctor",
+  "manifest",
+  "openapi",
+  "routes",
+  "sync-manifest",
+  "sync-routes",
+])
+
+const HELD_OPEN_GRACE_MS = 2_000
+
+/**
+ * A command that imports the app for its answer has already answered when the app's own work - a
+ * database or Redis client reconnecting, an interval - would keep the process alive indefinitely.
+ * A process that exits on its own never reaches this unref'd timer; a held one is ended with a note.
+ */
+function exitIfHeldOpen(command: string): void {
+  setTimeout(() => {
+    process.stderr.write(
+      `[nifra] \`nifra ${command}\` has finished, but something the app started when it was imported ` +
+        `(an open connection or a timer) is keeping the process alive, so nifra is exiting.` +
+        (process.env[REFLECT_ENV] === command
+          ? ` To skip that work while nifra only reads the app, check process.env.${REFLECT_ENV}, which is set to "${command}".\n`
+          : "\n"),
+    )
+    process.exit(typeof process.exitCode === "number" ? process.exitCode : 0)
+  }, HELD_OPEN_GRACE_MS).unref()
+}
+
 /** Set on the copy of `nifra mcp` that serves without `.env` files, so it does not restart again. */
 const MCP_WITHOUT_ENV_FILES = "NIFRA_MCP_WITHOUT_ENV_FILES"
 
@@ -1051,6 +1217,9 @@ async function main(): Promise<void> {
   const catalogSpec = findCommandSpec(dbSub === undefined ? command : `db-${dbSub}`)
   if (catalogSpec?.transports.includes("cli")) {
     const markReflecting = installReflectionExitHint()
+    if (READ_ONLY_COMMANDS.has(command) || (command === "assure" && !assureBundleRequested(argv))) {
+      process.env[REFLECT_ENV] = command
+    }
     try {
       const input = bindCommandArgv(catalogSpec, argv.slice(dbSub === undefined ? 1 : 2))
       markReflecting(command)
@@ -1073,7 +1242,7 @@ async function main(): Promise<void> {
       // A thrown error is nifra's own reporting path, not a silent abort: clear the sentinel so the
       // hint stays reserved for the case where the process died inside the app import.
       markReflecting(undefined)
-      console.error(formatCliError(err))
+      reportFailure(err, argv)
       const candidate =
         typeof err === "object" && err !== null && "exitCode" in err
           ? (err as { readonly exitCode?: unknown }).exitCode
@@ -1086,6 +1255,7 @@ async function main(): Promise<void> {
           ? candidate
           : 1
     }
+    exitIfHeldOpen(command)
     return
   }
   if (command === "verify") {
@@ -1135,6 +1305,7 @@ async function main(): Promise<void> {
       console.error(formatCliError(err))
       process.exitCode = 1
     }
+    exitIfHeldOpen(command)
     return
   }
   // `upgrade` is a pure cwd file-transformer (package.json pins + import moves) driven by a per-release
@@ -1150,15 +1321,17 @@ async function main(): Promise<void> {
         json: argv.includes("--json"),
         list: argv.includes("--list"),
         verify: !argv.includes("--no-verify"),
+        hooks: !argv.includes("--no-hooks"),
         allowDowngrade: argv.includes("--allow-downgrade"),
         exact: argv.includes("--exact"),
         cliVersion: CLI_VERSION,
       })
       if (!ok) process.exitCode = 1
     } catch (err) {
-      console.error(formatCliError(err))
+      reportFailure(err, argv)
       process.exitCode = 1
     }
+    exitIfHeldOpen(command)
     return
   }
   // `port` is a pure cwd-based portability linter (scans source, doesn't run the app) - like `check`/
@@ -1169,17 +1342,32 @@ async function main(): Promise<void> {
     process.exitCode = 1
     return
   }
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(HELP)
+    return
+  }
   const flags = parseFlags(argv.slice(1))
-  const app = await loadApp(process.cwd(), flags.out)
-  if (command !== "start") {
-    const { refreshRouteTypes, watchRouteTypes } = await import("./route-types.ts")
-    refreshRouteTypes(app.cwd)
-    // A relaunched `nifra dev --bun` child runs beside its parent, which already watches.
-    if (command === "dev" && process.env.NIFRA_BUN_DEV_TOKEN === undefined) watchRouteTypes(app.cwd)
+  try {
+    const app = await loadApp(process.cwd(), flags.out)
+    if (command !== "start" && process.env.NIFRA_BUN_DEV_TOKEN === undefined) {
+      const { unservedRoutesWarning } = await import("./introspect.ts")
+      const unserved = unservedRoutesWarning(app)
+      if (unserved !== undefined) console.warn(unserved)
+    }
+    if (command !== "start") {
+      const { refreshRouteTypes, watchRouteTypes } = await import("./route-types.ts")
+      refreshRouteTypes(app.cwd)
+      // A relaunched `nifra dev --bun` child runs beside its parent, which already watches.
+      if (command === "dev" && process.env.NIFRA_BUN_DEV_TOKEN === undefined)
+        watchRouteTypes(app.cwd)
+    }
+    if (command === "dev") await dev(app, flags)
+    else if (command === "build") await buildForTarget(app, flags.target, flags)
+    else await start(app, flags)
+  } finally {
+    // `dev` and `start` keep serving after they return; a build is over.
+    if (command === "build") exitIfHeldOpen(command)
   }
-  if (command === "dev") await dev(app, flags)
-  else if (command === "build") await buildForTarget(app, flags.target, flags)
-  else await start(app, flags)
 }
 
 /**
@@ -1278,12 +1466,29 @@ function findCliCommand(values: readonly string[]): number {
   return values.findIndex((value) => isCliCommandToken(value))
 }
 
+/**
+ * The command vector from one runtime argv: the command, then its arguments. Arguments typed before
+ * the command (`nifra --json check`) follow the command's own, ahead of any `--`, rather than being
+ * dropped. Only when index 1 is the script: a runtime flag there means the leading entries are the
+ * runtime's own, not the caller's.
+ */
+export function commandArgv(values: readonly string[], commandIndex: number): readonly string[] {
+  const command = values.slice(commandIndex)
+  const script = values[1]
+  if (commandIndex <= 2 || script === undefined || script.startsWith("-")) return command
+  const leading = values.slice(2, commandIndex)
+  const separator = command.indexOf("--")
+  return separator === -1
+    ? [...command, ...leading]
+    : [...command.slice(0, separator), ...leading, ...command.slice(separator)]
+}
+
 function cliArgv(): readonly string[] {
   const reexec = reexecCliArgv()
   if (reexec !== undefined) return reexec
   for (const values of [Bun.argv, process.argv]) {
     const commandIndex = findCliCommand(values)
-    if (commandIndex >= 0) return values.slice(commandIndex)
+    if (commandIndex >= 0) return commandArgv(values, commandIndex)
   }
   return Bun.argv.slice(2)
 }
@@ -1349,7 +1554,7 @@ if (isMainModule() || isBunDevReexecChild() || hasCliCommandToken()) {
   try {
     await main()
   } catch (err) {
-    console.error(formatCliError(err))
+    reportFailure(err, cliArgv())
     process.exitCode = 1
   }
 }

package/src/client-module.ts

@@ -0,0 +1,97 @@
+/**
+ * An app's `clientModule` when its config names a first-party file. The browser bundle's generated
+ * entry imports it, so the build classifies that file, and everything it imports, as browser code.
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import type * as TS from "typescript"
+import { CONFIG_FILE, FRAMEWORK_FILE } from "./app-files.ts"
+import { stripComments } from "./check-scan.ts"
+import { configPathReader, exportedInitializer } from "./internal/config-paths.ts"
+import type { SpecifierResolver } from "./internal/project-specifiers.ts"
+
+const CLIENT_MODULE_EXPORT =
+  /\bexport\s+const\s+clientModule\s*(?::\s*string\s*)?=\s*(?:"([^"\\\r\n]*)"|'([^'\\\r\n]*)')/
+
+export interface ClientModuleRoot {
+  /** The project-relative config file that names it. */
+  readonly config: string
+  readonly line: number
+  readonly specifier: string
+  /** The real path of the file it names. */
+  readonly file: string
+}
+
+/** The project-relative directory of every app among `files`: one holding a nifra config. */
+export function appDirs(files: readonly string[]): string[] {
+  const apps = new Set<string>()
+  for (const file of files) {
+    for (const config of [CONFIG_FILE, FRAMEWORK_FILE]) {
+      if (file === config) apps.add("")
+      else if (file.endsWith(`/${config}`)) apps.add(file.slice(0, -config.length - 1))
+    }
+  }
+  return [...apps]
+}
+
+/**
+ * The file `clientModule` names in `app`, read the way the loader reads it: from `nifra.config.ts`
+ * when it exists, else `backend/framework.ts`; a string against the app root, and, with `ts`, a
+ * `resolve`/`join` of the config's own folder against that folder. `undefined` for a package
+ * specifier, a value built any other way, or a path to no file.
+ */
+export function clientModuleRoot(
+  root: string,
+  app: string,
+  resolve: SpecifierResolver,
+  ts?: typeof TS,
+): ClientModuleRoot | undefined {
+  const config = existsSync(join(root, app, CONFIG_FILE)) ? CONFIG_FILE : FRAMEWORK_FILE
+  const path = join(root, app, config)
+  if (!existsSync(path)) return undefined
+  const text = readFileSync(path, "utf8")
+  const found = ts === undefined ? literalClientModule(text) : staticClientModule(ts, path, text)
+  if (found === undefined) return undefined
+  const file =
+    found.base === "app"
+      ? resolve(join(root, app, CONFIG_FILE), found.specifier)
+      : resolve(path, found.specifier.startsWith("../") ? found.specifier : `./${found.specifier}`)
+  if (file === undefined) return undefined
+  return {
+    config: app === "" ? config : `${app}/${config}`,
+    line: text.slice(0, found.index).split("\n").length,
+    specifier: found.specifier,
+    file,
+  }
+}
+
+interface FoundClientModule {
+  readonly base: "app" | "config"
+  readonly specifier: string
+  readonly index: number
+}
+
+function literalClientModule(text: string): FoundClientModule | undefined {
+  // `stripComments` keeps offsets, so the match index is a position in `text`.
+  const match = CLIENT_MODULE_EXPORT.exec(stripComments(text))
+  if (match === null) return undefined
+  return { base: "app", specifier: match[1] ?? match[2] ?? "", index: match.index }
+}
+
+function staticClientModule(
+  ts: typeof TS,
+  path: string,
+  text: string,
+): FoundClientModule | undefined {
+  let sf: TS.SourceFile
+  try {
+    sf = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+  } catch {
+    // TypeScript 7 parses only what its session preloaded; the literal form still reads.
+    return literalClientModule(text)
+  }
+  const initializer = exportedInitializer(ts, sf, "clientModule")
+  const found = configPathReader(ts, sf)(initializer)
+  if (initializer === undefined || found === undefined) return undefined
+  return { base: found.base, specifier: found.path, index: initializer.getStart(sf) }
+}