nerdsystem 0.0.11 → 0.0.13

package/dist/gates/text.js

@@ -150,3 +150,111 @@ export function cvss3BaseScore(vector) {
     const roundUp = (x) => Math.ceil(x * 10 - 1e-9) / 10;
     return scopeChanged ? roundUp(Math.min(1.08 * (impact + exploitability), 10)) : roundUp(Math.min(impact + exploitability, 10));
 }
+/*
+ * Source snapshots (docs/source-snapshots.md). The CLI packs them, the control plane validates
+ * them while streaming, and both read the lists below, so a rule added here holds on both sides.
+ */
+/** Name of the first entry in every snapshot tar. */
+export const SNAPSHOT_MANIFEST = ".nerd-snapshot.json";
+/** Most files one snapshot may hold. */
+export const MAX_SOURCE_FILES = 20_000;
+/** Largest compressed snapshot accepted, in bytes (25 MB). */
+export const MAX_SOURCE_BYTES = 25 * 1024 * 1024;
+/** Largest uncompressed tar stream accepted, in bytes (200 MB). */
+export const MAX_SOURCE_UNPACKED = 200 * 1024 * 1024;
+/** A single file over this is left out of the snapshot with a warning (50 MB). */
+export const MAX_SNAPSHOT_FILE_BYTES = 50 * 1024 * 1024;
+/** A PAX or GNU long-name header larger than this is refused; real ones are a few hundred bytes. */
+export const MAX_SNAPSHOT_HEADER_BYTES = 1024 * 1024;
+/** Longest entry name accepted, in UTF-16 code units. */
+export const MAX_SNAPSHOT_NAME_LENGTH = 4096;
+/**
+ * Never in a snapshot, whatever git or the include list says: repository internals, build output,
+ * caches, local databases, env files, keys, package-manager credentials, and agent chat history.
+ * Matched against the posix path relative to the app root at any depth.
+ */
+export const SNAPSHOT_EXCLUDE = [
+    /(^|\/)(\.git|node_modules|dist|\.wrangler|\.vite|coverage|\.nerd|\.turbo|\.cache|\.aws|\.ssh|\.specstory)(\/|$)/,
+    /(^|\/)\.aider[^/]*(\/|$)/,
+    /(^|\/)(\.DS_Store|Thumbs\.db|\.npmrc|\.yarnrc\.yml|\.netrc)$/i,
+    ENV_FILES,
+    /\.(pem|key|p12|pfx|jks|keystore|sqlite|sqlite3|db|db-journal|log)$/i,
+    /(^|\/)(id_rsa|id_ed25519)[^/]*$/,
+    /(^|\/)\.claude\/settings\.local\.json$/,
+    /^\.nerd-snapshot\.json$/,
+];
+export function isSnapshotExcluded(posixPath) {
+    return SNAPSHOT_EXCLUDE.some((re) => re.test(posixPath));
+}
+/** Directories at the app root whose whole tree a rebuild needs even when .gitignore hides it. */
+export const SNAPSHOT_INCLUDE_DIRS = ["migrations", "src", "public", ".claude", ".cursor", ".github"];
+/**
+ * Files a rebuild needs; when .gitignore hides one it still goes into the snapshot, with a warning.
+ * Root-level config files and the trees in SNAPSHOT_INCLUDE_DIRS. The hard exclude still wins.
+ */
+export const SNAPSHOT_INCLUDE = [
+    /^(package\.json|pnpm-lock\.yaml|package-lock\.json|yarn\.lock|nerd\.json|wrangler\.json[^/]*|vite\.config\.[^/]+|tsconfig[^/]*\.json|drizzle\.config\.[^/]+|index\.html|CLAUDE\.md|AGENTS\.md|GEMINI\.md|\.mcp\.json|README\.md|\.gitignore)$/,
+    new RegExp(`^(${SNAPSHOT_INCLUDE_DIRS.map((d) => d.replace(/\./g, "\\.")).join("|")})/`),
+];
+export function isSnapshotForced(posixPath) {
+    return !isSnapshotExcluded(posixPath) && SNAPSHOT_INCLUDE.some((re) => re.test(posixPath));
+}
+/** True when an ignored directory may hold forced files, so a walker should still descend into it. */
+export function isSnapshotForcedDir(posixDir) {
+    const dir = posixDir.replace(/\/+$/, "");
+    if (dir === "" || isSnapshotExcluded(`${dir}/`))
+        return false;
+    return SNAPSHOT_INCLUDE_DIRS.some((d) => dir === d || dir.startsWith(`${d}/`));
+}
+/** The warning printed for every ignored file the snapshot keeps anyway. */
+export function snapshotForcedWarning(posixPath) {
+    return `\`${posixPath}\` is in .gitignore but a rebuild needs it; it is in the saved copy`;
+}
+/** Tar entry types a snapshot may hold: regular files, directories, PAX headers, GNU long names. */
+export const SNAPSHOT_ENTRY_TYPES = new Set(["0", "\0", "5", "x", "L"]);
+const TYPE_NAMES = { "1": "hard link", "2": "symbolic link", "3": "character device", "4": "block device", "6": "fifo", "7": "contiguous file", g: "global PAX header", K: "GNU long link", S: "sparse file" };
+function shortName(name) {
+    const clean = name.replace(/[^\x20-\x7e]/g, "?");
+    return clean.length > 120 ? `${clean.slice(0, 117)}...` : clean;
+}
+/**
+ * Checks one tar entry against the snapshot rules. Returns null when it passes, else a short reason.
+ * The same check runs on the control plane while the upload streams and in the CLI before a file
+ * is written on restore. `type` is the one-character typeflag ("" counts as "\0").
+ */
+export function validateSnapshotEntry(entry) {
+    const type = entry.type === "" ? "\0" : entry.type;
+    const name = entry.name;
+    if (!SNAPSHOT_ENTRY_TYPES.has(type)) {
+        const what = TYPE_NAMES[type] ?? `type ${JSON.stringify(type)}`;
+        return `entry "${shortName(name)}" is a ${what}; only regular files are allowed`;
+    }
+    if (!Number.isSafeInteger(entry.size) || entry.size < 0)
+        return `entry "${shortName(name)}" has an invalid size`;
+    if ((type === "0" || type === "\0") && entry.size > MAX_SNAPSHOT_FILE_BYTES)
+        return `entry "${shortName(name)}" is larger than ${MAX_SNAPSHOT_FILE_BYTES / (1024 * 1024)} MB`;
+    if ((type === "x" || type === "L") && entry.size > MAX_SNAPSHOT_HEADER_BYTES)
+        return `entry "${shortName(name)}" has an oversized ${type === "x" ? "PAX" : "long-name"} header`;
+    if (name.length === 0)
+        return "an entry has no name";
+    if (name.length > MAX_SNAPSHOT_NAME_LENGTH)
+        return `entry "${shortName(name)}" has a name longer than ${MAX_SNAPSHOT_NAME_LENGTH} characters`;
+    if (name.includes("\0"))
+        return `entry "${shortName(name)}" has a NUL byte in its name`;
+    if (name.includes("\\"))
+        return `entry "${shortName(name)}" has a backslash in its name; paths must use /`;
+    if (name.startsWith("/"))
+        return `entry "${shortName(name)}" is an absolute path`;
+    const relative = type === "5" && name.endsWith("/") ? name.slice(0, -1) : name;
+    for (const segment of relative.split("/")) {
+        if (segment === "")
+            return `entry "${shortName(name)}" has an empty path segment`;
+        if (segment === ".")
+            return `entry "${shortName(name)}" has a "." path segment`;
+        if (segment === "..")
+            return `entry "${shortName(name)}" has a ".." path segment`;
+        if (segment === ".git")
+            return `entry "${shortName(name)}" is inside a .git directory`;
+    }
+    return null;
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,161 @@
+import { type SnapshotManifest } from "./gates/text.js";
+export { MAX_SNAPSHOT_FILE_BYTES, MAX_SOURCE_BYTES, MAX_SOURCE_FILES, MAX_SOURCE_UNPACKED, SNAPSHOT_MANIFEST, validateSnapshotEntry, type SnapshotFile, type SnapshotManifest } from "./gates/text.js";
+export type SnapshotErrorCode = "invalid_snapshot" | "not_empty" | "changed" | "too_large";
+export declare class SnapshotError extends Error {
+    readonly code: SnapshotErrorCode;
+    constructor(message: string, code: SnapshotErrorCode);
+}
+export declare function formatMb(bytes: number): string;
+export interface SnapshotCandidate {
+    /** Posix path relative to the root. */
+    path: string;
+    abs: string;
+    size: number;
+    /** 0o644 or 0o755. */
+    mode: number;
+}
+export interface SkippedFile {
+    path: string;
+    size: number;
+    reason: string;
+}
+export interface SnapshotSelection {
+    files: SnapshotCandidate[];
+    warnings: string[];
+    skipped: SkippedFile[];
+    /** Ignored files a rebuild needs that were kept anyway (every one; `warnings` folds past 20). */
+    forced: string[];
+    /** Where the candidate list came from. */
+    listedBy: "git" | "walk";
+}
+export interface ListOptions {
+    /** Set false to skip git and use the filesystem walker (tests). Default true. */
+    useGit?: boolean;
+}
+/** `{ sha, branch }` of the checkout at `root`, or null when there is no git, no repo, or no commit yet. */
+export declare function gitInfo(root: string): {
+    sha: string;
+    branch: string;
+} | null;
+interface IgnoreRule {
+    re: RegExp;
+    dirOnly: boolean;
+}
+export declare function parseGitignore(text: string, baseRel: string): IgnoreRule[];
+/**
+ * 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 declare function listSnapshotFiles(root: string, opts?: ListOptions): SnapshotSelection;
+export interface RawTarEntry {
+    name: string;
+    type: string;
+    data?: Buffer;
+    mode?: number;
+    linkname?: string;
+    /** Written into the ustar prefix field (tests only). */
+    prefix?: string;
+}
+/** The bytes of one entry: an optional PAX header for a long path, the ustar header, data, padding. */
+export declare function tarEntryBytes(e: RawTarEntry): Buffer[];
+/** A whole tar from raw entries, in the given order, with the two end blocks. Tests build hostile tars with it. */
+export declare function buildTar(entries: RawTarEntry[]): Buffer;
+/** gzip level 6 with a fixed header (mtime 0, OS byte 3) so the same tar always gives the same bytes. */
+export declare function gzipDeterministic(chunks: AsyncIterable<Buffer> | Iterable<Buffer>, maxBytes?: number): Promise<Buffer>;
+export interface PackOptions extends ListOptions {
+    /** CLI version written into the manifest. */
+    cli?: string;
+    /** Git provenance for the manifest; omitted means "detect from root", null means none. */
+    git?: {
+        sha: string;
+        branch: string;
+    } | null;
+    /** Manifest timestamp; defaults to now. Tests pin it so two packs give the same bytes. */
+    createdAt?: string;
+    node?: string;
+}
+export interface TooLarge {
+    /** Which cap was hit. */
+    reason: "files" | "unpacked" | "compressed";
+    /** Size of the selected files on disk. */
+    bytes: number;
+    fileCount: number;
+    /** The five largest selected files, biggest first. */
+    largest: {
+        path: string;
+        size: number;
+    }[];
+    /** The sentence the CLI prints. */
+    message: string;
+}
+export interface PackBase {
+    fileCount: number;
+    manifest: SnapshotManifest;
+    warnings: string[];
+    skipped: SkippedFile[];
+    forced: string[];
+    listedBy: "git" | "walk";
+}
+export interface PackOk extends PackBase {
+    gz: Buffer;
+    /** Hex sha256 of `gz`, what the API stores and verifies. */
+    sha256: string;
+    /** Hex sha256 of the uncompressed tar minus the manifest entry: the dedup key. */
+    treeHash: string;
+    /** Compressed size. */
+    bytes: number;
+    /** Uncompressed tar size. */
+    tarBytes: number;
+    tooLarge?: undefined;
+}
+export interface PackTooLarge extends PackBase {
+    gz?: undefined;
+    sha256?: undefined;
+    treeHash?: undefined;
+    /** Size of the selected files on disk. */
+    bytes: number;
+    tarBytes: number;
+    tooLarge: TooLarge;
+}
+export type PackResult = PackOk | PackTooLarge;
+/**
+ * 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 declare function packSnapshot(root: string, opts?: PackOptions): Promise<PackResult>;
+interface ParsedEntry {
+    name: string;
+    type: string;
+    size: number;
+    mode: number;
+    data: Buffer;
+}
+/** Raw entries in order; PAX and long-name headers are yielded as entries and resolved by the caller. */
+export declare function parseTar(tar: Buffer): Generator<ParsedEntry>;
+/** Uncompresses a snapshot with the unpacked cap enforced. */
+export declare function gunzipSnapshot(gz: Buffer): Buffer;
+/** The manifest alone, for callers that only need the file list. */
+export declare function readSnapshotManifest(gz: Buffer): SnapshotManifest;
+export interface ExtractOptions {
+    /** Write into a directory that already has files in it. */
+    force?: boolean;
+}
+export interface ExtractResult {
+    /** Regular files written. */
+    files: number;
+    manifest: SnapshotManifest;
+    dir: string;
+}
+/**
+ * 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 declare function extractSnapshot(gz: Buffer, targetDir: string, opts?: ExtractOptions): ExtractResult;
+/** The size on disk of a folder's selected files, for messages. */
+export declare function selectionBytes(selection: SnapshotSelection): number;