@africode/core 5.0.0 → 5.0.2

package/core/plugins/index.js

@@ -1,312 +1,345 @@
-/**
- * AfriCode Plugin Registry
- *
- * A minimal, strict, and predictable plug-in architecture for the AfriCode Framework.
- * Employs deterministic execution, strong boundary isolation, and a stable context
- * contract to prevent ecosystem bloat and ensure framework resilience.
- */
-
-// Core framework version to check plugin compatibility
-export const AFRICODE_VERSION = '4.0.0';
-
-// Only these specific hooks are permitted in v1
-export const ALLOWED_HOOKS = new Set([
-  'onConfigLoad',
-  'onComponentRegister',
-  'onRouteRegister',
-  'onStateInit',
-  'onServerStart',
-  'onRequest',
-  'onResponse',
-  'onError',
-  'onCliCommandRegister',
-]);
-
-// Protected core CLI commands that plugins cannot overwrite
-const PROTECTED_CLI_COMMANDS = new Set([
-  'dev',
-  'build',
-  'start',
-  'test',
-  'lint',
-  'audit',
-  'add',
-  'migrate',
-  'create',
-  'help',
-]);
-
-export class AfriPluginRegistry {
-  constructor(options = {}) {
-    this.plugins = new Map();
-    // Mode mapping: safe (swallow errors), strict (propagate crashes immediately)
-    this.mode = options.mode || 'safe';
-
-    // Plugin state tracking
-    this.disabledPlugins = new Set();
-
-    // Internal structured store for deterministic hook execution (arrays maintain registration order)
-    this.hooks = {
-      onConfigLoad: [],
-      onComponentRegister: [],
-      onRouteRegister: [],
-      onStateInit: [],
-      onServerStart: [],
-      onRequest: [],
-      onResponse: [],
-      onError: [],
-      onCliCommandRegister: [],
-    };
-
-    // Store plugin-registered CLI commands
-    this.pluginCommands = new Map();
-  }
-
-  /**
-   * Registers a new plugin into the framework.
-   * @param {Object} manifest - The Plugin manifest
-   * @param {Object} hooks - The hooks implementation
-   */
-  register(manifest, hooks) {
-    this._validateManifest(manifest);
-    this._validateCompatibility(manifest.compatibleWith);
-    this._validateHooks(manifest.name, hooks);
-
-    if (this.plugins.has(manifest.name)) {
-      console.warn(`[AfriCode Plugin] Plugin '${manifest.name}' is already registered. Skipping.`);
-      return;
-    }
-
-    this.plugins.set(manifest.name, manifest);
-
-    // Bind hooks into the deterministic execution pipeline
-    for (const [hookName, handler] of Object.entries(hooks)) {
-      this.hooks[hookName].push({
-        pluginName: manifest.name,
-        handler,
-      });
-    }
-
-    // Observability Hook
-    this._logObservability('onPluginLoad', manifest.name, `Registered v${manifest.version}`);
-  }
-
-  /**
-   * Disable a plugin at runtime. Safely ejects it from the pipeline.
-   */
-  disable(pluginName) {
-    if (!this.plugins.has(pluginName)) {
-      return;
-    }
-    this.disabledPlugins.add(pluginName);
-    this._logObservability('onPluginDisable', pluginName, 'Plugin forcefully disabled.');
-  }
-
-  /**
-   * Enable a previously disabled plugin.
-   */
-  enable(pluginName) {
-    this.disabledPlugins.delete(pluginName);
-  }
-
-  /**
-   * Execute a specific hook safely across all registered plugins in registration order.
-   * @param {string} hookName - The name of the hook to trigger
-   * @param {Object} context - A stable execution context exposed to plugins
-   */
-  async emit(hookName, context = {}) {
-    if (!ALLOWED_HOOKS.has(hookName)) {
-      throw new Error(`[AfriCode Plugin] Attempted to emit unknown hook: ${hookName}`);
-    }
-
-    const handlers = this.hooks[hookName];
-    if (!handlers || handlers.length === 0) {
-      return context;
-    }
-
-    // Clone context defensively to prevent deep framework mutation
-    // but allow mutations on specifically designed properties.
-    const stableContext = this._buildStableContext(hookName, context);
-
-    for (const { pluginName, handler } of handlers) {
-      if (this.disabledPlugins.has(pluginName)) {
-        continue;
-      } // Skip disabled plugins
-
-      const hookPromise = async () => {
-        const startTime = performance.now();
-        await handler(stableContext);
-        const latency = performance.now() - startTime;
-
-        // Deep trace for heavy hooks taking >50ms
-        if (latency > 50) {
-          this._logObservability(
-            'onHookComplete',
-            pluginName,
-            `Hook ${hookName} resolved in ${latency.toFixed(2)}ms`
-          );
-        }
-      };
-
-      const timeoutPromise = new Promise((_, reject) =>
-        setTimeout(() => reject(new Error(`[Timeout] Plugin Execution exceeded 200ms`)), 200)
-      );
-
-      try {
-        // Execution Guarantee: Plugin must resolve within 200ms boundary
-        await Promise.race([hookPromise(), timeoutPromise]);
-      } catch (error) {
-        this._logObservability(
-          'onPluginError',
-          pluginName,
-          `Failed during '${hookName}': ${error.message}`
-        );
-
-        // Isolation Policy: Bubble crash explicitly if registry runs in 'strict' mode
-        if (this.mode === 'strict') {
-          throw error;
-        }
-
-        // Safe mode: Prevent crash mapping downstream
-        if (hookName !== 'onError') {
-          await this.emit('onError', {
-            error,
-            source: `plugin:${pluginName}`,
-            hook: hookName,
-          });
-        }
-      }
-    }
-
-    return stableContext;
-  }
-
-  /**
-   * Internal observability tracking logger to format structured output guarantees
-   */
-  _logObservability(event, pluginName, metadata) {
-    const timestamp = new Date().toISOString();
-    console.log(
-      `[AfriCode Observability] ${timestamp} | EVENT: ${event} | PLUGIN: ${pluginName} | ${metadata}`
-    );
-  }
-
-  /**
-   * Validates the schema of a plugin manifest.
-   */
-  _validateManifest(manifest) {
-    if (!manifest || typeof manifest !== 'object') {
-      throw new Error('[AfriCode Plugin] Plugin manifest must be a valid object.');
-    }
-    if (!manifest.name || typeof manifest.name !== 'string') {
-      throw new Error("[AfriCode Plugin] Plugin manifest is missing a valid 'name' property.");
-    }
-    if (!manifest.version || typeof manifest.version !== 'string') {
-      throw new Error(
-        `[AfriCode Plugin: ${manifest.name}] Manifest is missing a valid 'version' property.`
-      );
-    }
-    if (!manifest.compatibleWith) {
-      throw new Error(
-        `[AfriCode Plugin: ${manifest.name}] Manifest is missing 'compatibleWith' boundary property.`
-      );
-    }
-  }
-
-  /**
-   * Optional lightweight boundary check against standard semantic mapping.
-   */
-  _validateCompatibility(compatibleWith) {
-    // In a full production scenario, use a semantic versioning library.
-    // For v1, we provide a structured warning if versions mismatched wildly.
-    if (typeof compatibleWith !== 'string') {
-      return;
-    }
-
-    // Very basic extraction of major version target (e.g., ^2.0.0 or ~3.0.0)
-    const targetMajor = compatibleWith.match(/\d+/)?.[0];
-    const currentMajor = AFRICODE_VERSION.split('.')[0];
-
-    if (targetMajor && targetMajor !== currentMajor) {
-      console.warn(
-        `[AfriCode Plugin Warning] Plugin requires compatibility '${compatibleWith}' but framework is v${AFRICODE_VERSION}. Unexpected behavior may occur.`
-      );
-    }
-  }
-
-  /**
-   * Ensures plugins only utilize globally permitted v1 hooks.
-   */
-  _validateHooks(pluginName, hooks) {
-    if (!hooks || typeof hooks !== 'object') {
-      throw new Error(`[AfriCode Plugin: ${pluginName}] Hooks object is missing or invalid.`);
-    }
-
-    for (const hookName of Object.keys(hooks)) {
-      if (!ALLOWED_HOOKS.has(hookName)) {
-        throw new Error(
-          `[AfriCode Plugin: ${pluginName}] Invalid hook attempt: '${hookName}'. Authorized hooks are explicitly scoped.`
-        );
-      }
-      if (typeof hooks[hookName] !== 'function') {
-        throw new Error(`[AfriCode Plugin: ${pluginName}] Hook '${hookName}' must be a function.`);
-      }
-    }
-  }
-
-  /**
-   * Scopes the contextual payload based on the specific hook type.
-   * Prevents plugins from pulling down random core internals.
-   */
-  _buildStableContext(hookName, payload = {}) {
-    switch (hookName) {
-      case 'onCliCommandRegister':
-        return {
-          // Safe command registration mechanism
-          registerCommand: (commandName, commandHandler) => {
-            if (PROTECTED_CLI_COMMANDS.has(commandName)) {
-              console.warn(
-                `[AfriCode Plugin] Refused to overwrite core framework CLI command: '${commandName}'.`
-              );
-              return false;
-            }
-            this.pluginCommands.set(commandName, commandHandler);
-            return true;
-          },
-        };
-      case 'onRouteRegister':
-        return {
-          addRoute: payload.addRoute, // The framework passes a strict routing interface
-          router: payload.router,
-        };
-      case 'onServerStart':
-        return { port: payload.port };
-      case 'onStateInit':
-        return { store: payload.store };
-      case 'onComponentRegister':
-        return { componentName: payload.name, componentClass: payload.component };
-      case 'onRequest':
-      case 'onResponse':
-        // Plugins receive specific restricted request/response maps
-        return { req: payload.req, res: payload.res, meta: payload.meta || {} };
-      case 'onError':
-        return { error: payload.error, source: payload.source };
-      case 'onConfigLoad': {
-        // Security Hardening: Never dump RAW process.env unconditionally
-        // Mask sensitive keys by delivering a tailored subset mapping.
-        const env = typeof process !== 'undefined' ? process.env : {};
-        const safeEnvSubset = {
-          NODE_ENV: env.NODE_ENV || 'development',
-          PORT: env.PORT || 3000,
-          // Blacklist database IPs, JWT secrets, Stripe Keys from rogue downstream plugins
-        };
-        return { config: payload.config, env: safeEnvSubset };
-      }
-      default:
-        return payload;
-    }
-  }
-}
-
-// Global static registry instance for core
-export const registry = new AfriPluginRegistry();
+/**
+ * AfriCode Plugin Registry
+ *
+ * A minimal, strict, and predictable plug-in architecture for the AfriCode Framework.
+ * Employs deterministic execution, strong boundary isolation, and a stable context
+ * contract to prevent ecosystem bloat and ensure framework resilience.
+ */
+
+// Core framework version to check plugin compatibility
+export const AFRICODE_VERSION = '5.0.0';
+
+// Only these specific hooks are permitted in v1
+export const ALLOWED_HOOKS = new Set([
+  'onConfigLoad',
+  'onComponentRegister',
+  'onRouteRegister',
+  'onStateInit',
+  'onServerStart',
+  'onRequest',
+  'onResponse',
+  'onError',
+  'onCliCommandRegister',
+]);
+
+// Protected core CLI commands that plugins cannot overwrite
+const PROTECTED_CLI_COMMANDS = new Set([
+  'dev',
+  'build',
+  'start',
+  'test',
+  'lint',
+  'audit',
+  'add',
+  'migrate',
+  'create',
+  'help',
+]);
+
+export class AfriPluginRegistry {
+  constructor(options = {}) {
+    this.plugins = new Map();
+    // Mode mapping: safe (swallow errors), strict (propagate crashes immediately)
+    this.mode = options.mode || 'safe';
+
+    // Plugin state tracking
+    this.disabledPlugins = new Set();
+
+    // Internal structured store for deterministic hook execution (arrays maintain registration order)
+    this.hooks = {
+      onConfigLoad: [],
+      onComponentRegister: [],
+      onRouteRegister: [],
+      onStateInit: [],
+      onServerStart: [],
+      onRequest: [],
+      onResponse: [],
+      onError: [],
+      onCliCommandRegister: [],
+    };
+
+    // Store plugin-registered CLI commands
+    this.pluginCommands = new Map();
+  }
+
+  /**
+   * Registers a new plugin into the framework.
+   * @param {Object} manifest - The Plugin manifest
+   * @param {Object} hooks - The hooks implementation
+   */
+  register(manifest, hooks) {
+    this._validateManifest(manifest);
+    this._validateCompatibility(manifest.compatibleWith);
+    this._validateHooks(manifest.name, hooks);
+
+    if (this.plugins.has(manifest.name)) {
+      console.warn(`[AfriCode Plugin] Plugin '${manifest.name}' is already registered. Skipping.`);
+      return;
+    }
+
+    this.plugins.set(manifest.name, manifest);
+
+    // Bind hooks into the deterministic execution pipeline
+    for (const [hookName, handler] of Object.entries(hooks)) {
+      this.hooks[hookName].push({
+        pluginName: manifest.name,
+        handler,
+      });
+    }
+
+    // Observability Hook
+    this._logObservability('onPluginLoad', manifest.name, `Registered v${manifest.version}`);
+  }
+
+  /**
+   * Disable a plugin at runtime. Safely ejects it from the pipeline.
+   */
+  disable(pluginName) {
+    if (!this.plugins.has(pluginName)) {
+      return;
+    }
+    this.disabledPlugins.add(pluginName);
+    this._logObservability('onPluginDisable', pluginName, 'Plugin forcefully disabled.');
+  }
+
+  /**
+   * Enable a previously disabled plugin.
+   */
+  enable(pluginName) {
+    this.disabledPlugins.delete(pluginName);
+  }
+
+  /**
+   * Returns a stable, public snapshot of the plugin registry for docs/debugging.
+   */
+  getSnapshot() {
+    return {
+      frameworkVersion: AFRICODE_VERSION,
+      mode: this.mode,
+      plugins: [...this.plugins.values()].map((manifest) => ({
+        name: manifest.name,
+        version: manifest.version,
+        compatibleWith: manifest.compatibleWith,
+        hooks: Array.isArray(manifest.hooks) ? [...manifest.hooks] : [],
+        disabled: this.disabledPlugins.has(manifest.name)
+      })),
+      allowedHooks: [...ALLOWED_HOOKS],
+      protectedCliCommands: [...PROTECTED_CLI_COMMANDS]
+    };
+  }
+
+  /**
+   * Returns the canonical plugin lifecycle description.
+   */
+  getLifecycleGuide() {
+    return [
+      { step: 'manifest', description: 'Validate name, version, and compatibleWith.' },
+      { step: 'hooks', description: 'Allow only approved hook names and function handlers.' },
+      { step: 'register', description: 'Bind hooks in registration order.' },
+      { step: 'emit', description: 'Execute with a restricted stable context.' },
+      { step: 'disable', description: 'Skip disabled plugins without mutating the rest.' },
+      { step: 'strict-mode', description: 'Propagate failures immediately when configured.' }
+    ];
+  }
+
+  /**
+   * Execute a specific hook safely across all registered plugins in registration order.
+   * @param {string} hookName - The name of the hook to trigger
+   * @param {Object} context - A stable execution context exposed to plugins
+   */
+  async emit(hookName, context = {}) {
+    if (!ALLOWED_HOOKS.has(hookName)) {
+      throw new Error(`[AfriCode Plugin] Attempted to emit unknown hook: ${hookName}`);
+    }
+
+    const handlers = this.hooks[hookName];
+    if (!handlers || handlers.length === 0) {
+      return context;
+    }
+
+    // Clone context defensively to prevent deep framework mutation
+    // but allow mutations on specifically designed properties.
+    const stableContext = this._buildStableContext(hookName, context);
+
+    for (const { pluginName, handler } of handlers) {
+      if (this.disabledPlugins.has(pluginName)) {
+        continue;
+      } // Skip disabled plugins
+
+      const hookPromise = async () => {
+        const startTime = performance.now();
+        await handler(stableContext);
+        const latency = performance.now() - startTime;
+
+        // Deep trace for heavy hooks taking >50ms
+        if (latency > 50) {
+          this._logObservability(
+            'onHookComplete',
+            pluginName,
+            `Hook ${hookName} resolved in ${latency.toFixed(2)}ms`
+          );
+        }
+      };
+
+      const timeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error(`[Timeout] Plugin Execution exceeded 200ms`)), 200)
+      );
+
+      try {
+        // Execution Guarantee: Plugin must resolve within 200ms boundary
+        await Promise.race([hookPromise(), timeoutPromise]);
+      } catch (error) {
+        this._logObservability(
+          'onPluginError',
+          pluginName,
+          `Failed during '${hookName}': ${error.message}`
+        );
+
+        // Isolation Policy: Bubble crash explicitly if registry runs in 'strict' mode
+        if (this.mode === 'strict') {
+          throw error;
+        }
+
+        // Safe mode: Prevent crash mapping downstream
+        if (hookName !== 'onError') {
+          await this.emit('onError', {
+            error,
+            source: `plugin:${pluginName}`,
+            hook: hookName,
+          });
+        }
+      }
+    }
+
+    return stableContext;
+  }
+
+  /**
+   * Internal observability tracking logger to format structured output guarantees
+   */
+  _logObservability(event, pluginName, metadata) {
+    const timestamp = new Date().toISOString();
+    console.log(
+      `[AfriCode Observability] ${timestamp} | EVENT: ${event} | PLUGIN: ${pluginName} | ${metadata}`
+    );
+  }
+
+  /**
+   * Validates the schema of a plugin manifest.
+   */
+  _validateManifest(manifest) {
+    if (!manifest || typeof manifest !== 'object') {
+      throw new Error('[AfriCode Plugin] Plugin manifest must be a valid object.');
+    }
+    if (!manifest.name || typeof manifest.name !== 'string') {
+      throw new Error("[AfriCode Plugin] Plugin manifest is missing a valid 'name' property.");
+    }
+    if (!manifest.version || typeof manifest.version !== 'string') {
+      throw new Error(
+        `[AfriCode Plugin: ${manifest.name}] Manifest is missing a valid 'version' property.`
+      );
+    }
+    if (!manifest.compatibleWith) {
+      throw new Error(
+        `[AfriCode Plugin: ${manifest.name}] Manifest is missing 'compatibleWith' boundary property.`
+      );
+    }
+  }
+
+  /**
+   * Optional lightweight boundary check against standard semantic mapping.
+   */
+  _validateCompatibility(compatibleWith) {
+    // In a full production scenario, use a semantic versioning library.
+    // For v1, we provide a structured warning if versions mismatched wildly.
+    if (typeof compatibleWith !== 'string') {
+      return;
+    }
+
+    // Very basic extraction of major version target (e.g., ^2.0.0 or ~3.0.0)
+    const targetMajor = compatibleWith.match(/\d+/)?.[0];
+    const currentMajor = AFRICODE_VERSION.split('.')[0];
+
+    if (targetMajor && targetMajor !== currentMajor) {
+      console.warn(
+        `[AfriCode Plugin Warning] Plugin requires compatibility '${compatibleWith}' but framework is v${AFRICODE_VERSION}. Unexpected behavior may occur.`
+      );
+    }
+  }
+
+  /**
+   * Ensures plugins only utilize globally permitted v1 hooks.
+   */
+  _validateHooks(pluginName, hooks) {
+    if (!hooks || typeof hooks !== 'object') {
+      throw new Error(`[AfriCode Plugin: ${pluginName}] Hooks object is missing or invalid.`);
+    }
+
+    for (const hookName of Object.keys(hooks)) {
+      if (!ALLOWED_HOOKS.has(hookName)) {
+        throw new Error(
+          `[AfriCode Plugin: ${pluginName}] Invalid hook attempt: '${hookName}'. Authorized hooks are explicitly scoped.`
+        );
+      }
+      if (typeof hooks[hookName] !== 'function') {
+        throw new Error(`[AfriCode Plugin: ${pluginName}] Hook '${hookName}' must be a function.`);
+      }
+    }
+  }
+
+  /**
+   * Scopes the contextual payload based on the specific hook type.
+   * Prevents plugins from pulling down random core internals.
+   */
+  _buildStableContext(hookName, payload = {}) {
+    switch (hookName) {
+      case 'onCliCommandRegister':
+        return {
+          // Safe command registration mechanism
+          registerCommand: (commandName, commandHandler) => {
+            if (PROTECTED_CLI_COMMANDS.has(commandName)) {
+              console.warn(
+                `[AfriCode Plugin] Refused to overwrite core framework CLI command: '${commandName}'.`
+              );
+              return false;
+            }
+            this.pluginCommands.set(commandName, commandHandler);
+            return true;
+          },
+        };
+      case 'onRouteRegister':
+        return {
+          addRoute: payload.addRoute, // The framework passes a strict routing interface
+          router: payload.router,
+        };
+      case 'onServerStart':
+        return { port: payload.port };
+      case 'onStateInit':
+        return { store: payload.store };
+      case 'onComponentRegister':
+        return { componentName: payload.name, componentClass: payload.component };
+      case 'onRequest':
+      case 'onResponse':
+        // Plugins receive specific restricted request/response maps
+        return { req: payload.req, res: payload.res, meta: payload.meta || {} };
+      case 'onError':
+        return { error: payload.error, source: payload.source };
+      case 'onConfigLoad': {
+        // Security Hardening: Never dump RAW process.env unconditionally
+        // Mask sensitive keys by delivering a tailored subset mapping.
+        const env = typeof process !== 'undefined' ? process.env : {};
+        const safeEnvSubset = {
+          NODE_ENV: env.NODE_ENV || 'development',
+          PORT: env.PORT || 3000,
+          // Blacklist database IPs, JWT secrets, Stripe Keys from rogue downstream plugins
+        };
+        return { config: payload.config, env: safeEnvSubset };
+      }
+      default:
+        return payload;
+    }
+  }
+}
+
+// Global static registry instance for core
+export const registry = new AfriPluginRegistry();