@theholocron/datapad 5.0.0-alpha.148 → 5.0.0-alpha.149

package/README.md

@@ -69,7 +69,8 @@ the exact same internals `loadConfigFile` uses for a file it discovered
 itself. `dir` matters: it's what upward `node_modules` resolution sees, so
 content that does `import { defineConfig } from "@theholocron/cli"` only
 resolves if `dir` sits under a tree where that package is a real
-dependency. Callers own creating and cleaning up `dir`. Returns
+dependency — [`withConfigSandbox`](#withconfigsandbox-nodemodules-root-prefix--run) prepares
+one. Callers own creating and cleaning up `dir`. Returns
 `{ config, filepath }`; throws `ConfigFileError` the same way
 `loadConfigFile` does on a parse/load failure.
 
@@ -77,7 +78,26 @@ Built for `@theholocron/sentinel`'s `validateConfig()` — it fetches a
 repo's `holocron.config.*` from GitHub's API, not a local checkout, but
 still needs the fetched content to execute as a real module.
 
-### `loadLayered<T>({ cwd, name, fallback?, extensions?, walkUp? })`
+### `readConfigSource({ name, fetch, extensions? })`
+
+`loadConfigFile`'s extension probe for a config that lives somewhere other
+than the local disk. Asks `fetch(path)` for `<name>.config.<ext>` in
+extension-priority order (`fetch` returns the content, or `undefined` when
+the file isn't there, and throws for any other failure) and returns the first
+hit as `{ path, extension, content }`, or `undefined`. Hand the result to
+`loadConfigFromContent`.
+
+### `withConfigSandbox({ nodeModules, root?, prefix? }, run)`
+
+Runs `run(dir)` with a throwaway directory ready to be
+`loadConfigFromContent`'s `dir`: `node_modules` symlinked to
+`options.nodeModules` (so the config's package imports resolve) and a
+`{"type":"module"}` `package.json` (so `tsx` doesn't default the files to
+CommonJS and `require()` a pure-ESM dependency). Created under the OS temp dir
+by default — read-only deployments can't write inside a package — and removed
+afterwards, also when `run` throws.
+
+### `loadLayered<T>({ cwd, name, fallback?, extensions?, walkUp?, coerce? })`
 
 `<name>.config.*` layered over the `[fallback.key]` of
 `<fallback.file>.config.*`. Either, both, or neither may be present; the
@@ -85,6 +105,19 @@ dedicated file wins on conflict (`vitest`-over-`vite`). Returns
 `{ config, filepath, sources } | null` — `sources` lists the absolute
 paths actually merged, lowest priority first.
 
+- `fallback.preloaded` — the `<fallback.file>.config.*` the caller has
+  already loaded (`null`: looked for, not there), used as is instead of loading
+  it again.
+- `coerce(raw)` — turns each layer's raw value into the shape being merged
+  before the merge (a bare array standing for `{ tasks: [...] }`, say);
+  returning `undefined` treats the layer as absent.
+
+### `mergeLayers<T>(layers)`
+
+The merge `loadLayered` uses, for layers loaded some other way: deep-merges
+`layers` lowest priority first, skipping `undefined`, and returns a copy — or
+`undefined` when there is nothing to merge.
+
 ### `mergeConfig<T>(base, override)`
 
 Deep-merge, `vite`-style: plain objects merge recursively, arrays

package/dist/index.d.mts

@@ -1,4 +1,8 @@
 import { deepMerge as mergeConfig } from "@theholocron/object-utils";
+//#region src/default-extensions.d.ts
+/** Default extension probe order, highest priority first. */
+declare const DEFAULT_EXTENSIONS: readonly ["ts", "js", "mjs", "cjs", "json"];
+//#endregion
 //#region src/define.d.ts
 /**
  * Build a typed identity `defineConfig` for a specific config shape.
@@ -30,30 +34,7 @@ declare class ConfigFileError extends Error {
   filepath?: string | undefined);
 }
 //#endregion
-//#region src/load.d.ts
-/**
- * Discover and load `<name>.config.*` files, or load one from content that
- * didn't come from a file at all ({@link loadConfigFromContent}).
- * Holocron-agnostic — no schema, no validation, no defaults. Consumers
- * layer those on top.
- *
- * Probe order is **TS-first**: `.ts` → `.js` → `.mjs` → `.cjs` → `.json`.
- * TS is loaded through `tsx`'s `tsImport` (a runtime dependency) so a
- * typed `defineConfig` file works with no build step.
- *
- * `walkUp` (off by default) adds the "nearest config" search
- * cosmiconfig/postcss/stylelint/ESLint's flat config all do: when `cwd`
- * itself has no match, check its parent, then its parent's parent, and so
- * on — stopping at the first directory containing a `.git` entry (checked
- * after that directory's own config probe, so the project root itself is
- * still searched) or the filesystem root. Never wanders past a repo
- * boundary into an unrelated enclosing directory. Built on
- * `@theholocron/fs-utils`'s `findUpward`/`hasGitEntry` — the same
- * upward-walk shape `@theholocron/sentinel`'s own `findPackageRoot` needs,
- * only with a different predicate.
- */
-/** Default extension probe order, highest priority first. */
-declare const DEFAULT_EXTENSIONS: readonly ["ts", "js", "mjs", "cjs", "json"];
+//#region src/load-config-file.type.d.ts
 interface LoadConfigFileOptions {
   /** Directory to start looking in. */
   cwd: string;
@@ -75,6 +56,8 @@ interface Loaded<T> {
   /** Absolute path of the file the value came from. */
   filepath: string;
 }
+//#endregion
+//#region src/load-config-file.d.ts
 /**
  * Load the first `<name>.config.<ext>` found starting at `cwd` — just
  * `cwd` itself by default, or walking up through ancestor directories when
@@ -83,31 +66,8 @@ interface Loaded<T> {
  * {@link ConfigFileError} when a file exists but cannot be loaded.
  */
 declare function loadConfigFile<T>(opts: LoadConfigFileOptions): Promise<Loaded<T> | null>;
-interface LoadLayeredOptions extends LoadConfigFileOptions {
-  /**
-   * When no dedicated `<name>.config.*` exists — or in addition to it —
-   * read `<file>.config.*` and take its `[key]`. The dedicated file (if
-   * any) is merged on top.
-   */
-  fallback?: {
-    file: string;
-    key: string;
-  };
-}
-interface LayeredResult<T> {
-  config: T;
-  /** The dedicated file path if present, else the fallback file path, else `null`. */
-  filepath: string | null;
-  /** Absolute paths actually merged, lowest priority first. */
-  sources: string[];
-}
-/**
- * `<name>.config.*` layered over the `[fallback.key]` of
- * `<fallback.file>.config.*`. Either, both, or neither may be present;
- * the dedicated file wins on conflict (vitest-over-vite). Returns `null`
- * when neither source resolves.
- */
-declare function loadLayered<T>(opts: LoadLayeredOptions): Promise<LayeredResult<T> | null>;
+//#endregion
+//#region src/load-config-from-content.type.d.ts
 interface LoadConfigFromContentOptions {
   /**
    * Directory to write `<name>.config.<extension>` into before loading —
@@ -125,6 +85,8 @@ interface LoadConfigFromContentOptions {
   /** Which of `DEFAULT_EXTENSIONS` `content` is — determines how it's interpreted (ts/js/mjs/cjs parsed as a module, json as `JSON.parse`). */
   extension: string;
 }
+//#endregion
+//#region src/load-config-from-content.d.ts
 /**
  * Load config from content that didn't come from a file already on disk —
  * writes it to `<dir>/<name>.config.<extension>` first, then loads it
@@ -137,4 +99,131 @@ interface LoadConfigFromContentOptions {
  */
 declare function loadConfigFromContent<T>(opts: LoadConfigFromContentOptions): Promise<Loaded<T>>;
 //#endregion
-export { ConfigFileError, DEFAULT_EXTENSIONS, type LayeredResult, type LoadConfigFileOptions, type LoadConfigFromContentOptions, type LoadLayeredOptions, type Loaded, createDefineConfig, loadConfigFile, loadConfigFromContent, loadLayered, mergeConfig };
+//#region src/load-layered.type.d.ts
+interface LoadLayeredOptions<T = unknown> extends LoadConfigFileOptions {
+  /**
+   * When no dedicated `<name>.config.*` exists — or in addition to it —
+   * read `<file>.config.*` and take its `[key]`. The dedicated file (if
+   * any) is merged on top.
+   */
+  fallback?: {
+    file: string;
+    key: string;
+    /**
+     * The `<file>.config.*` already loaded by the caller (`null`: it was
+     * looked for and isn't there). Used as is instead of loading it again;
+     * leave it `undefined` to have `loadLayered` find and load it.
+     */
+    preloaded?: Loaded<object> | null;
+  };
+  /**
+   * Turns each layer's raw value — the dedicated file's default export, and
+   * the fallback's `[key]` — into the shape being merged, before the merge.
+   * Return `undefined` to treat the layer as absent. For configs that accept
+   * shorthand (a bare array standing for `{ tasks: [...] }`).
+   */
+  coerce?: (raw: unknown) => T | undefined;
+}
+interface LayeredResult<T> {
+  config: T;
+  /** The dedicated file path if present, else the fallback file path, else `null`. */
+  filepath: string | null;
+  /** Absolute paths actually merged, lowest priority first. */
+  sources: string[];
+}
+//#endregion
+//#region src/load-layered.d.ts
+/**
+ * `<name>.config.*` layered over the `[fallback.key]` of
+ * `<fallback.file>.config.*`. Either, both, or neither may be present;
+ * the dedicated file wins on conflict (vitest-over-vite). Returns `null`
+ * when neither source resolves.
+ */
+declare function loadLayered<T>(opts: LoadLayeredOptions<T>): Promise<LayeredResult<T> | null>;
+//#endregion
+//#region src/merge-layers.d.ts
+/**
+ * Deep-merges config layers, lowest priority first (a later layer wins on
+ * scalars; arrays concatenate; nested objects merge). `undefined` layers are
+ * skipped. Returns `undefined` when there is no layer to merge. The result is
+ * a copy for object layers — it never aliases a layer.
+ *
+ * The one merge `loadLayered` and every caller layering configs it loaded
+ * some other way (content from an API, say) use, so layering means the same
+ * thing everywhere.
+ */
+declare function mergeLayers<T>(layers: readonly (T | undefined)[]): T | undefined;
+//#endregion
+//#region src/read-config-source.type.d.ts
+/** A config file's content fetched from somewhere other than the local disk. */
+interface ConfigSource {
+  /** The file name probed, e.g. `holocron.config.ts` — relative, as `fetch` was asked for it. */
+  path: string;
+  /** Which extension matched — what {@link loadConfigFromContent} needs as `extension`. */
+  extension: string;
+  /** The raw file content. */
+  content: string;
+}
+interface ReadConfigSourceOptions {
+  /** Base name — `"holocron"` probes `holocron.config.{ts,js,mjs,cjs,json}`. */
+  name: string;
+  /**
+   * Fetches one file by relative path (`holocron.config.ts`): its content, or
+   * `undefined` when it doesn't exist. Throw for anything else (a network
+   * failure, a permission error) — that propagates rather than reading as "absent".
+   */
+  fetch: (path: string) => Promise<string | undefined>;
+  /** Override the extension probe order. */
+  extensions?: readonly string[];
+}
+//#endregion
+//#region src/read-config-source.d.ts
+/**
+ * {@link probeExtensions} for a config that lives somewhere other than the
+ * local disk (a GitHub API, a git blob): probes `<name>.config.<ext>` in
+ * extension-priority order through `options.fetch`, returning the first file
+ * that exists, or `undefined` when none does. Pass the result to
+ * `loadConfigFromContent` to execute it exactly as a local file would be.
+ */
+declare function readConfigSource(options: ReadConfigSourceOptions): Promise<ConfigSource | undefined>;
+//#endregion
+//#region src/with-config-sandbox.type.d.ts
+interface ConfigSandboxOptions {
+  /**
+   * A real `node_modules` directory to make visible from the sandbox. A config
+   * that does `import { defineConfig } from "@theholocron/cli"` only resolves
+   * if the directory it sits in has that package reachable by Node's upward
+   * `node_modules` search, so the sandbox gets a symlink to this one (not a
+   * copy — nothing is duplicated).
+   */
+  nodeModules: string;
+  /** Where to create the sandbox. Defaults to the OS temp dir. */
+  root?: string;
+  /** Prefix for the sandbox directory's name. */
+  prefix?: string;
+}
+//#endregion
+//#region src/with-config-sandbox.d.ts
+/**
+ * Runs `run` with a throwaway directory prepared for
+ * {@link loadConfigFromContent}'s `dir`, and removes it afterwards (also when
+ * `run` throws).
+ *
+ * The directory is made for a TS/JS config that imports packages:
+ *
+ * - `node_modules` is a symlink to `options.nodeModules`, so those imports
+ *   resolve as if the config sat next to that directory.
+ * - A `package.json` of `{"type":"module"}` is written into it. Node decides
+ *   whether a `.ts`/`.js` file is ESM or CommonJS from the nearest ancestor
+ *   `package.json`'s `type`, defaulting to CommonJS — and `tsx`'s loader,
+ *   correctly honouring that, would then `require()` a pure-ESM dependency
+ *   such as `@theholocron/cli`'s `dist/index.mjs`, which Node rejects outright
+ *   ("require() of ES Module … not supported").
+ *
+ * The directory lives under the OS temp dir by default rather than inside any
+ * package: read-only deployments (Vercel's Node.js Functions ship the bundle
+ * read-only under `/var/task`) can't create a directory there.
+ */
+declare function withConfigSandbox<R>(options: ConfigSandboxOptions, run: (dir: string) => Promise<R>): Promise<R>;
+//#endregion
+export { ConfigFileError, type ConfigSandboxOptions, type ConfigSource, DEFAULT_EXTENSIONS, type LayeredResult, type LoadConfigFileOptions, type LoadConfigFromContentOptions, type LoadLayeredOptions, type Loaded, type ReadConfigSourceOptions, createDefineConfig, loadConfigFile, loadConfigFromContent, loadLayered, mergeConfig, mergeLayers, readConfigSource, withConfigSandbox };

package/dist/index.mjs

@@ -1,9 +1,20 @@
-import { readFile, stat, writeFile } from "node:fs/promises";
-import { join } from "node:path";
 import { findUpward, hasGitEntry } from "@theholocron/fs-utils";
-import { deepMerge, deepMerge as mergeConfig } from "@theholocron/object-utils";
+import { join } from "node:path";
+import { mkdir, mkdtemp, readFile, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 import { errorMessage } from "@theholocron/misc-utils";
+import { deepMerge, deepMerge as mergeConfig } from "@theholocron/object-utils";
+import { tmpdir } from "node:os";
+//#region src/default-extensions.ts
+/** Default extension probe order, highest priority first. */
+const DEFAULT_EXTENSIONS = [
+	"ts",
+	"js",
+	"mjs",
+	"cjs",
+	"json"
+];
+//#endregion
 //#region src/define.ts
 /**
 * Build a typed identity `defineConfig` for a specific config shape.
@@ -37,7 +48,16 @@ var ConfigFileError = class extends Error {
 	}
 };
 //#endregion
-//#region src/utils.ts
+//#region src/is-file.ts
+async function isFile(path) {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/load-file.ts
 /**
 * The actual file-loading mechanics `load.ts`'s exported functions share:
 * JSON parsing, dynamic `import()` (TS via `tsx`'s persistent ESM loader,
@@ -49,7 +69,7 @@ var ConfigFileError = class extends Error {
 */
 async function loadFile(filepath, ext) {
 	if (ext === "json") return loadJson(filepath);
-	return extractDefault(filepath, ext === "ts" ? await importTs(filepath) : await importModule(filepath));
+	return extractDefault(filepath, await importModule(filepath, ext));
 }
 async function loadJson(filepath) {
 	const text = await readFile(filepath, "utf8");
@@ -59,28 +79,23 @@ async function loadJson(filepath) {
 		throw new ConfigFileError(`${filepath} is not valid JSON: ${errorMessage(err)}`, filepath);
 	}
 }
-async function importModule(filepath) {
-	try {
-		return await import(pathToFileURL(filepath).href);
-	} catch (err) {
-		throw new ConfigFileError(`could not load ${filepath}: ${errorMessage(err)}`, filepath);
-	}
-}
 let tsRegistered;
 async function registerTsx() {
 	const { register } = await import("tsx/esm/api");
 	register();
 }
 /**
-* Load a `.ts` file. `tsx`'s ESM loader is registered once per process
-* (lazily — only when a `.ts` file is actually loaded). `register()` is
-* used over `tsImport()` because a single run may load several TS files
-* (`loadLayered` reads a dedicated file *and* a parent file) and
-* `tsImport`'s one-off register/unregister cycle is not reentrant.
+* Import `filepath`. For `.ts`, `tsx`'s ESM loader is registered first, once
+* per process (lazily — only when a `.ts` file is actually loaded).
+* `register()` is used over `tsImport()` because a single run may load
+* several TS files (`loadLayered` reads a dedicated file *and* a parent
+* file) and `tsImport`'s one-off register/unregister cycle is not reentrant.
 */
-async function importTs(filepath) {
-	tsRegistered ??= registerTsx();
-	await tsRegistered;
+async function importModule(filepath, ext) {
+	if (ext === "ts") {
+		tsRegistered ??= registerTsx();
+		await tsRegistered;
+	}
 	try {
 		return await import(pathToFileURL(filepath).href);
 	} catch (err) {
@@ -99,15 +114,27 @@ function extractDefault(filepath, mod) {
 	if (raw === void 0 || raw === null) throw new ConfigFileError(`${filepath} must have a default export (use \`export default defineConfig({…})\`)`, filepath);
 	return raw;
 }
-async function isFile(path) {
-	try {
-		return (await stat(path)).isFile();
-	} catch {
-		return false;
+//#endregion
+//#region src/probe-extensions.ts
+/**
+* Probe `dir` for `<name>.config.<ext>` in extension-priority order,
+* loading and returning the first match. The one piece of per-directory
+* orchestration `loadConfigFile` needs on both its non-walking and
+* walking paths — pulled out so it can be unit-tested directly instead of
+* only through `loadConfigFile`'s full probe/walk behavior.
+*/
+async function probeExtensions(dir, name, extensions) {
+	for (const ext of extensions) {
+		const filepath = join(dir, `${name}.config.${ext}`);
+		if (!await isFile(filepath)) continue;
+		return {
+			config: await loadFile(filepath, ext),
+			filepath
+		};
 	}
 }
 //#endregion
-//#region src/load.ts
+//#region src/load-config-file.ts
 /**
 * Discover and load `<name>.config.*` files, or load one from content that
 * didn't come from a file at all ({@link loadConfigFromContent}).
@@ -129,31 +156,6 @@ async function isFile(path) {
 * upward-walk shape `@theholocron/sentinel`'s own `findPackageRoot` needs,
 * only with a different predicate.
 */
-/** Default extension probe order, highest priority first. */
-const DEFAULT_EXTENSIONS = [
-	"ts",
-	"js",
-	"mjs",
-	"cjs",
-	"json"
-];
-/**
-* Probe `dir` for `<name>.config.<ext>` in extension-priority order,
-* loading and returning the first match. The one piece of per-directory
-* orchestration `loadConfigFile` needs on both its non-walking and
-* walking paths — pulled out so it can be unit-tested directly instead of
-* only through `loadConfigFile`'s full probe/walk behavior.
-*/
-async function probeExtensions(dir, name, extensions) {
-	for (const ext of extensions) {
-		const filepath = join(dir, `${name}.config.${ext}`);
-		if (!await isFile(filepath)) continue;
-		return {
-			config: await loadFile(filepath, ext),
-			filepath
-		};
-	}
-}
 /**
 * Load the first `<name>.config.<ext>` found starting at `cwd` — just
 * `cwd` itself by default, or walking up through ancestor directories when
@@ -167,6 +169,45 @@ async function loadConfigFile(opts) {
 	if (!opts.walkUp) return await checkDir(opts.cwd) ?? null;
 	return await findUpward(opts.cwd, checkDir, hasGitEntry) ?? null;
 }
+//#endregion
+//#region src/load-config-from-content.ts
+/**
+* Load config from content that didn't come from a file already on disk —
+* writes it to `<dir>/<name>.config.<extension>` first, then loads it
+* through the exact same path {@link loadConfigFile} uses for a file it
+* discovered itself. Exists because sourcing config content from somewhere
+* other than the local filesystem (a GitHub API fetch, for one — see
+* `@theholocron/sentinel`) doesn't change what loading it correctly means:
+* a `.ts` config still needs real module resolution, `defineConfig` import
+* included, not a re-implemented parser.
+*/
+async function loadConfigFromContent(opts) {
+	const filepath = join(opts.dir, `${opts.name}.config.${opts.extension}`);
+	await writeFile(filepath, opts.content, "utf8");
+	return {
+		config: await loadFile(filepath, opts.extension),
+		filepath
+	};
+}
+//#endregion
+//#region src/merge-layers.ts
+/**
+* Deep-merges config layers, lowest priority first (a later layer wins on
+* scalars; arrays concatenate; nested objects merge). `undefined` layers are
+* skipped. Returns `undefined` when there is no layer to merge. The result is
+* a copy for object layers — it never aliases a layer.
+*
+* The one merge `loadLayered` and every caller layering configs it loaded
+* some other way (content from an API, say) use, so layering means the same
+* thing everywhere.
+*/
+function mergeLayers(layers) {
+	const present = layers.filter((layer) => layer !== void 0);
+	if (present.length === 0) return void 0;
+	return present.reduce((acc, layer) => deepMerge(acc, layer), {});
+}
+//#endregion
+//#region src/load-layered.ts
 /**
 * `<name>.config.*` layered over the `[fallback.key]` of
 * `<fallback.file>.config.*`. Either, both, or neither may be present;
@@ -174,47 +215,94 @@ async function loadConfigFile(opts) {
 * when neither source resolves.
 */
 async function loadLayered(opts) {
+	const coerce = opts.coerce ?? ((raw) => raw);
 	const dedicated = await loadConfigFile(opts);
+	let top;
+	let topFile = null;
+	if (dedicated) {
+		top = coerce(dedicated.config);
+		if (top !== void 0) topFile = dedicated.filepath;
+	}
 	let base;
 	let baseFile = null;
 	if (opts.fallback) {
-		const parent = await loadConfigFile({
+		const parent = opts.fallback.preloaded !== void 0 ? opts.fallback.preloaded : await loadConfigFile({
 			cwd: opts.cwd,
 			name: opts.fallback.file,
 			extensions: opts.extensions,
 			walkUp: opts.walkUp
 		});
-		if (parent && parent.config[opts.fallback.key] !== void 0) {
-			base = parent.config[opts.fallback.key];
-			baseFile = parent.filepath;
+		const raw = (parent?.config)?.[opts.fallback.key];
+		if (parent && raw !== void 0) {
+			base = coerce(raw);
+			if (base !== void 0) baseFile = parent.filepath;
 		}
 	}
-	if (!dedicated && base === void 0) return null;
-	const config = deepMerge(base, dedicated?.config);
-	const sources = [baseFile, dedicated?.filepath ?? null].filter((s) => s !== null);
+	const config = mergeLayers([base, top]);
+	if (config === void 0) return null;
+	const sources = [baseFile, topFile].filter((s) => s !== null);
 	return {
 		config,
-		filepath: dedicated?.filepath ?? baseFile,
+		filepath: topFile ?? baseFile,
 		sources
 	};
 }
+//#endregion
+//#region src/read-config-source.ts
 /**
-* Load config from content that didn't come from a file already on disk —
-* writes it to `<dir>/<name>.config.<extension>` first, then loads it
-* through the exact same path {@link loadConfigFile} uses for a file it
-* discovered itself. Exists because sourcing config content from somewhere
-* other than the local filesystem (a GitHub API fetch, for one — see
-* `@theholocron/sentinel`) doesn't change what loading it correctly means:
-* a `.ts` config still needs real module resolution, `defineConfig` import
-* included, not a re-implemented parser.
+* {@link probeExtensions} for a config that lives somewhere other than the
+* local disk (a GitHub API, a git blob): probes `<name>.config.<ext>` in
+* extension-priority order through `options.fetch`, returning the first file
+* that exists, or `undefined` when none does. Pass the result to
+* `loadConfigFromContent` to execute it exactly as a local file would be.
 */
-async function loadConfigFromContent(opts) {
-	const filepath = join(opts.dir, `${opts.name}.config.${opts.extension}`);
-	await writeFile(filepath, opts.content, "utf8");
-	return {
-		config: await loadFile(filepath, opts.extension),
-		filepath
-	};
+async function readConfigSource(options) {
+	for (const extension of options.extensions ?? DEFAULT_EXTENSIONS) {
+		const path = `${options.name}.config.${extension}`;
+		const content = await options.fetch(path);
+		if (content !== void 0) return {
+			path,
+			extension,
+			content
+		};
+	}
+}
+//#endregion
+//#region src/with-config-sandbox.ts
+/**
+* Runs `run` with a throwaway directory prepared for
+* {@link loadConfigFromContent}'s `dir`, and removes it afterwards (also when
+* `run` throws).
+*
+* The directory is made for a TS/JS config that imports packages:
+*
+* - `node_modules` is a symlink to `options.nodeModules`, so those imports
+*   resolve as if the config sat next to that directory.
+* - A `package.json` of `{"type":"module"}` is written into it. Node decides
+*   whether a `.ts`/`.js` file is ESM or CommonJS from the nearest ancestor
+*   `package.json`'s `type`, defaulting to CommonJS — and `tsx`'s loader,
+*   correctly honouring that, would then `require()` a pure-ESM dependency
+*   such as `@theholocron/cli`'s `dist/index.mjs`, which Node rejects outright
+*   ("require() of ES Module … not supported").
+*
+* The directory lives under the OS temp dir by default rather than inside any
+* package: read-only deployments (Vercel's Node.js Functions ship the bundle
+* read-only under `/var/task`) can't create a directory there.
+*/
+async function withConfigSandbox(options, run) {
+	const root = options.root ?? tmpdir();
+	await mkdir(root, { recursive: true });
+	const dir = await mkdtemp(join(root, options.prefix ?? "datapad-"));
+	try {
+		await symlink(options.nodeModules, join(dir, "node_modules"), "dir");
+		await writeFile(join(dir, "package.json"), JSON.stringify({ type: "module" }), "utf8");
+		return await run(dir);
+	} finally {
+		await rm(dir, {
+			recursive: true,
+			force: true
+		});
+	}
 }
 //#endregion
-export { ConfigFileError, DEFAULT_EXTENSIONS, createDefineConfig, loadConfigFile, loadConfigFromContent, loadLayered, mergeConfig };
+export { ConfigFileError, DEFAULT_EXTENSIONS, createDefineConfig, loadConfigFile, loadConfigFromContent, loadLayered, mergeConfig, mergeLayers, readConfigSource, withConfigSandbox };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/datapad",
-  "version": "5.0.0-alpha.148",
+  "version": "5.0.0-alpha.149",
   "description": "Generic config-file loading for Holocron — discover, load (JSON/JS/TS/ESM/CJS), and merge <name>.config.* files with a typed defineConfig.",
   "keywords": [
     "config",