@platformatic/foundation 3.68.0 → 4.0.0-new-config.0

package/lib/v4/detect.js

@@ -0,0 +1,112 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { hasJavascriptFiles } from '../file-system.js'
+import { AmbiguousCapabilityError, CapabilityNotDetectedError } from './errors.js'
+
+/*
+  The table is enumerated rather than pattern-matched on @platformatic/*, so companion packages
+  like @platformatic/globals — which @platformatic/node's own generator writes alongside it —
+  cannot trip the ambiguity error, and the out-of-tree capabilities already in v3's table have a
+  defined place. A capability outside the table, which is every third-party one, is never inferred:
+  those applications declare an explicit config file.
+*/
+export const capabilityPackages = [
+  '@platformatic/node',
+  '@platformatic/service',
+  '@platformatic/db',
+  '@platformatic/gateway',
+  '@platformatic/next',
+  '@platformatic/astro',
+  '@platformatic/vite',
+  '@platformatic/remix',
+  '@platformatic/nest',
+  '@platformatic/nitro',
+  '@platformatic/nuxt',
+  '@platformatic/react-router',
+  '@platformatic/tanstack',
+  '@platformatic/php',
+  '@platformatic/ai-warp',
+  '@platformatic/pg-hooks',
+  '@platformatic/rabbitmq-hooks',
+  '@platformatic/kafka-hooks'
+]
+
+export const capabilityAliases = { '@platformatic/composer': '@platformatic/gateway' }
+
+// Fallback only, and ordered: Nitro applications often use Vite, so Nitro is checked first, and
+// Vite comes last amongst the frontend frameworks for the same reason.
+export const frameworkDependencies = [
+  { capability: '@platformatic/nest', dependencies: ['@nestjs/core'] },
+  { capability: '@platformatic/next', dependencies: ['next'] },
+  { capability: '@platformatic/remix', dependencies: ['@remix-run/dev'] },
+  { capability: '@platformatic/astro', dependencies: ['astro'] },
+  { capability: '@platformatic/react-router', dependencies: ['@react-router/dev'] },
+  { capability: '@platformatic/nuxt', dependencies: ['nuxt'] },
+  { capability: '@platformatic/tanstack', dependencies: ['@tanstack/react-start'] },
+  { capability: '@platformatic/nitro', dependencies: ['nitro', 'nitropack'] },
+  { capability: '@platformatic/vite', dependencies: ['vite'] }
+]
+
+export function hasDirectDependency (packageJson, dependency) {
+  return Boolean(packageJson?.dependencies?.[dependency] ?? packageJson?.devDependencies?.[dependency])
+}
+
+async function readPackageJson (directory) {
+  try {
+    return JSON.parse(await readFile(join(directory, 'package.json'), 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+/*
+  One deterministic run against the application's package.json, for an entry with neither an inline
+  config nor a per-app file.
+
+  The order inverts v3, which checked framework dependencies first and reached @platformatic/node
+  only through the terminal fallback. Under that order a generated Node application that later
+  added Vite as unrelated tooling would silently switch capability on its next boot. Because
+  scaffolding always adds the chosen capability to the application's dependencies, this order
+  provably reconstructs the wizard's choice — which is what makes the single-app zero-config case
+  sound. Multi-app projects never rely on it.
+*/
+export async function detectCapability (directory, { id, packageJson } = {}) {
+  packageJson ??= await readPackageJson(directory)
+
+  const declared = new Set()
+
+  for (const [alias, canonical] of Object.entries(capabilityAliases)) {
+    if (hasDirectDependency(packageJson, alias)) {
+      declared.add(canonical)
+    }
+  }
+
+  for (const capability of capabilityPackages) {
+    if (hasDirectDependency(packageJson, capability)) {
+      declared.add(capability)
+    }
+  }
+
+  if (declared.size > 1) {
+    throw new AmbiguousCapabilityError(id ?? directory, [...declared].sort().join(', '))
+  }
+
+  if (declared.size === 1) {
+    return { capability: [...declared][0], source: 'dependency' }
+  }
+
+  for (const { capability, dependencies } of frameworkDependencies) {
+    if (dependencies.some(dependency => hasDirectDependency(packageJson, dependency))) {
+      return { capability, source: 'framework' }
+    }
+  }
+
+  // The terminal rule keeps v3's zero-config floor: a directory containing JavaScript or
+  // TypeScript sources that matched nothing else is a generic Node application. A directory with
+  // none is an error naming the application — there is no generic fallback beyond this one.
+  if (await hasJavascriptFiles(directory)) {
+    return { capability: '@platformatic/node', source: 'terminal' }
+  }
+
+  throw new CapabilityNotDetectedError(id ?? directory, directory)
+}

package/lib/v4/env.js

@@ -0,0 +1,208 @@
+import { readFile } from 'node:fs/promises'
+import { isAbsolute, resolve } from 'node:path'
+import { parseEnv } from 'node:util'
+import { EnvFileNotFoundError } from './errors.js'
+import { ancestorDirectories } from './scope.js'
+
+// Vite parity. Ordered most specific first, which is the order the layering consumes:
+// .env.<mode>.local > .env.<mode> > .env.local > .env
+export function listEnvFileNames (mode) {
+  const names = []
+
+  if (mode) {
+    names.push(`.env.${mode}.local`, `.env.${mode}`)
+  }
+
+  names.push('.env.local', '.env')
+
+  return names
+}
+
+// A chain runs from `directory` up to and including `envRoot`, nearest winning. When `envRoot` is
+// not an ancestor of `directory` — an application outside the runtime's tree, whose own env root
+// is itself — the chain is the directory alone. Every chain terminates.
+export function resolveDirectoryChain (directory, envRoot) {
+  const chain = []
+
+  for (const candidate of ancestorDirectories(directory)) {
+    chain.push(candidate)
+
+    if (candidate === envRoot) {
+      return chain
+    }
+  }
+
+  return [directory]
+}
+
+async function readEnvFile (path, { required = false } = {}) {
+  let contents
+
+  try {
+    contents = await readFile(path, 'utf-8')
+  } catch (error) {
+    if (!required && (error.code === 'ENOENT' || error.code === 'EISDIR')) {
+      return null
+    }
+
+    if (error.code === 'ENOENT') {
+      throw new EnvFileNotFoundError(path)
+    }
+
+    throw error
+  }
+
+  return { path, values: parseEnv(contents) }
+}
+
+// Every path a directory contributes, whether or not it exists. The watcher needs the full set:
+// creating a .env is how a rung appears, and a set built from what exists cannot see that.
+export function listDirectoryEnvFilePaths (directory, mode) {
+  return listEnvFileNames(mode).map(name => resolve(directory, name))
+}
+
+export function listChainEnvFilePaths (chain, mode) {
+  return chain.flatMap(directory => listDirectoryEnvFilePaths(directory, mode))
+}
+
+async function collectPaths (paths, { required = false } = {}) {
+  const sources = await Promise.all(paths.map(path => readEnvFile(path, { required })))
+
+  return sources.filter(source => source !== null)
+}
+
+// The env-files rung for one application, most specific first: its own chain layered over the
+// chain of the file that decided the boot. For an application inside the project the two chains
+// coincide and the second contributes nothing.
+export async function resolveEnvFileSources ({
+  directory,
+  envRoot,
+  decidingDirectory,
+  decidingEnvRoot,
+  mode,
+  envfile,
+  customEnvFile
+}) {
+  // --env replaces the entire rung, in both views and mode-exempt: no directory in any chain
+  // contributes. Defining it as merely the outermost layer would leave it overridden by any
+  // application's own .env, which is not what an escape hatch is.
+  if (customEnvFile) {
+    const path = isAbsolute(customEnvFile) ? customEnvFile : resolve(directory ?? decidingDirectory, customEnvFile)
+
+    return collectPaths([path], { required: true })
+  }
+
+  const ownChain = directory ? resolveDirectoryChain(directory, envRoot ?? directory) : []
+  const decidingChain = decidingDirectory
+    ? resolveDirectoryChain(decidingDirectory, decidingEnvRoot ?? decidingDirectory)
+    : []
+
+  const sources = []
+
+  if (envfile) {
+    // envfile is an opt-out of the convention that occupies the application's own-directory layer:
+    // none of the four mode-aware files are read for it, and the directories above are unaffected.
+    // It resolves app-relative and a missing one is a load error.
+    const path = isAbsolute(envfile) ? envfile : resolve(directory, envfile)
+
+    sources.push(...(await collectPaths([path], { required: true })))
+    sources.push(...(await collectPaths(listChainEnvFilePaths(ownChain.slice(1), mode))))
+  } else {
+    sources.push(...(await collectPaths(listChainEnvFilePaths(ownChain, mode))))
+  }
+
+  sources.push(...(await collectPaths(listChainEnvFilePaths(decidingChain, mode))))
+
+  const seen = new Set()
+
+  return sources.filter(source => {
+    if (seen.has(source.path)) {
+      return false
+    }
+
+    seen.add(source.path)
+    return true
+  })
+}
+
+// Resolution is declarative: for each key, walk the ladder from the top and take the first source
+// that defines it. There are no sequential apply-and-overwrite passes, so the ordering bugs they
+// invite — an app env file clobbering a value an env block just set — are unrepresentable.
+export function layerEnvironment (layers) {
+  const environment = {}
+
+  for (const layer of layers) {
+    if (!layer) {
+      continue
+    }
+
+    for (const key of Object.keys(layer)) {
+      const value = layer[key]
+
+      if (value === undefined || key in environment) {
+        continue
+      }
+
+      environment[key] = typeof value === 'string' ? value : String(value)
+    }
+  }
+
+  return environment
+}
+
+// The bottom rung, and it belongs to both views. The test is non-empty rather than absent because
+// that is what v3 tested: a production build running with NODE_ENV='' is read by every bundler in
+// the ecosystem as "not production". This is the one place the ladder treats '' as missing.
+export function applyNodeEnvDefault (environment, production) {
+  if (production && !environment.NODE_ENV) {
+    environment.NODE_ENV = 'production'
+  }
+
+  return environment
+}
+
+// The config-evaluation view: real environment > env files > NODE_ENV default. No env block
+// appears at any position — a block configures the running application, not the reading of
+// configuration.
+export function resolveConfigurationEnvironment ({ realEnv = process.env, fileSources = [], production = false }) {
+  const environment = layerEnvironment([realEnv, ...fileSources.map(source => source.values)])
+
+  return applyNodeEnvDefault(environment, production)
+}
+
+// The worker-runtime view. It differs from the one above by exactly the rungs that exist only once
+// the runtime is running: the two env blocks and the injected PLT_<ID>_URL values.
+export function resolveWorkerEnvironment ({
+  realEnv = process.env,
+  entryEnv,
+  rootEnv,
+  injectedUrls,
+  fileSources = [],
+  production = false
+}) {
+  const environment = layerEnvironment([
+    realEnv,
+    entryEnv,
+    rootEnv,
+    injectedUrls,
+    ...fileSources.map(source => source.values)
+  ])
+
+  return applyNodeEnvDefault(environment, production)
+}
+
+// Injection outranks env files, so a per-app eval worker must not read a stale PLT_<ID>_URL out of
+// one and bake it into resolvedConfig, where injection can no longer reach it. The strip is scoped
+// to names the runtime is going to supply itself: a key already in the real environment is one
+// injection skips, so the worker genuinely uses the inherited value and it stays.
+export function stripInjectedTopologyKeys (environment, injectedNames, realEnv = process.env) {
+  for (const name of injectedNames) {
+    if (name in realEnv) {
+      continue
+    }
+
+    delete environment[name]
+  }
+
+  return environment
+}

package/lib/v4/errors.js

@@ -0,0 +1,131 @@
+import createError from '@fastify/error'
+import { ERROR_PREFIX } from '../errors.js'
+
+// The v4 loader carries its own error table rather than extending the v3 one: the v3
+// configuration machinery moves out of foundation into wattpm-utils' migrate reader, and
+// an error shared between the two would follow it.
+
+export const AmbiguousConfigurationFileError = createError(
+  `${ERROR_PREFIX}_AMBIGUOUS_CONFIGURATION_FILE`,
+  'Multiple Watt configuration files found in %s: %s. Exactly one is allowed.'
+)
+
+export const LegacyConfigurationFileError = createError(
+  `${ERROR_PREFIX}_LEGACY_CONFIGURATION_FILE`,
+  '%s is a v3-era configuration. Watt v4 uses watt.config.ts.\n  Run:  npx wattpm-utils@4 migrate'
+)
+
+export const ConfigurationFileNotFoundError = createError(
+  `${ERROR_PREFIX}_CONFIGURATION_FILE_NOT_FOUND`,
+  'No Watt configuration file found in %s or its ancestors up to %s.'
+)
+
+export const InvalidConfigurationExportError = createError(
+  `${ERROR_PREFIX}_INVALID_CONFIGURATION_EXPORT`,
+  'The default export of %s is not a configuration object (received %s).'
+)
+
+export const NestedFunctionExportError = createError(
+  `${ERROR_PREFIX}_NESTED_FUNCTION_EXPORT`,
+  'The default export of %s is a function that returned another function.'
+)
+
+export const InvalidConfigValueError = createError(
+  `${ERROR_PREFIX}_INVALID_CONFIG_VALUE`,
+  'Invalid configuration value at %s: %s.'
+)
+
+export const DeferredSlotInApplicationDefinitionError = createError(
+  `${ERROR_PREFIX}_DEFERRED_SLOT_IN_APPLICATION_DEFINITION`,
+  '%s exports an application definition with a function at %s. Application definitions have no config slots; use the factory callback form instead.'
+)
+
+export const ApplicationShorthandConflictError = createError(
+  `${ERROR_PREFIX}_APPLICATION_SHORTHAND_CONFLICT`,
+  '%s declares the singular application shorthand alongside %s. The shorthand is only for genuinely single-application projects.'
+)
+
+export const RootConfigurationInApplicationEntryError = createError(
+  `${ERROR_PREFIX}_ROOT_CONFIGURATION_IN_APPLICATION_ENTRY`,
+  '%s is the configuration of application %s but classifies as a root configuration. A root configuration cannot nest inside an application entry.'
+)
+
+export const ApplicationConfiguredTwiceError = createError(
+  `${ERROR_PREFIX}_APPLICATION_CONFIGURED_TWICE`,
+  'Application %s has an inline config in the root configuration and a configuration file at %s. Remove one of them.'
+)
+
+export const ApplicationStartsNothingError = createError(
+  `${ERROR_PREFIX}_APPLICATION_STARTS_NOTHING`,
+  'Application %s would start nothing: %s does not serve without a listener under %s, and the application declares neither server.port nor application.commands.%s.'
+)
+
+export const CapabilitySchemaNotFoundError = createError(
+  `${ERROR_PREFIX}_CAPABILITY_SCHEMA_NOT_FOUND`,
+  'Cannot import the schema of %s from %s, nor from the copy bundled with the runtime. A v4 capability exports one from its /schema subpath.'
+)
+
+export const InvalidApplicationConfigurationError = createError(
+  `${ERROR_PREFIX}_INVALID_APPLICATION_CONFIGURATION`,
+  'The configuration of application %s does not validate against the %s schema:%s'
+)
+
+export const CapabilityNotResolvableError = createError(
+  `${ERROR_PREFIX}_CAPABILITY_NOT_RESOLVABLE`,
+  'Cannot resolve %s from %s, nor from the copy bundled with the runtime.'
+)
+
+export const CapabilityVersionSkewError = createError(
+  `${ERROR_PREFIX}_CAPABILITY_VERSION_SKEW`,
+  '%s'
+)
+
+export const AmbiguousCapabilityError = createError(
+  `${ERROR_PREFIX}_AMBIGUOUS_CAPABILITY`,
+  'Application %s declares more than one capability dependency: %s. Add a configuration file naming the one it uses.'
+)
+
+export const CapabilityNotDetectedError = createError(
+  `${ERROR_PREFIX}_CAPABILITY_NOT_DETECTED`,
+  'Cannot detect the capability of application %s: %s declares no capability dependency, no known framework and no JavaScript sources.'
+)
+
+export const ObjectSourceRootRequiredError = createError(
+  `${ERROR_PREFIX}_OBJECT_SOURCE_ROOT_REQUIRED`,
+  'Provide the root argument when passing a configuration object: it stands in for the directory a configuration file would have been read from.'
+)
+
+export const EnvFileOnInlineConfigError = createError(
+  `${ERROR_PREFIX}_ENV_FILE_ON_INLINE_CONFIG`,
+  'Application %s declares an envfile but carries an inline config, so no file is read for it and the envfile would govern the worker environment alone.'
+)
+
+export const EnvFileOnDecidingDirectoryError = createError(
+  `${ERROR_PREFIX}_ENV_FILE_ON_DECIDING_DIRECTORY`,
+  'Application %s declares an envfile and its directory is the directory of %s. Applying it would mean reading the configuration in order to build the environment that produces the configuration.'
+)
+
+export const EnvFileNotFoundError = createError(
+  `${ERROR_PREFIX}_ENV_FILE_NOT_FOUND`,
+  'The env file %s does not exist.'
+)
+
+export const InvalidApplicationIdError = createError(
+  `${ERROR_PREFIX}_INVALID_APPLICATION_ID`,
+  'The application id %s (derived from %s) is not a valid DNS label, so it cannot be used as a mesh hostname. Set an explicit id on the entry.'
+)
+
+export const InvalidRootConfigurationError = createError(
+  `${ERROR_PREFIX}_INVALID_ROOT_CONFIGURATION`,
+  'The configuration %s does not validate: %s'
+)
+
+export const ConfigurationEvaluationTimeoutError = createError(
+  `${ERROR_PREFIX}_CONFIGURATION_EVALUATION_TIMEOUT`,
+  'Evaluating %s timed out after %dms.'
+)
+
+export const EvaluationEndedWithoutResultError = createError(
+  `${ERROR_PREFIX}_EVALUATION_ENDED_WITHOUT_RESULT`,
+  'Evaluating %s ended without a result (worker exit code %d). A configuration that never resolves, or that calls process.exit, ends this way.'
+)

package/lib/v4/eval-worker.js

@@ -0,0 +1,47 @@
+import { registerHooks } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import { parentPort, workerData } from 'node:worker_threads'
+import { ensureLoggableError } from '../errors.js'
+import { evaluateConfiguration } from './pipeline.js'
+
+/*
+  The recorded import list has to survive a failed evaluation, which is exactly when it matters:
+  add an import of a helper to a config file, have the helper throw, and there is no valid result
+  for the list to ride back on. So the hook streams each resolved path as it records it rather than
+  accumulating one to post at the end — which is also what covers termination, where nothing can
+  be posted at all.
+
+  The synchronous API is deliberate: module.register's async variant does not intercept require(),
+  and a watt.config.js in a "type": "commonjs" package is CJS.
+*/
+registerHooks({
+  resolve (specifier, context, nextResolve) {
+    const result = nextResolve(specifier, context)
+
+    if (typeof result?.url === 'string' && result.url.startsWith('file:')) {
+      parentPort.postMessage({ type: 'import', path: fileURLToPath(result.url) })
+    }
+
+    return result
+  }
+})
+
+try {
+  const { config, classification, resolveCandidates, warnings, mutatedEnvKeys } = await evaluateConfiguration({
+    ...workerData,
+    // The worker's process.env is the layered view the main process resolved and handed over; it
+    // never inherits the loader's.
+    env: process.env,
+    onWatchFile (path) {
+      parentPort.postMessage({ type: 'watch', path })
+    }
+  })
+
+  parentPort.postMessage({ type: 'result', config, classification, resolveCandidates, warnings, mutatedEnvKeys })
+} catch (error) {
+  // Errors are posted as plain data rather than as Error instances: structured clone keeps name,
+  // message and stack but drops the code, which is the part every caller branches on.
+  const { message, code, stack, name } = ensureLoggableError(error)
+
+  parentPort.postMessage({ type: 'error', error: { message, code, stack, name } })
+}

package/lib/v4/evaluate.js

@@ -0,0 +1,180 @@
+import { dirname } from 'node:path'
+import { Worker } from 'node:worker_threads'
+import { ensureError } from '../errors.js'
+import { ConfigurationEvaluationTimeoutError, EvaluationEndedWithoutResultError } from './errors.js'
+import { evaluateConfiguration } from './pipeline.js'
+
+export const defaultEvaluationTimeout = 30000
+
+const workerPath = new URL('./eval-worker.js', import.meta.url)
+
+/*
+  All configuration is evaluated in short-lived evaluation worker threads — one for the root
+  config, then one per per-app config file, run in parallel.
+
+  A throwaway worker rather than a plain import() in the main process because the ESM module cache
+  is not invalidatable, so a same-process re-import would silently return stale config on every dev
+  reload — and the recorded import list is what lets the watcher cover helper files, not just the
+  config file itself. It also isolates env mutation and config crashes and hangs from the loader.
+
+  The workers isolate module caches, environments, crashes and hangs. They are not a sandbox: a
+  config file runs with the runtime's privileges, exactly as in v3, where an application's config
+  selected a module the worker then imported and executed.
+*/
+export async function evaluateConfigurationFile ({
+  path,
+  directory,
+  role = 'root',
+  applicationId,
+  env,
+  command,
+  mode,
+  production,
+  schema,
+  timeout = defaultEvaluationTimeout,
+  onImport,
+  onWatchFile
+} = {}) {
+  const importedFiles = new Set()
+  const watchedFiles = new Set()
+
+  const worker = new Worker(workerPath, {
+    // Every eval worker is constructed with an explicit env — the computed layered view — never by
+    // inheriting the main process's process.env, so a mutated parent environment can never leak in
+    // as apparent real-environment keys. No env windows, no apply/restore choreography.
+    env: env ?? {},
+    workerData: {
+      path,
+      directory: directory ?? dirname(path),
+      role,
+      applicationId,
+      command,
+      mode,
+      production,
+      schema
+    }
+  })
+
+  let settle
+  const settled = new Promise(resolve => {
+    settle = resolve
+  })
+
+  let outcome = null
+  let timer = null
+
+  worker.on('message', message => {
+    switch (message.type) {
+      case 'import':
+        if (!importedFiles.has(message.path)) {
+          importedFiles.add(message.path)
+          onImport?.(message.path)
+        }
+        break
+      case 'watch':
+        if (!watchedFiles.has(message.path)) {
+          watchedFiles.add(message.path)
+          onWatchFile?.(message.path)
+        }
+        break
+      case 'result':
+        outcome = { ok: true, value: message }
+        settle()
+        break
+      case 'error':
+        outcome = { ok: false, error: ensureError(message.error) }
+        settle()
+        break
+    }
+  })
+
+  worker.on('error', error => {
+    outcome ??= { ok: false, error }
+    settle()
+  })
+
+  worker.on('exit', code => {
+    // A worker that dies without posting anything still has to settle, and with the paths it did
+    // report. The deadline does not cover this: a configuration that awaits a promise nothing will
+    // ever settle leaves an empty event loop, so Node exits the thread at once rather than hanging
+    // — which is the deadlock the timer is too late to see, not a case it handles.
+    outcome ??= { ok: false, error: new EvaluationEndedWithoutResultError(path, code) }
+    settle()
+  })
+
+  if (timeout > 0) {
+    // A config that never resolves — an awaited fetch to a dead host, a forgotten promise —
+    // terminates the worker and fails the load with a targeted error instead of hanging boot.
+    // Streaming is what makes the imports recorded up to this point survive the termination.
+    timer = setTimeout(() => {
+      outcome ??= { ok: false, error: new ConfigurationEvaluationTimeoutError(path, timeout) }
+      worker.terminate()
+      settle()
+    }, timeout)
+
+    timer.unref?.()
+  }
+
+  try {
+    await settled
+  } finally {
+    clearTimeout(timer)
+    await worker.terminate()
+  }
+
+  const collected = { importedFiles: [...importedFiles], watchedFiles: [...watchedFiles] }
+
+  if (!outcome.ok) {
+    // The paths ride back on the failure too: a watcher holding only the last good set is not
+    // watching the helper that just threw, so fixing it would trigger no reload and wattpm dev
+    // would look hung on a file the user is actively editing.
+    Object.assign(outcome.error, collected)
+    throw outcome.error
+  }
+
+  const { config, classification, resolveCandidates, warnings, mutatedEnvKeys } = outcome.value
+
+  return { config, classification, resolveCandidates, warnings, mutatedEnvKeys, ...collected }
+}
+
+function installEnvironment (view) {
+  const previous = { ...process.env }
+
+  for (const key of Object.keys(process.env)) {
+    delete process.env[key]
+  }
+
+  Object.assign(process.env, view)
+
+  return function restore () {
+    for (const key of Object.keys(process.env)) {
+      delete process.env[key]
+    }
+
+    Object.assign(process.env, previous)
+  }
+}
+
+/*
+  Breakpoint debugging gets an explicit escape hatch, since a throwaway thread dies before an
+  inspector can attach: with --inspect-brk, evaluation runs in-process and is therefore restricted
+  to one config file, precisely because one process has one module cache, in which only a single
+  file's env view can be correct. The other files still evaluate in their workers, and cannot be
+  contaminated by this one regardless of ordering — the main process constructs each worker with an
+  explicit env, and workers never inherit process.env.
+
+  process.env is installed and restored around the call, so the "does not propagate" statement
+  stays true in debug mode. The evaluation deadline is not applied: a paused breakpoint session
+  must not be killed by the 30 s timer.
+*/
+export async function evaluateConfigurationInProcess ({ env, ...options } = {}) {
+  const restore = installEnvironment(env ?? {})
+
+  try {
+    const result = await evaluateConfiguration({ ...options, env: process.env })
+
+    return { ...result, importedFiles: [], watchedFiles: [] }
+  } finally {
+    restore()
+  }
+}