@africode/core 5.0.0

package/core/errors.js

@@ -0,0 +1,222 @@
+/**
+ * AfriCode Error System
+ *
+ * Standardized error hierarchy for the entire framework.
+ * Every error has: code, message, field (optional), context (optional).
+ *
+ * Design:
+ * - All framework errors extend AfriCodeError
+ * - Errors carry structured metadata for programmatic handling
+ * - toJSON() produces a consistent API response format
+ * - Error codes are namespaced: VALIDATION_*, SECURITY_*, DB_*, etc.
+ *
+ * @module core/errors
+ */
+
+/**
+ * Base error class for all AfriCode framework errors.
+ *
+ * @example
+ * throw new AfriCodeError('Something failed', 'GENERIC_ERROR', { detail: '...' });
+ *
+ * @example
+ * // In an API handler:
+ * try { ... } catch (err) {
+ *   if (err instanceof AfriCodeError) {
+ *     return new Response(JSON.stringify(err.toJSON()), { status: err.statusCode });
+ *   }
+ * }
+ */
+export class AfriCodeError extends Error {
+  /**
+   * @param {string} message - Human-readable error message
+   * @param {string} code - Machine-readable error code (e.g. 'VALIDATION_FAILED')
+   * @param {Object} [context={}] - Additional context for debugging
+   * @param {number} [statusCode=500] - HTTP status code
+   */
+  constructor(message, code = 'INTERNAL_ERROR', context = {}, statusCode = 500) {
+    super(message);
+    this.name = 'AfriCodeError';
+    this.code = code;
+    this.context = context;
+    this.statusCode = statusCode;
+    this.timestamp = new Date().toISOString();
+  }
+
+  /**
+   * Produce a consistent JSON structure for API responses.
+   * @returns {Object}
+   */
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.context.field ? { field: this.context.field } : {}),
+        ...(Object.keys(this.context).length > 0 ? { context: this.context } : {})
+      }
+    };
+  }
+
+  /**
+   * Create an HTTP Response from this error.
+   * @returns {Response}
+   */
+  toResponse() {
+    return new Response(JSON.stringify(this.toJSON()), {
+      status: this.statusCode,
+      headers: { 'Content-Type': 'application/json' }
+    });
+  }
+}
+
+/**
+ * Validation error — thrown when input fails schema validation.
+ *
+ * @example
+ * throw new ValidationError("Field 'avatar_url' must be a valid URL or null", 'avatar_url');
+ */
+export class ValidationError extends AfriCodeError {
+  /**
+   * @param {string} message
+   * @param {string} [field] - The field that failed validation
+   * @param {Object} [context={}]
+   */
+  constructor(message, field = null, context = {}) {
+    super(message, 'VALIDATION_FAILED', { field, ...context }, 422);
+    this.name = 'ValidationError';
+  }
+
+  /**
+   * Create a ValidationError from a Zod error.
+   * @param {import('zod').ZodError} zodError
+   * @returns {ValidationError}
+   */
+  static fromZodError(zodError) {
+    const firstIssue = zodError.issues[0];
+    const field = firstIssue?.path?.join('.') || null;
+    const message = firstIssue?.message || 'Validation failed';
+
+    return new ValidationError(message, field, {
+      issues: zodError.issues.map(issue => ({
+        field: issue.path.join('.'),
+        message: issue.message,
+        code: issue.code
+      }))
+    });
+  }
+}
+
+/**
+ * Invalid URL error — specific subtype of validation error for URL fields.
+ *
+ * @example
+ * throw new InvalidUrlError('avatar_url', '');
+ * // → { error: { code: "INVALID_URL", message: "Field 'avatar_url' ...", field: "avatar_url" } }
+ */
+export class InvalidUrlError extends AfriCodeError {
+  /**
+   * @param {string} field - The URL field name
+   * @param {*} value - The invalid value that was provided
+   */
+  constructor(field, value) {
+    const valueDesc = value === '' ? 'an empty string' : `"${value}"`;
+    super(
+      `Field '${field}' must be a valid URL or null. Got ${valueDesc}.`,
+      'INVALID_URL',
+      { field, received: value },
+      422
+    );
+    this.name = 'InvalidUrlError';
+  }
+}
+
+/**
+ * Security error — thrown for CSRF violations, rate limiting, etc.
+ */
+export class SecurityError extends AfriCodeError {
+  /**
+   * @param {string} message
+   * @param {string} [code='SECURITY_VIOLATION']
+   * @param {Object} [context={}]
+   * @param {number} [statusCode=403]
+   */
+  constructor(message, code = 'SECURITY_VIOLATION', context = {}, statusCode = 403) {
+    super(message, code, context, statusCode);
+    this.name = 'SecurityError';
+  }
+}
+
+/**
+ * CSRF error — thrown when CSRF token is missing or mismatched.
+ */
+export class CsrfError extends SecurityError {
+  constructor(reason = 'missing') {
+    const messages = {
+      missing: 'CSRF token missing. Include the token in both the cookie and the X-CSRF-Token header.',
+      mismatch: 'CSRF token mismatch. The header token does not match the cookie token.'
+    };
+    super(messages[reason] || messages.missing, 'CSRF_FAILURE', { reason });
+    this.name = 'CsrfError';
+  }
+}
+
+/**
+ * Rate limit error — thrown when request limit is exceeded.
+ */
+export class RateLimitError extends SecurityError {
+  /**
+   * @param {number} retryAfter - Seconds until the client can retry
+   * @param {string} [message]
+   */
+  constructor(retryAfter, message = 'Too many requests. Please try again later.') {
+    super(message, 'RATE_LIMIT_EXCEEDED', { retryAfter }, 429);
+    this.name = 'RateLimitError';
+  }
+}
+
+/**
+ * Database error — thrown for DB operation failures.
+ */
+export class DatabaseError extends AfriCodeError {
+  /**
+   * @param {string} message
+   * @param {string} [operation] - The operation that failed (e.g. 'INSERT', 'UPDATE')
+   * @param {Object} [context={}]
+   */
+  constructor(message, operation = null, context = {}) {
+    super(message, 'DATABASE_ERROR', { operation, ...context }, 500);
+    this.name = 'DatabaseError';
+  }
+}
+
+/**
+ * Component error — thrown for Web Component failures.
+ */
+export class ComponentError extends AfriCodeError {
+  /**
+   * @param {string} message
+   * @param {string} componentName - The component tag name (e.g. 'af-button')
+   * @param {Object} [context={}]
+   */
+  constructor(message, componentName, context = {}) {
+    super(
+      `Component Error in <${componentName}>: ${message}`,
+      'COMPONENT_ERROR',
+      { componentName, ...context },
+      500
+    );
+    this.name = 'ComponentError';
+  }
+}
+
+export default {
+  AfriCodeError,
+  ValidationError,
+  InvalidUrlError,
+  SecurityError,
+  CsrfError,
+  RateLimitError,
+  DatabaseError,
+  ComponentError
+};

package/core/file-router.js

@@ -0,0 +1,290 @@
+/**
+ * File-Based Router for Bun Runtime
+ * Automatic mapping of /pages directory to URLs
+ * Supports dynamic routes, nested layouts, and API routes
+ */
+
+import { readdirSync, statSync } from 'fs';
+import { join, extname, dirname, relative } from 'path';
+import { fileURLToPath } from 'url';
+
+export class FileBasedRouter {
+    constructor(options = {}) {
+        this.options = {
+            pagesDir: options.pagesDir || 'pages',
+            apiDir: options.apiDir || 'pages/api',
+            layoutsDir: options.layoutsDir || 'layouts',
+            middlewareDir: options.middlewareDir || 'middleware',
+            ...options
+        };
+
+        this.routes = new Map();
+        this.apiRoutes = new Map();
+        this.layouts = new Map();
+        this.middleware = new Map();
+
+        this._scanRoutes();
+    }
+
+    /**
+     * Scan pages directory and build route mappings
+     */
+    _scanRoutes() {
+        const pagesPath = join(process.cwd(), this.options.pagesDir);
+
+        try {
+            this._scanDirectory(pagesPath, '');
+        } catch (error) {
+            console.warn('[Router] Pages directory not found:', pagesPath);
+        }
+    }
+
+    /**
+     * Recursively scan directory for route files
+     */
+    _scanDirectory(dirPath, routePrefix) {
+        const items = readdirSync(dirPath);
+
+        for (const item of items) {
+            const itemPath = join(dirPath, item);
+            const stat = statSync(itemPath);
+
+            if (stat.isDirectory()) {
+                // Handle nested directories
+                const subRoute = routePrefix + '/' + item;
+                this._scanDirectory(itemPath, subRoute);
+            } else if (stat.isFile()) {
+                // Handle route files
+                this._processRouteFile(itemPath, item, routePrefix);
+            }
+        }
+    }
+
+    /**
+     * Process individual route file
+     */
+    _processRouteFile(filePath, filename, routePrefix) {
+        const ext = extname(filename);
+        const name = filename.replace(ext, '');
+
+        // Skip non-route files
+        if (!['.js', '.ts', '.mjs'].includes(ext)) return;
+
+        // Handle API routes
+        if (filePath.includes('/api/') || routePrefix.includes('/api')) {
+            this._addApiRoute(filePath, filename, routePrefix);
+            return;
+        }
+
+        // Handle page routes
+        this._addPageRoute(filePath, filename, routePrefix);
+    }
+
+    /**
+     * Add API route mapping
+     */
+    _addApiRoute(filePath, filename, routePrefix) {
+        let routePath = routePrefix + '/' + filename.replace(/\.(js|ts|mjs)$/, '');
+
+        // Handle dynamic routes
+        routePath = routePath.replace(/\[([^\]]+)\]/g, ':$1');
+
+        // Handle catch-all routes
+        routePath = routePath.replace(/\[\.\.\.([^\]]+)\]/g, '*$1');
+
+        this.apiRoutes.set(routePath, {
+            filePath,
+            handler: null, // Lazy load
+            methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']
+        });
+
+        console.log(`[Router] API Route: ${routePath} -> ${relative(process.cwd(), filePath)}`);
+    }
+
+    /**
+     * Add page route mapping
+     */
+    _addPageRoute(filePath, filename, routePrefix) {
+        let routePath = routePrefix;
+
+        // Handle index files
+        if (filename === 'index.js' || filename === 'index.ts' || filename === 'index.mjs') {
+            // Keep routePrefix as is
+        } else {
+            routePath += '/' + filename.replace(/\.(js|ts|mjs)$/, '');
+        }
+
+        // Handle dynamic routes
+        routePath = routePath.replace(/\[([^\]]+)\]/g, ':$1');
+
+        // Handle catch-all routes
+        routePath = routePath.replace(/\[\.\.\.([^\]]+)\]/g, '*$1');
+
+        // Ensure root route
+        if (routePath === '') routePath = '/';
+
+        this.routes.set(routePath, {
+            filePath,
+            component: null, // Lazy load
+            layout: this._findLayoutForRoute(routePath)
+        });
+
+        console.log(`[Router] Page Route: ${routePath} -> ${relative(process.cwd(), filePath)}`);
+    }
+
+    /**
+     * Find appropriate layout for route
+     */
+    _findLayoutForRoute(routePath) {
+        // Check for nested layouts
+        const segments = routePath.split('/').filter(Boolean);
+        let layoutPath = null;
+
+        // Walk up the route hierarchy
+        for (let i = segments.length; i >= 0; i--) {
+            const testPath = '/' + segments.slice(0, i).join('/');
+            const layoutFile = join(process.cwd(), this.options.layoutsDir, testPath, 'layout.js');
+
+            try {
+                statSync(layoutFile);
+                layoutPath = layoutFile;
+                break;
+            } catch {
+                // Continue searching
+            }
+        }
+
+        // Fallback to root layout
+        if (!layoutPath) {
+            const rootLayout = join(process.cwd(), this.options.layoutsDir, 'layout.js');
+            try {
+                statSync(rootLayout);
+                layoutPath = rootLayout;
+            } catch {
+                // No layout found
+            }
+        }
+
+        return layoutPath;
+    }
+
+    /**
+     * Match incoming request to route
+     */
+    matchRoute(pathname, method = 'GET') {
+        // Check API routes first
+        for (const [routePath, route] of this.apiRoutes) {
+            const params = this._matchRoutePattern(routePath, pathname);
+            if (params && route.methods.includes(method)) {
+                return {
+                    type: 'api',
+                    route: routePath,
+                    filePath: route.filePath,
+                    params,
+                    handler: route.handler
+                };
+            }
+        }
+
+        // Check page routes
+        for (const [routePath, route] of this.routes) {
+            const params = this._matchRoutePattern(routePath, pathname);
+            if (params) {
+                return {
+                    type: 'page',
+                    route: routePath,
+                    filePath: route.filePath,
+                    params,
+                    component: route.component,
+                    layout: route.layout
+                };
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Match route pattern with pathname
+     */
+    _matchRoutePattern(pattern, pathname) {
+        const patternParts = pattern.split('/').filter(Boolean);
+        const pathParts = pathname.split('/').filter(Boolean);
+
+        if (pattern === '/' && pathname === '/') {
+            return {};
+        }
+
+        if (patternParts.length !== pathParts.length && !pattern.includes('*')) {
+            return null;
+        }
+
+        const params = {};
+
+        for (let i = 0; i < patternParts.length; i++) {
+            const patternPart = patternParts[i];
+            const pathPart = pathParts[i];
+
+            if (patternPart.startsWith(':')) {
+                // Dynamic parameter
+                const paramName = patternPart.slice(1);
+                params[paramName] = pathPart;
+            } else if (patternPart.startsWith('*')) {
+                // Catch-all parameter
+                const paramName = patternPart.slice(1);
+                params[paramName] = pathParts.slice(i).join('/');
+                return params; // Catch-all consumes rest
+            } else if (patternPart !== pathPart) {
+                return null;
+            }
+        }
+
+        return params;
+    }
+
+    /**
+     * Load route handler/component lazily
+     */
+    async loadRoute(routeMatch) {
+        if (routeMatch.type === 'api') {
+            if (!routeMatch.handler) {
+                const module = await import(routeMatch.filePath);
+                routeMatch.handler = module.default || module;
+                this.apiRoutes.get(routeMatch.route).handler = routeMatch.handler;
+            }
+            return routeMatch.handler;
+        } else {
+            if (!routeMatch.component) {
+                const module = await import(routeMatch.filePath);
+                routeMatch.component = module.default || module;
+                this.routes.get(routeMatch.route).component = routeMatch.component;
+            }
+            return routeMatch.component;
+        }
+    }
+
+    /**
+     * Get all registered routes
+     */
+    getRoutes() {
+        return {
+            pages: Array.from(this.routes.keys()),
+            apis: Array.from(this.apiRoutes.keys())
+        };
+    }
+
+    /**
+     * Clear route cache (for hot reloading)
+     */
+    clearCache() {
+        for (const route of this.apiRoutes.values()) {
+            route.handler = null;
+        }
+        for (const route of this.routes.values()) {
+            route.component = null;
+        }
+        console.log('[Router] Route cache cleared');
+    }
+}
+
+export default FileBasedRouter;

package/core/heartbeat.js

@@ -0,0 +1,64 @@
+/**
+ * AfriCode Heartbeat (Integrity System)
+ * 
+ * "Unremovable" integrity check that logs usage and validates
+ * the framework environment.
+ * 
+ * @module core/heartbeat
+ */
+
+const HEARTBEAT_KEY = 'af_integrity';
+const FRAMEWORK_VERSION = '1.0.0';
+
+export function initHeartbeat() {
+    // 1. Console Stamp
+    console.log(
+        `%c AfriCode v${FRAMEWORK_VERSION} %c Powered by the Rhythm of the Continent `,
+        'background: #1EB53A; color: white; padding: 4px; border-radius: 4px 0 0 4px; font-weight: bold;',
+        'background: #121212; color: #FCD116; padding: 4px; border-radius: 0 4px 4px 0;'
+    );
+
+    // 2. DOM Injection (Watermark)
+    // Ensures attribution exists in the DOM, invisible but present
+    if (typeof document !== 'undefined') {
+        const meta = document.createElement('meta');
+        meta.name = 'generator';
+        meta.content = `AfriCode ${FRAMEWORK_VERSION}`;
+        document.head.appendChild(meta);
+
+        // "Unremovable" attribute watcher
+        // If someone tries to remove the attribute, it puts it back
+        document.documentElement.setAttribute('data-africode', 'true');
+
+        const observer = new MutationObserver((mutations) => {
+            mutations.forEach((mutation) => {
+                if (mutation.type === 'attributes' && mutation.attributeName === 'data-africode') {
+                    if (!document.documentElement.hasAttribute('data-africode')) {
+                        document.documentElement.setAttribute('data-africode', 'true');
+                        console.warn('AfriCode integrity check: Attribute restored.');
+                    }
+                }
+            });
+        });
+
+        observer.observe(document.documentElement, { attributes: true });
+    }
+
+    // 3. Usage Telemetry (Mock)
+    // In a real scenario, this would POST to a server
+    const usage = {
+        url: typeof window !== 'undefined' ? window.location.href : 'server',
+        timestamp: Date.now(),
+        version: FRAMEWORK_VERSION
+    };
+
+    // Storing locally for now
+    try {
+        localStorage.setItem(HEARTBEAT_KEY, JSON.stringify(usage));
+    } catch (e) {
+        // Ignore in non-browser envs
+    }
+}
+
+// Auto-init on import
+initHeartbeat();