@moku-labs/core 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -230,7 +230,7 @@ Every field is optional. A plugin with only `api` works. A plugin with only `hoo
 
 ## Design Principles
 
-**Brutal simplicity.** No classes. No decorators. No dependency injection. No inheritance. Every function is a pure factory: input → output.
+**Brutal simplicity.** No classes. No decorators. No dependency injection. No inheritance. `createCoreConfig`, `createCore`, and `createPlugin` are pure factories. `createApp()` performs synchronous init. `app.start()` / `app.stop()` run the runtime lifecycle.
 
 **Types over runtime.** Most of the codebase is type definitions and JSDoc. The type system provides autocomplete, compile-time validation, and documentation simultaneously.
 
@@ -268,13 +268,13 @@ Creates a plugin instance. Zero explicit generics — everything inferred from t
 
 ### createApp(options?)
 
-Merges framework defaults with consumer options. Validates, resolves config, runs `onInit`. Returns `App` — a frozen object with plugin APIs mounted as properties.
+Merges framework defaults with consumer options. Validates, resolves config, runs `onInit`, and returns `App` — a frozen object with plugin APIs mounted as properties. `createApp()` is synchronous and side-effectful within the init phase; it is not a lazy builder. `start()` / `stop()` are optional and mainly useful for apps with a distinct runtime phase. Lifecycle execution is non-transactional: start/stop errors propagate, they are not rolled back by the kernel.
 
 ### App
 
 ```typescript
-await app.start();            // onStart (forward order)
-await app.stop();             // onStop (reverse order)
+await app.start();            // optional: onStart (forward order)
+await app.stop();             // optional: onStop (reverse order)
 app.emit('event', payload);   // strictly typed, fire-and-forget
 app.require(plugin);          // returns typed API or throws
 app.has('name');              // boolean, never throws

package/dist/index.cjs

@@ -32,6 +32,8 @@ const RESERVED_NAMES = new Set([
 	"require",
 	"has",
 	"config",
+	"global",
+	"state",
 	"__proto__",
 	"constructor",
 	"prototype"
@@ -108,6 +110,37 @@ function validatePlugins(id, plugins) {
 	checkDuplicateNames(id, names);
 	checkDependencyOrder(id, plugins, names);
 }
+/**
+* Validate core plugins: no reserved names, no duplicates.
+*
+* @param id - Framework identifier for error messages.
+* @param corePlugins - The core plugin list to validate.
+* @throws {TypeError} If validation fails.
+* @example
+* ```ts
+* validateCorePlugins("my-site", [logPlugin, envPlugin]); // throws if invalid
+* ```
+*/
+function validateCorePlugins(id, corePlugins) {
+	const names = corePlugins.map((p) => p.name);
+	checkReservedNames(id, names);
+	checkDuplicateNames(id, names);
+}
+/**
+* Validate that no regular plugin name conflicts with a core plugin name.
+*
+* @param id - Framework identifier for error messages.
+* @param plugins - The regular plugin list.
+* @param corePluginNames - Set of core plugin names.
+* @throws {TypeError} If a name conflict is found.
+* @example
+* ```ts
+* checkCorePluginConflicts("my-site", [routerPlugin], new Set(["log", "env"]));
+* ```
+*/
+function checkCorePluginConflicts(id, plugins, corePluginNames) {
+	for (const plugin of plugins) if (corePluginNames.has(plugin.name)) throw new TypeError(`[${id}] Plugin name "${plugin.name}" conflicts with core plugin "${plugin.name}".\n  Choose a different plugin name.`);
+}
 
 //#endregion
 //#region src/app.ts
@@ -302,6 +335,7 @@ function registerPluginHooks(flatPlugins, buildPluginContext, registerHook) {
 * @param runtime - The kernel runtime with shared state.
 * @param resolvedConfigs - The resolved per-plugin config map.
 * @param states - The plugin state map.
+* @param coreApis - Core plugin APIs to spread onto every plugin context.
 * @returns A factory function that produces a PluginContext for any plugin.
 * @example
 * ```ts
@@ -309,7 +343,7 @@ function registerPluginHooks(flatPlugins, buildPluginContext, registerHook) {
 * const ctx = factory(routerPlugin);
 * ```
 */
-function createContextFactory(runtime, resolvedConfigs, states) {
+function createContextFactory(runtime, resolvedConfigs, states, coreApis) {
 	const has = createHas(runtime);
 	return (plugin) => ({
 		global: runtime.globalConfig,
@@ -317,7 +351,8 @@ function createContextFactory(runtime, resolvedConfigs, states) {
 		state: states.get(plugin.name),
 		emit: runtime.emit,
 		require: createRequire(runtime, (name) => `[${runtime.id}] Plugin "${plugin.name}" requires "${name}", but "${name}" is not registered.\n  Add "${name}" to your plugin list.`),
-		has
+		has,
+		...coreApis
 	});
 }
 /**
@@ -364,6 +399,10 @@ async function executeStop(flatPlugins, globalConfig) {
 * @param runtime - The kernel runtime with shared state and APIs.
 * @param flatPlugins - The flattened plugin list.
 * @param buildPluginContext - Factory that builds context for a plugin.
+* @param corePluginData - Core plugin instances, resolved configs, and states.
+* @param corePluginData.plugins - The core plugin instances.
+* @param corePluginData.configs - Resolved core plugin config map.
+* @param corePluginData.states - Core plugin state map.
 * @param consumer - Optional consumer lifecycle callbacks.
 * @returns A frozen app object with lifecycle methods and plugin APIs.
 * @example
@@ -372,13 +411,17 @@ async function executeStop(flatPlugins, globalConfig) {
 * await app.start();
 * ```
 */
-function buildApp(runtime, flatPlugins, buildPluginContext, consumer) {
+function buildApp(runtime, flatPlugins, buildPluginContext, corePluginData, consumer) {
 	let started = false;
 	const appRequire = createRequire(runtime, (name) => `[${runtime.id}] app.require("${name}") failed: "${name}" is not registered.\n  Check your plugin list.`);
 	const appHas = createHas(runtime);
 	const app = {
 		start: async () => {
 			if (started) throw new Error(`[${runtime.id}] App already started.\n  start() can only be called once.`);
+			for (const plugin of corePluginData.plugins) if (plugin.spec.onStart) await plugin.spec.onStart({
+				config: corePluginData.configs.get(plugin.name) ?? {},
+				state: corePluginData.states.get(plugin.name)
+			});
 			for (const plugin of flatPlugins) if (plugin.spec.onStart) await plugin.spec.onStart(buildPluginContext(plugin));
 			if (consumer?.onStart) await consumer.onStart(buildCallbackContext(runtime));
 			started = true;
@@ -386,6 +429,10 @@ function buildApp(runtime, flatPlugins, buildPluginContext, consumer) {
 		stop: async () => {
 			if (!started) throw new Error(`[${runtime.id}] App not started.\n  Call start() before stop().`);
 			await executeStop(flatPlugins, runtime.globalConfig);
+			for (const plugin of corePluginData.plugins.toReversed()) if (plugin.spec.onStop) await plugin.spec.onStop({
+				config: corePluginData.configs.get(plugin.name) ?? {},
+				state: corePluginData.states.get(plugin.name)
+			});
 			if (consumer?.onStop) await consumer.onStop(buildCallbackContext(runtime));
 		},
 		emit: (eventName, payload) => {
@@ -398,6 +445,59 @@ function buildApp(runtime, flatPlugins, buildPluginContext, consumer) {
 	return Object.freeze(app);
 }
 /**
+* Initialize core plugins: resolve configs, create states, build APIs, run onInit.
+*
+* @param corePlugins - Core plugin instances.
+* @param corePluginConfigs - Config overrides from createCoreConfig.
+* @param frameworkPluginConfigs - Config overrides from createCore.
+* @param consumerPluginConfigs - Config overrides from createApp.
+* @returns Resolved configs, states, core APIs map, and shared apis Map.
+* @example
+* ```ts
+* const { coreResolvedConfigs, coreStates, coreApis, apis } = initCorePlugins(
+*   corePlugins, corePluginConfigs, frameworkPluginConfigs, consumerPluginConfigs
+* );
+* ```
+*/
+function initCorePlugins(corePlugins, corePluginConfigs, frameworkPluginConfigs, consumerPluginConfigs) {
+	const coreResolvedConfigs = /* @__PURE__ */ new Map();
+	for (const plugin of corePlugins) {
+		const merged = Object.freeze({
+			...plugin.spec.config,
+			...asRecord(corePluginConfigs[plugin.name]),
+			...asRecord(frameworkPluginConfigs[plugin.name]),
+			...asRecord(consumerPluginConfigs[plugin.name])
+		});
+		coreResolvedConfigs.set(plugin.name, merged);
+	}
+	const coreStates = /* @__PURE__ */ new Map();
+	for (const plugin of corePlugins) if (plugin.spec.createState) {
+		const pluginConfig = coreResolvedConfigs.get(plugin.name) ?? {};
+		coreStates.set(plugin.name, plugin.spec.createState({ config: pluginConfig }));
+	} else coreStates.set(plugin.name, {});
+	const coreApis = {};
+	const apis = /* @__PURE__ */ new Map();
+	for (const plugin of corePlugins) if (plugin.spec.api) {
+		const context = {
+			config: coreResolvedConfigs.get(plugin.name) ?? {},
+			state: coreStates.get(plugin.name)
+		};
+		const api = plugin.spec.api(context);
+		coreApis[plugin.name] = api;
+		apis.set(plugin.name, api);
+	}
+	for (const plugin of corePlugins) if (plugin.spec.onInit) plugin.spec.onInit({
+		config: coreResolvedConfigs.get(plugin.name) ?? {},
+		state: coreStates.get(plugin.name)
+	});
+	return {
+		coreResolvedConfigs,
+		coreStates,
+		coreApis,
+		apis
+	};
+}
+/**
 * The kernel — creates and initializes the application.
 *
 * Receives pre-flattened, pre-validated plugins and all captured context from
@@ -412,15 +512,15 @@ function buildApp(runtime, flatPlugins, buildPluginContext, consumer) {
 * ```
 */
 function kernel(parameters) {
-	const { id, configDefaults, frameworkPluginConfigs, flatPlugins, configOverrides, consumerPluginConfigs, onReady, onError, consumer } = parameters;
-	const pluginNameSet = new Set(flatPlugins.map((plugin) => plugin.name));
+	const { id, configDefaults, frameworkPluginConfigs, flatPlugins, corePlugins, corePluginConfigs, configOverrides, consumerPluginConfigs, onReady, onError, consumer } = parameters;
+	const pluginNameSet = new Set([...corePlugins.map((plugin) => plugin.name), ...flatPlugins.map((plugin) => plugin.name)]);
 	const globalConfig = Object.freeze({
 		...configDefaults,
 		...configOverrides
 	});
+	const { coreResolvedConfigs, coreStates, coreApis, apis } = initCorePlugins(corePlugins, corePluginConfigs, frameworkPluginConfigs, consumerPluginConfigs);
 	const resolvedConfigs = resolvePluginConfigs(flatPlugins, frameworkPluginConfigs, consumerPluginConfigs);
 	const states = createPluginStates(flatPlugins, globalConfig, resolvedConfigs);
-	const apis = /* @__PURE__ */ new Map();
 	const { emit, registerHook } = buildEventBus(onError || consumer?.onError ? (error) => {
 		if (onError) onError(error);
 		if (consumer?.onError) consumer.onError(error, buildCallbackContext(runtime));
@@ -432,13 +532,17 @@ function kernel(parameters) {
 		apis,
 		pluginNameSet
 	};
-	const buildPluginContext = createContextFactory(runtime, resolvedConfigs, states);
+	const buildPluginContext = createContextFactory(runtime, resolvedConfigs, states, coreApis);
 	registerPluginHooks(flatPlugins, buildPluginContext, registerHook);
 	for (const plugin of flatPlugins) if (plugin.spec.api) apis.set(plugin.name, plugin.spec.api(buildPluginContext(plugin)));
 	for (const plugin of flatPlugins) if (plugin.spec.onInit) plugin.spec.onInit(buildPluginContext(plugin));
 	if (onReady) onReady({ config: globalConfig });
 	if (consumer?.onReady) consumer.onReady(buildCallbackContext(runtime));
-	return buildApp(runtime, flatPlugins, buildPluginContext, consumer);
+	return buildApp(runtime, flatPlugins, buildPluginContext, {
+		plugins: corePlugins,
+		configs: coreResolvedConfigs,
+		states: coreStates
+	}, consumer);
 }
 
 //#endregion
@@ -453,6 +557,8 @@ function kernel(parameters) {
 * @param frameworkId - The framework identifier for error messages.
 * @param configDefaults - Default config values captured from Step 1.
 * @param createPlugin - Bound createPlugin function from Step 1.
+* @param corePlugins - Core plugin instances from createCoreConfig.
+* @param corePluginConfigs - Core plugin config overrides from createCoreConfig.
 * @returns A createCore function bound to the framework's Config and Events types.
 * @example
 * ```ts
@@ -461,7 +567,7 @@ function kernel(parameters) {
 * );
 * ```
 */
-function createCoreFactory(frameworkId, configDefaults, createPlugin) {
+function createCoreFactory(frameworkId, configDefaults, createPlugin, corePlugins, corePluginConfigs) {
 	/**
 	* Step 2: Captures framework default plugins and returns createApp.
 	*
@@ -495,11 +601,14 @@ function createCoreFactory(frameworkId, configDefaults, createPlugin) {
 			const appOptions = consumerOptions ?? {};
 			const allPlugins = [...defaultPlugins, ...appOptions.plugins ?? []];
 			validatePlugins(frameworkId, allPlugins);
+			checkCorePluginConflicts(frameworkId, allPlugins, new Set(corePlugins.map((p) => p.name)));
 			return kernel({
 				id: frameworkId,
 				configDefaults,
 				frameworkPluginConfigs,
 				flatPlugins: allPlugins,
+				corePlugins,
+				corePluginConfigs,
 				configOverrides: appOptions.config ?? {},
 				consumerPluginConfigs: appOptions.pluginConfigs ?? {},
 				onReady,
@@ -692,6 +801,8 @@ function createPluginFactory(frameworkId) {
 * @param id - Framework identifier used in error messages.
 * @param options - Configuration options containing the default config values.
 * @param options.config - Default configuration values for the framework.
+* @param options.plugins - Optional core plugin instances to register.
+* @param options.pluginConfigs - Optional config overrides for core plugins.
 * @returns An object with createPlugin (bound to Config/Events) and createCore.
 * @example
 * ```ts
@@ -704,12 +815,137 @@ function createPluginFactory(frameworkId) {
 function createCoreConfig(id, options) {
 	const configDefaults = options.config;
 	const frameworkId = id;
+	const corePlugins = options.plugins ?? [];
+	const corePluginConfigs = options.pluginConfigs ?? {};
+	validateCorePlugins(frameworkId, corePlugins);
 	const createPlugin = createPluginFactory(frameworkId);
 	return {
 		createPlugin,
-		createCore: createCoreFactory(frameworkId, configDefaults, createPlugin)
+		createCore: createCoreFactory(frameworkId, configDefaults, createPlugin, corePlugins, corePluginConfigs)
+	};
+}
+
+//#endregion
+//#region src/core-plugin.ts
+/**
+* Reserved names that cannot be used for core plugins.
+* Includes regular reserved names plus context property names that would collide.
+*/
+const CORE_PLUGIN_RESERVED_NAMES = new Set([
+	"start",
+	"stop",
+	"emit",
+	"require",
+	"has",
+	"config",
+	"global",
+	"state",
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/** Fields that core plugins must not have. */
+const CORE_PLUGIN_FORBIDDEN_FIELDS = [
+	"depends",
+	"events",
+	"hooks"
+];
+/**
+* Asserts that a core plugin name is a non-empty string and not reserved.
+*
+* @param name - Candidate core plugin name.
+* @example
+* ```ts
+* assertValidCorePluginName("log"); // ok
+* assertValidCorePluginName("config"); // throws
+* ```
+*/
+function assertValidCorePluginName(name) {
+	if (typeof name !== "string" || name.length === 0) throw new TypeError("Core plugin name must be a non-empty string.\n  Pass a non-empty string as the first argument to createCorePlugin.");
+	if (CORE_PLUGIN_RESERVED_NAMES.has(name)) throw new TypeError(`Core plugin name "${name}" conflicts with a reserved name.\n  Choose a different core plugin name.`);
+}
+/**
+* Asserts that the core plugin spec is a non-null object.
+*
+* @param name - Validated core plugin name.
+* @param spec - Candidate core plugin spec.
+* @example
+* ```ts
+* assertValidCorePluginSpec("log", { api: () => ({}) }); // ok
+* ```
+*/
+function assertValidCorePluginSpec(name, spec) {
+	if (isRecord(spec)) return;
+	throw new TypeError(`Core plugin "${name}" has invalid spec: expected an object.\n  Provide a plugin specification object as the second argument.`);
+}
+/**
+* Asserts that the core plugin spec does not contain forbidden fields.
+*
+* @param name - Validated core plugin name.
+* @param spec - Validated core plugin spec.
+* @example
+* ```ts
+* assertNoCorePluginForbiddenFields("log", { api: () => ({}) }); // ok
+* assertNoCorePluginForbiddenFields("log", { depends: [] }); // throws
+* ```
+*/
+function assertNoCorePluginForbiddenFields(name, spec) {
+	for (const field of CORE_PLUGIN_FORBIDDEN_FIELDS) if (field in spec) throw new TypeError(`Core plugin "${name}" cannot have "${field}".\n  Core plugins are self-contained — remove the forbidden field.`);
+}
+/**
+* Validates lifecycle handlers and factories on a core plugin spec.
+*
+* @param name - Validated core plugin name.
+* @param spec - Validated core plugin spec.
+* @example
+* ```ts
+* assertValidCorePluginCallbacks("log", { api: () => ({}) }); // ok
+* ```
+*/
+function assertValidCorePluginCallbacks(name, spec) {
+	for (const field of [
+		"api",
+		"createState",
+		"onInit",
+		"onStart",
+		"onStop"
+	]) {
+		const value = spec[field];
+		if (value !== void 0 && typeof value !== "function") throw new TypeError(`Core plugin "${name}" has invalid ${field}: expected a function.\n  Provide a function for ${field} or remove it from the spec.`);
+	}
+}
+/**
+* Creates a core plugin instance. Core plugins are standalone, self-contained
+* infrastructure plugins (log, storage, env) whose APIs are injected directly
+* onto every regular plugin's context.
+*
+* @param name - Unique core plugin name (inferred as literal string type).
+* @param spec - Core plugin specification: config, createState, api, lifecycle.
+* @returns A CorePluginInstance carrying phantom types for compile-time inference.
+* @example
+* ```ts
+* const logPlugin = createCorePlugin("log", {
+*   config: { level: "info" },
+*   createState: () => ({ entries: [] as string[] }),
+*   api: ctx => ({
+*     info: (msg: string) => { ctx.state.entries.push(msg); console.log(msg); },
+*   }),
+* });
+* ```
+*/
+function createCorePlugin(name, spec) {
+	assertValidCorePluginName(name);
+	assertValidCorePluginSpec(name, spec);
+	assertNoCorePluginForbiddenFields(name, spec);
+	assertValidCorePluginCallbacks(name, spec);
+	return {
+		name,
+		spec,
+		_corePlugin: true,
+		_phantom: {}
 	};
 }
 
 //#endregion
-exports.createCoreConfig = createCoreConfig;
+exports.createCoreConfig = createCoreConfig;
+exports.createCorePlugin = createCorePlugin;