@noverax/courier-build 0.4.0 → 0.5.0

package/README.md

@@ -89,8 +89,8 @@ declare module "@noverax/courier/routes" {
 
 A page then takes the routes of the API it calls, and its client reaches exactly the endpoints that API opens to a page:
 
-```ts
-import { createProxyCaller } from "@noverax/courier"
+```ts side="page"
+import { createProxyCaller } from "@noverax/courier/client"
 import { routes } from "@noverax/courier/routes"
 
 export const shop = createProxyCaller(routes.shop)
@@ -103,6 +103,7 @@ export const shop = createProxyCaller(routes.shop)
 - **The config** is the `courier.config.*` in Vite's root or the nearest folder above it, up to the top of the project: the folder that holds its repository (`.git`, `.hg`, `.jj`) or is the root of its workspace (`pnpm-workspace.yaml`, or a `package.json` with `workspaces`). One found above the root runs only when it belongs to you or to the owner of the root, and no user outside its group may write it; otherwise the routes are not read, and the error says why. Name another config with the `config` option.
 - **Env files** are those Vite reads for the mode — `.env.[mode].local`, `.env.[mode]`, `.env.local`, `.env`, the first to set a variable winning — with the values Vite gives them, a reference such as `${HOST}` or `${FLAG:-1}` filled in; a variable the process was started with wins over all. An endpoint opened by a variable is opened as the build sees it. The config reads them from `process.env`: `import.meta.env.MODE`, `DEV` and the other values Vite builds into a page are not set for it.
 - **A build** reads the routes once for every environment, and fails with what the config threw; a build that watches builds again once what failed it is mended. **The dev server** reads them again whenever something they came from changes: the config, a module it imports, a file it reads or a folder it lists, an env file, a variable it looked at, or a config saved where one is looked for, Vite's root or a folder above it. A change saved while the routes are read is read too. A config that breaks leaves the routes it read last in force, says why in the terminal and over the page, and is followed until it is mended.
+- **The framework's own modules** are answered as its server answers them, by the framework the project's package.json lists: Next's `server-only` is an empty module and `client-only` is refused, SvelteKit's `$env/*` and `$app/environment` and Astro's `astro:env/*` come from the environment — see [How Courier reads your project](https://courier.noverax.cloud/docs/reading-your-project).
 - **The config in a page** fails the build: imported as a value it would ship the server's settings and every API's definition to the browser. Import its type alone, with `import type`.
 - **Vitest** runs tests through Vite with the plugin: a test gets the routes under Node and under jsdom alike, may import the config itself, and in watch mode an edit reruns the tests that import the routes, with the new ones. Vitest 3.1 and later tell the plugin they run it; under Vitest 3.0 a test that imports the config as a value in a browser environment is refused as a page would be.
 - **Definitions in a page** are not refused: a module of definitions a page imports as a value goes to the browser whole, with each API's address, its paths and middleware, and its endpoints closed to pages. Keep them out of a page's modules, or import their types alone; the routes are all a page needs to call through the proxy.
@@ -146,7 +147,7 @@ Next.js takes `withCourier()` from `@noverax/courier-next/plugin`, under Turbopa
 
 ## esbuild
 
-The same routes, under esbuild: the plugin from `@noverax/courier-build/esbuild` builds them in place of `@noverax/courier/routes`, and a bundle for any `platform` but `node` — a page's — fails where it takes the config itself.
+The same routes, under esbuild: the plugin from `@noverax/courier-build/esbuild` builds them in place of `@noverax/courier/routes`, and a bundle for any `platform` but `node` — a page's — fails where it takes the config itself. A page's bundle takes the core's modules for a page with `platform: "browser"`, esbuild's default; `"neutral"` sets no condition, and a page built so takes the core's server modules.
 
 ```ts
 import { build } from "esbuild"
@@ -163,7 +164,7 @@ await build({ entryPoints: ["src/main.ts"], bundle: true, outdir: "dist", plugin
 
 ## Rollup and Rolldown
 
-Rollup and Rolldown take the same plugin, from `@noverax/courier-build/rollup`. Neither tells a page's bundle from a server's, so a bundle is taken for a page's, which fails where it takes the config itself; a server's, which may import it, says so:
+Rollup and Rolldown take the same plugin, from `@noverax/courier-build/rollup`. Neither tells a page's bundle from a server's, so a bundle is taken for a page's, which fails where it takes the config itself; a server's, which may import it, says so. A page's bundle takes the core's modules for a page by the `browser` condition, which Rollup's `@rollup/plugin-node-resolve` sets with `nodeResolve({ browser: true })`:
 
 ```js
 // rollup.config.js
@@ -248,6 +249,11 @@ export default {
 | `createTransformCache(options?)` | `/config` | Reuse each module's transform while its bytes are unchanged, in memory and in that directory |
 | `projectTransformCache(projectRoot)` | `/config` | The transforms kept in a project's `node_modules/.cache`, for a process that loads its modules once |
 | `readPathAliases(projectRoot)` | `/config` | The tsconfig `paths` the loader resolves imports through |
+| `projectFramework(folder)` / `detectFramework(listed)` / `FRAMEWORK_MARKERS` | `/config` | The framework a project is built with, told by the packages the nearest package.json lists |
+| `profileOf(framework)` / `RefusedModuleError` | `/config` | How the framework's server answers the imports it answers itself, and the error for one it refuses where definitions run |
+| `importProjectFile(file, options?)` / `ConfigLoadError` / `configLoadError(error, load)` | `/config` | Run one of the project's files with the project's loader, and why one did not load: its `code`, the `hint`, and `context.importChain` from the entry to the module that failed, no variable's value in any of them |
+| `COURIER_PHASE` / `DEFINITIONS_PHASE` / `enterDefinitionsPhase(env?)` | `/config` | The variable a project's code reads to tell that Courier reads its definitions, its value then, and how a process says so before the project's code runs |
+| `CONFIG_READ_LIMIT_MS` | `/config` | How long one reading of a config may take, 60 s, before `courier-cli routes` and the routes plugin give it up |
 | `unknownConfigKeys(config)` | `/config` | The keys of a config Courier does not read, which are usually typos |
 
 <br />

package/lib/config/index.d.ts

@@ -1,5 +1,5 @@
 import { CourierError } from "@noverax/courier";
-import { Jiti, TransformOptions, TransformResult } from "jiti";
+import { Jiti, ModuleCache, TransformOptions, TransformResult } from "jiti";
 import { CourierConfig } from "@noverax/courier/config";
 /** The file names a Courier config may have, in the order they are looked for */
 export declare const CONFIG_BASENAMES: ReadonlyArray<string>;
@@ -19,6 +19,107 @@ export declare const CONFIG_BASENAMES: ReadonlyArray<string>;
  * ```
  */
 export declare function configCandidates(startDir: string): string[];
+/** The frameworks Courier tells apart. */
+type FrameworkId = "next" | "nuxt" | "sveltekit" | "astro" | "react-router" | "remix" | "solid-start" | "expo" | "nestjs" | "fastify" | "hono" | "express" | "koa" | "hapi" | "elysia" | "h3" | "nitro" | "react" | "vue";
+/** A framework, and the packages a project that uses it lists. */
+interface FrameworkMarker {
+  readonly id: FrameworkId;
+  /** The framework as its users name it. */
+  readonly label: string;
+  /** The package whose presence tells the framework, and whose version is the framework's. */
+  readonly marker: string;
+  /** Another package the project must list too. */
+  readonly also?: string;
+  /**
+   * Whether the marker tells the framework first as a dependency the app
+   * runs with: Courier's setup installs Hono for Studio's mock as a dev
+   * dependency, in an app built with another framework. Listed only among
+   * the dev dependencies, it still tells the framework where no other is
+   * listed, as for a worker a bundler builds.
+   */
+  readonly runsWith?: boolean;
+  /**
+   * Whether it runs a server alone, which a package may list beside the
+   * framework its page is built with: such a package is told by its
+   * server, which comes before the page's in the list, and is not a
+   * page's alone. The same servers as the upgrade's, in create-courier.
+   */
+  readonly server?: boolean;
+}
+/** The frameworks, the ones built on others first: a Next.js app lists React too; a server before a page Vite builds. */
+export declare const FRAMEWORK_MARKERS: readonly FrameworkMarker[];
+/** The packages a package.json lists, by the field it lists them in. */
+interface ListedPackages {
+  readonly dependencies: Readonly<Record<string, unknown>>;
+  readonly devDependencies: Readonly<Record<string, unknown>>;
+  readonly peerDependencies: Readonly<Record<string, unknown>>;
+  readonly optionalDependencies: Readonly<Record<string, unknown>>;
+}
+/** The framework a project is built with, and the package.json that says so. */
+interface ProjectFramework {
+  /** The framework, or `undefined` when the package.json lists none Courier tells. */
+  readonly framework: FrameworkMarker | undefined;
+  /** The package.json read, absolute; `undefined` when there is none up to the root of the disk. */
+  readonly manifest: string | undefined;
+}
+/**
+ * The framework a project is built with, told by the packages it lists: a
+ * framework told first by what the app runs with counts among the dev
+ * dependencies only where no other framework is listed.
+ *
+ * @param listed - The packages the project's package.json lists
+ * @returns The framework, or `undefined` when it lists none Courier tells
+ * @example
+ * ```ts
+ * detectFramework({ dependencies: { next: "^16.0.0", react: "^19.0.0" }, … })?.label; // "Next.js"
+ * ```
+ */
+export declare function detectFramework(listed: ListedPackages): FrameworkMarker | undefined;
+/**
+ * The framework of the project a folder belongs to, told by the nearest
+ * package.json at or above it. A package.json that does not parse lists
+ * nothing: the project is then read as plain Node, as it would be with none.
+ *
+ * @param folder - A folder of the project, absolute: the config's own
+ * @returns The framework, and the package.json that told it
+ * @example
+ * ```ts
+ * projectFramework("/app").framework?.id; // "sveltekit", where /app/package.json lists @sveltejs/kit
+ * ```
+ */
+export declare function projectFramework(folder: string): ProjectFramework;
+/** What a module of the project gets for an import its framework's server answers itself. */
+type ModuleRule = {
+  readonly kind: "empty";
+} | {
+  readonly kind: "provided";
+  readonly exports: () => object;
+} | {
+  readonly kind: "refused";
+  readonly reason: string;
+  readonly remedy: string;
+};
+/** What a framework says of an import or a name of its own that the load could not find. */
+interface Diagnosis {
+  /** What the import or the name is, worded to follow it: `is a module of SvelteKit's runtime, …`. */
+  readonly reason: string;
+  /** What to do about it, worded as an instruction. */
+  readonly remedy: string;
+}
+/** What a framework's server answers outside its build, and what it says of what it does not. */
+interface FrameworkRules {
+  /** The imports the framework's server answers itself, by specifier. */
+  readonly modules: ReadonlyMap<string, ModuleRule>;
+  /** What the framework says of an import of its own that does not resolve outside its build. */
+  readonly unresolved?: ((specifier: string) => Diagnosis | undefined) | undefined;
+  /** What the framework says of a name its build provides where the code imports nothing. */
+  readonly undefinedName?: ((name: string) => Diagnosis | undefined) | undefined;
+}
+/** How a framework's server answers imports outside its build. */
+interface ResolutionProfile extends FrameworkRules {
+  /** The framework; `undefined` for a project read as plain Node. */
+  readonly framework: FrameworkMarker | undefined;
+}
 /**
  * A store of jiti transforms: TypeScript and ESM sources compiled to the
  * CommonJS jiti evaluates, reused while the bytes and options that produced
@@ -132,12 +233,38 @@ interface ConfigJitiOptions {
    * unnoted: what the transformer reads is its own, not the config's.
    */
   runTransform?: (<TResult>(transform: () => TResult) => TResult) | undefined;
+  /**
+   * How the project's framework answers the imports its server answers
+   * itself — Next's `server-only`, SvelteKit's `$env/static/private`; see
+   * `ResolutionProfile`. Left out, the framework the nearest package.json to
+   * the file lists.
+   */
+  profile?: ResolutionProfile | undefined;
+  /**
+   * Told of each module whose transform failed — its syntax — with what the
+   * transformer said, so whoever reports the load's failure can say which
+   * module would not compile.
+   */
+  onTransformError?: ((filename: string, error: unknown) => void) | undefined;
 }
 /**
  * The module loader for Courier's project files — `courier.config.*` and
  * `courier.mocks.*` — with the options both need: the project's tsconfig path
- * aliases, default-export interop, no module cache, and no native import
- * tried before the loader's own.
+ * aliases, the imports its framework's server answers itself, default-export
+ * interop, no module cache, and no native import tried before the loader's
+ * own.
+ *
+ * A framework resolves some imports where it builds the server, never
+ * through Node: Next makes `server-only` an empty module on its server
+ * layers, SvelteKit and Astro write their env modules from the environment.
+ * The loader answers them as that server does, by the framework the
+ * project's package.json lists (see `profileOf`), in every module it
+ * transforms; one the project's own path aliases name is theirs. A package
+ * the loader hands to Node — an installed library — resolves its own imports
+ * as Node does while that works; where it fails — a library that imports
+ * `server-only` itself — the loader runs the package itself, and answers
+ * them there too. A package Node loads without a failure keeps Node's
+ * answers: one that imports an installed `client-only` is not refused.
  *
  * The module cache is off because this is also the reload path: the dev
  * server loads the files again on every edit, and a cached module would hand
@@ -171,7 +298,8 @@ interface ConfigJitiOptions {
  * @param file - Absolute, symlink-resolved path of the file to load; modules
  *   and aliases resolve from its directory
  * @param options - Whether to resolve through the project's path aliases
- *   (default: yes), and where to reuse transforms (default: nowhere)
+ *   (default: yes), where to reuse transforms (default: nowhere), and how the
+ *   framework answers its own imports (default: as package.json tells it)
  * @returns A jiti instance for that file
  * @example
  * ```ts
@@ -180,7 +308,182 @@ interface ConfigJitiOptions {
  * const config = await jiti.import(configFile, { default: true });
  * ```
  */
-export declare function createConfigJiti(file: string, { aliases, transformCache, onModule, runTransform }?: ConfigJitiOptions): Promise<Jiti>;
+export declare function createConfigJiti(file: string, { aliases, transformCache, onModule, runTransform, profile, onTransformError }?: ConfigJitiOptions): Promise<Jiti>;
+/**
+ * The signal a project's code reads to tell that Courier is reading its
+ * definitions rather than serving requests: `COURIER_PHASE` holds
+ * `definitions` in every process Courier starts to read them — the
+ * `courier-cli routes` command, `courier-mcp --list`, Studio, the process a
+ * bundler plugin reads the routes in — after the fashion of `NEXT_PHASE`.
+ * Code that checks the environment as it is imported can skip the check
+ * then, as `@t3-oss/env-core` does with `skipValidation`; Courier guesses
+ * nothing for it. Where the application runs — `courier-server`,
+ * `courier-mcp` serving an agent, `attachRuntime()`, the app itself — the
+ * variable is not set.
+ */
+/** The variable a project's code reads the phase from. */
+export declare const COURIER_PHASE = "COURIER_PHASE";
+/** Its value while Courier reads the project's definitions. */
+export declare const DEFINITIONS_PHASE = "definitions";
+/**
+ * Mark the process as one that reads the project's definitions, before the
+ * project's code runs in it.
+ *
+ * @param env - The environment to mark (default: the process's)
+ * @example
+ * ```ts
+ * enterDefinitionsPhase();
+ * process.env.COURIER_PHASE; // "definitions"
+ * ```
+ */
+export declare function enterDefinitionsPhase(env?: NodeJS.ProcessEnv): void;
+/** Why a project's config — or its mocks file — did not load. */
+type ConfigLoadErrorCode = "MODULE_NOT_FOUND" | "MODULE_REFUSED" | "TRANSFORM_FAILED" | "EVALUATION_FAILED" | "LOAD_TIMED_OUT";
+/** Where a load failed. */
+interface ConfigLoadErrorContext extends Record<string, unknown> {
+  /** The file loaded, absolute: `courier.config.*` or `courier.mocks.*`. */
+  readonly entry: string;
+  /** The import that did not resolve or was refused, as written. */
+  readonly specifier: string | undefined;
+  /**
+   * The modules from the entry to the one that failed, the entry first: each
+   * of the project's by its absolute path, as the system names it — with `\`
+   * on Windows — and an installed package by its name.
+   */
+  readonly importChain: readonly string[];
+}
+/**
+ * A project's config, or its mocks file, did not load. The message says
+ * what failed and in which module, with the chain of imports that led there
+ * from the entry — `src/api.ts imports "server-only", which does not resolve
+ * (courier.config.ts → src/api.ts).` — in one line; `hint` says what to do,
+ * in another. Neither holds a secret: the project's own message is quoted
+ * with the environment's values masked and every credential `redact()`
+ * finds cut, each as `[redacted]`. What the project threw is the `cause`,
+ * for a log at debug level, cut the same way in its message and its stack.
+ *
+ * @example
+ * ```ts
+ * if (error instanceof ConfigLoadError) log.error(`${error.message}\n${error.hint}`);
+ * ```
+ */
+export declare class ConfigLoadError extends CourierError<ConfigLoadErrorCode> {
+  readonly context: ConfigLoadErrorContext;
+  /** What to do about it, in a sentence or two. */
+  readonly hint: string;
+  /**
+   * @param code - Why the load failed
+   * @param message - What failed and where, in one line
+   * @param details - Where it failed, what to do, and what the project threw
+   */
+  constructor(code: ConfigLoadErrorCode, message: string, details: {
+    context: ConfigLoadErrorContext;
+    hint: string;
+    cause?: unknown;
+  });
+}
+/** What a loader knows of a load that failed. */
+interface FailedLoad {
+  /** The file loaded, absolute: `courier.config.*` or `courier.mocks.*`. */
+  readonly entry: string;
+  /** The load's module cache, which tells the chain of imports; none, and the chain is the entry. */
+  readonly cache?: ModuleCache | undefined;
+  /** The entry's key in the cache, when the loader registered it under another than its path. */
+  readonly entryKey?: string | undefined;
+  /** The framework Courier read the project as; left out, the one the entry's package.json lists. */
+  readonly profile?: ResolutionProfile | undefined;
+  /** The package.json that told the framework, absolute. */
+  readonly manifest?: string | undefined;
+  /** Each module whose transform failed in the load, by file, with what the transformer said. */
+  readonly transformFailures?: ReadonlyMap<string, unknown> | undefined;
+}
+/**
+ * The load error that says why a load failed, what to do, and where — the
+ * chain of imports from the entry to the module that failed.
+ *
+ * @param error - What the load threw
+ * @param load - What the loader knows of the load
+ * @returns The error, typed: an error that already is one is handed back
+ * @example
+ * ```ts
+ * try { await jiti.evalModule(source, { filename: file, cache }); }
+ * catch (error) { throw configLoadError(error, { entry: file, cache }); }
+ * ```
+ */
+export declare function configLoadError(error: unknown, load: FailedLoad): ConfigLoadError;
+/**
+ * The load error for a load given up after its time: the evaluation goes on
+ * — nothing stops a module's top-level code — and the process that gave up
+ * on it ends rather than wait.
+ *
+ * @param load - What the loader knows of the load
+ * @param limitMs - How long it was given
+ * @returns The error
+ * @example
+ * ```ts
+ * reject(loadTimedOut({ entry: configFile }, 60_000));
+ * ```
+ */
+export declare function loadTimedOut(load: FailedLoad, limitMs: number): ConfigLoadError;
+/** How one of the project's files is run, what runs just before its code does, and how long it may take. */
+interface ImportProjectFileOptions extends ConfigJitiOptions {
+  /**
+   * Called once the loader is made, just before the file's code runs. A
+   * caller noting what that code reads starts here, so the loader's own
+   * start-up is not taken for the file's.
+   */
+  beforeRun?: (() => void) | undefined;
+  /**
+   * How long the file may take to run before it is given up with
+   * `ConfigLoadError` `LOAD_TIMED_OUT`, in milliseconds. Its code runs on —
+   * nothing stops a module's top-level code — so a process that gives up
+   * should end. Left out, it is waited for however long it takes.
+   */
+  timeoutMs?: number | undefined;
+  /**
+   * Hand back the file's default export rather than its namespace, as the
+   * runtime's loader does for `import(file, { default: true })`: see
+   * {@link settledDefault}. A promise it exports is waited for within the
+   * load's time.
+   */
+  default?: boolean | undefined;
+}
+/**
+ * Run one of the project's files — `courier.config.*`, `courier.mocks.*` —
+ * with the project's loader, and hand back its module namespace. The
+ * modules it runs go into a cache of this load's own, so a failure names the
+ * chain of imports that led to it: the file runs as the loader's `import`
+ * runs it, the loader choosing by its format whether to transform it or hand
+ * it to Node.
+ *
+ * @param file - The file, absolute and symlink-resolved
+ * @param options - How the loader resolves and transforms, what runs before the file, how long it may take, and whether its default is wanted
+ * @returns The file's module namespace, or its default export, settled
+ * @throws ConfigLoadError saying why the file did not load, where, and what to do
+ * @example
+ * ```ts
+ * const namespace = await importProjectFile("/app/courier.mocks.ts");
+ * ```
+ */
+export declare function importProjectFile(file: string, { beforeRun, timeoutMs, default: wantsDefault, ...options }?: ImportProjectFileOptions): Promise<unknown>;
+/**
+ * A project file's default export, as the runtime's loader hands it back
+ * for `import(file, { default: true })`: the namespace's default, or the
+ * namespace itself where that is nullish — a promise among them settled.
+ * A promise that rejects fails the load as the file's code throwing does,
+ * with `ConfigLoadError`, whose text and cause hold no value of the
+ * environment. Every loader of a project's file settles its default here.
+ *
+ * @param namespace - The file's module namespace, as its loader evaluated it
+ * @param load - What the loader knows of the load
+ * @returns The default export, settled
+ * @throws ConfigLoadError when the promise rejects
+ * @example
+ * ```ts
+ * const config = await settledDefault(await loadCourierEntry(file, cache, transformCache), { entry: file });
+ * ```
+ */
+export declare function settledDefault(namespace: unknown, load: FailedLoad): Promise<unknown>;
 /**
  * Result of a successful `loadCourierConfig` call.
  *
@@ -231,6 +534,13 @@ interface LoadCourierConfigOptions {
    * of modules, most of a second. Passed over when `transformCache` is given.
    */
   projectTransforms?: boolean | undefined;
+  /**
+   * How long the load may take before it is given up with `ConfigLoadError`
+   * `LOAD_TIMED_OUT`, in milliseconds. The config's code runs on — nothing
+   * stops a module's top-level code — so a process that gives up should
+   * end. Left out, the load is waited for however long it takes.
+   */
+  timeoutMs?: number | undefined;
 }
 /**
  * Walk up from `startDir` looking for a `courier.config.*` file, up to the
@@ -266,10 +576,10 @@ export declare function findConfigFileAt(cwd: string): string | null;
  * Find and load a `courier.config.*` file.
  *
  * Returns `null` when no config file exists, so a caller can fall back.
- * Throws when a file was found and loading it failed, reporting what the
- * loader reported — for a TypeScript config, usually an unresolvable import.
+ * Throws `ConfigLoadError` when a file was found and loading it failed,
+ * saying why, where — the chain of imports — and what to do.
  *
- * @param options - Where to look, and where to reuse transforms
+ * @param options - Where to look, where to reuse transforms, and how long to wait
  * @returns The config and its canonical path, or `null` when there is no config
  * @example
  * ```ts
@@ -290,25 +600,23 @@ export declare function loadCourierConfig(options?: LoadCourierConfigOptions): P
  * ```
  */
 export declare function projectTransformCache(projectRoot: string): TransformCache | undefined;
-/** How one config file is loaded: the loader's options, and when its code is about to run. */
-interface LoadConfigFileOptions extends ConfigJitiOptions {
-  /**
-   * Called once the loader is made, just before the config's code runs. A
-   * caller noting what that code reads starts here, so the loader's own
-   * start-up is not taken for the config's.
-   */
-  beforeRun?: (() => void) | undefined;
-}
+/**
+ * How one config file is loaded: the loader's options, what runs just before
+ * the config's code does, and how long it may take; see `importProjectFile`.
+ */
+interface LoadConfigFileOptions extends Omit<ImportProjectFileOptions, "default"> {}
 /**
  * Load one config file, found by whatever means the caller chose — the
  * standalone server takes it from `--config`.
  *
  * @param file - Absolute path of an existing config file
  * @param options - How the loader resolves imports and where it reuses
- *   transforms, see {@link ConfigJitiOptions}, and what runs before the config
+ *   transforms, see {@link ConfigJitiOptions}, what runs before the config,
+ *   and how long it may take
  * @returns The config and the canonical path it was loaded from
- * @throws What the loader reported when the file will not load — for a
- *   TypeScript config, usually an unresolvable import
+ * @throws ConfigLoadError when the file will not load: an import that does
+ *   not resolve or that the framework refuses, a module that does not
+ *   compile, or code that throws
  * @example
  * ```ts
  * const { config } = await loadCourierConfigFile("/app/courier.config.ts", {
@@ -316,7 +624,38 @@ interface LoadConfigFileOptions extends ConfigJitiOptions {
  * });
  * ```
  */
-export declare function loadCourierConfigFile(file: string, { beforeRun, ...options }?: LoadConfigFileOptions): Promise<LoadedCourierConfig>;
+export declare function loadCourierConfigFile(file: string, options?: LoadConfigFileOptions): Promise<LoadedCourierConfig>;
+/** An environment, as a process holds it. */
+type Environment = Readonly<Record<string, string | undefined>>;
+/**
+ * The text with no secret left to quote, by the rules above.
+ *
+ * @param text - The message, as the project's code wrote it
+ * @param env - The environment whose values are masked
+ * @returns The message, with the one sign in place of each secret
+ * @example
+ * ```ts
+ * withoutSecrets("cannot reach postgres://app:pw@db/shop", { PGUSER: "postgres" });
+ * // → "cannot reach [redacted]://db/shop"
+ * ```
+ */
+export declare function withoutSecrets(text: string, env?: Environment): string;
+/**
+ * What the project's code threw, as an error whose message and stack hold
+ * no secret, by the rules above: the error a load error carries as its
+ * `cause`, so no log that prints it — at debug level, by a bundler — holds
+ * one either. It keeps the thrown error's name and `code`; a value thrown
+ * that is no error becomes one, its text cut the same way.
+ *
+ * @param thrown - What the code threw
+ * @param env - The environment whose values are masked
+ * @returns The error, masked
+ * @example
+ * ```ts
+ * maskedError(new TypeError(`bad ${process.env.API_KEY}`)).message; // "bad [redacted]"
+ * ```
+ */
+export declare function maskedError(thrown: unknown, env?: Environment): Error;
 /** Path aliases a project declares, ready for both consumers. */
 interface PathAliases {
   /**
@@ -341,6 +680,58 @@ interface PathAliases {
  * ```
  */
 export declare function readPathAliases(projectRoot: string): PathAliases;
+/**
+ * How a framework's server answers the imports it answers itself. A
+ * framework that answers none, and a project that lists no framework, are
+ * read as plain Node.
+ *
+ * @param framework - The project's framework, as its package.json tells it
+ * @returns The profile every loader of the project's files applies
+ * @example
+ * ```ts
+ * profileOf(projectFramework(projectRoot).framework).modules.has("server-only"); // true for Next.js
+ * ```
+ */
+export declare function profileOf(framework: FrameworkMarker | undefined): ResolutionProfile;
+/** The import a profile refused, and the framework whose rule refused it. */
+interface RefusedModuleContext extends Record<string, unknown> {
+  readonly specifier: string;
+  /** The framework, as its users name it. */
+  readonly framework: string | undefined;
+}
+/**
+ * A module of the project imported one its framework refuses where
+ * definitions run — Next's `client-only` — so the config did not load.
+ *
+ * @example
+ * ```ts
+ * throw new RefusedModuleError("client-only", rule, nextMarker);
+ * ```
+ */
+export declare class RefusedModuleError extends CourierError<"MODULE_REFUSED"> {
+  readonly context: RefusedModuleContext;
+  /** Why the framework refuses it, worded to follow the import: `is the marker of …`. */
+  readonly reason: string;
+  /** What to do about it, worded as an instruction. */
+  readonly remedy: string;
+  /**
+   * @param specifier - The import, as written
+   * @param rule - Why the framework refuses it, and what to do
+   * @param framework - The framework whose rule it is
+   */
+  constructor(specifier: string, rule: {
+    readonly reason: string;
+    readonly remedy: string;
+  }, framework: FrameworkMarker | undefined);
+}
+/**
+ * How long one reading of a project's config may take before it is given
+ * up, in milliseconds: a config that waits on the network, or on a timer,
+ * never ends. The routes plugin's process and `courier-cli routes` hold to
+ * it; Studio, which keeps running what it loaded last, has its own,
+ * `COURIER_CONFIG_LOAD_TIMEOUT_MS`.
+ */
+export declare const CONFIG_READ_LIMIT_MS = 6e4;
 /**
  * Where a project's transforms are kept across processes:
  * `.cache/courier/transform` in the nearest `node_modules` directory at or
@@ -417,4 +808,4 @@ export declare class UntrustedConfigError extends CourierError<"CONFIG_NOT_TRUST
    */
   constructor(configFile: string, folder: string, reason: string);
 }
-export type { ConfigJitiOptions, LoadConfigFileOptions, LoadCourierConfigOptions, LoadedCourierConfig, PathAliases, TransformCache, TransformCacheOptions, UntrustedConfigContext };
+export type { ConfigJitiOptions, ConfigLoadErrorCode, ConfigLoadErrorContext, FailedLoad, FrameworkId, FrameworkMarker, ImportProjectFileOptions, ListedPackages, LoadConfigFileOptions, LoadCourierConfigOptions, LoadedCourierConfig, ModuleRule, PathAliases, ProjectFramework, RefusedModuleContext, ResolutionProfile, TransformCache, TransformCacheOptions, UntrustedConfigContext };

package/lib/config/index.js

@@ -1,5 +1,6 @@
+import { i as enterDefinitionsPhase, n as COURIER_PHASE, r as DEFINITIONS_PHASE, t as CONFIG_READ_LIMIT_MS } from "../read-limits-DUuUaEQM.js";
 import { n as isRecord } from "../errno-code-CNx_E80R.js";
-import { a as projectTransformCache, c as UntrustedConfigError, d as CONFIG_BASENAMES, f as configCandidates, i as loadCourierConfigFile, l as createConfigJiti, n as findConfigFileAt, o as findTransformCacheDirectory, r as loadCourierConfig, s as createTransformCache, t as findConfigFile, u as readPathAliases } from "../load-config-BeedbpkN.js";
+import { C as projectFramework, S as detectFramework, T as configCandidates, _ as createConfigJiti, a as projectTransformCache, b as readPathAliases, c as UntrustedConfigError, d as configLoadError, f as loadTimedOut, g as ConfigLoadError, i as loadCourierConfigFile, l as importProjectFile, m as withoutSecrets, n as findConfigFileAt, o as findTransformCacheDirectory, p as maskedError, r as loadCourierConfig, s as createTransformCache, t as findConfigFile, u as settledDefault, v as profileOf, w as CONFIG_BASENAMES, x as FRAMEWORK_MARKERS, y as RefusedModuleError } from "../load-config-barNPfXN.js";
 // src/config/unknown-config-keys.ts
 const TOP_LEVEL = {
 	sources: true,
@@ -25,6 +26,14 @@ const BLOCKS = /* @__PURE__ */ new Map([
 		allowedHosts: true,
 		maxBodyBytes: true,
 		maxUploadBytes: true,
+		uploadMode: true,
+		uploadMemoryBytes: true,
+		totalUploadMemoryBytes: true,
+		totalUploadDiskBytes: true,
+		uploadDirectory: true,
+		maxUploadParts: true,
+		bodyIdleTimeoutMs: true,
+		bodyTimeoutMs: true,
 		rateLimit: true,
 		browsersOnly: true
 	}],
@@ -63,4 +72,4 @@ function unknownConfigKeys(config) {
 	}
 	return unknown;
 }
-export { CONFIG_BASENAMES, UntrustedConfigError, configCandidates, createConfigJiti, createTransformCache, findConfigFile, findConfigFileAt, findTransformCacheDirectory, loadCourierConfig, loadCourierConfigFile, projectTransformCache, readPathAliases, unknownConfigKeys };
+export { CONFIG_BASENAMES, CONFIG_READ_LIMIT_MS, COURIER_PHASE, ConfigLoadError, DEFINITIONS_PHASE, FRAMEWORK_MARKERS, RefusedModuleError, UntrustedConfigError, configCandidates, configLoadError, createConfigJiti, createTransformCache, detectFramework, enterDefinitionsPhase, findConfigFile, findConfigFileAt, findTransformCacheDirectory, importProjectFile, loadCourierConfig, loadCourierConfigFile, loadTimedOut, maskedError, profileOf, projectFramework, projectTransformCache, readPathAliases, settledDefault, unknownConfigKeys, withoutSecrets };

package/lib/{config-file-of-Zkwyi9zf.js → config-file-of-Clf_dWUQ.js}

@@ -1,5 +1,5 @@
 import { t as errnoCode } from "./errno-code-CNx_E80R.js";
-import { c as UntrustedConfigError, t as findConfigFile } from "./load-config-BeedbpkN.js";
+import { c as UntrustedConfigError, t as findConfigFile } from "./load-config-barNPfXN.js";
 import { resolve } from "node:path";
 import { realpathSync } from "node:fs";
 // src/util/config-file-of.ts