@africode/core 5.0.0

package/bin/africode.js.1758507140

@@ -0,0 +1,343 @@
+#!/usr/bin/env bun
+/**
+ * AfriCode CLI
+ * 
+ * Commands:
+ *   africode dev      - Start development server
+ *   africode build    - Production build
+ *   africode add      - Add component to project
+ * 
+ * @module bin/africode
+ */
+
+// --- SSR DOM SHIM (Must be first) ---
+if (typeof globalThis.HTMLElement === 'undefined') {
+    globalThis.HTMLElement = class HTMLElement { };
+    globalThis.customElements = { define: () => { }, get: () => { } };
+    globalThis.document = {
+        createElement: () => ({
+            classList: { add: () => { } },
+            setAttribute: () => { },
+            style: {}
+        }),
+        head: { appendChild: () => { } },
+        body: { appendChild: () => { } }
+    };
+    globalThis.window = globalThis;
+    globalThis.CSSStyleSheet = class CSSStyleSheet { replaceSync() { } };
+}
+// ------------------------------------
+
+const args = process.argv.slice(2);
+const command = args[0];
+// Allows Web Components to be imported in Node/Bun environment
+if (typeof global !== 'undefined') {
+    global.HTMLElement = class HTMLElement { };
+    global.customElements = {
+        define: () => { },
+        get: () => { }
+    };
+    global.document = {
+        createElement: () => ({ classList: { add: () => { } }, setAttribute: () => { } }),
+        head: { appendChild: () => { } }
+    };
+    global.window = global;
+}
+// --------------------
+
+const colors = {
+    green: '\x1b[32m',
+    gold: '\x1b[33m',
+    blue: '\x1b[34m',
+    red: '\x1b[31m',
+    reset: '\x1b[0m',
+    bold: '\x1b[1m'
+};
+
+function logo() {
+    console.log(`
+${colors.gold}╔═══════════════════════════════════════╗
+║                                       ║
+║   ${colors.green}█████╗ ███████╗██████╗ ██╗${colors.gold}          ║
+║   ${colors.green}██╔══██╗██╔════╝██╔══██╗██║${colors.gold}          ║
+║   ${colors.green}███████║█████╗  ██████╔╝██║${colors.gold}          ║
+║   ${colors.green}██╔══██║██╔══╝  ██╔══██╗██║${colors.gold}          ║
+║   ${colors.green}██║  ██║██║     ██║  ██║██║${colors.gold}          ║
+║   ${colors.green}╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝╚═╝${colors.gold}          ║
+║                                       ║
+║   ${colors.reset}The Rhythmic Web Framework${colors.gold}          ║
+╚═══════════════════════════════════════╝${colors.reset}
+  `);
+}
+
+function help() {
+    logo();
+    console.log(`
+${colors.bold}Usage:${colors.reset}
+  africode <command> [options]
+
+${colors.bold}Commands:${colors.reset}
+  ${colors.green}dev${colors.reset}       Start development server
+  ${colors.green}build${colors.reset}     Create production build
+  ${colors.green}add${colors.reset}       Add a component (e.g., africode add sidebar)
+  ${colors.green}new${colors.reset}       Create a new project (options: --template 3d)
+  ${colors.green}migrate${colors.reset}   Run database migrations
+  ${colors.green}help${colors.reset}      Show this help message
+
+${colors.bold}Examples:${colors.reset}
+  africode dev
+  africode new my-app --template 3d
+  africode add toast
+
+${colors.gold}Powered by the rhythm of the continent.${colors.reset}
+  `);
+}
+
+async function dev() {
+    logo();
+    console.log(`${colors.green}▶ Starting development server...${colors.reset}\n`);
+
+    const server = Bun.serve({
+        port: 3000,
+        async fetch(req) {
+            const url = new URL(req.url);
+            let path = url.pathname;
+
+            // 1. API Route Delegation
+            if (path.startsWith('/api/')) {
+                const { handleApiRequest } = await import('../core/server/router.js');
+                const apiRes = await handleApiRequest(req);
+                if (apiRes) return apiRes;
+            }
+
+            // 2. Root Redirect
+            if (path === '/') path = '/index';
+
+            // 3. JS-First Page Rendering (Next.js Style)
+            // Route /about -> looks for pages/about.js
+            const pageName = path.replace(/^\//, '').replace(/\.html$/, '');
+            const jsPagePath = `./pages/${pageName}.js`;
+
+            if (await Bun.file(jsPagePath).exists()) {
+                try {
+                    // Dynamic Import with Cache Busting (for Hot Reloading in Dev)
+                    const pageModule = await import(`${process.cwd()}/pages/${pageName}.js?t=${Date.now()}`);
+
+                    // execute loader if present
+                    let loaderData = {};
+                    if (typeof pageModule.loader === 'function') {
+                        try {
+                            loaderData = await pageModule.loader({ request: req, params: {} });
+                        } catch (loadErr) {
+                            console.error(`Loader failed for ${pageName}:`, loadErr);
+                            return new Response(`Loader Error: ${loadErr.message}`, { status: 500 });
+                        }
+                    }
+
+                    // Render Default Export
+                    if (typeof pageModule.default === 'function') {
+                        // Pass loader data to the component
+                        const htmlContent = pageModule.default({ data: loaderData });
+                        return new Response(htmlContent, {
+                            headers: { 'Content-Type': 'text/html' }
+                        });
+                    }
+                } catch (err) {
+                    console.error(`Error rendering page ${pageName}:`, err);
+                    return new Response(`Error rendering page: ${err.message}`, { status: 500 });
+                }
+            }
+
+            // 4. Fallback to Static HTML (Legacy Support)
+            // If .js doesn't exist, looking for .html
+            if (await Bun.file(`./pages${path}.html`).exists()) {
+                const { renderPage } = await import('../core/server/render.js');
+                return await renderPage(`./pages${path}.html`);
+            }
+
+            // 5. Static Assets (CSS, Images, etc)
+            const file = Bun.file('.' + url.pathname); // Use original path for assets
+
+            if (await file.exists()) {
+
+                // SSR Hook for HTML
+                if (path.endsWith('.html')) {
+                    const { renderPage } = await import('../core/server/render.js');
+                    return await renderPage('.' + path);
+                }
+
+                const ext = path.split('.').pop();
+                const types = {
+                    html: 'text/html', css: 'text/css', js: 'application/javascript',
+                    json: 'application/json', svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg'
+                };
+                return new Response(file, {
+                    headers: { 'Content-Type': types[ext] || 'application/octet-stream' }
+                });
+            }
+
+            return new Response('404 Not Found', { status: 404 });
+        }
+    });
+
+    console.log(`${colors.green}✓ Server running at ${colors.blue}http://localhost:${server.port}${colors.reset}`);
+    console.log(`${colors.gold}  Press Ctrl+C to stop${colors.reset}\n`);
+}
+
+async function build() {
+    logo();
+    console.log(`${colors.green}▶ Building for production (SSG + Islands)...${colors.reset}\n`);
+
+    const { rm, cp, mkdir, readdir, writeFile } = await import('fs/promises');
+    const path = await import('path');
+    const distDir = './dist';
+    const pagesDir = './pages';
+
+    try {
+        // Clean
+        await rm(distDir, { recursive: true, force: true });
+        await mkdir(distDir);
+
+        // 1. Bundle Core SDK & Components (Islands)
+        console.log('  Bundling JavaScript Islands...');
+        const buildResult = await Bun.build({
+            entrypoints: ['./core/sdk.js', './components/index.js'],
+            outdir: './dist/assets',
+            minify: true,
+            splitting: true,
+            target: 'browser',
+            naming: '[name]-[hash].[ext]' // Cache busting
+        });
+
+        if (!buildResult.success) {
+            throw new Error(buildResult.logs.join('\n'));
+        }
+
+        // 2. Static Site Generation (Pre-rendering)
+        console.log('  Pre-rendering Pages (SSG)...');
+        const pageFiles = await readdir(pagesDir);
+        const routes = [];
+
+        // Need the renderPage logic but adapted for Module imports
+        // We can't easily reuse the dev server logic verbatim, so we implement the SSG loop here.
+
+        for (const file of pageFiles) {
+            if (!file.endsWith('.js')) continue;
+
+            const name = file.replace('.js', '');
+            const route = name === 'index' ? '/' : `/${name}`;
+            routes.push(route);
+
+            console.log(`    • Rendering ${route}...`);
+
+            // Dynamic Import of the Page Component
+            // CAUTION: In a real CLI, we might need to transpile or ignore CSS imports if they exist in JS.
+            // But since we use vanilla JS + tagged templates, it should work in Bun.
+            const pagePath = path.resolve(process.cwd(), pagesDir, file);
+            const pageModule = await import(pagePath);
+
+            // Execute Loader (Server-Side Data Fetching)
+            let loaderData = {};
+            if (typeof pageModule.loader === 'function') {
+                loaderData = await pageModule.loader({ request: new Request(`http://localhost${route}`), params: {} });
+            }
+
+            // Render HTML
+            if (typeof pageModule.default === 'function') {
+                const htmlContent = pageModule.default({ data: loaderData });
+
+                // We need to inject the hashed SDK script paths into the HTML
+                // For simplicity, we'll assume the standard names or use a manifest interaction if we were more advanced.
+                // For now, let's keep the SDK imports standard in Layout (or replace them here).
+                // NOTE: The Layout component currently hardcodes /core/sdk.js. 
+                // To support hashing, we'd need to update Layout or use a transform here. 
+                // We will stick to standard paths for the "Islands" bundles for now to keep it simple.
+                // Or better: write a small logic to replace the script src.
+
+                const outputPath = path.join(distDir, `${name}.html`);
+                await writeFile(outputPath, htmlContent);
+            }
+        }
+
+        // 3. Generate Sitemap
+        console.log('  Generating Sitemap...');
+        const { generateSitemap } = await import('../core/seo.js');
+        const sitemapXml = generateSitemap('https://your-domain.com', routes);
+        await writeFile(path.join(distDir, 'sitemap.xml'), sitemapXml);
+
+        // 4. Copy Static Assets
+        console.log('  Copying Assets...');
+        if (await Bun.file('./styles').exists()) await cp('./styles', `${distDir}/styles`, { recursive: true });
+        // Copy public assets if any (assuming root level assets or create a public folder later)
+
+        // 5. Create Server Entry (Optional, for dynamic hosting)
+        const serverBuild = await Bun.build({
+            entrypoints: ['./server.js'],
+            outdir: './dist',
+            target: 'bun'
+        });
+
+        console.log(`${colors.green}✓ Build complete!${colors.reset}`);
+        console.log(`  Output: ${colors.blue}./dist${colors.reset} (Ready to deploy)`);
+        console.log(`  Pages: ${colors.bold}${routes.length}${colors.reset} pre-rendered`);
+        console.log(`  Sitemap: ${colors.blue}./dist/sitemap.xml${colors.reset}\n`);
+
+    } catch (err) {
+        console.error(`${colors.red}✗ Build failed:${colors.reset}`, err.message || err);
+    }
+}
+
+async function addComponent(name) {
+    if (!name) {
+        console.log(`${colors.red}✗ Please specify a component name${colors.reset}`);
+        console.log(`  Example: africode add sidebar\n`);
+        return;
+    }
+
+    const components = {
+        sidebar: 'af-sidebar',
+        tooltip: 'af-tooltip',
+        toast: 'af-toast',
+        skeleton: 'af-skeleton',
+        dropdown: 'af-dropdown'
+    };
+
+    if (!components[name]) {
+        console.log(`${colors.red}✗ Unknown component: ${name}${colors.reset}`);
+        console.log(`  Available: ${Object.keys(components).join(', ')}\n`);
+        return;
+    }
+
+    console.log(`${colors.green}✓ Component ${colors.gold}${components[name]}${colors.green} is available in AfriCode!${colors.reset}`);
+    console.log(`  Import with: import './components/${name}.js';\n`);
+}
+
+// Command router
+switch (command) {
+    case 'dev':
+        dev();
+        break;
+    case 'build':
+        build();
+        break;
+    case 'add':
+        addComponent(args[1]);
+        break;
+    case 'migrate':
+        const { runMigrations } = await import('../core/cli/migrator.js');
+        await runMigrations();
+        break;
+    case 'new':
+    case 'create':
+    case 'init':
+        const { createProject } = await import('./create-africode.js');
+        await createProject(args[1]);
+        break;
+    case 'help':
+    case '--help':
+    case '-h':
+        help();
+        break;
+    default:
+        help();
+}

package/bin/cli.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env bun
+/**
+ * AfriCode CLI v5.0.0 - Bun-Native Framework Tool
+ * Autonomous application lifecycle management
+ */
+
+import '../core/shim.js';
+import { help } from '../core/cli/ui.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+async function run(): Promise<void> {
+    switch (command) {
+        case 'dev': {
+            const { dev } = await import('../core/cli/commands/dev.js');
+            await dev();
+            break;
+        }
+        case 'build': {
+            const { build } = await import('../core/cli/commands/build.js');
+            await build();
+            break;
+        }
+        case 'add': {
+            const { addComponent } = await import('../core/cli/commands/add.js');
+            await addComponent(args[1]);
+            break;
+        }
+        case 'migrate': {
+            const { runMigrations } = await import('../core/cli/migrator.js');
+            await runMigrations();
+            break;
+        }
+        case 'new':
+        case 'create':
+        case 'init': {
+            if (args[1] === 'plugin') {
+                const { createPlugin } = await import('../core/cli/commands/create-plugin.js');
+                await createPlugin(args[2], args.slice(3));
+            } else {
+                const { createProject } = await import('./scaffold.js');
+                await createProject(args[1]);
+            }
+            break;
+        }
+        case 'lint': {
+            const { lint } = await import('../core/cli/commands/lint.js');
+            await lint();
+            break;
+        }
+        case 'audit': {
+            const { audit } = await import('../core/cli/commands/audit.js');
+            await audit();
+            break;
+        }
+        case 'deploy': {
+            const { deploy } = await import('../core/cli/commands/deploy.js');
+            await deploy();
+            break;
+        }
+        case 'generate': {
+            if (args[1] === 'a2ui') {
+                const { generateA2UISchema } = await import('../core/a2ui-schema-manager.js');
+                await generateA2UISchema();
+            } else if (args[1] === 'patterns') {
+                const { generatePatterns } = await import('../core/patterns.js');
+                await generatePatterns();
+            }
+            break;
+        }
+        case 'help':
+        default: {
+            help();
+            break;
+        }
+    }
+}
+
+run().catch((error) => {
+    console.error('CLI Error:', error.message);
+    process.exit(1);
+});

package/bin/create-africode.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env bun
+/**
+ * create-africode
+ * 
+ * Scaffolds a new AfriCode project by copying the live framework files.
+ * usage: bunx create-africode my-app
+ * 
+ * @module bin/create-africode
+ */
+
+import { mkdir, writeFile, cp, readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const FRAMEWORK_ROOT = path.resolve(__dirname, '..');
+
+const colors = {
+  green: '\x1b[32m',
+  gold: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m'
+};
+
+export async function createProject(targetName) {
+  const projectName = targetName || 'africode-app';
+
+  console.log(`
+${colors.gold}╔═══════════════════════════════════════╗
+║   ${colors.green}Creating AfriCode Project${colors.gold}            ║
+╚═══════════════════════════════════════╝${colors.reset}
+`);
+
+  const projectDir = path.join(process.cwd(), projectName);
+
+  if (existsSync(projectDir)) {
+    console.log(`${colors.red}✗ Directory "${projectName}" already exists${colors.reset}`);
+    process.exit(1);
+  }
+
+  console.log(`${colors.dim}  Creating ${projectName}...${colors.reset}\n`);
+
+  try {
+    // 1. Create Project Root
+    await mkdir(projectDir);
+
+    // 2. Copy Template Files
+    // Support --template arg
+    // node bin/create-africode.js my-app --template 3d
+    const args = process.argv;
+    const templateIdx = args.indexOf('--template');
+    const templateName = templateIdx > -1 ? args[templateIdx + 1] : 'starter';
+
+    // Validate template
+    const validTemplates = ['starter', 'starter-3d', 'starter-tailwind', 'starter-react', '3d', 'tailwind', 'react'];
+    // Map short aliases to full template directory names
+    const aliasMap = { '3d': 'starter-3d', 'tailwind': 'starter-tailwind', 'react': 'starter-react' };
+    const actualTemplate = aliasMap[templateName] || templateName || 'starter';
+
+    const templateDir = path.join(FRAMEWORK_ROOT, 'templates', actualTemplate);
+
+    if (!existsSync(templateDir)) {
+      throw new Error(`Template "${actualTemplate}" not found. Available: starter, tailwind, react, 3d`);
+    }
+
+    console.log(`${colors.blue}ℹ Using template: ${actualTemplate}${colors.reset}`);
+
+    // Recursive copy of the template
+    await cp(templateDir, projectDir, { recursive: true });
+
+
+    // 3. Package.json is already copied from template
+    // We just need to update the name
+    const pkgPath = path.join(projectDir, 'package.json');
+    const pkgData = await readFile(pkgPath, 'utf8');
+    const pkgJson = JSON.parse(pkgData);
+
+    pkgJson.name = projectName;
+
+    await writeFile(pkgPath, JSON.stringify(pkgJson, null, 2));
+
+    // 4. Create bin directory and copy CLI tool (africode.js)
+    // This allows 'bun run bin/africode.js dev' to work in the new project
+    const binSrc = path.join(FRAMEWORK_ROOT, 'bin', 'africode.js');
+    const binDestDir = path.join(projectDir, 'bin');
+    await mkdir(binDestDir, { recursive: true });
+
+    if (existsSync(binSrc)) {
+      await cp(binSrc, path.join(binDestDir, 'africode.js'));
+    } else {
+      console.error(`${colors.red}✗ Critical: CLI entry point not found${colors.reset}`);
+    }
+
+    // 5. Auto-generate index.js if missing
+    const srcDir = path.join(projectDir, 'src');
+    await mkdir(srcDir, { recursive: true });
+    const indexPath = path.join(srcDir, 'index.js');
+    if (!existsSync(indexPath)) {
+      const indexContent = `/**
+ * AfriCode App Entry Point
+ * 
+ * This file exports your app. Modify as needed for your use case:
+ * - Server-side rendering: import Layout from core
+ * - Static site: export your components here
+ * - SPA: import and initialize your router here
+ */
+
+import { Layout } from './core/server/render.js';
+import { html } from './core/html.js';
+
+// Example: Simple HTML page export
+export default function App() {
+  return Layout({
+    title: 'Welcome to AfriCode',
+    children: html\`
+      <main>
+        <h1>Welcome to AfriCode!</h1>
+        <p>Your African-centric full-stack framework is ready.</p>
+        <p><a href="/components">View Components</a> | <a href="/docs">Read Docs</a></p>
+      </main>
+    \`
+  });
+}
+`;
+      await writeFile(indexPath, indexContent);
+      console.log(`${colors.blue}ℹ Generated index.js entry point${colors.reset}`);
+    }
+
+    // 6. Success Message
+    console.log(`${colors.green}✓ Project created successfully!${colors.reset}\n`);
+    console.log(`${colors.bold}Your project contains:${colors.reset}`);
+    console.log(`  ${colors.blue}africode.config.js${colors.reset} - Framework Configuration`);
+    console.log(`  ${colors.blue}src/components/${colors.reset}    - 24+ UI Components`);
+    console.log(`  ${colors.blue}src/styles/${colors.reset}        - Design Tokens`);
+    console.log(`  ${colors.blue}src/pages/${colors.reset}         - Documentation & Demos`);
+    console.log(`  ${colors.blue}src/index.js${colors.reset}       - App Entry Point (auto-generated)`);
+    console.log(`\n${colors.bold}Next steps:${colors.reset}`);
+    console.log(`  ${colors.dim}cd${colors.reset} ${projectName}`);
+    console.log(`  ${colors.dim}bun install${colors.reset} (if needed)`);
+    console.log(`  ${colors.dim}bun run${colors.reset} dev\n`);
+    console.log(`${colors.gold}Happy coding with the rhythm of the continent!${colors.reset}\n`);
+
+  } catch (err) {
+    console.error(`${colors.red}✗ Failed to create project:${colors.reset}`, err);
+    process.exit(1);
+  }
+}
+
+// Allow standalone execution if run directly
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  createProject(args[0]);
+}