nuclie 1.0.0

package/dist/core/engine/index.js

@@ -0,0 +1,156 @@
+import path from 'path';
+import { initBuild, attachGraph, computeInputFingerprint } from './config.js';
+import { planBuild, planParallelExecution, determinismCheck } from './plan.js';
+import { executeParallel } from './execute.js';
+import { optimizeArtifacts } from './optimize.js';
+import { emit, computeBuildFingerprint } from './emit.js';
+import { DependencyGraph } from '../../resolve/graph.js';
+import { explainReporter } from './events.js';
+import { log } from '../../utils/logger.js';
+/**
+ * Core Build Engine
+ *
+ * PUBLIC: The main orchestrator for the Nuclie build pipeline.
+ * Use this class to run builds programmatically.
+ *
+ * @public
+ */
+export class CoreBuildEngine {
+    constructor() {
+        /** @internal */
+        this.latestGraph = null;
+        /** @internal */
+        this.ctx = null;
+    }
+    /** @public */
+    getGraph() { return this.latestGraph; }
+    /**
+     * Incremental Invalidation (Phase 10)
+     */
+    async invalidateFile(filePath) {
+        if (this.latestGraph && this.ctx) {
+            await this.latestGraph.invalidate(filePath, this.ctx.rootDir);
+        }
+    }
+    /**
+     * Shutdown and cleanup resources
+     */
+    async close() {
+        if (this.ctx && this.ctx.cache) {
+            this.ctx.cache.close();
+        }
+        this.ctx = null;
+    }
+    /**
+     * Main Entry Point for the Build Engine (Pipeline Orchestrator)
+     */
+    async run(userConfig, mode = 'dev', rootDir, changedFiles = []) {
+        try {
+            explainReporter.clear();
+            explainReporter.startMark('Total Build');
+            log.info('--> Core Engine: Starting Build Pipeline');
+            // Stage 1: Initialization
+            // Normalize paths, Load env, Resolve config, Freeze context
+            explainReporter.startMark('Initialization');
+            if (!this.ctx) {
+                this.ctx = await initBuild(userConfig, mode, rootDir);
+            }
+            explainReporter.endMark('Initialization', 'init');
+            // Stage 2: Input Fingerprinting
+            // Hash all inputs for CI verification
+            explainReporter.startMark('Fingerprinting');
+            const inputFingerprint = await computeInputFingerprint(this.ctx);
+            explainReporter.endMark('Fingerprinting', 'fingerprint');
+            // Stage 3: Attach Dependency Graph
+            // (In a full architecture, Module 2 would be invoked here independently)
+            explainReporter.startMark('Dependency Graph');
+            if (!this.latestGraph) {
+                log.info('--> Core Engine: Building NEW Dependency Graph');
+                const graph = new DependencyGraph(this.ctx.pluginManager);
+                for (const entry of this.ctx.config.entryPoints) {
+                    const absEntry = path.isAbsolute(entry)
+                        ? entry
+                        : path.resolve(this.ctx.rootDir, entry);
+                    await graph.addEntry(absEntry, this.ctx.rootDir);
+                }
+                this.latestGraph = graph;
+            }
+            else {
+                log.info(`--> Core Engine: Reusing Incremental Dependency Graph with ${changedFiles.length} changes`);
+                // If we have explicit changed files, invalidate them now
+                for (const file of changedFiles) {
+                    await this.latestGraph.invalidate(file, this.ctx.rootDir);
+                }
+            }
+            this.ctx = attachGraph(this.ctx, this.latestGraph);
+            explainReporter.endMark('Dependency Graph', 'graph');
+            // Stage 4: Build Planning
+            // Chunk boundaries, Asset grouping, Execution order
+            explainReporter.startMark('Build Planning');
+            log.info('--> Core Engine: Planning Build');
+            const buildPlan = planBuild(this.ctx);
+            explainReporter.endMark('Build Planning', 'plan');
+            // Stage 5: Parallel Execution Planning
+            // Group independent work
+            explainReporter.startMark('Parallel Planning');
+            const execPlan = planParallelExecution(buildPlan);
+            explainReporter.endMark('Parallel Planning', 'parallel_plan');
+            // Stage 6: Determinism Check
+            // Mode-aware checks
+            explainReporter.startMark('Determinism Check');
+            determinismCheck(buildPlan, this.ctx);
+            explainReporter.endMark('Determinism Check', 'determinism');
+            // Stage 7: Execution
+            // Execute parallel groups, Cache-aware
+            explainReporter.startMark('Execution');
+            log.info('--> Core Engine: Executing Plan');
+            let artifacts = await executeParallel(execPlan, buildPlan, this.ctx);
+            explainReporter.endMark('Execution', 'execute');
+            // Stage 8: Optimization
+            explainReporter.startMark('Optimization');
+            artifacts = await optimizeArtifacts(artifacts, this.ctx);
+            explainReporter.endMark('Optimization', 'optimize');
+            // POST-BUILD HOOK (Federation, Manifests, etc.)
+            const hookResult = await this.ctx.pluginManager.runHook('buildEnd', {
+                artifacts,
+                ctx: this.ctx
+            }, this.ctx);
+            if (hookResult && hookResult.artifacts) {
+                artifacts = hookResult.artifacts;
+            }
+            // Stage 9: Emit
+            // Write files, Store metadata
+            explainReporter.startMark('Emit');
+            log.info('--> Core Engine: Emitting Artifacts');
+            const emittedArtifacts = await emit(artifacts, this.ctx);
+            explainReporter.endMark('Emit', 'emit');
+            // Stage 10: Output Fingerprinting
+            // Compute final build hash
+            explainReporter.startMark('Output Fingerprint');
+            const buildFingerprint = computeBuildFingerprint(inputFingerprint, emittedArtifacts, buildPlan, this.ctx);
+            explainReporter.endMark('Output Fingerprint', 'fingerprint_output');
+            explainReporter.endMark('Total Build', 'profile');
+            log.success(`--> Core Engine: Build Complete. ${emittedArtifacts.length} artifacts emitted.`);
+            return {
+                success: true,
+                fingerprint: buildFingerprint,
+                artifacts: emittedArtifacts,
+                events: explainReporter.getEvents(),
+                pluginMetrics: this.ctx.pluginManager.getMetricsSummary()
+            };
+        }
+        catch (error) {
+            log.error('--> Core Engine: Build Failed', error);
+            // In case of error, we can still try to dump explain logs for debugging
+            return {
+                success: false,
+                error: {
+                    message: error.message,
+                    code: error.code || 'UNKNOWN_ERROR',
+                    stage: error.stage || 'unknown'
+                },
+                events: explainReporter.getEvents()
+            };
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+import { BuildArtifact, BuildContext } from './types.js';
+export declare function optimizeArtifacts(artifacts: BuildArtifact[], ctx: BuildContext): Promise<BuildArtifact[]>;

package/dist/core/engine/optimize.js

@@ -0,0 +1,99 @@
+import { explainReporter } from './events.js';
+import { canonicalHash } from './hash.js';
+import { gzipSync, brotliCompressSync, constants } from 'node:zlib';
+export async function optimizeArtifacts(artifacts, ctx) {
+    explainReporter.report('optimize', 'start', 'Starting parallel optimization passes');
+    const optimizationTasks = artifacts.map(async (artifact) => {
+        if (!artifact.source) {
+            return [artifact];
+        }
+        let content = typeof artifact.source === 'string'
+            ? artifact.source
+            : new TextDecoder().decode(artifact.source);
+        const tasks = [];
+        // 1. Minification (Concurrent)
+        if (ctx.config.minify) {
+            explainReporter.report('optimize', 'minify', `Minifying ${artifact.fileName}`);
+            try {
+                const { transform } = await import('esbuild');
+                // Day 52: Advanced CSS Purging (Heuristic)
+                if (artifact.type === 'css' && (ctx.mode === 'production' || ctx.mode === 'build')) {
+                    const jsArtifacts = artifacts.filter(a => a.type === 'js');
+                    const allJsContent = jsArtifacts.map(a => typeof a.source === 'string' ? a.source : new TextDecoder().decode(a.source)).join('\n');
+                    if (allJsContent.length > 0) {
+                        content = content.replace(/([^{}]*)\{([^}]*)\}/g, (match, selector, rules) => {
+                            const cleanSelector = selector.trim().split(/[ ,>+]/)[0].replace(/[.#]/, '');
+                            if (cleanSelector === '' || cleanSelector === 'body' || cleanSelector === 'html' || cleanSelector === '*' ||
+                                allJsContent.includes(cleanSelector) || allJsContent.includes(selector.trim())) {
+                                return match;
+                            }
+                            return ''; // Purged!
+                        });
+                    }
+                }
+                const result = await transform(content, {
+                    minify: true,
+                    loader: artifact.type,
+                    legalComments: 'none',
+                    charset: 'utf8'
+                });
+                content = result.code;
+            }
+            catch (err) {
+                explainReporter.report('optimize', 'error', `Minification failed for ${artifact.fileName}: ${err.message}`);
+            }
+        }
+        // 2. Metadata Stripping
+        if (ctx.config.sourceMaps === false) {
+            content = content.replace(/\/\/# sourceMappingURL=.*/g, '');
+        }
+        const optimizedArtifact = {
+            ...artifact,
+            source: content,
+            id: canonicalHash(content).substring(0, 16)
+        };
+        tasks.push(optimizedArtifact);
+        // 3. Compression (Parallel)
+        if ((ctx.mode === 'production' || ctx.mode === 'build') && /\.(js|css|html|svg|json)$/.test(artifact.fileName)) {
+            const buffer = Buffer.from(content);
+            // Gzip
+            try {
+                const gz = gzipSync(buffer, { level: constants.Z_BEST_COMPRESSION });
+                tasks.push({
+                    id: optimizedArtifact.id + '.gz',
+                    fileName: optimizedArtifact.fileName + '.gz',
+                    source: gz,
+                    type: 'asset',
+                    dependencies: []
+                });
+            }
+            catch (e) {
+                explainReporter.report('optimize', 'warn', `Gzip failed for ${artifact.fileName}`);
+            }
+            // Brotli
+            try {
+                const br = brotliCompressSync(buffer, {
+                    params: {
+                        [constants.BROTLI_PARAM_MODE]: constants.BROTLI_MODE_TEXT,
+                        [constants.BROTLI_PARAM_QUALITY]: constants.BROTLI_MAX_QUALITY,
+                    }
+                });
+                tasks.push({
+                    id: optimizedArtifact.id + '.br',
+                    fileName: optimizedArtifact.fileName + '.br',
+                    source: br,
+                    type: 'asset',
+                    dependencies: []
+                });
+            }
+            catch (e) {
+                explainReporter.report('optimize', 'warn', `Brotli failed for ${artifact.fileName}`);
+            }
+        }
+        return tasks;
+    });
+    const results = await Promise.all(optimizationTasks);
+    const flattenedResults = results.flat();
+    explainReporter.report('optimize', 'complete', `Optimization finished. ${flattenedResults.length} artifacts generated.`);
+    return flattenedResults;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Engine Build Planning
+ *
+ * @internal - This is part of the core engine and NOT a public API.
+ */
+import { BuildContext, BuildPlan, ExecutionPlan } from './types.js';
+export declare function planBuild(ctx: BuildContext): BuildPlan;
+export declare function planParallelExecution(plan: BuildPlan): ExecutionPlan;
+export declare function determinismCheck(plan: BuildPlan, ctx: BuildContext): void;

package/dist/core/engine/plan.js

@@ -0,0 +1,196 @@
+/**
+ * Engine Build Planning
+ *
+ * @internal - This is part of the core engine and NOT a public API.
+ */
+import { explainReporter } from './events.js';
+import { canonicalHash } from './hash.js';
+import path from 'path';
+import { normalizePath, generateModuleId } from '../../resolve/utils.js';
+// Stage 4: Build Planning
+export function planBuild(ctx) {
+    explainReporter.report('plan', 'start', 'Starting build planning');
+    const chunks = [];
+    const assets = [];
+    const entryDeps = new Map();
+    const sortedEntries = [...ctx.config.entryPoints].sort();
+    const getId = (p) => {
+        const normalized = normalizePath(p);
+        return generateModuleId('file', normalized, ctx.rootDir);
+    };
+    // 1. Identify Async Entry Points (targets of dynamic imports)
+    const asyncEntries = new Set();
+    for (const node of ctx.graph.nodes.values()) {
+        for (const edge of node.edges) {
+            if (edge.kind === 'dynamic-import') {
+                asyncEntries.add(edge.to);
+            }
+        }
+    }
+    // 2. Traversal Helper (stops at async boundaries)
+    const traverse = (startId) => {
+        const visited = new Set();
+        const queue = [startId];
+        while (queue.length > 0) {
+            const currId = queue.shift();
+            if (visited.has(currId))
+                continue;
+            visited.add(currId);
+            const node = ctx.graph.nodes.get(currId);
+            if (node) {
+                const sortedDeps = node.edges
+                    .filter(e => e.kind !== 'dynamic-import') // Stop at dynamic boundaries
+                    .map(e => e.to)
+                    .sort();
+                for (const dep of sortedDeps) {
+                    if (!asyncEntries.has(dep)) { // Don't follow into other async entries
+                        queue.push(dep);
+                    }
+                }
+            }
+        }
+        return visited;
+    };
+    // 3. Process Main Entries
+    const mainEntries = sortedEntries.map(e => getId(path.resolve(ctx.rootDir, e)));
+    // PRODUCTION TREE-SHAKING: Use native graph analysis to prune unreachable modules
+    let reachableModules = null;
+    if (ctx.mode === 'production' || ctx.mode === 'build') {
+        try {
+            const entryIds = mainEntries.filter(id => ctx.graph.nodes.has(id));
+            if (entryIds.length > 0) {
+                const reachable = ctx.graph.getReachableNodes(entryIds);
+                reachableModules = new Set(reachable);
+                const totalNodes = ctx.graph.nodes.size;
+                const pruned = totalNodes - reachable.length;
+                if (pruned > 0) {
+                    explainReporter.report('plan', 'tree_shake', `Native tree-shaking: Pruned ${pruned}/${totalNodes} unreachable modules`);
+                }
+            }
+        }
+        catch (e) {
+            explainReporter.report('plan', 'tree_shake_fallback', 'Native tree-shaking unavailable, using all modules');
+        }
+    }
+    for (const entryId of mainEntries) {
+        if (!ctx.graph.nodes.has(entryId))
+            continue;
+        const deps = traverse(entryId);
+        // Filter to only reachable modules if tree-shaking was successful
+        const finalDeps = reachableModules
+            ? new Set([...deps].filter(id => reachableModules.has(id)))
+            : deps;
+        entryDeps.set(ctx.graph.nodes.get(entryId).path, finalDeps);
+    }
+    // 4. Process Async Entries
+    for (const entryId of Array.from(asyncEntries).sort()) {
+        const deps = traverse(entryId);
+        // Filter to only reachable modules if tree-shaking was successful
+        const finalDeps = reachableModules
+            ? new Set([...deps].filter(id => reachableModules.has(id)))
+            : deps;
+        entryDeps.set(ctx.graph.nodes.get(entryId).path, finalDeps);
+    }
+    // 5. Create Chunks
+    const sortedEntryKeys = Array.from(entryDeps.keys()).sort();
+    for (const entry of sortedEntryKeys) {
+        const deps = entryDeps.get(entry);
+        const allModules = Array.from(deps).sort();
+        const jsModules = allModules.filter(id => {
+            const type = ctx.graph.nodes.get(id)?.type;
+            return type === 'file' || type === 'style-asset';
+        });
+        const cssModules = allModules.filter(id => {
+            const type = ctx.graph.nodes.get(id)?.type;
+            return type === 'css' || type === 'css-module';
+        });
+        const assetModules = allModules.filter(id => ctx.graph.nodes.get(id)?.type === 'style-asset');
+        const isAsync = asyncEntries.has(getId(entry));
+        const name = path.basename(entry, path.extname(entry));
+        const outputPrefix = isAsync ? `chunk.${name}` : name;
+        if (jsModules.length > 0) {
+            chunks.push({
+                id: `chunk_${name}_js`,
+                entry: path.relative(ctx.rootDir, entry),
+                modules: jsModules,
+                outputName: `assets/${outputPrefix}.${canonicalHash(jsModules).substring(0, 8)}.bundle.js`
+            });
+        }
+        if (cssModules.length > 0) {
+            chunks.push({
+                id: `chunk_${name}_css`,
+                entry: path.relative(ctx.rootDir, entry),
+                modules: cssModules,
+                outputName: `assets/${outputPrefix}.${canonicalHash(cssModules).substring(0, 8)}.bundle.css`
+            });
+        }
+        for (const assetId of assetModules) {
+            const node = ctx.graph.nodes.get(assetId);
+            if (node) {
+                assets.push({
+                    id: assetId,
+                    sourcePath: path.relative(ctx.rootDir, node.path),
+                    outputName: `assets/${path.basename(node.path)}`
+                });
+            }
+        }
+    }
+    // Sort chunks strictly by ID
+    chunks.sort((a, b) => a.id.localeCompare(b.id));
+    const executionOrder = chunks.map(c => c.id);
+    // Calculate Plan ID (Hash of the plan content)
+    const planStructure = {
+        target: ctx.target,
+        chunks,
+        assets,
+        executionOrder
+    };
+    const planId = canonicalHash(planStructure);
+    explainReporter.report('plan', 'complete', 'Build plan created', { planId, chunkCount: chunks.length });
+    return {
+        planId,
+        target: ctx.target,
+        chunks,
+        assets,
+        executionOrder
+    };
+}
+// Stage 5: Parallel Execution Planning
+export function planParallelExecution(plan) {
+    explainReporter.report('parallel_plan', 'start', 'Planning parallel execution');
+    // For this simple engine, chunks are independent enough to run in parallel
+    // In a real complex graph, we'd analyze shared chunks to avoid race conditions 
+    // or build shared dependencies first.
+    // Here we treat all chunks as one parallel group.
+    const chunkIds = plan.chunks.map(c => c.id);
+    const execPlan = {
+        sequential: [], // setup steps if any
+        parallelGroups: [chunkIds] // All chunks in one parallel wave
+    };
+    explainReporter.report('parallel_plan', 'complete', 'Execution plan ready', { groups: execPlan.parallelGroups.length });
+    return execPlan;
+}
+// Stage 6: Determinism Check
+export function determinismCheck(plan, ctx) {
+    explainReporter.report('determinism', 'check', `Checking determinism for mode: ${ctx.mode}`);
+    // 1. Check Module Sorting
+    // All chunk modules must be sorted.
+    for (const chunk of plan.chunks) {
+        const sorted = [...chunk.modules].sort();
+        if (JSON.stringify(chunk.modules) !== JSON.stringify(sorted)) {
+            const msg = `Determinism Violation: Chunk ${chunk.id} modules are not sorted.`;
+            if (ctx.mode === 'ci')
+                throw new Error(msg);
+            explainReporter.report('determinism', 'fail', msg);
+        }
+    }
+    // 2. Check Execution Order matches Chunks
+    const planIds = plan.chunks.map(c => c.id);
+    if (JSON.stringify(planIds) !== JSON.stringify(plan.executionOrder)) {
+        const msg = `Determinism Violation: Execution order does not match chunk sort order.`;
+        if (ctx.mode === 'ci')
+            throw new Error(msg);
+        explainReporter.report('determinism', 'fail', msg);
+    }
+    explainReporter.report('determinism', 'pass', 'Determinism checks passed');
+}

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

@@ -0,0 +1,120 @@
+import { DependencyGraph } from '../../resolve/graph.js';
+export type EngineInfo = {
+    name: "Nuclie";
+    version: string;
+    commit?: string;
+    buildTime?: string;
+};
+export type BuildMode = 'dev' | 'build' | 'ci' | 'debug' | 'production';
+export type BuildTarget = 'browser' | 'node' | 'edge';
+export interface BuildContext {
+    engine: EngineInfo;
+    mode: BuildMode;
+    target: BuildTarget;
+    rootDir: string;
+    env: Record<string, string>;
+    graph: DependencyGraph;
+    graphHash: string;
+    cache: BuildCache;
+    config: ResolvedConfig;
+    pluginManager: any;
+}
+export type InputFingerprint = {
+    sourceFiles: {
+        path: string;
+        contentHash: string;
+    }[];
+    configHash: string;
+    engineFingerprint: string;
+    inputHash: string;
+};
+export interface ChunkPlan {
+    id: string;
+    entry: string;
+    modules: string[];
+    outputName: string;
+}
+export interface AssetPlan {
+    id: string;
+    sourcePath: string;
+    outputName: string;
+}
+export interface BuildPlan {
+    planId: string;
+    target: BuildTarget;
+    chunks: ChunkPlan[];
+    assets: AssetPlan[];
+    executionOrder: string[];
+}
+export type ExecutionPlan = {
+    sequential: string[];
+    parallelGroups: string[][];
+};
+export interface BuildArtifact {
+    id: string;
+    type: 'js' | 'css' | 'asset' | 'map';
+    fileName: string;
+    dependencies: string[];
+    source?: string | Uint8Array;
+    modules?: Array<{
+        id: string;
+        size: number;
+        originalSize: number;
+    }>;
+}
+export type BuildFingerprint = {
+    engineVersion: string;
+    graphHash: string;
+    planHash: string;
+    inputHash: string;
+    outputHash: string;
+    target: string;
+    buildTime?: string;
+};
+export interface CachedResult {
+    hash: string;
+    artifact: BuildArtifact;
+}
+export interface BuildCache {
+    get(key: string): CachedResult | null | Promise<CachedResult | null>;
+    set(key: string, value: CachedResult): void | Promise<void>;
+    clear(): void | Promise<void>;
+    close(): void | Promise<void>;
+}
+export interface ResolvedConfig {
+    entryPoints: string[];
+    outputDir: string;
+    publicPath: string;
+    splittingStrategy: 'route' | 'module';
+    hashing: 'content';
+    sourceMaps: boolean | 'inline' | 'external' | 'hidden';
+    minify?: boolean;
+    cssModules?: boolean;
+    federation?: any;
+}
+export interface BuildError {
+    code: string;
+    message: string;
+    module?: string;
+    stage: 'init' | 'fingerprint' | 'graph' | 'plan' | 'parallel_plan' | 'determinism' | 'execute' | 'optimize' | 'emit' | 'fingerprint_output' | 'audit' | 'unknown';
+}
+export interface ExplainEvent {
+    stage: string;
+    decision: string;
+    reason: string;
+    name?: string;
+    id?: string;
+    data?: any;
+    timestamp?: number;
+}
+export type DeltaGraph = {
+    added: string[];
+    modified: string[];
+    removed: string[];
+};
+export type HotReloadContext = {
+    baseGraphHash: string;
+    deltaGraph: DeltaGraph;
+    affectedNodes: string[];
+    affectedChunks: string[];
+};

package/dist/core/engine/types.js

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

package/dist/core/errors/hero-errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Hero Errors System
+ *
+ * Provides rich, contextual error messages with:
+ * - File chain visualization
+ * - Graph explanation
+ * - Suggested fixes
+ * - Related documentation
+ *
+ * Never show "Build failed" without context.
+ */
+export interface ErrorContext {
+    code: string;
+    message: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    stack?: string;
+    fileChain?: string[];
+    graphExplanation?: string;
+    suggestedFix?: string;
+    relatedDocs?: string[];
+    severity: 'error' | 'warning' | 'info';
+}
+export declare class HeroError extends Error {
+    readonly context: ErrorContext;
+    constructor(context: ErrorContext);
+    /**
+     * Format error for display with rich context
+     */
+    format(): string;
+    /**
+     * Display error to console
+     */
+    display(): void;
+}
+/**
+ * Error Registry - 10 High-Impact Errors
+ */
+export declare function createModuleNotFoundError(modulePath: string, importedFrom: string, fileChain: string[]): HeroError;
+export declare function createCircularDependencyError(cycle: string[]): HeroError;
+export declare function createCSSImportError(cssFile: string, reason: string, importedFrom?: string): HeroError;
+export declare function createFrameworkAdapterMissingError(framework: string): HeroError;
+export declare function createInvalidConfigError(configPath: string, validationErrors: string[]): HeroError;
+export declare function createCacheCorruptedError(cachePath: string): HeroError;
+export declare function createHMRConnectionError(port: number, reason: string): HeroError;
+export declare function createAssetResolutionError(assetPath: string, importedFrom: string): HeroError;
+export declare function createTypeScriptError(file: string, line: number, column: number, message: string, code: string): HeroError;
+export declare function createPluginHookError(pluginName: string, hookName: string, error: Error): HeroError;
+/**
+ * Wrap any error in a HeroError with context
+ */
+export declare function wrapError(error: Error, context?: Partial<ErrorContext>): HeroError;
+/**
+ * Print a Hero Error to the console
+ */
+export declare function printHeroError(error: HeroError): void;