sparkbun 0.2.2 → 0.2.4

package/package.json

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

package/src/bun/SparkBunConfig.ts

@@ -141,6 +141,50 @@ export interface SparkBunConfig {
 		copy?: {
 			[sourcePath: string]: string;
 		};
+
+		/**
+		 * Configuration for the `sparkbun installer` command, which builds a
+		 * single-file graphical installer with embedded payload archives.
+		 *
+		 * Each archive is tarred (preserving its source folder name as the
+		 * archive root) and compressed independently. The compiled installer
+		 * app reads the embedded `archives.json` manifest and extracts the
+		 * payloads itself — the framework does not auto-extract, giving the
+		 * installer full control over the process (streaming, progress,
+		 * placement, ordering, conditional components, etc.).
+		 *
+		 * Archives can also be supplied on the CLI via repeated
+		 * `--archive name=path` flags; config entries and flags are combined.
+		 */
+		installer?: {
+			archives?: Array<{
+				/**
+				 * Logical identifier for the archive. Referenced by the app and
+				 * used as the manifest key. Must match /^[a-zA-Z_][a-zA-Z0-9_]*$/.
+				 */
+				name: string;
+				/**
+				 * 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.
+				 */
+				path: string;
+				/**
+				 * Compression algorithm.
+				 * - "zstd" — best ratio at high levels, streaming decode (default)
+				 * - "gzip" — widest compatibility, faster, larger output
+				 * @default "zstd"
+				 */
+				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
+				 */
+				level?: number;
+			}>;
+		};
+
 		/**
 		 * Output folder for built application
 		 * @default "build"

package/src/cli/index.ts

@@ -56,7 +56,47 @@ function createTar(tarPath: string, cwd: string, entries: string[]) {
 	);
 }
 
-// Create a tar.gz file using system tar command
+// 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 } {
+	let bytes = 0;
+	let fileCount = 0;
+	const stack = [dir];
+	while (stack.length) {
+		const d = stack.pop()!;
+		for (const entry of readdirSync(d, { withFileTypes: true })) {
+			const full = join(d, entry.name);
+			if (entry.isDirectory()) stack.push(full);
+			else if (entry.isFile()) {
+				bytes += statSync(full).size;
+				fileCount++;
+			}
+		}
+	}
+	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();
@@ -3207,10 +3247,15 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 	 * with admin elevation. On second launch (from temp, with DLLs present) it
 	 * loads SparkBunCore and runs the webview-based installer UI.
 	 *
-	 * Payload archives are compressed with LZMA via NSIS and embedded directly
-	 * in the binary. They stay embedded until the user triggers installation,
-	 * at which point the app code writes them to disk and runs them as silent
-	 * self-extractors.
+	 * Payload archives are tarred (preserving each source's folder name as the
+	 * archive root) and compressed with zstd (default, levels 1–22) or gzip,
+	 * then embedded directly in the binary. They stay embedded until the user
+	 * triggers installation; the app code reads the embedded `archives.json`
+	 * manifest and extracts them itself — typically by streaming the embedded
+	 * blob through DecompressionStream("zstd") into a tar reader, which bounds
+	 * memory to the decompression window regardless of archive size. The
+	 * framework never auto-extracts payloads, so the installer has full control
+	 * over progress, placement, ordering, and conditional components.
 	 *
 	 * This is a separate pipeline from `runBuild` — it does not produce update
 	 * artifacts, delta patches, DMGs, or .deb packages.
@@ -3221,7 +3266,59 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 	) {
 		// --- Parse installer-specific CLI flags ---
 
-		const archives: { name: string; path: string }[] = [];
+		const getFlag = (prefix: string): string | undefined =>
+			process.argv.find((arg) => arg.startsWith(prefix))?.split("=").slice(1).join("=");
+
+		// 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");
+		const globalLevelFlag = getFlag("--level=");
+		const defaultLevelFor = (fmt: "zstd" | "gzip") => (fmt === "gzip" ? 9 : 19);
+
+		type ArchiveSpec = {
+			name: string;
+			path: string;
+			format: "zstd" | "gzip";
+			level: number;
+		};
+		const archives: ArchiveSpec[] = [];
+
+		const addArchive = (
+			name: string,
+			rawPath: string,
+			fmt: "zstd" | "gzip",
+			level: number,
+		) => {
+			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_]*).`);
+				process.exit(1);
+			}
+			if (archives.some((a) => a.name === name)) {
+				console.error(`Duplicate archive name: "${name}".`);
+				process.exit(1);
+			}
+			const resolvedPath = path.resolve(projectRoot, rawPath);
+			if (!existsSync(resolvedPath)) {
+				console.error(`Archive path does not exist: ${resolvedPath}`);
+				process.exit(1);
+			}
+			archives.push({ name, path: resolvedPath, format: fmt, level });
+		};
+
+		// Archives declared in sparkbun.config.ts (build.installer.archives)
+		const configArchives = (config.build as any)?.installer?.archives as
+			| Array<{ name: string; path: string; format?: "zstd" | "gzip"; 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);
+			}
+		}
+
+		// Archives passed via --archive name=path (level/format 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]!;
@@ -3230,30 +3327,18 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 					console.error(`Invalid --archive format: "${arg}". Expected: name=path`);
 					process.exit(1);
 				}
-				const name = arg.substring(0, eqIdx);
-				const archivePath = arg.substring(eqIdx + 1);
-				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_]*).`);
-					process.exit(1);
-				}
-				if (archives.some((a) => a.name === name)) {
-					console.error(`Duplicate archive name: "${name}".`);
-					process.exit(1);
-				}
-				const resolvedPath = path.resolve(projectRoot, archivePath);
-				if (!existsSync(resolvedPath)) {
-					console.error(`Archive path does not exist: ${resolvedPath}`);
-					process.exit(1);
-				}
-				archives.push({ name, path: resolvedPath });
+				const level = globalLevelFlag ? Number(globalLevelFlag) : defaultLevelFor(globalFormat);
+				addArchive(arg.substring(0, eqIdx), arg.substring(eqIdx + 1), globalFormat, level);
 			}
 		}
 
-		const getFlag = (prefix: string): string | undefined =>
-			process.argv.find((arg) => arg.startsWith(prefix))?.split("=").slice(1).join("=");
-
 		const outPath = getFlag("--out=");
-		const iconPath = getFlag("--icon=");
+		// Fall back to the platform icon from sparkbun.config.ts (build.win.icon)
+		// so the installer is branded without needing an explicit --icon flag.
+		const iconPath =
+			getFlag("--icon=") ||
+			(config.build as any)?.win?.icon ||
+			undefined;
 		const installerName = getFlag("--name=") || config.app.name;
 		const installerVersion = getFlag("--version=") || config.app.version;
 		const installerPublisher = getFlag("--publisher=") || (config.app as any).publisher || "";
@@ -3311,46 +3396,66 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 		if (existsSync(stagingDir)) rmSync(stagingDir, { recursive: true, force: true });
 		mkdirSync(stagingDir, { recursive: true });
 
-		const archiveManifest: Record<string, string> = {};
+		type ArchiveInfo = {
+			file: string;
+			format: "zstd" | "gzip";
+			level: number;
+			uncompressedBytes: number;
+			fileCount: number;
+			compressedBytes: number;
+		};
+		const archiveManifest: Record<string, ArchiveInfo> = {};
 
 		if (archives.length > 0) {
-			console.log("Creating archives (LZMA solid via NSIS)...");
-
-			const nsisDir = join(SPARKBUN_DEP_PATH, `dist-${targetOS}-${targetARCH}`, "nsis");
-			const makensisPath = join(nsisDir, "Bin", "makensis.exe");
-			if (!existsSync(makensisPath)) {
-				throw new Error(`makensis not found at ${makensisPath}. LZMA compression requires NSIS binaries in dist-${targetOS}-${targetARCH}/nsis/`);
-			}
+			console.log("Creating archives (tar + streaming compression)...");
 
-			for (const { name, path: archiveSrcPath } of archives) {
-				const archiveFileName = `archive-${name}.exe`;
+			for (const spec of archives) {
+				const ext = spec.format === "gzip" ? "tar.gz" : "tar.zst";
+				const archiveFileName = `archive-${spec.name}.${ext}`;
 				const archiveDestPath = join(stagingDir, archiveFileName);
-				const nsiPath = join(stagingDir, `archive-${name}.nsi`);
-
-				console.log(`  Archiving ${name}: ${archiveSrcPath}`);
-
-				const nsiContent = `SetCompressor /SOLID lzma\nSilentInstall silent\nName "${name}"\nOutFile "${archiveDestPath.replace(/\\/g, "\\\\")}"\nInstallDir "$TEMP\\sparkbun-extract-${name}"\nSection\n  SetOutPath "$INSTDIR"\n  File /r "${archiveSrcPath.replace(/\\/g, "\\\\")}\\*.*"\nSectionEnd\n`;
-				writeFileSync(nsiPath, nsiContent);
-
-				const result = Bun.spawnSync([makensisPath, nsiPath], {
-					cwd: nsisDir,
-					env: { ...process.env, NSISDIR: nsisDir },
-					stdout: "pipe",
-					stderr: "pipe",
-				});
-
-				if (result.exitCode !== 0) {
-					const stderr = result.stderr.toString();
-					const stdout = result.stdout.toString();
-					console.error(`makensis failed for ${name}:`, stderr || stdout);
-					throw new Error(`Failed to compress archive: ${name}`);
-				}
-
-				unlinkSync(nsiPath);
-
-				const archiveSize = statSync(archiveDestPath).size;
-				console.log(`  ${name}: ${(archiveSize / 1024 / 1024).toFixed(2)} MB`);
-				archiveManifest[name] = 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]);
+
+				// 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)`,
+				);
+				archiveManifest[spec.name] = {
+					file: archiveFileName,
+					format: spec.format,
+					level: spec.level,
+					uncompressedBytes,
+					fileCount,
+					compressedBytes,
+				};
 			}
 		}
 
@@ -3521,7 +3626,7 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 		const archiveImports: string[] = [];
 		const archiveExports: string[] = [];
 		for (const { name } of archives) {
-			const fileName = archiveManifest[name];
+			const fileName = archiveManifest[name]!.file;
 			archiveImports.push(`import archive_${name} from "./${fileName}" with { type: "file" };`);
 			archiveExports.push(`  "${name}": archive_${name},`);
 		}

package/src/installer/installer-wrapper-template.ts

@@ -4,7 +4,7 @@
  * This file is the entrypoint for installers built with `bun sparkbun installer`.
  * It gets compiled into a single executable that contains:
  *   - A small runtime bundle (DLLs, views, app code — ~1MB compressed)
- *   - The installer's payload archives (LZMA compressed via NSIS)
+ *   - The installer's payload archives (tar + zstd/gzip)
  *
  * The binary uses a two-phase execution model with a single Bun runtime:
  *
@@ -25,7 +25,8 @@
  *
  * The payload archives stay embedded in the binary at all times — they are
  * never extracted to temp. Only when the user clicks "Install" does the app
- * code write them to disk and run them (NSIS silent self-extractors).
+ * code read them (via Bun.embeddedFiles, guided by the Resources/archives.json
+ * manifest) and stream them to disk.
  */
 
 import runtimeArchive from "./runtime-bundle.tar.gz" with { type: "file" };