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

package/README.md

@@ -110,7 +110,7 @@ export const { createApp, createPlugin } = framework;
 // my-app/main.ts
 import { createApp } from 'my-framework';
 
-const app = await createApp({
+const app = createApp({
   plugins: [blogPlugin],
   config: { siteName: 'My Blog', mode: 'production' },
   pluginConfigs: { router: { basePath: '/blog' } },
@@ -218,7 +218,7 @@ createPlugin('name', {
   createState: ctx => ({ /* mutable state */ }),
   api:         ctx => ({ /* public methods, mounted on app.name */ }),
   hooks:       ctx => ({ 'event:name': handler }),
-  onInit:      async ctx => { /* all plugins exist */ },
+  onInit:      ctx => { /* all plugins exist, sync only */ },
   onStart:     async ctx => { /* app is running */ },
   onStop:      async ctx => { /* teardown, reverse order */ },
 });
@@ -268,7 +268,7 @@ 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 `Promise<App>` — a frozen object with plugin APIs mounted as properties.
+Merges framework defaults with consumer options. Validates, resolves config, runs `onInit`. Returns `App` — a frozen object with plugin APIs mounted as properties.
 
 ### App
 

package/dist/index.cjs

@@ -405,13 +405,13 @@ function buildApp(runtime, flatPlugins, buildPluginContext, consumer) {
 * API building, lifecycle execution, returns frozen app object.
 *
 * @param parameters - All kernel inputs captured from the factory chain.
-* @returns A promise that resolves to the frozen app object.
+* @returns The frozen app object.
 * @example
 * ```ts
 * const app = await kernel({ id: "my-app", configDefaults: {}, ... });
 * ```
 */
-async function kernel(parameters) {
+function kernel(parameters) {
 	const { id, configDefaults, frameworkPluginConfigs, flatPlugins, configOverrides, consumerPluginConfigs, onReady, onError, consumer } = parameters;
 	const pluginNameSet = new Set(flatPlugins.map((plugin) => plugin.name));
 	const globalConfig = Object.freeze({
@@ -435,9 +435,9 @@ async function kernel(parameters) {
 	const buildPluginContext = createContextFactory(runtime, resolvedConfigs, states);
 	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) await plugin.spec.onInit(buildPluginContext(plugin));
-	if (onReady) await onReady({ config: globalConfig });
-	if (consumer?.onReady) await consumer.onReady(buildCallbackContext(runtime));
+	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);
 }
 
@@ -485,13 +485,13 @@ function createCoreFactory(frameworkId, configDefaults, createPlugin) {
 		* plugins, then delegates to the kernel for lifecycle execution.
 		*
 		* @param consumerOptions - Consumer-level config, plugins, and callbacks.
-		* @returns A promise that resolves to the frozen App object.
+		* @returns The frozen App object.
 		* @example
 		* ```ts
-		* const app = await createApp({ config: { siteName: "Blog" } });
+		* const app = createApp({ config: { siteName: "Blog" } });
 		* ```
 		*/
-		const createApp = async (consumerOptions) => {
+		const createApp = (consumerOptions) => {
 			const appOptions = consumerOptions ?? {};
 			const allPlugins = [...defaultPlugins, ...appOptions.plugins ?? []];
 			validatePlugins(frameworkId, allPlugins);

package/dist/index.d.cts

@@ -221,7 +221,7 @@ type PluginSpec<Config, Events extends Record<string, unknown>, PluginEvents ext
   depends?: Deps;
   createState?: (context: MinimalContext<Config, C>) => S;
   api?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => A;
-  onInit?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => void | Promise<void>;
+  onInit?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => void;
   onStart?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => void | Promise<void>;
   onStop?: (context: TeardownContext<Config>) => void | Promise<void>;
   hooks?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => { [K in string & keyof (Events & PluginEvents & DepsEvents<Deps>)]?: (payload: (Events & PluginEvents & DepsEvents<Deps>)[K]) => void | Promise<void> };
@@ -378,7 +378,7 @@ type AppCallbackContext<Config extends Record<string, unknown>, Events extends R
 *
 * @example
 * ```ts
-* const app = await createApp({
+* const app = createApp({
 *   config: { siteName: "My Blog" },
 *   pluginConfigs: { router: { basePath: "/blog" } },
 *   onReady: ctx => { console.log("App ready:", ctx.config.siteName); },
@@ -389,7 +389,7 @@ type CreateAppOptions<Config extends Record<string, unknown>, Events extends Rec
   plugins?: ExtraPlugins;
   config?: { [K in keyof Config]?: Config[K] };
   pluginConfigs?: { [K in P as ExtractConfig<K> extends Record<string, never> ? never : IsLiteralString<ExtractName<K>> extends true ? ExtractName<K> : never]?: Partial<ExtractConfig<K>> };
-  onReady?: (context: AppCallbackContext<Config, Events, P>) => void | Promise<void>;
+  onReady?: (context: AppCallbackContext<Config, Events, P>) => void;
   onError?: (error: Error, context: AppCallbackContext<Config, Events, P>) => void;
   onStart?: (context: AppCallbackContext<Config, Events, P>) => void | Promise<void>;
   onStop?: (context: AppCallbackContext<Config, Events, P>) => void | Promise<void>;
@@ -699,7 +699,8 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
   api?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => PluginApi;
   /**
   * Called after all plugins are registered and APIs are built. Runs in forward
-  * plugin order, sequentially awaited. Use for setup that depends on other plugins.
+  * plugin order, synchronously. Use for setup that depends on other plugins.
+  * For async initialization, use `onStart` instead.
   *
   * @example
   * ```ts
@@ -709,7 +710,7 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
   * }
   * ```
   */
-  onInit?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => void | Promise<void>;
+  onInit?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => void;
   /**
   * Called when the app starts. Runs in forward plugin order, sequentially awaited.
   * Use for runtime startup (open connections, start listeners).
@@ -801,7 +802,7 @@ interface CreateCoreOptions<Config> {
   /** Called after all plugins are initialized. */
   readonly onReady?: (context: {
     config: Readonly<Config>;
-  }) => void | Promise<void>;
+  }) => void;
   /** Error handler for hook dispatch and teardown failures. */
   readonly onError?: (error: Error) => void;
 }
@@ -820,9 +821,9 @@ interface CreateCoreResult<Config extends Record<string, unknown>, Events extend
   * Generic over ExtraPlugins to merge consumer plugins into the return type.
   *
   * @param options - Consumer-level config overrides, plugin configs, extra plugins.
-  * @returns A promise that resolves to the frozen, fully typed App object.
+  * @returns The frozen, fully typed App object.
   */
-  readonly createApp: <const ExtraPlugins extends readonly AnyPluginInstance[] = readonly []>(options?: CreateAppOptions<Config, Events, Plugins[number] | ExtraPlugins[number], [...ExtraPlugins]>) => Promise<App<Config, Events, Plugins[number] | ExtraPlugins[number]>>;
+  readonly createApp: <const ExtraPlugins extends readonly AnyPluginInstance[] = readonly []>(options?: CreateAppOptions<Config, Events, Plugins[number] | ExtraPlugins[number], [...ExtraPlugins]>) => App<Config, Events, Plugins[number] | ExtraPlugins[number]>;
   /** Re-exported createPlugin for consumer convenience. */
   readonly createPlugin: BoundCreatePluginFunction<Config, Events>;
 }
@@ -897,4 +898,4 @@ declare function createCoreConfig<Config extends Record<string, unknown>, Events
   config: Config;
 }): CoreConfigResult<Config, Events>;
 //#endregion
-export { type EmitFunction as EmitFn, type PluginContext_ as PluginCtx, createCoreConfig };
+export { type AnyPluginInstance, type App, type BoundCreateCoreFunction, type BoundCreatePluginFunction, type CoreConfigResult, type CreateAppOptions, type CreateCoreOptions, type CreateCoreResult, type EmitFunction as EmitFn, type PluginContext_ as PluginCtx, type PluginInstance, createCoreConfig };

package/dist/index.d.mts

@@ -221,7 +221,7 @@ type PluginSpec<Config, Events extends Record<string, unknown>, PluginEvents ext
   depends?: Deps;
   createState?: (context: MinimalContext<Config, C>) => S;
   api?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => A;
-  onInit?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => void | Promise<void>;
+  onInit?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => void;
   onStart?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => void | Promise<void>;
   onStop?: (context: TeardownContext<Config>) => void | Promise<void>;
   hooks?: (context: PluginContext<Config, Events & PluginEvents & DepsEvents<Deps>, C, S>) => { [K in string & keyof (Events & PluginEvents & DepsEvents<Deps>)]?: (payload: (Events & PluginEvents & DepsEvents<Deps>)[K]) => void | Promise<void> };
@@ -378,7 +378,7 @@ type AppCallbackContext<Config extends Record<string, unknown>, Events extends R
 *
 * @example
 * ```ts
-* const app = await createApp({
+* const app = createApp({
 *   config: { siteName: "My Blog" },
 *   pluginConfigs: { router: { basePath: "/blog" } },
 *   onReady: ctx => { console.log("App ready:", ctx.config.siteName); },
@@ -389,7 +389,7 @@ type CreateAppOptions<Config extends Record<string, unknown>, Events extends Rec
   plugins?: ExtraPlugins;
   config?: { [K in keyof Config]?: Config[K] };
   pluginConfigs?: { [K in P as ExtractConfig<K> extends Record<string, never> ? never : IsLiteralString<ExtractName<K>> extends true ? ExtractName<K> : never]?: Partial<ExtractConfig<K>> };
-  onReady?: (context: AppCallbackContext<Config, Events, P>) => void | Promise<void>;
+  onReady?: (context: AppCallbackContext<Config, Events, P>) => void;
   onError?: (error: Error, context: AppCallbackContext<Config, Events, P>) => void;
   onStart?: (context: AppCallbackContext<Config, Events, P>) => void | Promise<void>;
   onStop?: (context: AppCallbackContext<Config, Events, P>) => void | Promise<void>;
@@ -699,7 +699,8 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
   api?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => PluginApi;
   /**
   * Called after all plugins are registered and APIs are built. Runs in forward
-  * plugin order, sequentially awaited. Use for setup that depends on other plugins.
+  * plugin order, synchronously. Use for setup that depends on other plugins.
+  * For async initialization, use `onStart` instead.
   *
   * @example
   * ```ts
@@ -709,7 +710,7 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
   * }
   * ```
   */
-  onInit?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => void | Promise<void>;
+  onInit?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState>) => void;
   /**
   * Called when the app starts. Runs in forward plugin order, sequentially awaited.
   * Use for runtime startup (open connections, start listeners).
@@ -801,7 +802,7 @@ interface CreateCoreOptions<Config> {
   /** Called after all plugins are initialized. */
   readonly onReady?: (context: {
     config: Readonly<Config>;
-  }) => void | Promise<void>;
+  }) => void;
   /** Error handler for hook dispatch and teardown failures. */
   readonly onError?: (error: Error) => void;
 }
@@ -820,9 +821,9 @@ interface CreateCoreResult<Config extends Record<string, unknown>, Events extend
   * Generic over ExtraPlugins to merge consumer plugins into the return type.
   *
   * @param options - Consumer-level config overrides, plugin configs, extra plugins.
-  * @returns A promise that resolves to the frozen, fully typed App object.
+  * @returns The frozen, fully typed App object.
   */
-  readonly createApp: <const ExtraPlugins extends readonly AnyPluginInstance[] = readonly []>(options?: CreateAppOptions<Config, Events, Plugins[number] | ExtraPlugins[number], [...ExtraPlugins]>) => Promise<App<Config, Events, Plugins[number] | ExtraPlugins[number]>>;
+  readonly createApp: <const ExtraPlugins extends readonly AnyPluginInstance[] = readonly []>(options?: CreateAppOptions<Config, Events, Plugins[number] | ExtraPlugins[number], [...ExtraPlugins]>) => App<Config, Events, Plugins[number] | ExtraPlugins[number]>;
   /** Re-exported createPlugin for consumer convenience. */
   readonly createPlugin: BoundCreatePluginFunction<Config, Events>;
 }
@@ -897,4 +898,4 @@ declare function createCoreConfig<Config extends Record<string, unknown>, Events
   config: Config;
 }): CoreConfigResult<Config, Events>;
 //#endregion
-export { type EmitFunction as EmitFn, type PluginContext_ as PluginCtx, createCoreConfig };
+export { type AnyPluginInstance, type App, type BoundCreateCoreFunction, type BoundCreatePluginFunction, type CoreConfigResult, type CreateAppOptions, type CreateCoreOptions, type CreateCoreResult, type EmitFunction as EmitFn, type PluginContext_ as PluginCtx, type PluginInstance, createCoreConfig };

package/dist/index.mjs

@@ -403,13 +403,13 @@ function buildApp(runtime, flatPlugins, buildPluginContext, consumer) {
 * API building, lifecycle execution, returns frozen app object.
 *
 * @param parameters - All kernel inputs captured from the factory chain.
-* @returns A promise that resolves to the frozen app object.
+* @returns The frozen app object.
 * @example
 * ```ts
 * const app = await kernel({ id: "my-app", configDefaults: {}, ... });
 * ```
 */
-async function kernel(parameters) {
+function kernel(parameters) {
 	const { id, configDefaults, frameworkPluginConfigs, flatPlugins, configOverrides, consumerPluginConfigs, onReady, onError, consumer } = parameters;
 	const pluginNameSet = new Set(flatPlugins.map((plugin) => plugin.name));
 	const globalConfig = Object.freeze({
@@ -433,9 +433,9 @@ async function kernel(parameters) {
 	const buildPluginContext = createContextFactory(runtime, resolvedConfigs, states);
 	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) await plugin.spec.onInit(buildPluginContext(plugin));
-	if (onReady) await onReady({ config: globalConfig });
-	if (consumer?.onReady) await consumer.onReady(buildCallbackContext(runtime));
+	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);
 }
 
@@ -483,13 +483,13 @@ function createCoreFactory(frameworkId, configDefaults, createPlugin) {
 		* plugins, then delegates to the kernel for lifecycle execution.
 		*
 		* @param consumerOptions - Consumer-level config, plugins, and callbacks.
-		* @returns A promise that resolves to the frozen App object.
+		* @returns The frozen App object.
 		* @example
 		* ```ts
-		* const app = await createApp({ config: { siteName: "Blog" } });
+		* const app = createApp({ config: { siteName: "Blog" } });
 		* ```
 		*/
-		const createApp = async (consumerOptions) => {
+		const createApp = (consumerOptions) => {
 			const appOptions = consumerOptions ?? {};
 			const allPlugins = [...defaultPlugins, ...appOptions.plugins ?? []];
 			validatePlugins(frameworkId, allPlugins);

package/package.json

@@ -1,26 +1,59 @@
 {
   "name": "@moku-labs/core",
-  "version": "0.1.0-alpha.0",
-  "description": "Micro-kernel plugin framework for LLMs (TypeScript)",
-  "type": "module",
-  "license": "MIT",
+  "version": "0.1.0-alpha.2",
   "author": "Alex Kucherenko",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/moku-labs/core.git"
   },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.2",
+    "@arethetypeswrong/core": "0.18.2",
+    "@biomejs/biome": "2.4.2",
+    "@types/bun": "1.3.9",
+    "@vitest/coverage-istanbul": "4.0.18",
+    "eslint": "9",
+    "eslint-config-biome": "2.1.3",
+    "eslint-plugin-jsdoc": "62.6.0",
+    "eslint-plugin-sonarjs": "4.0.0",
+    "eslint-plugin-unicorn": "63.0.0",
+    "globals": "17.3.0",
+    "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",
+    "vitest": "4.0.18"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
   "bugs": {
     "url": "https://github.com/moku-labs/core/issues"
   },
-  "homepage": "https://github.com/moku-labs/core#readme",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
+  "description": "Micro-kernel plugin framework for LLMs (TypeScript)",
   "engines": {
     "node": ">=22.0.0",
     "bun": ">=1.3.8"
   },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "homepage": "https://github.com/moku-labs/core#readme",
   "keywords": [
     "plugin",
     "framework",
@@ -30,21 +63,11 @@
     "event-bus",
     "type-safe"
   ],
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.mts",
   "scripts": {
     "build": "tsdown",
     "validate": "publint && attw --pack . --profile node16",
@@ -57,29 +80,6 @@
     "test:sandbox": "vitest run --project sandbox",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "files": [
-    "dist",
-    "LICENSE",
-    "README.md"
-  ],
-  "devDependencies": {
-    "@arethetypeswrong/cli": "0.18.2",
-    "@arethetypeswrong/core": "0.18.2",
-    "@biomejs/biome": "2.4.2",
-    "@types/bun": "1.3.9",
-    "@vitest/coverage-istanbul": "4.0.18",
-    "eslint": "9",
-    "eslint-config-biome": "2.1.3",
-    "eslint-plugin-jsdoc": "62.6.0",
-    "eslint-plugin-sonarjs": "4.0.0",
-    "eslint-plugin-unicorn": "63.0.0",
-    "globals": "17.3.0",
-    "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",
-    "vitest": "4.0.18"
-  }
+  "type": "module",
+  "types": "./dist/index.d.mts"
 }