@noverax/courier-build 0.0.0-stage → 0.5.0

package/lib/config/index.d.ts

@@ -0,0 +1,811 @@
+import { CourierError } from "@noverax/courier";
+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>;
+/**
+ * Every path a config is looked for at from a folder, in the order it is
+ * looked for: each of {@link CONFIG_BASENAMES} in the folder, then in each
+ * folder above it, up to the top of the project — the first folder that
+ * holds its repository (`.git`, `.hg`, `.jj`) or is the root of its
+ * workspace (`pnpm-workspace.yaml`, or a `package.json` that declares
+ * `workspaces`) — or, with no such folder, the root of the file system.
+ *
+ * @param startDir - The folder to look in first
+ * @returns The paths, absolute, whether there or not
+ * @example
+ * ```ts
+ * configCandidates("/repo/apps/web"); // → ["/repo/apps/web/courier.config.ts", …, "/repo/courier.config.cjs"]
+ * ```
+ */
+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
+ * them are unchanged.
+ */
+interface TransformCache {
+  /**
+   * What jiti's transform yields for `options`: the kept code when the store
+   * holds a successful transform of the same file from the same bytes and
+   * options, and otherwise whatever `compute` returns.
+   *
+   * @param options - What jiti hands its transform
+   * @param compute - jiti's own transform, run on a miss
+   * @returns The result of `compute`, or its kept code, byte for byte
+   */
+  transform(options: TransformOptions, compute: (options: TransformOptions) => TransformResult): TransformResult;
+}
+/** Where a {@link TransformCache} keeps transforms, and how much in memory. */
+interface TransformCacheOptions {
+  /**
+   * A directory to keep transforms in across processes, as
+   * `findTransformCacheDirectory` finds it. Without one, or with `null`,
+   * transforms are kept in memory only.
+   */
+  directory?: string | null | undefined;
+  /**
+   * Characters of transformed code kept in memory across all files; the file
+   * used least recently is dropped first once they are exceeded. `0` keeps
+   * none, for a process that loads each module once. Defaults to 128 Mi
+   * characters.
+   */
+  maxMemoryChars?: number | undefined;
+  /**
+   * Whether the `directory` is only read: nothing in it is created, written,
+   * pruned or marked as used, so a transform computed on a miss stays in
+   * this process. For a process that loads, once, what another process has
+   * just kept there, as a mock worker loads the modules Studio loaded: its
+   * own entries would only duplicate that process's. Defaults to `false`.
+   */
+  readOnly?: boolean | undefined;
+}
+/**
+ * Create a {@link TransformCache} that keeps transforms in memory for the
+ * life of the process and, given a `directory`, on disk for the next one.
+ *
+ * Each file holds one entry per module system — required and imported are
+ * transformed differently, and a module reached both ways keeps both. An
+ * entry is reused only when the digest of jiti's version, the options and
+ * the source matches, so an edited file is transformed again the first time
+ * it is loaded.
+ *
+ * A transform is looked for in memory, then in the directory, where a hit
+ * is also kept in memory; only when both miss is it computed, and a success
+ * is then kept in both. The directory is shared with every process that
+ * names it, and a directory that cannot be read or written only costs
+ * transforms; see `createTransformCacheDisk` for what an entry must be to be
+ * used. A mock worker, which loads once the modules Studio has just loaded,
+ * opens Studio's directory `readOnly` with `maxMemoryChars: 0`: it reads
+ * what Studio kept, adds nothing to the directory, and holds nothing in
+ * memory past its one load.
+ *
+ * A failed transform, one whose result carries an `error`, is never kept:
+ * babel can fail on bytes it transforms without complaint a moment later,
+ * such as a deeply nested module that overflows the stack while babel is
+ * still cold. Such a file is transformed again on every load, and every
+ * failure reaches jiti with its error, as it does without a cache. A file
+ * named by a relative path, or not named, is transformed every time.
+ *
+ * @param options - The directory (default: none, memory only), the memory
+ *   bound (default: 128 Mi characters), and whether the directory is only
+ *   read (default: no)
+ * @returns A cache to pass to `createConfigJiti` or `loadCourierConfig`
+ * @example
+ * ```ts
+ * const transformCache = createTransformCache({
+ *   directory: findTransformCacheDirectory(projectRoot),
+ * });
+ * const first = await loadCourierConfig({ cwd: projectRoot, transformCache });
+ * // Unchanged modules are not transformed again, here or in the next process:
+ * const second = await loadCourierConfig({ cwd: projectRoot, transformCache });
+ *
+ * // A process that loads once what another has just kept:
+ * const reader = createTransformCache({ directory, readOnly: true, maxMemoryChars: 0 });
+ * ```
+ */
+export declare function createTransformCache({ directory, maxMemoryChars, readOnly }?: TransformCacheOptions): TransformCache;
+/** How a project-file loader resolves imports and transforms modules. */
+interface ConfigJitiOptions {
+  /**
+   * Whether imports resolve through the project's tsconfig path aliases, as
+   * the project's own files expect. Off to load an installed package as it is:
+   * an alias of its scope would send its imports to project sources.
+   */
+  aliases?: boolean | undefined;
+  /**
+   * Where to reuse each module's transform while its bytes are unchanged.
+   * Without one, every module is transformed on every load. Aliases take no
+   * part in it: they change where an import resolves, never the code a
+   * module's own bytes transform to.
+   */
+  transformCache?: TransformCache | undefined;
+  /**
+   * Told the file of each module the load transforms — the config and every
+   * TypeScript or ES module of the project it reaches — so whoever follows
+   * the project knows which files its config depends on.
+   */
+  onModule?: ((filename: string) => void) | undefined;
+  /**
+   * Runs each transform the load makes, the first of which loads the
+   * transformer itself. A caller noting what the config's code reads runs it
+   * 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, 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
+ * back the file as it was before the user changed it. Every load therefore
+ * reads and evaluates every file again; a `transformCache` only spares the
+ * transform of a file whose bytes are unchanged.
+ *
+ * jiti's native attempt, which imports every module natively before falling
+ * back to its own loader, stays off too, whatever `JITI_TRY_NATIVE` says and
+ * under Bun, where it defaults to on: a module imported natively is the
+ * runtime's first evaluation of it for the life of the process, so an edit to
+ * it would never be seen, and the attempt comes before the module cache
+ * `evalModule` is handed, so two files evaluated over one cache would each
+ * evaluate a module they both import.
+ *
+ * jiti's own file cache stays off, with or without a `transformCache`:
+ * - it writes each entry in place, so concurrent writers can leave an entry
+ *   torn between two transforms that its check still accepts;
+ * - an entry it cannot write makes the whole load throw `EACCES`;
+ * - unless the file's own directory has a `node_modules`, it falls back to
+ *   `os.tmpdir()/jiti`, where another user of the machine can place an entry
+ *   that is then run;
+ * - its key ignores `interopDefault` and the babel options, so a transform
+ *   made under other options can be handed back;
+ * - nothing ever prunes it.
+ *
+ * jiti is loaded here rather than at the top of a module so a bundler that
+ * merely reaches this code does not pull a TypeScript transpiler into its
+ * graph; only a process that actually reads such a file pays for it.
+ *
+ * @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), 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
+ * const transformCache = createTransformCache();
+ * const jiti = await createConfigJiti(configFile, { transformCache });
+ * const config = await jiti.import(configFile, { default: true });
+ * ```
+ */
+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.
+ *
+ * `configFile` is the absolute, symlink-resolved path of the file that
+ * was loaded — the dev-server side uses it for the `fs.watch` dep tracker;
+ * the runtime side uses it only for log/debug output.
+ */
+interface LoadedCourierConfig {
+  config: CourierConfig;
+  configFile: string;
+}
+/**
+ * Options for `loadCourierConfig`.
+ */
+interface LoadCourierConfigOptions {
+  /**
+   * Starting directory for the config search. Defaults to `process.cwd()`.
+   * The dev-server passes the explicit project root; the runtime path
+   * passes `process.cwd()` so the walk-up finds configs located at the
+   * workspace root from a nested package cwd (common in monorepos).
+   */
+  cwd?: string | undefined;
+  /**
+   * When true, skip the walk-up and require the config file to exist at
+   * exactly `cwd`. The dev-server uses this because it was told the
+   * project root explicitly and wants to distinguish "no config in root"
+   * from "config found higher up" (which would usually mean the user
+   * pointed at the wrong directory). The runtime path leaves this false
+   * so a nested `cwd` still discovers a root-level config.
+   *
+   * Defaults to false (walk up).
+   */
+  requireAtCwd?: boolean | undefined;
+  /**
+   * Where to reuse each module's transform while its bytes are unchanged. A
+   * caller that keeps one across loads transforms only the modules whose
+   * bytes changed; without one, every module is transformed on every load.
+   */
+  transformCache?: TransformCache | undefined;
+  /** Told the file of each module the load transforms; see `createConfigJiti`. */
+  onModule?: ((filename: string) => void) | undefined;
+  /**
+   * Reuse the transforms kept in the project's `node_modules/.cache`, the
+   * ones Studio keeps, and keep there the ones this load makes: a process
+   * that loads the config beside Studio — an app that attaches, the MCP
+   * server, `courier-server` — transforms only the modules no process has
+   * transformed yet. On a project of a thousand endpoints that is hundreds
+   * 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
+ * top of the project: the folder that holds its repository or is the root
+ * of its workspace (see {@link configCandidates}). A config found in a folder
+ * above `startDir` is taken only when it belongs to this user or to the
+ * owner of `startDir`, and no user outside its group may write it: a folder
+ * many users share, such as `/tmp`, would otherwise run anyone's config.
+ *
+ * @param startDir - The directory to look in first
+ * @returns The absolute path of the first match, or `null` when no directory
+ *   up to the top of the project holds one
+ * @throws UntrustedConfigError when the nearest config lies above `startDir`
+ *   and someone else could have put it there
+ * @example
+ * ```ts
+ * findConfigFile("/app/src"); // → "/app/courier.config.ts", or null
+ * ```
+ */
+export declare function findConfigFile(startDir: string): string | null;
+/**
+ * Find a config file in `cwd` itself, without walking up.
+ *
+ * @param cwd - The directory to look in
+ * @returns The first of {@link CONFIG_BASENAMES} present there, or `null`
+ * @example
+ * ```ts
+ * findConfigFileAt(process.cwd()); // → "/app/courier.config.ts", or null
+ * ```
+ */
+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 `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, 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
+ * const loaded = await loadCourierConfig({ cwd: projectRoot, requireAtCwd: true });
+ * ```
+ */
+export declare function loadCourierConfig(options?: LoadCourierConfigOptions): Promise<LoadedCourierConfig | null>;
+/**
+ * The transforms kept in a project's `node_modules/.cache` — the ones Studio
+ * keeps — for a process that loads the project's modules once: it reuses
+ * them, keeps there the ones it makes, and holds none in memory.
+ *
+ * @param projectRoot - The project's root
+ * @returns The cache, or `undefined` when the project has no directory to keep them in
+ * @example
+ * ```ts
+ * await loadCourierConfigFile(file, { transformCache: projectTransformCache(dirname(file)) });
+ * ```
+ */
+export declare function projectTransformCache(projectRoot: string): TransformCache | 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}, what runs before the config,
+ *   and how long it may take
+ * @returns The config and the canonical path it was loaded from
+ * @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", {
+ *   transformCache: createTransformCache(),
+ * });
+ * ```
+ */
+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 {
+  /**
+   * Prefix → absolute target, in the shape jiti's `alias` option takes.
+   * Only the first target of a mapping appears: jiti resolves one path per
+   * alias, while `candidatesFor` offers every declared target.
+   */
+  readonly loader: Readonly<Record<string, string>>;
+  /** Absolute paths `specifier` may denote, in declaration order. */
+  candidatesFor(specifier: string): string[];
+}
+/**
+ * Read the path aliases that apply to `projectRoot`.
+ *
+ * @param projectRoot - Directory holding the project's `tsconfig.json`
+ * @returns The aliases, empty when the project declares none
+ *
+ * @example
+ * ```ts
+ * const aliases = readPathAliases("/app");
+ * aliases.candidatesFor("@/lib/sources"); // → ["/app/src/lib/sources"]
+ * ```
+ */
+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
+ * above the project root.
+ *
+ * The nearest one is taken, not the one module resolution would reach: under
+ * pnpm that lies inside `.pnpm`, and what keeps the directory safe is the
+ * rule below, not where it is. Every file in it holds code that Studio, mock
+ * workers and build plugins run, so on POSIX the directory is refused when
+ * `node_modules`, `.cache`, `courier` or `transform` — those that exist — is
+ * a symbolic link or belongs to another user, and when `courier` or
+ * `transform`, which only Studio creates, is writable by its group or
+ * others; any of these lets someone else replace or remove entries, or put
+ * the directory somewhere they control. `node_modules` and `.cache` may be
+ * group-writable, as package managers leave them under a umask of 002:
+ * whoever can write `node_modules` can replace any package in it already. On
+ * Windows only links and other kinds of file are refused.
+ *
+ * There is none when no `node_modules` exists, as with Yarn Plug'n'Play, or
+ * when `COURIER_TRANSFORM_CACHE` is `0`, `false` or `off` in any case. The
+ * system temporary directory, which every user of the machine may write, is
+ * never used instead. Why there is none is logged at debug level, once for
+ * each root until the reason changes, however often the root is looked up.
+ *
+ * @param projectRoot - The directory holding `courier.config.*`
+ * @param env - The environment to read `COURIER_TRANSFORM_CACHE` from
+ *   (default: `process.env`)
+ * @returns The directory, which may not exist yet, or `null` for none
+ * @example
+ * ```ts
+ * const transformCache = createTransformCache({
+ *   directory: findTransformCacheDirectory(projectRoot),
+ * });
+ * ```
+ */
+export declare function findTransformCacheDirectory(projectRoot: string, env?: Readonly<Record<string, string | undefined>>): string | null;
+/**
+ * The keys of a courier.config that Courier does not read, at the top and
+ * in its `studio`, `server`, `runtime` and `agents` blocks — a misspelt `studo:` say
+ * — so a load can name them rather than ignore them in silence.
+ *
+ * @param config - The config, as its module exported it
+ * @returns Each such key, dotted under its block
+ * @example
+ * ```ts
+ * unknownConfigKeys({ sources: {}, studo: {}, server: { prot: 3001 } }); // → ["studo", "server.prot"]
+ * ```
+ */
+export declare function unknownConfigKeys(config: unknown): string[];
+/** Where a config that was not run lies, and the folder it was looked for from. */
+interface UntrustedConfigContext extends Record<string, unknown> {
+  /** The config, absolute. */
+  configFile: string;
+  /** The folder the config was looked for from, below it. */
+  folder: string;
+}
+/**
+ * The config nearest a folder lies in a folder above it, and someone else
+ * could have put it there: it belongs to another user, or any user may
+ * write it. It was not run, as it would run with the rights of whoever
+ * builds or serves the project.
+ *
+ * @example
+ * ```ts
+ * throw new UntrustedConfigError("/tmp/courier.config.ts", "/tmp/app", "it belongs to uid 1001");
+ * ```
+ */
+export declare class UntrustedConfigError extends CourierError<"CONFIG_NOT_TRUSTED"> {
+  readonly context: UntrustedConfigContext;
+  /**
+   * @param configFile - The config that was not run, absolute
+   * @param folder - The folder it was looked for from
+   * @param reason - Why it is not trusted, worded to follow "and"
+   */
+  constructor(configFile: string, folder: string, reason: string);
+}
+export type { ConfigJitiOptions, ConfigLoadErrorCode, ConfigLoadErrorContext, FailedLoad, FrameworkId, FrameworkMarker, ImportProjectFileOptions, ListedPackages, LoadConfigFileOptions, LoadCourierConfigOptions, LoadedCourierConfig, ModuleRule, PathAliases, ProjectFramework, RefusedModuleContext, ResolutionProfile, TransformCache, TransformCacheOptions, UntrustedConfigContext };