nerdsystem 0.0.11 → 0.0.13

package/dist/snapshot.js

@@ -0,0 +1,896 @@
+/**
+ * Source snapshots: the deterministic tar.gz of an app folder that is stored with every deploy and
+ * every `nerd save`, and restored by `nerd pull` (docs/source-snapshots.md). The builder imports this
+ * file from the CLI's dist, so it depends on Node and `./gates/text.js` only.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, unlinkSync, writeFileSync, chmodSync } from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGzip, gunzipSync } from "node:zlib";
+import { isSnapshotExcluded, isSnapshotForced, isSnapshotForcedDir, MAX_SNAPSHOT_FILE_BYTES, MAX_SNAPSHOT_HEADER_BYTES, MAX_SOURCE_BYTES, MAX_SOURCE_FILES, MAX_SOURCE_UNPACKED, SKIP_DIR, SNAPSHOT_MANIFEST, snapshotForcedWarning, validateSnapshotEntry, } from "./gates/text.js";
+export { MAX_SNAPSHOT_FILE_BYTES, MAX_SOURCE_BYTES, MAX_SOURCE_FILES, MAX_SOURCE_UNPACKED, SNAPSHOT_MANIFEST, validateSnapshotEntry } from "./gates/text.js";
+export class SnapshotError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "SnapshotError";
+    }
+}
+const MB = 1024 * 1024;
+const BLOCK = 512;
+const MODE_FILE = 0o644;
+const MODE_EXEC = 0o755;
+/** Warnings printed per forced file before the rest fold into one line. */
+const FORCED_WARNING_LIMIT = 20;
+export function formatMb(bytes) {
+    const mb = bytes / MB;
+    return mb >= 10 ? `${Math.round(mb)} MB` : `${Math.max(0.1, Math.round(mb * 10) / 10)} MB`;
+}
+function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function byteOrder(a, b) {
+    return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+function gitEnv() {
+    const env = { ...process.env };
+    for (const k of ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES"])
+        delete env[k];
+    return env;
+}
+function gitRun(root, args) {
+    try {
+        return execFileSync("git", args, { cwd: root, env: gitEnv(), stdio: ["ignore", "pipe", "ignore"], maxBuffer: 256 * MB, windowsHide: true });
+    }
+    catch {
+        return null;
+    }
+}
+function gitLsFiles(root, args) {
+    const out = gitRun(root, ["ls-files", "-z", ...args]);
+    if (out === null)
+        return null;
+    return out.toString("utf8").split("\0").filter((p) => p.length > 0);
+}
+/** `{ sha, branch }` of the checkout at `root`, or null when there is no git, no repo, or no commit yet. */
+export function gitInfo(root) {
+    if (!existsSync(path.join(root, ".git")))
+        return null;
+    const sha = gitRun(root, ["rev-parse", "HEAD"])?.toString("utf8").trim();
+    if (!sha || !/^[0-9a-f]{40,64}$/.test(sha))
+        return null;
+    const branch = gitRun(root, ["rev-parse", "--abbrev-ref", "HEAD"])?.toString("utf8").trim() || "HEAD";
+    return { sha, branch };
+}
+function toAbs(root, posix) {
+    return path.join(root, ...posix.split("/"));
+}
+/** Every regular file under an ignored directory the snapshot must keep (hard excludes still apply). */
+function walkForced(root, dirRel, out) {
+    let entries;
+    try {
+        entries = readdirSync(toAbs(root, dirRel), { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort((a, b) => byteOrder(a.name, b.name));
+    for (const entry of entries) {
+        const rel = `${dirRel}/${entry.name}`;
+        const kind = direntKind(entry, toAbs(root, rel));
+        if (kind === "dir") {
+            if (!isSnapshotExcluded(`${rel}/`))
+                walkForced(root, rel, out);
+        }
+        else if (kind === "file" && isSnapshotForced(rel)) {
+            out.push(rel);
+        }
+    }
+}
+function direntKind(entry, abs) {
+    if (entry.isSymbolicLink())
+        return "other";
+    if (entry.isDirectory())
+        return "dir";
+    if (entry.isFile())
+        return "file";
+    try {
+        const st = lstatSync(abs);
+        return st.isDirectory() ? "dir" : st.isFile() ? "file" : "other";
+    }
+    catch {
+        return "other";
+    }
+}
+/** Candidates from git: tracked plus untracked-not-ignored, and the ignored files a rebuild needs. */
+function listWithGit(root) {
+    if (!existsSync(path.join(root, ".git")))
+        return null;
+    const listed = gitLsFiles(root, ["--cached", "--others", "--exclude-standard"]);
+    if (listed === null)
+        return null;
+    // `--directory` collapses a wholly ignored directory into one `dir/` entry, so node_modules is one
+    // line instead of fifty thousand; the directories a rebuild needs are walked on the filesystem.
+    const ignored = gitLsFiles(root, ["--others", "--ignored", "--exclude-standard", "--directory"]) ?? [];
+    const forced = [];
+    for (const entry of ignored) {
+        if (entry.endsWith("/")) {
+            const dir = entry.replace(/\/+$/, "");
+            if (isSnapshotForcedDir(dir))
+                walkForced(root, dir, forced);
+        }
+        else if (isSnapshotForced(entry)) {
+            forced.push(entry);
+        }
+    }
+    return { paths: listed, forced };
+}
+function globToRegex(glob) {
+    let out = "";
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === "*") {
+            if (glob[i + 1] === "*") {
+                out += ".*";
+                i++;
+                if (glob[i + 1] === "/")
+                    i++;
+            }
+            else
+                out += "[^/]*";
+        }
+        else if (ch === "?")
+            out += "[^/]";
+        else if (/[.+^${}()|[\]\\]/.test(ch))
+            out += `\\${ch}`;
+        else
+            out += ch;
+    }
+    return out;
+}
+export function parseGitignore(text, baseRel) {
+    const base = baseRel ? `${globToRegex(baseRel)}/` : "";
+    const rules = [];
+    for (const raw of text.split(/\r?\n/)) {
+        let line = raw.replace(/(?<!\\)\s+$/, "");
+        if (line === "" || line.startsWith("#") || line.startsWith("!"))
+            continue;
+        let dirOnly = false;
+        if (line.endsWith("/")) {
+            dirOnly = true;
+            line = line.replace(/\/+$/, "");
+        }
+        if (line.startsWith("**/"))
+            line = line.slice(3);
+        let anchored = false;
+        if (line.startsWith("/")) {
+            anchored = true;
+            line = line.replace(/^\/+/, "");
+        }
+        else if (line.includes("/"))
+            anchored = true;
+        if (line === "")
+            continue;
+        const body = globToRegex(line.replace(/\\(.)/g, "$1"));
+        const re = anchored ? new RegExp(`^${base}${body}(/|$)`) : new RegExp(`^${base}(.*/)?${body}(/|$)`);
+        rules.push({ re, dirOnly });
+    }
+    return rules;
+}
+function ignoredBy(rules, rel, isDir) {
+    return rules.some((r) => (!r.dirOnly || isDir) && r.re.test(rel));
+}
+/** Candidates from the filesystem when git is not there. */
+function listByWalking(root, skipped) {
+    const paths = [];
+    const forced = [];
+    const walk = (dirRel, inherited, ancestorIgnored) => {
+        let entries;
+        try {
+            entries = readdirSync(dirRel ? toAbs(root, dirRel) : root, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => byteOrder(a.name, b.name));
+        let rules = inherited;
+        const ignoreFile = path.join(dirRel ? toAbs(root, dirRel) : root, ".gitignore");
+        if (entries.some((e) => e.name === ".gitignore" && !e.isDirectory())) {
+            try {
+                rules = [...inherited, ...parseGitignore(readFileSync(ignoreFile, "utf8"), dirRel)];
+            }
+            catch {
+                // unreadable .gitignore: ignore nothing extra
+            }
+        }
+        for (const entry of entries) {
+            const rel = dirRel ? `${dirRel}/${entry.name}` : entry.name;
+            const kind = direntKind(entry, toAbs(root, rel));
+            if (kind === "dir") {
+                if (isSnapshotExcluded(`${rel}/`))
+                    continue;
+                const underForced = isSnapshotForcedDir(rel);
+                if (!underForced && SKIP_DIR.test(`${rel}/`))
+                    continue;
+                const ignored = ancestorIgnored || ignoredBy(rules, rel, true);
+                if (ignored && !underForced)
+                    continue;
+                walk(rel, rules, ignored);
+            }
+            else if (kind === "file") {
+                if (isSnapshotExcluded(rel))
+                    continue;
+                const ignored = ancestorIgnored || ignoredBy(rules, rel, false);
+                if (ignored) {
+                    if (isSnapshotForced(rel))
+                        forced.push(rel);
+                }
+                else
+                    paths.push(rel);
+            }
+            else {
+                let size = 0;
+                try {
+                    size = lstatSync(toAbs(root, rel)).size;
+                }
+                catch {
+                    // gone already
+                }
+                skipped.push({ path: rel, size, reason: "not a regular file" });
+            }
+        }
+    };
+    walk("", [], false);
+    return { paths, forced };
+}
+/**
+ * The files a snapshot of `root` holds, sorted by path in byte order. Uses git when `.git` exists and
+ * git runs, else walks the folder. Every candidate is stat'ed; missing and non-regular paths are
+ * dropped, the hard exclude list is applied last, and a file over 50 MB is left out with a warning.
+ */
+export function listSnapshotFiles(root, opts = {}) {
+    root = path.resolve(root);
+    const skipped = [];
+    const warnings = [];
+    const fromGit = opts.useGit === false ? null : listWithGit(root);
+    const listedBy = fromGit ? "git" : "walk";
+    const { paths, forced } = fromGit ?? listByWalking(root, skipped);
+    const forcedSet = new Set();
+    const candidates = new Map();
+    for (const p of paths)
+        candidates.set(p, false);
+    for (const p of forced)
+        if (!candidates.has(p))
+            candidates.set(p, true);
+    const files = [];
+    for (const [rel, isForced] of candidates) {
+        if (rel.startsWith("../") || rel === ".." || rel.startsWith("/"))
+            continue;
+        if (isSnapshotExcluded(rel)) {
+            skipped.push({ path: rel, size: 0, reason: "never saved: local databases, env files, keys, and caches stay on this computer" });
+            continue;
+        }
+        const abs = toAbs(root, rel);
+        let st;
+        try {
+            st = lstatSync(abs);
+        }
+        catch {
+            skipped.push({ path: rel, size: 0, reason: "missing on disk" });
+            continue;
+        }
+        if (!st.isFile()) {
+            skipped.push({ path: rel, size: st.size, reason: st.isSymbolicLink() ? "symbolic link" : "not a regular file" });
+            continue;
+        }
+        if (st.size > MAX_SNAPSHOT_FILE_BYTES) {
+            skipped.push({ path: rel, size: st.size, reason: `over ${MAX_SNAPSHOT_FILE_BYTES / MB} MB` });
+            warnings.push(`\`${rel}\` is ${formatMb(st.size)} and was left out of the saved copy; files over ${MAX_SNAPSHOT_FILE_BYTES / MB} MB are not saved. Keep videos and large files in file storage.`);
+            continue;
+        }
+        files.push({ path: rel, abs, size: st.size, mode: st.mode & 0o111 ? MODE_EXEC : MODE_FILE });
+        if (isForced)
+            forcedSet.add(rel);
+    }
+    files.sort((a, b) => byteOrder(a.path, b.path));
+    const forcedKept = files.map((f) => f.path).filter((p) => forcedSet.has(p));
+    forcedKept.slice(0, FORCED_WARNING_LIMIT).forEach((p) => warnings.push(snapshotForcedWarning(p)));
+    if (forcedKept.length > FORCED_WARNING_LIMIT)
+        warnings.push(`${forcedKept.length - FORCED_WARNING_LIMIT} more files are in .gitignore but a rebuild needs them; they are in the saved copy`);
+    return { files, warnings, skipped, forced: forcedKept, listedBy };
+}
+// ---------------------------------------------------------------------------------------------
+// Tar writer (ustar, deterministic)
+// ---------------------------------------------------------------------------------------------
+function octalField(n, width) {
+    const b = Buffer.alloc(width);
+    b.write(n.toString(8).padStart(width - 1, "0"), 0, "ascii");
+    return b;
+}
+function tarHeader(e) {
+    const h = Buffer.alloc(BLOCK);
+    const name = Buffer.from(e.name, "utf8");
+    name.copy(h, 0, 0, Math.min(100, name.length));
+    octalField(e.mode ?? MODE_FILE, 8).copy(h, 100);
+    octalField(0, 8).copy(h, 108);
+    octalField(0, 8).copy(h, 116);
+    octalField(e.data?.length ?? 0, 12).copy(h, 124);
+    octalField(0, 12).copy(h, 136);
+    h.fill(0x20, 148, 156);
+    h.write(e.type === "" ? "\0" : e.type, 156, 1, "latin1");
+    if (e.linkname)
+        Buffer.from(e.linkname, "utf8").copy(h, 157, 0, 100);
+    h.write("ustar\0", 257, "ascii");
+    h.write("00", 263, "ascii");
+    octalField(0, 8).copy(h, 329);
+    octalField(0, 8).copy(h, 337);
+    if (e.prefix)
+        Buffer.from(e.prefix, "utf8").copy(h, 345, 0, 155);
+    let sum = 0;
+    for (const byte of h)
+        sum += byte;
+    h.write(sum.toString(8).padStart(6, "0"), 148, "ascii");
+    h[154] = 0;
+    h[155] = 0x20;
+    return h;
+}
+function padding(size) {
+    const rest = size % BLOCK;
+    return rest === 0 ? Buffer.alloc(0) : Buffer.alloc(BLOCK - rest);
+}
+/** The bytes of one entry: an optional PAX header for a long path, the ustar header, data, padding. */
+export function tarEntryBytes(e) {
+    const out = [];
+    const data = e.data ?? Buffer.alloc(0);
+    const nameBytes = Buffer.from(e.name, "utf8");
+    let headerName = e.name;
+    if (nameBytes.length > 100 && !e.prefix) {
+        const record = paxRecord("path", e.name);
+        const shortName = truncateName(nameBytes);
+        out.push(tarHeader({ name: `PaxHeader/${shortName}`.slice(0, 100), type: "x", data: record, mode: MODE_FILE }), record, padding(record.length));
+        headerName = shortName;
+    }
+    out.push(tarHeader({ ...e, name: headerName, data }));
+    if (data.length > 0)
+        out.push(data, padding(data.length));
+    return out;
+}
+/** The first 100 bytes of a long name, cut back to a whole path segment so it is never a partial one. */
+function truncateName(nameBytes) {
+    const cut = nameBytes.subarray(0, 100);
+    const slash = cut.lastIndexOf(0x2f);
+    return (slash > 0 ? cut.subarray(0, slash) : cut).toString("utf8").replace(/�+$/, "");
+}
+function paxRecord(key, value) {
+    const body = Buffer.from(` ${key}=${value}\n`, "utf8");
+    let len = body.length + 1;
+    while (String(len).length + body.length !== len)
+        len = String(len).length + body.length;
+    return Buffer.concat([Buffer.from(String(len), "ascii"), body]);
+}
+/** A whole tar from raw entries, in the given order, with the two end blocks. Tests build hostile tars with it. */
+export function buildTar(entries) {
+    const parts = [];
+    for (const e of entries)
+        parts.push(...tarEntryBytes(e));
+    parts.push(Buffer.alloc(BLOCK * 2));
+    return Buffer.concat(parts);
+}
+/** gzip level 6 with a fixed header (mtime 0, OS byte 3) so the same tar always gives the same bytes. */
+export async function gzipDeterministic(chunks, maxBytes = Infinity) {
+    const out = [];
+    let total = 0;
+    const gzip = createGzip({ level: 6 });
+    let over = false;
+    try {
+        await pipeline(Readable.from(chunks), gzip, async (source) => {
+            for await (const chunk of source) {
+                total += chunk.length;
+                if (total > maxBytes) {
+                    over = true;
+                    throw new SnapshotError("compressed snapshot is over the cap", "too_large");
+                }
+                out.push(chunk);
+            }
+        });
+    }
+    catch (err) {
+        // pipeline may report its own abort error once the consumer stops early; the cap is the cause.
+        if (over)
+            throw new SnapshotError("compressed snapshot is over the cap", "too_large");
+        throw err;
+    }
+    const gz = Buffer.concat(out);
+    gz.writeUInt32LE(0, 4);
+    gz[9] = 3;
+    return gz;
+}
+function tarSizeOf(name, size) {
+    const nameBytes = Buffer.byteLength(name, "utf8");
+    let total = BLOCK + size + padding(size).length;
+    if (nameBytes > 100) {
+        const record = paxRecord("path", name).length;
+        total += BLOCK + record + padding(record).length;
+    }
+    return total;
+}
+function tooLargeResult(reason, files, base, tarBytes) {
+    const bytes = files.reduce((n, f) => n + f.size, 0);
+    const largest = [...files]
+        .sort((a, b) => b.size - a.size || byteOrder(a.path, b.path))
+        .slice(0, 5)
+        .map((f) => ({ path: f.path, size: f.size }));
+    const names = largest
+        .slice(0, 2)
+        .map((f) => `${f.path} (${formatMb(f.size)})`)
+        .join(", ");
+    const message = reason === "files"
+        ? `Code not saved: the app folder has ${files.length.toLocaleString("en-US")} files; the most a snapshot holds is ${MAX_SOURCE_FILES.toLocaleString("en-US")}. Add generated folders to .gitignore.`
+        : `Code not saved: the app folder is ${formatMb(bytes)}; the largest files are ${names}. Keep videos and large files in file storage, or add them to .gitignore.`;
+    return { ...base, bytes, tarBytes, tooLarge: { reason, bytes, fileCount: files.length, largest, message } };
+}
+/**
+ * Packs the app at `root` into a deterministic tar.gz. Returns `tooLarge` instead of `gz` when a
+ * cap is hit (a user-caused skip: the deploy proceeds without a snapshot). Throws `SnapshotError`
+ * with code `changed` when a file changed under it; the caller should try once more.
+ */
+export async function packSnapshot(root, opts = {}) {
+    root = path.resolve(root);
+    const selection = listSnapshotFiles(root, opts);
+    const { files } = selection;
+    const git = opts.git === undefined ? gitInfo(root) : opts.git;
+    const base = {
+        fileCount: files.length,
+        manifest: { version: 1, createdAt: opts.createdAt ?? new Date().toISOString(), cli: opts.cli ?? "unknown", node: opts.node ?? process.version, git, files: [] },
+        warnings: selection.warnings,
+        skipped: selection.skipped,
+        forced: selection.forced,
+        listedBy: selection.listedBy,
+    };
+    let tarBytes = BLOCK * 2;
+    for (const f of files)
+        tarBytes += tarSizeOf(f.path, f.size);
+    if (files.length > MAX_SOURCE_FILES)
+        return tooLargeResult("files", files, base, tarBytes);
+    if (tarBytes > MAX_SOURCE_UNPACKED)
+        return tooLargeResult("unpacked", files, base, tarBytes);
+    // Pass one: hash every file so the manifest, the first entry, can list them all.
+    const manifestFiles = files.map((f) => {
+        const data = readFileSync(f.abs);
+        return { path: f.path, size: data.length, sha256: sha256(data), mode: f.mode };
+    });
+    const manifest = { ...base.manifest, files: manifestFiles };
+    const manifestData = Buffer.from(JSON.stringify(manifest, null, 2), "utf8");
+    tarBytes += tarSizeOf(SNAPSHOT_MANIFEST, manifestData.length);
+    if (tarBytes > MAX_SOURCE_UNPACKED)
+        return tooLargeResult("unpacked", files, base, tarBytes);
+    // Pass two: stream the tar through gzip, hashing the tar bytes (manifest excluded) on the way.
+    const tree = createHash("sha256");
+    let streamed = 0;
+    async function* chunks() {
+        for (const chunk of tarEntryBytes({ name: SNAPSHOT_MANIFEST, type: "0", data: manifestData, mode: MODE_FILE })) {
+            streamed += chunk.length;
+            yield chunk;
+        }
+        for (let i = 0; i < files.length; i++) {
+            const f = files[i];
+            const listed = manifestFiles[i];
+            const data = readFileSync(f.abs);
+            if (data.length !== listed.size || sha256(data) !== listed.sha256)
+                throw new SnapshotError(`\`${f.path}\` changed while the snapshot was being packed. Try again.`, "changed");
+            for (const chunk of tarEntryBytes({ name: f.path, type: "0", data, mode: f.mode })) {
+                tree.update(chunk);
+                streamed += chunk.length;
+                yield chunk;
+            }
+        }
+        const end = Buffer.alloc(BLOCK * 2);
+        tree.update(end);
+        streamed += end.length;
+        yield end;
+    }
+    let gz;
+    try {
+        gz = await gzipDeterministic(chunks(), MAX_SOURCE_BYTES);
+    }
+    catch (err) {
+        if (err instanceof SnapshotError && err.code === "too_large")
+            return tooLargeResult("compressed", files, base, tarBytes);
+        throw err;
+    }
+    if (streamed !== tarBytes)
+        throw new SnapshotError("snapshot size did not add up; try again", "changed");
+    return { ...base, manifest, gz, sha256: sha256(gz), treeHash: tree.digest("hex"), bytes: gz.length, tarBytes };
+}
+function parseOctal(h, offset, width, what) {
+    if (h[offset] & 0x80)
+        throw new SnapshotError(`tar ${what} uses base-256 encoding, which snapshots never do`, "invalid_snapshot");
+    const text = h.toString("ascii", offset, offset + width).replace(/\0.*$/s, "").trim();
+    if (text === "")
+        return 0;
+    if (!/^[0-7]+$/.test(text))
+        throw new SnapshotError(`tar ${what} field is not octal`, "invalid_snapshot");
+    return parseInt(text, 8);
+}
+function cString(h, offset, width) {
+    const end = h.indexOf(0, offset);
+    return h.toString("utf8", offset, end === -1 || end > offset + width ? offset + width : end);
+}
+/** Raw entries in order; PAX and long-name headers are yielded as entries and resolved by the caller. */
+export function* parseTar(tar) {
+    let offset = 0;
+    while (offset + BLOCK <= tar.length) {
+        const h = tar.subarray(offset, offset + BLOCK);
+        if (h.every((b) => b === 0))
+            return;
+        let unsigned = 0;
+        let signed = 0;
+        for (let i = 0; i < BLOCK; i++) {
+            const b = i >= 148 && i < 156 ? 0x20 : h[i];
+            unsigned += b;
+            signed += i >= 148 && i < 156 ? 0x20 : (b << 24) >> 24;
+        }
+        const stored = parseOctal(h, 148, 8, "checksum");
+        if (stored !== unsigned && stored !== signed)
+            throw new SnapshotError("tar header checksum does not match; the snapshot is damaged", "invalid_snapshot");
+        const size = parseOctal(h, 124, 12, "size");
+        const mode = parseOctal(h, 100, 8, "mode");
+        const type = h.toString("latin1", 156, 157);
+        const magic = h.toString("ascii", 257, 262);
+        const prefix = magic === "ustar" ? cString(h, 345, 155) : "";
+        const base = cString(h, 0, 100);
+        const name = prefix ? `${prefix}/${base}` : base;
+        const dataStart = offset + BLOCK;
+        const dataEnd = dataStart + size;
+        if (dataEnd > tar.length)
+            throw new SnapshotError(`entry "${name.slice(0, 120)}" runs past the end of the archive`, "invalid_snapshot");
+        yield { name, type, size, mode, data: tar.subarray(dataStart, dataEnd) };
+        offset = dataEnd + padding(size).length;
+    }
+}
+function parsePax(data) {
+    const out = new Map();
+    let pos = 0;
+    while (pos < data.length) {
+        const space = data.indexOf(0x20, pos);
+        if (space === -1)
+            throw new SnapshotError("malformed PAX header", "invalid_snapshot");
+        const len = Number(data.toString("ascii", pos, space));
+        if (!Number.isInteger(len) || len <= space - pos + 1 || pos + len > data.length || data[pos + len - 1] !== 0x0a)
+            throw new SnapshotError("malformed PAX header", "invalid_snapshot");
+        const record = data.toString("utf8", space + 1, pos + len - 1);
+        const eq = record.indexOf("=");
+        if (eq === -1)
+            throw new SnapshotError("malformed PAX header", "invalid_snapshot");
+        out.set(record.slice(0, eq), record.slice(eq + 1));
+        pos += len;
+    }
+    return out;
+}
+const HEX64 = /^[0-9a-f]{64}$/;
+function parseManifest(entry) {
+    if (!entry || (entry.type !== "0" && entry.type !== "\0") || entry.name !== SNAPSHOT_MANIFEST)
+        throw new SnapshotError(`the first entry must be ${SNAPSHOT_MANIFEST}`, "invalid_snapshot");
+    let raw;
+    try {
+        raw = JSON.parse(entry.data.toString("utf8"));
+    }
+    catch {
+        throw new SnapshotError(`${SNAPSHOT_MANIFEST} is not valid JSON`, "invalid_snapshot");
+    }
+    if (!raw || typeof raw !== "object")
+        throw new SnapshotError(`${SNAPSHOT_MANIFEST} is not an object`, "invalid_snapshot");
+    const m = raw;
+    if (m.version !== 1)
+        throw new SnapshotError(`${SNAPSHOT_MANIFEST} has version ${JSON.stringify(m.version)}; this nerd reads version 1`, "invalid_snapshot");
+    if (!Array.isArray(m.files))
+        throw new SnapshotError(`${SNAPSHOT_MANIFEST} has no files list`, "invalid_snapshot");
+    if (m.files.length > MAX_SOURCE_FILES)
+        throw new SnapshotError(`${SNAPSHOT_MANIFEST} lists more than ${MAX_SOURCE_FILES} files`, "invalid_snapshot");
+    const seen = new Set();
+    const files = [];
+    for (const f of m.files) {
+        const r = (f && typeof f === "object" ? f : {});
+        if (typeof r.path !== "string" || typeof r.size !== "number" || typeof r.sha256 !== "string" || typeof r.mode !== "number")
+            throw new SnapshotError(`${SNAPSHOT_MANIFEST} has a malformed file entry`, "invalid_snapshot");
+        const reason = validateSnapshotEntry({ name: r.path, type: "0", size: r.size });
+        if (reason)
+            throw new SnapshotError(`${SNAPSHOT_MANIFEST}: ${reason}`, "invalid_snapshot");
+        if (r.path === SNAPSHOT_MANIFEST)
+            throw new SnapshotError(`${SNAPSHOT_MANIFEST} lists itself`, "invalid_snapshot");
+        if (!HEX64.test(r.sha256))
+            throw new SnapshotError(`${SNAPSHOT_MANIFEST}: "${r.path.slice(0, 120)}" has a malformed sha256`, "invalid_snapshot");
+        if (seen.has(r.path))
+            throw new SnapshotError(`${SNAPSHOT_MANIFEST} lists "${r.path.slice(0, 120)}" twice`, "invalid_snapshot");
+        seen.add(r.path);
+        files.push({ path: r.path, size: r.size, sha256: r.sha256, mode: r.mode & 0o111 ? MODE_EXEC : MODE_FILE });
+    }
+    const git = m.git && typeof m.git === "object" ? m.git : null;
+    return {
+        version: 1,
+        createdAt: typeof m.createdAt === "string" ? m.createdAt : "",
+        cli: typeof m.cli === "string" ? m.cli : "",
+        node: typeof m.node === "string" ? m.node : "",
+        git: git && typeof git.sha === "string" ? { sha: git.sha, branch: typeof git.branch === "string" ? git.branch : "" } : null,
+        files,
+    };
+}
+/** Uncompresses a snapshot with the unpacked cap enforced. */
+export function gunzipSnapshot(gz) {
+    if (gz.length > MAX_SOURCE_BYTES)
+        throw new SnapshotError(`the snapshot is ${formatMb(gz.length)} compressed; the most this nerd accepts is ${MAX_SOURCE_BYTES / MB} MB`, "too_large");
+    try {
+        return gunzipSync(gz, { maxOutputLength: MAX_SOURCE_UNPACKED });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ERR_BUFFER_TOO_LARGE")
+            throw new SnapshotError(`the snapshot unpacks to more than ${MAX_SOURCE_UNPACKED / MB} MB and was refused`, "too_large");
+        throw new SnapshotError("the snapshot is not a gzip file nerd can read; the download may be damaged", "invalid_snapshot");
+    }
+}
+/** The manifest alone, for callers that only need the file list. */
+export function readSnapshotManifest(gz) {
+    const tar = gunzipSnapshot(gz);
+    const first = parseTar(tar).next();
+    return parseManifest(first.done ? undefined : first.value);
+}
+function isInside(target, candidate) {
+    return candidate === target || candidate.startsWith(target + path.sep);
+}
+function shown(name) {
+    return name.slice(0, 120);
+}
+/**
+ * The archive-only pass: every header checksum, every type, PAX and long-name resolution, the
+ * manifest's rules, duplicates, sizes, the sha256 of every file, every manifest file present, and
+ * no path listed both as a file and as a folder. Reads nothing from and writes nothing to the disk,
+ * so a bad archive is refused before a single byte lands.
+ */
+function planExtraction(gz) {
+    const tar = gunzipSnapshot(gz);
+    const entries = parseTar(tar);
+    const first = entries.next();
+    const manifest = parseManifest(first.done ? undefined : first.value);
+    const expected = new Map(manifest.files.map((f) => [f.path, f]));
+    const done = new Set();
+    const dirs = new Set();
+    const steps = [];
+    let pending = null;
+    let count = 0;
+    for (const raw of entries) {
+        const type = raw.type === "" ? "\0" : raw.type;
+        if (type === "x" || type === "L") {
+            // The raw ustar name of a PAX or long-name header is filler readers ignore (the packer writes
+            // "PaxHeader/<short name>" cut at 100 bytes, which can end on a slash); only its type and size count.
+            // The path it carries is held to the full rules when the entry it names comes up.
+            const headerReason = validateSnapshotEntry({ name: type === "x" ? "PaxHeader" : "LongLink", type, size: raw.size });
+            if (headerReason)
+                throw new SnapshotError(headerReason, "invalid_snapshot");
+            if (pending)
+                throw new SnapshotError(type === "x" ? "two PAX headers in a row" : "two long-name headers in a row", "invalid_snapshot");
+            if (type === "x") {
+                const records = parsePax(raw.data);
+                if (records.has("linkpath"))
+                    throw new SnapshotError("a PAX header carries a link path; links are not allowed", "invalid_snapshot");
+                if (records.has("size") && Number(records.get("size")) > MAX_SNAPSHOT_FILE_BYTES)
+                    throw new SnapshotError("a PAX header declares a file over the size cap", "invalid_snapshot");
+                pending = { path: records.get("path") ?? null };
+            }
+            else {
+                pending = { path: raw.data.toString("utf8").replace(/\0.*$/s, "") };
+            }
+            continue;
+        }
+        // Only data entries count toward the cap, the way the packer and the API count them.
+        count++;
+        if (count > MAX_SOURCE_FILES)
+            throw new SnapshotError(`the snapshot has more than ${MAX_SOURCE_FILES} entries`, "invalid_snapshot");
+        const name = pending?.path ?? raw.name;
+        pending = null;
+        const reason = validateSnapshotEntry({ name, type, size: raw.size });
+        if (reason)
+            throw new SnapshotError(reason, "invalid_snapshot");
+        const segments = name.replace(/\/+$/, "").split("/");
+        const clean = segments.join("/");
+        if (type === "5") {
+            if (expected.has(clean))
+                throw new SnapshotError(`"${shown(clean)}" is listed both as a file and as a folder`, "invalid_snapshot");
+            dirs.add(clean);
+            steps.push({ kind: "dir", name: clean, segments });
+            continue;
+        }
+        if (name === SNAPSHOT_MANIFEST)
+            throw new SnapshotError(`${SNAPSHOT_MANIFEST} appears twice`, "invalid_snapshot");
+        const listed = expected.get(name);
+        if (!listed)
+            throw new SnapshotError(`"${shown(name)}" is in the archive but not in its manifest`, "invalid_snapshot");
+        if (done.has(name))
+            throw new SnapshotError(`"${shown(name)}" appears twice`, "invalid_snapshot");
+        if (raw.data.length !== listed.size)
+            throw new SnapshotError(`"${shown(name)}" is ${raw.data.length} bytes but the manifest says ${listed.size}`, "invalid_snapshot");
+        if (sha256(raw.data) !== listed.sha256)
+            throw new SnapshotError(`"${shown(name)}" does not match its manifest hash`, "invalid_snapshot");
+        if (dirs.has(name))
+            throw new SnapshotError(`"${shown(name)}" is listed both as a file and as a folder`, "invalid_snapshot");
+        for (let i = 1; i < segments.length; i++) {
+            const parent = segments.slice(0, i).join("/");
+            if (expected.has(parent))
+                throw new SnapshotError(`"${shown(parent)}" is listed both as a file and as a folder`, "invalid_snapshot");
+            dirs.add(parent);
+        }
+        done.add(name);
+        steps.push({ kind: "file", name, segments, data: raw.data, mode: listed.mode });
+    }
+    if (pending)
+        throw new SnapshotError("the archive ends after a PAX or long-name header with no entry following it", "invalid_snapshot");
+    for (const f of manifest.files)
+        if (!done.has(f.path))
+            throw new SnapshotError(`"${shown(f.path)}" is in the manifest but missing from the archive`, "invalid_snapshot");
+    return { manifest, steps, files: done.size };
+}
+/**
+ * Checks the directories between the target and `dir` from the top down, each one that exists by
+ * lstat: a symbolic link is refused (wherever it points), a file in a folder's place is refused, and
+ * every real directory must resolve inside the real target. With `create`, the missing ones are then
+ * made one level at a time, so no directory is created anywhere before the check passes. `okDirs`
+ * remembers the directories already verified or created, so each one is looked at once.
+ */
+function ensureInside(target, realTarget, dir, name, okDirs, create) {
+    const rel = path.relative(target, dir);
+    const segments = rel === "" ? [] : rel.split(path.sep);
+    let current = target;
+    let missing = false;
+    for (const segment of segments) {
+        current = path.join(current, segment);
+        if (okDirs.has(current))
+            continue;
+        let st = null;
+        if (!missing) {
+            try {
+                st = lstatSync(current);
+            }
+            catch {
+                st = null;
+            }
+        }
+        if (!st) {
+            missing = true;
+            if (create) {
+                mkdirSync(current);
+                okDirs.add(current);
+            }
+            continue;
+        }
+        const where = path.relative(target, current).split(path.sep).join("/");
+        if (st.isSymbolicLink()) {
+            let real;
+            try {
+                real = realpathSync(current);
+            }
+            catch {
+                real = null;
+            }
+            if (!real || !isInside(realTarget, real))
+                throw new SnapshotError(`"${shown(name)}" would be written outside the target folder through a link`, "invalid_snapshot");
+            throw new SnapshotError(`"${shown(name)}" would be written through a link at "${where}"; replace the link with a folder first`, "invalid_snapshot");
+        }
+        if (!st.isDirectory())
+            throw new SnapshotError(`"${shown(name)}" needs the folder "${where}", but a file is in its place; move it away first`, "invalid_snapshot");
+        if (!isInside(realTarget, realpathSync(current)))
+            throw new SnapshotError(`"${shown(name)}" would be written outside the target folder`, "invalid_snapshot");
+        okDirs.add(current);
+    }
+}
+/** What is on the disk where a step wants to write, or null when nothing is. */
+function existingAt(dest) {
+    try {
+        return lstatSync(dest);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The disk pass, writing nothing: every step's destination is inside the target by path, the
+ * directories above it are real directories inside the target (no link anywhere on the way), and
+ * what sits at the destination can be replaced (a file or a link for a file; nothing or a real
+ * directory for a folder).
+ */
+function checkDestinations(plan, target, realTarget, okDirs) {
+    for (const step of plan.steps) {
+        const dest = path.resolve(target, ...step.segments);
+        if (!isInside(target, dest) || dest === target)
+            throw new SnapshotError(`entry "${shown(step.name)}" would land outside the target folder`, "invalid_snapshot");
+        ensureInside(target, realTarget, path.dirname(dest), step.name, okDirs, false);
+        const existing = existingAt(dest);
+        if (!existing)
+            continue;
+        if (step.kind === "dir") {
+            if (existing.isSymbolicLink())
+                throw new SnapshotError(`"${shown(step.name)}" is a link on this computer; replace it with a folder first`, "invalid_snapshot");
+            if (!existing.isDirectory())
+                throw new SnapshotError(`"${shown(step.name)}" exists as a file; move it away first`, "invalid_snapshot");
+        }
+        else if (!existing.isSymbolicLink() && !existing.isFile()) {
+            throw new SnapshotError(`"${shown(step.name)}" exists as a folder; move it away first`, "invalid_snapshot");
+        }
+    }
+}
+/**
+ * Extracts a snapshot into `targetDir` with every hardening rule from the spec: only regular files,
+ * directories, PAX and long-name headers; relative names with no `..`, backslash, or `.git`; nothing
+ * outside the target after resolution (symlinked parents included); every file listed in the
+ * manifest with the listed size and sha256, and every listed file present. The whole archive and the
+ * whole target are checked before the first write, so a refused archive changes nothing on the disk,
+ * the files already in a `force` target included. A non-empty target needs `force`.
+ */
+export function extractSnapshot(gz, targetDir, opts = {}) {
+    const target = path.resolve(targetDir);
+    const targetExists = existsSync(target);
+    if (targetExists) {
+        if (!lstatSync(target).isDirectory())
+            throw new SnapshotError(`${target} exists and is not a directory`, "not_empty");
+        if (readdirSync(target).length > 0 && !opts.force)
+            throw new SnapshotError(`${target} is not empty. Use --force to write into it anyway; files with the same names are replaced.`, "not_empty");
+    }
+    // Pass 1: the archive alone. Nothing exists on the disk yet for a bad archive, not even the target.
+    const plan = planExtraction(gz);
+    let createdTarget = false;
+    if (!targetExists) {
+        mkdirSync(target, { recursive: true });
+        createdTarget = true;
+    }
+    const realTarget = realpathSync(target);
+    const okDirs = new Set();
+    const written = [];
+    // Only a disk error during the write pass can reach this: pass 1 and the disk check refuse before any write.
+    const fail = (err) => {
+        try {
+            if (createdTarget)
+                rmSync(target, { recursive: true, force: true });
+            else
+                for (const f of written)
+                    rmSync(f, { force: true });
+        }
+        catch {
+            // best effort
+        }
+        throw err;
+    };
+    try {
+        // Pass 1, on the disk: still writes nothing.
+        checkDestinations(plan, target, realTarget, okDirs);
+        // Pass 2: write.
+        for (const step of plan.steps) {
+            const dest = path.resolve(target, ...step.segments);
+            if (step.kind === "dir") {
+                ensureInside(target, realTarget, dest, step.name, okDirs, true);
+                continue;
+            }
+            ensureInside(target, realTarget, path.dirname(dest), step.name, okDirs, true);
+            const existing = existingAt(dest);
+            // A link in a file's place is replaced, never written through.
+            if (existing?.isSymbolicLink())
+                unlinkSync(dest);
+            else if (existing && !existing.isFile())
+                throw new SnapshotError(`"${shown(step.name)}" exists as a folder; move it away first`, "invalid_snapshot");
+            writeFileSync(dest, step.data, { mode: step.mode });
+            if (process.platform !== "win32")
+                chmodSync(dest, step.mode);
+            written.push(dest);
+        }
+        return { files: plan.files, manifest: plan.manifest, dir: target };
+    }
+    catch (err) {
+        return fail(err);
+    }
+}
+/** The size on disk of a folder's selected files, for messages. */
+export function selectionBytes(selection) {
+    return selection.files.reduce((n, f) => n + f.size, 0);
+}