@africode/core 5.0.0

package/core/db.js

@@ -0,0 +1,284 @@
+/**
+ * AfriCode Database Engine
+ * Type-safe SQLite ORM with migrations and schema management
+ *
+ * URL fields (avatar_url, repository_url, demo_url) are validated strictly:
+ * - Valid URL → accepted
+ * - null → accepted (nullable columns)
+ * - "" (empty string) → rejected with error
+ */
+import { Database } from "bun:sqlite";
+import { Validation, schemas } from './validation.js';
+import { InvalidUrlError } from './errors.js';
+import { emitDatabaseError } from './config.js';
+
+// Automatically creates/opens 'afriCode.db' in the project root
+const dbUrl = new URL('../afriCode.db', import.meta.url);
+const isWindows = typeof process !== 'undefined' && process.platform === 'win32';
+const dbPath = decodeURIComponent(isWindows ? dbUrl.pathname.replace(/^\//, '') : dbUrl.pathname);
+const db = new Database(dbPath, { create: true });
+
+// Enable WAL mode for better concurrency
+db.query("PRAGMA journal_mode = WAL;").run();
+
+// Initialize schema
+initSchema();
+
+function initSchema() {
+    // Users table
+    db.query(`
+        CREATE TABLE IF NOT EXISTS users (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            email TEXT UNIQUE NOT NULL,
+            username TEXT UNIQUE NOT NULL,
+            password_hash TEXT NOT NULL,
+            full_name TEXT,
+            avatar_url TEXT,
+            bio TEXT,
+            theme TEXT DEFAULT 'africanity',
+            language TEXT DEFAULT 'en',
+            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+            updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+        )
+    `).run();
+
+    // Projects table
+    db.query(`
+        CREATE TABLE IF NOT EXISTS projects (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT NOT NULL,
+            description TEXT,
+            owner_id INTEGER NOT NULL,
+            is_public BOOLEAN DEFAULT 0,
+            repository_url TEXT,
+            demo_url TEXT,
+            tags TEXT, -- JSON array
+            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+            updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+            FOREIGN KEY (owner_id) REFERENCES users(id)
+        )
+    `).run();
+
+    // Components table for storing custom components
+    db.query(`
+        CREATE TABLE IF NOT EXISTS components (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT UNIQUE NOT NULL,
+            code TEXT NOT NULL,
+            author_id INTEGER NOT NULL,
+            category TEXT,
+            tags TEXT, -- JSON array
+            is_public BOOLEAN DEFAULT 0,
+            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+            updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+            FOREIGN KEY (author_id) REFERENCES users(id)
+        )
+    `).run();
+
+    // Sessions table for auth
+    db.query(`
+        CREATE TABLE IF NOT EXISTS sessions (
+            id TEXT PRIMARY KEY,
+            user_id INTEGER NOT NULL,
+            expires_at DATETIME NOT NULL,
+            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+            FOREIGN KEY (user_id) REFERENCES users(id)
+        )
+    `).run();
+}
+
+/**
+ * Validate URL fields strictly.
+ * Rejects empty strings, accepts valid URLs and null.
+ * Uses standardized InvalidUrlError for consistent error format.
+ *
+ * @param {Object} data - The data object to validate
+ * @param {string[]} urlFields - Field names that should be validated as URLs
+ * @throws {InvalidUrlError} If any URL field contains an empty string or invalid URL
+ */
+function validateUrlFields(data, urlFields) {
+    for (const field of urlFields) {
+        if (!(field in data)) {continue;}
+
+        const value = data[field];
+
+        // null is allowed (nullable columns)
+        if (value === null || value === undefined) {continue;}
+
+        // Empty string is strictly rejected
+        if (value === '') {
+            throw new InvalidUrlError(field, value);
+        }
+
+        // Must be a valid URL
+        try {
+            new URL(value);
+        } catch {
+            throw new InvalidUrlError(field, value);
+        }
+    }
+}
+
+/**
+ * User Model Operations
+ */
+export const User = {
+    create: (userData) => {
+        const { email, username, password_hash, full_name } = userData;
+        const result = run(`
+            INSERT INTO users (email, username, password_hash, full_name)
+            VALUES (?, ?, ?, ?)
+        `, [email, username, password_hash, full_name]);
+        return result.lastInsertRowid;
+    },
+
+    findById: (id) => get('SELECT * FROM users WHERE id = ?', [id]),
+
+    findByEmail: (email) => get('SELECT * FROM users WHERE email = ?', [email]),
+
+    findByUsername: (username) => get('SELECT * FROM users WHERE username = ?', [username]),
+
+    update: (id, updates) => {
+        // Validate URL fields strictly: no empty strings, only valid URLs or null
+        validateUrlFields(updates, ['avatar_url']);
+
+        const fields = Object.keys(updates);
+        const values = Object.values(updates);
+        const setClause = fields.map(field => `${field} = ?`).join(', ');
+        const sql = `UPDATE users SET ${setClause}, updated_at = CURRENT_TIMESTAMP WHERE id = ?`;
+        try {
+            console.log('DB User.update:', { sql, params: [...values, id] });
+            return run(sql, [...values, id]);
+        } catch (err) {
+            console.error('DB User.update error:', err, { sql, params: [...values, id] });
+            throw err;
+        }
+    }
+};
+
+/**
+ * Project Model Operations
+ */
+export const Project = {
+    create: (projectData) => {
+        // Validate URL fields strictly: no empty strings, only valid URLs or null
+        validateUrlFields(projectData, ['repository_url', 'demo_url']);
+
+        const { name, description, owner_id, repository_url, demo_url, tags } = projectData;
+        const result = run(`
+            INSERT INTO projects (name, description, owner_id, repository_url, demo_url, tags)
+            VALUES (?, ?, ?, ?, ?, ?)
+        `, [name, description, owner_id, repository_url || null, demo_url || null, JSON.stringify(tags || [])]);
+        return result.lastInsertRowid;
+    },
+
+    findByUser: (userId, limit = 50) => query(`
+        SELECT p.*, u.username as owner_username
+        FROM projects p
+        JOIN users u ON p.owner_id = u.id
+        WHERE p.owner_id = ? OR p.is_public = 1
+        ORDER BY p.created_at DESC
+        LIMIT ?
+    `, [userId, limit]),
+
+    findById: (id) => get(`
+        SELECT p.*, u.username as owner_username
+        FROM projects p
+        JOIN users u ON p.owner_id = u.id
+        WHERE p.id = ?
+    `, [id])
+};
+
+/**
+ * Component Model Operations
+ */
+export const Component = {
+    create: (componentData) => {
+        const { name, code, author_id, category, tags } = componentData;
+        const result = run(`
+            INSERT INTO components (name, code, author_id, category, tags)
+            VALUES (?, ?, ?, ?, ?)
+        `, [name, code, author_id, category, JSON.stringify(tags || [])]);
+        return result.lastInsertRowid;
+    },
+
+    findPublic: (limit = 100) => query(`
+        SELECT c.*, u.username as author_username
+        FROM components c
+        JOIN users u ON c.author_id = u.id
+        WHERE c.is_public = 1
+        ORDER BY c.created_at DESC
+        LIMIT ?
+    `, [limit]),
+
+    findById: (id) => get(`
+        SELECT c.*, u.username as author_username
+        FROM components c
+        JOIN users u ON c.author_id = u.id
+        WHERE c.id = ?
+    `, [id])
+};
+
+/**
+ * Session Model Operations
+ */
+export const Session = {
+    create: (sessionData) => {
+        const { id, user_id, expires_at } = sessionData;
+        return run(`
+            INSERT INTO sessions (id, user_id, expires_at)
+            VALUES (?, ?, ?)
+        `, [id, user_id, expires_at]);
+    },
+
+    findById: (id) => get(`
+        SELECT s.*, u.username, u.email
+        FROM sessions s
+        JOIN users u ON s.user_id = u.id
+        WHERE s.id = ? AND s.expires_at > CURRENT_TIMESTAMP
+    `, [id]),
+
+    update: (id, updates) => {
+        const fields = Object.keys(updates);
+        const values = Object.values(updates);
+        const setClause = fields.map(field => `${field} = ?`).join(', ');
+        const sql = `UPDATE sessions SET ${setClause} WHERE id = ?`;
+        return run(sql, [...values, id]);
+    },
+
+    delete: (id) => run('DELETE FROM sessions WHERE id = ?', [id]),
+
+    cleanup: () => run('DELETE FROM sessions WHERE expires_at <= CURRENT_TIMESTAMP')
+};
+
+/**
+ * Execute a query and return all results
+ * @param {string} sql - SQL query
+ * @param {Array} params - Binding parameters
+ * @returns {Array} Array of row objects
+ */
+export function query(sql, params = []) {
+    return db.query(sql).all(...params);
+}
+
+/**
+ * Execute a query and return a single result
+ * @param {string} sql - SQL query
+ * @param {Array} params - Binding parameters
+ * @returns {Object} Single row object
+ */
+export function get(sql, params = []) {
+    return db.query(sql).get(...params);
+}
+
+/**
+ * Run a command (INSERT, UPDATE, DELETE)
+ * @param {string} sql - SQL command
+ * @param {Array} params - Binding parameters
+ * @returns {Object} Result info (changes, lastInsertRowid)
+ */
+export function run(sql, params = []) {
+    return db.query(sql).run(...params);
+}
+
+export default { query, get, run, native: db, User, Project, Component, Session };

package/core/enhanced-hmr.js

@@ -0,0 +1,404 @@
+/**
+ * Enhanced HMR Middleware for AfriCode v5.0.0
+ * Zero-downtime hot reload with session preservation
+ *
+ * Features:
+ * - WebSocket-based file watching
+ * - Graceful module replacement
+ * - Database connection persistence
+ * - Session state retention
+ * - Soft reloads without full restart
+ */
+
+import { watch } from 'node:fs';
+import { join, extname, dirname } from 'node:path';
+
+export class EnhancedHMRMiddleware {
+    constructor(options = {}) {
+        this.options = {
+            port: options.port || 3001,
+            watchPaths: options.watchPaths || ['pages', 'components', 'core', 'styles'],
+            ignorePatterns: options.ignorePatterns || [
+                'node_modules',
+                '.git',
+                'dist',
+                '.bun',
+                'build',
+                'coverage',
+                'test-results',
+                '*.test.js',
+                '*.spec.js'
+            ],
+            debounceMs: options.debounceMs || 100,
+            ...options
+        };
+
+        this.clients = new Set();
+        this.watchers = new Map();
+        this.fileChanges = new Map();
+        this.sessions = new Map(); // Store session data during reloads
+        this.dbConnections = new Map(); // Preserve database connections
+    }
+
+    /**
+     * Initialize HMR server with Bun.serve integration
+     */
+    async initialize(devServer) {
+        console.log(`[HMR] Initializing enhanced hot reload on port ${this.options.port}`);
+
+        // Setup WebSocket upgrade handler
+        devServer.upgrade({
+            open: (ws) => this.handleClientConnect(ws),
+            message: (ws, message) => this.handleClientMessage(ws, message),
+            close: (ws) => this.handleClientDisconnect(ws)
+        });
+
+        // Start file watching
+        await this.startFileWatching();
+
+        console.log(`[HMR] Watching ${this.options.watchPaths.length} paths for changes...`);
+    }
+
+    /**
+     * Handle new client connection
+     */
+    handleClientConnect(ws) {
+        console.log(`[HMR] Client connected from ${ws.remoteAddress}`);
+        this.clients.add(ws);
+
+        // Send welcome message with current state
+        ws.send(JSON.stringify({
+            type: 'welcome',
+            timestamp: Date.now(),
+            sessionId: this.generateSessionId()
+        }));
+    }
+
+    /**
+     * Handle client messages (ping, session data, etc.)
+     */
+    handleClientMessage(ws, message) {
+        try {
+            const data = JSON.parse(message);
+
+            switch (data.type) {
+                case 'ping':
+                    ws.send(JSON.stringify({ type: 'pong', timestamp: Date.now() }));
+                    break;
+
+                case 'session-data':
+                    // Store session data for preservation during reloads
+                    this.sessions.set(data.sessionId, data.data);
+                    break;
+
+                case 'db-connection':
+                    // Preserve database connection state
+                    this.dbConnections.set(data.connectionId, data.state);
+                    break;
+
+                default:
+                    console.log(`[HMR] Unknown message type: ${data.type}`);
+            }
+        } catch (error) {
+            console.error('[HMR] Error parsing client message:', error);
+        }
+    }
+
+    /**
+     * Handle client disconnection
+     */
+    handleClientDisconnect(ws) {
+        console.log('[HMR] Client disconnected');
+        this.clients.delete(ws);
+    }
+
+    /**
+     * Start watching files for changes
+     */
+    async startFileWatching() {
+        const watchPromises = this.options.watchPaths.map(path =>
+            this.watchDirectory(path)
+        );
+
+        await Promise.all(watchPromises);
+    }
+
+    /**
+     * Watch a directory recursively
+     */
+    async watchDirectory(dirPath) {
+        try {
+            const watcher = watch(dirPath, { recursive: true }, (eventType, filename) => {
+                if (!filename) return;
+
+                const fullPath = join(dirPath, filename);
+
+                // Check ignore patterns
+                if (this.shouldIgnoreFile(fullPath)) return;
+
+                // Debounce rapid changes
+                const changeKey = fullPath;
+                if (this.fileChanges.has(changeKey)) {
+                    clearTimeout(this.fileChanges.get(changeKey));
+                }
+
+                const timeoutId = setTimeout(() => {
+                    this.handleFileChange(filename, fullPath);
+                    this.fileChanges.delete(changeKey);
+                }, this.options.debounceMs);
+
+                this.fileChanges.set(changeKey, timeoutId);
+            });
+
+            this.watchers.set(dirPath, watcher);
+            console.log(`[HMR] Watching directory: ${dirPath}`);
+
+        } catch (error) {
+            console.error(`[HMR] Failed to watch ${dirPath}:`, error.message);
+        }
+    }
+
+    /**
+     * Check if file should be ignored
+     */
+    shouldIgnoreFile(filePath) {
+        const normalizedPath = filePath.replace(/\\/g, '/');
+
+        return this.options.ignorePatterns.some(pattern => {
+            if (pattern.includes('*')) {
+                // Simple glob matching
+                const regex = new RegExp(pattern.replace(/\*/g, '.*'));
+                return regex.test(normalizedPath);
+            }
+            return normalizedPath.includes(pattern);
+        });
+    }
+
+    /**
+     * Handle file change and determine reload strategy
+     */
+    handleFileChange(filename, fullPath) {
+        const ext = extname(filename);
+        const relativePath = this.getRelativePath(fullPath);
+
+        console.log(`[HMR] File changed: ${relativePath}`);
+
+        // Determine change type and reload strategy
+        const changeType = this.classifyChange(filename, ext);
+
+        switch (changeType) {
+            case 'page':
+                this.handlePageChange(relativePath);
+                break;
+
+            case 'component':
+                this.handleComponentChange(relativePath);
+                break;
+
+            case 'core':
+                this.handleCoreChange(relativePath);
+                break;
+
+            case 'style':
+                this.handleStyleChange(relativePath);
+                break;
+
+            case 'config':
+                this.handleConfigChange(relativePath);
+                break;
+
+            default:
+                this.handleGenericChange(relativePath);
+        }
+    }
+
+    /**
+     * Classify the type of file change
+     */
+    classifyChange(filename, ext) {
+        if (filename.includes('pages/')) {
+            return ext === '.html' ? 'page' : 'api';
+        }
+
+        if (filename.includes('components/')) {
+            return 'component';
+        }
+
+        if (filename.includes('core/')) {
+            return 'core';
+        }
+
+        if (ext === '.css') {
+            return 'style';
+        }
+
+        if (filename.includes('config') || filename.includes('bunfig')) {
+            return 'config';
+        }
+
+        return 'generic';
+    }
+
+    /**
+     * Handle page changes (soft reload)
+     */
+    handlePageChange(relativePath) {
+        this.broadcast({
+            type: 'page-update',
+            path: relativePath,
+            strategy: 'soft-reload',
+            preserveSession: true,
+            timestamp: Date.now()
+        });
+    }
+
+    /**
+     * Handle component changes (hot swap)
+     */
+    handleComponentChange(relativePath) {
+        this.broadcast({
+            type: 'component-update',
+            path: relativePath,
+            strategy: 'hot-swap',
+            componentName: this.extractComponentName(relativePath),
+            timestamp: Date.now()
+        });
+    }
+
+    /**
+     * Handle core module changes (full reload required)
+     */
+    handleCoreChange(relativePath) {
+        console.log(`[HMR] Core module changed, triggering full reload: ${relativePath}`);
+
+        this.broadcast({
+            type: 'core-update',
+            path: relativePath,
+            strategy: 'full-reload',
+            preserveSession: true,
+            preserveConnections: true,
+            timestamp: Date.now()
+        });
+    }
+
+    /**
+     * Handle style changes (CSS injection)
+     */
+    handleStyleChange(relativePath) {
+        this.broadcast({
+            type: 'style-update',
+            path: relativePath,
+            strategy: 'css-injection',
+            timestamp: Date.now()
+        });
+    }
+
+    /**
+     * Handle config changes (server restart)
+     */
+    handleConfigChange(relativePath) {
+        console.log(`[HMR] Config changed, server restart required: ${relativePath}`);
+
+        this.broadcast({
+            type: 'config-update',
+            path: relativePath,
+            strategy: 'server-restart',
+            timestamp: Date.now()
+        });
+    }
+
+    /**
+     * Handle generic file changes
+     */
+    handleGenericChange(relativePath) {
+        this.broadcast({
+            type: 'file-update',
+            path: relativePath,
+            strategy: 'soft-reload',
+            timestamp: Date.now()
+        });
+    }
+
+    /**
+     * Broadcast message to all connected clients
+     */
+    broadcast(message) {
+        const messageStr = JSON.stringify(message);
+
+        for (const client of this.clients) {
+            try {
+                client.send(messageStr);
+            } catch (error) {
+                console.error('[HMR] Failed to send to client:', error);
+                this.clients.delete(client);
+            }
+        }
+    }
+
+    /**
+     * Extract component name from path
+     */
+    extractComponentName(path) {
+        const match = path.match(/components\/([^/]+)\.js$/);
+        return match ? match[1] : 'unknown';
+    }
+
+    /**
+     * Get relative path from project root
+     */
+    getRelativePath(fullPath) {
+        return fullPath.replace(process.cwd() + '/', '');
+    }
+
+    /**
+     * Generate unique session ID
+     */
+    generateSessionId() {
+        return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+
+    /**
+     * Get preserved session data
+     */
+    getSessionData(sessionId) {
+        return this.sessions.get(sessionId) || {};
+    }
+
+    /**
+     * Get preserved database connection state
+     */
+    getConnectionState(connectionId) {
+        return this.dbConnections.get(connectionId) || {};
+    }
+
+    /**
+     * Cleanup watchers on shutdown
+     */
+    async shutdown() {
+        console.log('[HMR] Shutting down...');
+
+        // Close all watchers
+        for (const [path, watcher] of this.watchers) {
+            watcher.close();
+        }
+        this.watchers.clear();
+
+        // Close all client connections
+        for (const client of this.clients) {
+            try {
+                client.close();
+            } catch (error) {
+                // Ignore errors during shutdown
+            }
+        }
+        this.clients.clear();
+
+        // Clear session data
+        this.sessions.clear();
+        this.dbConnections.clear();
+
+        console.log('[HMR] Shutdown complete');
+    }
+}
+
+export default EnhancedHMRMiddleware;