@moku-labs/common 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1023 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+let _moku_labs_core = require("@moku-labs/core");
+let node_fs = require("node:fs");
+//#region src/plugins/log/expect.ts
+/**
+* Named error thrown by `expect()` assertions when a trace condition fails.
+*
+* @example
+* ```ts
+* throw new LogExpectAssertionError("missing event build:complete");
+* ```
+*/
+var LogExpectAssertionError = class extends Error {
+	/**
+	* Construct a new assertion error with a descriptive failure message.
+	*
+	* @param message - Descriptive failure message (event name, partial, index).
+	* @example
+	* ```ts
+	* throw new LogExpectAssertionError("missing event build:complete");
+	* ```
+	*/
+	constructor(message) {
+		super(message);
+		this.name = "LogExpectAssertionError";
+	}
+};
+/**
+* Tests whether a value is a non-null, non-array plain object.
+*
+* @param value - The value to test.
+* @returns `true` when `value` is a non-null object that is not an array.
+* @example
+* ```ts
+* isPlainObject({ a: 1 }); // true
+* isPlainObject([1]); // false
+* ```
+*/
+function isPlainObject$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Tests whether `actual` is an array that recursively matches every element of
+* the `partial` array (element-wise, with equal length).
+*
+* @param actual - The value to test against (must be an array of equal length).
+* @param partial - The expected partial array shape.
+* @returns `true` when `actual` is an equal-length array matching `partial` element-wise.
+* @example
+* ```ts
+* matchesPartialArray([1, 2], [1, 2]); // true
+* matchesPartialArray([1], [1, 2]); // false (length mismatch)
+* ```
+*/
+function matchesPartialArray(actual, partial) {
+	if (!Array.isArray(actual) || actual.length !== partial.length) return false;
+	return partial.every((value, index) => matchesPartial(actual[index], value));
+}
+/**
+* Tests whether `actual` is a plain object in which every `partial` key
+* recursively matches (extra `actual` keys are ignored).
+*
+* @param actual - The value to test against (must be a plain object).
+* @param partial - The expected partial object shape.
+* @returns `true` when every `partial` key exists in `actual` and matches recursively.
+* @example
+* ```ts
+* matchesPartialObject({ a: 1, b: 2 }, { a: 1 }); // true
+* matchesPartialObject({ a: 1 }, { b: 1 }); // false (missing key)
+* ```
+*/
+function matchesPartialObject(actual, partial) {
+	if (!isPlainObject$1(actual)) return false;
+	return Object.keys(partial).every((key) => key in actual && matchesPartial(actual[key], partial[key]));
+}
+/**
+* Subset-equality matcher: is `partial` a recursive subset of `actual`?
+*
+* Fast path via `Object.is` (covers identical primitives/references and
+* `null`/`NaN`); primitives compare with `Object.is`; arrays match element-wise
+* with equal length; plain objects require every `partial` key to recursively
+* match (extra `actual` keys ignored).
+*
+* @param actual - The value to test against (typically `entry.data`).
+* @param partial - The expected partial shape.
+* @returns `true` when `partial` is a recursive subset of `actual`.
+* @example
+* ```ts
+* matchesPartial({ a: 1, b: 2 }, { a: 1 }); // true
+* matchesPartial([1, 2], [1]); // false (length mismatch)
+* ```
+*/
+function matchesPartial(actual, partial) {
+	if (Object.is(actual, partial)) return true;
+	if (Array.isArray(partial)) return matchesPartialArray(actual, partial);
+	if (isPlainObject$1(partial)) return matchesPartialObject(actual, partial);
+	return false;
+}
+/**
+* Tests whether an entry matches `event` and (when provided) `partial`.
+*
+* @param entry - The candidate trace entry.
+* @param event - Required event name.
+* @param partial - Optional partial data shape (subset-matched against `entry.data`).
+* @returns `true` when the entry matches the event and optional partial.
+* @example
+* ```ts
+* entryMatches({ level: "info", event: "a", data: { x: 1 }, ts: 0 }, "a", { x: 1 }); // true
+* ```
+*/
+function entryMatches(entry, event, partial) {
+	if (entry.event !== event) return false;
+	return partial === void 0 ? true : matchesPartial(entry.data, partial);
+}
+/**
+* Render a `partial` for an error message, prefixed with a space when present.
+*
+* @param partial - Optional partial data shape.
+* @returns A ` matching <json>` suffix, or an empty string when absent.
+* @example
+* ```ts
+* describePartial({ ok: true }); // ' matching {"ok":true}'
+* ```
+*/
+function describePartial(partial) {
+	return partial === void 0 ? "" : ` matching ${JSON.stringify(partial)}`;
+}
+/**
+* Find the first entry with `event` at or after `startIndex`, scanning forward.
+*
+* @param entries - The trace array to scan.
+* @param event - Event name to find.
+* @param startIndex - Index to begin scanning from (inclusive).
+* @returns The index of the first match, or `-1` when none exists from `startIndex` on.
+* @example
+* ```ts
+* findEventAtOrAfter([{ event: "a" }, { event: "b" }] as LogEntry[], "b", 0); // 1
+* ```
+*/
+function findEventAtOrAfter(entries, event, startIndex) {
+	for (let index = startIndex; index < entries.length; index++) if (entries[index]?.event === event) return index;
+	return -1;
+}
+/**
+* Create a fluent assertion chain bound to the live `entries` array. Each method
+* reads `entries` at call time, so assertions reflect later logging.
+*
+* @param entries - The live trace array (read on each assertion call).
+* @returns A fresh {@link ExpectChain} backed by `entries`.
+* @example
+* ```ts
+* createExpectChain(state.entries).toHaveEvent("build:complete");
+* ```
+*/
+function createExpectChain(entries) {
+	const chain = {
+		/**
+		* Assert at least one entry has `event`, optionally matching `partial`.
+		*
+		* @param event - Event name to find.
+		* @param partial - Optional partial data shape (subset-matched).
+		* @returns The same chain for chaining.
+		* @throws {LogExpectAssertionError} When no matching entry exists.
+		* @example
+		* ```ts
+		* chain.toHaveEvent("build:phase", { status: "start" });
+		* ```
+		*/
+		toHaveEvent(event, partial) {
+			if (!entries.some((entry) => entryMatches(entry, event, partial))) throw new LogExpectAssertionError(`Expected trace to contain event "${event}"${describePartial(partial)}, but none was found.`);
+			return chain;
+		},
+		/**
+		* Assert all of `events` appear in the trace in the given relative order.
+		*
+		* @param events - Ordered list of event names (gaps allowed).
+		* @returns The same chain for chaining.
+		* @throws {LogExpectAssertionError} When the ordering cannot be satisfied.
+		* @example
+		* ```ts
+		* chain.toHaveEventInOrder(["build:phase", "build:complete"]);
+		* ```
+		*/
+		toHaveEventInOrder(events) {
+			let cursor = 0;
+			for (const [position, event] of events.entries()) {
+				const matchIndex = findEventAtOrAfter(entries, event, cursor);
+				if (matchIndex === -1) throw new LogExpectAssertionError(`Expected events in order ${JSON.stringify(events)}, but "${event}" (index ${position}) was not found at or after position ${cursor}.`);
+				cursor = matchIndex + 1;
+			}
+			return chain;
+		},
+		/**
+		* Assert NO entry has `event` (optionally narrowed by `partial`).
+		*
+		* @param event - Event name that must be absent.
+		* @param partial - Optional partial data shape; only matching entries violate.
+		* @returns The same chain for chaining.
+		* @throws {LogExpectAssertionError} When a matching entry exists.
+		* @example
+		* ```ts
+		* chain.toNotHaveEvent("deploy:failed");
+		* ```
+		*/
+		toNotHaveEvent(event, partial) {
+			const offending = entries.findIndex((entry) => entryMatches(entry, event, partial));
+			if (offending !== -1) throw new LogExpectAssertionError(`Expected trace to NOT contain event "${event}"${describePartial(partial)}, but found one at index ${offending}.`);
+			return chain;
+		}
+	};
+	return chain;
+}
+//#endregion
+//#region src/plugins/log/api.ts
+/**
+* @file log plugin — API factory.
+*
+* Builds the `LogApi` over the plugin's `{ config, state }` core context:
+* the leveled loggers (via a shared `append`), the frozen `trace()` snapshot,
+* the live `expect()` chain, `addSink`, and `reset`.
+*/
+/**
+* Append a new entry to the trace and fan it out to every sink in order.
+*
+* @param state - The mutable log state to append to.
+* @param level - Severity level for the entry.
+* @param event - Event identifier.
+* @param data - Optional structured payload.
+* @example
+* ```ts
+* append(state, "info", "content:ready", { count: 12 });
+* ```
+*/
+function append(state, level, event, data) {
+	const entry = {
+		level,
+		event,
+		data,
+		ts: Date.now()
+	};
+	state.entries.push(entry);
+	for (const sink of state.sinks) sink.write(entry);
+}
+/**
+* Tests whether a value is a non-null, non-array plain object.
+*
+* @param value - The value to test.
+* @returns `true` when `value` is a non-null object that is not an array.
+* @example
+* ```ts
+* isPlainObject({ a: 1 }); // true
+* isPlainObject([1]); // false
+* ```
+*/
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Merge an `Error`'s `message`/`stack` into `data` under an `error` key. The
+* `error` field is always preserved; only a plain object `data` contributes its
+* keys. Non-plain-object `data` (arrays and primitives) is replaced by `{}` —
+* its original value is not retained — so the merge target is always a record.
+*
+* @param data - Original payload (any shape).
+* @param error - The originating error to merge.
+* @returns A new object carrying any plain-object keys plus the `error` field.
+* @example
+* ```ts
+* mergeError({ target: "cf" }, new Error("boom"));
+* // { target: "cf", error: { message: "boom", stack: "..." } }
+* ```
+*/
+function mergeError(data, error) {
+	return {
+		...isPlainObject(data) ? data : {},
+		error: {
+			message: error.message,
+			stack: error.stack
+		}
+	};
+}
+/**
+* Create the log plugin API surface injected as `ctx.log` / `app.log`.
+*
+* @param ctx - Core plugin context (`{ config, state }`).
+* @returns The {@link LogApi} bound to `ctx.state`.
+* @example
+* ```ts
+* const log = createLogApi(ctx);
+* log.info("content:ready", { articleCount: 12 });
+* ```
+*/
+function createLogApi(ctx) {
+	const { state } = ctx;
+	return {
+		/**
+		* Append an `info` entry and fan it out to every sink.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @example
+		* ```ts
+		* log.info("content:ready", { count: 12 });
+		* ```
+		*/
+		info(event, data) {
+			append(state, "info", event, data);
+		},
+		/**
+		* Append a `debug` entry and fan it out to every sink.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @example
+		* ```ts
+		* log.debug("router:match", { path: "/blog/" });
+		* ```
+		*/
+		debug(event, data) {
+			append(state, "debug", event, data);
+		},
+		/**
+		* Append a `warn` entry and fan it out to every sink.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @example
+		* ```ts
+		* log.warn("build:skip", { reason: "no sitemap" });
+		* ```
+		*/
+		warn(event, data) {
+			append(state, "warn", event, data);
+		},
+		/**
+		* Append an `error` entry. When `error` is provided, its `message`/`stack`
+		* are merged into `data` under an `error` key (existing keys preserved);
+		* otherwise `data` is recorded as-is.
+		*
+		* @param event - Event identifier (convention: `domain:action`).
+		* @param data - Optional structured payload.
+		* @param error - Optional originating Error to merge into `data`.
+		* @example
+		* ```ts
+		* log.error("deploy:failed", { target: "cf" }, err);
+		* ```
+		*/
+		error(event, data, error) {
+			append(state, "error", event, error === void 0 ? data : mergeError(data, error));
+		},
+		/**
+		* Return a frozen snapshot (fresh copy) of the entries recorded so far.
+		*
+		* @returns A readonly, frozen copy of the recorded entries.
+		* @example
+		* ```ts
+		* const entries = log.trace();
+		* ```
+		*/
+		trace() {
+			return Object.freeze([...state.entries]);
+		},
+		/**
+		* Return a fluent assertion chain bound to the live entries array.
+		*
+		* @returns A fresh {@link ExpectChain} reading `state.entries` live.
+		* @example
+		* ```ts
+		* log.expect().toHaveEvent("build:complete");
+		* ```
+		*/
+		expect() {
+			return createExpectChain(state.entries);
+		},
+		/**
+		* Register an additional output sink at runtime.
+		*
+		* @param sink - The sink to add to the fan-out list.
+		* @example
+		* ```ts
+		* log.addSink({ write: (e) => stream.write(JSON.stringify(e)) });
+		* ```
+		*/
+		addSink(sink) {
+			state.sinks.push(sink);
+		},
+		/**
+		* Clear all recorded entries while keeping registered sinks.
+		*
+		* @example
+		* ```ts
+		* log.reset();
+		* ```
+		*/
+		reset() {
+			state.entries.length = 0;
+		}
+	};
+}
+//#endregion
+//#region src/plugins/log/sinks.ts
+/** Severity rank for threshold comparison (higher = more severe). */
+const LEVEL_RANK = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40
+};
+/**
+* Build the console sink: routes entries by channel — `error` → `console.error`,
+* `warn` → `console.warn`, and `debug`/`info` → `console.log`. The full entry
+* object is forwarded so the console serializes its `event` and `data`. Entries
+* below `minLevel` are dropped (the in-memory trace still records everything).
+*
+* @param minLevel - Lowest severity to print. Defaults to `"debug"` (print all).
+* @returns A {@link LogSink} that writes to the matching `console` channel.
+* @example
+* ```ts
+* state.sinks.push(consoleSink("info")); // suppress debug spam
+* ```
+*/
+function consoleSink(minLevel = "debug") {
+	const threshold = LEVEL_RANK[minLevel];
+	return { 
+	/**
+	* Route a single entry to the console channel matching its level.
+	*
+	* @param entry - The entry to emit.
+	* @example
+	* ```ts
+	* sink.write({ level: "warn", event: "build:skip", ts: Date.now() });
+	* ```
+	*/
+write(entry) {
+		if (LEVEL_RANK[entry.level] < threshold) return;
+		if (entry.level === "error") console.error(entry);
+		else if (entry.level === "warn") console.warn(entry);
+		else console.log(entry);
+	} };
+}
+/**
+* Install mode-selected default sinks at onInit. The in-memory trace is always
+* on (`state.entries`); the console sink is added only in dev/production. `dev`
+* prints everything (debug+); `production` prints `info`+ only, so the per-phase
+* `debug` events (build:bundle, build:pages, …) don't spam a prod build. Both
+* modes still record all levels in the in-memory trace.
+*
+* @param ctx - Core plugin context (`{ config, state }`).
+* @param ctx.config - Resolved log config (`{ mode }`).
+* @param ctx.state - Mutable log state (`{ entries, sinks }`).
+* @example
+* ```ts
+* // "dev" -> [consoleSink("debug")]; "production" -> [consoleSink("info")]; "test"/"silent" -> []
+* ```
+*/
+function installDefaultSinks(ctx) {
+	if (ctx.config.mode === "dev") ctx.state.sinks.push(consoleSink("debug"));
+	else if (ctx.config.mode === "production") ctx.state.sinks.push(consoleSink("info"));
+}
+//#endregion
+//#region src/plugins/log/state.ts
+/**
+* Create fresh log state: an empty append-only trace and an empty sink list.
+* No module-level singletons — guarantees per-`createApp` isolation (two
+* `createApp` calls never share `entries` or `sinks`).
+*
+* @param _ctx - Core plugin context (`{ config }`); unused at construction.
+* @returns A fresh `LogState` with empty `entries` and `sinks` arrays.
+* @example
+* ```ts
+* const state = createLogState({ config: { mode: "test" } }); // { entries: [], sinks: [] }
+* ```
+*/
+function createLogState(_ctx) {
+	return {
+		entries: [],
+		sinks: []
+	};
+}
+/**
+* Core logging plugin — always-on in-memory trace + `expect()` event-trace DSL.
+* API injected as `ctx.log` on every regular plugin and surfaced as `app.log`.
+* No depends / events / hooks (core plugin per spec/03 §5).
+*
+* @see README.md
+*/
+const logPlugin = (0, _moku_labs_core.createCorePlugin)("log", {
+	config: { mode: "production" },
+	createState: createLogState,
+	api: createLogApi,
+	onInit: installDefaultSinks
+});
+//#endregion
+//#region src/plugins/env/api.ts
+/** Error prefix for all env API failures. */
+const ERROR_PREFIX$1 = "[web]";
+/**
+* Creates the env plugin API surface mounted at `ctx.env`. Closes over
+* `ctx.state` ({@link EnvState}) and reads the frozen `resolved` / `publicMap`
+* maps; closures never return a raw `ctx.state` reference.
+*
+* @param ctx - Core plugin context carrying the frozen env state.
+* @param ctx.state - The resolved + public {@link EnvState} maps.
+* @returns The {@link EnvApi} accessor surface mounted at `ctx.env`.
+* @example
+* ```ts
+* const api = createEnvApi(ctx);
+* api.get("PUBLIC_API_URL");
+* ```
+*/
+function createEnvApi(ctx) {
+	const { resolved, publicMap } = ctx.state;
+	return {
+		/**
+		* Reads a resolved variable.
+		*
+		* @param key - Variable name.
+		* @returns The value, or `undefined` if not present.
+		* @example
+		* ```ts
+		* api.get("PUBLIC_API_URL");
+		* ```
+		*/
+		get(key) {
+			return resolved.get(key);
+		},
+		/**
+		* Reads a variable that must exist.
+		*
+		* @param key - Variable name.
+		* @returns The value.
+		* @throws {Error} If the variable is undefined.
+		* @example
+		* ```ts
+		* api.require("DEPLOY_TOKEN");
+		* ```
+		*/
+		require(key) {
+			const value = resolved.get(key);
+			if (value === void 0) throw new Error(`${ERROR_PREFIX$1} env: required variable "${key}" is not defined.`);
+			return value;
+		},
+		/**
+		* Tests presence of a resolved variable.
+		*
+		* @param key - Variable name.
+		* @returns `true` if a value is present.
+		* @example
+		* ```ts
+		* api.has("PUBLIC_API_URL");
+		* ```
+		*/
+		has(key) {
+			return resolved.has(key);
+		},
+		/**
+		* Returns all public variables as a frozen plain object — a fresh copy,
+		* never the raw state map.
+		*
+		* @returns A frozen `Record` of public variable names to values.
+		* @example
+		* ```ts
+		* const payload = { ...api.getPublic() };
+		* ```
+		*/
+		getPublic() {
+			return Object.freeze(Object.fromEntries(publicMap));
+		},
+		/**
+		* Returns the already-frozen map of public variables.
+		*
+		* @returns The frozen public map.
+		* @example
+		* ```ts
+		* [...api.getPublicMap()];
+		* ```
+		*/
+		getPublicMap() {
+			return publicMap;
+		}
+	};
+}
+//#endregion
+//#region src/plugins/env/state.ts
+/**
+* Creates initial env plugin state: two empty, mutable maps that are populated
+* and frozen by `validateSchema` (the `onInit`) at `createApp` time.
+*
+* @returns A fresh `EnvState` with empty `resolved` and `publicMap` maps.
+* @example
+* ```ts
+* const state = createEnvState();
+* state.resolved.size; // 0
+* ```
+*/
+function createEnvState() {
+	return {
+		resolved: /* @__PURE__ */ new Map(),
+		publicMap: /* @__PURE__ */ new Map()
+	};
+}
+//#endregion
+//#region src/plugins/env/validate.ts
+/** Error message thrown by every frozen-map mutator. */
+const FROZEN_MESSAGE = "env: map is frozen and cannot be mutated";
+/** Error prefix for all resolution-pipeline failures. */
+const ERROR_PREFIX = "[web]";
+/** The `Map` mutators redefined as throwers when a map is frozen. */
+const FROZEN_METHODS = [
+	"set",
+	"clear",
+	"delete"
+];
+/**
+* Throws the canonical frozen-map error; installed as a map's `set`/`clear`/`delete`.
+*
+* @throws {TypeError} Always, signalling the map is frozen.
+* @example
+* ```ts
+* frozenThrower(); // throws TypeError
+* ```
+*/
+function frozenThrower() {
+	throw new TypeError(FROZEN_MESSAGE);
+}
+/**
+* Coerces a raw provider value to its effective presence: an empty string counts
+* as "absent" so a `KEY=""` falls through to later providers.
+*
+* @param raw - The raw value a provider supplied for a key (possibly `undefined`).
+* @returns The value, or `undefined` when it is missing or an empty string.
+* @example
+* ```ts
+* coerceEmpty(""); // => undefined
+* coerceEmpty("3000"); // => "3000"
+* ```
+*/
+function coerceEmpty(raw) {
+	return raw === "" ? void 0 : raw;
+}
+/**
+* Merges providers in array order, coercing empty strings to `undefined` before
+* precedence so a `KEY=""` falls through to later providers. First non-empty
+* value wins.
+*
+* @param config - The resolved env config carrying the ordered providers.
+* @returns A flat record of the first defined value found per key.
+* @example
+* ```ts
+* mergeProviders({ providers: [a, b], schema: {}, publicPrefix: "PUBLIC_" });
+* ```
+*/
+function mergeProviders(config) {
+	const merged = {};
+	for (const provider of config.providers) for (const [key, raw] of Object.entries(provider.load())) {
+		const value = coerceEmpty(raw);
+		if (value !== void 0 && merged[key] === void 0) merged[key] = value;
+	}
+	return merged;
+}
+/**
+* Bidirectionally enforces the `PUBLIC_` naming convention against each schema
+* entry's `public` flag. Throws on either violation direction.
+*
+* @param config - The resolved env config carrying `schema` + `publicPrefix`.
+* @throws {Error} If a public var lacks the prefix, or a prefixed var is not public.
+* @example
+* ```ts
+* crossCheckPublicPrefix(config); // throws if PUBLIC_X is not public:true
+* ```
+*/
+function crossCheckPublicPrefix(config) {
+	const { schema, publicPrefix } = config;
+	for (const [key, spec] of Object.entries(schema)) {
+		const hasPrefix = key.startsWith(publicPrefix);
+		if (spec.public === true && !hasPrefix) throw new Error(`${ERROR_PREFIX} env: "${key}" is marked public but does not start with "${publicPrefix}".`);
+		if (hasPrefix && spec.public !== true) throw new Error(`${ERROR_PREFIX} env: "${key}" starts with "${publicPrefix}" but is not marked public:true.`);
+	}
+}
+/**
+* Seals a map so `set`, `clear`, and `delete` throw, then `Object.freeze`s it
+* for defense in depth. Closes the `Object.freeze`-on-`Map` mutability hole by
+* redefining the mutators as non-writable, non-configurable throwers.
+*
+* @param map - The map to freeze in place.
+* @example
+* ```ts
+* freezeMap(state.resolved); // resolved.set(...) now throws
+* ```
+*/
+function freezeMap(map) {
+	for (const method of FROZEN_METHODS) Object.defineProperty(map, method, {
+		value: frozenThrower,
+		writable: false,
+		configurable: false,
+		enumerable: false
+	});
+	Object.freeze(map);
+}
+/**
+* Populates `state.publicMap` with the schema-driven public subset: every
+* `public:true` schema key that resolved to a defined value. This map is the only
+* sanctioned input to a browser-facing `define`, so it stays schema-scoped (never
+* includes non-schema provider keys).
+*
+* @param schema - The per-variable schema from {@link EnvConfig}.
+* @param merged - The merged provider values keyed by variable name.
+* @param publicMap - The mutable public map to fill in place.
+* @example
+* ```ts
+* populatePublicMap(config.schema, merged, state.publicMap);
+* ```
+*/
+function populatePublicMap(schema, merged, publicMap) {
+	for (const [key, spec] of Object.entries(schema)) {
+		const value = merged[key];
+		if (spec.public === true && value !== void 0) publicMap.set(key, value);
+	}
+}
+/**
+* Populates `state.resolved` with EVERY merged key that carries a defined value
+* (spec/02 Lifecycle §5), including non-schema provider keys so
+* `ctx.env.require()` works for dynamic keys.
+*
+* @param merged - The merged provider values keyed by variable name.
+* @param resolved - The mutable resolved map to fill in place.
+* @example
+* ```ts
+* populateResolved(merged, state.resolved);
+* ```
+*/
+function populateResolved(merged, resolved) {
+	for (const [key, value] of Object.entries(merged)) resolved.set(key, value);
+}
+/**
+* Resolves, validates, and freezes the environment table at `onInit`.
+*
+* Pipeline order: merge providers (with empty-string → undefined coercion) →
+* `PUBLIC_` bidirectional cross-check → apply defaults → assert required →
+* populate `state.resolved` / `state.publicMap` → freeze both via
+* {@link freezeMap}. Fail-fast: any violation throws at `createApp` time.
+*
+* @param ctx - Core plugin context (`{ config, state }`).
+* @param ctx.config - The resolved {@link EnvConfig}.
+* @param ctx.state - The mutable {@link EnvState} to populate and freeze.
+* @throws {Error} On a `PUBLIC_` cross-check violation or a missing required variable.
+* @example
+* ```ts
+* validateSchema(ctx); // throws on missing required / PUBLIC_ violation
+* ```
+*/
+function validateSchema(ctx) {
+	const { config, state } = ctx;
+	const { schema } = config;
+	const merged = mergeProviders(config);
+	crossCheckPublicPrefix(config);
+	for (const [key, spec] of Object.entries(schema)) {
+		if (merged[key] === void 0 && spec.default !== void 0) merged[key] = spec.default;
+		if (merged[key] === void 0 && spec.required === true) throw new Error(`${ERROR_PREFIX} env: required variable "${key}" is not defined by any provider or default.`);
+	}
+	populatePublicMap(schema, merged, state.publicMap);
+	populateResolved(merged, state.resolved);
+	freezeMap(state.resolved);
+	freezeMap(state.publicMap);
+}
+//#endregion
+//#region src/plugins/env/providers.browser.ts
+/** Default `globalThis` property holding a runtime-injected public-env snapshot. */
+const DEFAULT_GLOBAL_KEY = "__ENV__";
+/**
+* A browser-safe {@link EnvProvider} that reads `import.meta.env` and an optional
+* `globalThis[globalKey]` snapshot, merging them with the runtime global winning.
+* Contains zero `node:*` imports, so it is safe to include in the client bundle.
+* Never throws on missing sources — each absent source resolves to `{}`.
+*
+* @param options - Optional settings.
+* @param options.globalKey - `globalThis` key to read a public-env snapshot from. Defaults to `"__ENV__"`.
+* @returns An {@link EnvProvider} named `browser-env`.
+* @example
+* ```ts
+* const provider = browserEnv();
+* provider.load(); // { PUBLIC_API_URL: "/api", ... }
+* ```
+*/
+function browserEnv(options) {
+	const globalKey = options?.globalKey ?? DEFAULT_GLOBAL_KEY;
+	return {
+		name: "browser-env",
+		/**
+		* Merges `import.meta.env` with `globalThis[globalKey]`, the runtime global
+		* winning. Each absent source resolves to `{}`; never throws.
+		*
+		* @returns The merged environment record.
+		* @example
+		* ```ts
+		* browserEnv().load();
+		* ```
+		*/
+		load() {
+			const importEnv = {}.env ?? {};
+			const globalObject = globalThis[globalKey] ?? {};
+			return {
+				...importEnv,
+				...globalObject
+			};
+		}
+	};
+}
+/**
+* Core plugin that resolves, validates, and freezes the environment at `onInit`,
+* exposing a read-only accessor at `ctx.env`. No `onStart`/`onStop` — holds no resource.
+*
+* @example
+* ```ts
+* createApp({ pluginConfigs: { env: { schema: { PUBLIC_API_URL: { public: true } } } } });
+* ```
+*/
+const envPlugin = (0, _moku_labs_core.createCorePlugin)("env", {
+	config: {
+		schema: {},
+		providers: [],
+		publicPrefix: "PUBLIC_"
+	},
+	createState: createEnvState,
+	api: createEnvApi,
+	onInit: validateSchema
+});
+//#endregion
+//#region src/plugins/env/providers.ts
+/**
+* @file env plugin — built-in providers: dotenv, processEnv, cloudflareBindings.
+*/
+/** Default dotenv file path: optional local overrides. */
+const DEFAULT_DOTENV_PATH = ".env.local";
+/** Property on `globalThis` that the consumer sets per Cloudflare request. */
+const CLOUDFLARE_GLOBAL = "__CLOUDFLARE_ENV__";
+/** `String.indexOf` sentinel meaning "no `=` separator on this line". */
+const NO_SEPARATOR = -1;
+/**
+* Strips a single matching pair of surrounding double or single quotes from a
+* value. Leaves unquoted values (and trailing inline comments) untouched.
+*
+* @param value - The already-trimmed raw value.
+* @returns The value with one outer quote pair removed, if present.
+* @example
+* ```ts
+* stripQuotes('"a"'); // "a"
+* stripQuotes("plain # c"); // "plain # c"
+* ```
+*/
+function stripQuotes(value) {
+	if (value.length < 2) return value;
+	const first = value[0];
+	const last = value.at(-1);
+	if ((first === "\"" || first === "'") && first === last) return value.slice(1, -1);
+	return value;
+}
+/**
+* Reports whether a trimmed line carries no assignment — a blank line or a
+* full-line `#` comment — and should be skipped by the parser.
+*
+* @param trimmed - A whitespace-trimmed line from the dotenv text.
+* @returns `true` when the line is empty or a comment.
+* @example
+* ```ts
+* isIgnoredLine(""); // true
+* isIgnoredLine("# note"); // true
+* isIgnoredLine("A=1"); // false
+* ```
+*/
+function isIgnoredLine(trimmed) {
+	return trimmed === "" || trimmed.startsWith("#");
+}
+/**
+* Parses `.env`-style text into a flat record. Handles CRLF/LF, blank lines,
+* full-line `#` comments, first-`=` splitting, key/value trimming, and a single
+* outer quote pair. Does not strip trailing inline comments on unquoted values.
+*
+* @param text - The raw file contents.
+* @returns A flat record of parsed key/value pairs.
+* @example
+* ```ts
+* parseDotenv('A=1\nB="two"'); // { A: "1", B: "two" }
+* ```
+*/
+function parseDotenv(text) {
+	const out = {};
+	for (const line of text.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (isIgnoredLine(trimmed)) continue;
+		const eq = trimmed.indexOf("=");
+		if (eq === NO_SEPARATOR) continue;
+		const key = trimmed.slice(0, eq).trim();
+		out[key] = stripQuotes(trimmed.slice(eq + 1).trim());
+	}
+	return out;
+}
+/**
+* A zero-dependency `.env`-style provider that re-reads and re-parses the file
+* from disk on every `load()`. Missing file resolves to `{}` (optional
+* overrides). Strips a single outer quote pair; does not strip trailing inline
+* comments on unquoted values.
+*
+* @param path - Path to the dotenv file. Defaults to `.env.local`.
+* @returns An {@link EnvProvider} named `dotenv:<path>` that reads fresh per call.
+* @example
+* ```ts
+* const provider = dotenv(".env.local");
+* provider.load(); // { PUBLIC_API_URL: "/api", ... }
+* ```
+*/
+function dotenv(path = DEFAULT_DOTENV_PATH) {
+	return {
+		name: `dotenv:${path}`,
+		/**
+		* Reads and parses the dotenv file fresh from disk; `{}` if it is missing.
+		*
+		* @returns The parsed environment record, or `{}` when the file is absent.
+		* @example
+		* ```ts
+		* dotenv(".env.local").load();
+		* ```
+		*/
+		load() {
+			if (!(0, node_fs.existsSync)(path)) return {};
+			return parseDotenv((0, node_fs.readFileSync)(path, "utf8"));
+		}
+	};
+}
+/**
+* A provider that returns a shallow copy of `process.env` at `load()` time.
+*
+* @returns An {@link EnvProvider} named `process-env`.
+* @example
+* ```ts
+* const provider = processEnv();
+* provider.load().HOME; // current process value
+* ```
+*/
+function processEnv() {
+	return {
+		name: "process-env",
+		/**
+		* Returns a shallow copy of `process.env` at call time.
+		*
+		* @returns A fresh shallow copy of `process.env`.
+		* @example
+		* ```ts
+		* processEnv().load();
+		* ```
+		*/
+		load() {
+			return { ...process.env };
+		}
+	};
+}
+/**
+* A provider that reads live, per-request Cloudflare bindings from
+* `globalThis.__CLOUDFLARE_ENV__` at `load()` time (`?? {}` when absent). Never
+* caches the binding object; the consumer owns the global's request lifecycle.
+*
+* @returns An {@link EnvProvider} named `cloudflare`.
+* @example
+* ```ts
+* globalThis.__CLOUDFLARE_ENV__ = env; // set by the request handler
+* const provider = cloudflareBindings();
+* provider.load(); // reads the current request's bindings
+* ```
+*/
+function cloudflareBindings() {
+	return {
+		name: "cloudflare",
+		/**
+		* Reads `globalThis.__CLOUDFLARE_ENV__` fresh, never caching the bindings.
+		*
+		* @returns The current Cloudflare bindings, or `{}` when the global is unset.
+		* @example
+		* ```ts
+		* cloudflareBindings().load();
+		* ```
+		*/
+		load() {
+			return globalThis[CLOUDFLARE_GLOBAL] ?? {};
+		}
+	};
+}
+//#endregion
+//#region src/plugins/log/types.ts
+var types_exports$1 = /* @__PURE__ */ __exportAll({});
+//#endregion
+//#region src/plugins/env/types.ts
+var types_exports = /* @__PURE__ */ __exportAll({});
+//#endregion
+Object.defineProperty(exports, "Env", {
+	enumerable: true,
+	get: function() {
+		return types_exports;
+	}
+});
+Object.defineProperty(exports, "Log", {
+	enumerable: true,
+	get: function() {
+		return types_exports$1;
+	}
+});
+exports.browserEnv = browserEnv;
+exports.cloudflareBindings = cloudflareBindings;
+exports.dotenv = dotenv;
+exports.envPlugin = envPlugin;
+exports.logPlugin = logPlugin;
+exports.processEnv = processEnv;