@nitpicker/archive 0.0.0-stage → 0.25.0

package/lib/filesystem/append-text.js

@@ -0,0 +1,14 @@
+import { promises as fs } from 'node:fs';
+import { mkdir } from './mkdir.js';
+/**
+ * Appends text data to a file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * A newline character is prepended to the data before appending.
+ * @param filePath - The absolute or relative path to the file to append to.
+ * @param data - The text content to append to the file.
+ */
+export async function appendText(filePath, data) {
+    mkdir(filePath);
+    await fs.appendFile(filePath, `\n${data}`, { encoding: 'utf8' });
+}

package/lib/filesystem/copy-dir-sync.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Synchronously copies a directory and its contents from one location to another.
+ * @param from - The source directory path to copy from.
+ * @param to - The destination directory path to copy to.
+ */
+export declare function copyDirSync(from: string, to: string): void;

package/lib/filesystem/copy-dir-sync.js

@@ -0,0 +1,9 @@
+import fsx from 'fs-extra';
+/**
+ * Synchronously copies a directory and its contents from one location to another.
+ * @param from - The source directory path to copy from.
+ * @param to - The destination directory path to copy to.
+ */
+export function copyDirSync(from, to) {
+    fsx.copySync(from, to);
+}

package/lib/filesystem/copy-dir.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Recursively copies a directory and its contents from one location to another.
+ * @param from - The source directory path to copy from.
+ * @param to - The destination directory path to copy to.
+ * @returns `true` if the copy succeeded, `false` if an error occurred.
+ */
+export declare function copyDir(from: string, to: string): Promise<boolean>;

package/lib/filesystem/copy-dir.js

@@ -0,0 +1,13 @@
+import fsx from 'fs-extra';
+/**
+ * Recursively copies a directory and its contents from one location to another.
+ * @param from - The source directory path to copy from.
+ * @param to - The destination directory path to copy to.
+ * @returns `true` if the copy succeeded, `false` if an error occurred.
+ */
+export async function copyDir(from, to) {
+    return fsx
+        .copy(from, to)
+        .then(() => true)
+        .catch(() => false);
+}

package/lib/filesystem/copy-file-with-progress.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copies a file while reporting byte progress — `fs.copyFile` offers no
+ * observability, and a `.nitpicker` archive's `.bak` safety copy (taken
+ * before every mutating `viewer-build`/`crawl --append`/`--inventory`/
+ * `--retry-failed` run, and copied back on failure) can be 15 GB+, running
+ * for tens of seconds with nothing on screen (issue #294). Byte granularity
+ * is the read-stream chunk size (~64 KB); callers wanting coarser updates
+ * throttle in their own callback.
+ * @param src - The file to copy.
+ * @param dest - The destination path, overwritten if present.
+ * @param onProgress - Called as bytes are copied, with the bytes copied so
+ *   far and the source file's total size. Omit for a silent copy.
+ * @example
+ * ```ts
+ * await copyFileWithProgress(archivePath, `${archivePath}.bak`, (copied, total) => {
+ *   console.error(`${copied}/${total}`);
+ * });
+ * ```
+ */
+export declare function copyFileWithProgress(src: string, dest: string, onProgress?: (copiedBytes: number, totalBytes: number) => void): Promise<void>;

package/lib/filesystem/copy-file-with-progress.js

@@ -0,0 +1,34 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+/**
+ * Copies a file while reporting byte progress — `fs.copyFile` offers no
+ * observability, and a `.nitpicker` archive's `.bak` safety copy (taken
+ * before every mutating `viewer-build`/`crawl --append`/`--inventory`/
+ * `--retry-failed` run, and copied back on failure) can be 15 GB+, running
+ * for tens of seconds with nothing on screen (issue #294). Byte granularity
+ * is the read-stream chunk size (~64 KB); callers wanting coarser updates
+ * throttle in their own callback.
+ * @param src - The file to copy.
+ * @param dest - The destination path, overwritten if present.
+ * @param onProgress - Called as bytes are copied, with the bytes copied so
+ *   far and the source file's total size. Omit for a silent copy.
+ * @example
+ * ```ts
+ * await copyFileWithProgress(archivePath, `${archivePath}.bak`, (copied, total) => {
+ *   console.error(`${copied}/${total}`);
+ * });
+ * ```
+ */
+export async function copyFileWithProgress(src, dest, onProgress) {
+    const { size: totalBytes } = await stat(src);
+    const source = createReadStream(src);
+    let copiedBytes = 0;
+    if (onProgress) {
+        source.on('data', (chunk) => {
+            copiedBytes += chunk.length;
+            onProgress(copiedBytes, totalBytes);
+        });
+    }
+    await pipeline(source, createWriteStream(dest));
+}

package/lib/filesystem/exists.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks whether a file or directory exists at the given path.
+ * @param filePath - The path to check for existence.
+ * @returns `true` if the path exists, `false` otherwise.
+ */
+export declare function exists(filePath: string): boolean;

package/lib/filesystem/exists.js

@@ -0,0 +1,9 @@
+import { existsSync } from 'node:fs';
+/**
+ * Checks whether a file or directory exists at the given path.
+ * @param filePath - The path to check for existence.
+ * @returns `true` if the path exists, `false` otherwise.
+ */
+export function exists(filePath) {
+    return existsSync(filePath);
+}

package/lib/filesystem/get-file-list.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Lists the file names in a directory, optionally filtered by a pattern.
+ * @param dirPath - The directory path to list files from.
+ * @param filter - An optional RegExp or string pattern to filter file names.
+ *   Only file names matching this pattern are included in the result.
+ * @returns An array of file names in the directory that match the filter (or all if no filter is provided).
+ */
+export declare function getFileList(dirPath: string, filter?: RegExp | string): Promise<string[]>;

package/lib/filesystem/get-file-list.js

@@ -0,0 +1,12 @@
+import fsx from 'fs-extra';
+/**
+ * Lists the file names in a directory, optionally filtered by a pattern.
+ * @param dirPath - The directory path to list files from.
+ * @param filter - An optional RegExp or string pattern to filter file names.
+ *   Only file names matching this pattern are included in the result.
+ * @returns An array of file names in the directory that match the filter (or all if no filter is provided).
+ */
+export async function getFileList(dirPath, filter) {
+    const list = await fsx.readdir(dirPath);
+    return filter ? list.filter((fileName) => fileName.match(filter)) : list;
+}

package/lib/filesystem/is-dir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks whether the given path points to a directory.
+ * @param dirPath - The path to check.
+ * @returns `true` if the path is a directory, `false` otherwise.
+ */
+export declare function isDir(dirPath: string): Promise<boolean>;

package/lib/filesystem/is-dir.js

@@ -0,0 +1,10 @@
+import fsx from 'fs-extra';
+/**
+ * Checks whether the given path points to a directory.
+ * @param dirPath - The path to check.
+ * @returns `true` if the path is a directory, `false` otherwise.
+ */
+export async function isDir(dirPath) {
+    const stat = await fsx.stat(dirPath);
+    return stat.isDirectory();
+}

package/lib/filesystem/mkdir.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Ensures the parent directory of the given file path exists.
+ *
+ * If the parent directory does not exist, it is created recursively
+ * with permissions `0o700` (owner-only access).
+ * @param filePath - The file path whose parent directory should be created.
+ */
+export declare function mkdir(filePath: string): void;

package/lib/filesystem/mkdir.js

@@ -0,0 +1,15 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Ensures the parent directory of the given file path exists.
+ *
+ * If the parent directory does not exist, it is created recursively
+ * with permissions `0o700` (owner-only access).
+ * @param filePath - The file path whose parent directory should be created.
+ */
+export function mkdir(filePath) {
+    const { dir } = path.parse(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(path.resolve(dir), { recursive: true, mode: 0o700 });
+    }
+}

package/lib/filesystem/output-binary.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Writes raw bytes to a file at the specified path, creating parent
+ * directories if needed.
+ *
+ * Unlike {@link outputText}, the buffer is written verbatim with no UTF-8
+ * re-encoding, so callers that need byte-for-byte fidelity (e.g. archiving
+ * a source file of unknown or mixed encoding for audit purposes) are not
+ * exposed to lossy round-tripping through a JS string.
+ * @param filePath - The absolute or relative path to the file to write.
+ * @param data - The raw bytes to write.
+ */
+export declare function outputBinary(filePath: string, data: Buffer): Promise<void>;

package/lib/filesystem/output-binary.js

@@ -0,0 +1,17 @@
+import { promises as fs } from 'node:fs';
+import { mkdir } from './mkdir.js';
+/**
+ * Writes raw bytes to a file at the specified path, creating parent
+ * directories if needed.
+ *
+ * Unlike {@link outputText}, the buffer is written verbatim with no UTF-8
+ * re-encoding, so callers that need byte-for-byte fidelity (e.g. archiving
+ * a source file of unknown or mixed encoding for audit purposes) are not
+ * exposed to lossy round-tripping through a JS string.
+ * @param filePath - The absolute or relative path to the file to write.
+ * @param data - The raw bytes to write.
+ */
+export async function outputBinary(filePath, data) {
+    mkdir(filePath);
+    await fs.writeFile(filePath, data);
+}

package/lib/filesystem/output-json.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Writes data to a JSON file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * The output is formatted with 2-space indentation.
+ * @param filePath - The absolute or relative path to the JSON file to write.
+ * @param data - The data to serialize as JSON and write to the file.
+ */
+export declare function outputJSON(filePath: string, data: unknown): Promise<void>;

package/lib/filesystem/output-json.js

@@ -0,0 +1,14 @@
+import { promises as fs } from 'node:fs';
+import { mkdir } from './mkdir.js';
+/**
+ * Writes data to a JSON file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * The output is formatted with 2-space indentation.
+ * @param filePath - The absolute or relative path to the JSON file to write.
+ * @param data - The data to serialize as JSON and write to the file.
+ */
+export async function outputJSON(filePath, data) {
+    mkdir(filePath);
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2), { encoding: 'utf8' });
+}

package/lib/filesystem/output-text.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Writes text data to a file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * If the file path exceeds the OS limit (ENAMETOOLONG), the file is saved
+ * with an auto-generated short name and an accompanying `.meta.txt` file
+ * that records the original file path.
+ * @param filePath - The absolute or relative path to the text file to write.
+ * @param data - The text content to write to the file.
+ */
+export declare function outputText(filePath: string, data: string): Promise<void>;

package/lib/filesystem/output-text.js

@@ -0,0 +1,32 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { mkdir } from './mkdir.js';
+let filePathTooLongCount = 0;
+/**
+ * Writes text data to a file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * If the file path exceeds the OS limit (ENAMETOOLONG), the file is saved
+ * with an auto-generated short name and an accompanying `.meta.txt` file
+ * that records the original file path.
+ * @param filePath - The absolute or relative path to the text file to write.
+ * @param data - The text content to write to the file.
+ */
+export async function outputText(filePath, data) {
+    mkdir(filePath);
+    await fs.writeFile(filePath, data, { encoding: 'utf8' }).catch(async (error) => {
+        if (error instanceof Error && 'code' in error && error.code === 'ENAMETOOLONG') {
+            // eslint-disable-next-line no-console
+            console.error(`File path too long: ${filePath}`);
+            const dir = path.dirname(filePath);
+            const altFileName = `__file_path_too_long_${(filePathTooLongCount++).toString().padStart(4, '0')}`;
+            const ext = path.extname(filePath);
+            const altFilePath = path.resolve(dir, `${altFileName}${ext}`);
+            // eslint-disable-next-line no-console
+            console.error(`Try to save to: ${altFilePath}`);
+            const altMetaFilePath = path.resolve(dir, `${altFileName}.meta.txt`);
+            await outputText(altFilePath, data);
+            await outputText(altMetaFilePath, `Original file path: ${filePath}`);
+        }
+    });
+}

package/lib/filesystem/parse-pax-path.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Parses a PAX extended header record block for the `path` key.
+ *
+ * Format: a sequence of `"<record-length> <key>=<value>\n"` records, where
+ * `<record-length>` is the decimal byte length of the ENTIRE record
+ * (including the length prefix itself and the trailing newline). `tar`
+ * (node-tar) emits one of these ahead of any entry whose name doesn't fit
+ * the ustar format's 100-byte field (UTF-8 multi-byte names, or names
+ * longer than 100 bytes) — verified empirically against this package's own
+ * `tar()`/`create()` output.
+ * @param data - The PAX header entry's raw data payload.
+ * @returns The `path` value if present, otherwise `null`.
+ * @example
+ * ```ts
+ * parsePaxPath(Buffer.from('20 path=日本語/\n', 'utf8')); // '日本語/'
+ * ```
+ */
+export declare function parsePaxPath(data: Buffer): string | null;

package/lib/filesystem/parse-pax-path.js

@@ -0,0 +1,47 @@
+/**
+ * Parses a PAX extended header record block for the `path` key.
+ *
+ * Format: a sequence of `"<record-length> <key>=<value>\n"` records, where
+ * `<record-length>` is the decimal byte length of the ENTIRE record
+ * (including the length prefix itself and the trailing newline). `tar`
+ * (node-tar) emits one of these ahead of any entry whose name doesn't fit
+ * the ustar format's 100-byte field (UTF-8 multi-byte names, or names
+ * longer than 100 bytes) — verified empirically against this package's own
+ * `tar()`/`create()` output.
+ * @param data - The PAX header entry's raw data payload.
+ * @returns The `path` value if present, otherwise `null`.
+ * @example
+ * ```ts
+ * parsePaxPath(Buffer.from('20 path=日本語/\n', 'utf8')); // '日本語/'
+ * ```
+ */
+export function parsePaxPath(data) {
+    let offset = 0;
+    while (offset < data.length) {
+        const spaceIndex = data.indexOf(0x20 /* ' ' */, offset);
+        if (spaceIndex === -1) {
+            return null;
+        }
+        const lengthText = data.subarray(offset, spaceIndex).toString('latin1');
+        const recordLength = Number.parseInt(lengthText, 10);
+        if (!Number.isFinite(recordLength) || recordLength <= 0) {
+            return null;
+        }
+        const recordEnd = offset + recordLength;
+        if (recordEnd > data.length) {
+            return null;
+        }
+        // Decimal (not `0x3D`) to sidestep the Prettier/eslint hex-case
+        // conflict — see `parse-tar-size-field.ts` for the full explanation.
+        const equalsIndex = data.indexOf(61 /* '=' */, spaceIndex);
+        if (equalsIndex !== -1 && equalsIndex < recordEnd) {
+            const key = data.subarray(spaceIndex + 1, equalsIndex).toString('utf8');
+            if (key === 'path') {
+                // Value runs from after '=' to just before the trailing '\n'.
+                return data.subarray(equalsIndex + 1, recordEnd - 1).toString('utf8');
+            }
+        }
+        offset = recordEnd;
+    }
+    return null;
+}

package/lib/filesystem/parse-tar-size-field.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parses a tar header's size field (offset 124, 12 bytes), which is either
+ * a NUL/space-terminated octal ASCII string (standard) or, when the
+ * high bit of the first byte is set, a GNU base-256 big-endian binary
+ * encoding (used for sizes too large for the 11-digit octal field).
+ * @param field - The 12-byte size field.
+ * @returns The size in bytes, or `null` if the field cannot be parsed.
+ * @example
+ * ```ts
+ * parseTarSizeField(Buffer.from('00000000004\0', 'latin1')); // 4
+ * ```
+ */
+export declare function parseTarSizeField(field: Buffer): number | null;

package/lib/filesystem/parse-tar-size-field.js

@@ -0,0 +1,40 @@
+/**
+ * Parses a tar header's size field (offset 124, 12 bytes), which is either
+ * a NUL/space-terminated octal ASCII string (standard) or, when the
+ * high bit of the first byte is set, a GNU base-256 big-endian binary
+ * encoding (used for sizes too large for the 11-digit octal field).
+ * @param field - The 12-byte size field.
+ * @returns The size in bytes, or `null` if the field cannot be parsed.
+ * @example
+ * ```ts
+ * parseTarSizeField(Buffer.from('00000000004\0', 'latin1')); // 4
+ * ```
+ */
+export function parseTarSizeField(field) {
+    const first = field[0];
+    if (first === undefined) {
+        return null;
+    }
+    if ((first & 0x80) !== 0) {
+        // GNU base-256: the remaining bits of the first byte plus all
+        // following bytes form a big-endian unsigned integer. `.nitpicker`
+        // tars never approach sizes needing this (single-digit-terabyte
+        // range before it would even matter), but a correct read here still
+        // costs nothing.
+        // `0b0111_1111` (not `0x7F`) to sidestep the Prettier/eslint hex-case
+        // conflict (Prettier always lowercases hex digits; this repo's
+        // `unicorn/number-literal-case` requires uppercase) — a binary literal
+        // has no letter digits to disagree about.
+        let value = BigInt(first & 0b0111_1111);
+        for (let i = 1; i < field.length; i++) {
+            value = (value << 8n) | BigInt(field[i] ?? 0);
+        }
+        return Number(value);
+    }
+    const text = field.toString('latin1').replaceAll('\0', ' ').trim();
+    if (text === '') {
+        return 0;
+    }
+    const parsed = Number.parseInt(text, 8);
+    return Number.isNaN(parsed) ? null : parsed;
+}

package/lib/filesystem/peek-tar-top-dir.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reads the top-level directory name from a `.nitpicker` tar archive.
+ *
+ * Why: a `.nitpicker` is a tar that wraps `<basename>/db.sqlite` (and
+ * historically other files). `Archive.write()` names the inner directory
+ * from the file's basename at write time, but users routinely rename
+ * `.nitpicker` files after the fact (e.g. `mv X.migrated.nitpicker
+ * X.nitpicker`) — a perfectly reasonable filesystem operation that breaks
+ * any code that recomputes the inner-dir name from the outer filename.
+ *
+ * This helper scans the tar's entry list and returns the first top-level
+ * directory it sees, so callers (`Archive.open`, the migration script) can
+ * use the actual inner name regardless of what the outer file is called.
+ *
+ * Parses raw tar headers directly (ustar fixed fields, PAX extended headers,
+ * GNU longname/longlink) instead of using the `tar` package's `list()` —
+ * `list()` reads the entire archive stream to completion even after
+ * `onReadEntry` has found what it needs (no internal early-abort), so on a
+ * 15 GB+ archive it was a second full read on top of `untar()`'s own read
+ * (issue #294). The fast path here stops at the first top-level directory
+ * entry, typically reading well under 1 KB. Falls back to the original
+ * `list()`-based scan on anything it doesn't recognize (unknown typeflag
+ * sequence, truncated read, non-tar content) — safety over speed for
+ * archives this function has never been exercised against.
+ * @param tarFilePath - Path to the `.nitpicker` tar file.
+ * @returns The first top-level directory name found in the archive.
+ * @throws {Error} When the tar contains no top-level directory entry
+ *   (e.g. file is empty, corrupted, or non-tar). The error message
+ *   identifies the path for diagnostics.
+ * @example
+ * // The user renamed `original.nitpicker` to `renamed.nitpicker`. The
+ * // inner directory was baked in at write time and is unaffected:
+ * await peekTarTopDir('renamed.nitpicker'); // → 'original'
+ */
+export declare function peekTarTopDir(tarFilePath: string): Promise<string>;