pakstr 0.30.0 → 0.31.0

package/dist/desktop/windows.js

@@ -0,0 +1,384 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WINDOWS_UNINSTALLER = exports.WINDOWS_X64_TARGET = void 0;
+exports.assertWindowsAppIdentity = assertWindowsAppIdentity;
+exports.windowsVersion = windowsVersion;
+exports.windowsExeName = windowsExeName;
+exports.windowsOutputPaths = windowsOutputPaths;
+exports.windowsPackagerOptions = windowsPackagerOptions;
+exports.packageWindowsApp = packageWindowsApp;
+exports.assertMakensis = assertMakensis;
+exports.validateWindowsZip = validateWindowsZip;
+exports.verifyWindowsApp = verifyWindowsApp;
+exports.assertWindowsVersionInfo = assertWindowsVersionInfo;
+exports.assertAsarIntegrityResource = assertAsarIntegrityResource;
+exports.assertNsisInstaller = assertNsisInstaller;
+exports.nsisString = nsisString;
+exports.nsisPath = nsisPath;
+exports.windowsInstallerScript = windowsInstallerScript;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const process_1 = require("../runners/process");
+const artifacts_1 = require("./common/artifacts");
+const asar_1 = require("./common/asar");
+const electron_1 = require("./common/electron");
+const files_1 = require("./common/files");
+const fuses_1 = require("./common/fuses");
+const packager_1 = require("./common/packager");
+const stage_1 = require("./stage");
+const zip_1 = require("./zip");
+exports.WINDOWS_X64_TARGET = "windows-x64";
+/** The installer's uninstaller, next to the app executable. */
+exports.WINDOWS_UNINSTALLER = "Uninstall.exe";
+const NSIS_OPTIONS = {
+    timeoutMs: 20 * 60_000,
+    timeoutHint: "makensis stopped responding; try again.",
+};
+// Device names Windows reserves for a file name, with or without an extension.
+const WINDOWS_RESERVED_NAME = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$)$/i;
+/**
+ * appName names `<appName>.exe`, the Start menu shortcut, and the portable
+ * folder; appId names the data and install directories. Both must be usable
+ * Windows file names.
+ */
+function assertWindowsAppIdentity(app) {
+    (0, stage_1.assertDesktopAppName)(app.appName);
+    if (/[<>"|?*]/.test(app.appName) || /[. ]$/.test(app.appName) || WINDOWS_RESERVED_NAME.test(app.appName.split(".")[0].trimEnd())) {
+        throw new Error(`app.appName "${app.appName}" cannot be used as a Windows file name: it must not contain < > " | ? *, ` +
+            "end with '.' or a space, or be a reserved device name such as CON or NUL");
+    }
+    if (WINDOWS_RESERVED_NAME.test(app.appId.split(".")[0])) {
+        throw new Error(`app.appId "${app.appId}" cannot be used on Windows: it starts with the reserved device name "${app.appId.split(".")[0]}"`);
+    }
+}
+const WINDOWS_VERSION = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:\.(\d+))?(?:[-+][0-9A-Za-z.+-]*)?$/;
+/**
+ * VERSIONINFO holds four 16-bit numbers, so the executable and installer get
+ * the numeric part of versionName (1.2.3-beta.1 -> 1.2.3.0). versionCode does
+ * not fit. The installed-apps list shows versionName itself.
+ */
+function windowsVersion(versionName) {
+    const match = WINDOWS_VERSION.exec(versionName);
+    const parts = match ? match.slice(1).map((part) => Number(part ?? 0)) : [];
+    if (!match || parts.some((part) => part > 0xffff)) {
+        throw new Error(`app.versionName "${versionName}" cannot be used as a Windows file version: ` +
+            "it must start with one to four numbers between 0 and 65535, like 1.2.3");
+    }
+    return parts.join(".");
+}
+function windowsExeName(app) {
+    return `${app.appName}.exe`;
+}
+/** Installer and portable ZIP next to build.out, named like the APK. */
+function windowsOutputPaths(buildOut, appId) {
+    const dir = (0, artifacts_1.desktopOutputDir)(buildOut);
+    return {
+        installer: (0, artifacts_1.desktopArtifactPath)(dir, appId, exports.WINDOWS_X64_TARGET, "-setup.exe"),
+        portable: (0, artifacts_1.desktopArtifactPath)(dir, appId, exports.WINDOWS_X64_TARGET, ".zip"),
+    };
+}
+/**
+ * @electron/packager options: the shared base (with the allowlist `ignore`)
+ * plus the executable's version resource, rewritten from the app so none of
+ * Electron's "GitHub, Inc." strings remain.
+ */
+function windowsPackagerOptions(options) {
+    const { stagingDir, outDir, electronZipDir, app } = options;
+    const version = windowsVersion(app.versionName);
+    return {
+        ...(0, packager_1.basePackagerOptions)({ stagingDir, outDir, electronZipDir }),
+        platform: "win32",
+        arch: "x64",
+        name: app.appName,
+        appVersion: version,
+        buildVersion: version,
+        appCopyright: app.appName,
+        win32metadata: {
+            CompanyName: app.appName,
+            FileDescription: app.appName,
+            InternalName: app.appName,
+            OriginalFilename: windowsExeName(app),
+            ProductName: app.appName,
+        },
+    };
+}
+/**
+ * Package the staged app as `<appName>.exe` plus Electron's files, flip
+ * fuses, and validate it. Then write the portable ZIP (validated from a fresh
+ * extraction) and the NSIS installer. Returns both paths in `workDir`.
+ */
+async function packageWindowsApp(options) {
+    const { stagingDir, workDir, app } = options;
+    assertWindowsAppIdentity(app);
+    windowsVersion(app.versionName);
+    let makensisVersion;
+    try {
+        makensisVersion = (0, process_1.runProcess)("makensis", ["-VERSION"], NSIS_OPTIONS).stdout;
+    }
+    catch (error) {
+        throw new Error("Windows installers need NSIS 3 (makensis) on PATH: brew install makensis, apt install nsis, " +
+            `or install NSIS on Windows. ${error.message}`);
+    }
+    assertMakensis(makensisVersion);
+    const electronZip = await (0, electron_1.fetchElectronZip)(electron_1.WINDOWS_ELECTRON_ZIP);
+    const { appDir, productPath: exePath } = await (0, packager_1.runPackager)(windowsPackagerOptions({ stagingDir, outDir: path_1.default.join(workDir, "out"), electronZipDir: path_1.default.dirname(electronZip), app }), { name: windowsExeName(app), type: "file" });
+    await (0, fuses_1.flipDesktopFuses)(exePath);
+    await verifyWindowsApp(appDir, app);
+    const portable = (0, artifacts_1.desktopArtifactPath)(workDir, app.appId, exports.WINDOWS_X64_TARGET, ".zip");
+    await (0, zip_1.zipDirectory)(appDir, portable, app.appName);
+    await validateWindowsZip(portable, appDir, app, path_1.default.join(workDir, "verify"));
+    const installer = (0, artifacts_1.desktopArtifactPath)(workDir, app.appId, exports.WINDOWS_X64_TARGET, "-setup.exe");
+    const script = path_1.default.join(workDir, "installer.nsi");
+    fs_1.default.writeFileSync(script, windowsInstallerScript({ app, appDir, outFile: installer }), { flag: "wx" });
+    // -NOCONFIG: a local nsisconf.nsh must not change the installer.
+    (0, process_1.runProcess)("makensis", ["-NOCONFIG", "-V2", "-WX", "-INPUTCHARSET", "UTF8", script], NSIS_OPTIONS);
+    assertNsisInstaller(installer);
+    return { installer, portable };
+}
+/** `makensis -VERSION` prints e.g. "v3.10"; Unicode installers need NSIS 3. */
+function assertMakensis(versionOutput) {
+    const major = /^v?(\d+)\./.exec(versionOutput.trim())?.[1];
+    if (major !== "3") {
+        throw new Error(`Windows installers need NSIS 3 (makensis), found ${JSON.stringify(versionOutput.trim())}`);
+    }
+}
+/** Extract the portable ZIP and check it holds exactly `<appName>/` with the validated app. */
+async function validateWindowsZip(zipPath, appDir, app, extractDir) {
+    const extracted = await (0, zip_1.verifyPortableZip)(zipPath, extractDir, app.appName, (0, zip_1.listRegularFiles)(appDir), { ordered: true });
+    await verifyWindowsApp(extracted, app);
+}
+/** Executable, version resource, asar integrity, fuses, and packaged files of an app folder. */
+async function verifyWindowsApp(appDir, app) {
+    const exePath = path_1.default.join(appDir, windowsExeName(app));
+    if (fs_1.default.existsSync(path_1.default.join(appDir, "electron.exe")))
+        throw new Error("Unexpected electron.exe next to the app executable");
+    const resources = path_1.default.join(appDir, "resources");
+    const resourceEntries = fs_1.default.readdirSync(resources);
+    if (resourceEntries.length !== 1 || resourceEntries[0] !== "app.asar") {
+        throw new Error(`resources must contain only app.asar, found: ${resourceEntries.join(", ")}`);
+    }
+    const asarPath = path_1.default.join(resources, "app.asar");
+    await (0, fuses_1.verifyDesktopFuses)(exePath);
+    const { NtExecutable, NtExecutableResource, Resource } = await import("resedit");
+    const exe = NtExecutable.from(fs_1.default.readFileSync(exePath));
+    if (exe.is32bit())
+        throw new Error(`${windowsExeName(app)} is not a 64-bit executable`);
+    const entries = NtExecutableResource.from(exe).entries;
+    const versionInfo = Resource.VersionInfo.fromEntries(entries);
+    if (versionInfo.length !== 1)
+        throw new Error(`${windowsExeName(app)} must have one version resource`);
+    const [info] = versionInfo;
+    const languages = info.getAllLanguagesForStringValues();
+    if (languages.length !== 1)
+        throw new Error(`${windowsExeName(app)} must have one version string table`);
+    assertWindowsVersionInfo({
+        fileVersion: fixedVersion(info.fixedInfo.fileVersionMS, info.fixedInfo.fileVersionLS),
+        productVersion: fixedVersion(info.fixedInfo.productVersionMS, info.fixedInfo.productVersionLS),
+        strings: info.getStringValues(languages[0]),
+    }, app);
+    const integrity = entries.filter((entry) => entry.type === "INTEGRITY" && entry.id === "ELECTRONASAR");
+    if (integrity.length !== 1)
+        throw new Error(`${windowsExeName(app)} must embed one asar integrity resource`);
+    const headerHash = await (0, asar_1.asarHeaderHash)(asarPath);
+    assertAsarIntegrityResource(Buffer.from(integrity[0].bin).toString("utf8"), headerHash);
+    await (0, asar_1.verifyAppAsar)(asarPath, app);
+}
+function fixedVersion(ms, ls) {
+    return [ms >>> 16, ms & 0xffff, ls >>> 16, ls & 0xffff].join(".");
+}
+/** The executable's VERSIONINFO carries the app's identity, not Electron's. */
+function assertWindowsVersionInfo(info, app) {
+    const version = windowsVersion(app.versionName);
+    const expected = {
+        CompanyName: app.appName,
+        FileDescription: app.appName,
+        FileVersion: version,
+        InternalName: app.appName,
+        LegalCopyright: app.appName,
+        OriginalFilename: windowsExeName(app),
+        ProductName: app.appName,
+        ProductVersion: version,
+    };
+    for (const [key, value] of Object.entries(expected)) {
+        if (info.strings[key] !== value) {
+            throw new Error(`Executable version ${key} is ${JSON.stringify(info.strings[key])}, expected ${JSON.stringify(value)}`);
+        }
+    }
+    if (info.fileVersion !== version || info.productVersion !== version) {
+        throw new Error(`Executable version is ${info.fileVersion}/${info.productVersion}, expected ${version}`);
+    }
+}
+/** Electron's ELECTRONASAR resource: exactly resources\app.asar with its header's SHA-256. */
+function assertAsarIntegrityResource(json, headerHash) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        parsed = null;
+    }
+    const entries = Array.isArray(parsed) ? parsed : [];
+    const [entry] = entries;
+    if (entries.length !== 1 || entry?.file !== "resources\\app.asar" || entry.alg !== "SHA256" || entry.value !== headerHash) {
+        throw new Error("Executable asar integrity does not match resources\\app.asar");
+    }
+}
+/** A PE executable carrying an NSIS installer header. */
+function assertNsisInstaller(installerPath) {
+    const head = (0, files_1.readHead)(installerPath, 1024 * 1024);
+    const peOffset = head.length >= 0x40 && head.toString("latin1", 0, 2) === "MZ" ? head.readUInt32LE(0x3c) : -1;
+    const isPe = peOffset > 0 && peOffset + 4 <= head.length && head.toString("latin1", peOffset, peOffset + 4) === "PE\0\0";
+    if (!isPe || !head.includes("NullsoftInst")) {
+        throw new Error(`Not an NSIS installer: ${installerPath}`);
+    }
+}
+/** Quote a runtime string for an NSIS script: `$` and `"` are escaped, line breaks are refused. */
+function nsisString(value) {
+    if (/[\u0000-\u001f\u007f]/.test(value))
+        throw new Error(`Cannot use ${JSON.stringify(value)} in an NSIS script`);
+    return `"${value.replace(/\$/g, "$$$$").replace(/"/g, '$\\"')}"`;
+}
+/**
+ * Quote a build-host path (File, OutFile). makensis reads these raw (no `$`
+ * escapes) but still expands `${define}` and treats `*`/`?` as wildcards, so
+ * paths containing those or a quote are refused.
+ */
+function nsisPath(value) {
+    if (/[\u0000-\u001f\u007f"*?]|\$\{/.test(value))
+        throw new Error(`Cannot use the path ${JSON.stringify(value)} in an NSIS script`);
+    return `"${value}"`;
+}
+/**
+ * Per-user NSIS installer (no admin rights) into
+ * %LOCALAPPDATA%\Programs\<appId>, with a Start menu shortcut and an
+ * Apps & features entry keyed by appId. Install and uninstall use the same
+ * explicit file list, so the uninstaller never deletes anything it did not
+ * install (no recursive RMDir). A reinstall first runs the previous
+ * uninstaller, so files from an older version or appName do not linger.
+ * App data in %APPDATA%\<appId> is kept.
+ */
+function windowsInstallerScript(options) {
+    const { app, appDir, outFile } = options;
+    const files = (0, zip_1.listRegularFiles)(appDir);
+    if (files.includes(exports.WINDOWS_UNINSTALLER))
+        throw new Error(`The packaged app must not contain ${exports.WINDOWS_UNINSTALLER}`);
+    const version = windowsVersion(app.versionName);
+    const exe = windowsExeName(app);
+    const q = nsisString;
+    // Escaped for the inside of a quoted NSIS string.
+    const inner = (value) => q(value).slice(1, -1);
+    const win = (file) => file.split("/").join("\\");
+    /** A path under $INSTDIR as an NSIS string. */
+    const instdir = (file) => `"$INSTDIR\\${inner(win(file))}"`;
+    /** A command line running a file under $INSTDIR, quoted for CreateProcess. */
+    const command = (file, args = "") => `"$\\"$INSTDIR\\${inner(win(file))}$\\"${args ? ` ${args}` : ""}"`;
+    const uninstallKey = q(`Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\${app.appId}`);
+    const shortcut = `"$SMPROGRAMS\\${inner(app.appName)}.lnk"`;
+    const sizeKb = Math.ceil(files.reduce((total, file) => total + fs_1.default.statSync(path_1.default.join(appDir, ...file.split("/"))).size, 0) / 1024);
+    const dirs = [...new Set(files.flatMap((file) => file.split("/").slice(0, -1).map((_, i, parts) => parts.slice(0, i + 1).join("/"))))].sort();
+    const installFiles = [];
+    for (const dir of ["", ...dirs]) {
+        const inDir = files.filter((file) => path_1.default.posix.dirname(file) === (dir || "."));
+        if (inDir.length === 0)
+            continue;
+        installFiles.push(`  SetOutPath ${dir ? instdir(dir) : '"$INSTDIR"'}`);
+        for (const file of inDir)
+            installFiles.push(`  File ${nsisPath(path_1.default.join(appDir, ...file.split("/")))}`);
+    }
+    const ensureClosed = (abort) => [
+        `  \${If} \${FileExists} ${instdir(exe)}`,
+        "    ${Do}",
+        "      ClearErrors",
+        `      FileOpen $0 ${instdir(exe)} a`,
+        "      ${IfNot} ${Errors}",
+        "        FileClose $0",
+        "        ${Break}",
+        "      ${EndIf}",
+        `      MessageBox MB_RETRYCANCEL|MB_ICONEXCLAMATION ${q(`Close ${app.appName}, then click Retry.`)} /SD IDCANCEL IDRETRY +2`,
+        `      Abort ${q(abort)}`,
+        "    ${Loop}",
+        "  ${EndIf}",
+    ];
+    return [
+        "; Generated by pakstr. Do not edit.",
+        "Unicode true",
+        "ManifestDPIAware true",
+        "RequestExecutionLevel user",
+        "SetCompressor /SOLID lzma",
+        `Name ${q(app.appName)}`,
+        `OutFile ${nsisPath(outFile)}`,
+        `InstallDir "$LOCALAPPDATA\\Programs\\${inner(app.appId)}"`,
+        `InstallDirRegKey HKCU ${uninstallKey} "InstallLocation"`,
+        `BrandingText ${q(`${app.appName} ${app.versionName}`)}`,
+        `VIProductVersion ${q(version)}`,
+        `VIFileVersion ${q(version)}`,
+        `VIAddVersionKey "ProductName" ${q(app.appName)}`,
+        `VIAddVersionKey "CompanyName" ${q(app.appName)}`,
+        `VIAddVersionKey "LegalCopyright" ${q(app.appName)}`,
+        `VIAddVersionKey "FileDescription" ${q(`${app.appName} Setup`)}`,
+        `VIAddVersionKey "FileVersion" ${q(app.versionName)}`,
+        `VIAddVersionKey "ProductVersion" ${q(app.versionName)}`,
+        "",
+        "!include LogicLib.nsh",
+        "!include MUI2.nsh",
+        "!include x64.nsh",
+        "",
+        "!define MUI_FINISHPAGE_RUN",
+        "!define MUI_FINISHPAGE_RUN_FUNCTION LaunchApp",
+        "!insertmacro MUI_PAGE_WELCOME",
+        "!insertmacro MUI_PAGE_INSTFILES",
+        "!insertmacro MUI_PAGE_FINISH",
+        "!insertmacro MUI_UNPAGE_CONFIRM",
+        "!insertmacro MUI_UNPAGE_INSTFILES",
+        '!insertmacro MUI_LANGUAGE "English"',
+        "",
+        "Function .onInit",
+        "  ${IfNot} ${RunningX64}",
+        `    MessageBox MB_ICONSTOP ${q(`${app.appName} requires 64-bit Windows.`)} /SD IDOK`,
+        "    Abort",
+        "  ${EndIf}",
+        "FunctionEnd",
+        "",
+        "Function LaunchApp",
+        `  Exec ${command(exe)}`,
+        "FunctionEnd",
+        "",
+        'Section "Install"',
+        // A running copy keeps its executable locked.
+        ...ensureClosed(`${app.appName} is running.`),
+        // Only an uninstaller this app's registry entry points at is run.
+        `  ReadRegStr $1 HKCU ${uninstallKey} "InstallLocation"`,
+        `  \${If} $1 == $INSTDIR`,
+        `  \${AndIf} \${FileExists} ${instdir(exports.WINDOWS_UNINSTALLER)}`,
+        `    ExecWait ${command(exports.WINDOWS_UNINSTALLER, "/S _?=$INSTDIR")}`,
+        "  ${EndIf}",
+        ...installFiles,
+        '  SetOutPath "$INSTDIR"',
+        `  WriteUninstaller ${instdir(exports.WINDOWS_UNINSTALLER)}`,
+        `  CreateShortcut ${shortcut} ${instdir(exe)}`,
+        `  WriteRegStr HKCU ${uninstallKey} "DisplayName" ${q(app.appName)}`,
+        `  WriteRegStr HKCU ${uninstallKey} "DisplayVersion" ${q(app.versionName)}`,
+        `  WriteRegStr HKCU ${uninstallKey} "DisplayIcon" "$INSTDIR\\${inner(exe)},0"`,
+        `  WriteRegStr HKCU ${uninstallKey} "InstallLocation" "$INSTDIR"`,
+        `  WriteRegStr HKCU ${uninstallKey} "UninstallString" ${command(exports.WINDOWS_UNINSTALLER)}`,
+        `  WriteRegStr HKCU ${uninstallKey} "QuietUninstallString" ${command(exports.WINDOWS_UNINSTALLER, "/S")}`,
+        `  WriteRegDWORD HKCU ${uninstallKey} "NoModify" 1`,
+        `  WriteRegDWORD HKCU ${uninstallKey} "NoRepair" 1`,
+        `  WriteRegDWORD HKCU ${uninstallKey} "EstimatedSize" ${sizeKb}`,
+        "SectionEnd",
+        "",
+        'Section "Uninstall"',
+        ...ensureClosed(`${app.appName} is running.`),
+        `  Delete ${shortcut}`,
+        ...[...files].reverse().map((file) => `  Delete ${instdir(file)}`),
+        ...[...dirs].reverse().map((dir) => `  RMDir ${instdir(dir)}`),
+        `  Delete ${instdir(exports.WINDOWS_UNINSTALLER)}`,
+        '  RMDir "$INSTDIR"',
+        `  DeleteRegKey HKCU ${uninstallKey}`,
+        "SectionEnd",
+        "",
+    ].join("\n");
+}

package/dist/desktop/zip.js

@@ -0,0 +1,204 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listRegularFiles = listRegularFiles;
+exports.zipDirectory = zipDirectory;
+exports.extractZip = extractZip;
+exports.verifyPortableZip = verifyPortableZip;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const stream_1 = require("stream");
+const promises_1 = require("stream/promises");
+const unzipper_1 = __importDefault(require("unzipper"));
+const zlib_1 = __importDefault(require("zlib"));
+// Neither macOS's ditto nor a zip tool exists on every build host, so desktop
+// ZIPs that are not macOS bundles are written here. Plain ZIP only: no ZIP64,
+// so every size and offset must fit in 32 bits (Electron apps are far below).
+const MAX_ZIP32 = 0xffffffff;
+const MAX_ENTRIES = 0xffff;
+const ZIP_VERSION = 20;
+const UTF8_NAMES = 0x0800;
+const DEFLATE = 8;
+// "Version made by" host bytes: MS-DOS keeps extractor defaults, Unix carries file modes.
+const HOST_UNIX = 3;
+const S_IFREG = 0o100000;
+// Fixed 1980-01-01 00:00 timestamps keep the archive reproducible.
+const DOS_TIME = 0;
+const DOS_DATE = (1 << 5) | 1;
+/**
+ * Sorted POSIX paths of the regular files under `root`. Symlinks and special
+ * files are refused; a directory is implied by the files inside it.
+ */
+function listRegularFiles(root, relative = "") {
+    const files = [];
+    const entries = fs_1.default.readdirSync(path_1.default.join(root, relative), { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+        const entryRelative = relative ? `${relative}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            const nested = listRegularFiles(root, entryRelative);
+            if (nested.length === 0)
+                throw new Error(`Refusing to package empty directory ${entryRelative}`);
+            files.push(...nested);
+        }
+        else if (entry.isFile()) {
+            files.push(entryRelative);
+        }
+        else {
+            throw new Error(`Refusing to package ${entryRelative}: only regular files and directories are allowed`);
+        }
+    }
+    return files;
+}
+/**
+ * Deflate every file under `sourceDir` into a new `zipPath`, inside a
+ * top-level `rootName/` folder. With `unixModes`, each entry records its
+ * file's permission bits (never setuid, setgid, or sticky) so executables stay
+ * executable when extracted on Linux or macOS.
+ */
+async function zipDirectory(sourceDir, zipPath, rootName, options = {}) {
+    const files = listRegularFiles(sourceDir);
+    if (files.length > MAX_ENTRIES)
+        throw new Error(`Too many files for a ZIP archive: ${files.length}`);
+    const fd = fs_1.default.openSync(zipPath, "wx");
+    let offset = 0;
+    const append = (buffer) => {
+        fs_1.default.writeSync(fd, buffer, 0, buffer.length, offset);
+        offset += buffer.length;
+        if (offset > MAX_ZIP32)
+            throw new Error("Desktop package is too large for a ZIP archive without ZIP64");
+    };
+    try {
+        const entries = [];
+        for (const file of files) {
+            const source = path_1.default.join(sourceDir, ...file.split("/"));
+            const mode = options.unixModes ? fs_1.default.statSync(source).mode & 0o777 : null;
+            const entry = { name: Buffer.from(`${rootName}/${file}`, "utf8"), mode, offset, crc: 0, size: 0, compressedSize: 0 };
+            // Written again with the real CRC and sizes once the data is in.
+            append(localHeader(entry));
+            await (0, promises_1.pipeline)(fs_1.default.createReadStream(source), new stream_1.Transform({
+                transform(chunk, _encoding, done) {
+                    entry.crc = zlib_1.default.crc32(chunk, entry.crc);
+                    entry.size += chunk.length;
+                    done(null, chunk);
+                },
+            }), zlib_1.default.createDeflateRaw(), new stream_1.Writable({
+                write(chunk, _encoding, done) {
+                    try {
+                        append(chunk);
+                        entry.compressedSize += chunk.length;
+                        done();
+                    }
+                    catch (error) {
+                        done(error);
+                    }
+                },
+            }));
+            if (entry.size > MAX_ZIP32)
+                throw new Error(`${file} is too large for a ZIP archive without ZIP64`);
+            const header = localHeader(entry);
+            fs_1.default.writeSync(fd, header, 0, header.length, entry.offset);
+            entries.push(entry);
+        }
+        const centralOffset = offset;
+        for (const entry of entries)
+            append(centralHeader(entry));
+        append(endOfCentralDirectory(entries.length, offset - centralOffset, centralOffset));
+    }
+    finally {
+        fs_1.default.closeSync(fd);
+    }
+}
+function localHeader(entry) {
+    const header = Buffer.alloc(30 + entry.name.length);
+    header.writeUInt32LE(0x04034b50, 0);
+    header.writeUInt16LE(ZIP_VERSION, 4);
+    header.writeUInt16LE(UTF8_NAMES, 6);
+    header.writeUInt16LE(DEFLATE, 8);
+    header.writeUInt16LE(DOS_TIME, 10);
+    header.writeUInt16LE(DOS_DATE, 12);
+    header.writeUInt32LE(entry.crc, 14);
+    header.writeUInt32LE(entry.compressedSize, 18);
+    header.writeUInt32LE(entry.size, 22);
+    header.writeUInt16LE(entry.name.length, 26);
+    entry.name.copy(header, 30);
+    return header;
+}
+function centralHeader(entry) {
+    const header = Buffer.alloc(46 + entry.name.length);
+    header.writeUInt32LE(0x02014b50, 0);
+    // Made by MS-DOS (host 0): no Unix modes, so extractors use their defaults.
+    header.writeUInt16LE(entry.mode === null ? ZIP_VERSION : (HOST_UNIX << 8) | ZIP_VERSION, 4);
+    header.writeUInt16LE(ZIP_VERSION, 6);
+    header.writeUInt16LE(UTF8_NAMES, 8);
+    header.writeUInt16LE(DEFLATE, 10);
+    header.writeUInt16LE(DOS_TIME, 12);
+    header.writeUInt16LE(DOS_DATE, 14);
+    header.writeUInt32LE(entry.crc, 16);
+    header.writeUInt32LE(entry.compressedSize, 20);
+    header.writeUInt32LE(entry.size, 24);
+    header.writeUInt16LE(entry.name.length, 28);
+    if (entry.mode !== null)
+        header.writeUInt32LE(((S_IFREG | entry.mode) << 16) >>> 0, 38);
+    header.writeUInt32LE(entry.offset, 42);
+    entry.name.copy(header, 46);
+    return header;
+}
+function endOfCentralDirectory(count, size, offset) {
+    const record = Buffer.alloc(22);
+    record.writeUInt32LE(0x06054b50, 0);
+    record.writeUInt16LE(count, 8);
+    record.writeUInt16LE(count, 10);
+    record.writeUInt32LE(size, 12);
+    record.writeUInt32LE(offset, 16);
+    return record;
+}
+/**
+ * Extract a ZIP into the empty `targetDir`, checking every entry's CRC-32.
+ * Entries must be relative paths without `.`/`..` segments or backslashes.
+ * Entries made on Unix get their recorded permission bits; they must be
+ * regular files without setuid, setgid, or sticky bits.
+ */
+async function extractZip(zipPath, targetDir) {
+    const directory = await unzipper_1.default.Open.file(zipPath);
+    const names = [];
+    for (const file of directory.files) {
+        const segments = file.path.split("/");
+        if (file.path.startsWith("/") || file.path.includes("\\") || segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+            throw new Error(`Unsafe ZIP entry: ${JSON.stringify(file.path)}`);
+        }
+        if (file.type !== "File")
+            throw new Error(`Unexpected ZIP entry type ${file.type}: ${file.path}`);
+        const data = await file.buffer();
+        if (data.length !== file.uncompressedSize || zlib_1.default.crc32(data) !== file.crc32) {
+            throw new Error(`ZIP entry is corrupt: ${file.path}`);
+        }
+        const unixAttributes = file.versionMadeBy >> 8 === HOST_UNIX ? file.externalFileAttributes >>> 16 : null;
+        if (unixAttributes !== null && (unixAttributes & 0o177000) !== S_IFREG) {
+            throw new Error(`Unexpected ZIP entry mode ${unixAttributes.toString(8)}: ${file.path}`);
+        }
+        const target = path_1.default.join(targetDir, ...segments);
+        fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+        fs_1.default.writeFileSync(target, data, { flag: "wx" });
+        if (unixAttributes !== null)
+            fs_1.default.chmodSync(target, unixAttributes & 0o777);
+        names.push(file.path);
+    }
+    return names;
+}
+/**
+ * Extract a portable ZIP into the new `extractDir` and check it holds exactly
+ * `rootName/<file>` for each expected file. With `ordered`, the entries must
+ * also be in that order. Returns the extracted `rootName` folder.
+ */
+async function verifyPortableZip(zipPath, extractDir, rootName, expectedFiles, options = {}) {
+    fs_1.default.mkdirSync(extractDir);
+    const names = await extractZip(zipPath, extractDir);
+    const expected = (options.ordered ? expectedFiles : [...expectedFiles].sort()).map((file) => `${rootName}/${file}`);
+    const actual = options.ordered ? names : [...names].sort();
+    if (actual.length !== expected.length || actual.some((name, i) => name !== expected[i])) {
+        throw new Error(`Portable ZIP does not match the packaged ${rootName} folder`);
+    }
+    return path_1.default.join(extractDir, rootName);
+}