@mhalle/vost 0.8.1

package/dist/fs.d.ts

@@ -0,0 +1,581 @@
+/**
+ * FS: immutable snapshot of a committed tree state.
+ *
+ * Read-only when writable is false (tag/detached snapshot).
+ * Writable when writable is true — writes auto-commit and return a new FS.
+ */
+import { type FsModule, type FileType, type WalkEntry, type WriteEntry, type ChangeReport, type CommitInfo, type StatResult } from './types.js';
+import { type TreeWrite } from './tree.js';
+import { Batch } from './batch.js';
+import { FsWriter } from './fileobj.js';
+import type { GitStore } from './gitstore.js';
+/**
+ * An immutable snapshot of a committed tree.
+ *
+ * Read-only when `writable` is false (tag snapshot).
+ * Writable when `writable` is true -- writes auto-commit and return a new FS.
+ */
+export declare class FS {
+    /** @internal */
+    _store: GitStore;
+    /** @internal */
+    _commitOid: string;
+    /** @internal */
+    _refName: string | null;
+    /** @internal */
+    _writable: boolean;
+    /** @internal */
+    _treeOid: string;
+    /** @internal */
+    _changes: ChangeReport | null;
+    /** @internal */
+    _commitTime: number | null;
+    /** @internal */
+    get _fsModule(): FsModule;
+    /** @internal */
+    get _gitdir(): string;
+    constructor(store: GitStore, commitOid: string, treeOid: string, refName: string | null, writable?: boolean);
+    /**
+     * @internal Create an FS from a commit OID (reads the commit to get tree OID).
+     */
+    static _fromCommit(store: GitStore, commitOid: string, refName: string | null, writable?: boolean): Promise<FS>;
+    toString(): string;
+    /** @internal */
+    private _readonlyError;
+    /** The 40-character hex SHA of this snapshot's commit. */
+    get commitHash(): string;
+    /** The branch or tag name, or `null` for detached snapshots. */
+    get refName(): string | null;
+    /** Whether this snapshot can be written to. */
+    get writable(): boolean;
+    /**
+     * Fetch commit metadata (message, time, author name/email) in a single read.
+     *
+     * @returns Commit info object with message, time, authorName, and authorEmail.
+     */
+    getCommitInfo(): Promise<CommitInfo>;
+    /** The commit message (trailing newline stripped). */
+    getMessage(): Promise<string>;
+    /** Timezone-aware commit timestamp. */
+    getTime(): Promise<Date>;
+    /** The commit author's name. */
+    getAuthorName(): Promise<string>;
+    /** The commit author's email address. */
+    getAuthorEmail(): Promise<string>;
+    /** Report of the operation that created this snapshot, or `null`. */
+    get changes(): ChangeReport | null;
+    /** The 40-char hex SHA of the root tree. */
+    get treeHash(): string;
+    /** @internal */
+    _getCommitTime(): Promise<number>;
+    /**
+     * Read file contents as bytes.
+     *
+     * @param path - File path in the repo.
+     * @param opts - Optional read options.
+     * @param opts.offset - Byte offset to start reading from.
+     * @param opts.size - Maximum bytes to return (undefined for all).
+     * @returns Raw file contents as Uint8Array.
+     * @throws {FileNotFoundError} If path does not exist.
+     * @throws {IsADirectoryError} If path is a directory.
+     */
+    read(path: string, opts?: {
+        offset?: number;
+        size?: number;
+    }): Promise<Uint8Array>;
+    /**
+     * Read file contents as a string.
+     *
+     * @param path - File path in the repo.
+     * @param encoding - Text encoding (default `"utf-8"`).
+     * @returns Decoded text content.
+     * @throws {FileNotFoundError} If path does not exist.
+     * @throws {IsADirectoryError} If path is a directory.
+     */
+    readText(path: string, encoding?: string): Promise<string>;
+    /**
+     * List entry names at path (or root if null/undefined).
+     *
+     * @param path - Directory path, or null/undefined for the repo root.
+     * @returns Array of entry names (files and subdirectories).
+     * @throws {NotADirectoryError} If path is a file.
+     */
+    ls(path?: string | null): Promise<string[]>;
+    /**
+     * Walk the repo tree recursively, like `os.walk`.
+     *
+     * Yields `[dirpath, dirnames, fileEntries]` tuples. Each file entry is a
+     * WalkEntry with `name`, `oid`, and `mode`.
+     *
+     * @param path - Subtree to walk, or null/undefined for root.
+     * @throws {NotADirectoryError} If path is a file.
+     */
+    walk(path?: string | null): AsyncGenerator<[string, string[], WalkEntry[]]>;
+    /**
+     * Return true if path exists (file or directory).
+     *
+     * @param path - Path to check.
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Return true if path is a directory (tree) in the repo.
+     *
+     * @param path - Path to check.
+     */
+    isDir(path: string): Promise<boolean>;
+    /**
+     * Return the FileType of path.
+     *
+     * Returns `'blob'`, `'executable'`, `'link'`, or `'tree'`.
+     *
+     * @param path - Path to check.
+     * @throws {FileNotFoundError} If path does not exist.
+     */
+    fileType(path: string): Promise<FileType>;
+    /**
+     * Return the size in bytes of the object at path.
+     *
+     * @param path - Path to check.
+     * @returns Size in bytes.
+     * @throws {FileNotFoundError} If path does not exist.
+     */
+    size(path: string): Promise<number>;
+    /**
+     * Return the 40-character hex SHA of the object at path.
+     *
+     * For files this is the blob SHA; for directories the tree SHA.
+     *
+     * @param path - Path to check.
+     * @returns 40-char hex SHA string.
+     * @throws {FileNotFoundError} If path does not exist.
+     */
+    objectHash(path: string): Promise<string>;
+    /**
+     * Read the target of a symlink.
+     *
+     * @param path - Symlink path in the repo.
+     * @returns The symlink target string.
+     * @throws {FileNotFoundError} If path does not exist.
+     * @throws {Error} If path is not a symlink.
+     */
+    readlink(path: string): Promise<string>;
+    /**
+     * Read raw blob data by hash, bypassing tree lookup.
+     *
+     * FUSE pattern: `stat()` -> cache hash -> `readByHash(hash)`.
+     *
+     * @param hash - 40-char hex SHA of the blob.
+     * @param opts - Optional read options.
+     * @param opts.offset - Byte offset to start reading from.
+     * @param opts.size - Maximum bytes to return (undefined for all).
+     * @returns Raw blob contents as Uint8Array.
+     */
+    readByHash(hash: string, opts?: {
+        offset?: number;
+        size?: number;
+    }): Promise<Uint8Array>;
+    /**
+     * Return a StatResult for path (or root if null/undefined).
+     *
+     * Combines fileType, size, oid, nlink, and mtime in a single call --
+     * the hot path for FUSE `getattr`.
+     *
+     * @param path - Path to stat, or null/undefined for root.
+     * @returns StatResult with mode, fileType, size, hash, nlink, and mtime.
+     * @throws {FileNotFoundError} If path does not exist.
+     */
+    stat(path?: string | null): Promise<StatResult>;
+    /**
+     * List directory entries with name, oid, and mode.
+     *
+     * Like `ls()` but returns WalkEntry objects so callers get entry types
+     * (useful for FUSE `readdir` d_type).
+     *
+     * @param path - Directory path, or null/undefined for root.
+     * @returns Array of WalkEntry objects.
+     */
+    listdir(path?: string | null): Promise<WalkEntry[]>;
+    /**
+     * Expand a glob pattern against the repo tree.
+     *
+     * Supports `*`, `?`, and `**`. `*` and `?` do not match a leading `.`
+     * unless the pattern segment itself starts with `.`. `**` matches zero or
+     * more directory levels, skipping directories whose names start with `.`.
+     *
+     * @param pattern - Glob pattern to match.
+     * @returns Sorted, deduplicated list of matching paths (files and directories).
+     */
+    glob(pattern: string): Promise<string[]>;
+    /**
+     * Expand a glob pattern against the repo tree, yielding unique matches.
+     *
+     * Like `glob()` but returns an unordered async iterator instead of a
+     * sorted list. Useful when you only need to iterate once and don't
+     * need sorted output.
+     *
+     * A `/./` pivot marker (rsync `-R` style) is preserved in the output
+     * so that callers can reconstruct partial source paths.
+     *
+     * @param pattern - Glob pattern to match.
+     */
+    iglob(pattern: string): AsyncGenerator<string>;
+    /** @internal */
+    private _iglobEntries;
+    /** @internal */
+    private _iglobWalk;
+    /** @internal */
+    private _iglobMatchEntries;
+    /**
+     * @internal Build ChangeReport from writes and removes with type detection.
+     */
+    _buildChanges(writes: Map<string, TreeWrite>, removes: Set<string>): Promise<ChangeReport>;
+    /**
+     * @internal Commit changes: rebuild tree, create commit, update ref atomically.
+     */
+    _commitChanges(writes: Map<string, TreeWrite>, removes: Set<string>, message?: string | null, operation?: string | null): Promise<FS>;
+    /**
+     * Write data to path and commit, returning a new FS.
+     *
+     * @param path - Destination path in the repo.
+     * @param data - Raw bytes to write.
+     * @param opts - Optional write options.
+     * @param opts.message - Commit message (auto-generated if omitted).
+     * @param opts.mode - File mode override (e.g. `'executable'`).
+     * @returns New FS snapshot with the write committed.
+     * @throws {PermissionError} If this snapshot is read-only.
+     * @throws {StaleSnapshotError} If the branch has advanced since this snapshot.
+     */
+    write(path: string, data: Uint8Array, opts?: {
+        message?: string;
+        mode?: FileType | string;
+    }): Promise<FS>;
+    /**
+     * Write text to path and commit, returning a new FS.
+     *
+     * @param path - Destination path in the repo.
+     * @param text - String content (encoded as UTF-8).
+     * @param opts - Optional write options.
+     * @param opts.message - Commit message (auto-generated if omitted).
+     * @param opts.mode - File mode override (e.g. `'executable'`).
+     * @returns New FS snapshot with the write committed.
+     * @throws {PermissionError} If this snapshot is read-only.
+     * @throws {StaleSnapshotError} If the branch has advanced since this snapshot.
+     */
+    writeText(path: string, text: string, opts?: {
+        message?: string;
+        mode?: FileType | string;
+    }): Promise<FS>;
+    /**
+     * Write a local file into the repo and commit, returning a new FS.
+     *
+     * Executable permission is auto-detected from disk unless `mode` is set.
+     *
+     * @param path - Destination path in the repo.
+     * @param localPath - Path to the local file.
+     * @param opts - Optional write options.
+     * @param opts.message - Commit message (auto-generated if omitted).
+     * @param opts.mode - File mode override (e.g. `'executable'`).
+     * @returns New FS snapshot with the write committed.
+     * @throws {PermissionError} If this snapshot is read-only.
+     * @throws {StaleSnapshotError} If the branch has advanced since this snapshot.
+     */
+    writeFromFile(path: string, localPath: string, opts?: {
+        message?: string;
+        mode?: FileType | string;
+    }): Promise<FS>;
+    /**
+     * Create a symbolic link entry and commit, returning a new FS.
+     *
+     * @param path - Symlink path in the repo.
+     * @param target - The symlink target string.
+     * @param opts - Optional write options.
+     * @param opts.message - Commit message (auto-generated if omitted).
+     * @returns New FS snapshot with the symlink committed.
+     * @throws {PermissionError} If this snapshot is read-only.
+     * @throws {StaleSnapshotError} If the branch has advanced since this snapshot.
+     */
+    writeSymlink(path: string, target: string, opts?: {
+        message?: string;
+    }): Promise<FS>;
+    /**
+     * Apply multiple writes and removes in a single atomic commit.
+     *
+     * `writes` maps repo paths to content. Values may be:
+     * - `Uint8Array` -- raw blob data
+     * - `string` -- UTF-8 text (encoded automatically)
+     * - `WriteEntry` -- full control over source, mode, and symlinks
+     *
+     * `removes` lists repo paths to delete (string, array, or Set).
+     *
+     * @param writes - Map of repo paths to content.
+     * @param removes - Path(s) to delete.
+     * @param opts - Optional apply options.
+     * @param opts.message - Commit message (auto-generated if omitted).
+     * @param opts.operation - Operation name for auto-generated messages.
+     * @returns New FS snapshot with the changes committed.
+     * @throws {PermissionError} If this snapshot is read-only.
+     * @throws {StaleSnapshotError} If the branch has advanced since this snapshot.
+     */
+    apply(writes?: Record<string, WriteEntry | Uint8Array | string> | null, removes?: string | string[] | Set<string> | null, opts?: {
+        message?: string;
+        operation?: string;
+    }): Promise<FS>;
+    /**
+     * Return a Batch for accumulating multiple writes in one commit.
+     *
+     * @param opts - Optional batch options.
+     * @param opts.message - Commit message (auto-generated if omitted).
+     * @param opts.operation - Operation name for auto-generated messages.
+     * @returns A Batch instance. Call `batch.commit()` to finalize.
+     * @throws {PermissionError} If this snapshot is read-only.
+     */
+    batch(opts?: {
+        message?: string;
+        operation?: string;
+    }): Batch;
+    /**
+     * Return a buffered writer that commits on close.
+     *
+     * Accepts `Uint8Array` or `string` via `write()`. Strings are UTF-8 encoded.
+     *
+     * @param path - Destination path in the repo.
+     * @returns An FsWriter instance. Call `close()` to flush and commit.
+     * @throws {PermissionError} If this snapshot is read-only.
+     */
+    writer(path: string): FsWriter;
+    /**
+     * Copy local files into the repo.
+     *
+     * Sources must be literal paths; use `diskGlob()` to expand patterns
+     * before calling.
+     *
+     * @param sources - Local path(s). Trailing `/` copies contents; `/./` is a pivot marker.
+     * @param dest - Destination path in the repo.
+     * @param opts - Copy-in options.
+     * @param opts.dryRun - Preview only; returned FS has `.changes` set.
+     * @param opts.followSymlinks - Dereference symlinks on disk.
+     * @param opts.message - Commit message (auto-generated if omitted).
+     * @param opts.mode - Override file mode for all files.
+     * @param opts.ignoreExisting - Skip files that already exist at dest.
+     * @param opts.delete - Remove repo files under dest not in source.
+     * @param opts.ignoreErrors - Collect errors instead of aborting.
+     * @param opts.checksum - Compare by content hash (default true).
+     * @returns New FS with `.changes` set.
+     * @throws {PermissionError} If this snapshot is read-only.
+     */
+    copyIn(sources: string | string[], dest: string, opts?: {
+        dryRun?: boolean;
+        followSymlinks?: boolean;
+        message?: string;
+        mode?: string;
+        ignoreExisting?: boolean;
+        delete?: boolean;
+        ignoreErrors?: boolean;
+        checksum?: boolean;
+        exclude?: import('./exclude.js').ExcludeFilter;
+    }): Promise<FS>;
+    /**
+     * Copy repo files to local disk.
+     *
+     * Sources must be literal repo paths; use `glob()` to expand patterns
+     * before calling.
+     *
+     * @param sources - Repo path(s). Trailing `/` copies contents; `/./` is a pivot marker.
+     * @param dest - Local destination directory.
+     * @param opts - Copy-out options.
+     * @param opts.dryRun - Preview only; returned FS has `.changes` set.
+     * @param opts.ignoreExisting - Skip files that already exist at dest.
+     * @param opts.delete - Remove local files under dest not in source.
+     * @param opts.ignoreErrors - Collect errors instead of aborting.
+     * @param opts.checksum - Compare by content hash (default true).
+     * @returns This FS with `.changes` set.
+     */
+    copyOut(sources: string | string[], dest: string, opts?: {
+        dryRun?: boolean;
+        ignoreExisting?: boolean;
+        delete?: boolean;
+        ignoreErrors?: boolean;
+        checksum?: boolean;
+    }): Promise<FS>;
+    /**
+     * Make repoPath identical to localPath (including deletes).
+     *
+     * @param localPath - Local directory to sync from.
+     * @param repoPath - Repo directory to sync to.
+     * @param opts - Sync-in options.
+     * @param opts.dryRun - Preview only; returned FS has `.changes` set.
+     * @param opts.message - Commit message (auto-generated if omitted).
+     * @param opts.ignoreErrors - Collect errors instead of aborting.
+     * @param opts.checksum - Compare by content hash (default true).
+     * @returns New FS with `.changes` set.
+     * @throws {PermissionError} If this snapshot is read-only.
+     */
+    syncIn(localPath: string, repoPath: string, opts?: {
+        dryRun?: boolean;
+        message?: string;
+        ignoreErrors?: boolean;
+        checksum?: boolean;
+        exclude?: import('./exclude.js').ExcludeFilter;
+    }): Promise<FS>;
+    /**
+     * Make localPath identical to repoPath (including deletes).
+     *
+     * @param repoPath - Repo directory to sync from.
+     * @param localPath - Local directory to sync to.
+     * @param opts - Sync-out options.
+     * @param opts.dryRun - Preview only; returned FS has `.changes` set.
+     * @param opts.ignoreErrors - Collect errors instead of aborting.
+     * @param opts.checksum - Compare by content hash (default true).
+     * @returns This FS with `.changes` set.
+     */
+    syncOut(repoPath: string, localPath: string, opts?: {
+        dryRun?: boolean;
+        ignoreErrors?: boolean;
+        checksum?: boolean;
+    }): Promise<FS>;
+    /**
+     * Remove files from the repo.
+     *
+     * Sources must be literal paths; use `glob()` to expand patterns before calling.
+     *
+     * @param sources - Repo path(s) to remove.
+     * @param opts - Remove options.
+     * @param opts.recursive - Allow removing directories.
+     * @param opts.dryRun - Preview only; returned FS has `.changes` set.
+     * @param opts.message - Commit message (auto-generated if omitted).
+     * @returns New FS with `.changes` set.
+     * @throws {PermissionError} If this snapshot is read-only.
+     * @throws {FileNotFoundError} If no source paths match.
+     */
+    remove(sources: string | string[], opts?: {
+        recursive?: boolean;
+        dryRun?: boolean;
+        message?: string;
+    }): Promise<FS>;
+    /**
+     * Move or rename files within the repo.
+     *
+     * Sources must be literal paths; use `glob()` to expand patterns before calling.
+     *
+     * @param sources - Repo path(s) to move.
+     * @param dest - Destination path in the repo.
+     * @param opts - Move options.
+     * @param opts.recursive - Allow moving directories.
+     * @param opts.dryRun - Preview only; returned FS has `.changes` set.
+     * @param opts.message - Commit message (auto-generated if omitted).
+     * @returns New FS with `.changes` set.
+     * @throws {PermissionError} If this snapshot is read-only.
+     */
+    move(sources: string | string[], dest: string, opts?: {
+        recursive?: boolean;
+        dryRun?: boolean;
+        message?: string;
+    }): Promise<FS>;
+    /**
+     * Copy files from source FS into this branch in a single atomic commit.
+     *
+     * Follows the same rsync trailing-slash conventions as `copyIn`/`copyOut`:
+     *
+     * - `"config"` → directory mode — copies `config/` *as* `config/` under dest.
+     * - `"config/"` → contents mode — pours the *contents* of `config/` into dest.
+     * - `"file.txt"` → file mode — copies the single file into dest.
+     * - `""` or `"/"` → root contents mode — copies everything.
+     *
+     * Since both snapshots share the same object store, blobs are referenced
+     * by OID — no data is read into memory regardless of file size.
+     *
+     * @param source - Any FS (branch, tag, detached commit). Read-only; not modified.
+     * @param sources - Source path(s) in source. Accepts a single string or array. Defaults to `""` (root).
+     * @param dest - Destination path in this branch. Defaults to `""` (root).
+     * @param opts - Copy-ref options.
+     * @param opts.delete - Remove dest files under the target that aren't in source.
+     * @param opts.dryRun - Compute changes but don't commit. Returned FS has `.changes` set.
+     * @param opts.message - Commit message (auto-generated if omitted).
+     * @returns New FS for the dest branch with the commit applied.
+     * @throws {Error} If source belongs to a different repo.
+     * @throws {PermissionError} If this FS is read-only.
+     */
+    copyFromRef(source: FS, sources?: string | string[], dest?: string, opts?: {
+        delete?: boolean;
+        dryRun?: boolean;
+        message?: string;
+    }): Promise<FS>;
+    /**
+     * The parent snapshot, or `null` for the initial commit.
+     *
+     * @returns The parent FS, or `null` if this is the initial commit.
+     */
+    getParent(): Promise<FS | null>;
+    /**
+     * Return the FS at the n-th ancestor commit.
+     *
+     * @param n - Number of commits to go back (default 1).
+     * @returns FS at the ancestor commit.
+     * @throws {Error} If n < 0 or history is too short.
+     */
+    back(n?: number): Promise<FS>;
+    /**
+     * Move branch back N commits.
+     *
+     * Walks back through parent commits and updates the branch pointer.
+     * Automatically writes a reflog entry.
+     *
+     * @param steps - Number of commits to undo (default 1).
+     * @returns New FS snapshot at the ancestor commit.
+     * @throws {PermissionError} If called on a read-only snapshot (tag).
+     * @throws {Error} If not enough history exists.
+     * @throws {StaleSnapshotError} If the branch has advanced since this snapshot.
+     */
+    undo(steps?: number): Promise<FS>;
+    /**
+     * Move branch forward N steps using reflog.
+     *
+     * Reads the reflog to find where the branch was before the last N movements.
+     * This can resurrect "orphaned" commits after undo.
+     *
+     * @param steps - Number of reflog entries to go back (default 1).
+     * @returns New FS snapshot at the target position.
+     * @throws {PermissionError} If called on a read-only snapshot (tag).
+     * @throws {Error} If not enough redo history exists.
+     * @throws {StaleSnapshotError} If the branch has advanced since this snapshot.
+     */
+    redo(steps?: number): Promise<FS>;
+    /**
+     * Walk the commit history, yielding ancestor FS snapshots.
+     *
+     * All filters are optional and combine with AND.
+     *
+     * @param opts - Log filter options.
+     * @param opts.path - Only yield commits that changed this file.
+     * @param opts.match - Message pattern (`*`/`?` wildcards).
+     * @param opts.before - Only yield commits on or before this time.
+     */
+    log(opts?: {
+        path?: string;
+        match?: string;
+        before?: Date;
+    }): AsyncGenerator<FS>;
+}
+/**
+ * Write data to a branch with automatic retry on concurrent modification.
+ *
+ * Re-fetches the branch FS on each attempt. Uses exponential backoff
+ * with jitter (base 10ms, factor 2x, cap 200ms) to avoid thundering-herd.
+ *
+ * @param store - The GitStore instance.
+ * @param branch - Branch name to write to.
+ * @param path - Destination path in the repo.
+ * @param data - Raw bytes to write.
+ * @param opts - Optional retry-write options.
+ * @param opts.message - Commit message (auto-generated if omitted).
+ * @param opts.mode - File mode override (e.g. `'executable'`).
+ * @param opts.retries - Maximum number of attempts (default 5).
+ * @returns New FS snapshot with the write committed.
+ * @throws {StaleSnapshotError} If all attempts are exhausted.
+ * @throws {Error} If the branch does not exist.
+ */
+export declare function retryWrite(store: GitStore, branch: string, path: string, data: Uint8Array, opts?: {
+    message?: string;
+    mode?: FileType | string;
+    retries?: number;
+}): Promise<FS>;