@hakobu/hakobu 1.0.0

package/lib-es5/external-artifacts.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * Hakobu External Artifact Runtime
+ *
+ * Manages declared external artifacts — files or directories that are
+ * intentionally kept outside the packaged executable. Examples:
+ *
+ *   - Browser binaries (Playwright, Camoufox)
+ *   - ffmpeg or other helper tools
+ *   - Large data files
+ *
+ * External artifacts are:
+ *   - Declared explicitly in the packaging manifest (not guessed)
+ *   - Resolved at runtime to real filesystem paths
+ *   - NOT embedded in the snapshot
+ *   - Validated at startup (required artifacts must exist)
+ *
+ * Resolution strategy:
+ *   1. Check HAKOBU_EXTERNAL_{NAME} env var (uppercase, dashes→underscores)
+ *   2. Check {execDir}/externals/{name}/ (relative to the executable)
+ *   3. Check the declared pattern path (absolute or relative to cwd)
+ *   4. If required and not found → throw with clear guidance
+ *
+ * Usage from packaged code:
+ *   const { getExternal } = require('@hakobu/runtime');
+ *   const browserPath = getExternal('camoufox-browser');
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalArtifactRegistry = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const runtime_diagnostics_1 = require("./runtime-diagnostics");
+// ─────────────────────────────────────────────────────────────────────
+// Registry
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Runtime registry of declared external artifacts.
+ * Created from the manifest's externals list during bootstrap.
+ */
+class ExternalArtifactRegistry {
+    declarations;
+    resolved;
+    execDir;
+    constructor(artifacts, execDir) {
+        this.declarations = new Map();
+        this.resolved = new Map();
+        this.execDir = execDir || path_1.default.dirname(process.execPath);
+        for (const artifact of artifacts) {
+            this.declarations.set(artifact.name, artifact);
+        }
+    }
+    /**
+     * Get a declared external artifact by name.
+     * Resolves the path on first access and caches the result.
+     *
+     * @param name - The declared artifact name
+     * @returns ResolvedExternal with the real filesystem path
+     * @throws Error if the artifact is required but not found
+     */
+    get(name) {
+        // Check cache
+        if (this.resolved.has(name)) {
+            return this.resolved.get(name);
+        }
+        const decl = this.declarations.get(name);
+        if (!decl) {
+            throw (0, runtime_diagnostics_1.externalNotDeclared)(name, [...this.declarations.keys()]);
+        }
+        const resolved = this.resolve(decl);
+        if (resolved) {
+            this.resolved.set(name, resolved);
+            return resolved;
+        }
+        if (decl.required) {
+            throw (0, runtime_diagnostics_1.externalNotFound)(name, [
+                `env: HAKOBU_EXTERNAL_${toEnvName(name)}`,
+                path_1.default.join(this.execDir, 'externals', name),
+                `pattern: ${decl.pattern}`,
+            ]);
+        }
+        return null;
+    }
+    /**
+     * Check if a declared external artifact exists without throwing.
+     */
+    has(name) {
+        try {
+            return this.get(name) !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Validate all required externals exist. Throws on first missing.
+     */
+    validateRequired() {
+        for (const [name, decl] of this.declarations) {
+            if (decl.required) {
+                this.get(name); // throws if missing
+            }
+        }
+    }
+    /**
+     * List all declared external artifact names.
+     */
+    listDeclared() {
+        return [...this.declarations.keys()];
+    }
+    // ── Resolution logic ──
+    resolve(decl) {
+        // 1. Environment variable override
+        const envKey = `HAKOBU_EXTERNAL_${toEnvName(decl.name)}`;
+        const envVal = process.env[envKey];
+        if (envVal && fs_1.default.existsSync(envVal)) {
+            return {
+                name: decl.name,
+                resolvedPath: path_1.default.resolve(envVal),
+                resolvedVia: 'env',
+                isDirectory: fs_1.default.statSync(envVal).isDirectory(),
+            };
+        }
+        // 2. Executable-relative: {execDir}/externals/{name}
+        const execRelative = path_1.default.join(this.execDir, 'externals', decl.name);
+        if (fs_1.default.existsSync(execRelative)) {
+            return {
+                name: decl.name,
+                resolvedPath: execRelative,
+                resolvedVia: 'exec-relative',
+                isDirectory: fs_1.default.statSync(execRelative).isDirectory(),
+            };
+        }
+        // 3. Pattern path (absolute or relative to cwd)
+        const patternPath = path_1.default.resolve(decl.pattern);
+        if (fs_1.default.existsSync(patternPath)) {
+            return {
+                name: decl.name,
+                resolvedPath: patternPath,
+                resolvedVia: 'pattern',
+                isDirectory: fs_1.default.statSync(patternPath).isDirectory(),
+            };
+        }
+        // 4. CWD-relative by name
+        const cwdRelative = path_1.default.resolve(decl.name);
+        if (cwdRelative !== patternPath && fs_1.default.existsSync(cwdRelative)) {
+            return {
+                name: decl.name,
+                resolvedPath: cwdRelative,
+                resolvedVia: 'cwd-relative',
+                isDirectory: fs_1.default.statSync(cwdRelative).isDirectory(),
+            };
+        }
+        return null;
+    }
+}
+exports.ExternalArtifactRegistry = ExternalArtifactRegistry;
+// ─────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Convert an artifact name to an environment variable suffix.
+ * "camoufox-browser" → "CAMOUFOX_BROWSER"
+ */
+function toEnvName(name) {
+    return name.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+}
+//# sourceMappingURL=external-artifacts.js.map

package/lib-es5/fabricator.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shutdown = exports.fabricateTwice = exports.fabricate = void 0;
+const child_process_1 = require("child_process");
+const log_1 = require("./log");
+const script = `
+  var vm = require('vm');
+  var module = require('module');
+  var stdin = Buffer.alloc(0);
+  process.stdin.on('data', function (data) {
+    stdin = Buffer.concat([ stdin, data ]);
+    if (stdin.length >= 4) {
+      var sizeOfSnap = stdin.readInt32LE(0);
+      if (stdin.length >= 4 + sizeOfSnap + 4) {
+        var sizeOfBody = stdin.readInt32LE(4 + sizeOfSnap);
+        if (stdin.length >= 4 + sizeOfSnap + 4 + sizeOfBody) {
+          var snap = stdin.toString('utf8', 4, 4 + sizeOfSnap);
+          var body = Buffer.alloc(sizeOfBody);
+          var startOfBody = 4 + sizeOfSnap + 4;
+          stdin.copy(body, 0, startOfBody, startOfBody + sizeOfBody);
+          stdin = Buffer.alloc(0);
+          var code = module.wrap(body);
+          var s = new vm.Script(code, {
+            filename: snap,
+            produceCachedData: true,
+            sourceless: true
+          });
+          if (!s.cachedDataProduced) {
+            console.error('Pkg: Cached data not produced.');
+            process.exit(2);
+          }
+          var h = Buffer.alloc(4);
+          var b = s.cachedData;
+          h.writeInt32LE(b.length, 0);
+          process.stdout.write(h);
+          process.stdout.write(b);
+        }
+      }
+    }
+  });
+  process.stdin.resume();
+`;
+const children = {};
+function fabricate(bakes, fabricator, snap, body, cb) {
+    const activeBakes = bakes.filter((bake) => {
+        // list of bakes that don't influence the bytecode
+        const bake2 = bake.replace(/_/g, '-');
+        return !['--prof', '--v8-options', '--trace-opt', '--trace-deopt'].includes(bake2);
+    });
+    const cmd = fabricator.binaryPath;
+    const key = JSON.stringify([cmd, activeBakes]);
+    let child = children[key];
+    if (!child) {
+        const stderr = log_1.log.debugMode ? process.stdout : 'ignore';
+        children[key] = (0, child_process_1.spawn)(cmd, activeBakes.concat('-e', script), {
+            stdio: ['pipe', 'pipe', stderr],
+            env: { PKG_EXECPATH: 'PKG_INVOKE_NODEJS' },
+        });
+        child = children[key];
+    }
+    function kill() {
+        delete children[key];
+        child.kill();
+    }
+    let stdout = Buffer.alloc(0);
+    function onError(error) {
+        removeListeners();
+        kill();
+        cb(new Error(`Failed to make bytecode ${fabricator.nodeRange}-${fabricator.arch} for file ${snap} error (${error.message})`));
+    }
+    function onClose(code) {
+        removeListeners();
+        kill();
+        if (code !== 0) {
+            return cb(new Error(`Failed to make bytecode ${fabricator.nodeRange}-${fabricator.arch} for file ${snap}`));
+        }
+        console.log(stdout.toString());
+        return cb(new Error(`${cmd} closed unexpectedly`));
+    }
+    function onData(data) {
+        stdout = Buffer.concat([stdout, data]);
+        if (stdout.length >= 4) {
+            const sizeOfBlob = stdout.readInt32LE(0);
+            if (stdout.length >= 4 + sizeOfBlob) {
+                const blob = Buffer.alloc(sizeOfBlob);
+                stdout.copy(blob, 0, 4, 4 + sizeOfBlob);
+                removeListeners();
+                return cb(undefined, blob);
+            }
+        }
+    }
+    function removeListeners() {
+        child.removeListener('error', onError);
+        child.removeListener('close', onClose);
+        child.stdin.removeListener('error', onError);
+        child.stdout.removeListener('error', onError);
+        child.stdout.removeListener('data', onData);
+    }
+    child.on('error', onError);
+    child.on('close', onClose);
+    child.stdin.on('error', onError);
+    child.stdout.on('error', onError);
+    child.stdout.on('data', onData);
+    const h = Buffer.alloc(4);
+    let b = Buffer.from(snap);
+    h.writeInt32LE(b.length, 0);
+    child.stdin.write(h);
+    child.stdin.write(b);
+    b = body;
+    h.writeInt32LE(b.length, 0);
+    child.stdin.write(h);
+    child.stdin.write(b);
+}
+exports.fabricate = fabricate;
+function fabricateTwice(bakes, fabricator, snap, body, cb) {
+    fabricate(bakes, fabricator, snap, body, (error, buffer) => {
+        // node0 can not produce second time, even if first time produced fine,
+        // probably because of 'filename' cache. also, there are weird cases
+        // when node4 can not compile as well, for example file 'lib/js-yaml/dumper.js'
+        // of package js-yaml@3.9.0 does not get bytecode second time on node4-win-x64
+        if (error)
+            return fabricate(bakes, fabricator, snap, body, cb);
+        cb(undefined, buffer);
+    });
+}
+exports.fabricateTwice = fabricateTwice;
+function shutdown() {
+    for (const key in children) {
+        if (children[key]) {
+            const child = children[key];
+            delete children[key];
+            child.kill();
+        }
+    }
+}
+exports.shutdown = shutdown;
+//# sourceMappingURL=fabricator.js.map

package/lib-es5/follow.js

@@ -0,0 +1,190 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.follow = void 0;
+const resolve_1 = require("resolve");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const common_1 = require("./common");
+const resolver_1 = require("./resolver");
+const PROOF = 'a-proof-that-main-is-captured.js';
+function parentDirectoriesContain(parent, directory) {
+    let currentParent = parent;
+    while (true) {
+        if (currentParent === directory) {
+            return true;
+        }
+        const newParent = path_1.default.dirname(currentParent);
+        if (newParent === currentParent) {
+            return false;
+        }
+        currentParent = newParent;
+    }
+}
+/**
+ * Check if a specifier looks like a valid npm package name
+ * npm package names must be lowercase and can only contain:
+ * - lowercase letters, digits, hyphens, underscores, dots
+ * - can be scoped (@scope/package)
+ * This helps filter out generated aliases like "connectNonLiteral"
+ */
+function isValidPackageName(specifier) {
+    // Scoped packages: @scope/package
+    if (specifier.startsWith('@')) {
+        const parts = specifier.split('/');
+        if (parts.length < 2)
+            return false;
+        // Scope must start with @ and both parts must be valid
+        return /^@[a-z0-9_.-]+$/.test(parts[0]) && /^[a-z0-9_.-]+$/.test(parts[1]);
+    }
+    // Regular package: must be lowercase with allowed characters
+    // Package name is the part before the first '/' (if any)
+    const packageName = specifier.split('/')[0];
+    return /^[a-z0-9_.-]+$/.test(packageName);
+}
+function follow(x, opts) {
+    // TODO async version
+    return new Promise((resolve, reject) => {
+        // Try ESM-aware resolution first for non-relative specifiers
+        // Skip if the specifier doesn't look like a valid npm package name
+        // (e.g., generated aliases like "connectNonLiteral")
+        if (!x.startsWith('.') &&
+            !x.startsWith('/') &&
+            !path_1.default.isAbsolute(x) &&
+            isValidPackageName(x)) {
+            try {
+                let extensions;
+                if (Array.isArray(opts.extensions)) {
+                    extensions = opts.extensions;
+                }
+                else if (opts.extensions) {
+                    extensions = [opts.extensions];
+                }
+                else {
+                    extensions = ['.js', '.json', '.node'];
+                }
+                const result = (0, resolver_1.resolveModule)(x, {
+                    basedir: opts.basedir || process.cwd(),
+                    extensions,
+                });
+                // Only use ESM resolution result if it's an actual ESM package
+                // For CJS packages, fall through to standard CommonJS resolution
+                // to ensure all callbacks (catchReadFile, catchPackageFilter) are handled correctly
+                if (result.isESM) {
+                    // This is a real ESM package, handle it here
+                    if (opts.catchReadFile) {
+                        // Find the package.json for this resolved module
+                        let currentDir = path_1.default.dirname(result.resolved);
+                        while (currentDir !== path_1.default.dirname(currentDir)) {
+                            const pkgPath = path_1.default.join(currentDir, 'package.json');
+                            // Honor ignoreFile to ensure correct package marker determination
+                            if (opts.ignoreFile &&
+                                path_1.default.normalize(pkgPath) === path_1.default.normalize(opts.ignoreFile)) {
+                                // Skip this package.json as it's marked to be ignored
+                                currentDir = path_1.default.dirname(currentDir);
+                                continue;
+                            }
+                            if (fs_1.default.existsSync(pkgPath)) {
+                                // Check if this package.json is in node_modules (not the root package)
+                                if (currentDir.includes('node_modules')) {
+                                    opts.catchReadFile(pkgPath);
+                                    // Also call catchPackageFilter if provided
+                                    if (opts.catchPackageFilter) {
+                                        const pkgContent = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf8'));
+                                        // If package doesn't have a "main" field but we resolved via exports,
+                                        // add a synthetic "main" field so runtime resolution works
+                                        if (!pkgContent.main) {
+                                            const relativePath = path_1.default.relative(currentDir, result.resolved);
+                                            pkgContent.main = `./${relativePath.replace(/\\/g, '/')}`;
+                                        }
+                                        opts.catchPackageFilter(pkgContent, currentDir, currentDir);
+                                    }
+                                    break;
+                                }
+                            }
+                            currentDir = path_1.default.dirname(currentDir);
+                        }
+                    }
+                    // ESM package resolved successfully
+                    resolve(result.resolved);
+                    return;
+                }
+                // CJS package - fall through to standard CommonJS resolution
+                // to handle all callbacks properly
+            }
+            catch (_error) {
+                // ESM resolution failed - fall through to standard CommonJS resolution
+            }
+        }
+        // Use standard CommonJS resolution
+        try {
+            resolve((0, resolve_1.sync)(x, {
+                basedir: opts.basedir,
+                extensions: opts.extensions,
+                isFile: (file) => {
+                    if (opts.ignoreFile &&
+                        path_1.default.join(path_1.default.dirname(opts.ignoreFile), PROOF) === file) {
+                        return true;
+                    }
+                    let stat;
+                    try {
+                        stat = fs_1.default.statSync(file);
+                    }
+                    catch (e) {
+                        const ex = e;
+                        if (ex && (ex.code === 'ENOENT' || ex.code === 'ENOTDIR'))
+                            return false;
+                        throw ex;
+                    }
+                    return stat.isFile() || stat.isFIFO();
+                },
+                isDirectory: (directory) => {
+                    if (opts.ignoreFile &&
+                        parentDirectoriesContain(opts.ignoreFile, directory)) {
+                        return false;
+                    }
+                    let stat;
+                    try {
+                        stat = fs_1.default.statSync(directory);
+                    }
+                    catch (e) {
+                        const ex = e;
+                        if (ex && (ex.code === 'ENOENT' || ex.code === 'ENOTDIR')) {
+                            return false;
+                        }
+                        throw ex;
+                    }
+                    return stat.isDirectory();
+                },
+                readFileSync: (file) => {
+                    if (opts.ignoreFile && opts.ignoreFile === file) {
+                        return Buffer.from(`{"main":"${PROOF}"}`);
+                    }
+                    if (opts.catchReadFile) {
+                        opts.catchReadFile(file);
+                    }
+                    return fs_1.default.readFileSync(file);
+                },
+                packageFilter: (config, base, dir) => {
+                    if (opts.catchPackageFilter) {
+                        opts.catchPackageFilter(config, base, dir);
+                    }
+                    return config;
+                },
+                /** function to synchronously resolve a potential symlink to its real path */
+                // realpathSync?: (file: string) => string;
+                realpathSync: (file) => {
+                    const file2 = (0, common_1.toNormalizedRealPath)(file);
+                    return file2;
+                },
+            }));
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+exports.follow = follow;
+//# sourceMappingURL=follow.js.map

package/lib-es5/help.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const colors_1 = require("./colors");
+function help() {
+    console.log(`
+  ${colors_1.pc.bold('pkg')} [options] <input>
+
+  ${colors_1.pc.dim('Options:')}
+
+    -h, --help           output usage information
+    -v, --version        output pkg version
+    -t, --targets        comma-separated list of targets (see examples)
+    -c, --config         package.json or any json file with top-level config
+    --options            bake v8 options into executable to run with them on
+    -o, --output         output file name or template for several files
+    --out-path           path to save output one or more executables
+    -d, --debug          show more information during packaging process [off]
+    -b, --build          don't download prebuilt base binaries, build them
+    --public             speed up and disclose the sources of top-level project
+    --public-packages    force specified packages to be considered public
+    --no-bytecode        skip bytecode generation and include source files as plain js
+    --no-native-build    skip native addons build
+    --no-dict            comma-separated list of packages names to ignore dictionaries. Use --no-dict * to disable all dictionaries
+    -C, --compress       [default=None] compression algorithm = Brotli or GZip
+    --sea                (Experimental) compile give file using node's SEA feature. Requires node v20.0.0 or higher and only single file is supported
+
+  ${colors_1.pc.dim('Examples:')}
+
+  ${colors_1.pc.gray('–')} Makes executables for Linux, macOS and Windows
+    ${colors_1.pc.cyan('$ pkg index.js')}
+  ${colors_1.pc.gray('–')} Takes package.json from cwd and follows 'bin' entry
+    ${colors_1.pc.cyan('$ pkg .')}
+  ${colors_1.pc.gray('–')} Makes executable for particular target machine
+    ${colors_1.pc.cyan('$ pkg -t node14-win-arm64 index.js')}
+  ${colors_1.pc.gray('–')} Makes executables for target machines of your choice
+    ${colors_1.pc.cyan('$ pkg -t node22-linux,node24-linux,node24-win index.js')}
+  ${colors_1.pc.gray('–')} Bakes '--expose-gc' and '--max-heap-size=34' into executable
+    ${colors_1.pc.cyan('$ pkg --options "expose-gc,max-heap-size=34" index.js')}
+  ${colors_1.pc.gray('–')} Consider packageA and packageB to be public
+    ${colors_1.pc.cyan('$ pkg --public-packages "packageA,packageB" index.js')}
+  ${colors_1.pc.gray('–')} Consider all packages to be public
+    ${colors_1.pc.cyan('$ pkg --public-packages "*" index.js')}
+  ${colors_1.pc.gray('–')} Bakes '--expose-gc' into executable
+    ${colors_1.pc.cyan('$ pkg --options expose-gc index.js')}
+  ${colors_1.pc.gray('–')} reduce size of the data packed inside the executable with GZip
+    ${colors_1.pc.cyan('$ pkg --compress GZip index.js')}
+  ${colors_1.pc.gray('–')} compile the file using node's SEA feature. Creates executables for Linux, macOS and Windows
+    ${colors_1.pc.cyan('$ pkg --sea index.js')}
+`);
+}
+exports.default = help;
+//# sourceMappingURL=help.js.map

package/lib-es5/index.d.ts

@@ -0,0 +1,2 @@
+export declare function exec(argv2: string[]): Promise<void>;
+//# sourceMappingURL=index.d.ts.map