@mhalle/vost 0.8.1

package/dist/copy.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Copy/sync/remove/move operations between local disk and git repo.
+ *
+ * Ports the Python vost copy/ subpackage into a single module.
+ */
+import { type FsModule } from './types.js';
+import type { FS } from './fs.js';
+import type { ExcludeFilter } from './exclude.js';
+/**
+ * Walk a git tree and return file entries as a map.
+ *
+ * Builds a `{relativePath: {oid, mode}}` map for all files under
+ * `repoPath`. OID values are hex strings suitable for comparison
+ * against local file hashes. Returns an empty map when `repoPath`
+ * does not exist or is not a directory.
+ *
+ * @param fs - Filesystem snapshot to walk.
+ * @param repoPath - Root path in the repo tree (empty string for root).
+ * @returns Map of relative paths to `{oid, mode}` objects.
+ */
+export declare function walkRepo(fs: FS, repoPath: string): Promise<Map<string, {
+    oid: string;
+    mode: string;
+}>>;
+/**
+ * Expand a glob pattern against the local filesystem.
+ *
+ * Uses the same dotfile-aware rules as the repo-side `fs.glob()`:
+ * `*` and `?` do not match a leading `.` unless the pattern segment
+ * itself starts with `.`.
+ *
+ * @param fsModule - Node.js-compatible filesystem module.
+ * @param pattern - Glob pattern (e.g. `"src/**\/*.ts"`). Supports `*`, `?`, and `**`.
+ * @returns Sorted list of matching paths.
+ */
+export declare function diskGlob(fsModule: FsModule, pattern: string): Promise<string[]>;
+/**
+ * A resolved repo source path with its copy mode.
+ * - `repoPath` — normalized path in the repo.
+ * - `mode` — 'file' for a single file, 'dir' for a directory, 'contents' for trailing-slash contents mode.
+ * - `prefix` — prefix for pivot marker support.
+ */
+export type ResolvedRepoSource = {
+    repoPath: string;
+    mode: 'file' | 'dir' | 'contents';
+    prefix: string;
+};
+/**
+ * Resolve repo source paths into their copy mode (file/dir/contents).
+ *
+ * Trailing `/` means contents mode; bare directory names mean directory mode;
+ * files mean file mode. Empty string or `/` means root contents.
+ *
+ * @param fs      - The FS snapshot to resolve paths against.
+ * @param sources - Array of repo paths to resolve.
+ * @returns Array of resolved sources with mode and prefix.
+ * @throws {FileNotFoundError} If a source path does not exist.
+ * @throws {NotADirectoryError} If a trailing-`/` source is not a directory.
+ */
+export declare function resolveRepoSources(fs: FS, sources: string[]): Promise<ResolvedRepoSource[]>;
+/**
+ * Copy local files, directories, or globs into the repo.
+ *
+ * Sources may use a trailing `/` for "contents" mode (pour directory
+ * contents into `dest` without creating a subdirectory).
+ *
+ * With `dryRun: true`, no changes are written; the input FS is
+ * returned with `.changes` populated.
+ *
+ * With `delete: true`, files under `dest` that are not covered by
+ * `sources` are removed (rsync `--delete` semantics).
+ *
+ * @param fs - Filesystem snapshot (must be writable, i.e. a branch).
+ * @param sources - One or more local paths to copy. A trailing `/` means "contents of directory".
+ * @param dest - Destination path in the repo tree.
+ * @param opts - Copy options.
+ * @param opts.dryRun - Preview changes without writing. Default `false`.
+ * @param opts.followSymlinks - Dereference symlinks instead of storing them. Default `false`.
+ * @param opts.message - Custom commit message.
+ * @param opts.mode - Override file mode for all written files.
+ * @param opts.ignoreExisting - Skip files that already exist at the destination. Default `false`.
+ * @param opts.delete - Remove destination files not present in sources. Default `false`.
+ * @param opts.ignoreErrors - Continue on per-file errors, collecting them in `changes.errors`. Default `false`.
+ * @param opts.checksum - Use content hashing to detect changes. When `false`, uses mtime comparison. Default `true`.
+ * @param opts.operation - Operation name for the commit message. Default `"cp"`.
+ * @returns FS snapshot after the copy, with `.changes` set.
+ * @throws {FileNotFoundError} If a source path does not exist (unless `ignoreErrors` is set).
+ * @throws {NotADirectoryError} If a trailing-`/` source is not a directory.
+ */
+export declare function copyIn(fs: FS, sources: string | string[], dest: string, opts?: {
+    dryRun?: boolean;
+    followSymlinks?: boolean;
+    message?: string;
+    mode?: string;
+    ignoreExisting?: boolean;
+    delete?: boolean;
+    ignoreErrors?: boolean;
+    checksum?: boolean;
+    operation?: string;
+    exclude?: ExcludeFilter;
+}): Promise<FS>;
+/**
+ * Copy repo files, directories, or globs to local disk.
+ *
+ * Sources may use a trailing `/` for "contents" mode (pour directory
+ * contents into `dest` without creating a subdirectory).
+ *
+ * With `dryRun: true`, no changes are written; the input FS is
+ * returned with `.changes` populated.
+ *
+ * With `delete: true`, local files under `dest` that are not covered
+ * by `sources` are removed (rsync `--delete` semantics).
+ *
+ * @param fs - Filesystem snapshot to copy from.
+ * @param sources - One or more repo paths to copy. A trailing `/` means "contents of directory".
+ * @param dest - Destination directory on local disk.
+ * @param opts - Copy options.
+ * @param opts.dryRun - Preview changes without writing. Default `false`.
+ * @param opts.ignoreExisting - Skip files that already exist at the destination. Default `false`.
+ * @param opts.delete - Remove local files not present in sources. Default `false`.
+ * @param opts.ignoreErrors - Continue on per-file errors, collecting them in `changes.errors`. Default `false`.
+ * @param opts.checksum - Use content hashing to detect changes. When `false`, uses mtime comparison. Default `true`.
+ * @param opts.operation - Operation name for the commit message.
+ * @returns FS snapshot with `.changes` set describing what was copied.
+ * @throws {FileNotFoundError} If a source path does not exist in the repo (unless `ignoreErrors` is set).
+ * @throws {NotADirectoryError} If a trailing-`/` source is not a directory.
+ */
+export declare function copyOut(fs: FS, sources: string | string[], dest: string, opts?: {
+    dryRun?: boolean;
+    ignoreExisting?: boolean;
+    delete?: boolean;
+    ignoreErrors?: boolean;
+    checksum?: boolean;
+    operation?: string;
+}): Promise<FS>;
+/**
+ * Remove files or directories from the repo.
+ *
+ * With `dryRun: true`, no changes are written; the input FS is
+ * returned with `.changes` populated.
+ *
+ * @param fs - Filesystem snapshot (must be writable, i.e. a branch).
+ * @param sources - One or more repo paths to remove.
+ * @param opts - Remove options.
+ * @param opts.recursive - Allow removal of directories. Default `false`.
+ * @param opts.dryRun - Preview changes without writing. Default `false`.
+ * @param opts.message - Custom commit message.
+ * @returns FS snapshot after the removal, with `.changes` set.
+ * @throws {FileNotFoundError} If no source matches any file.
+ * @throws {IsADirectoryError} If a source is a directory and `recursive` is `false`.
+ */
+export declare function remove(fs: FS, sources: string | string[], opts?: {
+    recursive?: boolean;
+    dryRun?: boolean;
+    message?: string;
+}): Promise<FS>;
+/**
+ * Make `repoPath` identical to `localPath` (disk to repo sync).
+ *
+ * Copies new and changed files from `localPath` into `repoPath` and
+ * deletes repo files that do not exist on disk. Equivalent to
+ * `copyIn` with `delete: true`.
+ *
+ * If `localPath` does not exist, all files under `repoPath` are
+ * deleted (treating the source as empty).
+ *
+ * With `dryRun: true`, no changes are written; the input FS is
+ * returned with `.changes` populated.
+ *
+ * @param fs - Filesystem snapshot (must be writable, i.e. a branch).
+ * @param localPath - Source directory on local disk.
+ * @param repoPath - Destination path in the repo tree.
+ * @param opts - Sync options.
+ * @param opts.dryRun - Preview changes without writing. Default `false`.
+ * @param opts.message - Custom commit message.
+ * @param opts.ignoreErrors - Continue on per-file errors. Default `false`.
+ * @param opts.checksum - Use content hashing. When `false`, uses mtime. Default `true`.
+ * @returns FS snapshot after sync, with `.changes` set.
+ * @throws {PermissionError} If the FS is read-only.
+ */
+export declare function syncIn(fs: FS, localPath: string, repoPath: string, opts?: {
+    dryRun?: boolean;
+    message?: string;
+    ignoreErrors?: boolean;
+    checksum?: boolean;
+    exclude?: ExcludeFilter;
+}): Promise<FS>;
+/**
+ * Make `localPath` identical to `repoPath` (repo to disk sync).
+ *
+ * Copies new and changed files from the repo to `localPath` and
+ * deletes local files that do not exist in the repo. Equivalent to
+ * `copyOut` with `delete: true`.
+ *
+ * If `repoPath` does not exist in the repo, all files under
+ * `localPath` are deleted (treating the source as empty).
+ *
+ * With `dryRun: true`, no changes are written; the input FS is
+ * returned with `.changes` populated.
+ *
+ * @param fs - Filesystem snapshot to sync from.
+ * @param repoPath - Source path in the repo tree.
+ * @param localPath - Destination directory on local disk.
+ * @param opts - Sync options.
+ * @param opts.dryRun - Preview changes without writing. Default `false`.
+ * @param opts.ignoreErrors - Continue on per-file errors. Default `false`.
+ * @param opts.checksum - Use content hashing. When `false`, uses mtime. Default `true`.
+ * @returns FS snapshot with `.changes` set describing what was synced.
+ */
+export declare function syncOut(fs: FS, repoPath: string, localPath: string, opts?: {
+    dryRun?: boolean;
+    ignoreErrors?: boolean;
+    checksum?: boolean;
+}): Promise<FS>;
+/**
+ * Move or rename files within the repo.
+ *
+ * Implements POSIX `mv` semantics: when there is a single source file
+ * and `dest` is not an existing directory and does not end with `/`,
+ * the destination is the exact target path (rename). Otherwise files
+ * are placed inside `dest`.
+ *
+ * With `dryRun: true`, no changes are written; the input FS is
+ * returned with `.changes` populated.
+ *
+ * @param fs - Filesystem snapshot (must be writable, i.e. a branch).
+ * @param sources - One or more repo paths to move.
+ * @param dest - Destination path in the repo tree.
+ * @param opts - Move options.
+ * @param opts.recursive - Allow moving directories. Default `false`.
+ * @param opts.dryRun - Preview changes without writing. Default `false`.
+ * @param opts.message - Custom commit message.
+ * @returns FS snapshot after the move, with `.changes` set.
+ * @throws {FileNotFoundError} If no source matches any file.
+ * @throws {IsADirectoryError} If a source is a directory and `recursive` is `false`.
+ * @throws {Error} If source and destination are the same path.
+ */
+export declare function move(fs: FS, sources: string | string[], dest: string, opts?: {
+    recursive?: boolean;
+    dryRun?: boolean;
+    message?: string;
+}): Promise<FS>;