tar.ts

1import { gzipSync } from "node:zlib";23export type TarFile = { path: string; bytes: Uint8Array };45// Kepr 2's strip list (§22.3, `source_archive.zig`): build metadata, Koh bookkeeping and lockfiles6// that pin a consumer's environment. Matched at the repo root only. `flake.lock` and `build.zig.zon`7// stay, because Nix needs both.8const STRIPPED = new Set([9	"koh.build",10	"kepr.build",11	"Cargo.lock",12	"package-lock.json",13	"yarn.lock",14	"pnpm-lock.yaml",15	"bun.lockb",16	"go.sum",17	"LOG.md",18	"CONTINUITY.md",19	"AGENTS.md",20	".kohignore",21	".gitignore",22]);2324export function isStripped(path: string): boolean {25	return STRIPPED.has(path) || path === ".agent" || path.startsWith(".agent/");26}2728const encoder = new TextEncoder();29const BLOCK = 512;3031/**32 * A deterministic `.tar.gz` of `files` under `root/`, byte for byte what Kepr 2 wrote: one directory33 * entry for the root, then the files in byte order of their paths, all 0644, with zero owners and34 * times (§22.3: the headers match Kepr 2's, so an executable bit is not kept).35 */36export function buildTarball(root: string, files: TarFile[]): Uint8Array<ArrayBuffer> {37	const entries = files38		.filter((file) => file.path !== "" && !isStripped(file.path))39		.map((file) => ({ ...file, name: encoder.encode(`${root}/${file.path}`) }))40		.sort((a, b) => Buffer.compare(a.name, b.name));41	const blocks: Uint8Array[] = [header(encoder.encode(root), 0, true)];42	for (const entry of entries) {43		blocks.push(header(entry.name, entry.bytes.length, false));44		blocks.push(entry.bytes, new Uint8Array((BLOCK - (entry.bytes.length % BLOCK)) % BLOCK));45	}46	blocks.push(new Uint8Array(2 * BLOCK));47	const gzip = gzipSync(Buffer.concat(blocks), { level: 6 });48	// zlib stamps the host's OS in the gzip header (19 on macOS); Kepr 2 wrote 3 (Unix) everywhere.49	gzip[9] = 3;50	return gzip;51}5253// A POSIX ustar header, as Kepr 2's `tarWriteHeader`: names over 99 bytes (98 for a directory, which54// needs its trailing slash) split at a '/' into the 155-byte prefix field, never truncated.55function header(name: Uint8Array, size: number, isDir: boolean): Uint8Array {56	const h = new Uint8Array(BLOCK);57	const maxName = isDir ? 98 : 99;58	let base = name;59	if (name.length > maxName) {60		const split = splitAt(name, maxName);61		if (split === null)62			throw new Error(`path too long for a tarball: ${new TextDecoder().decode(name)}`);63		h.set(name.subarray(0, split), 345);64		base = name.subarray(split + 1);65	}66	h.set(base);67	if (isDir) h[base.length] = 0x2f;68	const ascii = (text: string, at: number) => h.set(encoder.encode(text), at);69	ascii(isDir ? "0000755\0" : "0000644\0", 100);70	ascii("0000000\0", 108);71	ascii("0000000\0", 116);72	if (!isDir) ascii(`${size.toString(8).padStart(11, "0")}\0`, 124);73	ascii("00000000000\0", 136);74	ascii("        ", 148);75	ascii(isDir ? "5" : "0", 156);76	ascii("ustar\0", 257);77	ascii("00", 263);78	const sum = h.reduce((total, byte) => total + byte, 0);79	ascii(`${sum.toString(8).padStart(6, "0")}\0 `, 148);80	return h;81}8283// The rightmost '/' leaving a prefix of at most 154 bytes and a name of at most `maxName`.84function splitAt(path: Uint8Array, maxName: number): number | null {85	const min = path.length - maxName - 1;86	for (let i = Math.min(path.length - 1, 154); i >= Math.max(min, 0); i--) {87		if (path[i] === 0x2f) return i;88	}89	return null;90}