@kimesh/kit 0.2.20 → 0.2.21

package/dist/index.d.mts

@@ -116,6 +116,26 @@ interface KimeshRouteMiddleware {
 //#endregion
 //#region src/types/hooks.d.ts
 type HookResult = void | Promise<void>;
+/**
+ * Normalized component directory for shadcn extension hook.
+ * Defined inline to avoid circular dependency with @kimesh/shadcn.
+ */
+interface ShadcnComponentDir {
+  /** Absolute or relative path to component directory */
+  path: string;
+  /** Component name prefix (e.g., 'Ui' for UiButton) */
+  prefix: string;
+}
+/**
+ * Tailwind source entry for extension hook.
+ * Defined inline to avoid circular dependency with @kimesh/tailwindcss.
+ */
+interface TailwindSourceEntry {
+  /** Absolute path to source directory */
+  path: string;
+  /** Optional comment in generated CSS */
+  comment?: string;
+}
 interface KimeshHooks {
   /** Called after config is loaded, before layers */
   'config:loaded': (config: KimeshConfig) => HookResult;
@@ -179,6 +199,44 @@ interface KimeshHooks {
   'hmr:after': (file: string, kimesh: Kimesh) => HookResult;
   /** Called when Kimesh is closing */
   close: (kimesh: Kimesh) => HookResult;
+  /**
+   * Called by @kimesh/shadcn to allow extending modules to add component directories.
+   * Hook handlers can push entries to the componentDirs array.
+   *
+   * @example
+   * ```ts
+   * defineKimeshModule({
+   *   hooks: {
+   *     'shadcn:componentDirs:extend': (componentDirs) => {
+   *       componentDirs.push({
+   *         path: '/path/to/uikit/components',
+   *         prefix: 'Ui'
+   *       })
+   *     }
+   *   }
+   * })
+   * ```
+   */
+  'shadcn:componentDirs:extend': (componentDirs: ShadcnComponentDir[], kimesh: Kimesh) => HookResult;
+  /**
+   * Called by @kimesh/tailwindcss to allow extending modules to add source directories.
+   * Hook handlers can push entries to the sources array.
+   *
+   * @example
+   * ```ts
+   * defineKimeshModule({
+   *   hooks: {
+   *     'tailwindcss:sources:extend': (sources) => {
+   *       sources.push({
+   *         path: '/path/to/uikit/src',
+   *         comment: '@onesystem/uikit'
+   *       })
+   *     }
+   *   }
+   * })
+   * ```
+   */
+  'tailwindcss:sources:extend': (sources: TailwindSourceEntry[], kimesh: Kimesh) => HookResult;
 }
 //#endregion
 //#region src/types/runtime-plugin.d.ts
@@ -399,6 +457,23 @@ interface KimeshModuleMeta {
     /** Minimum Kimesh version required */kimesh?: string; /** Minimum Vite version required */
     vite?: string;
   };
+  /**
+   * Modules to auto-load before this module.
+   * Extended modules will be resolved and their hooks registered
+   * before this module's setup() is called.
+   *
+   * @example
+   * ```ts
+   * defineKimeshModule({
+   *   meta: {
+   *     name: '@onesystem/uikit',
+   *     extends: ['@kimesh/shadcn', '@kimesh/tailwindcss'],
+   *   },
+   *   // ...
+   * })
+   * ```
+   */
+  extends?: string[];
 }
 /**
  * Module defaults can be:
@@ -1473,11 +1548,33 @@ declare function normalizeModuleInput<TOptions>(input: KimeshModuleInput<TOption
   options: Partial<TOptions>;
 }>;
 /**
- * Execute a single module
+ * Execute a single module (legacy API - kept for backward compatibility)
+ * @deprecated Use executeModules for proper extends support
  */
 declare function executeModule<TOptions>(moduleInput: KimeshModuleInput<TOptions>, kimesh: Kimesh): Promise<void>;
 /**
- * Execute all modules in order
+ * Execute all modules using two-phase execution
+ *
+ * Two-phase execution ensures proper hook timing for module extends:
+ *
+ * **Phase 1: Resolve & Register Hooks**
+ * - Resolves all modules (including those in `extends`)
+ * - Registers hooks from all modules BEFORE any setup() runs
+ * - This allows extending modules to inject config via hooks
+ *
+ * **Phase 2: Execute Setup**
+ * - Calls setup() on all modules in dependency order
+ * - Extended modules run first, then extending modules
+ *
+ * @example
+ * ```ts
+ * // @onesystem/uikit extends @kimesh/shadcn
+ * // Execution order:
+ * // 1. shadcn hooks registered
+ * // 2. uikit hooks registered (can hook into shadcn)
+ * // 3. shadcn.setup() runs (calls shadcn:componentDirs:extend hook)
+ * // 4. uikit.setup() runs
+ * ```
  */
 declare function executeModules(modules: KimeshModuleInput[], kimesh: Kimesh): Promise<void>;
 //#endregion

package/dist/index.mjs

@@ -316,7 +316,8 @@ function defineKimeshModule(definition) {
 			name: definition.meta?.name ?? "anonymous-module",
 			version: definition.meta?.version ?? "0.0.0",
 			configKey: definition.meta?.configKey ?? "",
-			compatibility: definition.meta?.compatibility ?? {}
+			compatibility: definition.meta?.compatibility ?? {},
+			extends: definition.meta?.extends ?? []
 		},
 		async getDefaults(kimesh) {
 			if (!definition.defaults) return {};
@@ -324,9 +325,6 @@ function defineKimeshModule(definition) {
 			return definition.defaults;
 		},
 		async setup(options, kimesh) {
-			if (definition.hooks) {
-				for (const [hookName, handler] of Object.entries(definition.hooks)) if (handler) kimesh.hook(hookName, handler);
-			}
 			if (definition.setup) await definition.setup(options, kimesh);
 		}
 	};
@@ -335,6 +333,7 @@ function defineKimeshModule(definition) {
 * Resolve a string module name to an actual module
 */
 async function resolveStringModule(moduleName, kimesh) {
+	if (moduleName.includes("..") || moduleName.startsWith("/") || moduleName.includes("\\")) throw new Error(`Invalid module name: "${moduleName}". Module names cannot contain path traversal characters.`);
 	try {
 		const requirePath = kimesh.root + "/package.json";
 		const require = createRequire(pathToFileURL(requirePath).href);
@@ -381,7 +380,82 @@ async function normalizeModuleInput(input, kimesh) {
 	};
 }
 /**
-* Execute a single module
+* Create a fresh execution context
+*/
+function createExecutionContext() {
+	return {
+		loadedModules: /* @__PURE__ */ new Set(),
+		loadingStack: [],
+		resolvedModules: /* @__PURE__ */ new Map()
+	};
+}
+/**
+* PHASE 1: Resolve module and its dependencies, register hooks
+*
+* This function:
+* 1. Resolves the module (from string or object)
+* 2. Recursively resolves all modules in `extends` first
+* 3. Registers the module's hooks
+* 4. Tracks loaded modules to prevent duplicates
+* 5. Detects circular dependencies
+*/
+async function resolveAndRegisterHooks(moduleInput, kimesh, ctx, userOptions = {}) {
+	const { module, options: inputOptions } = await normalizeModuleInput(moduleInput, kimesh);
+	const moduleName = module.meta.name;
+	if (ctx.loadedModules.has(moduleName)) return;
+	if (ctx.loadingStack.includes(moduleName)) {
+		const cycle = [...ctx.loadingStack, moduleName].join(" -> ");
+		throw new Error(`Circular dependency detected: ${cycle}`);
+	}
+	ctx.loadingStack.push(moduleName);
+	try {
+		const extendsModules = module.meta.extends || [];
+		for (const extendedName of extendsModules) await resolveAndRegisterHooks(extendedName, kimesh, ctx);
+		ctx.loadedModules.add(moduleName);
+		const mergedOptions = {
+			...inputOptions,
+			...userOptions
+		};
+		ctx.resolvedModules.set(moduleName, {
+			module,
+			options: mergedOptions
+		});
+		if (module._def.hooks) {
+			for (const [hookName, handler] of Object.entries(module._def.hooks)) if (handler) kimesh.hook(hookName, handler);
+		}
+	} finally {
+		ctx.loadingStack.pop();
+	}
+}
+/**
+* PHASE 2: Execute all setup() functions in dependency order
+*
+* Called after all modules are resolved and hooks registered.
+* Modules execute in the order they were resolved (dependencies first).
+*/
+async function executeAllSetups(kimesh, ctx) {
+	for (const [moduleName, { module, options: userOptions }] of ctx.resolvedModules) {
+		_setKimeshContext(kimesh);
+		try {
+			const defaults = await module.getDefaults(kimesh);
+			const configKey = module.meta.configKey;
+			const configOptions = configKey ? kimesh.options.config[configKey] ?? {} : {};
+			const mergedOptions = {
+				...defaults,
+				...configOptions,
+				...userOptions
+			};
+			await module.setup(mergedOptions, kimesh);
+		} catch (error) {
+			consola.error(`[Kimesh] Failed to execute module "${moduleName}":`, error);
+		} finally {
+			_setKimeshContext(void 0);
+		}
+	}
+}
+/**
+* Execute a single module (legacy API - kept for backward compatibility)
+* @deprecated Use executeModules for proper extends support
 */
 async function executeModule(moduleInput, kimesh) {
 	const { module, options: userOptions } = await normalizeModuleInput(moduleInput, kimesh);
@@ -393,6 +467,9 @@ async function executeModule(moduleInput, kimesh) {
 		...configOptions,
 		...userOptions
 	};
+	if (module._def.hooks) {
+		for (const [hookName, handler] of Object.entries(module._def.hooks)) if (handler) kimesh.hook(hookName, handler);
+	}
 	_setKimeshContext(kimesh);
 	try {
 		await module.setup(mergedOptions, kimesh);
@@ -413,16 +490,39 @@ function getModuleName(input) {
 	return input.meta?.name ?? "unknown";
 }
 /**
-* Execute all modules in order
+* Execute all modules using two-phase execution
+*
+* Two-phase execution ensures proper hook timing for module extends:
+*
+* **Phase 1: Resolve & Register Hooks**
+* - Resolves all modules (including those in `extends`)
+* - Registers hooks from all modules BEFORE any setup() runs
+* - This allows extending modules to inject config via hooks
+*
+* **Phase 2: Execute Setup**
+* - Calls setup() on all modules in dependency order
+* - Extended modules run first, then extending modules
+*
+* @example
+* ```ts
+* // @onesystem/uikit extends @kimesh/shadcn
+* // Execution order:
+* // 1. shadcn hooks registered
+* // 2. uikit hooks registered (can hook into shadcn)
+* // 3. shadcn.setup() runs (calls shadcn:componentDirs:extend hook)
+* // 4. uikit.setup() runs
+* ```
 */
 async function executeModules(modules, kimesh) {
 	await kimesh.callHook("modules:before", kimesh);
+	const ctx = createExecutionContext();
 	for (const moduleInput of modules) try {
-		await executeModule(moduleInput, kimesh);
+		await resolveAndRegisterHooks(moduleInput, kimesh, ctx, Array.isArray(moduleInput) ? moduleInput[1] : {});
 	} catch (error) {
 		const moduleName = getModuleName(moduleInput);
-		consola.error(`[Kimesh] Failed to execute module "${moduleName}":`, error);
+		consola.error(`[Kimesh] Failed to resolve module "${moduleName}":`, error);
 	}
+	await executeAllSetups(kimesh, ctx);
 	await kimesh.callHook("modules:done", kimesh);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kimesh/kit",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "description": "Build-time engine for Kimesh framework",
   "repository": {
     "type": "git",
@@ -27,9 +27,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@kimesh/auto-import": "0.2.20",
-    "@kimesh/layers": "0.2.20",
-    "@kimesh/router-generator": "0.2.20",
+    "@kimesh/auto-import": "0.2.21",
+    "@kimesh/layers": "0.2.21",
+    "@kimesh/router-generator": "0.2.21",
     "@vitejs/plugin-vue": "^6.0.3",
     "c12": "^3.3.3",
     "consola": "^3.4.2",