@zenithbuild/cli 0.4.10 → 0.5.0-beta.2.12

package/dist/dev-server.js

@@ -0,0 +1,214 @@
+// ---------------------------------------------------------------------------
+// dev-server.js — Zenith CLI V0
+// ---------------------------------------------------------------------------
+// Development server with in-memory compilation and file watching.
+//
+// - Compiles pages on demand
+// - Rebuilds on file change
+// - Injects HMR client script
+// - Server route resolution uses manifest matching
+//
+// V0: Uses Node.js http module + fs.watch. No external deps.
+// ---------------------------------------------------------------------------
+
+import { createServer } from 'node:http';
+import { watch } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+import { build } from './build.js';
+import {
+    executeServerScript,
+    injectSsrPayload,
+    loadRouteManifest,
+    resolveWithinDist,
+    toStaticFilePath
+} from './preview.js';
+import { resolveRequestRoute } from './server/resolve-request-route.js';
+
+const MIME_TYPES = {
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.svg': 'image/svg+xml'
+};
+
+const HMR_CLIENT_SCRIPT = `
+<script>
+// Zenith HMR Client V0
+(function() {
+    const es = new EventSource('/__zenith_hmr');
+    es.onmessage = function(event) {
+        if (event.data === 'reload') {
+            window.location.reload();
+        }
+    };
+    es.onerror = function() {
+        setTimeout(function() { window.location.reload(); }, 1000);
+    };
+})();
+</script>`;
+
+/**
+ * Create and start a development server.
+ *
+ * @param {{ pagesDir: string, outDir: string, port?: number, config?: object }} options
+ * @returns {Promise<{ server: import('http').Server, port: number, close: () => void }>}
+ */
+export async function createDevServer(options) {
+    const {
+        pagesDir,
+        outDir,
+        port = 3000,
+        config = {}
+    } = options;
+
+    /** @type {import('http').ServerResponse[]} */
+    const hmrClients = [];
+    let _watcher = null;
+
+    // Initial build
+    await build({ pagesDir, outDir, config });
+
+    const server = createServer(async (req, res) => {
+        const url = new URL(req.url, `http://localhost:${port}`);
+        let pathname = url.pathname;
+
+        // HMR endpoint
+        if (pathname === '/__zenith_hmr') {
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive'
+            });
+            // Flush headers by sending initial comment
+            res.write(': connected\n\n');
+            hmrClients.push(res);
+            req.on('close', () => {
+                const idx = hmrClients.indexOf(res);
+                if (idx !== -1) hmrClients.splice(idx, 1);
+            });
+            return;
+        }
+
+        try {
+            const requestExt = extname(pathname);
+            if (requestExt) {
+                const assetPath = join(outDir, pathname);
+                const asset = await readFile(assetPath);
+                const mime = MIME_TYPES[requestExt] || 'application/octet-stream';
+                res.writeHead(200, { 'Content-Type': mime });
+                res.end(asset);
+                return;
+            }
+
+            const routes = await loadRouteManifest(outDir);
+            const resolved = resolveRequestRoute(url, routes);
+            let filePath = null;
+
+            if (resolved.matched && resolved.route) {
+                console.log(`[zenith] Request: ${pathname} | Route: ${resolved.route.path} | Params: ${JSON.stringify(resolved.params)}`);
+                const output = resolved.route.output.startsWith('/')
+                    ? resolved.route.output.slice(1)
+                    : resolved.route.output;
+                filePath = resolveWithinDist(outDir, output);
+            } else {
+                filePath = toStaticFilePath(outDir, pathname);
+            }
+
+            if (!filePath) {
+                throw new Error('not found');
+            }
+
+            let content = await readFile(filePath, 'utf8');
+            if (resolved.matched && resolved.route?.server_script && resolved.route.prerender !== true) {
+                let payload = null;
+                try {
+                    payload = await executeServerScript({
+                        source: resolved.route.server_script,
+                        sourcePath: resolved.route.server_script_path || '',
+                        params: resolved.params,
+                        requestUrl: url.toString(),
+                        requestMethod: req.method || 'GET',
+                        requestHeaders: req.headers,
+                        routePattern: resolved.route.path,
+                        routeFile: resolved.route.server_script_path || ''
+                    });
+                } catch (error) {
+                    payload = {
+                        __zenith_error: {
+                            status: 500,
+                            code: 'LOAD_FAILED',
+                            message: error instanceof Error ? error.message : String(error)
+                        }
+                    };
+                }
+                if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+                    content = injectSsrPayload(content, payload);
+                }
+            }
+
+            content = content.replace('</body>', `${HMR_CLIENT_SCRIPT}</body>`);
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(content);
+        } catch {
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            res.end('404 Not Found');
+        }
+    });
+
+    /**
+     * Broadcast HMR reload to all connected clients.
+     */
+    function _broadcastReload() {
+        for (const client of hmrClients) {
+            try {
+                client.write('data: reload\n\n');
+            } catch {
+                // client disconnected
+            }
+        }
+    }
+
+    /**
+     * Start watching the pages directory for changes.
+     */
+    function _startWatcher() {
+        try {
+            _watcher = watch(pagesDir, { recursive: true }, async (eventType, filename) => {
+                if (!filename) return;
+
+                // Rebuild
+                await build({ pagesDir, outDir, config });
+                _broadcastReload();
+            });
+        } catch {
+            // fs.watch may not support recursive on all platforms
+        }
+    }
+
+    return new Promise((resolve) => {
+        server.listen(port, () => {
+            const actualPort = server.address().port;
+            _startWatcher();
+
+            resolve({
+                server,
+                port: actualPort,
+                close: () => {
+                    if (_watcher) {
+                        _watcher.close();
+                        _watcher = null;
+                    }
+                    for (const client of hmrClients) {
+                        try { client.end(); } catch { }
+                    }
+                    hmrClients.length = 0;
+                    server.close();
+                }
+            });
+        });
+    });
+}

package/dist/index.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// index.js — Zenith CLI V0 Entry Point
+// ---------------------------------------------------------------------------
+// Commands:
+//   zenith dev      — Development server + HMR
+//   zenith build    — Static site generation to /dist
+//   zenith preview  — Serve /dist statically
+//
+// Minimal arg parsing. No heavy dependencies.
+// ---------------------------------------------------------------------------
+
+import { resolve, join, dirname } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createLogger } from './ui/logger.js';
+
+const COMMANDS = ['dev', 'build', 'preview'];
+const DEFAULT_VERSION = '0.0.0';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function getCliVersion() {
+    try {
+        const pkgPath = join(__dirname, '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : DEFAULT_VERSION;
+    } catch {
+        return DEFAULT_VERSION;
+    }
+}
+
+function printUsage(logger) {
+    logger.heading('V0');
+    logger.print('Usage:');
+    logger.print('  zenith dev [port|--port <port>]      Start development server');
+    logger.print('  zenith build                         Build static site to /dist');
+    logger.print('  zenith preview [port|--port <port>]  Preview /dist statically');
+    logger.print('');
+    logger.print('Options:');
+    logger.print('  -h, --help        Show this help message');
+    logger.print('  -v, --version     Print Zenith CLI version');
+    logger.print('');
+}
+
+function resolvePort(args, fallback) {
+    if (!Array.isArray(args) || args.length === 0) {
+        return fallback;
+    }
+
+    const flagIndex = args.findIndex((arg) => arg === '--port' || arg === '-p');
+    if (flagIndex >= 0 && args[flagIndex + 1]) {
+        const parsed = Number.parseInt(args[flagIndex + 1], 10);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+
+    const positional = args.find((arg) => /^[0-9]+$/.test(arg));
+    if (positional) {
+        const parsed = Number.parseInt(positional, 10);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+
+    return fallback;
+}
+
+/**
+ * Load zenith.config.js from project root.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<object>}
+ */
+async function loadConfig(projectRoot) {
+    const configPath = join(projectRoot, 'zenith.config.js');
+    try {
+        const mod = await import(configPath);
+        return mod.default || {};
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * CLI entry point.
+ *
+ * @param {string[]} args - Process arguments (without node and script paths)
+ * @param {string} [cwd] - Working directory override
+ */
+export async function cli(args, cwd) {
+    const logger = createLogger(process);
+    const command = args[0];
+    const cliVersion = getCliVersion();
+
+    if (args.includes('--version') || args.includes('-v')) {
+        logger.print(`zenith ${cliVersion}`);
+        process.exit(0);
+    }
+
+    if (args.includes('--help') || args.includes('-h')) {
+        printUsage(logger);
+        process.exit(0);
+    }
+
+    if (!command || !COMMANDS.includes(command)) {
+        printUsage(logger);
+        process.exit(command ? 1 : 0);
+    }
+
+    const projectRoot = resolve(cwd || process.cwd());
+    const rootPagesDir = join(projectRoot, 'pages');
+    const srcPagesDir = join(projectRoot, 'src', 'pages');
+    const pagesDir = existsSync(rootPagesDir) ? rootPagesDir : srcPagesDir;
+    const outDir = join(projectRoot, 'dist');
+    const config = await loadConfig(projectRoot);
+
+    if (command === 'build') {
+        const { build } = await import('./build.js');
+        logger.info('Building...');
+        const result = await build({ pagesDir, outDir, config });
+        logger.success(`Built ${result.pages} page(s), ${result.assets.length} asset(s)`);
+        logger.summary([{ label: 'Output', value: './dist' }]);
+    }
+
+    if (command === 'dev') {
+        const { createDevServer } = await import('./dev-server.js');
+        const port = resolvePort(args.slice(1), 3000);
+        logger.info('Starting dev server...');
+        const dev = await createDevServer({ pagesDir, outDir, port, config });
+        logger.success(`Dev server running at http://localhost:${dev.port}`);
+
+        // Graceful shutdown
+        process.on('SIGINT', () => {
+            dev.close();
+            process.exit(0);
+        });
+        process.on('SIGTERM', () => {
+            dev.close();
+            process.exit(0);
+        });
+    }
+
+    if (command === 'preview') {
+        const { createPreviewServer } = await import('./preview.js');
+        const port = resolvePort(args.slice(1), 4000);
+        logger.info('Starting preview server...');
+        const preview = await createPreviewServer({ distDir: outDir, port });
+        logger.success(`Preview server running at http://localhost:${preview.port}`);
+
+        process.on('SIGINT', () => {
+            preview.close();
+            process.exit(0);
+        });
+        process.on('SIGTERM', () => {
+            preview.close();
+            process.exit(0);
+        });
+    }
+}
+
+// Auto-run if called directly
+const isDirectRun = process.argv[1] && (
+    process.argv[1].endsWith('/index.js') ||
+    process.argv[1].endsWith('/zenith')
+);
+
+if (isDirectRun) {
+    cli(process.argv.slice(2)).catch((error) => {
+        const logger = createLogger(process);
+        logger.error(error);
+        process.exit(1);
+    });
+}

package/dist/manifest.js

@@ -0,0 +1,273 @@
+// ---------------------------------------------------------------------------
+// manifest.js — Zenith CLI V0
+// ---------------------------------------------------------------------------
+// File-based manifest engine.
+//
+// Scans a /pages directory and produces a deterministic RouteManifest.
+//
+// Rules:
+//   - index.zen → parent directory path
+//   - [param].zen → :param dynamic segment
+//   - [...slug].zen → *slug catch-all segment (must be terminal, 1+ segments;
+//                     root '/*slug' may match '/' in router matcher)
+//   - [[...slug]].zen → *slug? optional catch-all segment (must be terminal, 0+ segments)
+//   - Deterministic precedence: static > :param > *catchall
+//   - Tie-breaker: lexicographic route path
+// ---------------------------------------------------------------------------
+
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative, sep, basename, extname, dirname } from 'node:path';
+
+/**
+ * @typedef {{ path: string, file: string }} ManifestEntry
+ */
+
+/**
+ * Scan a pages directory and produce a deterministic RouteManifest.
+ *
+ * @param {string} pagesDir - Absolute path to /pages directory
+ * @param {string} [extension='.zen'] - File extension to scan for
+ * @returns {Promise<ManifestEntry[]>}
+ */
+export async function generateManifest(pagesDir, extension = '.zen') {
+    const entries = await _scanDir(pagesDir, pagesDir, extension);
+
+    // Validate: no repeated param names in any single route
+    for (const entry of entries) {
+        _validateParams(entry.path);
+    }
+
+    // Sort: static first, dynamic after, alpha within each category
+    return _sortEntries(entries);
+}
+
+/**
+ * Recursively scan a directory for page files.
+ *
+ * @param {string} dir - Current directory
+ * @param {string} root - Root pages directory
+ * @param {string} ext - Extension to match
+ * @returns {Promise<ManifestEntry[]>}
+ */
+async function _scanDir(dir, root, ext) {
+    /** @type {ManifestEntry[]} */
+    const entries = [];
+
+    let items;
+    try {
+        items = await readdir(dir);
+    } catch {
+        return entries;
+    }
+
+    // Sort items for deterministic traversal
+    items.sort();
+
+    for (const item of items) {
+        const fullPath = join(dir, item);
+        const info = await stat(fullPath);
+
+        if (info.isDirectory()) {
+            const nested = await _scanDir(fullPath, root, ext);
+            entries.push(...nested);
+        } else if (item.endsWith(ext)) {
+            const routePath = _fileToRoute(fullPath, root, ext);
+            entries.push({ path: routePath, file: relative(root, fullPath) });
+        }
+    }
+
+    return entries;
+}
+
+/**
+ * Convert a file path to a route path.
+ *
+ * pages/index.zen       → /
+ * pages/about.zen       → /about
+ * pages/users/[id].zen  → /users/:id
+ * pages/docs/[...slug].zen → /docs/*slug
+ * pages/[[...slug]].zen → /*slug?
+ * pages/docs/api/index.zen → /docs/api
+ *
+ * @param {string} filePath - Absolute file path
+ * @param {string} root - Root pages directory
+ * @param {string} ext - Extension
+ * @returns {string}
+ */
+function _fileToRoute(filePath, root, ext) {
+    const rel = relative(root, filePath);
+    const withoutExt = rel.slice(0, -ext.length);
+
+    // Normalize path separators
+    const segments = withoutExt.split(sep).filter(Boolean);
+
+    // Convert segments
+    const routeSegments = segments.map((seg) => {
+        // [[...param]] → *param? (optional catch-all)
+        const optionalCatchAllMatch = seg.match(/^\[\[\.\.\.([a-zA-Z_][a-zA-Z0-9_]*)\]\]$/);
+        if (optionalCatchAllMatch) {
+            return '*' + optionalCatchAllMatch[1] + '?';
+        }
+
+        // [...param] → *param (required catch-all)
+        const catchAllMatch = seg.match(/^\[\.\.\.([a-zA-Z_][a-zA-Z0-9_]*)\]$/);
+        if (catchAllMatch) {
+            return '*' + catchAllMatch[1];
+        }
+
+        // [param] → :param
+        const paramMatch = seg.match(/^\[([a-zA-Z_][a-zA-Z0-9_]*)\]$/);
+        if (paramMatch) {
+            return ':' + paramMatch[1];
+        }
+        return seg;
+    });
+
+    // Remove trailing 'index'
+    if (routeSegments.length > 0 && routeSegments[routeSegments.length - 1] === 'index') {
+        routeSegments.pop();
+    }
+
+    const route = '/' + routeSegments.join('/');
+    return route;
+}
+
+/**
+ * Validate that a route path has no repeated param names.
+ *
+ * @param {string} routePath
+ * @throws {Error} If repeated params found
+ */
+function _validateParams(routePath) {
+    const segments = routePath.split('/').filter(Boolean);
+    const paramNames = new Set();
+
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (seg.startsWith(':') || seg.startsWith('*')) {
+            const rawName = seg.slice(1);
+            const isCatchAll = seg.startsWith('*');
+            const optionalCatchAll = isCatchAll && rawName.endsWith('?');
+            const name = optionalCatchAll ? rawName.slice(0, -1) : rawName;
+            const label = isCatchAll ? `*${rawName}` : `:${name}`;
+            if (paramNames.has(name)) {
+                throw new Error(
+                    `[Zenith CLI] Repeated param name '${label}' in route '${routePath}'`
+                );
+            }
+            if (isCatchAll && i !== segments.length - 1) {
+                throw new Error(
+                    `[Zenith CLI] Catch-all segment '${label}' must be the last segment in route '${routePath}'`
+                );
+            }
+            paramNames.add(name);
+        }
+    }
+}
+
+/**
+ * Check if a route contains any dynamic segments.
+ *
+ * @param {string} routePath
+ * @returns {boolean}
+ */
+function _isDynamic(routePath) {
+    return routePath.split('/').some((seg) => seg.startsWith(':') || seg.startsWith('*'));
+}
+
+/**
+ * Sort manifest entries by deterministic route precedence.
+ *
+ * @param {ManifestEntry[]} entries
+ * @returns {ManifestEntry[]}
+ */
+function _sortEntries(entries) {
+    return [...entries].sort((a, b) => compareRouteSpecificity(a.path, b.path));
+}
+
+/**
+ * Deterministic route precedence:
+ *   static segment > param segment > catch-all segment.
+ * Tie-breakers: segment count (more specific first), then lexicographic path.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function compareRouteSpecificity(a, b) {
+    if (a === '/' && b !== '/') return -1;
+    if (b === '/' && a !== '/') return 1;
+
+    const aSegs = a.split('/').filter(Boolean);
+    const bSegs = b.split('/').filter(Boolean);
+    const aClass = routeClass(aSegs);
+    const bClass = routeClass(bSegs);
+    if (aClass !== bClass) {
+        return bClass - aClass;
+    }
+
+    const max = Math.min(aSegs.length, bSegs.length);
+
+    for (let i = 0; i < max; i++) {
+        const aWeight = segmentWeight(aSegs[i]);
+        const bWeight = segmentWeight(bSegs[i]);
+        if (aWeight !== bWeight) {
+            return bWeight - aWeight;
+        }
+    }
+
+    if (aSegs.length !== bSegs.length) {
+        return bSegs.length - aSegs.length;
+    }
+
+    return a.localeCompare(b);
+}
+
+/**
+ * @param {string[]} segments
+ * @returns {number}
+ */
+function routeClass(segments) {
+    let hasParam = false;
+    let hasCatchAll = false;
+    for (const segment of segments) {
+        if (segment.startsWith('*')) {
+            hasCatchAll = true;
+        } else if (segment.startsWith(':')) {
+            hasParam = true;
+        }
+    }
+    if (!hasParam && !hasCatchAll) return 3;
+    if (hasCatchAll) return 1;
+    return 2;
+}
+
+/**
+ * @param {string | undefined} segment
+ * @returns {number}
+ */
+function segmentWeight(segment) {
+    if (!segment) return 0;
+    if (segment.startsWith('*')) return 1;
+    if (segment.startsWith(':')) return 2;
+    return 3;
+}
+
+/**
+ * Generate a JavaScript module string from manifest entries.
+ * Used for writing the manifest file to disk.
+ *
+ * @param {ManifestEntry[]} entries
+ * @returns {string}
+ */
+export function serializeManifest(entries) {
+    const lines = entries.map((e) => {
+        const hasParams = _isDynamic(e.path);
+        const loader = hasParams
+            ? `(params) => import('./pages/${e.file}')`
+            : `() => import('./pages/${e.file}')`;
+        return `  { path: '${e.path}', load: ${loader} }`;
+    });
+
+    return `export default [\n${lines.join(',\n')}\n];\n`;
+}