@kanian77/choux 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# Choux Plugin System
+
+Choux is a modular, type-safe plugin system for Node.js/TypeScript applications, built on top of the `@kanian77/simple-di` dependency injection framework. It enables dynamic plugin discovery, loading, lifecycle management, and custom hooks, making it easy to extend your application with isolated, reusable modules.
+
+## Core Concepts
+
+### Plugin
+
+A plugin is a class extending the abstract `Plugin` base class (`src/core/Plugin.ts`). Each plugin must define metadata (name, version, optional description and dependencies) and can implement lifecycle methods:
+
+- `onLoad`: Called when the plugin is loaded, before dependencies are resolved.
+- `onInit`: Called after dependencies are resolved and injected.
+- `onDestroy`: Called when the plugin is being unloaded.
+- `registerCustomHooks`: Register custom hooks for other plugins to use.
+
+Plugins are typically defined in their own folder (e.g. `plugins/example-plugin/`) with a `module.ts` file exporting the plugin class as default.
+
+### Plugin Discovery & Loading
+
+- **PluginLoader (`src/core/PluginLoader.ts`)**: Scans a plugins directory for valid plugins (folders containing `module.ts`), loads them, resolves dependencies, and manages their lifecycle. Plugins are loaded dynamically using ES module imports.
+- **PluginManager (`src/core/PluginManager.ts`)**: High-level manager for initializing and shutting down all plugins, using the loader. It also exposes methods to get loaded plugins and their services.
+
+### Dependency Injection
+
+All plugins and core services use the DI system from `@kanian77/simple-di`. Tokens (see `src/core/tokens.ts`) are used to register and inject services, including plugin services and the hook registry.
+
+### Hooks & Events
+
+- **HookRegistry (`src/core/HookRegistry.ts`)**: Central registry for registering, triggering, and managing hooks/events. Plugins can register handlers for lifecycle or custom hooks, and trigger hooks to communicate with other plugins.
+- **Lifecycle Hooks**: Standard hooks for plugin load/init/destroy and application start/shutdown (see `LIFECYCLE_HOOKS`).
+- **Custom Hooks**: Plugins can define and trigger their own hooks for extensibility.
+
+### Decorators & Utilities
+
+- **Hook Decorator (`src/decorators/hookDecorator.ts`)**: Provides a decorator and utility for registering hook handlers in plugin classes.
+- **Function Utilities (`src/lib/functions/`)**: Helper functions for hook registration and plugin management.
+- **Types (`src/lib/types/`)**: Shared interfaces and type definitions for plugins, hook registry, plugin loader/manager, and metadata.
+
+## Example Plugin Structure
+
+See `plugins/example-plugin/` for a reference implementation:
+
+- `module.ts`: Exports the plugin class, registers services, and hooks.
+- `services.ts`: Defines plugin-specific services, which can be injected elsewhere.
+- `tokens.ts`: Declares DI tokens for plugin services.
+
+## Usage
+
+### Bootstrapping
+
+See `src/main.ts` for application startup:
+
+- Create a DI module importing the core module.
+- Bootstrap the DI system.
+- Get the plugin manager and initialize plugins from the plugins directory.
+- Access plugin services via DI tokens.
+
+### Accessing Plugin Services
+
+You can inject services provided by plugins using their tokens:
+
+```typescript
+import { inject } from '@kanian77/simple-di';
+import { EXAMPLE_SERVICE_TOKEN } from '../plugins/example-plugin/tokens';
+import { IExampleService } from '../plugins/example-plugin/services';
+
+const exampleService = inject<IExampleService>(EXAMPLE_SERVICE_TOKEN);
+exampleService.doSomething();
+```
+
+## Extending Choux
+
+- Add new plugins by creating a folder with a `module.ts` exporting a class extending `Plugin`.
+- Register services and hooks in your plugin.
+- Use the hook registry to communicate between plugins.
+- Use DI tokens for type-safe service access.
+
+## Directory Overview
+
+- `src/core/`: Core plugin system (Plugin, PluginLoader, PluginManager, HookRegistry, tokens)
+- `src/decorators/`: Hook decorator and registration utilities
+- `src/lib/functions/`: Helper functions for hooks and plugins
+- `src/lib/types/`: Shared type definitions
+- `plugins/`: Example and user plugins
+
+## License
+
+MIT
+## What's Already Great ✅
+
+- **Core Architecture**: Plugin extends Module, proper DI integration
+- **Lifecycle Management**: Load, init, destroy with proper ordering
+- **Hook System**: Both decorators and manual registration
+- **Dependency Resolution**: Plugin-level and module-level dependencies
+- **Type Safety**: Full TypeScript support with tokens
+- **Documentation**: Clear structure and examples
+
+## Areas for Enhancement 🔧
+
+### 1. **Plugin Configuration System**
+```typescript
+// src/core/pluginConfig.ts
+export interface PluginConfig {
+  [pluginName: string]: {
+    enabled?: boolean;
+    config?: Record<string, any>;
+  };
+}
+
+// In PluginLoader
+async loadPlugins(pluginsDir: string, config?: PluginConfig): Promise<LoadedPlugin[]>
+```
+
+### 2. **Plugin Validation & Health Checks**
+```typescript
+// Add to Plugin base class
+async healthCheck?(): Promise<{ healthy: boolean; message?: string }>;
+
+// Plugin metadata validation
+export function validatePluginMetadata(metadata: PluginMetadata): string[] {
+  const errors: string[] = [];
+  if (!metadata.name) errors.push('Plugin name is required');
+  // ... more validations
+  return errors;
+}
+```
+
+### 3. **Error Handling & Recovery**
+```typescript
+// Enhanced error handling in PluginLoader
+interface PluginLoadError {
+  pluginPath: string;
+  error: Error;
+  phase: 'discovery' | 'load' | 'init';
+}
+
+// Add retry mechanisms for failed plugins
+async retryFailedPlugin(pluginName: string): Promise<void>
+```
+
+### 4. **Plugin Hot Reloading** (Development)
+```typescript
+// src/core/pluginWatcher.ts
+export class PluginWatcher {
+  async watchForChanges(pluginsDir: string): Promise<void>;
+  async reloadPlugin(pluginName: string): Promise<void>;
+}
+```

package/bun.lock

@@ -0,0 +1,36 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@kanian77/choux",
+      "dependencies": {
+        "@kanian77/simple-di": "^0.1.2",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@kanian77/simple-di": ["@kanian77/simple-di@0.1.2", "", { "dependencies": { "@types/bun": "^1.2.4", "reflect-metadata": "^0.2.2" } }, "sha512-sTf0ul3ckEncXugV5eB7sdwLuP8F2ScryXqKtOheQ7WwKVK4xs5/oAj2xihDHXKkjgfVvcnnqWhXGCky67PVsg=="],
+
+    "@types/bun": ["@types/bun@1.2.19", "", { "dependencies": { "bun-types": "1.2.19" } }, "sha512-d9ZCmrH3CJ2uYKXQIUuZ/pUnTqIvLDS0SK7pFmbx8ma+ziH/FRMoAq5bYpRG7y+w1gl+HgyNZbtqgMq4W4e2Lg=="],
+
+    "@types/node": ["@types/node@24.1.0", "", { "dependencies": { "undici-types": "~7.8.0" } }, "sha512-ut5FthK5moxFKH2T1CUOC6ctR67rQRvvHdFLCD2Ql6KXmMuCrjsSsRI9UsLCm9M18BMwClv4pn327UvB7eeO1w=="],
+
+    "@types/react": ["@types/react@19.1.8", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-AwAfQ2Wa5bCx9WP8nZL2uMZWod7J7/JSplxbTmBQ5ms6QpqNYm672H0Vu9ZVKVngQ+ii4R/byguVEUZQyeg44g=="],
+
+    "bun-types": ["bun-types@1.2.19", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-uAOTaZSPuYsWIXRpj7o56Let0g/wjihKCkeRqUBhlLVM/Bt+Fj9xTo+LhC1OV1XDaGkz4hNC80et5xgy+9KTHQ=="],
+
+    "csstype": ["csstype@3.1.3", "", {}, "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw=="],
+
+    "reflect-metadata": ["reflect-metadata@0.2.2", "", {}, "sha512-urBwgfrvVP/eAyXx4hluJivBKzuEbSQs9rKWCrCkbSxNv8mxPcUZKeuoF3Uy4mJl3Lwprp6yy5/39VWigZ4K6Q=="],
+
+    "typescript": ["typescript@5.8.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ=="],
+
+    "undici-types": ["undici-types@7.8.0", "", {}, "sha512-9UJ2xGDvQ43tYyVMpuHlsgApydB8ZKfVYTsLDhXkFL/6gfkp+U8xTGdh8pMJv1SpZna0zxG1DwsKZsreLbXBxw=="],
+  }
+}

package/index.ts

@@ -0,0 +1,4 @@
+export * from './src/lib/types';
+export * from './src/lib/functions';
+export * from './src/core';
+export * from './src/decorators';

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@kanian77/choux",
+  "version": "0.1.0",
+  "description": "A simple plugin framework for TypeScript.",
+  "author": {
+    "name": "Patrick Assoa Adou",
+    "email": "kanian77@gmail.com"
+  },
+  "repository": "git@github.com:kanian/choux.git",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./dist/*": {
+      "import": "./dist/*.js",
+      "require": "./dist/*.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --build --verbose",
+    "dev": "tsc --build --verbose --watch",
+    "clean": "rm -rf dist && rm -rf tsconfig.tsbuildinfo",
+    "prepublishOnly": "bun run clean && bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@kanian77/simple-di": "^0.1.2"
+  }
+}

package/plugins/example-plugin/module.ts

@@ -0,0 +1,80 @@
+import { Module } from '@kanian77/simple-di';
+import { ExampleService } from './services';
+import { EXAMPLE_SERVICE_TOKEN } from './tokens';
+import { Hook } from '../../src/decorators/hookDecorator';
+import { inject } from '@kanian77/simple-di';
+import { Plugin } from '../../src/core/Plugin';
+import type { IHookRegistry } from '../../src/lib/types';
+import { HOOK_REGISTRY_TOKEN } from '../../src/lib/types/tokens';
+
+export default class ExamplePlugin extends Plugin {
+  readonly metadata = {
+    name: 'example-plugin',
+    version: '1.0.0',
+    description: 'An example plugin',
+    dependencies: [], // other plugin names this depends on
+  };
+
+  constructor() {
+    // Call parent Module constructor with plugin configuration
+    super({
+      providers: [
+        {
+          provide: EXAMPLE_SERVICE_TOKEN,
+          useClass: ExampleService,
+        },
+      ],
+      // Can also import other modules if needed
+      // imports: [SomeOtherModule],
+    });
+  }
+
+  override async onLoad(): Promise<void> {
+    console.log('ExamplePlugin loading...');
+  }
+
+  override async onInit(): Promise<void> {
+    console.log('ExamplePlugin initialized!');
+
+    // Additional manual hook registration if needed
+    this.registerAdditionalHooks();
+  }
+
+  override async onDestroy(): Promise<void> {
+    console.log('ExamplePlugin destroyed!');
+  }
+
+  protected override registerCustomHooks(): void {
+    // Define custom hooks that this plugin provides
+    // Other plugins can listen to these hooks
+    console.log('Registering custom hooks for ExamplePlugin');
+  }
+
+  // These methods will be automatically registered as hook handlers
+  @Hook('custom:example-event')
+  private async handleExampleEvent(data: any): Promise<void> {
+    console.log('Handling example event via decorator:', data);
+  }
+
+  @Hook('core:application-start')
+  private async onApplicationStart(): Promise<void> {
+    console.log('ExamplePlugin responding to application start via decorator');
+  }
+
+  @Hook('core:before-plugin-load')
+  private async onBeforePluginLoad(pluginPath: string): Promise<void> {
+    console.log('Another plugin is about to load:', pluginPath);
+  }
+
+  // Manual hook registration for dynamic scenarios
+  private registerAdditionalHooks(): void {
+    const hookRegistry = inject<IHookRegistry>(HOOK_REGISTRY_TOKEN);
+
+    // Register additional hooks manually if needed
+    hookRegistry.register('dynamic:custom-hook', this.handleDynamicHook.bind(this));
+  }
+
+  private async handleDynamicHook(data: any): Promise<void> {
+    console.log('Handling dynamic hook:', data);
+  }
+}

package/plugins/example-plugin/services.ts

@@ -0,0 +1,22 @@
+import { Service, Inject, inject } from '@kanian77/simple-di';
+import { EXAMPLE_SERVICE_TOKEN } from './tokens';
+import { HOOK_REGISTRY_TOKEN } from '../../src/lib/types/tokens';
+import type { IHookRegistry } from '../../src/lib/types';
+
+export interface IExampleService {
+  doSomething(): void;
+}
+
+@Service({ token: EXAMPLE_SERVICE_TOKEN })
+export class ExampleService implements IExampleService {
+  private hookRegistry: IHookRegistry;
+  constructor() {
+    this.hookRegistry = inject<IHookRegistry>(HOOK_REGISTRY_TOKEN);
+  }
+
+  doSomething(): void {
+    console.log('ExampleService doing something...');
+    // Can trigger custom hooks
+    this.hookRegistry.trigger('example:something-done', { data: 'example' });
+  }
+}

package/plugins/example-plugin/tokens.ts

@@ -0,0 +1 @@
+export const EXAMPLE_SERVICE_TOKEN = Symbol('ExampleService');

package/src/core/ChouxModule.ts

@@ -0,0 +1,17 @@
+import { Module } from '@kanian77/simple-di';
+import { HookRegistry } from './HookRegistry';
+import { PluginManager } from './PluginManager';
+import { HOOK_REGISTRY_TOKEN, PLUGIN_MANAGER_TOKEN } from '../lib/types/tokens';
+
+export const ChouxModule = new Module({
+  providers: [
+    {
+      provide: HOOK_REGISTRY_TOKEN,
+      useClass: HookRegistry,
+    },
+    {
+      provide: PLUGIN_MANAGER_TOKEN,
+      useClass: PluginManager,
+    },
+  ],
+});

package/src/core/HookRegistry.spec.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, beforeEach } from 'bun:test';
+import { HookRegistry } from './HookRegistry';
+import type { HookFn } from '../lib/types';
+
+describe('HookRegistry', () => {
+  let registry: HookRegistry;
+
+  beforeEach(() => {
+    registry = new HookRegistry();
+  });
+
+  it('registers and triggers a hook', async () => {
+    let called = false;
+    const fn: HookFn = () => {
+      called = true;
+    };
+    registry.register('test:hook', fn);
+    await registry.trigger('test:hook');
+    expect(called).toBe(true);
+  });
+
+  it('unregisters a specific hook handler', async () => {
+    let called = false;
+    const fn: HookFn = () => {
+      called = true;
+    };
+    registry.register('test:hook', fn);
+    registry.unregister('test:hook', fn);
+    await registry.trigger('test:hook');
+    expect(called).toBe(false);
+  });
+
+  it('unregisters all handlers for a hook', async () => {
+    let called = false;
+    const fn: HookFn = () => {
+      called = true;
+    };
+    registry.register('test:hook', fn);
+    registry.unregister('test:hook');
+    await registry.trigger('test:hook');
+    expect(called).toBe(false);
+  });
+
+  it('getHooks returns all registered handlers', () => {
+    const fn1: HookFn = () => {};
+    const fn2: HookFn = () => {};
+    registry.register('test:hook', fn1);
+    registry.register('test:hook', fn2);
+    const hooks = registry.getHooks('test:hook');
+    expect(hooks.length).toBe(2);
+    expect(hooks).toContain(fn1);
+    expect(hooks).toContain(fn2);
+  });
+
+  it('clear removes all hooks', () => {
+    const fn: HookFn = () => {};
+    registry.register('test:hook', fn);
+    registry.clear();
+    expect(registry.getHooks('test:hook').length).toBe(0);
+  });
+
+  it('trigger calls all registered async handlers', async () => {
+    let result = '';
+    const fn1: HookFn = async () => {
+      result += 'a';
+    };
+    const fn2: HookFn = async () => {
+      result += 'b';
+    };
+    registry.register('test:hook', fn1);
+    registry.register('test:hook', fn2);
+    await registry.trigger('test:hook');
+    expect(result).toBe('ab');
+  });
+});

package/src/core/HookRegistry.ts

@@ -0,0 +1,78 @@
+import { Service } from '@kanian77/simple-di';
+import { HOOK_REGISTRY_TOKEN } from '../lib/types/tokens';
+import type { HookFn, HookMap, IHookRegistry } from '../lib/types';
+
+/**
+ * Registry for application hooks.
+ */
+@Service({ token: HOOK_REGISTRY_TOKEN })
+export class HookRegistry implements IHookRegistry {
+  private hooks: HookMap = new Map();
+
+  /**
+   * Register a hook handler.
+   * @param name The name of the hook to register the function for.
+   * @param fn The hook handler function.
+   */
+  register(name: string, fn: HookFn): void {
+    const list = this.hooks.get(name) || [];
+    this.hooks.set(name, [...list, fn]);
+  }
+
+  /**
+   * Trigger a hook, calling all registered handlers.
+   * @param name The name of the hook to trigger.
+   * @param args Arguments to pass to the hook handlers.
+   */
+  async trigger(name: string, ...args: any[]): Promise<void> {
+    const fns = this.hooks.get(name) || [];
+    for (const fn of fns) {
+      await fn(...args);
+    }
+  }
+
+  /**
+   * Unregister a hook handler.
+   * If no function is provided, all handlers for the hook will be removed.
+   * @param name The name of the hook to unregister from.
+   * @param fn Optional specific handler to remove.
+   */
+  unregister(name: string, fn?: HookFn): void {
+    if (!fn) {
+      this.hooks.delete(name);
+      return;
+    }
+
+    const list = this.hooks.get(name) || [];
+    const filtered = list.filter((registeredFn) => registeredFn !== fn);
+    this.hooks.set(name, filtered);
+  }
+
+  /**
+   * Get all registered handlers for a specific hook.
+   * @param name The name of the hook to retrieve handlers for.
+   * @returns An array of hook handler functions.
+   */
+  getHooks(name: string): HookFn[] {
+    return this.hooks.get(name) || [];
+  }
+
+  /**
+   * Clear all registered hooks.
+   */
+  clear(): void {
+    this.hooks.clear();
+  }
+}
+
+// Standard lifecycle hooks
+export const LIFECYCLE_HOOKS = {
+  BEFORE_PLUGIN_LOAD: 'core:before-plugin-load',
+  AFTER_PLUGIN_LOAD: 'core:after-plugin-load',
+  BEFORE_PLUGIN_INIT: 'core:before-plugin-init',
+  AFTER_PLUGIN_INIT: 'core:after-plugin-init',
+  BEFORE_PLUGIN_DESTROY: 'core:before-plugin-destroy',
+  AFTER_PLUGIN_DESTROY: 'core:after-plugin-destroy',
+  APPLICATION_START: 'core:application-start',
+  APPLICATION_SHUTDOWN: 'core:application-shutdown',
+} as const;

package/src/core/Plugin.ts

@@ -0,0 +1,26 @@
+import { Module } from '@kanian77/simple-di';
+import type { PluginMetadata } from '../lib/types';
+
+export abstract class Plugin extends Module {
+  abstract readonly metadata: PluginMetadata;
+
+  /**
+   * Called when plugin is loaded but before dependencies are resolved
+   */
+  async onLoad?(): Promise<void>;
+
+  /**
+   * Called after all dependencies are resolved and injected
+   */
+  async onInit?(): Promise<void>;
+
+  /**
+   * Called when plugin is being unloaded
+   */
+  async onDestroy?(): Promise<void>;
+
+  /**
+   * Register custom hooks specific to this plugin
+   */
+  protected registerCustomHooks?(): void;
+}

package/src/core/PluginLoader.spec.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { PluginLoader } from './PluginLoader';
+import { HOOK_REGISTRY_TOKEN } from '../lib/types/tokens';
+import { LIFECYCLE_HOOKS } from './HookRegistry';
+import type { IHookRegistry, LoadedPlugin } from '../lib/types';
+import { Plugin } from './Plugin';
+import { tmpdir } from 'os';
+import { mkdtempSync } from 'fs';
+// Minimal IHookRegistry mock
+const mockHookRegistry: IHookRegistry = {
+  trigger: async () => {},
+  register: () => {},
+  unregister: () => {},
+  getHooks: () => [],
+  clear: () => {},
+};
+
+// // Patch inject to return our mock
+// import * as simpleDi from "@kanian77/simple-di";
+// (simpleDi as any).inject = () => mockHookRegistry;
+
+// Patch fs.promises for plugin discovery
+import { mkdir, writeFile, rm } from 'fs/promises';
+import { join, resolve } from 'path';
+
+// Helper for plugin mocks
+class PluginMock extends Plugin {
+  override metadata = { name: 'pluginA', version: '1.0.0' };
+  override imports = [];
+  override providers = [];
+  override async onLoad() {}
+  override async onInit() {}
+  override async onDestroy() {}
+  override registerCustomHooks() {}
+}
+class PluginMockA extends Plugin {
+  override metadata = { name: 'A', version: '1.0.0', dependencies: ['B'] };
+  override imports = [];
+  override providers = [];
+}
+class PluginMockB extends Plugin {
+  override metadata = { name: 'B', version: '1.0.0', dependencies: ['A'] };
+  override imports = [];
+  override providers = [];
+}
+
+describe('PluginLoader', () => {
+  let loader: PluginLoader;
+  let tempRoot: string;
+
+  beforeEach(async () => {
+    loader = new PluginLoader();
+    tempRoot = mkdtempSync(join(tmpdir(), 'plugin-test-'));
+
+    // Create pluginA with module.ts
+    const pluginADir = join(tempRoot, 'pluginA');
+    await mkdir(pluginADir);
+    await writeFile(join(pluginADir, 'module.ts'), '// pluginA module');
+
+    // Create pluginB without module.ts
+    const pluginBDir = join(tempRoot, 'pluginB');
+    await mkdir(pluginBDir);
+
+    // Create a non-directory file
+    await writeFile(join(tempRoot, 'file.txt'), 'not a directory');
+  });
+
+  afterEach(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  it('findPlugins returns only directories with module.ts', async () => {
+    const plugins = await loader.findPlugins('./src/lib/test-related/plugins');
+
+    expect(plugins).toEqual([
+      'src/lib/test-related/plugins/plugin-a',
+      'src/lib/test-related/plugins/plugin-b',
+    ]);
+  });
+
+  it('loadPlugin throws if no default export', async () => {
+    const origJoin = require('path').join;
+    require('path').join = (...args: string[]) => args.join('/');
+    const origImport = (global as any).import;
+    (global as any).import = async (_: string) => ({});
+    await expect(
+      loader.loadPlugin('./src/lib/test-related/plugins/plugin-a')
+    ).rejects.toThrow();
+    (global as any).import = origImport;
+    require('path').join = origJoin;
+  });
+
+  it('loadPlugin loads valid plugin and triggers hooks', async () => {
+    const modulePath = resolve('src/lib/test-related/plugins/plugin-a');
+    const loaded = await loader.loadPlugin(modulePath);
+    expect(loaded.plugin).toBeInstanceOf(
+      await import(join(modulePath, 'module.ts')).then((m) => m.default)
+    );
+    expect(loaded.metadata.name).toBe('pluginA');
+  });
+
+  it('unloadPlugin triggers destroy hooks and removes plugin', async () => {
+    const loaded: LoadedPlugin = {
+      plugin: new PluginMock({}),
+      metadata: { name: 'pluginA', version: '1.0.0' },
+      pluginClass: PluginMock,
+    };
+    loader['loadedPlugins'].set('pluginA', loaded);
+    await loader.unloadPlugin('pluginA');
+    expect(loader.getPlugin('pluginA')).toBeUndefined();
+  });
+
+  it('getAllPlugins returns all loaded plugins', () => {
+    const loaded: LoadedPlugin = {
+      plugin: new PluginMock({}),
+      metadata: { name: 'pluginA', version: '1.0.0' },
+      pluginClass: PluginMock,
+    };
+    loader['loadedPlugins'].set('pluginA', loaded);
+    expect(loader.getAllPlugins()).toEqual([loaded]);
+  });
+
+  it('resolveDependencyOrder throws on circular dependency', () => {
+    const pluginA: LoadedPlugin = {
+      plugin: new PluginMockA({}),
+      metadata: { name: 'A', version: '1.0.0', dependencies: ['B'] },
+      pluginClass: PluginMockA,
+    };
+    const pluginB: LoadedPlugin = {
+      plugin: new PluginMockB({}),
+      metadata: { name: 'B', version: '1.0.0', dependencies: ['A'] },
+      pluginClass: PluginMockB,
+    };
+    expect(() =>
+      loader['resolveDependencyOrder']([pluginA, pluginB])
+    ).toThrow();
+  });
+});

package/src/core/PluginLoader.ts

@@ -0,0 +1,192 @@
+import { Module, inject } from '@kanian77/simple-di';
+import { Plugin } from './Plugin';
+import type { PluginMetadata, LoadedPlugin, IHookRegistry } from '../lib/types';
+import { LIFECYCLE_HOOKS } from './HookRegistry';
+import { HOOK_REGISTRY_TOKEN } from '../lib/types/tokens';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+// LoadedPlugin now imported from types
+
+export class PluginLoader {
+  private loadedPlugins: Map<string, LoadedPlugin> = new Map();
+
+  async findPlugins(pluginsDir: string): Promise<string[]> {
+    try {
+      const entries = await fs.readdir(pluginsDir, { withFileTypes: true });
+      const pluginDirs: string[] = [];
+
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const pluginPath = path.join(pluginsDir, entry.name);
+          const modulePath = path.join(pluginPath, 'module.ts');
+
+          try {
+            await fs.access(modulePath);
+            pluginDirs.push(pluginPath);
+          } catch {
+            // Skip directories without module.ts
+          }
+        }
+      }
+
+      return pluginDirs;
+    } catch (error) {
+      console.warn(`Could not read plugins directory: ${pluginsDir}`, error);
+      return [];
+    }
+  }
+
+  async loadPlugin(pluginPath: string): Promise<LoadedPlugin> {
+    const modulePath = path.join(pluginPath, 'module.ts');
+    console.log(`Loading plugin from ${modulePath}`);
+    const hookRegistry = inject<IHookRegistry>(HOOK_REGISTRY_TOKEN);
+    await hookRegistry.trigger(LIFECYCLE_HOOKS.BEFORE_PLUGIN_LOAD, pluginPath);
+
+    // Dynamic import of the plugin module
+    const module = await import(modulePath);
+    const PluginClass = module.default;
+
+    if (!PluginClass || !PluginClass.prototype) {
+      throw new Error(
+        `Invalid plugin at ${pluginPath}: must export a Plugin class as default`
+      );
+    }
+
+    // Create plugin instance (which is also a Module)
+    const plugin = new PluginClass();
+
+    if (!plugin.metadata) {
+      throw new Error(`Plugin at ${pluginPath} must have metadata property`);
+    }
+
+    // Call plugin's onLoad lifecycle method
+    if (plugin.onLoad) {
+      await plugin.onLoad();
+    }
+
+    // Register custom hooks if defined
+    if (plugin.registerCustomHooks) {
+      plugin.registerCustomHooks();
+    }
+
+    const loadedPlugin: LoadedPlugin = {
+      plugin, // plugin is already a Module
+      metadata: plugin.metadata,
+      pluginClass: PluginClass,
+    };
+
+    this.loadedPlugins.set(plugin.metadata.name, loadedPlugin);
+
+    await hookRegistry.trigger(LIFECYCLE_HOOKS.AFTER_PLUGIN_LOAD, loadedPlugin);
+
+    return loadedPlugin;
+  }
+
+  async loadPlugins(pluginsDir: string): Promise<LoadedPlugin[]> {
+    const pluginDirs = await this.findPlugins(pluginsDir);
+    const loadedPlugins: LoadedPlugin[] = [];
+
+    // Load all plugins first
+    for (const dir of pluginDirs) {
+      try {
+        const loaded = await this.loadPlugin(dir);
+        loadedPlugins.push(loaded);
+      } catch (error) {
+        console.error(`Failed to load plugin from ${dir}:`, error);
+      }
+    }
+
+    // Resolve dependencies and initialize
+    const sortedPlugins = this.resolveDependencyOrder(loadedPlugins);
+
+    for (const loaded of sortedPlugins) {
+      await this.initializePlugin(loaded);
+    }
+
+    return sortedPlugins;
+  }
+
+  private resolveDependencyOrder(plugins: LoadedPlugin[]): LoadedPlugin[] {
+    const sorted: LoadedPlugin[] = [];
+    const visited = new Set<string>();
+    const visiting = new Set<string>();
+
+    const visit = (plugin: LoadedPlugin) => {
+      const name = plugin.metadata.name;
+
+      if (visiting.has(name)) {
+        throw new Error(
+          `Circular dependency detected involving plugin: ${name}`
+        );
+      }
+
+      if (visited.has(name)) {
+        return;
+      }
+
+      visiting.add(name);
+
+      // Visit dependencies first
+      const dependencies = plugin.metadata.dependencies || [];
+      for (const depName of dependencies) {
+        const dep = plugins.find((p) => p.metadata.name === depName);
+        if (!dep) {
+          throw new Error(
+            `Plugin ${name} depends on ${depName}, but it's not loaded`
+          );
+        }
+        visit(dep);
+      }
+
+      visiting.delete(name);
+      visited.add(name);
+      sorted.push(plugin);
+    };
+
+    for (const plugin of plugins) {
+      visit(plugin);
+    }
+
+    return sorted;
+  }
+
+  private async initializePlugin(loaded: LoadedPlugin): Promise<void> {
+    const hookRegistry = inject<IHookRegistry>(HOOK_REGISTRY_TOKEN);
+    await hookRegistry.trigger(LIFECYCLE_HOOKS.BEFORE_PLUGIN_INIT, loaded);
+
+    // Call plugin's onInit lifecycle method
+    if (loaded.plugin.onInit) {
+      await loaded.plugin.onInit();
+    }
+
+    await hookRegistry.trigger(LIFECYCLE_HOOKS.AFTER_PLUGIN_INIT, loaded);
+  }
+
+  async unloadPlugin(pluginName: string): Promise<void> {
+    const loaded = this.loadedPlugins.get(pluginName);
+    if (!loaded) {
+      throw new Error(`Plugin ${pluginName} is not loaded`);
+    }
+
+    const hookRegistry = inject<IHookRegistry>(HOOK_REGISTRY_TOKEN);
+    await hookRegistry.trigger(LIFECYCLE_HOOKS.BEFORE_PLUGIN_DESTROY, loaded);
+
+    // Call plugin's onDestroy lifecycle method
+    if (loaded.plugin.onDestroy) {
+      await loaded.plugin.onDestroy();
+    }
+
+    this.loadedPlugins.delete(pluginName);
+
+    await hookRegistry.trigger(LIFECYCLE_HOOKS.AFTER_PLUGIN_DESTROY, loaded);
+  }
+
+  getPlugin(name: string): LoadedPlugin | undefined {
+    return this.loadedPlugins.get(name);
+  }
+
+  getAllPlugins(): LoadedPlugin[] {
+    return Array.from(this.loadedPlugins.values());
+  }
+}

package/src/core/PluginManager.spec.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { PluginManager } from './PluginManager';
+import { resolve } from 'path';
+import { inject } from '@kanian77/simple-di';
+import { PLUGIN_MANAGER_TOKEN } from '../lib/types/tokens';
+
+describe('PluginManager', () => {
+  let manager: PluginManager;
+  const pluginsDir = resolve('src/lib/test-related/plugins');
+
+  beforeEach(() => {
+    manager = inject<PluginManager>(PLUGIN_MANAGER_TOKEN);
+  });
+
+  afterEach(async () => {
+    // No cleanup needed for static test plugins
+  });
+
+  it('initialize loads plugins and prints info', async () => {
+    let logOutput = '';
+    const origLog = console.log;
+    console.log = (msg: string) => {
+      logOutput += msg + '\n';
+    };
+    await manager.initialize(pluginsDir);
+    expect(logOutput).toContain('Loaded 2 plugins:');
+    expect(logOutput).toContain('plugin-a');
+    expect(logOutput).toContain('plugin-b');
+    console.log = origLog;
+  });
+
+  it('getPlugin returns correct plugin', async () => {
+    await manager.initialize(pluginsDir);
+    const pluginA = manager.getPlugin('pluginA');
+    expect(pluginA).toBeDefined();
+    expect(pluginA?.metadata.name).toBe('pluginA');
+    const pluginB = manager.getPlugin('pluginB');
+    expect(pluginB).toBeDefined();
+    expect(pluginB?.metadata.name).toBe('pluginB');
+  });
+
+  it('getAllPlugins returns all loaded plugins', async () => {
+    await manager.initialize(pluginsDir);
+    const all = manager.getAllPlugins();
+    expect(all.length).toBe(2);
+    expect(all.map((p) => p.metadata.name).sort()).toEqual([
+      'pluginA',
+      'pluginB',
+    ]);
+  });
+
+  it('shutdown unloads all plugins and clears registry', async () => {
+    await manager.initialize(pluginsDir);
+    await manager.shutdown();
+    expect(manager.getAllPlugins()).toEqual([]);
+  });
+});

package/src/core/PluginManager.ts

@@ -0,0 +1,47 @@
+import { Module, Service, Inject, inject } from '@kanian77/simple-di';
+import { LIFECYCLE_HOOKS } from './HookRegistry';
+import { PLUGIN_MANAGER_TOKEN, HOOK_REGISTRY_TOKEN } from '../lib/types/tokens';
+import type { IHookRegistry, IPluginManager, LoadedPlugin } from '../lib/types';
+import { PluginLoader } from './PluginLoader';
+
+// Removed local interface IPluginManager, now imported from lib/types
+
+@Service({ token: PLUGIN_MANAGER_TOKEN })
+export class PluginManager implements IPluginManager {
+  constructor(
+    @Inject(HOOK_REGISTRY_TOKEN) private hookRegistry: IHookRegistry,
+    @Inject(PluginLoader) private loader: PluginLoader
+  ) {}
+
+  async initialize(pluginsDir: string): Promise<void> {
+    await this.hookRegistry.trigger(LIFECYCLE_HOOKS.APPLICATION_START);
+
+    const plugins = await this.loader.loadPlugins(pluginsDir);
+
+    console.log(`Loaded ${plugins.length} plugins:`);
+    plugins.forEach((p) => {
+      console.log(`  - ${p.metadata.name} v${p.metadata.version}`);
+    });
+  }
+
+  async shutdown(): Promise<void> {
+    await this.hookRegistry.trigger(LIFECYCLE_HOOKS.APPLICATION_SHUTDOWN);
+
+    const plugins = this.loader.getAllPlugins();
+
+    // Unload in reverse dependency order
+    for (const plugin of plugins.reverse()) {
+      await this.loader.unloadPlugin(plugin.metadata.name);
+    }
+
+    this.hookRegistry.clear();
+  }
+
+  getPlugin(name: string): LoadedPlugin | undefined {
+    return this.loader.getPlugin(name);
+  }
+
+  getAllPlugins(): LoadedPlugin[] {
+    return this.loader.getAllPlugins();
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export * from './Plugin';
+export * from './PluginManager';
+export * from './HookRegistry';
+export * from './ChouxModule';

package/src/decorators/hookDecorator.ts

@@ -0,0 +1,30 @@
+import { inject } from '@kanian77/simple-di';
+import { HOOK_METADATA_KEY, HOOK_REGISTRY_TOKEN } from '../lib/types/tokens';
+import type { IHookRegistry } from '../lib/types';
+
+/**
+ * Decorator to register a method as a hook handler.
+ * This allows the method to be called when the specified hook is triggered.
+ * @param hookName The name of the hook to register this method for.
+ * @returns
+ */
+export function Hook(hookName: string) {
+  return function <T extends (...args: any[]) => any>(
+    target: any,
+    propertyKey: string | symbol,
+    descriptor: TypedPropertyDescriptor<T>
+  ): TypedPropertyDescriptor<T> | void {
+    // Store hook metadata on the class prototype
+    if (!target.constructor[HOOK_METADATA_KEY]) {
+      target.constructor[HOOK_METADATA_KEY] = [];
+    }
+
+    target.constructor[HOOK_METADATA_KEY].push({
+      hookName,
+      methodName: propertyKey.toString(),
+    });
+
+    // Return the descriptor (or void, both are valid)
+    return descriptor;
+  };
+}

package/src/decorators/index.ts

@@ -0,0 +1 @@
+export * from './hookDecorator';

package/src/lib/functions/index.ts

@@ -0,0 +1,2 @@
+export * from "./registerHooksForInstance";
+export * from "./registerHookHandler";

package/src/lib/functions/registerHookHandler.ts

@@ -0,0 +1,11 @@
+import { inject } from "@kanian77/simple-di";
+import type { IHookRegistry } from "../types";
+import { HOOK_REGISTRY_TOKEN } from "../types/tokens";
+
+export function registerHookHandler(
+  hookName: string,
+  handler: (...args: any[]) => void | Promise<void>
+) {
+  const hookRegistry = inject<IHookRegistry>(HOOK_REGISTRY_TOKEN);
+  hookRegistry.register(hookName, handler);
+}

package/src/lib/functions/registerHooksForInstance.ts

@@ -0,0 +1,26 @@
+import { inject } from "@kanian77/simple-di";
+import type { IHookRegistry } from "../types";
+import type { HookMetadata } from "../types/HookMetadata";
+import { HOOK_METADATA_KEY, HOOK_REGISTRY_TOKEN } from "../types/tokens";
+
+export function registerHooksForInstance(instance: any): void {
+  const constructor = instance.constructor;
+  const hookMetadata: HookMetadata[] = constructor[HOOK_METADATA_KEY] || [];
+
+  if (hookMetadata.length === 0) {
+    return;
+  }
+
+  try {
+    const hookRegistry = inject<IHookRegistry>(HOOK_REGISTRY_TOKEN);
+
+    for (const { hookName, methodName } of hookMetadata) {
+      const method = instance[methodName];
+      if (typeof method === 'function') {
+        hookRegistry.register(hookName, method.bind(instance));
+      }
+    }
+  } catch (error) {
+    console.warn('Failed to register hooks - HookRegistry may not be available yet:', error);
+  }
+}

package/src/lib/test-related/plugins/plugin-a/module.ts

@@ -0,0 +1,74 @@
+import { inject } from '@kanian77/simple-di';
+import { ExampleService } from '../../../../../plugins/example-plugin/services';
+import { Plugin } from '../../../../core';
+import { Hook } from '../../../../decorators';
+import type { IHookRegistry } from '../../../types';
+import { HOOK_REGISTRY_TOKEN } from '../../../types/tokens';
+
+export const PLUGIN_A_TOKEN = 'PLUGIN_A_TOKEN';
+export default class PluginA extends Plugin {
+  readonly metadata = {
+    name: 'pluginA',
+    version: '1.0.0',
+    description: 'An example plugin',
+    dependencies: [], // other plugin names this depends on
+  };
+
+  constructor() {
+    // Call parent Module constructor with plugin configuration
+    super({
+      providers: [
+        {
+          provide: PLUGIN_A_TOKEN,
+          useClass: ExampleService,
+        },
+      ],
+    });
+  }
+
+  override async onLoad(): Promise<void> {
+    console.log('PluginA loading...');
+  }
+
+  override async onInit(): Promise<void> {
+    console.log('PluginA initialized!');
+
+    // Additional manual hook registration if needed
+    this.registerAdditionalHooks();
+  }
+
+  override async onDestroy(): Promise<void> {
+    console.log('PluginA destroyed!');
+  }
+
+  protected override registerCustomHooks(): void {
+    console.log('Registering custom hooks for PluginA');
+  }
+
+  // These methods will be automatically registered as hook handlers
+  @Hook('custom:example-event')
+  private async handleExampleEvent(data: any): Promise<void> {
+    console.log('Handling example event via decorator:', data);
+  }
+
+  @Hook('core:application-start')
+  private async onApplicationStart(): Promise<void> {
+    console.log('PluginA responding to application start via decorator');
+  }
+
+  @Hook('core:before-plugin-load')
+  private async onBeforePluginLoad(pluginPath: string): Promise<void> {
+    console.log('Another plugin is about to load:', pluginPath);
+  }
+
+  private registerAdditionalHooks(): void {
+    const hookRegistry = inject<IHookRegistry>(HOOK_REGISTRY_TOKEN);
+    hookRegistry.register(
+      'dynamic:custom-hook',
+      this.handleDynamicHook.bind(this)
+    );
+  }
+  private async handleDynamicHook(data: any): Promise<void> {
+    console.log('Handling dynamic hook:', data);
+  }
+}

package/src/lib/test-related/plugins/plugin-b/module.ts

@@ -0,0 +1,74 @@
+import { inject } from '@kanian77/simple-di';
+import { ExampleService } from '../../../../../plugins/example-plugin/services';
+import { Plugin } from '../../../../core';
+import { Hook } from '../../../../decorators';
+import type { IHookRegistry } from '../../../types';
+import { HOOK_REGISTRY_TOKEN } from '../../../types/tokens';
+
+export const PLUGIN_B_TOKEN = 'PLUGIN_B_TOKEN';
+export default class PluginB extends Plugin {
+  readonly metadata = {
+    name: 'pluginB',
+    version: '1.0.0',
+    description: 'An example plugin',
+    dependencies: [], // other plugin names this depends on
+  };
+
+  constructor() {
+    // Call parent Module constructor with plugin configuration
+    super({
+      providers: [
+        {
+          provide: PLUGIN_B_TOKEN,
+          useClass: ExampleService,
+        },
+      ],
+    });
+  }
+
+  override async onLoad(): Promise<void> {
+    console.log('PluginB loading...');
+  }
+
+  override async onInit(): Promise<void> {
+    console.log('PluginB initialized!');
+
+    // Additional manual hook registration if needed
+    this.registerAdditionalHooks();
+  }
+
+  override async onDestroy(): Promise<void> {
+    console.log('PluginB destroyed!');
+  }
+
+  protected override registerCustomHooks(): void {
+    console.log('Registering custom hooks for PluginB');
+  }
+
+  // These methods will be automatically registered as hook handlers
+  @Hook('custom:example-event')
+  private async handleExampleEvent(data: any): Promise<void> {
+    console.log('Handling example event via decorator:', data);
+  }
+
+  @Hook('core:application-start')
+  private async onApplicationStart(): Promise<void> {
+    console.log('PluginB responding to application start via decorator');
+  }
+
+  @Hook('core:before-plugin-load')
+  private async onBeforePluginLoad(pluginPath: string): Promise<void> {
+    console.log('Another plugin is about to load:', pluginPath);
+  }
+
+  private registerAdditionalHooks(): void {
+    const hookRegistry = inject<IHookRegistry>(HOOK_REGISTRY_TOKEN);
+    hookRegistry.register(
+      'dynamic:custom-hook',
+      this.handleDynamicHook.bind(this)
+    );
+  }
+  private async handleDynamicHook(data: any): Promise<void> {
+    console.log('Handling dynamic hook:', data);
+  }
+}

package/src/lib/types/HookMetadata.ts

@@ -0,0 +1,4 @@
+export interface HookMetadata {
+  hookName: string;
+  methodName: string;
+}

package/src/lib/types/IHookRegistry.ts

@@ -0,0 +1,10 @@
+export type HookFn = (...args: any[]) => void | Promise<void>;
+export type HookMap = Map<string, HookFn[]>;
+
+export interface IHookRegistry {
+  register(name: string, fn: HookFn): void;
+  trigger(name: string, ...args: any[]): Promise<void>;
+  unregister(name: string, fn?: HookFn): void;
+  getHooks(name: string): HookFn[];
+  clear(): void;
+}

package/src/lib/types/IPluginManager.ts

@@ -0,0 +1,8 @@
+import type { LoadedPlugin } from './LoadedPlugin';
+
+export interface IPluginManager {
+  initialize(pluginsDir: string): Promise<void>;
+  shutdown(): Promise<void>;
+  getPlugin(name: string): LoadedPlugin | undefined;
+  getAllPlugins(): LoadedPlugin[];
+}

package/src/lib/types/LoadedPlugin.ts

@@ -0,0 +1,9 @@
+import type { ModuleOptions } from '@kanian77/simple-di';
+import type { Plugin } from '../../core/Plugin';
+import type { PluginMetadata } from './PluginMetadata';
+
+export interface LoadedPlugin {
+  plugin: Plugin;
+  metadata: PluginMetadata;
+  pluginClass: new <T extends ModuleOptions = ModuleOptions>(options: T ) => Plugin;
+}

package/src/lib/types/PluginMetadata.ts

@@ -0,0 +1,9 @@
+import type { Module } from '@kanian77/simple-di';
+
+export interface PluginMetadata {
+  name: string;
+  version: string;
+  description?: string;
+  dependencies?: string[];
+}
+

package/src/lib/types/README.md

@@ -0,0 +1,3 @@
+# Types Exports
+
+This folder contains all shared interfaces and types for the plugin system. Use `import { ... } from 'src/lib/types'` for type-safe imports.

package/src/lib/types/index.ts

@@ -0,0 +1,5 @@
+export * from './PluginMetadata';
+export * from './IHookRegistry';
+export * from './LoadedPlugin';
+export * from './IPluginManager';
+export * from './HookMetadata';

package/src/lib/types/tokens.ts

@@ -0,0 +1,4 @@
+export const PLUGIN_MANAGER_TOKEN = Symbol('PluginManager');
+export const HOOK_REGISTRY_TOKEN = Symbol('HookRegistry');
+export const PLUGIN_METADATA_TOKEN = Symbol('PluginMetadata');
+export const HOOK_METADATA_KEY = Symbol('hookMetadata');

package/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false,
+
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}