@hakobu/hakobu 1.0.0

package/lib-es5/refiner.js

@@ -0,0 +1,87 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const colors_1 = require("./colors");
+const common_1 = require("./common");
+const log_1 = require("./log");
+const win32 = process.platform === 'win32';
+function hasParent(file, records) {
+    const dirname = path_1.default.dirname(file);
+    // root directory
+    if (dirname === file) {
+        return false;
+    }
+    return Boolean(records[dirname]);
+}
+function purgeTopDirectories(records) {
+    while (true) {
+        let found = false;
+        for (const file in records) {
+            if (records[file]) {
+                const record = records[file];
+                const links = record[common_1.STORE_LINKS];
+                if (links && links.length === 1) {
+                    if (!hasParent(file, records)) {
+                        const file2 = path_1.default.join(file, links[0]);
+                        const record2 = records[file2];
+                        const links2 = record2[common_1.STORE_LINKS];
+                        if (links2 && links2.length === 1) {
+                            const file3 = path_1.default.join(file2, links2[0]);
+                            const record3 = records[file3];
+                            const links3 = record3[common_1.STORE_LINKS];
+                            if (links3) {
+                                delete records[file];
+                                log_1.log.debug(colors_1.pc.cyan(`Deleting record file: ${file}`));
+                                found = true;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        if (!found)
+            break;
+    }
+}
+function denominate(records, entrypoint, denominator, symLinks) {
+    const newRecords = {};
+    const makeSnap = (file) => {
+        let snap = (0, common_1.substituteDenominator)(file, denominator);
+        if (win32) {
+            if (snap.slice(1) === ':')
+                snap += '\\';
+        }
+        else if (snap === '') {
+            snap = '/';
+        }
+        return snap;
+    };
+    for (const file in records) {
+        if (records[file]) {
+            const snap = makeSnap(file);
+            newRecords[snap] = records[file];
+        }
+    }
+    const tmpSymLinks = symLinks;
+    symLinks = {};
+    for (const [key, value] of Object.entries(tmpSymLinks)) {
+        const key1 = makeSnap(key);
+        const value1 = makeSnap(value);
+        symLinks[key1] = value1;
+    }
+    return {
+        records: newRecords,
+        entrypoint: (0, common_1.substituteDenominator)(entrypoint, denominator),
+        symLinks,
+    };
+}
+function refiner(records, entrypoint, symLinks) {
+    purgeTopDirectories(records);
+    const denominator = (0, common_1.retrieveDenominator)(Object.keys(records));
+    return denominate(records, entrypoint, denominator, symLinks);
+}
+exports.default = refiner;
+//# sourceMappingURL=refiner.js.map

package/lib-es5/resolver.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveModule = void 0;
+const resolve_1 = require("resolve");
+const resolve_exports_1 = require("resolve.exports");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const common_1 = require("./common");
+const log_1 = require("./log");
+/**
+ * Resolve using package.json "exports" field (ESM-style)
+ * @param packageName - Package name (e.g., 'nanoid')
+ * @param subpath - Subpath within package (e.g., './url-alphabet')
+ * @param packageRoot - Absolute path to package root
+ * @returns Resolved path or null if not found
+ */
+function resolveWithExports(packageName, subpath, packageRoot) {
+    try {
+        const packageJsonPath = path_1.default.join(packageRoot, 'package.json');
+        if (!fs_1.default.existsSync(packageJsonPath)) {
+            return null;
+        }
+        const pkg = JSON.parse(fs_1.default.readFileSync(packageJsonPath, 'utf8'));
+        // Check if package has exports field
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const pkgAny = pkg;
+        if (!pkgAny.exports) {
+            return null;
+        }
+        // Use resolve.exports to handle the exports field
+        // For pkg's context, we're bundling CJS code, so try 'require' condition first
+        // Then fallback to 'import' for ESM-only packages
+        let resolved = (0, resolve_exports_1.exports)(pkgAny, subpath, {
+            require: true, // Try require first
+        });
+        // Fallback to import condition for ESM-only packages
+        if (!resolved) {
+            resolved = (0, resolve_exports_1.exports)(pkgAny, subpath, {
+                require: false, // This enables import condition
+            });
+        }
+        if (resolved) {
+            // resolved can be a string or array
+            const resolvedPath = Array.isArray(resolved) ? resolved[0] : resolved;
+            const fullPath = path_1.default.join(packageRoot, resolvedPath);
+            if (fs_1.default.existsSync(fullPath)) {
+                return fullPath;
+            }
+        }
+        return null;
+    }
+    catch (_error) {
+        log_1.log.debug(`Failed to resolve with exports field: ${packageName}${subpath}`);
+        return null;
+    }
+}
+/**
+ * Try to resolve a module specifier as an ESM package
+ * @param specifier - Module specifier (e.g., 'nanoid', 'nanoid/url-alphabet')
+ * @param basedir - Base directory for resolution
+ * @returns Resolved path or null
+ */
+function tryResolveESM(specifier, basedir) {
+    try {
+        // Parse package name and subpath
+        let packageName;
+        let subpath;
+        if (specifier.startsWith('@')) {
+            // Scoped package: @org/pkg or @org/pkg/subpath
+            const parts = specifier.split('/');
+            packageName = `${parts[0]}/${parts[1]}`;
+            subpath = parts.length > 2 ? `./${parts.slice(2).join('/')}` : '.';
+        }
+        else {
+            // Regular package: pkg or pkg/subpath
+            const slashIndex = specifier.indexOf('/');
+            if (slashIndex === -1) {
+                packageName = specifier;
+                subpath = '.';
+            }
+            else {
+                packageName = specifier.substring(0, slashIndex);
+                subpath = `./${specifier.substring(slashIndex + 1)}`;
+            }
+        }
+        // Use resolveSync to find the package root (works with pnpm and other layouts)
+        // Try to resolve the package.json to get the package root
+        try {
+            const pkgJsonPath = (0, resolve_1.sync)(path_1.default.join(packageName, 'package.json'), {
+                basedir,
+                preserveSymlinks: false,
+            });
+            const packageRoot = path_1.default.dirname(pkgJsonPath);
+            // Try to resolve with exports field
+            const resolved = resolveWithExports(packageName, subpath, packageRoot);
+            if (resolved) {
+                return resolved;
+            }
+        }
+        catch {
+            // If package.json resolution fails, fall through to return null
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve a module specifier with ESM support
+ * Falls back to standard CommonJS resolution if ESM resolution fails
+ *
+ * @param specifier - Module specifier to resolve
+ * @param options - Resolution options
+ * @returns Resolved file path and ESM flag
+ */
+function resolveModule(specifier, options) {
+    const { basedir, extensions = ['.js', '.json', '.node'] } = options;
+    // First, try ESM-style resolution with exports field
+    const esmResolved = tryResolveESM(specifier, basedir);
+    if (esmResolved) {
+        // Use isESMFile which walks up to find the correct package.json
+        return {
+            resolved: esmResolved,
+            isESM: (0, common_1.isESMFile)(esmResolved),
+        };
+    }
+    // Fallback to standard CommonJS resolution
+    const resolved = (0, resolve_1.sync)(specifier, {
+        basedir,
+        extensions,
+    });
+    return {
+        resolved,
+        isESM: false, // CJS resolution
+    };
+}
+exports.resolveModule = resolveModule;
+//# sourceMappingURL=resolver.js.map

package/lib-es5/runtime-diagnostics.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Hakobu Runtime Diagnostics
+ *
+ * Structured error types for addon and external artifact failures.
+ * These wrap low-level errors with actionable context so users know
+ * what Hakobu was doing and how to fix the problem.
+ *
+ * Error types:
+ *   HakobuAddonError     — native .node addon failures
+ *   HakobuExternalError  — external artifact lookup failures
+ *
+ * All errors include:
+ *   - what Hakobu was trying to do (operation)
+ *   - the relevant path/name
+ *   - the original cause (if wrapping a lower-level error)
+ *   - remediation guidance
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.externalNotDeclared = exports.externalNotFound = exports.HakobuExternalError = exports.addonLoadFailed = exports.addonExtractionFailed = exports.addonNotInSnapshot = exports.HakobuAddonError = exports.HakobuRuntimeError = void 0;
+// ─────────────────────────────────────────────────────────────────────
+// Base error
+// ─────────────────────────────────────────────────────────────────────
+class HakobuRuntimeError extends Error {
+    /** Machine-readable error code. */
+    code;
+    /** What Hakobu was trying to do. */
+    operation;
+    /** The original error, if this wraps one. */
+    cause;
+    /** Remediation guidance. */
+    remediation;
+    constructor(opts) {
+        const fullMessage = [
+            `[${opts.code}] ${opts.message}`,
+            ``,
+            `Operation: ${opts.operation}`,
+            `Remediation: ${opts.remediation}`,
+            opts.cause ? `Cause: ${opts.cause.message}` : null,
+        ].filter(Boolean).join('\n');
+        super(fullMessage);
+        this.name = 'HakobuRuntimeError';
+        this.code = opts.code;
+        this.operation = opts.operation;
+        this.cause = opts.cause;
+        this.remediation = opts.remediation;
+    }
+}
+exports.HakobuRuntimeError = HakobuRuntimeError;
+// ─────────────────────────────────────────────────────────────────────
+// Addon errors
+// ─────────────────────────────────────────────────────────────────────
+class HakobuAddonError extends HakobuRuntimeError {
+    /** The snapshot path of the addon. */
+    addonPath;
+    /** The extraction target path, if applicable. */
+    extractionPath;
+    constructor(opts) {
+        super(opts);
+        this.name = 'HakobuAddonError';
+        this.addonPath = opts.addonPath;
+        this.extractionPath = opts.extractionPath;
+    }
+}
+exports.HakobuAddonError = HakobuAddonError;
+/**
+ * Create a diagnostic error for a missing addon in the snapshot.
+ */
+function addonNotInSnapshot(snapshotPath) {
+    return new HakobuAddonError({
+        code: 'HAKOBU_ADDON_NOT_FOUND',
+        operation: `Loading native addon from snapshot: ${snapshotPath}`,
+        message: `Native addon '${snapshotPath}' is not in the packaged snapshot.`,
+        addonPath: snapshotPath,
+        remediation: `Ensure the .node addon is included in the packaging manifest.\n` +
+            `If it's a build-time artifact, run 'npm rebuild' before packaging.\n` +
+            `If it should be excluded, add it to the externals list.`,
+    });
+}
+exports.addonNotInSnapshot = addonNotInSnapshot;
+/**
+ * Create a diagnostic error for extraction failure.
+ */
+function addonExtractionFailed(snapshotPath, extractionPath, cause) {
+    return new HakobuAddonError({
+        code: 'HAKOBU_ADDON_EXTRACT_FAILED',
+        operation: `Extracting addon to: ${extractionPath}`,
+        message: `Failed to extract native addon '${snapshotPath}' to disk.`,
+        addonPath: snapshotPath,
+        extractionPath,
+        cause,
+        remediation: `Check filesystem permissions for the extraction directory.\n` +
+            `Override the cache location with HAKOBU_ADDON_CACHE=/path/to/cache.\n` +
+            `Ensure there is enough disk space.`,
+    });
+}
+exports.addonExtractionFailed = addonExtractionFailed;
+/**
+ * Create a diagnostic error for dlopen/load failure (likely platform mismatch).
+ */
+function addonLoadFailed(snapshotPath, extractedPath, cause) {
+    const isPlatformMismatch = cause.message.includes('wrong ELF class') ||
+        cause.message.includes('not a valid Win32') ||
+        cause.message.includes('Mach-O') ||
+        cause.message.includes('invalid ELF header') ||
+        cause.message.includes('GLIBC');
+    const code = isPlatformMismatch
+        ? 'HAKOBU_ADDON_PLATFORM_MISMATCH'
+        : 'HAKOBU_ADDON_LOAD_FAILED';
+    const remediation = isPlatformMismatch
+        ? `This addon was compiled for a different platform or architecture.\n` +
+            `The packaged binary targets a specific platform — ensure the addon\n` +
+            `was built for the same OS and architecture.\n` +
+            `Run 'npm rebuild' on the target platform before packaging.`
+        : `The addon was extracted successfully but failed to load.\n` +
+            `Check that all shared library dependencies are available.\n` +
+            `On Linux, use 'ldd ${extractedPath}' to check dependencies.`;
+    return new HakobuAddonError({
+        code,
+        operation: `Loading extracted addon: ${extractedPath}`,
+        message: `Failed to load native addon '${snapshotPath}'.`,
+        addonPath: snapshotPath,
+        extractionPath: extractedPath,
+        cause,
+        remediation,
+    });
+}
+exports.addonLoadFailed = addonLoadFailed;
+// ─────────────────────────────────────────────────────────────────────
+// External artifact errors
+// ─────────────────────────────────────────────────────────────────────
+class HakobuExternalError extends HakobuRuntimeError {
+    /** The declared artifact name. */
+    artifactName;
+    constructor(opts) {
+        super(opts);
+        this.name = 'HakobuExternalError';
+        this.artifactName = opts.artifactName;
+    }
+}
+exports.HakobuExternalError = HakobuExternalError;
+/**
+ * Create a diagnostic error for a missing required external artifact.
+ */
+function externalNotFound(name, searchedPaths) {
+    return new HakobuExternalError({
+        code: 'HAKOBU_EXTERNAL_NOT_FOUND',
+        operation: `Locating required external artifact: ${name}`,
+        message: `Required external artifact '${name}' was not found.`,
+        artifactName: name,
+        remediation: `Searched locations:\n` +
+            searchedPaths.map(p => `  - ${p}`).join('\n') + '\n\n' +
+            `Set HAKOBU_EXTERNAL_${name.toUpperCase().replace(/[^A-Z0-9]/g, '_')} ` +
+            `to the artifact path, or place it at one of the search locations.`,
+    });
+}
+exports.externalNotFound = externalNotFound;
+/**
+ * Create a diagnostic error for an undeclared external artifact.
+ */
+function externalNotDeclared(name, declared) {
+    return new HakobuExternalError({
+        code: 'HAKOBU_EXTERNAL_NOT_DECLARED',
+        operation: `Looking up external artifact: ${name}`,
+        message: `External artifact '${name}' is not declared in the packaging manifest.`,
+        artifactName: name,
+        remediation: `Declared externals: ${declared.length ? declared.join(', ') : '(none)'}\n` +
+            `Add '${name}' to the externals list in your Hakobu config.`,
+    });
+}
+exports.externalNotDeclared = externalNotDeclared;
+//# sourceMappingURL=runtime-diagnostics.js.map