@africode/core 5.0.0

package/core/plugins/index.js

@@ -0,0 +1,312 @@
+/**
+ * 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();

package/core/router.js

@@ -0,0 +1,387 @@
+/**
+ * FileSystemRouter - Next.js style file-based routing for AfriCode
+ *
+ * Maps URL paths to files in the pages directory:
+ * - / → pages/index.html
+ * - /about → pages/about.html
+ * - /users/profile → pages/users/profile.html
+ * - /users/[id] → pages/users/[id].js (dynamic route)
+ * - /api/users → pages/api/users.js (API routes)
+ * - /api/[...slug] → pages/api/[...slug].js (catch-all routes)
+ */
+
+import { readdirSync, statSync } from 'fs';
+import { join, relative, extname } from 'path';
+
+export class FileSystemRouter {
+    constructor(pagesDir = './pages') {
+        this.pagesDir = pagesDir;
+        this.routes = [];        // Ordered routes (dynamic routes last)
+        this.apiRoutes = [];     // API routes
+        this.routeMap = new Map(); // Static routes for fast lookup
+        this.scanRoutes();
+    }
+
+    /**
+     * Recursively scan the pages directory and build route mappings
+     * @private
+     */
+    scanRoutes() {
+        try {
+            this._scanDirectory('', this.pagesDir);
+            
+            // Sort routes: exact matches first, then dynamic, then catch-all
+            this.routes.sort((a, b) => {
+                const aPriority = this._getRoutePriority(a.pattern);
+                const bPriority = this._getRoutePriority(b.pattern);
+                return aPriority - bPriority;
+            });
+            
+            this.apiRoutes.sort((a, b) => {
+                const aPriority = this._getRoutePriority(a.pattern);
+                const bPriority = this._getRoutePriority(b.pattern);
+                return aPriority - bPriority;
+            });
+        } catch (error) {
+            console.warn(`[AfriCode Router] Failed to scan pages directory: ${error.message}`);
+        }
+    }
+
+    /**
+     * Recursively scan a directory for route files
+     * @private
+     */
+    _scanDirectory(prefix, dirPath) {
+        try {
+            const entries = readdirSync(dirPath, { withFileTypes: true });
+
+            for (const entry of entries) {
+                // Skip special files/dirs
+                if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+                    continue;
+                }
+
+                const fullPath = join(dirPath, entry.name);
+                const routePath = prefix ? `${prefix}/${entry.name}` : `/${entry.name}`;
+
+                if (entry.isDirectory()) {
+                    // Recursively scan subdirectories
+                    this._scanDirectory(routePath, fullPath);
+                } else if (this._isRouteFile(entry.name)) {
+                    this._addRoute(routePath, fullPath, entry.name);
+                }
+            }
+        } catch (error) {
+            console.warn(`[AfriCode Router] Failed to scan directory ${dirPath}: ${error.message}`);
+        }
+    }
+
+    /**
+     * Check if a file should be treated as a route
+     * @private
+     */
+    _isRouteFile(filename) {
+        const validExtensions = ['.js', '.jsx', '.ts', '.tsx', '.html'];
+        return validExtensions.some(ext => filename.endsWith(ext)) && 
+               filename !== 'package.json';
+    }
+
+    /**
+     * Add a route from a file
+     * @private
+     */
+    _addRoute(routePath, filePath, filename) {
+        // Remove file extension and trailing index
+        let pattern = routePath.replace(/\.(js|jsx|ts|tsx|html)$/, '');
+        
+        // Handle index.js → /
+        if (pattern.endsWith('/index')) {
+            pattern = pattern.replace(/\/index$/, '') || '/';
+        }
+
+        // Separate API routes from page routes
+        const isApi = pattern.startsWith('/api');
+        
+        // Convert file path to route pattern with params
+        const route = {
+            pattern,
+            filePath,
+            isApi,
+            isDynamic: pattern.includes('['),
+            params: this._extractParams(pattern)
+        };
+
+        // Add to appropriate collection
+        if (isApi) {
+            this.apiRoutes.push(route);
+        } else {
+            this.routes.push(route);
+            // Add exact matches to fast lookup map
+            if (!route.isDynamic) {
+                this.routeMap.set(pattern, route);
+            }
+        }
+    }
+
+    /**
+     * Extract parameter names from route pattern
+     * /users/[id] → ['id']
+     * /posts/[...slug] → ['slug'] (with rest: true)
+     * @private
+     */
+    _extractParams(pattern) {
+        const params = {};
+        const matches = pattern.match(/\[([^\]]+)\]/g) || [];
+        
+        matches.forEach((match, index) => {
+            const name = match.slice(1, -1); // Remove [ and ]
+            if (name.startsWith('...')) {
+                params[name.slice(3)] = { rest: true, index };
+            } else {
+                params[name] = { rest: false, index };
+            }
+        });
+        
+        return params;
+    }
+
+    /**
+     * Get route priority for sorting
+     * Lower number = higher priority
+     * @private
+     */
+    _getRoutePriority(pattern) {
+        // Exact matches: priority 0
+        if (!pattern.includes('[')) {
+            return 0;
+        }
+        
+        // Dynamic with rest params (catch-all): priority 2
+        if (pattern.includes('[...')) {
+            return 2;
+        }
+        
+        // Regular dynamic params: priority 1
+        return 1;
+    }
+
+    /**
+     * Check if a route matches a URL pathname
+     * @private
+     */
+    _matchRoute(route, pathname) {
+        if (!route.isDynamic) {
+            return route.pattern === pathname ? {} : null;
+        }
+
+        const patternParts = route.pattern.split('/').filter(Boolean);
+        const pathParts = pathname.split('/').filter(Boolean);
+
+        // Check if catch-all route
+        const hasCatchAll = Object.values(route.params).some(p => p.rest);
+        
+        if (hasCatchAll) {
+            // Catch-all must match at least as many segments (minus 1 for the catch-all param)
+            if (pathParts.length < patternParts.length - 1) {
+                return null;
+            }
+
+            // Verify static segments match and capture catch-all
+            const params = {};
+            
+            for (let i = 0; i < patternParts.length; i++) {
+                const part = patternParts[i];
+                
+                if (part.startsWith('[...')) {
+                    // Catch-all: capture remaining segments
+                    // [... is 4 chars to remove from start, ] is 1 char from end
+                    const paramName = part.slice(4, -1); // Remove [... and ]
+                    params[paramName] = pathParts.slice(i).join('/');
+                    return params;  // IMPORTANT: Return immediately after matching catch-all
+                } else if (part !== pathParts[i]) {
+                    // Static segment mismatch
+                    return null;
+                }
+            }
+            
+            return params;
+        }
+        
+        // Not a catch-all route
+        if (patternParts.length !== pathParts.length) {
+            return null;
+        }
+
+        // Regular dynamic route matching (NOT catch-all)
+        const params = {};
+        for (let i = 0; i < patternParts.length; i++) {
+            const part = patternParts[i];
+            
+            if (part.startsWith('[')) {
+                // Dynamic segment
+                const paramName = part.slice(1, -1);
+                params[paramName] = pathParts[i];
+            } else if (part !== pathParts[i]) {
+                // Static segment mismatch
+                return null;
+            }
+        }
+
+        return params;
+    }
+
+    /**
+     * Check which route should be used (prioritize based on specificity)
+     * @private
+     */
+    _findBestMatch(pathname) {
+        const exactMatches = [];
+        const dynamicMatches = [];
+        const catchAllMatches = [];
+
+        // Try all routes
+        for (const route of this.routes) {
+            const params = this._matchRoute(route, pathname);
+            if (params !== null) {
+                if (!route.isDynamic) {
+                    exactMatches.push({ route, params });
+                } else if (Object.values(route.params).some(p => p.rest)) {
+                    catchAllMatches.push({ route, params });
+                } else {
+                    dynamicMatches.push({ route, params });
+                }
+            }
+        }
+
+        // Return best match: exact > dynamic > catch-all
+        if (exactMatches.length > 0) return exactMatches[0];
+        if (dynamicMatches.length > 0) return dynamicMatches[0];
+        if (catchAllMatches.length > 0) return catchAllMatches[0];
+        return null;
+    }
+
+    /**
+     * Check which API route should be used (prioritize based on specificity)
+     * @private
+     */
+    _findBestApiMatch(pathname) {
+        const exactMatches = [];
+        const dynamicMatches = [];
+        const catchAllMatches = [];
+
+        // Try all API routes
+        for (const route of this.apiRoutes) {
+            const params = this._matchRoute(route, pathname);
+            if (params !== null) {
+                if (!route.isDynamic) {
+                    exactMatches.push({ route, params });
+                } else if (Object.values(route.params).some(p => p.rest)) {
+                    catchAllMatches.push({ route, params });
+                } else {
+                    dynamicMatches.push({ route, params });
+                }
+            }
+        }
+
+        // Return best match: exact > dynamic > catch-all
+        if (exactMatches.length > 0) return exactMatches[0];
+        if (dynamicMatches.length > 0) return dynamicMatches[0];
+        if (catchAllMatches.length > 0) return catchAllMatches[0];
+        return null;
+    }
+
+    /**
+     * Resolve a URL path to a file path and extract parameters
+     * @param {string} pathname - The URL pathname
+     * @returns {object|null} - { filePath, isApi, params, isDynamic } or null
+     */
+    resolve(pathname) {
+        // Normalize pathname
+        pathname = pathname.startsWith('/') ? pathname : `/${pathname}`;
+        if (pathname.endsWith('/') && pathname !== '/') {
+            pathname = pathname.slice(0, -1);
+        }
+
+        // Fast path for exact matches
+        if (this.routeMap.has(pathname)) {
+            const route = this.routeMap.get(pathname);
+            return {
+                filePath: route.filePath,
+                isApi: route.isApi,
+                params: {},
+                isDynamic: false
+            };
+        }
+
+        // Check API routes first
+        const apiMatch = this._findBestApiMatch(pathname);
+        if (apiMatch) {
+            return {
+                filePath: apiMatch.route.filePath,
+                isApi: true,
+                params: apiMatch.params,
+                isDynamic: apiMatch.route.isDynamic
+            };
+        }
+
+        // Check page routes
+        const pageMatch = this._findBestMatch(pathname);
+        if (pageMatch) {
+            return {
+                filePath: pageMatch.route.filePath,
+                isApi: false,
+                params: pageMatch.params,
+                isDynamic: pageMatch.route.isDynamic
+            };
+        }
+
+        return null;
+    }
+
+    /**
+     * Get all registered routes for debugging/manifest
+     */
+    getRoutes() {
+        return {
+            pages: this.routes.map(r => ({
+                pattern: r.pattern,
+                file: r.filePath,
+                isDynamic: r.isDynamic
+            })),
+            apis: this.apiRoutes.map(r => ({
+                pattern: r.pattern,
+                file: r.filePath,
+                isDynamic: r.isDynamic
+            }))
+        };
+    }
+
+    /**
+     * Get route manifest for build/analysis
+     */
+    getManifest() {
+        const manifest = {
+            timestamp: new Date().toISOString(),
+            pages: {},
+            apis: {}
+        };
+
+        for (const route of this.routes) {
+            manifest.pages[route.pattern] = {
+                file: relative(this.pagesDir, route.filePath),
+                dynamic: route.isDynamic,
+                params: route.params
+            };
+        }
+
+        for (const route of this.apiRoutes) {
+            manifest.apis[route.pattern] = {
+                file: relative(this.pagesDir, route.filePath),
+                dynamic: route.isDynamic,
+                params: route.params
+            };
+        }
+
+        return manifest;
+    }
+}