nuclie 1.0.0

package/dist/core/permissions.d.ts

@@ -0,0 +1,16 @@
+export type PermissionType = 'read' | 'write' | 'network' | 'env';
+export interface PermissionSet {
+    read?: string[];
+    write?: string[];
+    network?: string[];
+    env?: string[];
+}
+export declare class PermissionManager {
+    private permissions;
+    private rootDir;
+    constructor(permissions?: PermissionSet, rootDir?: string);
+    canRead(filePath: string): boolean;
+    canWrite(filePath: string): boolean;
+    canAccessNetwork(host: string): boolean;
+    canAccessEnv(key: string): boolean;
+}

package/dist/core/permissions.js

@@ -0,0 +1,47 @@
+import path from 'path';
+function isPathWithin(basePath, targetPath) {
+    const relative = path.relative(basePath, targetPath);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+export class PermissionManager {
+    constructor(permissions = {}, rootDir = process.cwd()) {
+        this.permissions = permissions;
+        this.rootDir = path.resolve(rootDir);
+    }
+    canRead(filePath) {
+        if (!this.permissions.read)
+            return false; // Default deny
+        if (this.permissions.read.includes('*'))
+            return true;
+        const resolvedPath = path.resolve(this.rootDir, filePath);
+        return this.permissions.read.some(p => {
+            const allowedPath = path.resolve(this.rootDir, p);
+            return isPathWithin(allowedPath, resolvedPath);
+        });
+    }
+    canWrite(filePath) {
+        if (!this.permissions.write)
+            return false; // Default deny
+        if (this.permissions.write.includes('*'))
+            return true;
+        const resolvedPath = path.resolve(this.rootDir, filePath);
+        return this.permissions.write.some(p => {
+            const allowedPath = path.resolve(this.rootDir, p);
+            return isPathWithin(allowedPath, resolvedPath);
+        });
+    }
+    canAccessNetwork(host) {
+        if (!this.permissions.network)
+            return false;
+        if (this.permissions.network.includes('*'))
+            return true;
+        return this.permissions.network.includes(host);
+    }
+    canAccessEnv(key) {
+        if (!this.permissions.env)
+            return false;
+        if (this.permissions.env.includes('*'))
+            return true;
+        return this.permissions.env.includes(key);
+    }
+}

package/dist/core/pipeline/framework-pipeline.d.ts

@@ -0,0 +1,71 @@
+import { CoreBuildEngine } from '../engine/index.js';
+import { BuildConfig } from '../../config/index.js';
+import { Framework } from '../framework-detector.js';
+export declare class FrameworkPipeline {
+    private engine;
+    private config;
+    private preset;
+    private framework;
+    constructor(config: BuildConfig, framework: Framework);
+    getEngine(): CoreBuildEngine;
+    getConfig(): BuildConfig;
+    getFramework(): Framework;
+    /**
+     * Factory method to create a pipeline based on auto-detection
+     */
+    static auto(config: BuildConfig): Promise<FrameworkPipeline>;
+    /**
+     * Run the build pipeline
+     * Multi-Target Orchestration (Phase E1 Honest)
+     *
+     * @experimental This implementation is currently Internal/Experimental.
+     * @internal Deferring full public API until Phase B/C stabilization is confirmed.
+     */
+    build(): Promise<{
+        success: boolean;
+        fingerprint: import("../engine/types.js").BuildFingerprint;
+        artifacts: import("../engine/types.js").BuildArtifact[];
+        events: import("../engine/types.js").ExplainEvent[];
+        pluginMetrics: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: {
+            message: any;
+            code: any;
+            stage: any;
+        };
+        events: import("../engine/types.js").ExplainEvent[];
+        fingerprint?: undefined;
+        artifacts?: undefined;
+        pluginMetrics?: undefined;
+    } | {
+        success: boolean;
+        targets: ({
+            success: boolean;
+            fingerprint: import("../engine/types.js").BuildFingerprint;
+            artifacts: import("../engine/types.js").BuildArtifact[];
+            events: import("../engine/types.js").ExplainEvent[];
+            pluginMetrics: any;
+            error?: undefined;
+            target: string;
+        } | {
+            success: boolean;
+            error: {
+                message: any;
+                code: any;
+                stage: any;
+            };
+            events: import("../engine/types.js").ExplainEvent[];
+            fingerprint?: undefined;
+            artifacts?: undefined;
+            pluginMetrics?: undefined;
+            target: string;
+        })[];
+        artifactCount: number;
+        events: any[];
+        pluginMetrics: any;
+    }>;
+    close(): Promise<void>;
+    applyDefaults(): void;
+}

package/dist/core/pipeline/framework-pipeline.js

@@ -0,0 +1,113 @@
+import { CoreBuildEngine } from '../engine/index.js';
+import { detectFramework } from '../framework-detector.js';
+import { getFrameworkPreset } from '../../presets/frameworks.js';
+import { log } from '../../utils/logger.js';
+export class FrameworkPipeline {
+    constructor(config, framework) {
+        this.config = config;
+        this.framework = framework;
+        this.preset = getFrameworkPreset(framework);
+        this.engine = new CoreBuildEngine();
+    }
+    getEngine() { return this.engine; }
+    getConfig() { return this.config; }
+    getFramework() { return this.framework; }
+    /**
+     * Factory method to create a pipeline based on auto-detection
+     */
+    static async auto(config) {
+        const rootDir = config.root || process.cwd();
+        // Honor explicit configuration (Phase 2/3 Alignment)
+        let framework = config.framework;
+        if (!framework && config.adapter) {
+            if (config.adapter.includes('react'))
+                framework = 'react';
+            else if (config.adapter.includes('vue'))
+                framework = 'vue';
+            else if (config.adapter.includes('svelte'))
+                framework = 'svelte';
+            else if (config.adapter.includes('angular'))
+                framework = 'angular';
+            else if (config.adapter.includes('solid'))
+                framework = 'solid';
+        }
+        if (!framework) {
+            framework = await detectFramework(rootDir);
+            log.info(`Pipeline: Auto-detected ${framework} workflow`);
+        }
+        else {
+            log.info(`Pipeline: Using explicitly configured ${framework} workflow`);
+        }
+        return new FrameworkPipeline(config, framework);
+    }
+    /**
+     * Run the build pipeline
+     * Multi-Target Orchestration (Phase E1 Honest)
+     *
+     * @experimental This implementation is currently Internal/Experimental.
+     * @internal Deferring full public API until Phase B/C stabilization is confirmed.
+     */
+    async build() {
+        log.info(`Pipeline: Running ${this.framework} build...`);
+        // 1. Apply Opinionated Defaults
+        this.applyDefaults();
+        // 2. Identify Targets
+        // If targets are not specified, default to platform or framework requirements
+        let targets = this.config.build?.targets;
+        if (!targets || targets.length === 0) {
+            if (this.config.preset === 'ssr') {
+                targets = ['browser', 'node'];
+            }
+            else {
+                targets = [this.config.platform || 'browser'];
+            }
+        }
+        log.info(`Pipeline: Orchestrating ${targets.length} targets: ${targets.join(', ')}`);
+        const results = [];
+        const baseOutputDir = this.config.outDir;
+        // 3. Run Build for Each Target
+        for (const target of targets) {
+            log.info(`Pipeline: Building for target [${target}]`);
+            // Clone config and set target-specific output
+            const targetConfig = {
+                ...this.config,
+                platform: target,
+                // Use subdirectories for multi-target builds to prevent overwrite
+                outDir: targets.length > 1 ? `${baseOutputDir}/${target}` : baseOutputDir
+            };
+            const result = await this.engine.run(targetConfig, this.config.mode === 'production' ? 'build' : 'dev', this.config.root || process.cwd());
+            results.push({ target, ...result });
+            if (!result.success) {
+                log.error(`Pipeline: Build failed for target ${target}`);
+                return result; // Exit early on error
+            }
+        }
+        // Aggregate Result
+        return {
+            success: true,
+            targets: results,
+            artifactCount: results.reduce((acc, r) => acc + (r.artifacts?.length || 0), 0),
+            events: results.flatMap(r => r.events || []),
+            pluginMetrics: results[results.length - 1].pluginMetrics || []
+        };
+    }
+    async close() {
+        await this.engine.close();
+    }
+    applyDefaults() {
+        // Here we can merge preset options into config with "escape hatches"
+        // If user already specified something, we don't override it unless necessary.
+        if (!this.config.build)
+            this.config.build = {};
+        if (this.config.build.minify === undefined) {
+            this.config.build.minify = this.preset.build?.minify;
+        }
+        if (this.config.build.splitting === undefined) {
+            this.config.build.splitting = this.preset.build?.splitting;
+        }
+        log.debug(`Pipeline: Applied ${this.framework} defaults`, {
+            minify: this.config.build.minify,
+            splitting: this.config.build.splitting
+        });
+    }
+}

package/dist/core/plugins/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './manager.js';
+export * from './sandbox_js.js';
+export * from './sandbox_wasm.js';
+export * from './validation.js';

package/dist/core/plugins/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './manager.js';
+export * from './sandbox_js.js';
+export * from './sandbox_wasm.js';
+export * from './validation.js';

package/dist/core/plugins/manager.d.ts

@@ -0,0 +1,30 @@
+import { NucliePlugin, PluginHookName } from './types.js';
+/**
+ * Plugin Manager
+ *
+ * PUBLIC: Responsible for registering and executing plugins in the Nuclie pipeline.
+ * Use this to extend engine functionality via the official plugin contract.
+ *
+ * @public
+ */
+export declare class PluginManager {
+    /** @internal */
+    private plugins;
+    /** @public */
+    register(plugin: NucliePlugin | any): Promise<void>;
+    /** @internal */
+    private metrics;
+    /** @internal */
+    private hookCache;
+    /** @internal - Used by the engine to execute hooks. */
+    runHook(hookName: PluginHookName, input: any, context?: any): Promise<any>;
+    /** @public */
+    getPipelineHash(): string;
+    /** @public */
+    getMetricsSummary(): {
+        plugin: string;
+        totalTimeMs: number;
+        avgTimeMs: number;
+        callCount: number;
+    }[];
+}

package/dist/core/plugins/manager.js

@@ -0,0 +1,123 @@
+import { canonicalHash } from '../engine/hash.js';
+import { explainReporter } from '../engine/events.js';
+/**
+ * Plugin Manager
+ *
+ * PUBLIC: Responsible for registering and executing plugins in the Nuclie pipeline.
+ * Use this to extend engine functionality via the official plugin contract.
+ *
+ * @public
+ */
+export class PluginManager {
+    constructor() {
+        /** @internal */
+        this.plugins = new Map();
+        /** @internal */
+        this.metrics = new Map();
+        /** @internal */
+        this.hookCache = new Map();
+    }
+    /** @public */
+    async register(plugin) {
+        let activePlugin = plugin;
+        // Auto-adapt ported plugins (missing manifest)
+        if (!plugin.manifest && plugin.name) {
+            activePlugin = {
+                id: canonicalHash(plugin.name),
+                manifest: {
+                    name: plugin.name,
+                    version: '0.0.0',
+                    type: 'js',
+                    hooks: Object.keys(plugin).filter(k => typeof plugin[k] === 'function'),
+                    permissions: { fs: 'read' },
+                    engineVersion: '^1.0.0'
+                },
+                runHook: async (hook, ...args) => {
+                    if (typeof plugin[hook] === 'function') {
+                        return plugin[hook](...args);
+                    }
+                    return null;
+                }
+            };
+        }
+        const { name, version } = activePlugin.manifest;
+        const pluginId = canonicalHash(`${name}@${version}`);
+        // Verify engine version (simplified check for now)
+        if (!activePlugin.manifest.engineVersion) {
+            throw new Error(`Plugin ${name} missing engineVersion`);
+        }
+        // 6.2 Deterministic Registration
+        // In practice, we'd sort these before registering if they come from a list
+        this.plugins.set(pluginId, activePlugin);
+        explainReporter.report('plugins', 'load', `Loaded plugin: ${name}@${version} (${activePlugin.manifest.type})`);
+    }
+    /** @internal - Used by the engine to execute hooks. */
+    async runHook(hookName, input, context) {
+        let result = input;
+        const isProd = context?.mode === 'production' || context?.mode === 'build';
+        let sortedPlugins = this.hookCache.get(hookName);
+        if (!sortedPlugins) {
+            sortedPlugins = Array.from(this.plugins.values())
+                .filter(p => p.manifest.hooks.includes(hookName))
+                .sort((a, b) => a.id.localeCompare(b.id));
+            this.hookCache.set(hookName, sortedPlugins);
+        }
+        for (const plugin of sortedPlugins) {
+            const inputHash = isProd ? '' : canonicalHash(result);
+            const executionStart = performance.now();
+            let hookResult;
+            try {
+                hookResult = await plugin.runHook(hookName, result, context);
+            }
+            catch (error) {
+                explainReporter.report('plugins', 'error', `Plugin ${plugin.manifest.name} failed during ${hookName}`, { error: error.message });
+                const pluginError = new Error(`[Plugin:${plugin.manifest.name}] ${hookName} failed: ${error.message}`);
+                pluginError.code = 'PLUGIN_ERROR';
+                pluginError.plugin = plugin.manifest.name;
+                pluginError.hook = hookName;
+                pluginError.originalError = error;
+                throw pluginError;
+            }
+            const executionTime = Date.now() - executionStart;
+            // Track metrics (Phase 2.2)
+            const m = this.metrics.get(plugin.manifest.name) || { time: 0, calls: 0 };
+            m.time += executionTime;
+            m.calls += 1;
+            this.metrics.set(plugin.manifest.name, m);
+            if (!isProd) {
+                const outputHash = canonicalHash(hookResult);
+                const validation = {
+                    passesDeterminism: true,
+                    executionTimeMs: executionTime,
+                    outputSizeBytes: JSON.stringify(hookResult).length,
+                    mutationScore: 0
+                };
+                explainReporter.report('plugins', 'hook', `Executed ${plugin.manifest.name}:${hookName} (${executionTime.toFixed(2)}ms)`);
+            }
+            if (hookResult !== null && hookResult !== undefined) {
+                result = hookResult;
+                // Stop at first successful resolution for resolveId/load
+                if (hookName === 'resolveId' || hookName === 'load') {
+                    break;
+                }
+            }
+        }
+        return result;
+    }
+    /** @public */
+    getPipelineHash() {
+        const pluginIdentities = Array.from(this.plugins.values())
+            .map(p => `${p.manifest.name}@${p.manifest.version}`)
+            .sort();
+        return canonicalHash(pluginIdentities);
+    }
+    /** @public */
+    getMetricsSummary() {
+        return Array.from(this.metrics.entries()).map(([name, m]) => ({
+            plugin: name,
+            totalTimeMs: m.time,
+            avgTimeMs: Math.round(m.time / m.calls),
+            callCount: m.calls
+        })).sort((a, b) => b.totalTimeMs - a.totalTimeMs);
+    }
+}

package/dist/core/plugins/sandbox_js.d.ts

@@ -0,0 +1,9 @@
+import { NucliePlugin, PluginHookName, PluginManifest } from './types.js';
+export declare class JSPluginSandbox implements NucliePlugin {
+    manifest: PluginManifest;
+    id: string;
+    private context;
+    private script;
+    constructor(code: string, manifest: PluginManifest);
+    runHook(hookName: PluginHookName, input: any): Promise<any>;
+}

package/dist/core/plugins/sandbox_js.js

@@ -0,0 +1,37 @@
+import vm from 'vm';
+import { canonicalHash } from '../engine/hash.js';
+export class JSPluginSandbox {
+    constructor(code, manifest) {
+        this.manifest = manifest;
+        this.id = canonicalHash(`${manifest.name}@${manifest.version}`);
+        // Create a sandboxed context with restricted globals
+        this.context = vm.createContext({
+            console: {
+                log: (...args) => console.log(`[Plugin:${manifest.name}]`, ...args),
+                warn: (...args) => console.warn(`[Plugin:${manifest.name}]`, ...args),
+                error: (...args) => console.error(`[Plugin:${manifest.name}]`, ...args),
+            },
+            // Restricted process.env
+            process: {
+                env: { NODE_ENV: 'production' }
+            },
+            // No fs/network by default
+            Buffer,
+            URL,
+        });
+        // Wrap code in a function if needed or expect it to be an IIFE / module
+        // For this implementation, we expect `code` to return an object with hooks
+        this.script = new vm.Script(`(function() {
+      ${code}
+      return plugin; // Expecting plugin object in scope
+    })()`);
+    }
+    async runHook(hookName, input) {
+        const pluginInstance = this.script.runInContext(this.context);
+        if (pluginInstance && pluginInstance[hookName]) {
+            // Direct execution for now. In full impl we might want to run in a separate worker
+            return await pluginInstance[hookName](input);
+        }
+        return input;
+    }
+}

package/dist/core/plugins/sandbox_wasm.d.ts

@@ -0,0 +1,10 @@
+import { NucliePlugin, PluginHookName, PluginManifest } from './types.js';
+export declare class WASMPluginSandbox implements NucliePlugin {
+    manifest: PluginManifest;
+    id: string;
+    private instance;
+    private memory;
+    constructor(wasmBuffer: Buffer, manifest: PluginManifest, instance: WebAssembly.Instance);
+    static create(wasmBuffer: Buffer): Promise<WASMPluginSandbox>;
+    runHook(hookName: PluginHookName, input: any): Promise<any>;
+}

package/dist/core/plugins/sandbox_wasm.js

@@ -0,0 +1,68 @@
+import { canonicalHash } from '../engine/hash.js';
+export class WASMPluginSandbox {
+    constructor(wasmBuffer, manifest, instance) {
+        this.manifest = manifest;
+        this.id = canonicalHash(`${manifest.name}@${manifest.version}`);
+        this.instance = instance;
+        this.memory = instance.exports.memory;
+    }
+    static async create(wasmBuffer) {
+        const memory = new WebAssembly.Memory({ initial: 10, maximum: 100 });
+        // 6.4 B) No FS / network imports
+        const importObject = {
+            env: {
+                memory: memory,
+                abort: () => { throw new Error("WASM Plugin Aborted"); }
+            }
+        };
+        const wasmResult = await WebAssembly.instantiate(wasmBuffer, importObject);
+        const instance = wasmResult.instance || wasmResult;
+        // 6.5 ABI Initialization
+        const exports = instance.exports;
+        if (exports._init) {
+            exports._init();
+        }
+        // Extraction of manifest from WASM
+        let manifest;
+        if (exports._get_manifest) {
+            const ptr = exports._get_manifest();
+            manifest = JSON.parse(readString(memory, ptr));
+        }
+        else {
+            throw new Error("WASM Plugin missing _get_manifest");
+        }
+        return new WASMPluginSandbox(wasmBuffer, manifest, instance);
+    }
+    async runHook(hookName, input) {
+        const exports = this.instance.exports;
+        if (!exports._run_hook)
+            return input;
+        const inputJson = JSON.stringify(input);
+        const inputPtr = writeString(this.memory, exports, inputJson);
+        const hookNamePtr = writeString(this.memory, exports, hookName);
+        const resultPtr = exports._run_hook(hookNamePtr, inputPtr, inputJson.length);
+        const resultJson = readString(this.memory, resultPtr);
+        // In real ABI, we'd need to free strings here if WASM provides free()
+        return JSON.parse(resultJson);
+    }
+}
+// Helpers for WASM string interop
+function readString(memory, ptr) {
+    const bytes = new Uint8Array(memory.buffer, ptr);
+    let end = ptr;
+    while (bytes[end] !== 0)
+        end++; // C-style null terminated
+    return new TextDecoder().decode(bytes.slice(ptr, end));
+}
+function writeString(memory, exports, str) {
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(str);
+    // If WASM exports malloc, use it. Otherwise we are in trouble or use a fixed buffer.
+    const ptr = exports.malloc ? exports.malloc(bytes.length + 1) : 0;
+    if (ptr === 0 && exports.malloc)
+        throw new Error("WASM out of memory");
+    const view = new Uint8Array(memory.buffer, ptr, bytes.length + 1);
+    view.set(bytes);
+    view[bytes.length] = 0; // null terminate
+    return ptr;
+}

package/dist/core/plugins/types.d.ts

@@ -0,0 +1,37 @@
+/** @public */
+export type PluginHookName = 'beforeGraph' | 'afterGraph' | 'beforePlan' | 'afterPlan' | 'transformModule' | 'resolveId' | 'load' | 'renderChunk' | 'cssPrecedence' | 'cssTreeShake' | 'analyzeBuild' | 'buildEnd';
+/** @public */
+export type PluginType = 'js' | 'wasm';
+/** @public */
+export interface PluginManifest {
+    name: string;
+    version: string;
+    engineVersion: string;
+    type: PluginType;
+    hooks: PluginHookName[];
+    permissions: {
+        fs?: 'read' | 'none';
+        network?: 'none';
+    };
+}
+/** @internal */
+export interface PluginValidation {
+    passesDeterminism: boolean;
+    executionTimeMs: number;
+    outputSizeBytes: number;
+    mutationScore: number;
+}
+/** @internal */
+export interface PluginExecutionRecord {
+    pluginId: string;
+    hook: PluginHookName;
+    inputHash: string;
+    outputHash: string;
+    validation: PluginValidation;
+}
+/** @public */
+export interface NucliePlugin {
+    manifest: PluginManifest;
+    id: string;
+    runHook(hook: PluginHookName, input: any, context?: any): Promise<any>;
+}

package/dist/core/plugins/types.js

@@ -0,0 +1,2 @@
+// Module 6: Plugin System Types (LOCKED SPEC)
+export {};

package/dist/core/plugins/validation.d.ts

@@ -0,0 +1,8 @@
+import { NucliePlugin, PluginValidation, PluginHookName } from './types.js';
+export declare class PluginValidator {
+    /**
+     * 6.3 Validation Pipeline
+     * Runs the plugin twice and compares outputs to ensure determinism.
+     */
+    validate(plugin: NucliePlugin, sampleHook: PluginHookName, sampleInput: any): Promise<PluginValidation>;
+}

package/dist/core/plugins/validation.js

@@ -0,0 +1,30 @@
+import { canonicalHash } from '../engine/hash.js';
+export class PluginValidator {
+    /**
+     * 6.3 Validation Pipeline
+     * Runs the plugin twice and compares outputs to ensure determinism.
+     */
+    async validate(plugin, sampleHook, sampleInput) {
+        const start = Date.now();
+        // First run
+        const result1 = await plugin.runHook(sampleHook, sampleInput);
+        const hash1 = canonicalHash(result1);
+        const time1 = Date.now() - start;
+        // Second run (for determinism check)
+        const start2 = Date.now();
+        const result2 = await plugin.runHook(sampleHook, sampleInput);
+        const hash2 = canonicalHash(result2);
+        const time2 = Date.now() - start2;
+        const passesDeterminism = hash1 === hash2;
+        // Detect mutation
+        // If we passed result1 to the second run, we could detect mutation,
+        // but here we pass sampleInput both times.
+        // To detect mutation of sampleInput, we'd hash it before and after.
+        return {
+            passesDeterminism,
+            executionTimeMs: Math.max(time1, time2),
+            outputSizeBytes: JSON.stringify(result1).length,
+            mutationScore: passesDeterminism ? 0 : 1 // Simple suspicious score
+        };
+    }
+}

package/dist/core/sandbox.d.ts

@@ -0,0 +1,9 @@
+import { PermissionManager } from './permissions.js';
+export declare class PluginSandbox {
+    private context;
+    private permissionManager;
+    constructor(permissionManager: PermissionManager);
+    private createContext;
+    private createFsProxy;
+    run(code: string, filename?: string): any;
+}