sparkbun 0.2.7 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sparkbun",
-	"version": "0.2.7",
+	"version": "0.2.8",
 	"description": "Build fast, lightweight, cross-platform desktop apps with TypeScript and Bun.",
 	"license": "MIT",
 	"author": "SparkBun Contributors",

package/src/bun/SparkBunConfig.ts

@@ -167,6 +167,12 @@ export interface SparkBunConfig {
 				 * Source directory (relative to project root or absolute). The
 				 * directory's own name becomes the archive's top-level folder,
 				 * so it extracts into the correct subdirectory.
+				 *
+				 * May also point at a PREBUILT `.tar` / `.tar.gz` / `.tar.zst`
+				 * file, which is embedded verbatim (no per-build tar+compress —
+				 * useful when a large payload is slow to compress and rarely
+				 * changes). Format is taken from the extension; `format`/
+				 * `compression` are ignored for prebuilt archives.
 				 */
 				path: string;
 				/**
@@ -177,9 +183,23 @@ export interface SparkBunConfig {
 				 */
 				format?: "zstd" | "gzip";
 				/**
-				 * Compression level. zstd: 1–22 (22 = maximum, large window).
-				 * gzip: 1–9. Higher is smaller but slower to compress.
-				 * @default 19 for zstd, 9 for gzip
+				 * Compression tier.
+				 * - "basic" — Bun's built-in CompressionStream (zstd ≈ level 3,
+				 *   gzip ≈ level 6). Fast, streaming, no level control. (default)
+				 * - number — explicit level via node:zlib streaming transforms.
+				 *   zstd: 1–22 (22 = maximum; large window, smallest output).
+				 *   gzip: 1–9. Higher is smaller but slower to compress.
+				 * - "none" — no compression; a plain `.tar`. For payloads that
+				 *   are already compressed (video, media) where recompression
+				 *   wastes build time. The manifest records format "none" and
+				 *   the app's extractor must skip its decompression step.
+				 * @default "basic"
+				 */
+				compression?: "none" | "basic" | number;
+				/**
+				 * Legacy alias for a numeric `compression` tier. Ignored when
+				 * `compression` is set.
+				 * @deprecated Use `compression` instead.
 				 */
 				level?: number;
 			}>;

package/src/cli/archive-stream.ts

@@ -0,0 +1,292 @@
+/**
+ * Streaming, pure-Bun tar + compression for installer payload archives.
+ *
+ * The tar layer is hand-rolled ustar, emitted entry-by-entry with file bodies
+ * read in 8 MiB slices, so build memory stays bounded regardless of payload
+ * size — and there is no system `tar` dependency. (Shelling out to tar was a
+ * reliability problem: macOS bsdtar emits xattr pax headers that GNU tar
+ * rejects, and GNU tar parses "C:\..." as a remote-host spec.) The output is
+ * plain ustar — long paths via the name/prefix split, file modes preserved
+ * (executables stay executable), symlinks as typeflag '2' — readable by every
+ * tar implementation and by apps' streaming extractors.
+ *
+ * Compression tiers, chosen per archive (config `compression` field or
+ * `--compression` flag):
+ *   - "basic"  — Bun's built-in CompressionStream (zstd default ≈ level 3;
+ *                gzip default ≈ level 6). Fast, streaming, no level control.
+ *                The default tier.
+ *   - <number> — explicit level via node:zlib streaming transforms (zstd 1–22,
+ *                gzip 1–9). zstd 22 uses a large window; its ratio depends on
+ *                it. Slower to build, smallest output.
+ *   - "none"   — no compression; a plain `.tar`. For payloads that are already
+ *                compressed (video, archives) where recompression wastes time.
+ */
+
+import { readdirSync, statSync, lstatSync, readlinkSync, createWriteStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import zlib from "node:zlib";
+import { join, basename } from "node:path";
+
+export type ArchiveFormat = "zstd" | "gzip";
+export type ArchiveCompression = "none" | "basic" | number;
+
+const READ_CHUNK = 8 * 1024 * 1024; // file read slice size (bounds memory)
+
+/** File extension for an archive of the given format + compression. */
+export function archiveExtension(format: ArchiveFormat, compression: ArchiveCompression): string {
+	if (compression === "none") return "tar";
+	return format === "gzip" ? "tar.gz" : "tar.zst";
+}
+
+/**
+ * The effective numeric level recorded in the manifest: 0 for "none", the
+ * library default for "basic" (zstd 3 / gzip 6 — approximate; CompressionStream
+ * exposes no level), or the explicit number.
+ */
+export function effectiveLevel(format: ArchiveFormat, compression: ArchiveCompression): number {
+	if (compression === "none") return 0;
+	if (compression === "basic") return format === "gzip" ? 6 : 3;
+	return compression;
+}
+
+/** Human label for build logs, e.g. "zstd level 22", "zstd (basic)", "uncompressed". */
+export function compressionLabel(format: ArchiveFormat, compression: ArchiveCompression): string {
+	if (compression === "none") return "uncompressed";
+	if (compression === "basic") return `${format} (basic)`;
+	return `${format} level ${compression}`;
+}
+
+/** A POSIX ustar 512-byte header. Splits long paths across name/prefix. */
+function ustarHeader(
+	path: string,
+	size: number,
+	type: "0" | "2" | "5",
+	mode: number,
+	linkname = "",
+): Uint8Array {
+	const bl = (s: string) => Buffer.byteLength(s);
+	let name = path;
+	let prefix = "";
+	if (bl(name) > 100) {
+		// Split at a "/" so the suffix fits the 100-byte name field and the
+		// prefix fits the 155-byte prefix field (extractors rejoin them).
+		let split = -1;
+		for (let i = 0; i < path.length; i++) {
+			if (path[i] !== "/") continue;
+			if (bl(path.slice(0, i)) <= 155 && bl(path.slice(i + 1)) <= 100) {
+				split = i;
+				break;
+			}
+		}
+		if (split < 0) throw new Error(`Path too long for ustar: ${path}`);
+		prefix = path.slice(0, split);
+		name = path.slice(split + 1);
+	}
+	if (bl(linkname) > 100) throw new Error(`Symlink target too long for ustar: ${linkname}`);
+	const h = Buffer.alloc(512);
+	h.write(name, 0);
+	const putOct = (off: number, len: number, v: number) =>
+		h.write(v.toString(8).padStart(len - 1, "0") + "\0", off);
+	putOct(100, 8, mode & 0o7777);
+	putOct(108, 8, 0); // uid
+	putOct(116, 8, 0); // gid
+	putOct(124, 12, size);
+	putOct(136, 12, 0); // mtime
+	h.write(type, 156);
+	h.write(linkname, 157);
+	h.write("ustar\0", 257);
+	h.write("00", 263);
+	h.write(prefix, 345);
+	h.fill(0x20, 148, 156); // checksum field = spaces while summing
+	let sum = 0;
+	for (let i = 0; i < 512; i++) sum += h[i]!;
+	h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148);
+	return new Uint8Array(h.buffer, h.byteOffset, h.length);
+}
+
+type WalkEntry = {
+	abs: string;
+	rel: string;
+	kind: "dir" | "file" | "symlink";
+	size: number;
+	mode: number;
+};
+
+/** Depth-first walk; directories before their contents; "/" separators. */
+function* walk(absDir: string, rel: string): Generator<WalkEntry> {
+	const entries = readdirSync(absDir, { withFileTypes: true }).sort((x, y) =>
+		x.name.localeCompare(y.name),
+	);
+	for (const e of entries) {
+		if (e.name === ".DS_Store") continue;
+		const abs = join(absDir, e.name);
+		const r = `${rel}/${e.name}`;
+		if (e.isSymbolicLink()) {
+			yield { abs, rel: r, kind: "symlink", size: 0, mode: 0o777 };
+		} else if (e.isDirectory()) {
+			yield { abs, rel: r, kind: "dir", size: 0, mode: lstatSync(abs).mode };
+			yield* walk(abs, r);
+		} else if (e.isFile()) {
+			const st = statSync(abs);
+			yield { abs, rel: r, kind: "file", size: st.size, mode: st.mode };
+		}
+		// Sockets/FIFOs/devices are skipped.
+	}
+}
+
+/**
+ * The tar bytes for the tree rooted at `srcDir`, as a lazy async sequence.
+ * The directory's own name becomes the archive root.
+ */
+export async function* tarBytes(srcDir: string): AsyncGenerator<Uint8Array> {
+	const rootName = basename(srcDir);
+	yield ustarHeader(`${rootName}/`, 0, "5", statSync(srcDir).mode);
+	for (const e of walk(srcDir, rootName)) {
+		if (e.kind === "dir") {
+			yield ustarHeader(`${e.rel}/`, 0, "5", e.mode);
+			continue;
+		}
+		if (e.kind === "symlink") {
+			yield ustarHeader(e.rel, 0, "2", e.mode, readlinkSync(e.abs));
+			continue;
+		}
+		yield ustarHeader(e.rel, e.size, "0", e.mode);
+		const f = Bun.file(e.abs);
+		for (let off = 0; off < e.size; off += READ_CHUNK) {
+			yield new Uint8Array(await f.slice(off, Math.min(off + READ_CHUNK, e.size)).arrayBuffer());
+		}
+		const pad = (512 - (e.size % 512)) % 512;
+		if (pad) yield new Uint8Array(pad);
+	}
+	yield new Uint8Array(1024); // end-of-archive: two zero blocks
+}
+
+/**
+ * Scan a prebuilt tar archive (optionally zstd/gzip compressed) and total its
+ * file payload — the uncompressedBytes/fileCount progress denominators the
+ * manifest needs. Streaming: headers are parsed and bodies skipped, so memory
+ * stays bounded.
+ */
+export async function scanTarArchive(
+	path: string,
+	format: ArchiveFormat | "none",
+): Promise<{ uncompressedBytes: number; fileCount: number }> {
+	let stream = Bun.file(path).stream() as unknown as ReadableStream<Uint8Array>;
+	if (format !== "none") {
+		const ds = new DecompressionStream(
+			(format === "gzip" ? "gzip" : "zstd") as CompressionFormat,
+		) as unknown as ReadableWritablePair<Uint8Array, Uint8Array>;
+		stream = stream.pipeThrough(ds);
+	}
+	const reader = stream.getReader();
+	const td = new TextDecoder();
+	let buf: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
+	let uncompressedBytes = 0;
+	let fileCount = 0;
+	let skip = 0; // bytes of body+padding left to discard
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (buf.length === 0) buf = value;
+		else {
+			const merged = new Uint8Array(buf.length + value.length);
+			merged.set(buf, 0);
+			merged.set(value, buf.length);
+			buf = merged;
+		}
+		while (true) {
+			if (skip > 0) {
+				const n = Math.min(skip, buf.length);
+				buf = buf.subarray(n);
+				skip -= n;
+				if (skip > 0) break;
+			}
+			if (buf.length < 512) break;
+			const h = buf.subarray(0, 512);
+			buf = buf.subarray(512);
+			let allZero = true;
+			for (let i = 0; i < 512; i++) {
+				if (h[i] !== 0) { allZero = false; break; }
+			}
+			if (allZero) continue; // end-of-archive marker block
+			const size =
+				parseInt(td.decode(h.subarray(124, 136)).replace(/\0.*$/, "").trim() || "0", 8) || 0;
+			const typeflag = String.fromCharCode(h[156] || 0);
+			// Regular files count toward the payload; metadata entries (long-name
+			// 'L'/'K', pax 'x'/'g') and dirs/links don't, but their bodies are
+			// still skipped.
+			if (typeflag === "0" || typeflag === "\0") {
+				uncompressedBytes += size;
+				fileCount++;
+			}
+			skip = size + ((512 - (size % 512)) % 512);
+		}
+	}
+	return { uncompressedBytes, fileCount };
+}
+
+/** Wrap an async generator as a web ReadableStream (for CompressionStream). */
+function toReadable(gen: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array> {
+	return new ReadableStream<Uint8Array>({
+		async pull(c) {
+			const { done, value } = await gen.next();
+			if (done) c.close();
+			else c.enqueue(value);
+		},
+	});
+}
+
+/**
+ * Tar `srcDir` and write it to `destPath`, compressed per the tier. Streaming
+ * end to end: nothing close to the payload size is ever in memory.
+ */
+export async function writeTarArchive(
+	srcDir: string,
+	destPath: string,
+	format: ArchiveFormat,
+	compression: ArchiveCompression,
+): Promise<void> {
+	const tar = tarBytes(srcDir);
+
+	if (compression === "none") {
+		await pipeline(tar, createWriteStream(destPath));
+		return;
+	}
+
+	if (compression === "basic") {
+		// Bun's built-in CompressionStream. "zstd" is valid in Bun but missing
+		// from the lib.dom CompressionFormat union (and the stream generics
+		// predate Uint8Array<ArrayBuffer>), hence the casts.
+		const cs = new CompressionStream(
+			(format === "gzip" ? "gzip" : "zstd") as CompressionFormat,
+		) as unknown as ReadableWritablePair<Uint8Array, Uint8Array>;
+		const compressed = toReadable(tar).pipeThrough(cs);
+		const sink = Bun.file(destPath).writer();
+		const reader = compressed.getReader();
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				sink.write(value);
+			}
+		} finally {
+			await sink.end();
+		}
+		return;
+	}
+
+	// Explicit level via node:zlib streaming transforms. The zstd APIs exist in
+	// Bun's node:zlib but not yet in the bundled @types, hence the cast.
+	const z = zlib as unknown as {
+		createGzip(opts: { level: number }): NodeJS.ReadWriteStream;
+		createZstdCompress(opts: { params: Record<number, number> }): NodeJS.ReadWriteStream;
+		constants: { ZSTD_c_compressionLevel: number };
+	};
+	const transform =
+		format === "gzip"
+			? z.createGzip({ level: compression })
+			: z.createZstdCompress({
+					params: { [z.constants.ZSTD_c_compressionLevel]: compression },
+				});
+	await pipeline(tar, transform, createWriteStream(destPath));
+}

package/src/cli/index.ts

@@ -33,6 +33,15 @@ import {
 	getMacOSBundleDisplayName,
 } from "../shared/naming";
 import { getTemplate, getTemplateNames } from "./templates/embedded";
+import {
+	writeTarArchive,
+	scanTarArchive,
+	archiveExtension,
+	effectiveLevel,
+	compressionLabel,
+	type ArchiveFormat,
+	type ArchiveCompression,
+} from "./archive-stream";
 // MacOS named pipes hang at around 4KB
 // @ts-expect-error - reserved for future use
 const _MAX_CHUNK_SIZE = 1024 * 2;
@@ -64,6 +73,38 @@ function createTar(tarPath: string, cwd: string, entries: string[]) {
 	);
 }
 
+// Compile an executable via Bun.build({ compile }) with a retry around a known
+// transient failure: on Windows the compile stamps PE version metadata through
+// resource updates (EndUpdateResourceW), and antivirus/indexer scans of the
+// freshly written exe intermittently fail that commit with "Failed to set
+// Windows metadata: FailedToCommit". Clear any stale output first (a scanned
+// leftover exe can hold locks), then retry a few times before giving up.
+async function buildCompiledExeWithRetry(
+	options: Parameters<typeof Bun.build>[0],
+	outputPath: string,
+): Promise<Awaited<ReturnType<typeof Bun.build>>> {
+	try { rmSync(outputPath, { force: true }); } catch {}
+	for (let attempt = 1; ; attempt++) {
+		try {
+			return await Bun.build(options);
+		} catch (err: any) {
+			// Bun surfaces compile errors as BuildMessage-like objects whose
+			// .message can be empty — the text only shows through Bun's inspect
+			// formatting, so match against every representation we can get.
+			let msg = "";
+			try {
+				msg = `${err?.message ?? ""} ${String(err)} ${Bun.inspect(err)}`;
+			} catch {}
+			if (attempt < 4 && /FailedToCommit|Failed to set Windows metadata/i.test(msg)) {
+				console.log(`  PE metadata commit failed (attempt ${attempt}/4) — retrying in 2s...`);
+				await Bun.sleep(2000);
+				continue;
+			}
+			throw err;
+		}
+	}
+}
+
 // Recursively measure a directory's total file bytes and file count.
 // Used to embed accurate progress denominators in the installer archive manifest.
 function measureDir(dir: string): { bytes: number; fileCount: number } {
@@ -84,28 +125,6 @@ function measureDir(dir: string): { bytes: number; fileCount: number } {
 	return { bytes, fileCount };
 }
 
-// Stream-compress a file with zstd or gzip at a specific level, using node:zlib
-// transforms so build memory stays bounded regardless of input size. Web
-// CompressionStream("zstd") is intentionally not used — it has no level control,
-// and the high compression ratio depends on level 22's large window.
-async function streamCompressFile(
-	srcPath: string,
-	destPath: string,
-	format: "zstd" | "gzip",
-	level: number,
-): Promise<void> {
-	const zlib = require("node:zlib");
-	const { createReadStream, createWriteStream } = require("node:fs");
-	const { pipeline } = require("node:stream/promises");
-	const transform =
-		format === "gzip"
-			? zlib.createGzip({ level })
-			: zlib.createZstdCompress({
-					params: { [zlib.constants.ZSTD_c_compressionLevel]: level },
-				});
-	await pipeline(createReadStream(srcPath), transform, createWriteStream(destPath));
-}
-
 // this when run as an npm script this will be where the folder where package.json is.
 const projectRoot = process.cwd();
 
@@ -3313,24 +3332,53 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 
 		// Compression defaults for archives supplied via --archive flags.
 		// (Archives declared in sparkbun.config.ts carry their own per-archive
-		// format/level, so each project can mix tight and fast compression.)
-		const globalFormat = ((getFlag("--format=") as "zstd" | "gzip") || "zstd");
+		// format/compression, so each project can mix tight and fast compression.)
+		const globalFormat = ((getFlag("--format=") as ArchiveFormat) || "zstd");
 		const globalLevelFlag = getFlag("--level=");
-		const defaultLevelFor = (fmt: "zstd" | "gzip") => (fmt === "gzip" ? 9 : 19);
+		const globalCompressionFlag = getFlag("--compression=");
+
+		// Parse a compression tier: "none" | "basic" | numeric level. Validates
+		// the level range for the format (zstd 1–22, gzip 1–9).
+		const parseCompression = (
+			raw: string | number,
+			fmt: ArchiveFormat,
+			source: string,
+		): ArchiveCompression => {
+			if (raw === "none" || raw === "basic") return raw;
+			const level = Number(raw);
+			const max = fmt === "gzip" ? 9 : 22;
+			if (!Number.isInteger(level) || level < 1 || level > max) {
+				console.error(
+					`Invalid compression for ${source}: "${raw}". Expected "none", "basic", or a ${fmt} level 1-${max}.`,
+				);
+				process.exit(1);
+			}
+			return level;
+		};
+
+		// Compression tier for archives that don't specify their own: the
+		// --compression / legacy --level flags, else "basic" (Bun's built-in
+		// CompressionStream — fast, streaming, no level control).
+		const defaultCompressionFor = (fmt: ArchiveFormat, source: string): ArchiveCompression =>
+			globalCompressionFlag
+				? parseCompression(globalCompressionFlag, fmt, source)
+				: globalLevelFlag
+					? parseCompression(globalLevelFlag, fmt, source)
+					: "basic";
 
 		type ArchiveSpec = {
 			name: string;
 			path: string;
-			format: "zstd" | "gzip";
-			level: number;
+			format: ArchiveFormat;
+			compression: ArchiveCompression;
 		};
 		const archives: ArchiveSpec[] = [];
 
 		const addArchive = (
 			name: string,
 			rawPath: string,
-			fmt: "zstd" | "gzip",
-			level: number,
+			fmt: ArchiveFormat,
+			compression: ArchiveCompression,
 		) => {
 			if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
 				console.error(`Invalid archive name: "${name}". Must be a valid identifier ([a-zA-Z_][a-zA-Z0-9_]*).`);
@@ -3345,22 +3393,35 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 				console.error(`Archive path does not exist: ${resolvedPath}`);
 				process.exit(1);
 			}
-			archives.push({ name, path: resolvedPath, format: fmt, level });
+			archives.push({ name, path: resolvedPath, format: fmt, compression });
 		};
 
-		// Archives declared in sparkbun.config.ts (build.installer.archives)
+		// Archives declared in sparkbun.config.ts (build.installer.archives).
+		// `compression` ("none" | "basic" | level) is the preferred knob; the
+		// legacy `level` field still works as a numeric tier.
 		const configArchives = (config.build as any)?.installer?.archives as
-			| Array<{ name: string; path: string; format?: "zstd" | "gzip"; level?: number }>
+			| Array<{
+					name: string;
+					path: string;
+					format?: ArchiveFormat;
+					compression?: "none" | "basic" | number;
+					level?: number;
+			  }>
 			| undefined;
 		if (configArchives) {
 			for (const a of configArchives) {
 				const fmt = a.format || globalFormat;
-				const level = a.level ?? (globalLevelFlag ? Number(globalLevelFlag) : defaultLevelFor(fmt));
-				addArchive(a.name, a.path, fmt, level);
+				const compression =
+					a.compression !== undefined
+						? parseCompression(a.compression, fmt, `archive "${a.name}"`)
+						: a.level !== undefined
+							? parseCompression(a.level, fmt, `archive "${a.name}"`)
+							: defaultCompressionFor(fmt, `archive "${a.name}"`);
+				addArchive(a.name, a.path, fmt, compression);
 			}
 		}
 
-		// Archives passed via --archive name=path (level/format from global flags)
+		// Archives passed via --archive name=path (format/compression from global flags)
 		for (let i = 0; i < process.argv.length; i++) {
 			if (process.argv[i] === "--archive" && process.argv[i + 1]) {
 				const arg = process.argv[i + 1]!;
@@ -3369,8 +3430,13 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 					console.error(`Invalid --archive format: "${arg}". Expected: name=path`);
 					process.exit(1);
 				}
-				const level = globalLevelFlag ? Number(globalLevelFlag) : defaultLevelFor(globalFormat);
-				addArchive(arg.substring(0, eqIdx), arg.substring(eqIdx + 1), globalFormat, level);
+				const name = arg.substring(0, eqIdx);
+				addArchive(
+					name,
+					arg.substring(eqIdx + 1),
+					globalFormat,
+					defaultCompressionFor(globalFormat, `--archive ${name}`),
+				);
 			}
 		}
 
@@ -3438,7 +3504,13 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 
 		type ArchiveInfo = {
 			file: string;
-			format: "zstd" | "gzip";
+			// "none" = plain .tar, no decompression step at extract time.
+			format: "zstd" | "gzip" | "none";
+			// The tier as configured ("prebuilt" = the config pointed at an
+			// already-built archive file, embedded verbatim); `level` keeps the
+			// effective numeric level for older consumers (0 = uncompressed or
+			// unknown; "basic" ≈ zstd 3 / gzip 6).
+			compression: "none" | "basic" | number | "prebuilt";
 			level: number;
 			uncompressedBytes: number;
 			fileCount: number;
@@ -3447,51 +3519,74 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 		const archiveManifest: Record<string, ArchiveInfo> = {};
 
 		if (archives.length > 0) {
-			console.log("Creating archives (tar + streaming compression)...");
+			console.log("Creating archives (streaming tar + compression)...");
 
 			for (const spec of archives) {
-				const ext = spec.format === "gzip" ? "tar.gz" : "tar.zst";
+				// A FILE path is a prebuilt archive: embed it verbatim instead of
+				// tarring + compressing a directory. Lets projects with large,
+				// slow-to-compress payloads (e.g. zstd-22 game data) build them
+				// once and skip the per-build recompression entirely. Format comes
+				// from the extension; the manifest's progress denominators come
+				// from a streaming scan of the archive.
+				if (statSync(spec.path).isFile()) {
+					const m = spec.path.match(/\.tar(\.zst|\.gz)?$/i);
+					if (!m) {
+						console.error(
+							`Archive "${spec.name}": file paths must point at a prebuilt .tar/.tar.gz/.tar.zst (got ${spec.path})`,
+						);
+						process.exit(1);
+					}
+					const fmt: "zstd" | "gzip" | "none" =
+						m[1]?.toLowerCase() === ".zst" ? "zstd" : m[1]?.toLowerCase() === ".gz" ? "gzip" : "none";
+					const preExt = fmt === "none" ? "tar" : fmt === "gzip" ? "tar.gz" : "tar.zst";
+					const preFileName = `archive-${spec.name}.${preExt}`;
+					console.log(`  Embedding prebuilt ${spec.name}: ${spec.path}`);
+					cpSync(spec.path, join(stagingDir, preFileName));
+					const { uncompressedBytes, fileCount } = await scanTarArchive(spec.path, fmt);
+					const compressedBytes = statSync(spec.path).size;
+					console.log(
+						`  ${spec.name}: ${(uncompressedBytes / 1024 / 1024).toFixed(0)} MB -> ` +
+							`${(compressedBytes / 1024 / 1024).toFixed(0)} MB (prebuilt ${preExt}, ${fileCount} files)`,
+					);
+					archiveManifest[spec.name] = {
+						file: preFileName,
+						format: fmt,
+						compression: "prebuilt",
+						level: 0,
+						uncompressedBytes,
+						fileCount,
+						compressedBytes,
+					};
+					continue;
+				}
+
+				const ext = archiveExtension(spec.format, spec.compression);
 				const archiveFileName = `archive-${spec.name}.${ext}`;
 				const archiveDestPath = join(stagingDir, archiveFileName);
-				const tarTmpPath = join(stagingDir, `archive-${spec.name}.tar`);
 
 				console.log(`  Archiving ${spec.name}: ${spec.path}`);
 
-				// Build the uncompressed tar with the system `tar`. It streams to disk
-				// (bounded build memory) and preserves empty directories as real
-				// entries. The source folder name is kept as the archive root (e.g.
-				// "Dune 2000/...") via `tar -C <parent> <basename>`, so it extracts
-				// into the correct subdirectory.
-				//
-				// The on-disk format may be GNU (Windows/Linux — long paths via
-				// "././@LongLink") or pax (macOS bsdtar — long paths via extended
-				// headers). The installer's streaming extractor understands both, plus
-				// plain ustar, so the archive is portable regardless of build host.
-				//
-				// (Bun.Archive is intentionally not used here: its lazy Bun.file()
-				// inputs write empty file bodies, and eager byte inputs would require
-				// loading the entire payload into memory.)
-				const parent = dirname(spec.path);
-				const baseName = basename(spec.path);
-				createTar(tarTmpPath, parent, [baseName]);
+				// Hand-rolled streaming tar piped straight into the compressor (see
+				// archive-stream.ts): plain ustar with the source folder name kept
+				// as the archive root (e.g. "Dune 2000/..."), file modes preserved,
+				// bounded build memory, and no system tar dependency — the on-disk
+				// format is identical regardless of build host.
+				await writeTarArchive(spec.path, archiveDestPath, spec.format, spec.compression);
 
 				// Measure uncompressed bytes + file count for progress denominators.
 				const { bytes: uncompressedBytes, fileCount } = measureDir(spec.path);
 
-				// Stream-compress the tar at the requested level (bounded build memory).
-				await streamCompressFile(tarTmpPath, archiveDestPath, spec.format, spec.level);
-				unlinkSync(tarTmpPath);
-
 				const compressedBytes = statSync(archiveDestPath).size;
 				console.log(
 					`  ${spec.name}: ${(uncompressedBytes / 1024 / 1024).toFixed(0)} MB -> ` +
 						`${(compressedBytes / 1024 / 1024).toFixed(0)} MB ` +
-						`(${spec.format} level ${spec.level}, ${fileCount} files)`,
+						`(${compressionLabel(spec.format, spec.compression)}, ${fileCount} files)`,
 				);
 				archiveManifest[spec.name] = {
 					file: archiveFileName,
-					format: spec.format,
-					level: spec.level,
+					format: spec.compression === "none" ? "none" : spec.format,
+					compression: spec.compression,
+					level: effectiveLevel(spec.format, spec.compression),
 					uncompressedBytes,
 					fileCount,
 					compressedBytes,
@@ -3688,6 +3783,8 @@ ${archiveExports.join("\n")}
 
 		console.log("Compiling installer executable...");
 
+		// (Compiled via buildCompiledExeWithRetry below — PE metadata commit
+		// failures from AV scans are transient and retried.)
 		const installerCompileOptions: any = {
 			target: `bun-${targetOSName}-${targetARCH}`,
 			outfile: outputPath,
@@ -3727,10 +3824,13 @@ ${archiveExports.join("\n")}
 			};
 		}
 
-		const installerBuild = await Bun.build({
-			entrypoints: [join(stagingDir, "installer.ts")],
-			compile: installerCompileOptions,
-		});
+		const installerBuild = await buildCompiledExeWithRetry(
+			{
+				entrypoints: [join(stagingDir, "installer.ts")],
+				compile: installerCompileOptions,
+			},
+			outputPath,
+		);
 		if (!installerBuild.success) {
 			console.error("Installer compilation failed:", installerBuild.logs);
 			throw new Error("Installer compilation failed");
@@ -4437,10 +4537,13 @@ ${archiveExports.join("\n")}
 		}
 
 		console.log("Compiling installer...");
-		const installerBuild = await Bun.build({
-			entrypoints: [join(stagingDir, "installer.ts")],
-			compile: installerCompileOptions,
-		});
+		const installerBuild = await buildCompiledExeWithRetry(
+			{
+				entrypoints: [join(stagingDir, "installer.ts")],
+				compile: installerCompileOptions,
+			},
+			outputPath,
+		);
 		if (!installerBuild.success) {
 			console.error("Installer compilation failed:", installerBuild.logs);
 			throw new Error("Installer compilation failed");