nuclie 1.0.0

package/dist/core/cache/lazy-init.js

@@ -0,0 +1,153 @@
+/**
+ * MODULE 8: PERSISTENT CACHE & COLD START MASTERY
+ *
+ * Strategy:
+ * 1. Lazy RocksDB Initialization (Deferred to background)
+ * 2. Mmap-backed reads for native performance
+ * 3. Cache Warming in non-blocking background thread
+ * 4. Docker/Edge persistent volume support
+ */
+import path from 'path';
+import fs from 'fs';
+import { log } from '../../utils/logger.js';
+import { BuildCache } from '../../native/cache.js';
+export class LazyCacheInitializer {
+    constructor(options) {
+        this.rocksDb = null;
+        this.initPromise = null;
+        this.isInitialized = false;
+        this.cacheDir = options.cacheDir;
+        this.preload = options.preload ?? true;
+        this.warmup = options.warmup ?? true;
+        // Auto-detect Docker/Edge persistent volumes
+        this.setupPersistentStorage();
+    }
+    /**
+     * Setup persistent storage paths for Docker/CI/Edge
+     */
+    setupPersistentStorage() {
+        // Task Day 51: Persistent cache for Docker/Edge
+        const tmpCache = '/tmp/nuclie-cache';
+        if (process.env.DOCKER_CONTAINER && !fs.existsSync(this.cacheDir)) {
+            try {
+                if (!fs.existsSync(tmpCache))
+                    fs.mkdirSync(tmpCache, { recursive: true });
+                this.cacheDir = tmpCache;
+                log.info(`Using Docker persistent cache volume at ${tmpCache}`);
+            }
+            catch (e) { }
+        }
+    }
+    /**
+     * Get database instance - initializes lazily on first access
+     */
+    async getDatabase() {
+        if (this.rocksDb)
+            return this.rocksDb;
+        if (this.initPromise) {
+            await this.initPromise;
+            return this.rocksDb;
+        }
+        this.initPromise = this.initialize();
+        await this.initPromise;
+        return this.rocksDb;
+    }
+    /**
+     * Initialize cache in background (non-blocking for <200ms cold start)
+     */
+    initializeInBackground() {
+        if (this.isInitialized || this.initPromise)
+            return;
+        log.debug('Starting background RocksDB initialization...');
+        // Use setImmediate to ensure it doesn't block the event loop during startup
+        global.setImmediate(() => {
+            this.initPromise = this.initialize().catch(err => {
+                log.warn(`Background cache init failed: ${err.message}`, { category: 'cache' });
+            });
+        });
+    }
+    /**
+     * Core initialization logic (RocksDB Native)
+     */
+    async initialize() {
+        const startTime = Date.now();
+        try {
+            if (!fs.existsSync(this.cacheDir)) {
+                fs.mkdirSync(this.cacheDir, { recursive: true });
+            }
+            // Task Day 51: Native RocksDB with mmap and level compaction
+            // The native module already has these opts now.
+            this.rocksDb = new BuildCache(this.cacheDir);
+            if (this.warmup) {
+                await this.warmupCache();
+            }
+            this.isInitialized = true;
+            const duration = Date.now() - startTime;
+            log.success(`RocksDB Cache ready in ${duration}ms`, { category: 'cache' });
+        }
+        catch (error) {
+            const isLockError = error.message?.includes('Lock') ||
+                error.message?.includes('IO error') ||
+                error.message?.includes('Resource temporarily unavailable');
+            if (isLockError) {
+                log.warn(`Cache locked by another process. Falling back to in-memory mode.`, { category: 'cache' });
+                // Return a mock DB object
+                const store = new Map();
+                this.rocksDb = {
+                    get: (k) => store.get(k) || null,
+                    set: (k, v) => { store.set(k, v); },
+                    clearAll: () => store.clear(),
+                    getStats: () => ({ size: store.size, keys: store.size }),
+                    close: () => { store.clear(); }
+                };
+                this.isInitialized = true;
+            }
+            else {
+                log.error(`RocksDB initialization failed: ${error.message}`, { category: 'cache' });
+                throw error;
+            }
+        }
+    }
+    /**
+     * Warm up cache by pre-reading essential keys
+     */
+    async warmupCache() {
+        if (!this.rocksDb)
+            return;
+        try {
+            // Task Day 51: Implement cache warming
+            // We just hit the stats and maybe some common keys
+            this.rocksDb.getStats();
+            log.debug('Cache warmup completed');
+        }
+        catch (e) { }
+    }
+    close() {
+        if (this.rocksDb) {
+            this.rocksDb.close();
+            this.rocksDb = null;
+            this.isInitialized = false;
+        }
+    }
+    isReady() {
+        return this.isInitialized;
+    }
+}
+let globalLazyCache = null;
+export function getLazyCache(cacheDir) {
+    if (!globalLazyCache) {
+        const dir = cacheDir || path.join(process.cwd(), '.nuclie_cache');
+        globalLazyCache = new LazyCacheInitializer({
+            cacheDir: dir,
+            preload: true,
+            warmup: true,
+        });
+    }
+    return globalLazyCache;
+}
+export function initCacheInBackground(cacheDir) {
+    getLazyCache(cacheDir).initializeInBackground();
+}
+export async function getLazyCacheDatabase(cacheDir) {
+    return getLazyCache(cacheDir).getDatabase();
+}

package/dist/core/cache-manager.d.ts

@@ -0,0 +1,51 @@
+/**
+ * RocksDB Cache Manager
+ * Day 6: Module 1 - Speed Mastery
+ *
+ * Provides a high-level interface for the persistent RocksDB cache.
+ * Manages cache partitions (Parse, Transform, Bundle) and enforces policies.
+ */
+export type CacheCategory = 'parse' | 'transform' | 'bundle' | 'optimize' | 'meta';
+export interface CacheOptions {
+    enabled: boolean;
+    root: string;
+    compression?: boolean;
+    maxSizeBytes?: number;
+}
+export declare class CacheManager {
+    private cache;
+    private enabled;
+    private root;
+    private maxSizeBytes;
+    constructor(options: CacheOptions);
+    private init;
+    private getDb;
+    /**
+     * Get a cached result
+     */
+    get(category: CacheCategory, key: string): Promise<string | null>;
+    /**
+     * Set a cached result
+     */
+    set(category: CacheCategory, key: string, value: string): Promise<void>;
+    /**
+     * Check existence
+     */
+    has(category: CacheCategory, key: string): Promise<boolean>;
+    /**
+     * Batch write
+     */
+    batchSet(entries: Record<string, string>, category: CacheCategory): Promise<void>;
+    /**
+     * Enforce cache policies (Compaction, Eviction simulation)
+     */
+    enforcePolicy(): Promise<void>;
+    getStats(): import("*.node").CacheStats | {
+        hitRate: number;
+        sizeBytes: number;
+        hits: number;
+        misses: number;
+    };
+    close(): void;
+}
+export declare function getCacheManager(root?: string): CacheManager;

package/dist/core/cache-manager.js

@@ -0,0 +1,149 @@
+/**
+ * RocksDB Cache Manager
+ * Day 6: Module 1 - Speed Mastery
+ *
+ * Provides a high-level interface for the persistent RocksDB cache.
+ * Manages cache partitions (Parse, Transform, Bundle) and enforces policies.
+ */
+import { log } from '../utils/logger.js';
+import path from 'path';
+export class CacheManager {
+    constructor(options) {
+        this.cache = null;
+        this.enabled = options.enabled;
+        this.root = options.root;
+        this.maxSizeBytes = options.maxSizeBytes || 512 * 1024 * 1024; // 512MB default
+        if (this.enabled) {
+            this.init();
+        }
+    }
+    async init() {
+        try {
+            const { getLazyCacheDatabase, initCacheInBackground } = await import('./cache/lazy-init.js');
+            // Background init
+            initCacheInBackground(path.join(this.root, '.nuclie_cache'));
+            // The first 'get' or 'set' will await the database if it's not ready
+        }
+        catch (error) {
+            log.warn(`Failed to initialize lazy RocksDB cache: ${error.message}`);
+        }
+    }
+    async getDb() {
+        if (!this.enabled)
+            return null;
+        try {
+            const { getLazyCacheDatabase } = await import('./cache/lazy-init.js');
+            return await getLazyCacheDatabase(path.join(this.root, '.nuclie_cache'));
+        }
+        catch (e) {
+            return null;
+        }
+    }
+    /**
+     * Get a cached result
+     */
+    async get(category, key) {
+        if (!this.enabled)
+            return null;
+        const db = await this.getDb();
+        if (!db)
+            return null;
+        try {
+            return db.get(`${category}:${key}`);
+        }
+        catch (e) {
+            return null;
+        }
+    }
+    /**
+     * Set a cached result
+     */
+    async set(category, key, value) {
+        if (!this.enabled)
+            return;
+        const db = await this.getDb();
+        if (!db)
+            return;
+        try {
+            db.set(`${category}:${key}`, value);
+        }
+        catch (e) { }
+    }
+    /**
+     * Check existence
+     */
+    async has(category, key) {
+        if (!this.enabled)
+            return false;
+        const db = await this.getDb();
+        if (!db)
+            return false;
+        return db.has(`${category}:${key}`);
+    }
+    /**
+     * Batch write
+     */
+    async batchSet(entries, category) {
+        if (!this.enabled)
+            return;
+        const db = await this.getDb();
+        if (!db)
+            return;
+        const prefixed = {};
+        for (const [k, v] of Object.entries(entries)) {
+            prefixed[`${category}:${k}`] = v;
+        }
+        db.batchSet(prefixed);
+    }
+    /**
+     * Enforce cache policies (Compaction, Eviction simulation)
+     */
+    async enforcePolicy() {
+        if (!this.enabled || !this.cache)
+            return;
+        try {
+            const stats = this.cache.getStats();
+            // log.debug('Cache Stats:', stats);
+            // 1. Compaction
+            // RocksDB does auto-compaction, but we can trigger it manually if fragmentation is high
+            // For now, we just call it periodically or on shutdown
+            // this.cache.compact(); // Expensive, maybe only do rarely?
+            // 2. Eviction (Size limit)
+            if (stats.sizeBytes > this.maxSizeBytes) {
+                log.warn(`Cache size (${(stats.sizeBytes / 1024 / 1024).toFixed(2)}MB) exceeds limit. Clearing...`);
+                // Simple strategy: Clear everything or specific targets. 
+                // RocksDB makes LRU hard without column families or manual tracking.
+                // We'll clear 'dev' builds first, preserving 'prod'.
+                const cleared = this.cache.clearTarget('dev');
+                log.info(`Evicted ${cleared} dev entries.`);
+                // If still too big, compact
+                this.cache.compact();
+            }
+        }
+        catch (e) {
+            log.error('Cache policy enforcement failed:', e);
+        }
+    }
+    getStats() {
+        if (!this.enabled || !this.cache)
+            return { hitRate: 0, sizeBytes: 0, hits: 0, misses: 0 };
+        return this.cache.getStats();
+    }
+    close() {
+        if (this.cache) {
+            this.cache.close();
+            this.cache = null;
+        }
+    }
+}
+// Global instance helper
+let _instance = null;
+export function getCacheManager(root = process.cwd()) {
+    if (!_instance) {
+        _instance = new CacheManager({
+            enabled: true,
+            root
+        });
+    }
+    return _instance;
+}

package/dist/core/css/engine.d.ts

@@ -0,0 +1,37 @@
+import { DependencyGraph, GraphNode } from '../../resolve/graph.js';
+import { PluginManager } from '../plugins/manager.js';
+export interface CSSUsage {
+    selector: string;
+    usedByModules: string[];
+    usagePercentage: number;
+}
+export declare class CSSEngine {
+    private graph;
+    private pluginManager;
+    private precedenceResolver;
+    constructor(graph: DependencyGraph, pluginManager: PluginManager);
+    /**
+     * 7.1 CSS & CSS-IN-JS DETECTION
+     */
+    detect(filePath: string, content: string): Promise<GraphNode['type'] | null>;
+    /**
+     * 7.2 CSS DEPENDENCY GRAPH + IMPORT PRECEDENCE
+     */
+    processEdges(node: GraphNode): Promise<void>;
+    /**
+     * 7.6 GRAPH-BASED CSS TREE-SHAKING
+     */
+    treeShake(node: GraphNode, usedSelectors: Set<string>): Promise<string>;
+    /**
+   * 7.5 DETERMINISTIC CSS MODULES
+   */
+    generateClassNameHash(filePath: string, className: string): string;
+    /**
+     * 7.3 CSS TRANSFORM PIPELINE (WASM + JS Hybrid)
+     */
+    transform(node: GraphNode): Promise<string>;
+    /**
+     * 7.1 CSS-IN-JS EXTRACTION (Unified)
+     */
+    extractCSSInJS(node: GraphNode, rootDir: string): Promise<void>;
+}

package/dist/core/css/engine.js

@@ -0,0 +1,113 @@
+import { CSSImportPrecedenceResolver } from '../../resolve/css-precedence.js';
+import { log } from '../../utils/logger.js';
+import path from 'path';
+import fs from 'fs/promises';
+import { generateModuleId } from '../../resolve/utils.js';
+import { canonicalHash } from '../engine/hash.js';
+export class CSSEngine {
+    constructor(graph, pluginManager) {
+        this.graph = graph;
+        this.pluginManager = pluginManager;
+        this.precedenceResolver = new CSSImportPrecedenceResolver();
+    }
+    /**
+     * 7.1 CSS & CSS-IN-JS DETECTION
+     */
+    async detect(filePath, content) {
+        const ext = path.extname(filePath).toLowerCase();
+        if (ext === '.css') {
+            if (filePath.endsWith('.module.css'))
+                return 'css-module';
+            return 'css';
+        }
+        if (['.scss', '.less', '.styl'].includes(ext)) {
+            return 'css';
+        }
+        // CSS-in-JS detection (Module 4 extractors would do the heavy lifting)
+        if (content.includes('styled-components') || content.includes('@emotion/react') || content.includes('linaria')) {
+            return 'css-in-js';
+        }
+        return null;
+    }
+    /**
+     * 7.2 CSS DEPENDENCY GRAPH + IMPORT PRECEDENCE
+     */
+    async processEdges(node) {
+        if (node.type !== 'css' && node.type !== 'css-module' && node.type !== 'css-in-js')
+            return;
+        // Resolve precedence deterministically
+        node.edges = this.precedenceResolver.resolve(node.edges, this.graph.nodes);
+    }
+    /**
+     * 7.6 GRAPH-BASED CSS TREE-SHAKING
+     */
+    async treeShake(node, usedSelectors) {
+        // In a real implementation, we'd parse the CSS and remove unused selectors
+        // based on the reachable selectors found in the dependency graph.
+        log.info(`Tree-shaking CSS for ${node.id}`);
+        // Placeholder for actual tree-shaking logic
+        // Uses Module 2 graph to know which selectors are reachable from JS modules
+        return node.path; // Return path for now
+    }
+    /**
+   * 7.5 DETERMINISTIC CSS MODULES
+   */
+    generateClassNameHash(filePath, className) {
+        // SHA256(filePath + className) as per plan
+        return canonicalHash(filePath + className).slice(0, 8);
+    }
+    /**
+     * 7.3 CSS TRANSFORM PIPELINE (WASM + JS Hybrid)
+     */
+    async transform(node) {
+        // 1. Detect if it's Tailwind, SCSS, etc.
+        // 2. Call WASM plugins for CPU-heavy (Sass, Tailwind)
+        // 3. Call JS plugins for others
+        log.info(`Transforming CSS node: ${node.id}`);
+        // Hybrid model: 
+        // - runHook('transformModule', ...)
+        const result = await this.pluginManager.runHook('transformModule', {
+            id: node.id,
+            path: node.path,
+            type: node.type,
+            code: '' // Assuming code is loaded elsewhere or we load it here
+        });
+        return result.code;
+    }
+    /**
+     * 7.1 CSS-IN-JS EXTRACTION (Unified)
+     */
+    async extractCSSInJS(node, rootDir) {
+        if (node.type !== 'css-in-js')
+            return;
+        log.info(`Extracting CSS-in-JS from ${node.path}`);
+        // Use plugins to extract CSS
+        const content = await fs.readFile(node.path, 'utf-8');
+        const result = await this.pluginManager.runHook('transformModule', {
+            id: node.id,
+            path: node.path,
+            type: node.type,
+            code: content
+        });
+        if (result.metadata?.cssInJs) {
+            node.cssInJs = result.metadata.cssInJs;
+            // Create virtual CSS node in graph
+            const virtualPath = `${node.path}.extracted.css`;
+            const virtualId = generateModuleId('css', virtualPath, rootDir);
+            this.graph.nodes.set(virtualId, {
+                id: virtualId,
+                type: 'css',
+                path: virtualPath,
+                contentHash: canonicalHash(result.metadata.cssInJs.extractedCss),
+                edges: []
+            });
+            // Add edge from JS to virtual CSS
+            node.edges.push({
+                from: node.id,
+                to: virtualId,
+                kind: 'js-style-import'
+            });
+            log.success(`Extracted CSS from ${node.path} -> ${virtualPath}`);
+        }
+    }
+}

package/dist/core/css-framework-detector.d.ts

@@ -0,0 +1,10 @@
+export type CSSFramework = 'tailwind' | 'bootstrap' | 'bulma' | 'material' | 'none';
+export interface DetectedCSSFramework {
+    name: CSSFramework;
+    version?: string;
+    source: 'package.json' | 'file-pattern' | 'class-scan';
+}
+/**
+ * Main CSS framework detection function
+ */
+export declare function detectCSSFramework(root: string): Promise<DetectedCSSFramework>;

package/dist/core/css-framework-detector.js

@@ -0,0 +1,169 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { log } from '../utils/logger.js';
+/**
+ * Check if a package exists in package.json dependencies
+ */
+async function hasPackage(root, packageName) {
+    try {
+        const pkgPath = path.join(root, 'package.json');
+        const content = await fs.readFile(pkgPath, 'utf-8');
+        const pkg = JSON.parse(content);
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        return deps[packageName] || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a file or directory exists
+ */
+async function hasFile(root, filePath) {
+    try {
+        await fs.access(path.join(root, filePath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Scan source files for class name patterns
+ */
+async function hasClassPattern(root, patterns) {
+    try {
+        const srcPath = path.join(root, 'src');
+        const srcExists = await fs.access(srcPath).then(() => true).catch(() => false);
+        if (!srcExists)
+            return false;
+        // Read first few files to check for class patterns
+        const files = await fs.readdir(srcPath);
+        const jsFiles = files.filter(f => f.endsWith('.js') || f.endsWith('.jsx') ||
+            f.endsWith('.ts') || f.endsWith('.tsx') ||
+            f.endsWith('.vue') || f.endsWith('.svelte')).slice(0, 5); // Check first 5 files
+        for (const file of jsFiles) {
+            const content = await fs.readFile(path.join(srcPath, file), 'utf-8');
+            // Check if any pattern exists in the content
+            for (const pattern of patterns) {
+                if (content.includes(`"${pattern}"`) ||
+                    content.includes(`'${pattern}'`) ||
+                    content.includes(`className="${pattern}`) ||
+                    content.includes(`class="${pattern}`)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detect Tailwind CSS
+ */
+async function detectTailwind(root) {
+    // Check package.json
+    const version = await hasPackage(root, 'tailwindcss');
+    if (version) {
+        return { name: 'tailwind', version, source: 'package.json' };
+    }
+    // Check for tailwind.config.js
+    if (await hasFile(root, 'tailwind.config.js') || await hasFile(root, 'tailwind.config.ts')) {
+        return { name: 'tailwind', source: 'file-pattern' };
+    }
+    // Check for Tailwind class patterns
+    if (await hasClassPattern(root, ['flex', 'grid', 'bg-', 'text-', 'p-', 'm-'])) {
+        return { name: 'tailwind', source: 'class-scan' };
+    }
+    return null;
+}
+/**
+ * Detect Bootstrap
+ */
+async function detectBootstrap(root) {
+    // Check package.json
+    const version = await hasPackage(root, 'bootstrap');
+    if (version) {
+        return { name: 'bootstrap', version, source: 'package.json' };
+    }
+    // Check for Bootstrap in node_modules
+    if (await hasFile(root, 'node_modules/bootstrap')) {
+        return { name: 'bootstrap', source: 'file-pattern' };
+    }
+    // Check for Bootstrap class patterns
+    if (await hasClassPattern(root, ['btn', 'container', 'row', 'col-', 'navbar'])) {
+        return { name: 'bootstrap', source: 'class-scan' };
+    }
+    return null;
+}
+/**
+ * Detect Bulma
+ */
+async function detectBulma(root) {
+    // Check package.json
+    const version = await hasPackage(root, 'bulma');
+    if (version) {
+        return { name: 'bulma', version, source: 'package.json' };
+    }
+    // Check for Bulma in node_modules
+    if (await hasFile(root, 'node_modules/bulma')) {
+        return { name: 'bulma', source: 'file-pattern' };
+    }
+    // Check for Bulma class patterns
+    if (await hasClassPattern(root, ['button', 'hero', 'section', 'column', 'box'])) {
+        return { name: 'bulma', source: 'class-scan' };
+    }
+    return null;
+}
+/**
+ * Detect Material UI / Material Design
+ */
+async function detectMaterial(root) {
+    // Check package.json for MUI
+    const muiVersion = await hasPackage(root, '@mui/material');
+    if (muiVersion) {
+        return { name: 'material', version: muiVersion, source: 'package.json' };
+    }
+    // Check for Material Design Lite
+    const mdlVersion = await hasPackage(root, 'material-design-lite');
+    if (mdlVersion) {
+        return { name: 'material', version: mdlVersion, source: 'package.json' };
+    }
+    // Check for Material Components Web
+    const mcwVersion = await hasPackage(root, '@material/web');
+    if (mcwVersion) {
+        return { name: 'material', version: mcwVersion, source: 'package.json' };
+    }
+    return null;
+}
+/**
+ * Main CSS framework detection function
+ */
+export async function detectCSSFramework(root) {
+    log.info('Detecting CSS framework...');
+    // Try each detector in priority order
+    const tailwind = await detectTailwind(root);
+    if (tailwind) {
+        log.success(`Detected Tailwind CSS ${tailwind.version || ''} (${tailwind.source})`);
+        return tailwind;
+    }
+    const bootstrap = await detectBootstrap(root);
+    if (bootstrap) {
+        log.success(`Detected Bootstrap ${bootstrap.version || ''} (${bootstrap.source})`);
+        return bootstrap;
+    }
+    const material = await detectMaterial(root);
+    if (material) {
+        log.success(`Detected Material UI ${material.version || ''} (${material.source})`);
+        return material;
+    }
+    const bulma = await detectBulma(root);
+    if (bulma) {
+        log.success(`Detected Bulma ${bulma.version || ''} (${bulma.source})`);
+        return bulma;
+    }
+    log.info('No CSS framework detected');
+    return { name: 'none', source: 'package.json' };
+}

package/dist/core/detection/files.d.ts

@@ -0,0 +1,2 @@
+import { DetectionSignal } from './types.js';
+export declare function inspectEntryFiles(rootDir: string, entryFiles: string[]): Promise<DetectionSignal[]>;