nerdsystem 0.0.11 → 0.0.12

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;