@wolfstar/schema 0.3.0 → 0.4.0-next-20261001111011

package/dist/esm/index.js

@@ -70,7 +70,7 @@ const configDiagnostics = defineDiagnostics({
 		},
 		TSDOWN_CONFIG_FILE_UNSUPPORTED: {
 			why: (p) => `\`${p.file}\` is not used with compatibility version ${p.version}`,
-			fix: (p) => `Move its options into \`tsdown\` here, drop the ${p.file} configuration, or set \`future.compatibilityVersion\` to ${p.legacyVersion}.`
+			fix: (p) => `Move its options into \`tsdown\` here and drop ${p.file}. \`future.compatibilityVersion\` ${p.legacyVersion} still loads it, but is end-of-life.`
 		},
 		INVALID_TYPE: {
 			why: (p) => `\`${p.path}\` must be ${p.expected}, received ${describeValue(p.value)}`,
@@ -78,12 +78,20 @@ const configDiagnostics = defineDiagnostics({
 		},
 		INVALID_COMPATIBILITY_VERSION: {
 			why: (p) => `Unknown compatibility version ${describeValue(p.value)}`,
-			fix: (p) => `Use ${p.legacyVersion} for the legacy build pipeline or ${p.latestVersion} for today's defaults.`
+			fix: (p) => `Use one of ${p.supported}; ${p.latestVersion} carries today's defaults.`
+		},
+		COMPATIBILITY_VERSION_EOL: {
+			why: (p) => `Compatibility version ${p.version} is end-of-life and will be removed in the next major`,
+			fix: (p) => `Move the options of your tsdown.config.* into \`tsdown\` in stars.config, delete that file, then set \`future.compatibilityVersion\` to ${p.latestVersion} (or remove it).`
 		},
 		UNKNOWN_OPTION: {
 			why: (p) => `Unknown option \`${p.path}\``,
 			fix: (p) => `Known options${p.parent ? ` of \`${p.parent}\`` : ""}: ${p.known}.`
 		},
+		UNKNOWN_HOOK: {
+			why: (p) => `Unknown hook \`${p.name}\``,
+			fix: (p) => `Known hooks: ${p.known}.`
+		},
 		EXPERIMENT_REQUIRED: {
 			why: (p) => `\`${p.path}\` needs \`${p.requires}\``,
 			fix: (p) => `Set \`${p.requires}\` to true as well, or drop \`${p.drop}\`.`
@@ -92,6 +100,10 @@ const configDiagnostics = defineDiagnostics({
 			why: (_p) => "`imports` requires the `tsdown` build tool",
 			fix: (_p) => "Set `build.tool` to 'tsdown', or remove `imports`/set it to `false`."
 		},
+		ENV_REQUIRES_ENV_UTILITIES: {
+			why: (_p) => "`env` is enabled, but the project does not depend on `@wolfstar/env-utilities`",
+			fix: (_p) => "Install it with `pnpm add @wolfstar/env-utilities`, or set `env` to `false`."
+		},
 		LOCALES_NOT_FOUND: {
 			why: (p) => `The locales directory does not exist: ${p.locales}`,
 			fix: (_p) => "Point `codegen.i18n.locales` to the base locale directory, relative to the project root."
@@ -208,6 +220,219 @@ function isFile$1(path) {
 	}
 }
 
+//#endregion
+//#region src/config/compatibility.ts
+const LEGACY_COMPATIBILITY_VERSION = 3;
+const LATEST_COMPATIBILITY_VERSION = 5;
+/** The version a project without `future.compatibilityVersion` runs on: today, the latest one. */
+const DEFAULT_COMPATIBILITY_VERSION = 5;
+/** Versions still accepted but scheduled for removal in the next major. */
+const EOL_COMPATIBILITY_VERSIONS = /* @__PURE__ */ new Set([3]);
+/** From this version on, `tsdown` is configured from `stars.config` alone and auto imports are on by default. */
+const STARS_CONFIG_TSDOWN_VERSION = 4;
+/** From this version on, `env` is registered automatically in the built entry. */
+const AUTO_ENV_VERSION = 5;
+const COMPATIBILITY_VERSIONS = /* @__PURE__ */ new Set([
+	3,
+	4,
+	5
+]);
+/**
+* Resolves the Nuxt-style compatibility block. Version 5 is the default and version 4 remains supported. Version 3 is
+* end-of-life: it still resolves, with a warning pushed to `warnings`, and is removed in the next major.
+*
+* New behaviour is gated by a named version constant (such as {@link AUTO_ENV_VERSION}), never by
+* {@link LATEST_COMPATIBILITY_VERSION}: bumping the latest version must not move older versions onto other defaults.
+*/
+function resolveFuture(config, validator, warnings) {
+	if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.typeError("future", "an object", config, "Use `{ compatibilityVersion }`.");
+	validator.knownKeys(config, "future", ["compatibilityVersion"]);
+	const version = config.compatibilityVersion;
+	if (version === void 0) return { compatibilityVersion: 5 };
+	if (typeof version !== "number" || !COMPATIBILITY_VERSIONS.has(version)) throw validator.error(configDiagnostics.INVALID_COMPATIBILITY_VERSION, {
+		value: version,
+		supported: [...COMPATIBILITY_VERSIONS].join(", "),
+		latestVersion: 5
+	});
+	if (EOL_COMPATIBILITY_VERSIONS.has(version)) warnings.push(validator.error(configDiagnostics.COMPATIBILITY_VERSION_EOL, {
+		version,
+		latestVersion: 5
+	}));
+	return { compatibilityVersion: version };
+}
+
+//#endregion
+//#region src/config/env.ts
+const ENV_UTILITIES = "@wolfstar/env-utilities";
+const LOADERS = /* @__PURE__ */ new Set(["dotenv", "varlock"]);
+/**
+* Resolves the `env` block. It is on by default from {@link AUTO_ENV_VERSION} on, but only when the project depends on
+* `@wolfstar/env-utilities` (the module the built entry imports) and does not build through Nitro, whose serverless
+* presets have no `.env` files to load. `true`, `enabled: true` or any option at all is an explicit opt-in, which
+* does require the dependency.
+*/
+function resolveEnv(config, packageJson, future, experimental, validator) {
+	if (config === false) return {
+		enabled: false,
+		options: {}
+	};
+	const forcedOn = config === true;
+	const raw = forcedOn || config === void 0 ? {} : config;
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw validator.typeError("env", "an object, `true` or `false`", raw, "Use `{ path, env, prefix, loader, debug, encoding }`, `true` to enable with defaults, or `false` to disable.");
+	validator.knownKeys(raw, "env", [
+		"enabled",
+		"path",
+		"env",
+		"prefix",
+		"loader",
+		"debug",
+		"encoding"
+	]);
+	const options = {};
+	const path = validator.string(raw.path, "env.path");
+	if (path !== void 0) options.path = path;
+	const env = validator.string(raw.env, "env.env");
+	if (env !== void 0) options.env = env;
+	const prefix = validator.string(raw.prefix, "env.prefix");
+	if (prefix !== void 0) options.prefix = prefix;
+	const loader = validator.string(raw.loader, "env.loader");
+	if (loader !== void 0) {
+		if (!LOADERS.has(loader)) throw validator.typeError("env.loader", "'dotenv' or 'varlock'", loader, "Use 'dotenv' (default) or 'varlock'.");
+		options.loader = loader;
+	}
+	const debug = validator.boolean(raw.debug, "env.debug");
+	if (debug !== void 0) options.debug = debug;
+	const encoding = validator.string(raw.encoding, "env.encoding");
+	if (encoding !== void 0) options.encoding = encoding;
+	const enabled = validator.boolean(raw.enabled, "env.enabled");
+	if (enabled === false) return {
+		enabled: false,
+		options
+	};
+	const installed = hasDependency(packageJson, ENV_UTILITIES);
+	const explicit = forcedOn || enabled === true || Object.keys(options).length > 0;
+	if (explicit && !installed) throw validator.error(configDiagnostics.ENV_REQUIRES_ENV_UTILITIES, {});
+	const enabledByDefault = installed && future.compatibilityVersion >= 5 && !experimental.enableNitro;
+	return {
+		enabled: explicit || enabledByDefault,
+		options
+	};
+}
+
+//#endregion
+//#region src/config/hooks.ts
+const STARS_HOOK_NAMES = [
+	"config:resolved",
+	"env:options",
+	"prepare:before",
+	"prepare:done",
+	"builder:created",
+	"tsdown:options",
+	"build:before",
+	"build:done",
+	"dev:start",
+	"dev:restart",
+	"dev:close"
+];
+const KNOWN = new Set(STARS_HOOK_NAMES);
+/**
+* Flattens and validates `hooks`. `hookable`'s own `flatHooks` is not used: it would split an array of callbacks into
+* `name:0`, `name:1` and silently drop anything that is not a function, while a typo in a hook name here should fail
+* loudly rather than register a hook that never runs.
+*/
+function resolveHooks(config, validator) {
+	if (config === void 0) return {};
+	const resolved = {};
+	const visit = (value, path) => {
+		if (value === null || typeof value !== "object" || Array.isArray(value)) throw validator.typeError(path ? `hooks.${path}` : "hooks", "an object", value, "Use `{ 'build:done'() {} }` or `{ build: { done() {} } }`.");
+		for (const [key, entry] of Object.entries(value)) {
+			const name = path ? `${path}:${key}` : key;
+			if (entry !== null && typeof entry === "object" && !Array.isArray(entry)) {
+				visit(entry, name);
+				continue;
+			}
+			if (!KNOWN.has(name)) throw validator.error(configDiagnostics.UNKNOWN_HOOK, {
+				name,
+				known: STARS_HOOK_NAMES.join(", ")
+			});
+			const callbacks = Array.isArray(entry) ? entry : [entry];
+			for (const callback of callbacks) if (typeof callback !== "function") throw validator.typeError(`hooks.${name}`, "a function or an array of functions", callback, "Pass a function.");
+			(resolved[name] ??= []).push(...callbacks);
+		}
+	};
+	visit(config, "");
+	return resolved;
+}
+
+//#endregion
+//#region src/config/validator.ts
+/** Validates raw `stars.config` values, throwing a `configDiagnostics` diagnostic grounded in the configuration file. */
+var Validator = class {
+	constructor(file) {
+		this.file = file;
+	}
+	get sources() {
+		return this.file ? [this.file] : void 0;
+	}
+	error(handle, params) {
+		return handle({
+			...params,
+			sources: this.sources
+		});
+	}
+	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(configDiagnostics.UNKNOWN_OPTION, {
+				path: fullPath,
+				parent: path,
+				known: 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;
+	}
+	/** A generic "wrong type" diagnostic. `fix` defaults to the standard "set it or remove it" wording. */
+	typeError(path, expected, value, fix) {
+		return this.error(configDiagnostics.INVALID_TYPE, {
+			path,
+			expected,
+			value,
+			fix: fix ?? `Set \`${path}\` to ${expected} or remove it to use the default.`
+		});
+	}
+};
+
 //#endregion
 //#region src/config/resolve.ts
 const DEFAULT_ENTRIES = [
@@ -236,10 +461,6 @@ const DEFAULT_IMPORTS_PRESETS = [
 const DEFAULT_IMPORTS_DTS = ".stars/imports.d.ts";
 const DEFAULT_DEV_LOG_FILE = ".stars/dev.log";
 const DEFAULT_TUNNEL_PATH = "/";
-const DEFAULT_COMPATIBILITY_VERSION = 4;
-const LEGACY_COMPATIBILITY_VERSION = 3;
-const LATEST_COMPATIBILITY_VERSION = 4;
-const COMPATIBILITY_VERSIONS = /* @__PURE__ */ new Set([3, 4]);
 const BUILD_TOOLS = /* @__PURE__ */ new Set([
 	"tsdown",
 	"tsc",
@@ -286,6 +507,7 @@ function resolveStarsConfig(options) {
 	const file = options.configFile;
 	const config = options.config;
 	const validator = new Validator(file);
+	const warnings = [];
 	validator.knownKeys(config, "", [
 		"root",
 		"entry",
@@ -293,6 +515,8 @@ function resolveStarsConfig(options) {
 		"dev",
 		"codegen",
 		"imports",
+		"env",
+		"hooks",
 		"experimental",
 		"future",
 		"vite",
@@ -303,12 +527,14 @@ function resolveStarsConfig(options) {
 	if (!isDirectory(root)) throw validator.error(configDiagnostics.ROOT_NOT_FOUND, { root });
 	const packageJson = readPackageJson(root, validator);
 	const experimental = resolveExperimental(config.experimental ?? {}, validator);
-	const future = resolveFuture(config.future ?? {}, validator);
+	const future = resolveFuture(config.future ?? {}, validator, warnings);
 	const entry = resolveEntry(root, validator.string(config.entry, "entry"), validator);
 	const vite = validator.plainObject(config.vite, "vite") ?? {};
 	const tsdown = validator.plainObject(config.tsdown, "tsdown") ?? {};
 	const build = resolveBuild(root, entry, packageJson, config.build ?? {}, experimental, future, Object.keys(tsdown).length > 0, validator);
-	const dev = resolveDev(root, entry, packageJson, config.dev ?? {}, env, validator);
+	const hooks = resolveHooks(config.hooks, validator);
+	const envConfig = resolveEnv(config.env, packageJson, future, experimental, validator);
+	const dev = resolveDev(root, entry, packageJson, config.dev ?? {}, env, envConfig.options, options.projectEnv, validator);
 	const codegen = resolveCodegen(root, config.codegen ?? {}, validator);
 	const imports = resolveImports(root, build.tool, future, config.imports, validator);
 	if (Object.keys(tsdown).length > 0 && build.tool !== "tsdown") throw validator.error(configDiagnostics.TSDOWN_OPTIONS_REQUIRE_TSDOWN, { tool: build.tool });
@@ -323,10 +549,13 @@ function resolveStarsConfig(options) {
 		dev,
 		codegen,
 		imports,
+		env: envConfig,
+		hooks,
 		experimental,
 		future,
 		vite,
-		tsdown
+		tsdown,
+		warnings
 	};
 }
 /**
@@ -418,21 +647,6 @@ function detectBuildTool(root, packageJson, isTypeScriptEntry, experimental, fut
 	return "none";
 }
 /**
-* Resolves the Nuxt-style compatibility block. Version 4 is the default; version 3 remains an explicit legacy mode.
-*/
-function resolveFuture(config, validator) {
-	if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.typeError("future", "an object", config, "Use `{ compatibilityVersion }`.");
-	validator.knownKeys(config, "future", ["compatibilityVersion"]);
-	const version = config.compatibilityVersion;
-	if (version === void 0) return { compatibilityVersion: 4 };
-	if (typeof version !== "number" || !COMPATIBILITY_VERSIONS.has(version)) throw validator.error(configDiagnostics.INVALID_COMPATIBILITY_VERSION, {
-		value: version,
-		legacyVersion: 3,
-		latestVersion: 4
-	});
-	return { compatibilityVersion: version };
-}
-/**
 * 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.
@@ -491,16 +705,18 @@ const ENV_PORT_KEYS = ["HTTP_PORT", "PORT"];
 * implementation — quoting is stripped, but expansion (`dotenv-expand`) is not. Earlier files win, matching
 * dotenv's own precedence.
 */
-function readProjectEnvFiles(root, environment = "development") {
+function readProjectEnvFiles(root, environment = "development", options = {}) {
 	const result = {};
-	const files = [
+	const suffixes = [
 		`.${environment}.local`,
 		...environment === "test" ? [] : [".local"],
 		`.${environment}`,
 		""
-	].flatMap((suffix) => [join("src", `.env${suffix}`), `.env${suffix}`]);
+	];
+	const bases = options.path ? [options.path] : [join("src", ".env"), ".env"];
+	const files = suffixes.flatMap((suffix) => bases.map((base) => `${base}${suffix}`));
 	for (const file of files) {
-		const path = join(root, file);
+		const path = resolve(root, file);
 		if (!isFile(path)) continue;
 		let contents;
 		try {
@@ -518,12 +734,13 @@ function readProjectEnvFiles(root, environment = "development") {
 	}
 	return result;
 }
-function readDevPortFromEnvFile(root, environment) {
-	const values = readProjectEnvFiles(root, environment);
+function readDevPortFromEnvFile(root, environment, envOptions, projectEnv) {
+	if (projectEnv === void 0 && envOptions.loader === "varlock") return null;
+	const values = projectEnv ?? readProjectEnvFiles(root, environment, { path: envOptions.path });
 	for (const key of ENV_PORT_KEYS) if (values[key]) return values[key];
 	return null;
 }
-function resolveDev(root, entry, packageJson, config, env, validator) {
+function resolveDev(root, entry, packageJson, config, env, envOptions, projectEnv, validator) {
 	validator.knownKeys(config, "dev", [
 		"banner",
 		"watch",
@@ -557,7 +774,7 @@ function resolveDev(root, entry, packageJson, config, env, validator) {
 		});
 	}
 	else {
-		const port = devEnv.HTTP_PORT ?? env.HTTP_PORT ?? readDevPortFromEnvFile(root, env.NODE_ENV ?? "development") ?? String(3e3);
+		const port = devEnv.HTTP_PORT ?? env.HTTP_PORT ?? readDevPortFromEnvFile(root, envOptions.env ?? env.NODE_ENV ?? "development", envOptions, projectEnv) ?? String(3e3);
 		url = /^\d+$/.test(port) ? `http://localhost:${port}` : `http://localhost:${DEFAULT_DEV_PORT}`;
 	}
 	const typecheck = resolveTypecheck(root, packageJson, config.typecheck, validator);
@@ -738,71 +955,6 @@ function resolveImports(root, buildTool, future, config, validator) {
 		dts
 	};
 }
-var Validator = class {
-	constructor(file) {
-		this.file = file;
-	}
-	get sources() {
-		return this.file ? [this.file] : void 0;
-	}
-	error(handle, params) {
-		return handle({
-			...params,
-			sources: this.sources
-		});
-	}
-	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(configDiagnostics.UNKNOWN_OPTION, {
-				path: fullPath,
-				parent: path,
-				known: 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;
-	}
-	/** A generic "wrong type" diagnostic. `fix` defaults to the standard "set it or remove it" wording. */
-	typeError(path, expected, value, fix) {
-		return this.error(configDiagnostics.INVALID_TYPE, {
-			path,
-			expected,
-			value,
-			fix: fix ?? `Set \`${path}\` to ${expected} or remove it to use the default.`
-		});
-	}
-};
 function hasDependency(packageJson, name) {
 	return Boolean(packageJson?.dependencies?.[name] ?? packageJson?.devDependencies?.[name]);
 }
@@ -857,5 +1009,5 @@ async function loadStarsConfig(options = {}) {
 }
 
 //#endregion
-export { CONFIG_EXTENSIONS, CONFIG_FILE_NAMES, configDiagnostics, defineConfig, discoverConfigFile, displayPath, loadConfigFile, loadStarsConfig, readProjectEnvFiles, resolveStarsConfig };
+export { AUTO_ENV_VERSION, CONFIG_EXTENSIONS, CONFIG_FILE_NAMES, DEFAULT_COMPATIBILITY_VERSION, EOL_COMPATIBILITY_VERSIONS, LATEST_COMPATIBILITY_VERSION, LEGACY_COMPATIBILITY_VERSION, STARS_CONFIG_TSDOWN_VERSION, STARS_HOOK_NAMES, configDiagnostics, defineConfig, discoverConfigFile, displayPath, loadConfigFile, loadStarsConfig, readProjectEnvFiles, resolveEnv, resolveHooks, resolveStarsConfig };
 //# sourceMappingURL=index.js.map