@wolfstar/http-framework 3.3.0 → 3.4.0-next-20260904111115

package/dist/esm/config.js

@@ -0,0 +1,673 @@
+import { t as _defineProperty } from "./defineProperty-BFrI-_1n.js";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+
+//#region src/lib/config/errors.ts
+/**
+* A `stars.config.*` error: an invalid option, or a file that failed to load or parse.
+*
+* This is a plain data error (no exit code or terminal formatting) so it stays meaningful outside a CLI, e.g. for a
+* dashboard or test that calls {@link loadStarsConfig} directly. `@wolfstar/cli` maps it to exit code `2` and renders
+* `message`, `path`, `file` and `hint` for the terminal.
+*/
+var ConfigError = class extends Error {
+	constructor(message, options) {
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		_defineProperty(this, "code", void 0);
+		_defineProperty(this, "hint", void 0);
+		_defineProperty(this, "path", void 0);
+		_defineProperty(this, "file", void 0);
+		this.name = "ConfigError";
+		this.code = options.code;
+		this.hint = options.hint ?? null;
+		this.path = options.path ?? null;
+		this.file = options.file ?? null;
+	}
+};
+
+//#endregion
+//#region src/lib/config/load.ts
+const CONFIG_EXTENSIONS = [
+	"ts",
+	"mts",
+	"cts",
+	"js",
+	"mjs",
+	"cjs"
+];
+const CONFIG_FILE_NAMES = CONFIG_EXTENSIONS.map((extension) => `stars.config.${extension}`);
+/**
+* Finds the first `stars.config.*` file in `cwd`, in {@link CONFIG_FILE_NAMES} order.
+*/
+function discoverConfigFile(cwd) {
+	for (const name of CONFIG_FILE_NAMES) {
+		const candidate = join(cwd, name);
+		if (isFile$1(candidate)) return candidate;
+	}
+	return null;
+}
+/**
+* Loads the raw configuration object. The loader (`c12`) is imported lazily so
+* commands that never touch the configuration stay fast.
+*/
+async function loadConfigFile(options) {
+	const cwd = resolve(options.cwd);
+	let file;
+	if (options.configFile) {
+		file = resolve(cwd, options.configFile);
+		if (!isFile$1(file)) throw new ConfigError(`Configuration file not found: ${file}`, {
+			code: "CONFIG_NOT_FOUND",
+			hint: `Pass an existing file to --config, or create one of ${CONFIG_FILE_NAMES.join(", ")} in ${cwd}.`
+		});
+	} else {
+		file = discoverConfigFile(cwd);
+		if (!file) return {
+			configFile: null,
+			config: {}
+		};
+	}
+	const { loadConfig } = await import("c12");
+	let loaded;
+	try {
+		const result = await loadConfig({
+			name: "stars",
+			cwd: dirname(file),
+			configFile: basename(file),
+			rcFile: false,
+			globalRc: false,
+			dotenv: false,
+			packageJson: false,
+			defaults: {}
+		});
+		const layer = result.layers?.find((candidate) => candidate.configFile && resolve(candidate.cwd ?? dirname(file), candidate.configFile) === file);
+		loaded = layer ? layer.config : result.config;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new ConfigError(`Failed to load the configuration: ${message}`, {
+			code: "CONFIG_LOAD_FAILED",
+			file,
+			hint: "The file must be valid TypeScript/JavaScript and export the configuration as its default export.",
+			cause: error
+		});
+	}
+	if (loaded === null || typeof loaded !== "object" || Array.isArray(loaded)) throw new ConfigError("The configuration file must export an object as its default export.", {
+		code: "CONFIG_NOT_OBJECT",
+		file,
+		hint: "Use `export default defineConfig({ ... })` from '@wolfstar/http-framework/config'."
+	});
+	return {
+		configFile: file,
+		config: loaded
+	};
+}
+function isFile$1(path) {
+	try {
+		return existsSync(path) && statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/lib/config/resolve.ts
+const DEFAULT_ENTRIES = [
+	"src/main.ts",
+	"src/main.js",
+	"src/index.ts",
+	"src/index.js"
+];
+const DEFAULT_IGNORE = [
+	"**/node_modules/**",
+	"**/dist/**",
+	"**/.git/**"
+];
+const DEFAULT_DEBOUNCE = 150;
+const DEFAULT_KILL_TIMEOUT = 5e3;
+const DEFAULT_NODE_ARGS = ["--enable-source-maps"];
+const DEFAULT_DEV_PORT = 3e3;
+const DEFAULT_I18N_LOCALES = "src/locales/en-US";
+const DEFAULT_I18N_OUTPUT = "src/@types/i18next.d.ts";
+const DEFAULT_IMPORTS_DIRS = ["src/lib/**", "src/utils/**"];
+const DEFAULT_IMPORTS_PRESETS = ["@wolfstar/http-framework", "@wolfstar/env-utilities"];
+const DEFAULT_IMPORTS_DTS = ".stars/imports.d.ts";
+const DEFAULT_DEV_LOG_FILE = ".stars/dev.log";
+const DEFAULT_TUNNEL_PATH = "/";
+const BUILD_TOOLS = /* @__PURE__ */ new Set([
+	"tsdown",
+	"tsc",
+	"none",
+	"vite",
+	"auto"
+]);
+const TYPECHECKERS = /* @__PURE__ */ new Set([
+	"tsc",
+	"golar",
+	"tsz",
+	"auto"
+]);
+const VITE_CONFIG_FILES = [
+	"vite.config.ts",
+	"vite.config.mts",
+	"vite.config.cts",
+	"vite.config.js",
+	"vite.config.mjs",
+	"vite.config.cjs"
+];
+const TSDOWN_CONFIG_FILES = [
+	"tsdown.config.ts",
+	"tsdown.config.mts",
+	"tsdown.config.cts",
+	"tsdown.config.js",
+	"tsdown.config.mjs",
+	"tsdown.config.cjs",
+	"tsdown.config.json"
+];
+const TYPESCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([
+	".ts",
+	".mts",
+	".cts"
+]);
+/**
+* Applies defaults, validates every option and resolves all paths to absolute ones.
+*
+* @throws {ConfigError} with an actionable `hint` on the first invalid option.
+*/
+function resolveStarsConfig(options) {
+	const cwd = resolve(options.cwd);
+	const env = options.env ?? process.env;
+	const file = options.configFile;
+	const config = options.config;
+	const validator = new Validator(file);
+	validator.knownKeys(config, "", [
+		"root",
+		"entry",
+		"build",
+		"dev",
+		"codegen",
+		"imports",
+		"experimental",
+		"vite",
+		"tsdown"
+	]);
+	const baseDirectory = file ? dirname(file) : cwd;
+	const root = resolve(baseDirectory, validator.string(config.root, "root") ?? ".");
+	if (!isDirectory(root)) throw validator.error(`The project root does not exist: ${root}`, "root", "ROOT_NOT_FOUND", "Point `root` to an existing directory, relative to the configuration file.");
+	const packageJson = readPackageJson(root);
+	const experimental = resolveExperimental(config.experimental ?? {}, validator);
+	const entry = resolveEntry(root, validator.string(config.entry, "entry"), validator);
+	const build = resolveBuild(root, entry, packageJson, config.build ?? {}, experimental, validator);
+	return {
+		configFile: file,
+		cwd,
+		root,
+		packageJson,
+		entry,
+		build,
+		dev: resolveDev(root, entry, packageJson, config.dev ?? {}, env, validator),
+		codegen: resolveCodegen(root, config.codegen ?? {}, validator),
+		imports: resolveImports(root, build.tool, config.imports, validator),
+		experimental,
+		vite: validator.plainObject(config.vite, "vite") ?? {},
+		tsdown: validator.plainObject(config.tsdown, "tsdown") ?? {}
+	};
+}
+/**
+* Presents an absolute path relative to `root` when possible, for display purposes.
+*/
+function displayPath(root, path) {
+	const rel = relative(root, path);
+	if (!rel) return ".";
+	return rel.startsWith("..") || isAbsolute(rel) ? path : rel;
+}
+function resolveEntry(root, configured, validator) {
+	if (configured !== void 0) {
+		const entry = resolve(root, configured);
+		if (!isFile(entry)) throw validator.error(`The entry file does not exist: ${entry}`, "entry", "ENTRY_NOT_FOUND", "Point `entry` to the file that starts the bot, relative to the project root.");
+		return entry;
+	}
+	for (const candidate of DEFAULT_ENTRIES) {
+		const entry = join(root, candidate);
+		if (isFile(entry)) return entry;
+	}
+	throw validator.error(`Could not find the entry file in ${root}`, "entry", "ENTRY_NOT_FOUND", `Set \`entry\` in the configuration, or create one of ${DEFAULT_ENTRIES.join(", ")}.`);
+}
+function resolveBuild(root, entry, packageJson, config, experimental, validator) {
+	validator.knownKeys(config, "build", [
+		"tool",
+		"outDir",
+		"tsconfig"
+	]);
+	const requested = validator.string(config.tool, "build.tool") ?? "auto";
+	if (!BUILD_TOOLS.has(requested)) throw validator.error(`Unknown build tool "${requested}"`, "build.tool", "INVALID_BUILD_TOOL", "Use one of 'tsdown', 'tsc', 'vite', 'none' or 'auto'.");
+	if (requested === "vite" && !experimental.enableVite) throw validator.error("The 'vite' build tool is experimental", "build.tool", "EXPERIMENT_REQUIRED", "Set `experimental.enableVite` to true to use it.");
+	const isTypeScriptEntry = TYPESCRIPT_EXTENSIONS.has(extname(entry));
+	const tool = requested === "auto" ? detectBuildTool(root, packageJson, isTypeScriptEntry, experimental) : requested;
+	if (tool === "none" && isTypeScriptEntry) throw validator.error(`The entry ${displayPath(root, entry)} is TypeScript but the build tool is 'none'`, "build.tool", "BUILD_TOOL_REQUIRED", "Set `build.tool` to 'tsdown' or 'tsc', or point `entry` to a JavaScript file.");
+	const defaultOutDir = experimental.enableNitro ? ".output" : "dist";
+	const outDir = resolve(root, validator.string(config.outDir, "build.outDir") ?? defaultOutDir);
+	let tsconfig = null;
+	const configuredTsconfig = validator.string(config.tsconfig, "build.tsconfig");
+	if (configuredTsconfig !== void 0) {
+		tsconfig = resolve(root, configuredTsconfig);
+		if (!isFile(tsconfig)) throw validator.error(`The tsconfig file does not exist: ${tsconfig}`, "build.tsconfig", "TSCONFIG_NOT_FOUND", "Point `build.tsconfig` to an existing tsconfig.json, relative to the project root.");
+	} else if (tool === "tsc") {
+		tsconfig = [join(root, "src", "tsconfig.json"), join(root, "tsconfig.json")].find((candidate) => isFile(candidate)) ?? null;
+		if (!tsconfig) throw validator.error(`Could not find a tsconfig.json in ${root}`, "build.tsconfig", "TSCONFIG_NOT_FOUND", "Create src/tsconfig.json or tsconfig.json, or set `build.tsconfig`.");
+	}
+	const output = experimental.enableNitro ? join(outDir, "server", "index.mjs") : tool === "none" ? entry : resolveBuildOutput(root, entry, outDir, packageJson);
+	return {
+		tool,
+		outDir,
+		tsconfig,
+		output
+	};
+}
+function detectBuildTool(root, packageJson, isTypeScriptEntry, experimental) {
+	if (experimental.enableVite) {
+		if (VITE_CONFIG_FILES.some((name) => isFile(join(root, name))) || hasDependency(packageJson, "vite")) return "vite";
+	}
+	if (TSDOWN_CONFIG_FILES.some((name) => isFile(join(root, name))) || hasDependency(packageJson, "tsdown")) return "tsdown";
+	if (isTypeScriptEntry) return "tsc";
+	return "none";
+}
+/**
+* Resolves the `experimental` block. Every flag is a boolean defaulting to `false`, the way Nuxt's own experimental
+* flags are declared, and the ones that build on each other are checked here rather than surfacing later as a
+* confusing runtime failure.
+*/
+function resolveExperimental(config, validator) {
+	if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.error("`experimental` must be an object", "experimental", "INVALID_TYPE", "Use `{ enableVite, enableExternalVite, enableNitro, nitro }`.");
+	validator.knownKeys(config, "experimental", [
+		"enableVite",
+		"enableExternalVite",
+		"enableNitro",
+		"nitro"
+	]);
+	const enableVite = validator.boolean(config.enableVite, "experimental.enableVite") ?? false;
+	const enableExternalVite = validator.boolean(config.enableExternalVite, "experimental.enableExternalVite") ?? false;
+	const enableNitro = validator.boolean(config.enableNitro, "experimental.enableNitro") ?? false;
+	if (enableExternalVite && !enableVite) throw validator.error("`experimental.enableExternalVite` needs `experimental.enableVite`", "experimental.enableExternalVite", "EXPERIMENT_REQUIRED", "Set `experimental.enableVite` to true as well, or drop `enableExternalVite`.");
+	if (enableNitro && !enableVite) throw validator.error("`experimental.enableNitro` needs `experimental.enableVite`", "experimental.enableNitro", "EXPERIMENT_REQUIRED", "Set `experimental.enableVite` to true as well, or drop `enableNitro`.");
+	const rawNitro = "nitro" in config ? config.nitro : void 0;
+	if (rawNitro !== void 0 && !enableNitro) throw validator.error("`experimental.nitro` needs `experimental.enableNitro`", "experimental.nitro", "EXPERIMENT_REQUIRED", "Set `experimental.enableNitro` to true as well, or drop `nitro`.");
+	if (rawNitro !== void 0 && (rawNitro === null || typeof rawNitro !== "object" || Array.isArray(rawNitro))) throw validator.error("`experimental.nitro` must be an object", "experimental.nitro", "INVALID_TYPE", "Use `{ preset }`.");
+	if (rawNitro) validator.knownKeys(rawNitro, "experimental.nitro", ["preset"]);
+	return {
+		enableVite,
+		enableExternalVite,
+		enableNitro,
+		nitro: { preset: validator.string(rawNitro?.preset, "experimental.nitro.preset") ?? "node-server" }
+	};
+}
+function resolveBuildOutput(root, entry, outDir, packageJson) {
+	if (packageJson?.main) return resolve(root, packageJson.main);
+	const extension = extname(entry);
+	const outputExtension = extension === ".mts" ? ".mjs" : extension === ".cts" ? ".cjs" : ".js";
+	return join(outDir, `${basename(entry, extension)}${outputExtension}`);
+}
+const ENV_FILES = [".env.local", ".env"];
+const ENV_PORT_KEYS = ["HTTP_PORT", "PORT"];
+/**
+* Reads the project's `.env.local`/`.env` into a plain object, the way `stars dev` and `stars commands` need it:
+* these files are only loaded into `process.env` by the bot itself once it starts (see `@wolfstar/env-utilities`),
+* so by the time the CLI runs they are not there yet. This is a minimal line reader, not a full dotenv
+* implementation — quoting is stripped, but expansion (`dotenv-expand`) is not. Earlier files win, matching
+* dotenv's own precedence.
+*/
+function readProjectEnvFiles(root) {
+	const result = {};
+	for (const file of ENV_FILES) {
+		const path = join(root, file);
+		if (!isFile(path)) continue;
+		let contents;
+		try {
+			contents = readFileSync(path, "utf-8");
+		} catch {
+			continue;
+		}
+		for (const line of contents.split(/\r?\n/)) {
+			const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+			if (!match) continue;
+			const key = match[1];
+			if (key in result) continue;
+			result[key] = match[2].trim().replace(/^['"]|['"]$/g, "");
+		}
+	}
+	return result;
+}
+function readDevPortFromEnvFile(root) {
+	const values = readProjectEnvFiles(root);
+	for (const key of ENV_PORT_KEYS) if (values[key]) return values[key];
+	return null;
+}
+function resolveDev(root, entry, packageJson, config, env, validator) {
+	validator.knownKeys(config, "dev", [
+		"watch",
+		"ignore",
+		"debounce",
+		"env",
+		"nodeArgs",
+		"args",
+		"url",
+		"health",
+		"killTimeout",
+		"typecheck",
+		"tunnel",
+		"logFile"
+	]);
+	const watch = (validator.stringArray(config.watch, "dev.watch") ?? [displayPath(root, dirname(entry))]).map((path) => resolve(root, path));
+	const ignore = validator.stringArray(config.ignore, "dev.ignore") ?? [...DEFAULT_IGNORE];
+	const debounce = validator.nonNegativeNumber(config.debounce, "dev.debounce") ?? 150;
+	const devEnv = validator.stringRecord(config.env, "dev.env") ?? {};
+	const nodeArgs = validator.stringArray(config.nodeArgs, "dev.nodeArgs") ?? [...DEFAULT_NODE_ARGS];
+	const args = validator.stringArray(config.args, "dev.args") ?? [];
+	const killTimeout = validator.nonNegativeNumber(config.killTimeout, "dev.killTimeout") ?? 5e3;
+	const health = validator.string(config.health, "dev.health") ?? null;
+	let url = validator.string(config.url, "dev.url") ?? null;
+	if (url !== null) try {
+		new URL(url);
+	} catch {
+		throw validator.error(`Invalid URL "${url}"`, "dev.url", "INVALID_URL", "Use an absolute URL such as http://localhost:3000.");
+	}
+	else {
+		const port = devEnv.HTTP_PORT ?? env.HTTP_PORT ?? readDevPortFromEnvFile(root) ?? String(3e3);
+		url = /^\d+$/.test(port) ? `http://localhost:${port}` : `http://localhost:${DEFAULT_DEV_PORT}`;
+	}
+	const typecheck = resolveTypecheck(root, packageJson, config.typecheck, validator);
+	const tunnel = resolveTunnel(config.tunnel, validator);
+	const logFile = config.logFile === false ? null : resolve(root, validator.string(config.logFile, "dev.logFile") ?? ".stars/dev.log");
+	return {
+		watch,
+		ignore,
+		debounce,
+		env: devEnv,
+		nodeArgs,
+		args,
+		url,
+		health,
+		killTimeout,
+		typecheck,
+		tunnel,
+		logFile
+	};
+}
+/**
+* Resolves `dev.typecheck`. The tsconfig is looked up the same way the `tsc` build tool looks up its own, so a
+* project building with `tsdown` still gets `tsc --watch --noEmit` on the right project file.
+*/
+function resolveTypecheck(root, packageJson, config, validator) {
+	if (config === void 0 || config === false) return {
+		enabled: false,
+		tsconfig: null,
+		checker: detectTypechecker(packageJson)
+	};
+	let configured;
+	let requestedChecker = "auto";
+	if (config !== true) {
+		if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.error("`dev.typecheck` must be a boolean or an object", "dev.typecheck", "INVALID_TYPE", "Use `true` to type-check with the project tsconfig, `{ tsconfig }` to pick one, or `false` to disable it.");
+		validator.knownKeys(config, "dev.typecheck", ["tsconfig", "checker"]);
+		configured = validator.string(config.tsconfig, "dev.typecheck.tsconfig");
+		requestedChecker = validator.string(config.checker, "dev.typecheck.checker") ?? "auto";
+		if (!TYPECHECKERS.has(requestedChecker)) throw validator.error(`Unknown type checker "${requestedChecker}"`, "dev.typecheck.checker", "INVALID_TYPECHECKER", "Use one of 'tsc', 'golar', 'tsz' or 'auto'.");
+	}
+	const checker = requestedChecker === "auto" ? detectTypechecker(packageJson) : requestedChecker;
+	if (configured !== void 0) {
+		const tsconfig = resolve(root, configured);
+		if (!isFile(tsconfig)) throw validator.error(`The tsconfig file does not exist: ${tsconfig}`, "dev.typecheck.tsconfig", "TSCONFIG_NOT_FOUND", "Point `dev.typecheck.tsconfig` to an existing tsconfig.json, relative to the project root.");
+		return {
+			enabled: true,
+			tsconfig,
+			checker
+		};
+	}
+	const found = [join(root, "src", "tsconfig.json"), join(root, "tsconfig.json")].find((candidate) => isFile(candidate)) ?? null;
+	if (!found) throw validator.error(`Could not find a tsconfig.json in ${root}`, "dev.typecheck", "TSCONFIG_NOT_FOUND", "Create src/tsconfig.json or tsconfig.json, or set `dev.typecheck.tsconfig`.");
+	return {
+		enabled: true,
+		tsconfig: found,
+		checker
+	};
+}
+/**
+* Picks the type checker when `dev.typecheck.checker` is `auto`: `golar` when the project already depends on it
+* (it wraps TypeScript and is what this repository's own `typecheck` scripts run), `tsc` otherwise. `tsz` is never
+* picked automatically — it is an early, tsc-compatible alternative a project opts into.
+*/
+function detectTypechecker(packageJson) {
+	return hasDependency(packageJson, "golar") ? "golar" : "tsc";
+}
+/**
+* Resolves `dev.tunnel`: `true` (or `{}`) opens a `cloudflared` quick tunnel, a string (or `{ url }`) is an https
+* URL the user already serves and the CLI only checks.
+*/
+function resolveTunnel(config, validator) {
+	if (config === void 0 || config === false) return { mode: "off" };
+	let url;
+	let updateEndpoint = false;
+	let path = "/";
+	if (typeof config === "string") url = config;
+	else if (config !== true) {
+		if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.error("`dev.tunnel` must be a boolean, an https URL or an object", "dev.tunnel", "INVALID_TYPE", "Use `true` for a cloudflared quick tunnel, an https URL you already serve, or `false` to disable it.");
+		validator.knownKeys(config, "dev.tunnel", [
+			"url",
+			"updateEndpoint",
+			"path"
+		]);
+		url = validator.string(config.url, "dev.tunnel.url");
+		updateEndpoint = validator.boolean(config.updateEndpoint, "dev.tunnel.updateEndpoint") ?? false;
+		path = validator.string(config.path, "dev.tunnel.path") ?? "/";
+	}
+	if (url === void 0) return {
+		mode: "quick",
+		path,
+		updateEndpoint
+	};
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw validator.error(`Invalid URL "${url}"`, "dev.tunnel", "INVALID_URL", "Use an absolute https URL such as https://bot.example.com.");
+	}
+	if (parsed.protocol !== "https:") throw validator.error(`The tunnel URL must be https, received "${url}"`, "dev.tunnel", "INVALID_URL", "Discord only accepts an https interactions endpoint.");
+	return {
+		mode: "url",
+		url,
+		path,
+		updateEndpoint
+	};
+}
+function resolveCodegen(root, config, validator) {
+	validator.knownKeys(config, "codegen", ["i18n"]);
+	if (config.i18n === false) return { i18n: null };
+	if (config.i18n === void 0) {
+		const locales = join(root, DEFAULT_I18N_LOCALES);
+		return { i18n: isDirectory(locales) ? {
+			locales,
+			output: join(root, DEFAULT_I18N_OUTPUT)
+		} : null };
+	}
+	if (config.i18n === null || typeof config.i18n !== "object") throw validator.error("`codegen.i18n` must be an object or `false`", "codegen.i18n", "INVALID_TYPE", "Use `{ locales, output }` to configure it or `false` to disable it.");
+	validator.knownKeys(config.i18n, "codegen.i18n", ["locales", "output"]);
+	const locales = resolve(root, validator.string(config.i18n.locales, "codegen.i18n.locales") ?? "src/locales/en-US");
+	if (!isDirectory(locales)) throw validator.error(`The locales directory does not exist: ${locales}`, "codegen.i18n.locales", "LOCALES_NOT_FOUND", "Point `codegen.i18n.locales` to the base locale directory, relative to the project root.");
+	return { i18n: {
+		locales,
+		output: resolve(root, validator.string(config.i18n.output, "codegen.i18n.output") ?? "src/@types/i18next.d.ts")
+	} };
+}
+/**
+* The transform that injects auto imports (`@wolfstar/http-framework/auto-imports`) only runs through `tsdown`'s
+* rolldown pipeline, the same way Nuxt's own auto imports only run through its Vite/webpack build: `tsc` and `none`
+* have no transform step to hook into. `tsdown` is picked as `build.tool` first (see {@link detectBuildTool}) for the
+* same reason — it is the only tool this feature, and this build config in general, treats as the default choice.
+*/
+function resolveImports(root, buildTool, config, validator) {
+	const defaultDirs = DEFAULT_IMPORTS_DIRS.map((dir) => resolve(root, dir));
+	const defaultPresets = [...DEFAULT_IMPORTS_PRESETS];
+	const defaultDts = resolve(root, DEFAULT_IMPORTS_DTS);
+	if (config === false) return {
+		enabled: false,
+		dirs: defaultDirs,
+		presets: defaultPresets,
+		exclude: [],
+		dts: defaultDts
+	};
+	const forcedOn = config === true;
+	const options = forcedOn || config === void 0 ? {} : config;
+	if (typeof options !== "object" || options === null || Array.isArray(options)) throw validator.error("`imports` must be an object, `true` or `false`", "imports", "INVALID_TYPE", "Use `{ dirs, presets, exclude, dts }`, `true` to enable with defaults, or `false` to disable.");
+	validator.knownKeys(options, "imports", [
+		"enabled",
+		"dirs",
+		"presets",
+		"exclude",
+		"dts"
+	]);
+	const requestedOn = forcedOn || validator.boolean(options.enabled, "imports.enabled");
+	if (requestedOn && buildTool !== "tsdown") throw validator.error("`imports` requires the `tsdown` build tool", "imports.enabled", "IMPORTS_REQUIRE_TSDOWN", "Set `build.tool` to 'tsdown', or remove `imports`/set it to `false`.");
+	const dirs = (validator.stringArray(options.dirs, "imports.dirs") ?? [...DEFAULT_IMPORTS_DIRS]).map((dir) => resolve(root, dir));
+	const presets = validator.stringArray(options.presets, "imports.presets") ?? defaultPresets;
+	const exclude = validator.stringArray(options.exclude, "imports.exclude") ?? [];
+	const dts = resolve(root, validator.string(options.dts, "imports.dts") ?? ".stars/imports.d.ts");
+	return {
+		enabled: requestedOn ?? buildTool === "tsdown",
+		dirs,
+		presets,
+		exclude,
+		dts
+	};
+}
+var Validator = class {
+	constructor(file) {
+		this.file = file;
+	}
+	error(message, path, code, hint) {
+		return new ConfigError(message, {
+			code,
+			path,
+			hint,
+			file: this.file
+		});
+	}
+	knownKeys(value, path, keys) {
+		for (const key of Object.keys(value)) {
+			if (keys.includes(key)) continue;
+			const fullPath = path ? `${path}.${key}` : key;
+			throw this.error(`Unknown option \`${fullPath}\``, fullPath, "UNKNOWN_OPTION", `Known options${path ? ` of \`${path}\`` : ""}: ${keys.join(", ")}.`);
+		}
+	}
+	string(value, path) {
+		if (value === void 0) return void 0;
+		if (typeof value !== "string" || value.length === 0) throw this.typeError(path, "a non-empty string", value);
+		return value;
+	}
+	boolean(value, path) {
+		if (value === void 0) return void 0;
+		if (typeof value !== "boolean") throw this.typeError(path, "a boolean", value);
+		return value;
+	}
+	/** A plain object passed through as-is (e.g. raw `vite`/`tsdown` config merged into the project's own). */
+	plainObject(value, path) {
+		if (value === void 0) return void 0;
+		if (value === null || typeof value !== "object" || Array.isArray(value)) throw this.typeError(path, "an object", value);
+		return value;
+	}
+	stringArray(value, path) {
+		if (value === void 0) return void 0;
+		if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) throw this.typeError(path, "an array of strings", value);
+		return value;
+	}
+	nonNegativeNumber(value, path) {
+		if (value === void 0) return void 0;
+		if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw this.typeError(path, "a non-negative number", value);
+		return value;
+	}
+	stringRecord(value, path) {
+		if (value === void 0) return void 0;
+		if (value === null || typeof value !== "object" || Array.isArray(value) || !Object.values(value).every((item) => typeof item === "string")) throw this.typeError(path, "an object of string values", value);
+		return value;
+	}
+	typeError(path, expected, value) {
+		return this.error(`\`${path}\` must be ${expected}, received ${describe(value)}`, path, "INVALID_TYPE", `Set \`${path}\` to ${expected} or remove it to use the default.`);
+	}
+};
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	if (typeof value === "string") return `"${value}"`;
+	return typeof value === "object" ? "an object" : `${typeof value} ${String(value)}`;
+}
+function hasDependency(packageJson, name) {
+	return Boolean(packageJson?.dependencies?.[name] ?? packageJson?.devDependencies?.[name]);
+}
+function readPackageJson(root) {
+	const file = join(root, "package.json");
+	if (!isFile(file)) return null;
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf-8"));
+		return parsed !== null && typeof parsed === "object" ? parsed : null;
+	} catch (error) {
+		throw new ConfigError(`Failed to parse ${file}: ${error instanceof Error ? error.message : String(error)}`, {
+			code: "PACKAGE_JSON_INVALID",
+			hint: "Fix the JSON syntax of the package.json file.",
+			cause: error
+		});
+	}
+}
+function isFile(path) {
+	try {
+		return existsSync(path) && statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+function isDirectory(path) {
+	try {
+		return existsSync(path) && statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/lib/config/index.ts
+/**
+* Loads, validates and resolves a project's `stars.config.*`.
+*
+* @throws {ConfigError} when the configuration file cannot be loaded or contains an invalid option.
+*/
+async function loadStarsConfig(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	const loaded = await loadConfigFile({
+		cwd,
+		configFile: options.configFile
+	});
+	return resolveStarsConfig({
+		cwd,
+		configFile: loaded.configFile,
+		config: loaded.config,
+		env: options.env
+	});
+}
+
+//#endregion
+//#region src/config.ts
+/**
+* Typed helper for `stars.config.{ts,mts,cts,js,mjs,cjs}` files.
+*
+* @example
+* ```ts
+* import { defineConfig } from '@wolfstar/http-framework/config';
+*
+* export default defineConfig({
+* 	entry: 'src/main.ts',
+* 	build: { tool: 'tsdown' }
+* });
+* ```
+*/
+function defineConfig(config) {
+	return config;
+}
+
+//#endregion
+export { CONFIG_EXTENSIONS, CONFIG_FILE_NAMES, ConfigError, defineConfig, discoverConfigFile, displayPath, loadConfigFile, loadStarsConfig, readProjectEnvFiles, resolveStarsConfig };
+//# sourceMappingURL=config.js.map