@nuraly/lumenjs 0.1.3 → 0.2.0

package/dist/build/serve-ssr.js

@@ -1,22 +1,27 @@
 import fs from 'fs';
 import path from 'path';
-import { stripOuterLitMarkers, dirToLayoutTagName, isRedirectResponse } from '../shared/utils.js';
+import { stripOuterLitMarkers, dirToLayoutTagName, isRedirectResponse, patchLoaderDataSpread } from '../shared/utils.js';
 import { matchRoute } from '../shared/route-matching.js';
 import { sendCompressed } from './serve-static.js';
+import { logger } from '../shared/logger.js';
 export async function handlePageRoute(manifest, serverDir, pagesDir, pathname, queryString, indexHtmlShell, title, ssrRuntime, req, res) {
     // Find matching route (any route, not just those with loaders)
     const allMatched = matchRoute(manifest.routes, pathname);
     // Try SSR for routes with loaders
     const matched = matchRoute(manifest.routes.filter(r => r.hasLoader), pathname);
     if (matched && matched.route.module) {
-        const modulePath = path.join(serverDir, matched.route.module);
+        // Rollup sanitizes brackets in filenames: [...path] → _...path_
+        let modulePath = path.join(serverDir, matched.route.module);
+        if (!fs.existsSync(modulePath)) {
+            modulePath = path.join(serverDir, matched.route.module.replace(/\[/g, '_').replace(/\]/g, '_'));
+        }
         if (fs.existsSync(modulePath)) {
             try {
                 const mod = await import(modulePath);
                 // Run loader
                 let loaderData = undefined;
                 if (mod.loader && typeof mod.loader === 'function') {
-                    loaderData = await mod.loader({ params: matched.params, query: {}, url: pathname, headers: req.headers });
+                    loaderData = await mod.loader({ params: matched.params, query: {}, url: pathname, headers: req.headers, user: req.nkAuth?.user ?? null });
                     if (isRedirectResponse(loaderData)) {
                         res.writeHead(loaderData.status || 302, { Location: loaderData.location });
                         res.end();
@@ -39,7 +44,7 @@ export async function handlePageRoute(manifest, serverDir, pagesDir, pathname, q
                         if (fs.existsSync(layoutModulePath)) {
                             const layoutMod = await import(layoutModulePath);
                             if (layoutMod.loader && typeof layoutMod.loader === 'function') {
-                                layoutLoaderData = await layoutMod.loader({ params: {}, query: {}, url: pathname, headers: req.headers });
+                                layoutLoaderData = await layoutMod.loader({ params: {}, query: {}, url: pathname, headers: req.headers, user: req.nkAuth?.user ?? null });
                                 if (isRedirectResponse(layoutLoaderData)) {
                                     res.writeHead(layoutLoaderData.status || 302, { Location: layoutLoaderData.location });
                                     res.end();
@@ -52,6 +57,12 @@ export async function handlePageRoute(manifest, serverDir, pagesDir, pathname, q
                     layoutsData.push({ loaderPath: dir, data: layoutLoaderData });
                     layoutModules.push({ tagName: layoutTagName, loaderData: layoutLoaderData });
                 }
+                // Patch element classes to spread loaderData into individual properties
+                for (const lm of layoutModules) {
+                    patchLoaderDataSpread(lm.tagName);
+                }
+                if (tagName)
+                    patchLoaderDataSpread(tagName);
                 if (tagName && ssrRuntime) {
                     // SSR render with the bundled @lit-labs/ssr runtime
                     try {
@@ -90,14 +101,18 @@ export async function handlePageRoute(manifest, serverDir, pagesDir, pathname, q
                         const loaderDataScript = ssrDataObj !== undefined
                             ? `<script type="application/json" id="__nk_ssr_data__">${JSON.stringify(ssrDataObj).replace(/</g, '\\u003c')}</script>`
                             : '';
-                        const hydrateScript = `<script type="module">import '@lit-labs/ssr-client/lit-element-hydrate-support.js';</script>`;
+                        // Auth: inline user data for client hydration
+                        const authUser = req.nkAuth?.user ?? null;
+                        const authScript = authUser
+                            ? `<script type="application/json" id="__nk_auth__">${JSON.stringify(authUser).replace(/</g, '\\u003c')}</script>`
+                            : '';
                         let html_out = indexHtmlShell;
-                        html_out = html_out.replace(/<nk-app><\/nk-app>/, `${loaderDataScript}<nk-app data-nk-ssr><div id="nk-router-outlet">${ssrHtml}</div></nk-app>${hydrateScript}`);
+                        html_out = html_out.replace(/<nk-app><\/nk-app>/, `${authScript}${loaderDataScript}<nk-app data-nk-ssr><div id="nk-router-outlet">${ssrHtml}</div></nk-app>`);
                         sendCompressed(req, res, 200, 'text/html; charset=utf-8', html_out);
                         return;
                     }
                     catch (ssrErr) {
-                        console.error('[LumenJS] SSR render failed, falling back to CSR:', ssrErr);
+                        logger.warn('SSR render failed, falling back to CSR', { error: ssrErr?.message });
                     }
                 }
                 // Fallback: inject loader data without SSR HTML
@@ -106,16 +121,28 @@ export async function handlePageRoute(manifest, serverDir, pagesDir, pathname, q
                         ? { page: loaderData, layouts: layoutsData }
                         : loaderData;
                     const loaderDataScript = `<script type="application/json" id="__nk_ssr_data__">${JSON.stringify(ssrDataObj).replace(/</g, '\\u003c')}</script>`;
-                    let html_out = indexHtmlShell.replace('<nk-app>', `${loaderDataScript}<nk-app>`);
+                    const authUserFb = req.nkAuth?.user ?? null;
+                    const authScriptFb = authUserFb
+                        ? `<script type="application/json" id="__nk_auth__">${JSON.stringify(authUserFb).replace(/</g, '\\u003c')}</script>`
+                        : '';
+                    let html_out = indexHtmlShell.replace('<nk-app>', `${authScriptFb}${loaderDataScript}<nk-app>`);
                     sendCompressed(req, res, 200, 'text/html; charset=utf-8', html_out);
                     return;
                 }
             }
             catch (err) {
-                console.error('[LumenJS] Page handler error:', err);
+                logger.error('Page handler error', { error: err?.message });
             }
         }
     }
-    // SPA fallback — serve the built index.html
-    sendCompressed(req, res, 200, 'text/html; charset=utf-8', indexHtmlShell);
+    // SPA fallback — serve the built index.html with auth data injected
+    const fallbackUser = req.nkAuth?.user ?? null;
+    if (fallbackUser) {
+        const authTag = `<script type="application/json" id="__nk_auth__">${JSON.stringify(fallbackUser).replace(/</g, '\\u003c')}</script>`;
+        const html = indexHtmlShell.replace('<nk-app>', `${authTag}<nk-app>`);
+        sendCompressed(req, res, 200, 'text/html; charset=utf-8', html);
+    }
+    else {
+        sendCompressed(req, res, 200, 'text/html; charset=utf-8', indexHtmlShell);
+    }
 }

package/dist/build/serve-static.js

@@ -52,9 +52,9 @@ export function sendCompressed(req, res, statusCode, contentType, body) {
 }
 export function serveStaticFile(clientDir, pathname, req, res) {
     // Prevent directory traversal
-    const safePath = path.normalize(pathname).replace(/^(\.\.[/\\])+/, '');
-    const filePath = path.join(clientDir, safePath);
-    if (!filePath.startsWith(clientDir)) {
+    const resolvedClientDir = path.resolve(clientDir);
+    const filePath = path.resolve(resolvedClientDir, pathname.replace(/^\/+/, ''));
+    if (!filePath.startsWith(resolvedClientDir + path.sep) && filePath !== resolvedClientDir) {
         return false;
     }
     if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory()) {

package/dist/build/serve.js

@@ -10,50 +10,329 @@ import { handlePageRoute } from './serve-ssr.js';
 import { renderErrorPage } from './error-page.js';
 import { handleI18nRequest } from './serve-i18n.js';
 import { resolveLocale } from '../dev-server/middleware/locale.js';
-import { setProjectDir } from '../db/context.js';
+import { runMiddlewareChain, extractMiddleware } from '../shared/middleware-runner.js';
+import { getMiddlewareDirsForPathname } from './scan.js';
+import { createAuthMiddleware } from '../auth/middleware.js';
+import { handleAuthRoutes } from '../auth/routes.js';
+import { loadAuthConfigProd } from '../auth/config.js';
+import { initLogger, logger } from '../shared/logger.js';
+import { createSecurityHeadersMiddleware } from '../shared/security-headers.js';
+import { createRateLimiter, createAuthRateLimiter } from '../shared/rate-limit.js';
+import { createHealthCheckHandler } from '../shared/health.js';
+import { createRequestIdMiddleware } from '../shared/request-id.js';
+import { getRequestId } from '../shared/request-id.js';
+import { setupGracefulShutdown } from '../shared/graceful-shutdown.js';
+import { setupSocketIO } from '../shared/socket-io-setup.js';
+import crypto from 'crypto';
 export async function serveProject(options) {
     const { projectDir } = options;
-    setProjectDir(projectDir);
     const port = options.port || 3000;
     const outDir = path.join(projectDir, '.lumenjs');
     const clientDir = path.join(outDir, 'client');
     const serverDir = path.join(outDir, 'server');
     const manifestPath = path.join(outDir, 'manifest.json');
+    // Initialize structured logging
+    initLogger();
     if (!fs.existsSync(manifestPath)) {
-        console.error('[LumenJS] No build found. Run `lumenjs build` first.');
+        logger.fatal('No build found. Run `lumenjs build` first.');
         process.exit(1);
     }
     const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-    const { title } = readProjectConfig(projectDir);
+    const config = readProjectConfig(projectDir);
+    const { title } = config;
     const localesDir = path.join(outDir, 'locales');
+    // Production middleware stack
+    const requestIdMiddleware = createRequestIdMiddleware();
+    const securityHeaders = createSecurityHeadersMiddleware(config.securityHeaders);
+    const rateLimiter = createRateLimiter(config.rateLimit);
+    const authRateLimiter = createAuthRateLimiter();
+    const healthCheck = createHealthCheckHandler({ version: config.version });
     // Read the built index.html shell
     const indexHtmlPath = path.join(clientDir, 'index.html');
     if (!fs.existsSync(indexHtmlPath)) {
-        console.error('[LumenJS] No index.html found in build output.');
+        logger.fatal('No index.html found in build output.');
         process.exit(1);
     }
-    const indexHtmlShell = fs.readFileSync(indexHtmlPath, 'utf-8');
-    // Load bundled SSR runtime first — it installs @lit-labs/ssr DOM shim
-    // which must be in place before any Lit class is instantiated.
+    let indexHtmlShell = fs.readFileSync(indexHtmlPath, 'utf-8');
+    // Substitute env var placeholders (e.g. __UMAMI_WEBSITE_ID__)
+    indexHtmlShell = indexHtmlShell.replace(/__([A-Z0-9_]+)__/g, (_, key) => process.env[key] || '');
+    // Load bundled SSR runtime first — its install-global-dom-shim sets up
+    // the proper HTMLElement/window/document shims that @lit-labs/ssr needs.
+    // The lit-shared chunk handles missing HTMLElement via a fallback to its own shim,
+    // so no pre-installation is needed.
     const ssrRuntimePath = path.join(serverDir, 'ssr-runtime.js');
     let ssrRuntime = null;
     if (fs.existsSync(ssrRuntimePath)) {
         ssrRuntime = await import(ssrRuntimePath);
     }
     // Install additional DOM shims that NuralyUI components may need
+    // (must run AFTER SSR runtime so we don't block its window/HTMLElement setup)
     installDomShims();
     const pagesDir = path.join(projectDir, 'pages');
+    // Load bundled middleware at startup
+    const middlewareModules = new Map();
+    if (manifest.middlewares) {
+        for (const entry of manifest.middlewares) {
+            const modPath = path.join(serverDir, entry.module);
+            if (fs.existsSync(modPath)) {
+                try {
+                    const mod = await import(modPath);
+                    middlewareModules.set(entry.dir, extractMiddleware(mod));
+                }
+                catch (err) {
+                    logger.error(`Failed to load middleware (${entry.dir || 'root'})`, { error: err?.message });
+                }
+            }
+        }
+    }
+    const middlewareEntries = manifest.middlewares
+        ? manifest.middlewares.map(e => ({ dir: e.dir, filePath: '' }))
+        : [];
+    // Load auth config if present
+    let authConfig = null;
+    let authMiddleware = null;
+    let authDb = null;
+    if (manifest.auth) {
+        try {
+            authConfig = await loadAuthConfigProd(serverDir, manifest.auth.configModule);
+            // Initialize DB for native auth
+            const { hasNativeAuth } = await import('../auth/config.js');
+            if (hasNativeAuth(authConfig)) {
+                try {
+                    const { setProjectDir } = await import('../db/context.js');
+                    const { useDb, waitForMigrations } = await import('../db/index.js');
+                    const { ensureUsersTable } = await import('../auth/native-auth.js');
+                    setProjectDir(projectDir);
+                    authDb = useDb();
+                    await waitForMigrations();
+                    await ensureUsersTable(authDb);
+                    // Run seed if not yet applied (SQLite and PG)
+                    {
+                        const seedModule = path.join(serverDir, 'seed.js');
+                        if (fs.existsSync(seedModule)) {
+                            try {
+                                if (authDb.isPg) {
+                                    await authDb.exec(`CREATE TABLE IF NOT EXISTS _lumen_seed_applied (
+                    name TEXT PRIMARY KEY,
+                    applied_at TIMESTAMP NOT NULL DEFAULT NOW()
+                  )`);
+                                }
+                                else {
+                                    await authDb.exec(`CREATE TABLE IF NOT EXISTS _lumen_seed_applied (
+                    name TEXT PRIMARY KEY,
+                    applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+                  )`);
+                                }
+                                const seedRow = authDb.isPg
+                                    ? await authDb.get('SELECT 1 FROM _lumen_seed_applied WHERE name = $1', 'data/seed.ts')
+                                    : await authDb.get('SELECT 1 FROM _lumen_seed_applied WHERE name = ?', 'data/seed.ts');
+                                if (!seedRow) {
+                                    if (authDb.isPg) {
+                                        await authDb.run('INSERT INTO _lumen_seed_applied (name) VALUES ($1) ON CONFLICT DO NOTHING', 'data/seed.ts');
+                                    }
+                                    else {
+                                        await authDb.run('INSERT OR IGNORE INTO _lumen_seed_applied (name) VALUES (?)', 'data/seed.ts');
+                                    }
+                                    logger.info('Running seed file (prod)...');
+                                    const { default: seedFn } = await import(seedModule);
+                                    if (typeof seedFn === 'function')
+                                        await seedFn();
+                                    logger.info('Seed applied (prod).');
+                                }
+                            }
+                            catch (seedErr) {
+                                try {
+                                    if (authDb.isPg) {
+                                        await authDb.run('DELETE FROM _lumen_seed_applied WHERE name = $1', 'data/seed.ts');
+                                    }
+                                    else {
+                                        await authDb.run('DELETE FROM _lumen_seed_applied WHERE name = ?', 'data/seed.ts');
+                                    }
+                                }
+                                catch { }
+                                logger.warn('Seed failed', { error: seedErr?.message });
+                            }
+                        }
+                    }
+                }
+                catch (dbErr) {
+                    logger.warn('Native auth DB init failed', { error: dbErr?.message });
+                }
+            }
+            authMiddleware = createAuthMiddleware(authConfig, authDb);
+            logger.info('Auth middleware loaded.');
+        }
+        catch (err) {
+            logger.error('Failed to load auth config', { error: err?.message });
+        }
+    }
+    const runMiddleware = (mw, req, res) => new Promise((resolve, reject) => mw(req, res, (err) => err ? reject(err) : resolve()));
     const server = http.createServer(async (req, res) => {
+        const startTime = Date.now();
         const url = req.url || '/';
         const [pathname, queryString] = url.split('?');
         const method = req.method || 'GET';
         try {
-            // 1. API routes
+            // --- Production middleware pipeline ---
+            // Request ID (always first)
+            await runMiddleware(requestIdMiddleware, req, res);
+            // Health check (bypass everything else)
+            let healthHandled = false;
+            await new Promise(resolve => healthCheck(req, res, () => { resolve(); }));
+            if (res.writableEnded)
+                return;
+            // Security headers
+            await runMiddleware(securityHeaders, req, res);
+            // Rate limiting (stricter for auth routes)
+            if (pathname.startsWith('/__nk_auth/')) {
+                await runMiddleware(authRateLimiter, req, res);
+            }
+            else {
+                await runMiddleware(rateLimiter, req, res);
+            }
+            if (res.writableEnded)
+                return;
+            // --- Original request handling ---
+            // -2. Auth session middleware (attach req.nkAuth — must run before auth routes and user middleware)
+            if (authMiddleware && !pathname.includes('.') && !pathname.startsWith('/@')) {
+                await new Promise(resolve => authMiddleware(req, res, resolve));
+                if (res.writableEnded)
+                    return;
+            }
+            // 0. Run user middleware chain (runs before auth routes so middleware can gate signup etc.)
+            if (middlewareModules.size > 0 && !pathname.includes('.') && (!pathname.startsWith('/__nk_') || pathname.startsWith('/__nk_auth/'))) {
+                const matching = getMiddlewareDirsForPathname(pathname, middlewareEntries);
+                const allMw = [];
+                for (const entry of matching) {
+                    const mws = middlewareModules.get(entry.dir);
+                    if (mws)
+                        allMw.push(...mws);
+                }
+                if (allMw.length > 0) {
+                    const err = await new Promise(resolve => runMiddlewareChain(allMw, req, res, resolve));
+                    if (err) {
+                        res.statusCode = 500;
+                        res.end('Internal Server Error');
+                        return;
+                    }
+                    if (res.writableEnded)
+                        return;
+                }
+            }
+            // 1. Auth routes (login, logout, me, signup, etc. — runs after user middleware so invite gate can intercept)
+            if (authConfig && pathname.startsWith('/__nk_auth/')) {
+                const handled = await handleAuthRoutes(authConfig, req, res, authDb);
+                if (handled)
+                    return;
+            }
+            // 2. API routes
             if (pathname.startsWith('/api/')) {
                 await handleApiRoute(manifest, serverDir, pathname, queryString, method, req, res);
                 return;
             }
-            // 2. Static assets — try to serve from client dir
+            // 2b. Communication file upload
+            if (pathname === '/__nk_comm/upload' && method === 'POST') {
+                const userId = req.nkAuth?.user?.sub;
+                if (!userId) {
+                    res.statusCode = 401;
+                    res.end(JSON.stringify({ error: 'Unauthorized' }));
+                    return;
+                }
+                const MAX_UPLOAD_SIZE = 10 * 1024 * 1024;
+                const chunks = [];
+                let uploadSize = 0;
+                let aborted = false;
+                req.on('data', (c) => {
+                    uploadSize += c.length;
+                    if (uploadSize > MAX_UPLOAD_SIZE) {
+                        aborted = true;
+                        req.destroy();
+                        res.statusCode = 413;
+                        res.end(JSON.stringify({ error: 'File too large' }));
+                        return;
+                    }
+                    chunks.push(c);
+                });
+                req.on('end', async () => {
+                    if (aborted)
+                        return;
+                    try {
+                        const body = Buffer.concat(chunks);
+                        const id = crypto.randomUUID();
+                        const fileName = req.headers['x-filename'] || `file-${id}`;
+                        const mimeType = req.headers['content-type'] || 'application/octet-stream';
+                        const ext = fileName.includes('.') ? `.${fileName.split('.').pop()}` : '';
+                        const key = `chat-uploads/${id}${ext}`;
+                        // Use R2/S3 if configured, otherwise fall back to local disk
+                        if (process.env.R2_BUCKET && process.env.R2_ENDPOINT) {
+                            const { S3StorageAdapter } = await import('../storage/adapters/s3.js');
+                            const s3 = new S3StorageAdapter({
+                                bucket: process.env.R2_BUCKET,
+                                region: 'auto',
+                                accessKeyId: process.env.LUMENJS_S3_ACCESS_KEY || '',
+                                secretAccessKey: process.env.LUMENJS_S3_SECRET_KEY || '',
+                                endpoint: process.env.R2_ENDPOINT,
+                                publicBaseUrl: process.env.R2_PUBLIC_URL,
+                            });
+                            const stored = await s3.put(body, { key, mimeType, fileName });
+                            res.statusCode = 201;
+                            res.setHeader('Content-Type', 'application/json');
+                            res.end(JSON.stringify({ id, url: stored.url, size: body.length }));
+                        }
+                        else {
+                            // Local fallback
+                            const uploadDir = path.join(projectDir, 'data', 'uploads');
+                            if (!fs.existsSync(uploadDir))
+                                fs.mkdirSync(uploadDir, { recursive: true });
+                            fs.writeFileSync(path.join(uploadDir, `${id}.bin`), body);
+                            fs.writeFileSync(path.join(uploadDir, `${id}.meta.json`), JSON.stringify({ id, filename: fileName, mimetype: mimeType, size: body.length }));
+                            res.statusCode = 201;
+                            res.setHeader('Content-Type', 'application/json');
+                            res.end(JSON.stringify({ id, url: `/__nk_comm/files/${id}`, size: body.length }));
+                        }
+                    }
+                    catch (err) {
+                        logger.error('Upload failed', { error: err?.message });
+                        res.statusCode = 500;
+                        res.end(JSON.stringify({ error: 'Upload failed' }));
+                    }
+                });
+                return;
+            }
+            // Serve locally stored files (fallback when R2 is not configured)
+            if (pathname.startsWith('/__nk_comm/files/') && method === 'GET') {
+                const fileId = pathname.slice('/__nk_comm/files/'.length);
+                if (!/^[a-zA-Z0-9._-]+$/.test(fileId)) {
+                    res.statusCode = 400;
+                    res.end('Invalid file ID');
+                    return;
+                }
+                const uploadDir = path.join(projectDir, 'data', 'uploads');
+                const filePath = path.resolve(uploadDir, `${fileId}.bin`);
+                if (!filePath.startsWith(path.resolve(uploadDir))) {
+                    res.statusCode = 400;
+                    res.end('Invalid file ID');
+                    return;
+                }
+                if (!fs.existsSync(filePath)) {
+                    res.statusCode = 404;
+                    res.end('File not found');
+                    return;
+                }
+                let contentType = 'application/octet-stream';
+                try {
+                    const meta = JSON.parse(fs.readFileSync(path.resolve(uploadDir, `${fileId}.meta.json`), 'utf-8'));
+                    contentType = meta.mimetype || contentType;
+                }
+                catch { }
+                const stat = fs.statSync(filePath);
+                res.setHeader('Content-Type', contentType);
+                res.setHeader('Content-Length', stat.size);
+                res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+                fs.createReadStream(filePath).pipe(res);
+                return;
+            }
+            // 3. Static assets — try to serve from client dir
             if (pathname.includes('.')) {
                 const served = serveStaticFile(clientDir, pathname, req, res);
                 if (served)
@@ -66,25 +345,26 @@ export async function serveProject(options) {
             }
             // 4. Layout subscribe endpoint (SSE)
             if (pathname === '/__nk_subscribe/__layout/' || pathname === '/__nk_subscribe/__layout') {
-                await handleLayoutSubscribeRequest(manifest, serverDir, queryString, req.headers, res);
+                const authUser = req.nkAuth?.user ?? undefined;
+                await handleLayoutSubscribeRequest(manifest, serverDir, queryString, req.headers, res, authUser);
                 return;
             }
             // 5. Subscribe endpoint (SSE)
             if (pathname.startsWith('/__nk_subscribe/')) {
-                await handleSubscribeRequest(manifest, serverDir, pagesDir, pathname, queryString, req.headers, res);
+                await handleSubscribeRequest(manifest, serverDir, pagesDir, pathname, queryString, req.headers, res, req.nkAuth?.user ?? undefined);
                 return;
             }
             // 6. Layout loader endpoint
             if (pathname === '/__nk_loader/__layout/' || pathname === '/__nk_loader/__layout') {
-                await handleLayoutLoaderRequest(manifest, serverDir, queryString, req.headers, res);
+                await handleLayoutLoaderRequest(manifest, serverDir, queryString, req.headers, res, req.nkAuth?.user ?? undefined);
                 return;
             }
             // 7. Loader endpoint for client-side navigation
             if (pathname.startsWith('/__nk_loader/')) {
-                await handleLoaderRequest(manifest, serverDir, pagesDir, pathname, queryString, req.headers, res);
+                await handleLoaderRequest(manifest, serverDir, pagesDir, pathname, queryString, req.headers, res, req.nkAuth?.user ?? undefined);
                 return;
             }
-            // 6. Resolve locale and strip prefix for page routing
+            // 8. Resolve locale and strip prefix for page routing
             let resolvedPathname = pathname;
             let locale;
             if (manifest.i18n) {
@@ -92,16 +372,59 @@ export async function serveProject(options) {
                 resolvedPathname = result.pathname;
                 locale = result.locale;
             }
-            // 7. Page routes — SSR render
+            // 9. Check for pre-rendered HTML file
+            const prerenderFile = path.join(clientDir, resolvedPathname === '/' ? '' : resolvedPathname, 'index.html');
+            if (resolvedPathname !== '/' && fs.existsSync(prerenderFile)) {
+                const prerenderHtml = fs.readFileSync(prerenderFile, 'utf-8');
+                sendCompressed(req, res, 200, 'text/html; charset=utf-8', prerenderHtml);
+                return;
+            }
+            // Check if the root index.html is a pre-rendered page (has data-nk-ssr attribute)
+            if (resolvedPathname === '/') {
+                const rootRoute = manifest.routes.find(r => r.path === '/');
+                if (rootRoute?.prerender) {
+                    sendCompressed(req, res, 200, 'text/html; charset=utf-8', indexHtmlShell);
+                    return;
+                }
+            }
+            // 10. Page routes — SSR render
             await handlePageRoute(manifest, serverDir, pagesDir, resolvedPathname, queryString, indexHtmlShell, title, ssrRuntime, req, res);
         }
         catch (err) {
-            console.error('[LumenJS] Request error:', err);
+            logger.error('Request error', {
+                method, url: pathname, error: err?.message, stack: err?.stack,
+                requestId: getRequestId(req),
+            });
             const html = renderErrorPage(500, 'Something went wrong', 'An unexpected error occurred while processing your request.', process.env.NODE_ENV !== 'production' ? err?.stack || err?.message : undefined);
             sendCompressed(req, res, 500, 'text/html; charset=utf-8', html);
         }
+        finally {
+            // Log request completion
+            const duration = Date.now() - startTime;
+            logger.request(req, res.statusCode, duration, { requestId: getRequestId(req) });
+        }
+    });
+    // Socket.IO setup (attach before listen so it shares the HTTP server)
+    const socketRoutes = manifest.routes
+        .filter(r => r.hasSocket && r.module)
+        .map(r => ({ path: r.path, hasSocket: true, filePath: path.join(serverDir, r.module) }));
+    if (socketRoutes.length > 0) {
+        setupSocketIO({
+            httpServer: server,
+            loadModule: (fp) => import(fp),
+            routes: socketRoutes,
+            projectDir,
+        }).catch((err) => {
+            logger.warn('Socket.IO setup failed', { error: err?.message });
+        });
+    }
+    // Graceful shutdown
+    setupGracefulShutdown(server, {
+        onShutdown: async () => {
+            logger.info('Cleaning up resources...');
+        },
     });
     server.listen(port, () => {
-        console.log(`[LumenJS] Production server running at http://localhost:${port}`);
+        logger.info(`Production server running at http://localhost:${port}`, { port });
     });
 }

package/dist/cli.js

@@ -9,19 +9,32 @@ function getArg(name) {
     return undefined;
 }
 const USAGE = `Usage:
-  lumenjs dev   [--project <dir>] [--port <port>] [--base <path>] [--editor-mode]
-  lumenjs build [--project <dir>] [--out <dir>]
-  lumenjs serve [--project <dir>] [--port <port>]
-  lumenjs add   <integration>`;
-if (!command || !['dev', 'build', 'serve', 'add'].includes(command)) {
+  lumenjs create <name> [--template <default|blog|dashboard|social>]
+  lumenjs dev    [--project <dir>] [--port <port>] [--base <path>] [--editor-mode]
+  lumenjs build  [--project <dir>] [--out <dir>]
+  lumenjs serve  [--project <dir>] [--port <port>]
+  lumenjs add    <integration>
+  lumenjs db seed [--force] [--project <dir>]`;
+if (!command || !['create', 'dev', 'build', 'serve', 'add', 'db'].includes(command)) {
     console.error(USAGE);
     process.exit(1);
 }
 const projectDir = path.resolve(getArg('project') || '.');
 async function main() {
-    if (command === 'dev') {
+    if (command === 'create') {
+        const { createProject } = await import('./create.js');
+        const name = args[1];
+        const template = getArg('template') || 'default';
+        await createProject(name, template);
+        return;
+    }
+    else if (command === 'dev') {
         const { createDevServer } = await import('./dev-server/server.js');
         const port = parseInt(getArg('port') || '3000', 10);
+        if (isNaN(port) || port < 1 || port > 65535) {
+            console.error(`Invalid port number. Must be between 1 and 65535.`);
+            process.exit(1);
+        }
         const editorMode = args.includes('--editor-mode');
         const base = getArg('base') || '/';
         console.log(`[LumenJS] Starting dev server...`);
@@ -53,11 +66,29 @@ async function main() {
     else if (command === 'serve') {
         const { serveProject } = await import('./build/serve.js');
         const port = parseInt(getArg('port') || '3000', 10);
+        if (isNaN(port) || port < 1 || port > 65535) {
+            console.error(`Invalid port number. Must be between 1 and 65535.`);
+            process.exit(1);
+        }
         console.log(`[LumenJS] Starting production server...`);
         console.log(`  Project: ${projectDir}`);
         console.log(`  Port: ${port}`);
         await serveProject({ projectDir, port });
     }
+    else if (command === 'db') {
+        const subcommand = args[1];
+        if (subcommand === 'seed') {
+            const { setProjectDir } = await import('./db/context.js');
+            const { runSeed } = await import('./db/seed.js');
+            setProjectDir(projectDir);
+            const force = args.includes('--force');
+            await runSeed(projectDir, force);
+        }
+        else {
+            console.error(`Unknown db subcommand: ${subcommand}\n\n${USAGE}`);
+            process.exit(1);
+        }
+    }
 }
 main().catch(err => {
     console.error('[LumenJS] Failed to start:', err);