@moku-labs/core 0.1.0-alpha.6 → 0.1.2

package/README.md

@@ -2,7 +2,7 @@
 
 **Micro-kernel plugin framework for TypeScript. Three layers of isolation. Built for LLM-scale development.**
 
-One runtime export. Bundle < 5KB. Zero dependencies. The type system does the heavy lifting.
+Two runtime exports. Bundle < 8KB gzipped. Zero dependencies. The type system does the heavy lifting.
 
 ```
 bun add @moku-labs/core
@@ -33,7 +33,7 @@ Moku enforces a 3-layer architecture where each layer physically constrains the
 │  Cannot: modify the kernel                              │
 ├─────────────────────────────────────────────────────────┤
 │  Layer 1: @moku-labs/core                               │
-│  One function. Zero domain knowledge. Pure machinery.   │
+│  Two functions. Zero domain knowledge. Pure machinery.  │
 └─────────────────────────────────────────────────────────┘
 ```
 
@@ -122,7 +122,7 @@ app.blog.listPosts();           // fully typed
 await app.stop();
 ```
 
-**That's the entire API.** `createCoreConfig` → `createCore` → `createApp`. Three functions, three layers.
+**That's the entire factory chain.** `createCoreConfig` → `createCore` → `createApp`. Three functions, three layers. (A second runtime export, `createCorePlugin`, builds self-contained infrastructure plugins — see the API reference below.)
 
 ---
 
@@ -171,7 +171,7 @@ Moku is designed for a world where LLMs write plugins and CI enforces quality. T
 
 - **Strict emit** — only known event names compile. Wrong payloads are type errors. No `any`, no escape hatch.
 - **Phantom types** — plugin APIs, configs, and events flow through the type system without runtime cost.
-- **Required configs** — if a plugin needs config and you don't provide it, TypeScript tells you.
+- **Typed plugin configs** — `pluginConfigs` overrides are checked against each plugin's declared config shape. Wrong keys or value types don't compile. Overrides are optional — plugin defaults fill anything you omit.
 - **Context tiers** — `createState` can't call `emit` (other plugins don't exist yet). `onStop` can't access other plugins (they may already be stopped). The type system prevents temporal bugs.
 
 ### Runtime guarantees
@@ -248,7 +248,7 @@ Every field is optional. A plugin with only `api` works. A plugin with only `hoo
 
 ```typescript
 // Runtime
-import { createCoreConfig } from '@moku-labs/core';
+import { createCoreConfig, createCorePlugin } from '@moku-labs/core';
 
 // Type utilities for plugin authors
 import type { PluginCtx, EmitFn } from '@moku-labs/core';
@@ -258,6 +258,10 @@ import type { PluginCtx, EmitFn } from '@moku-labs/core';
 
 Creates a bound factory chain for a framework. Returns `{ createPlugin, createCore }`, both locked to `Config` and `Events`.
 
+### createCorePlugin(name, spec)
+
+Creates a self-contained infrastructure plugin (logging, env, storage). Core plugins are passed to `createCoreConfig` via `plugins`, and their APIs are injected onto every regular plugin's context (`ctx.log.info(...)`). No `depends`, no `events`, no `hooks` — a minimal `{ config, state }` context only.
+
 ### createCore(coreConfig, options)
 
 Captures framework defaults: plugins, plugin configs, `onReady`, `onError`. Returns `{ createApp, createPlugin }`.
@@ -308,7 +312,7 @@ The full specification lives in [`specification/`](specification/):
 
 ## Status
 
-Alpha. API is stabilizing. Not yet published to npm.
+Early release (`0.1.x`). The public API — `createCoreConfig` → `createCore` → `createApp` — is stable; pre-1.0 means internals may still be refined. Published to npm: `bun add @moku-labs/core`.
 
 ## License
 

package/dist/index.cjs

@@ -1,5 +1,4 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/utilities.ts
 /**
 * Checks whether a value is a non-null, non-array object record.
@@ -141,7 +140,6 @@ function validateCorePlugins(id, corePlugins) {
 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
 /**
@@ -158,10 +156,16 @@ function checkCorePluginConflicts(id, plugins, corePluginNames) {
 function asRecord(value) {
 	return isRecord(value) ? value : {};
 }
+/** Shared frozen API for registered plugins that declare no api(). */
+const EMPTY_API = Object.freeze({});
 /**
 * Create a require function that looks up a plugin API by instance reference.
 *
-* @param runtime - The kernel runtime containing the API map.
+* Registered plugins without an api() resolve to a frozen empty object —
+* matching the type contract (ExtractApi = Record<string, never>) and
+* agreeing with has(). Only genuinely unregistered plugins throw.
+*
+* @param runtime - The kernel runtime containing the API map and name set.
 * @param formatError - Formats the error message using the plugin instance name.
 * @returns A function that returns the API for a given plugin instance or throws.
 * @example
@@ -173,8 +177,9 @@ function asRecord(value) {
 function createRequire(runtime, formatError) {
 	return (instance) => {
 		const api = runtime.apis.get(instance.name);
-		if (!api) throw new Error(formatError(instance.name));
-		return api;
+		if (api) return api;
+		if (runtime.pluginNameSet.has(instance.name)) return EMPTY_API;
+		throw new Error(formatError(instance.name));
 	};
 }
 /**
@@ -270,7 +275,9 @@ function buildEventBus(onError) {
 		for (const handler of handlers) try {
 			await handler(payload);
 		} catch (error) {
-			if (onError) onError(error);
+			try {
+				if (onError) onError(error);
+			} catch {}
 		}
 	}
 	/**
@@ -416,6 +423,14 @@ function buildApp(runtime, flatPlugins, buildPluginContext, corePluginData, cons
 	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 = {
+		/**
+		* Run onStart for all plugins, then consumer onStart.
+		*
+		* @example
+		* ```ts
+		* await app.start();
+		* ```
+		*/
 		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({
@@ -426,6 +441,14 @@ function buildApp(runtime, flatPlugins, buildPluginContext, corePluginData, cons
 			if (consumer?.onStart) await consumer.onStart(buildCallbackContext(runtime));
 			started = true;
 		},
+		/**
+		* Run onStop for all plugins in reverse, then consumer onStop.
+		*
+		* @example
+		* ```ts
+		* await app.stop();
+		* ```
+		*/
 		stop: async () => {
 			if (!started) throw new Error(`[${runtime.id}] App not started.\n  Call start() before stop().`);
 			await executeStop(flatPlugins, runtime.globalConfig);
@@ -435,10 +458,40 @@ function buildApp(runtime, flatPlugins, buildPluginContext, corePluginData, cons
 			});
 			if (consumer?.onStop) await consumer.onStop(buildCallbackContext(runtime));
 		},
+		/**
+		* Emit an event with an optional payload.
+		*
+		* @param eventName - The event name to emit.
+		* @param payload - The optional event payload.
+		* @example
+		* ```ts
+		* app.emit("page:view", { path: "/" });
+		* ```
+		*/
 		emit: (eventName, payload) => {
 			runtime.emit(eventName, payload);
 		},
+		/**
+		* Look up a plugin API by instance reference.
+		*
+		* @param instance - The plugin instance to look up.
+		* @returns The plugin's API object.
+		* @example
+		* ```ts
+		* const routerApi = app.require(routerPlugin);
+		* ```
+		*/
 		require: (instance) => appRequire(instance),
+		/**
+		* Check if a plugin name is registered.
+		*
+		* @param name - The plugin name to check.
+		* @returns True if the plugin is registered.
+		* @example
+		* ```ts
+		* app.has("router"); // => true or false
+		* ```
+		*/
 		has: (name) => appHas(name)
 	};
 	for (const [name, api] of runtime.apis) app[name] = api;
@@ -522,7 +575,9 @@ function kernel(parameters) {
 	const resolvedConfigs = resolvePluginConfigs(flatPlugins, frameworkPluginConfigs, consumerPluginConfigs);
 	const states = createPluginStates(flatPlugins, globalConfig, resolvedConfigs);
 	const { emit, registerHook } = buildEventBus(onError || consumer?.onError ? (error) => {
-		if (onError) onError(error);
+		try {
+			if (onError) onError(error);
+		} catch {}
 		if (consumer?.onError) consumer.onError(error, buildCallbackContext(runtime));
 	} : void 0);
 	const runtime = {
@@ -544,7 +599,6 @@ function kernel(parameters) {
 		states: coreStates
 	}, consumer);
 }
-
 //#endregion
 //#region src/core.ts
 /**
@@ -628,7 +682,6 @@ function createCoreFactory(frameworkId, configDefaults, createPlugin, corePlugin
 	};
 	return createCore;
 }
-
 //#endregion
 //#region src/plugin.ts
 /**
@@ -816,7 +869,6 @@ function createPluginFactory(frameworkId) {
 	};
 	return createPlugin;
 }
-
 //#endregion
 //#region src/config.ts
 /**
@@ -852,7 +904,6 @@ function createCoreConfig(id, options) {
 		createCore: createCoreFactory(frameworkId, configDefaults, createPlugin, corePlugins, corePluginConfigs)
 	};
 }
-
 //#endregion
 //#region src/core-plugin.ts
 /**
@@ -973,7 +1024,6 @@ function createCorePlugin(name, spec) {
 		_phantom: {}
 	};
 }
-
 //#endregion
 exports.createCoreConfig = createCoreConfig;
-exports.createCorePlugin = createCorePlugin;
+exports.createCorePlugin = createCorePlugin;

package/dist/index.d.cts

@@ -953,14 +953,14 @@ type BoundCreatePluginFunction<GlobalConfig extends FrameworkConfig, GlobalEvent
 */
 interface CreateCoreOptions<Config> {
   /** Framework default plugins. */
-  readonly plugins: AnyPluginInstance[];
+  readonly plugins: readonly AnyPluginInstance[];
   /** Framework-level plugin config overrides keyed by plugin name. */
   readonly pluginConfigs?: Record<string, unknown>;
   /** Called after all plugins are initialized. */
   readonly onReady?: (context: {
     config: Readonly<Config>;
   }) => void;
-  /** Error handler for hook dispatch and teardown failures. */
+  /** Error handler for hook dispatch failures. Lifecycle errors from start()/stop() propagate to the caller instead. */
   readonly onError?: (error: Error) => void;
 }
 /**
@@ -996,7 +996,7 @@ interface CreateCoreResult<Config extends Record<string, unknown>, Events extend
 type BoundCreateCoreFunction<Config extends Record<string, unknown>, Events extends Record<string, unknown>, CorePlugins extends readonly AnyCorePluginInstance[] = readonly []> = <const Plugins extends readonly AnyPluginInstance[]>(coreConfig: {
   readonly createPlugin: BoundCreatePluginFunction<Config, Events, CoreApisFromTuple<CorePlugins>>;
 }, options: CreateCoreOptions<Config> & {
-  readonly plugins: [...Plugins];
+  readonly plugins: readonly [...Plugins];
 }) => CreateCoreResult<Config, Events, Plugins, CorePlugins>;
 /**
 * Creates a bound `createCore` function that captures framework context.
@@ -1055,7 +1055,7 @@ interface CoreConfigResult<Config extends Record<string, unknown>, Events extend
 * const { createPlugin, createCore } = coreConfig;
 * ```
 */
-declare function createCoreConfig<Config extends Record<string, unknown>, Events extends Record<string, unknown> = Record<string, never>, const CorePlugins extends readonly AnyCorePluginInstance[] = readonly []>(id: string, options: {
+declare function createCoreConfig<Config extends Record<string, unknown>, Events extends Record<string, unknown> = EmptyPluginEventMap, const CorePlugins extends readonly AnyCorePluginInstance[] = readonly []>(id: string, options: {
   config: Config;
   plugins?: [...CorePlugins];
   pluginConfigs?: { [K in CorePlugins[number] as ExtractCoreConfig<K> extends Record<string, never> ? never : IsLiteralString<ExtractCoreName<K>> extends true ? ExtractCoreName<K> : never]?: Partial<ExtractCoreConfig<K>> };

package/dist/index.d.mts

@@ -953,14 +953,14 @@ type BoundCreatePluginFunction<GlobalConfig extends FrameworkConfig, GlobalEvent
 */
 interface CreateCoreOptions<Config> {
   /** Framework default plugins. */
-  readonly plugins: AnyPluginInstance[];
+  readonly plugins: readonly AnyPluginInstance[];
   /** Framework-level plugin config overrides keyed by plugin name. */
   readonly pluginConfigs?: Record<string, unknown>;
   /** Called after all plugins are initialized. */
   readonly onReady?: (context: {
     config: Readonly<Config>;
   }) => void;
-  /** Error handler for hook dispatch and teardown failures. */
+  /** Error handler for hook dispatch failures. Lifecycle errors from start()/stop() propagate to the caller instead. */
   readonly onError?: (error: Error) => void;
 }
 /**
@@ -996,7 +996,7 @@ interface CreateCoreResult<Config extends Record<string, unknown>, Events extend
 type BoundCreateCoreFunction<Config extends Record<string, unknown>, Events extends Record<string, unknown>, CorePlugins extends readonly AnyCorePluginInstance[] = readonly []> = <const Plugins extends readonly AnyPluginInstance[]>(coreConfig: {
   readonly createPlugin: BoundCreatePluginFunction<Config, Events, CoreApisFromTuple<CorePlugins>>;
 }, options: CreateCoreOptions<Config> & {
-  readonly plugins: [...Plugins];
+  readonly plugins: readonly [...Plugins];
 }) => CreateCoreResult<Config, Events, Plugins, CorePlugins>;
 /**
 * Creates a bound `createCore` function that captures framework context.
@@ -1055,7 +1055,7 @@ interface CoreConfigResult<Config extends Record<string, unknown>, Events extend
 * const { createPlugin, createCore } = coreConfig;
 * ```
 */
-declare function createCoreConfig<Config extends Record<string, unknown>, Events extends Record<string, unknown> = Record<string, never>, const CorePlugins extends readonly AnyCorePluginInstance[] = readonly []>(id: string, options: {
+declare function createCoreConfig<Config extends Record<string, unknown>, Events extends Record<string, unknown> = EmptyPluginEventMap, const CorePlugins extends readonly AnyCorePluginInstance[] = readonly []>(id: string, options: {
   config: Config;
   plugins?: [...CorePlugins];
   pluginConfigs?: { [K in CorePlugins[number] as ExtractCoreConfig<K> extends Record<string, never> ? never : IsLiteralString<ExtractCoreName<K>> extends true ? ExtractCoreName<K> : never]?: Partial<ExtractCoreConfig<K>> };

package/dist/index.mjs

@@ -139,7 +139,6 @@ function validateCorePlugins(id, corePlugins) {
 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
 /**
@@ -156,10 +155,16 @@ function checkCorePluginConflicts(id, plugins, corePluginNames) {
 function asRecord(value) {
 	return isRecord(value) ? value : {};
 }
+/** Shared frozen API for registered plugins that declare no api(). */
+const EMPTY_API = Object.freeze({});
 /**
 * Create a require function that looks up a plugin API by instance reference.
 *
-* @param runtime - The kernel runtime containing the API map.
+* Registered plugins without an api() resolve to a frozen empty object —
+* matching the type contract (ExtractApi = Record<string, never>) and
+* agreeing with has(). Only genuinely unregistered plugins throw.
+*
+* @param runtime - The kernel runtime containing the API map and name set.
 * @param formatError - Formats the error message using the plugin instance name.
 * @returns A function that returns the API for a given plugin instance or throws.
 * @example
@@ -171,8 +176,9 @@ function asRecord(value) {
 function createRequire(runtime, formatError) {
 	return (instance) => {
 		const api = runtime.apis.get(instance.name);
-		if (!api) throw new Error(formatError(instance.name));
-		return api;
+		if (api) return api;
+		if (runtime.pluginNameSet.has(instance.name)) return EMPTY_API;
+		throw new Error(formatError(instance.name));
 	};
 }
 /**
@@ -268,7 +274,9 @@ function buildEventBus(onError) {
 		for (const handler of handlers) try {
 			await handler(payload);
 		} catch (error) {
-			if (onError) onError(error);
+			try {
+				if (onError) onError(error);
+			} catch {}
 		}
 	}
 	/**
@@ -414,6 +422,14 @@ function buildApp(runtime, flatPlugins, buildPluginContext, corePluginData, cons
 	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 = {
+		/**
+		* Run onStart for all plugins, then consumer onStart.
+		*
+		* @example
+		* ```ts
+		* await app.start();
+		* ```
+		*/
 		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({
@@ -424,6 +440,14 @@ function buildApp(runtime, flatPlugins, buildPluginContext, corePluginData, cons
 			if (consumer?.onStart) await consumer.onStart(buildCallbackContext(runtime));
 			started = true;
 		},
+		/**
+		* Run onStop for all plugins in reverse, then consumer onStop.
+		*
+		* @example
+		* ```ts
+		* await app.stop();
+		* ```
+		*/
 		stop: async () => {
 			if (!started) throw new Error(`[${runtime.id}] App not started.\n  Call start() before stop().`);
 			await executeStop(flatPlugins, runtime.globalConfig);
@@ -433,10 +457,40 @@ function buildApp(runtime, flatPlugins, buildPluginContext, corePluginData, cons
 			});
 			if (consumer?.onStop) await consumer.onStop(buildCallbackContext(runtime));
 		},
+		/**
+		* Emit an event with an optional payload.
+		*
+		* @param eventName - The event name to emit.
+		* @param payload - The optional event payload.
+		* @example
+		* ```ts
+		* app.emit("page:view", { path: "/" });
+		* ```
+		*/
 		emit: (eventName, payload) => {
 			runtime.emit(eventName, payload);
 		},
+		/**
+		* Look up a plugin API by instance reference.
+		*
+		* @param instance - The plugin instance to look up.
+		* @returns The plugin's API object.
+		* @example
+		* ```ts
+		* const routerApi = app.require(routerPlugin);
+		* ```
+		*/
 		require: (instance) => appRequire(instance),
+		/**
+		* Check if a plugin name is registered.
+		*
+		* @param name - The plugin name to check.
+		* @returns True if the plugin is registered.
+		* @example
+		* ```ts
+		* app.has("router"); // => true or false
+		* ```
+		*/
 		has: (name) => appHas(name)
 	};
 	for (const [name, api] of runtime.apis) app[name] = api;
@@ -520,7 +574,9 @@ function kernel(parameters) {
 	const resolvedConfigs = resolvePluginConfigs(flatPlugins, frameworkPluginConfigs, consumerPluginConfigs);
 	const states = createPluginStates(flatPlugins, globalConfig, resolvedConfigs);
 	const { emit, registerHook } = buildEventBus(onError || consumer?.onError ? (error) => {
-		if (onError) onError(error);
+		try {
+			if (onError) onError(error);
+		} catch {}
 		if (consumer?.onError) consumer.onError(error, buildCallbackContext(runtime));
 	} : void 0);
 	const runtime = {
@@ -542,7 +598,6 @@ function kernel(parameters) {
 		states: coreStates
 	}, consumer);
 }
-
 //#endregion
 //#region src/core.ts
 /**
@@ -626,7 +681,6 @@ function createCoreFactory(frameworkId, configDefaults, createPlugin, corePlugin
 	};
 	return createCore;
 }
-
 //#endregion
 //#region src/plugin.ts
 /**
@@ -814,7 +868,6 @@ function createPluginFactory(frameworkId) {
 	};
 	return createPlugin;
 }
-
 //#endregion
 //#region src/config.ts
 /**
@@ -850,7 +903,6 @@ function createCoreConfig(id, options) {
 		createCore: createCoreFactory(frameworkId, configDefaults, createPlugin, corePlugins, corePluginConfigs)
 	};
 }
-
 //#endregion
 //#region src/core-plugin.ts
 /**
@@ -971,6 +1023,5 @@ function createCorePlugin(name, spec) {
 		_phantom: {}
 	};
 }
-
 //#endregion
-export { createCoreConfig, createCorePlugin };
+export { createCoreConfig, createCorePlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/core",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.2",
   "author": "Alex Kucherenko",
   "repository": {
     "type": "git",
@@ -23,9 +23,9 @@
     "jiti": "2.6.1",
     "lefthook": "2.1.1",
     "publint": "0.3.17",
-    "tsdown": "0.20.3",
-    "typescript": "5.9.3",
-    "typescript-eslint": "8.56.0",
+    "tsdown": "0.22.1",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.58.0",
     "vitest": "4.0.18"
   },
   "exports": {
@@ -40,6 +40,7 @@
       }
     }
   },
+  "sideEffects": false,
   "bugs": {
     "url": "https://github.com/moku-labs/core/issues"
   },