@hakobu/hakobu 1.0.0

package/lib-es5/bin.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const minimist_1 = __importDefault(require("minimist"));
+const log_1 = require("./log");
+const packager_1 = require("./packager");
+const commands_1 = require("./commands");
+const config_1 = require("./config");
+const { version } = JSON.parse((0, fs_1.readFileSync)(path_1.default.join(__dirname, '../package.json'), 'utf-8'));
+const USAGE = `
+hakobu v${version} — Package Node.js projects into executables
+
+Usage:
+  hakobu <project-root>                     Package a project
+  hakobu targets                            Show available targets and cache
+  hakobu inspect <project-root>             Analyze a project without packaging
+  hakobu doctor <project-root> [--target]   Check if a project is ready to package
+
+Options:
+  --target <spec>     Target(s), comma-separated (e.g., node24-linux-x64,node24-win-x64)
+                      Use 'all' for all published targets. Default: host
+  --output <path>     Output executable path
+  --entry <file>      Entry file (relative to project root)
+  --help, -h          Show this help
+  --version, -v       Show version
+  --debug, -d         Show detailed packaging diagnostics
+
+Bundle mode (optional — for TypeScript / monorepo projects):
+  --bundle [name]     Pre-bundle with Rolldown before packaging
+  --external <mod>    Keep module external when bundling (repeatable)
+
+Advanced:
+  --bytecode          Compile JS to V8 bytecode before packaging
+  --compress <algo>   Compress snapshot payload (Brotli or GZip)
+  --options <flags>   Bake V8 flags into executable (comma-separated)
+  --build, -b         Force local build of base binary (skip download)
+                      Example: --options "expose-gc,max-heap-size=34"
+  --app-bundle        Wrap macOS output in a .app bundle (macOS only)
+                      Output path becomes the .app directory
+  --appdir            Wrap Linux output in an AppDir (Linux only)
+                      Output path becomes the .AppDir directory
+  --appimage          Build an AppImage from AppDir (Linux only)
+                      Requires external appimagetool in PATH
+
+macOS bundle metadata (used with --app-bundle):
+  --bundle-id <id>      CFBundleIdentifier (e.g., com.example.my-app)
+  --bundle-version <v>  CFBundleVersion (e.g., 1.2.3)
+  --short-version <v>   CFBundleShortVersionString (defaults to bundle-version)
+  --display-name <n>    CFBundleDisplayName
+  --copyright <s>       NSHumanReadableCopyright
+  --macos-icon <path>   Path to .icns file for the app icon
+                        Also configurable via "hakobu.macos" in package.json
+
+Linux AppDir metadata (used with --appdir):
+  --desktop-name <n>    Application name in .desktop file
+  --desktop-comment <s> Short description / tooltip
+  --desktop-categories <c>  Semicolon-separated categories (e.g., Utility;Development;)
+  --desktop-terminal    App needs a terminal (default: true)
+  --no-desktop-terminal App does not need a terminal
+  --linux-icon <path>   Path to .png file for the app icon
+                        Also configurable via "hakobu.linux" in package.json
+
+Signing:
+  --sign-identity <id>  macOS code-signing identity (default: ad-hoc)
+                        Also: HAKOBU_SIGN_IDENTITY env var
+  --notarize            Submit to Apple notarization after signing
+                        Requires: HAKOBU_APPLE_ID, HAKOBU_APPLE_PASSWORD,
+                        HAKOBU_APPLE_TEAM_ID env vars
+                        See docs/macos-notarization.md
+  --win-cert <path>     Windows Authenticode .pfx/.p12 certificate
+                        Also: HAKOBU_WIN_CERT env var
+  --win-cert-password   Certificate password
+                        Also: HAKOBU_WIN_CERT_PASSWORD env var
+                        See docs/windows-signing.md
+
+Windows metadata (PE VERSIONINFO):
+  --product-name <n>    Product name in file properties
+  --file-description <d> Description shown in Task Manager
+  --company-name <n>    Company / publisher name
+  --file-version <v>    File version (e.g., 1.2.3)
+  --product-version <v> Product version (defaults to file version)
+  --icon <path>         .ico file to embed as application icon
+                        See docs/exe-metadata.md
+
+  Without --bundle, Hakobu packages JS files directly (native mode).
+  With --bundle, Rolldown compiles TS and resolves dependencies first.
+  See docs/bundle-mode.md for semantic differences and caveats.
+
+Config:
+  Hakobu reads the "hakobu" field from package.json:
+    { "hakobu": { "entry": "src/index.js", "assets": ["templates/**"] } }
+
+  Legacy "pkg" config is accepted with migration warnings.
+  CLI flags override package.json config.
+
+Examples:
+  hakobu ./my-app --output ./dist/app                    Native mode
+  hakobu ./my-ts-app --bundle --output ./dist/app        Bundle mode
+  hakobu ./app --bundle --entry src/cli.ts --external electron
+`.trim();
+function printConfigWarnings(warnings) {
+    let hasUnsupported = false;
+    for (const w of warnings) {
+        if (w.type === 'unsupported') {
+            log_1.log.error(`[config] ${w.message}`);
+            hasUnsupported = true;
+        }
+        else if (w.type === 'deprecated') {
+            log_1.log.warn(`[config] ${w.message}`);
+        }
+        else {
+            log_1.log.info(`[config] ${w.message}`);
+        }
+    }
+    return hasUnsupported;
+}
+async function main() {
+    if (process.env.CHDIR && process.env.CHDIR !== process.cwd()) {
+        process.chdir(process.env.CHDIR);
+    }
+    const argv = (0, minimist_1.default)(process.argv.slice(2), {
+        string: ['target', 'targets', 'output', 'entry', 'external', 'config',
+            'out-path', 'outdir', 'out-dir', 'compress', 'public-packages',
+            'options', 'no-dict', 'sign-identity', 'win-cert', 'win-cert-password',
+            'product-name', 'file-description', 'company-name', 'file-version',
+            'product-version', 'icon',
+            'bundle-id', 'bundle-version', 'short-version', 'display-name', 'copyright',
+            'macos-icon', 'desktop-name', 'desktop-comment', 'desktop-categories',
+            'linux-icon'],
+        boolean: ['help', 'version', 'bytecode', 'no-bytecode', 'build', 'public', 'sea',
+            'no-native-build', 'notarize', 'app-bundle', 'appdir',
+            'desktop-terminal', 'no-desktop-terminal', 'appimage'],
+        alias: { h: 'help', v: 'version', o: 'output', t: 'target',
+            c: 'config', b: 'build', d: 'debug', C: 'compress' },
+    });
+    if (argv.version) {
+        console.log(version);
+        return;
+    }
+    if (argv.help || argv._.length === 0) {
+        console.log(USAGE);
+        return;
+    }
+    // Debug mode — activates verbose logging throughout the pipeline
+    if (argv.debug) {
+        log_1.log.debugMode = true;
+    }
+    const command = argv._[0];
+    switch (command) {
+        case 'targets':
+            await (0, commands_1.commandTargets)();
+            break;
+        case 'inspect':
+            await (0, commands_1.commandInspect)(argv._[1] || '.');
+            break;
+        case 'doctor':
+            await (0, commands_1.commandDoctor)(argv._[1] || '.', argv.target);
+            break;
+        default: {
+            const { options, warnings } = (0, config_1.normalizeConfig)({
+                projectRoot: path_1.default.resolve(command),
+                entry: argv.entry,
+                target: argv.target,
+                output: argv.output,
+                bundle: argv.bundle,
+                external: argv.external,
+                bytecode: argv.bytecode,
+                // Legacy aliases
+                targets: argv.targets,
+                config: argv.config,
+                'out-path': argv['out-path'],
+                outdir: argv.outdir,
+                'out-dir': argv['out-dir'],
+                'no-bytecode': argv['no-bytecode'],
+                compress: argv.compress,
+                build: argv.build,
+                public: argv.public,
+                'public-packages': argv['public-packages'],
+                sea: argv.sea,
+                options: argv.options,
+                'no-native-build': argv['no-native-build'],
+                'no-dict': argv['no-dict'],
+            });
+            const hasUnsupported = printConfigWarnings(warnings);
+            if (hasUnsupported) {
+                log_1.log.error('Unsupported options detected. Remove them or see migration guidance above.');
+                process.exit(1);
+            }
+            // Detect multi-target: comma-separated --target or 'all'
+            const targetStr = options.target || '';
+            const isMulti = targetStr.includes(',') || targetStr === 'all';
+            // Signing options
+            if (argv['sign-identity'])
+                options.signIdentity = argv['sign-identity'];
+            if (argv.notarize)
+                options.notarize = true;
+            if (argv['win-cert'])
+                options.winCertPath = argv['win-cert'];
+            if (argv['win-cert-password'])
+                options.winCertPassword = argv['win-cert-password'];
+            // App bundle / AppDir
+            if (argv['app-bundle'])
+                options.appBundle = true;
+            if (argv.appdir)
+                options.appDir = true;
+            if (argv.appimage)
+                options.appImage = true;
+            // macOS bundle metadata — CLI flags override config
+            const cliMacos = {};
+            if (argv['bundle-id'])
+                cliMacos.bundleId = argv['bundle-id'];
+            if (argv['bundle-version'])
+                cliMacos.bundleVersion = argv['bundle-version'];
+            if (argv['short-version'])
+                cliMacos.shortVersion = argv['short-version'];
+            if (argv['display-name'])
+                cliMacos.displayName = argv['display-name'];
+            if (argv.copyright)
+                cliMacos.copyright = argv.copyright;
+            if (argv['macos-icon'])
+                cliMacos.icon = argv['macos-icon'];
+            if (Object.keys(cliMacos).length > 0) {
+                options.macos = { ...options.macos, ...cliMacos };
+            }
+            // Linux desktop metadata — CLI flags override config
+            const cliLinux = {};
+            if (argv['desktop-name'])
+                cliLinux.name = argv['desktop-name'];
+            if (argv['desktop-comment'])
+                cliLinux.comment = argv['desktop-comment'];
+            if (argv['desktop-categories'])
+                cliLinux.categories = argv['desktop-categories'];
+            if (argv['desktop-terminal'])
+                cliLinux.terminal = true;
+            if (argv['no-desktop-terminal'])
+                cliLinux.terminal = false;
+            if (argv['linux-icon'])
+                cliLinux.iconPath = argv['linux-icon'];
+            if (Object.keys(cliLinux).length > 0) {
+                options.linux = { ...options.linux, ...cliLinux };
+            }
+            // PE metadata — CLI flags override config
+            const cliMeta = {};
+            if (argv['product-name'])
+                cliMeta.productName = argv['product-name'];
+            if (argv['file-description'])
+                cliMeta.fileDescription = argv['file-description'];
+            if (argv['company-name'])
+                cliMeta.companyName = argv['company-name'];
+            if (argv['file-version'])
+                cliMeta.fileVersion = argv['file-version'];
+            if (argv['product-version'])
+                cliMeta.productVersion = argv['product-version'];
+            if (argv.icon)
+                cliMeta.icon = argv.icon;
+            if (Object.keys(cliMeta).length > 0) {
+                options.metadata = { ...options.metadata, ...cliMeta };
+            }
+            if (isMulti) {
+                const results = await (0, packager_1.packageMultiple)({
+                    projectRoot: options.projectRoot,
+                    targets: [targetStr],
+                    outputDir: options.output,
+                    entry: options.entry,
+                    assets: options.assets,
+                    externals: options.externals,
+                    bundle: options.bundle,
+                    bundleExternal: options.bundleExternal,
+                    signIdentity: options.signIdentity,
+                    notarize: options.notarize,
+                    winCertPath: options.winCertPath,
+                    winCertPassword: options.winCertPassword,
+                    metadata: options.metadata,
+                    appBundle: options.appBundle,
+                    macos: options.macos,
+                    appDir: options.appDir,
+                    linux: options.linux,
+                    appImage: options.appImage,
+                    compress: options.compress,
+                    options: options.options,
+                    forceBuild: options.forceBuild,
+                });
+                const failed = results.filter(r => r.status === 'failed');
+                if (failed.length > 0)
+                    process.exit(1);
+            }
+            else {
+                await (0, packager_1.packageApp)(options);
+            }
+            break;
+        }
+    }
+}
+main().catch((error) => {
+    if (!error.wasReported)
+        log_1.log.error(error);
+    process.exit(2);
+});
+//# sourceMappingURL=bin.js.map

package/lib-es5/bootstrap.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * Hakobu Runtime Bootstrap
+ *
+ * Initializes the snapshot filesystem and loads the packaged entrypoint.
+ *
+ * Startup sequence:
+ *   1. Mount the snapshot FS (patch Node's fs module)
+ *   2. Determine entry format (ESM or CJS)
+ *   3. For ESM: register loader hooks via module.register(), then import()
+ *   4. For CJS: require() the entry directly
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.determineBootstrapMode = exports.bootstrap = void 0;
+const node_module_1 = require("node:module");
+const node_module_2 = __importDefault(require("node:module"));
+const node_url_1 = require("node:url");
+const snapshot_fs_patch_1 = require("./snapshot-fs-patch");
+const snapshot_path_1 = require("./snapshot-path");
+const esm_hooks_1 = require("./esm-hooks");
+// ─────────────────────────────────────────────────────────────────────
+// Bootstrap
+// ─────────────────────────────────────────────────────────────────────
+async function bootstrap(sfs, options) {
+    const unpatch = (0, snapshot_fs_patch_1.patchFS)(sfs);
+    const entrySnapshotPath = options?.entry ?? sfs.getEntrypoint();
+    const format = sfs.getModuleFormat(entrySnapshotPath) ?? sfs.getEntrypointFormat();
+    if (format === 'esm') {
+        return bootstrapESM(sfs, entrySnapshotPath, unpatch, options?.dryRun ?? false);
+    }
+    else {
+        return bootstrapCJS(sfs, entrySnapshotPath, unpatch, options?.dryRun ?? false);
+    }
+}
+exports.bootstrap = bootstrap;
+// ─────────────────────────────────────────────────────────────────────
+// ESM bootstrap — registers real loader hooks
+// ─────────────────────────────────────────────────────────────────────
+async function bootstrapESM(sfs, entrySnapshotPath, unpatch, dryRun) {
+    const entryUrl = (0, snapshot_path_1.toFileUrl)(entrySnapshotPath);
+    if (!dryRun) {
+        // Build the transfer data for the loader hooks
+        const transferData = buildHookTransferData(sfs);
+        // Register the ESM loader hooks via data: URL.
+        // The hooks run in Node's loader thread and receive the snapshot
+        // data via initialize(). They handle resolve + load for all
+        // snapshot-owned modules.
+        const hookSource = (0, esm_hooks_1.getHookSource)();
+        const hookUrl = `data:text/javascript,${encodeURIComponent(hookSource)}`;
+        (0, node_module_1.register)(hookUrl, {
+            parentURL: (0, node_url_1.pathToFileURL)(__filename).href,
+            data: transferData,
+            transferList: [transferData.blob],
+        });
+        // Pre-cache all CJS modules from the snapshot in Node's module
+        // cache. This is needed because Node 24's CJS translator creates
+        // its own require() that doesn't go through the hooks for nested
+        // CJS requires. By pre-caching, require() finds the module in
+        // cache and skips the file-existence validation.
+        preloadCJSModules(sfs);
+        // Now import the entry. The registered hooks will handle
+        // resolution and loading for ESM snapshot modules.
+        //
+        // Use Function constructor to get the real import() that goes
+        // through the ESM loader, not TypeScript's CJS-compiled require().
+        const dynamicImport = new Function('url', 'return import(url)');
+        await dynamicImport(entryUrl);
+    }
+    return {
+        mode: 'esm',
+        entrypoint: entrySnapshotPath,
+        entryUrl,
+        unpatch,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────
+// CJS bootstrap
+// ─────────────────────────────────────────────────────────────────────
+async function bootstrapCJS(sfs, entrySnapshotPath, unpatch, dryRun) {
+    const nativePath = (0, snapshot_path_1.toNative)(entrySnapshotPath);
+    if (!dryRun) {
+        // CJS entry is loaded directly via require(). The patched
+        // Module._resolveFilename + Module._compile handle snapshot
+        // resolution and source loading. No preloading needed.
+        require(nativePath);
+    }
+    return {
+        mode: 'cjs',
+        entrypoint: entrySnapshotPath,
+        entryUrl: null,
+        unpatch,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────
+// Hook data builder
+// ─────────────────────────────────────────────────────────────────────
+function buildHookTransferData(sfs) {
+    const index = sfs.index;
+    // Build entries map: path → { offset, size, format }
+    const entries = {};
+    for (const entry of index.entries) {
+        entries[entry.path] = {
+            offset: entry.offset,
+            size: entry.size,
+            format: entry.format,
+        };
+    }
+    // Build packages map: path → { type, main, directory }
+    const packages = {};
+    for (const [path, pkg] of Object.entries(index.packages)) {
+        packages[path] = {
+            type: pkg.type,
+            main: pkg.main,
+            directory: pkg.directory,
+        };
+    }
+    // Get directory paths for existence checks
+    const directories = Object.keys(index.directories);
+    // Copy the blob to a transferable ArrayBuffer
+    const blob = sfs.blob;
+    const blobCopy = new ArrayBuffer(blob.length);
+    new Uint8Array(blobCopy).set(blob);
+    return {
+        entries,
+        packages,
+        blob: blobCopy,
+        appId: index.appId,
+        directories,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────
+// CJS preloading
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Pre-populate Node's CJS module cache for JSON/package.json files in
+ * the snapshot. CJS scripts are NOT preloaded — they're loaded lazily
+ * when require() is called, using the _resolveFilename + _compile
+ * patches on the main thread.
+ *
+ * JSON files are preloaded eagerly because they have no side effects
+ * and are frequently needed for package resolution.
+ */
+function preloadCJSModules(sfs) {
+    const index = sfs.index;
+    for (const entry of index.entries) {
+        // Only preload JSON files eagerly (no side effects)
+        if (entry.kind !== 'json' && entry.kind !== 'package-json')
+            continue;
+        const filename = (0, snapshot_path_1.toNative)(entry.path);
+        if (node_module_2.default._cache[filename])
+            continue;
+        try {
+            const content = sfs.readFileSync(entry.path).toString('utf8');
+            const mod = new node_module_2.default(filename, null);
+            mod.filename = filename;
+            mod.exports = JSON.parse(content);
+            mod.loaded = true;
+            node_module_2.default._cache[filename] = mod;
+        }
+        catch {
+            // Skip invalid JSON
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────
+// Diagnostics
+// ─────────────────────────────────────────────────────────────────────
+function determineBootstrapMode(sfs) {
+    const entrypoint = sfs.getEntrypoint();
+    const format = sfs.getEntrypointFormat();
+    const entryUrl = (0, snapshot_path_1.toFileUrl)(entrypoint);
+    const nativePath = (0, snapshot_path_1.toNative)(entrypoint);
+    return { entrypoint, format, entryUrl, nativePath };
+}
+exports.determineBootstrapMode = determineBootstrapMode;
+//# sourceMappingURL=bootstrap.js.map