nuclie 1.0.0

package/dist/dev/overlay/overlay-ui.js

@@ -0,0 +1,133 @@
+/**
+ * Nuclie Error Overlay UI
+ * Implementation: Web Component with Shadow DOM
+ * Day 15: Reliable Error Overlay Lock
+ */
+const STYLE = `
+:host {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  z-index: 99999;
+  font-family: Menlo, Consolas, monospace;
+  background: rgba(0, 0, 0, 0.95);
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  color: #fff;
+}
+
+.window {
+  background: #1e1e1e;
+  width: 80%;
+  max-width: 800px;
+  max-height: 80%;
+  border-radius: 8px;
+  box-shadow: 0 4px 20px rgba(0,0,0,0.5);
+  border: 1px solid #ff4444;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.header {
+  background: #ff4444;
+  color: white;
+  padding: 12px 20px;
+  font-weight: bold;
+  font-size: 16px;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.close-btn {
+  background: transparent;
+  border: none;
+  font-size: 20px;
+  cursor: pointer;
+  color: white;
+}
+
+.content {
+  padding: 20px;
+  overflow-y: auto;
+}
+
+.message {
+  font-size: 18px;
+  line-height: 1.4;
+  margin-bottom: 20px;
+  font-weight: 600;
+  color: #ffcccc;
+}
+
+.stack {
+  background: #000;
+  padding: 15px;
+  border-radius: 4px;
+  font-size: 14px;
+  line-height: 1.5;
+  color: #aaddff;
+  white-space: pre-wrap;
+  font-family: inherit;
+}
+
+.file-link {
+  color: #44aaff;
+  text-decoration: underline;
+  cursor: pointer;
+}
+`;
+export class NuclieErrorOverlay extends HTMLElement {
+    constructor() {
+        super();
+        this.root = this.attachShadow({ mode: 'open' });
+    }
+    connectedCallback() {
+        this.render();
+    }
+    showError(err) {
+        // Clean existing
+        this.root.innerHTML = '';
+        const style = document.createElement('style');
+        style.textContent = STYLE;
+        this.root.appendChild(style);
+        const win = document.createElement('div');
+        win.className = 'window';
+        // Header
+        const header = document.createElement('div');
+        header.className = 'header';
+        header.innerHTML = `<span>Error in ${err.file || 'Application'}</span>`;
+        const close = document.createElement('button');
+        close.className = 'close-btn';
+        close.textContent = '×';
+        close.onclick = () => this.remove();
+        header.appendChild(close);
+        win.appendChild(header);
+        // Content
+        const content = document.createElement('div');
+        content.className = 'content';
+        const msg = document.createElement('div');
+        msg.className = 'message';
+        msg.textContent = err.message;
+        content.appendChild(msg);
+        if (err.stack) {
+            const stack = document.createElement('pre');
+            stack.className = 'stack';
+            // Simple robust stack formatting
+            stack.textContent = err.stack.replace(err.message, '').trim();
+            content.appendChild(stack);
+        }
+        win.appendChild(content);
+        this.root.appendChild(win);
+    }
+    render() {
+        // Initial render logic if needed
+    }
+}
+if (!customElements.get('nuclie-error-overlay')) {
+    customElements.define('nuclie-error-overlay', NuclieErrorOverlay);
+}

package/dist/dev/preBundler.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Production-Ready Dependency Pre-Bundler
+ * Uses full dependency graph bundling with splitting
+ * Handles transitive dependencies automatically
+ */
+export declare class DependencyPreBundler {
+    private root;
+    private cacheDir;
+    constructor(root: string, cacheDir?: string);
+    /**
+     * Pre-bundle dependencies using full graph approach
+     * This bundles ALL dependencies together with their transitive deps
+     * Uses esbuild's splitting to create shared chunks
+     */
+    preBundleDependencies(deps: string[]): Promise<Map<string, string>>;
+    scanDependencies(entryFile: string): Promise<string[]>;
+}

package/dist/dev/preBundler.js

@@ -0,0 +1,343 @@
+import path from 'path';
+import fs from 'fs/promises';
+import { build } from 'esbuild';
+import { createHash } from 'crypto';
+import { createRequire } from 'module';
+import { log } from '../utils/logger.js';
+const require = createRequire(import.meta.url);
+/**
+ * Production-Ready Dependency Pre-Bundler
+ * Uses full dependency graph bundling with splitting
+ * Handles transitive dependencies automatically
+ */
+export class DependencyPreBundler {
+    constructor(root, cacheDir = 'node_modules/.nuclie') {
+        this.root = root;
+        this.cacheDir = cacheDir;
+    }
+    /**
+     * Pre-bundle dependencies using full graph approach
+     * This bundles ALL dependencies together with their transitive deps
+     * Uses esbuild's splitting to create shared chunks
+     */
+    async preBundleDependencies(deps) {
+        const bundledDeps = new Map();
+        const cacheDir = path.join(this.root, this.cacheDir);
+        // Ensure cache directory exists
+        await fs.mkdir(cacheDir, { recursive: true });
+        // Generate hash of package.json for cache invalidation
+        const pkgJsonPath = path.join(this.root, 'package.json');
+        const pkgJson = await fs.readFile(pkgJsonPath, 'utf-8');
+        const hash = createHash('md5').update(pkgJson).digest('hex').slice(0, 8);
+        const metaPath = path.join(cacheDir, '_metadata.json');
+        // Check if cache is valid
+        let cachedMeta = {};
+        try {
+            cachedMeta = JSON.parse(await fs.readFile(metaPath, 'utf-8'));
+            if (cachedMeta.hash === hash && cachedMeta.deps?.length === deps.length) {
+                log.info('Using cached pre-bundled dependencies');
+                // Load from cache
+                for (const dep of deps) {
+                    const cachedPath = cachedMeta.depMap?.[dep];
+                    if (cachedPath) {
+                        bundledDeps.set(dep, cachedPath);
+                    }
+                }
+                if (bundledDeps.size === deps.length) {
+                    return bundledDeps;
+                }
+            }
+        }
+        catch {
+            // No cache or invalid, proceed with bundling
+        }
+        log.info('--> Pipeline: Pre-bundling dependencies...', { count: deps.length });
+        const root = this.root;
+        // Helper to check if file exists
+        const fileExists = async (p) => {
+            try {
+                await fs.access(p);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        // Helper to find node_modules up the tree
+        const findNodeModules = async (startDir, pkgName) => {
+            let current = startDir;
+            while (current !== path.parse(current).root) {
+                const maybe = path.join(current, 'node_modules', pkgName);
+                if (await fileExists(maybe))
+                    return maybe;
+                const parent = path.dirname(current);
+                if (parent === current)
+                    break;
+                current = parent;
+            }
+            return undefined;
+        };
+        try {
+            // Resolve all entry points
+            const entryPoints = {};
+            for (const dep of deps) {
+                let resolvedPath;
+                // Priority: Try to find package.json and use 'module' field (ESM)
+                try {
+                    // Find package root
+                    const pkgName = dep.startsWith('@') ? dep.split('/').slice(0, 2).join('/') : dep.split('/')[0];
+                    let pkgDir;
+                    try {
+                        const pkgJsonResolved = require.resolve(pkgName + '/package.json', { paths: [root] });
+                        pkgDir = path.dirname(pkgJsonResolved);
+                    }
+                    catch (e) {
+                        // Manual search up the tree
+                        pkgDir = await findNodeModules(root, pkgName);
+                        // log.debug(`[PreBundler] JSON resolve failed for ${pkgName}, using fallback: ${pkgDir}`);
+                    }
+                    if (pkgDir) {
+                        const pkgJsonPath = path.join(pkgDir, 'package.json');
+                        try {
+                            const pkgJsonRaw = await fs.readFile(pkgJsonPath, 'utf-8');
+                            const pkgJson = JSON.parse(pkgJsonRaw);
+                            // log.debug(`[PreBundler] Checked ${pkgName} package.json. Module: ${pkgJson.module}`);
+                            // 1. Check 'exports' (Modern Node Resolution - Precedence over 'module')
+                            if (pkgJson.exports) {
+                                let exportKey = '.';
+                                if (dep !== pkgName) {
+                                    // Calculate subpath: preact/hooks -> ./hooks
+                                    const subpath = './' + dep.substring(pkgName.length + 1);
+                                    exportKey = subpath;
+                                }
+                                if (typeof pkgJson.exports === 'object') {
+                                    const exportEntry = pkgJson.exports[exportKey];
+                                    if (exportEntry) {
+                                        // Handle nested conditions (browser > import > default > node > source)
+                                        const resolveCondition = (entry) => {
+                                            if (typeof entry === 'string')
+                                                return entry;
+                                            if (typeof entry === 'object' && entry !== null) {
+                                                return resolveCondition(entry.browser) ||
+                                                    resolveCondition(entry.import) ||
+                                                    resolveCondition(entry.default) ||
+                                                    resolveCondition(entry.node) ||
+                                                    resolveCondition(entry.source) ||
+                                                    resolveCondition(entry.require);
+                                            }
+                                            return undefined;
+                                        };
+                                        const importPath = resolveCondition(exportEntry);
+                                        if (importPath) {
+                                            const candidate = path.join(pkgDir, importPath);
+                                            if (await fileExists(candidate)) {
+                                                resolvedPath = candidate;
+                                                log.debug(`[PreBundler] Resolved via exports for ${dep}: ${resolvedPath}`);
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                            // 2. Fallback to 'module' or 'source' (only for main entry)
+                            if (!resolvedPath && dep === pkgName) {
+                                if (pkgJson.module && await fileExists(path.join(pkgDir, pkgJson.module))) {
+                                    resolvedPath = path.join(pkgDir, pkgJson.module);
+                                }
+                                else if (pkgJson.source && await fileExists(path.join(pkgDir, pkgJson.source))) {
+                                    resolvedPath = path.join(pkgDir, pkgJson.source);
+                                    log.debug(`[PreBundler] Using 'source' field for ${dep}: ${resolvedPath}`);
+                                }
+                                else if (pkgJson.main && await fileExists(path.join(pkgDir, pkgJson.main))) {
+                                    resolvedPath = path.join(pkgDir, pkgJson.main);
+                                }
+                            }
+                        }
+                        catch (e) {
+                            log.warn(`[PreBundler] Failed to read/parse package.json for ${pkgName}: ${e.message}`);
+                        }
+                    }
+                }
+                catch (e) {
+                    log.warn(`[PreBundler] ESM resolution error for ${dep}: ${e.message}`);
+                }
+                // Fallback to require.resolve (Standard Node Resolution)
+                if (!resolvedPath) {
+                    try {
+                        const cand = require.resolve(dep, { paths: [root] });
+                        if (await fileExists(cand)) {
+                            resolvedPath = cand;
+                        }
+                    }
+                    catch (e) {
+                        try {
+                            const maybeDirect = path.join(root, 'node_modules', dep);
+                            if (await fileExists(maybeDirect))
+                                resolvedPath = maybeDirect;
+                        }
+                        catch { }
+                    }
+                }
+                if (resolvedPath) {
+                    // ... verify existence ...
+                    const normalizedName = dep.replace(/[/@]/g, '_');
+                    entryPoints[normalizedName] = resolvedPath;
+                    log.debug(`[PreBundler] Resolved ${dep} → ${resolvedPath}`);
+                }
+                else {
+                    log.warn(`[PreBundler] Could not resolve ${dep}`);
+                }
+            }
+            if (Object.keys(entryPoints).length === 0) {
+                log.warn('[PreBundler] No dependencies to bundle');
+                return bundledDeps;
+            }
+            // Production-ready: Full graph bundling WITH splitting + CJS export fix
+            const result = await build({
+                entryPoints,
+                bundle: true,
+                format: 'esm',
+                platform: 'browser',
+                target: 'es2020',
+                outdir: cacheDir,
+                splitting: true, // PRODUCTION: Shared chunks for efficiency
+                chunkNames: 'chunks/[name]-[hash]',
+                entryNames: '[name]',
+                minify: false,
+                sourcemap: true,
+                treeShaking: true,
+                define: {
+                    'process.env.NODE_ENV': '"development"',
+                    'global': 'globalThis'
+                },
+                plugins: [
+                    // Plugin to fix CJS → ESM named exports
+                    {
+                        name: 'cjs-esm-interop',
+                        setup(build) {
+                            // Post-process: Add named exports to entry point files
+                            build.onEnd(async (result) => {
+                                if (result.metafile) {
+                                    for (const [outputPath, outputInfo] of Object.entries(result.metafile.outputs)) {
+                                        // Only process entry points (not chunks)
+                                        if (outputInfo.entryPoint) {
+                                            const fullPath = path.resolve(outputPath);
+                                            let content = await fs.readFile(fullPath, 'utf-8');
+                                            // Check if it's a thin wrapper (only imports from chunks)
+                                            if (content.includes('from "./chunks/') && !content.includes('export {')) {
+                                                // Find which original package this is
+                                                const basename = path.basename(outputPath, '.js');
+                                                for (const dep of deps) {
+                                                    const normalizedName = dep.replace(/[/@]/g, '_');
+                                                    if (basename === normalizedName) {
+                                                        try {
+                                                            // Load the original CJS module to get exports
+                                                            let pkg;
+                                                            try {
+                                                                const pkgPath = require.resolve(dep, { paths: [root] });
+                                                                pkg = require(pkgPath);
+                                                            }
+                                                            catch (e) {
+                                                                // If require fails (e.g. ESM package), try to find common names or skip
+                                                                log.debug(`[PreBundler] Skipped CJS re-export for ${dep} (ESM or missing)`);
+                                                                continue;
+                                                            }
+                                                            if (!pkg)
+                                                                continue;
+                                                            // Get all named exports
+                                                            const exportNames = Object.getOwnPropertyNames(pkg)
+                                                                .filter(key => /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) &&
+                                                                key !== 'default' &&
+                                                                key !== '__esModule');
+                                                            // Add re-exports if needed
+                                                            if (exportNames.length > 0 && !content.includes('export const')) {
+                                                                const defaultExportMatch = content.match(/export default (\w+)(?:\(\))?;?/);
+                                                                if (defaultExportMatch) {
+                                                                    const varName = defaultExportMatch[1];
+                                                                    const isFunctionCall = content.includes(`export default ${varName}()`);
+                                                                    let exportBase = varName;
+                                                                    if (isFunctionCall) {
+                                                                        // Replace "export default foo();" with "const __pkg = foo(); export default __pkg;"
+                                                                        content = content.replace(`export default ${varName}();`, `const __pkg = ${varName}();\nexport default __pkg;`);
+                                                                        exportBase = '__pkg';
+                                                                    }
+                                                                    const namedExports = exportNames.map(name => `export const ${name} = ${exportBase}.${name};`).join('\n');
+                                                                    content = content.replace(/\/\/# sourceMappingURL=/, `${namedExports}\n//# sourceMappingURL=`);
+                                                                    await fs.writeFile(fullPath, content);
+                                                                    log.debug(`[PreBundler] Added ${exportNames.length} named exports to ${dep}`);
+                                                                }
+                                                            }
+                                                        }
+                                                        catch (e) {
+                                                            log.warn(`[PreBundler] Could not add exports for ${dep}: ${e.message}`);
+                                                        }
+                                                        break;
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            });
+                        }
+                    }
+                ],
+                logLevel: 'warning',
+                metafile: true,
+            });
+            // Build dependency map from output files
+            const depMap = {};
+            if (result.metafile) {
+                const outputs = result.metafile.outputs;
+                // Map entry points to their output files
+                for (const [outputPath, outputInfo] of Object.entries(outputs)) {
+                    if (outputInfo.entryPoint) {
+                        // Match output file to original dependency by exact normalized name
+                        const outputBasename = path.basename(outputPath, '.js');
+                        for (const dep of deps) {
+                            const normalizedName = dep.replace(/[/@]/g, '_');
+                            // Exact match - prevent "react" matching "react-router-dom"
+                            if (outputBasename === normalizedName) {
+                                const relativePath = path.relative(cacheDir, outputPath);
+                                const urlPath = `/@nuclie-deps/${relativePath}`;
+                                bundledDeps.set(dep, urlPath);
+                                depMap[dep] = urlPath;
+                                log.debug(`✓ Pre-bundled: ${dep} → ${urlPath}`);
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+            // Save metadata
+            await fs.writeFile(metaPath, JSON.stringify({
+                hash,
+                deps: Array.from(bundledDeps.keys()),
+                depMap,
+                timestamp: Date.now()
+            }, null, 2));
+            log.info(`✓ Pre-bundled ${bundledDeps.size} dependencies`);
+            return bundledDeps;
+        }
+        catch (error) {
+            log.error('Pre-bundling failed:', error.message);
+            log.error(error.stack);
+            return bundledDeps;
+        }
+    }
+    async scanDependencies(entryFile) {
+        const content = await fs.readFile(entryFile, 'utf-8');
+        const deps = new Set();
+        // Simple regex-based scan for imports
+        const importRegex = /from\s+['"]([^.\/][^'"]+)['"]/g;
+        let match;
+        while ((match = importRegex.exec(content)) !== null) {
+            const dep = match[1];
+            // Extract package name (handle scoped packages)
+            const pkgName = dep.startsWith('@')
+                ? dep.split('/').slice(0, 2).join('/')
+                : dep.split('/')[0];
+            deps.add(pkgName);
+        }
+        return Array.from(deps);
+    }
+}

package/dist/dev/statusHandler.d.ts

@@ -0,0 +1,11 @@
+import http from 'http';
+export declare class StatusHandler {
+    private startTime;
+    private requestCount;
+    private hmrPatches;
+    constructor();
+    trackRequest(): void;
+    trackHMR(): void;
+    handleRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<boolean>;
+    private checkMemory;
+}

package/dist/dev/statusHandler.js

@@ -0,0 +1,44 @@
+import { log } from '../utils/logger.js';
+export class StatusHandler {
+    constructor() {
+        this.startTime = Date.now();
+        this.requestCount = 0;
+        this.hmrPatches = 0;
+        // Start memory monitor
+        setInterval(() => this.checkMemory(), 30000);
+    }
+    trackRequest() {
+        this.requestCount++;
+    }
+    trackHMR() {
+        this.hmrPatches++;
+    }
+    async handleRequest(req, res) {
+        if (req.url === '/__nuclie/status') {
+            const stats = {
+                uptime: Math.floor((Date.now() - this.startTime) / 1000),
+                memory: process.memoryUsage(),
+                requests: this.requestCount,
+                hmrPatches: this.hmrPatches,
+                pid: process.pid
+            };
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(stats, null, 2));
+            return true;
+        }
+        return false;
+    }
+    checkMemory() {
+        const mem = process.memoryUsage();
+        const heapUsedMB = Math.round(mem.heapUsed / 1024 / 1024);
+        const heapTotalMB = Math.round(mem.heapTotal / 1024 / 1024);
+        // Warn if heap usage > 800MB (arbitrary limit for dev server)
+        if (heapUsedMB > 800) {
+            log.warn(`High memory usage: ${heapUsedMB}MB / ${heapTotalMB}MB`, { category: 'audit' });
+            if (global.gc) {
+                log.info('Triggering Garbage Collection', { category: 'audit' });
+                global.gc();
+            }
+        }
+    }
+}

package/dist/dev/types.d.ts

@@ -0,0 +1,30 @@
+export interface HMRBoundary {
+    moduleId: string;
+    boundaryType: 'safe' | 'unsafe' | 'reload-required';
+    reason: string;
+}
+export interface ModuleUpdate {
+    moduleId: string;
+    url: string;
+    affectedExports: string[] | null;
+    reason: string;
+    timestamp: number;
+}
+export type HMRDecision = 'hot-update' | 'reload';
+export interface HMRDecisionTrace {
+    changeSet: string[];
+    affectedModules: string[];
+    boundaries: HMRBoundary[];
+    decision: HMRDecision;
+    decidedBy: 'server' | 'client';
+}
+export interface HMRStats {
+    graphHash: string;
+    lastDeltaSize: number;
+    lastHMRDuration: number;
+    failureCount: number;
+}
+export interface HMRMessage {
+    type: 'connected' | 'update' | 'reload' | 'error' | 'status';
+    payload: any;
+}

package/dist/dev/types.js

@@ -0,0 +1 @@
+export {};

package/dist/dev/watcher.d.ts

@@ -0,0 +1,11 @@
+import { EventEmitter } from 'events';
+export declare class DevWatcher extends EventEmitter {
+    private rootDir;
+    private debounceMs;
+    private watcher;
+    private batch;
+    private timer;
+    constructor(rootDir: string, debounceMs?: number);
+    private addToBatch;
+    close(): void;
+}

package/dist/dev/watcher.js

@@ -0,0 +1,40 @@
+import chokidar from 'chokidar';
+import { EventEmitter } from 'events';
+import { explainReporter } from '../core/engine/events.js';
+export class DevWatcher extends EventEmitter {
+    constructor(rootDir, debounceMs = 50) {
+        super();
+        this.rootDir = rootDir;
+        this.debounceMs = debounceMs;
+        this.batch = new Set();
+        this.timer = null;
+        this.watcher = chokidar.watch(this.rootDir, {
+            ignored: [
+                '**/node_modules/**',
+                '**/.git/**',
+                '**/dist/**',
+                '**/.nuclie/**'
+            ],
+            ignoreInitial: true
+        });
+        this.watcher.on('all', (event, path) => {
+            if (event === 'add' || event === 'change' || event === 'unlink') {
+                this.addToBatch(path);
+            }
+        });
+    }
+    addToBatch(filePath) {
+        this.batch.add(filePath);
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            const sortedBatch = Array.from(this.batch).sort();
+            this.batch.clear();
+            explainReporter.report('watcher', 'batch', `Batched ${sortedBatch.length} changes`);
+            this.emit('change', sortedBatch);
+        }, this.debounceMs);
+    }
+    close() {
+        this.watcher.close();
+    }
+}

package/dist/dev-server-manual.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Manual Dev Server for Testing
+ * Run this and open manual-test/index.html in browser
+ */
+export {};

package/dist/dev-server-manual.js

@@ -0,0 +1,24 @@
+/**
+ * Manual Dev Server for Testing
+ * Run this and open manual-test/index.html in browser
+ */
+import { startDevServer } from './dev-server.js';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const testRoot = path.join(__dirname, '../manual-test');
+async function main() {
+    console.log('🚀 Starting Manual Test Server...\n');
+    const server = await startDevServer(3003, testRoot);
+    server.watchDirectory(testRoot);
+    console.log('\n✅ Server ready!');
+    console.log('\n📝 Instructions:');
+    console.log('   1. Open http://localhost:3003 in your browser');
+    console.log('   2. Edit manual-test/test.css');
+    console.log('   3. Change background color');
+    console.log('   4. Save the file');
+    console.log('   5. Watch the page update WITHOUT refresh!\n');
+    console.log('Press Ctrl+C to stop\n');
+}
+main().catch(console.error);