@outfitter/file-ops 0.2.4 → 0.2.5

package/dist/index.d.ts

@@ -1,348 +1,8 @@
-import { ConflictError, InternalError, NotFoundError, Result, ValidationError } from "@outfitter/contracts";
-/**
-* Options for workspace root detection.
-*
-* Configure which marker files trigger workspace detection and where to stop searching.
-*/
-interface FindWorkspaceRootOptions {
-	/**
-	* Marker files/directories to search for.
-	* Search stops when any marker is found at a directory level.
-	* @defaultValue [".git", "package.json"]
-	*/
-	markers?: string[];
-	/**
-	* Stop searching at this directory boundary.
-	* The search will not continue above this path.
-	* @defaultValue filesystem root
-	*/
-	stopAt?: string;
-}
-/**
-* Options for glob operations.
-*
-* Configure base directory, exclusion patterns, and file matching behavior.
-*/
-interface GlobOptions {
-	/**
-	* Base directory for glob matching.
-	* All returned paths will be absolute paths within this directory.
-	* @defaultValue process.cwd()
-	*/
-	cwd?: string;
-	/**
-	* Include files and directories starting with a dot in results.
-	* @defaultValue false
-	*/
-	dot?: boolean;
-	/**
-	* Follow symbolic links when scanning directories.
-	* @defaultValue false
-	*/
-	followSymlinks?: boolean;
-	/**
-	* Patterns to exclude from results.
-	* Supports negation with "!" prefix to re-include previously excluded files.
-	*/
-	ignore?: string[];
-}
-/**
-* Options for atomic write operations.
-*
-* Configure directory creation, permission handling, and file modes.
-*/
-interface AtomicWriteOptions {
-	/**
-	* Create parent directories if they do not exist.
-	* Uses recursive mkdir when enabled.
-	* @defaultValue true
-	*/
-	createParentDirs?: boolean;
-	/**
-	* Unix file mode for newly created files.
-	* @defaultValue 0o644
-	*/
-	mode?: number;
-	/**
-	* Preserve file permissions from existing file.
-	* If the target file does not exist, falls back to the mode option.
-	* @defaultValue false
-	*/
-	preservePermissions?: boolean;
-}
-/**
-* Represents an acquired file lock.
-*
-* Contains metadata about the lock including the owning process ID and
-* acquisition timestamp. Used with acquireLock and releaseLock functions.
-*/
-interface FileLock {
-	/** Path to the .lock file that indicates the lock */
-	lockPath: string;
-	/** Absolute path to the locked file */
-	path: string;
-	/** Process ID of the lock holder */
-	pid: number;
-	/** Unix timestamp (milliseconds) when the lock was acquired */
-	timestamp: number;
-}
-/**
-* Represents an acquired shared (reader) file lock.
-*
-* Extends FileLock with a lock type discriminator. Multiple processes can
-* hold shared locks simultaneously, but shared locks block exclusive locks.
-*/
-interface SharedFileLock extends FileLock {
-	/** Discriminator indicating this is a shared/reader lock */
-	lockType: "shared";
-	/** Unique identifier for this reader (allows multiple readers from same PID) */
-	readerId: string;
-}
-/**
-* Options for lock acquisition.
-*/
-interface LockOptions {
-	/**
-	* Interval in milliseconds between retry attempts when waiting.
-	* @defaultValue 50
-	*/
-	retryInterval?: number;
-	/**
-	* Maximum time in milliseconds to wait for lock acquisition.
-	* If not specified, fails immediately if lock cannot be acquired.
-	*/
-	timeout?: number;
-}
-/**
-* Finds the workspace root by searching upward for marker files/directories.
-*
-* Searches from startPath up to the filesystem root (or stopAt if specified),
-* returning the first directory containing any of the marker files.
-* Default markers are ".git" and "package.json".
-*
-* @param startPath - Path to start searching from (can be file or directory)
-* @param options - Search options including custom markers and stop boundary
-* @returns Result containing absolute workspace root path, or NotFoundError if no markers found
-*/
-declare function findWorkspaceRoot(startPath: string, options?: FindWorkspaceRootOptions): Promise<Result<string, InstanceType<typeof NotFoundError>>>;
-/**
-* Gets the path relative to the workspace root.
-*
-* Finds the workspace root from the file's directory and returns the
-* path relative to that root. Uses forward slashes for cross-platform consistency.
-*
-* @param absolutePath - Absolute path to convert to workspace-relative
-* @returns Result containing relative path with forward slashes, or NotFoundError if no workspace found
-*/
-declare function getRelativePath(absolutePath: string): Promise<Result<string, InstanceType<typeof NotFoundError>>>;
-/**
-* Checks if a path is inside a workspace directory.
-*
-* Resolves both paths to absolute form and checks if path is equal to
-* or a descendant of workspaceRoot. Does not follow symlinks.
-*
-* @param path - Path to check (can be relative or absolute)
-* @param workspaceRoot - Workspace root directory to check against
-* @returns True if path is inside or equal to workspace root, false otherwise
-*/
-declare function isInsideWorkspace(path: string, workspaceRoot: string): boolean;
-/**
-* Validates and secures a user-provided path, preventing path traversal attacks.
-*
-* Security checks performed:
-* - Null bytes are rejected immediately
-* - Path traversal sequences (..) are rejected
-* - Absolute paths are rejected
-* - Final resolved path is verified to remain within basePath (defense in depth)
-*
-* Always use this function when handling user-provided paths instead of
-* directly using path.join with untrusted input.
-*
-* @param path - User-provided path to validate (must be relative)
-* @param basePath - Base directory to resolve against
-* @returns Result containing resolved absolute safe path, or ValidationError if path is unsafe
-*/
-declare function securePath(path: string, basePath: string): Result<string, InstanceType<typeof ValidationError>>;
-/**
-* Checks if a path is safe (no traversal, valid characters).
-*
-* Convenience wrapper around securePath that returns a boolean.
-* Use this for quick validation; use securePath when you need the resolved path.
-*
-* @param path - Path to check (should be relative)
-* @param basePath - Base directory to resolve against
-* @returns True if path passes all security checks, false otherwise
-*/
-declare function isPathSafe(path: string, basePath: string): boolean;
-/**
-* Safely resolves path segments into an absolute path.
-*
-* Validates each segment for security issues before joining. Use this
-* instead of path.join when any segment may come from user input.
-*
-* Security checks per segment:
-* - Null bytes are rejected
-* - Path traversal (..) is rejected
-* - Absolute path segments are rejected
-*
-* @param basePath - Base directory (must be absolute)
-* @param segments - Path segments to join (each validated individually)
-* @returns Result containing resolved absolute path, or ValidationError if any segment is unsafe
-*/
-declare function resolveSafePath(basePath: string, ...segments: string[]): Result<string, InstanceType<typeof ValidationError>>;
-/**
-* Finds files matching a glob pattern.
-*
-* Uses Bun.Glob internally for fast pattern matching. Returns absolute paths.
-* Supports standard glob syntax including recursive matching, alternation, and character classes.
-*
-* Pattern syntax:
-* - Single asterisk matches any characters except path separator
-* - Double asterisk matches any characters including path separator (recursive)
-* - Curly braces for alternation
-* - Square brackets for character classes
-*
-* @param pattern - Glob pattern to match
-* @param options - Glob options including cwd, ignore patterns, and file type filters
-* @returns Result containing array of absolute file paths, or InternalError on failure
-*/
-declare function glob(pattern: string, options?: GlobOptions): Promise<Result<string[], InstanceType<typeof InternalError>>>;
-/**
-* Synchronous version of glob.
-*
-* Use the async glob function when possible. This synchronous version
-* blocks the event loop and should only be used in initialization code
-* or synchronous contexts.
-*
-* @param pattern - Glob pattern to match
-* @param options - Glob options including cwd, ignore patterns, and file type filters
-* @returns Result containing array of absolute file paths, or InternalError on failure
-*/
-declare function globSync(pattern: string, options?: GlobOptions): Result<string[], InstanceType<typeof InternalError>>;
-/**
-* Acquires an exclusive advisory lock on a file.
-*
-* Creates a .lock file next to the target file with lock metadata (PID, timestamp).
-* Uses atomic file creation (wx flag) to prevent race conditions.
-*
-* Exclusive locks block and are blocked by both shared and exclusive locks.
-* Use shared locks (acquireSharedLock) for read-only operations.
-*
-* Important: This is advisory locking. All processes must cooperate by using
-* these locking APIs. The filesystem does not enforce the lock.
-*
-* Prefer using withLock for automatic lock release.
-*
-* @param path - Absolute path to the file to lock
-* @param options - Lock options including timeout and retry interval
-* @returns Result containing FileLock on success, or ConflictError if already locked
-*/
-declare function acquireLock(path: string, options?: LockOptions): Promise<Result<FileLock, InstanceType<typeof ConflictError>>>;
-/**
-* Releases a file lock by removing the .lock file.
-*
-* Should only be called with a lock obtained from acquireLock.
-* Prefer using withLock for automatic lock management.
-*
-* @param lock - Lock object returned from acquireLock
-* @returns Result indicating success, or InternalError if lock file cannot be removed
-*/
-declare function releaseLock(lock: FileLock): Promise<Result<void, InstanceType<typeof InternalError>>>;
-/**
-* Executes a callback while holding an exclusive lock on a file.
-*
-* Lock is automatically released after callback completes, whether it
-* succeeds or throws an error. This is the recommended way to use file locking.
-*
-* Uses advisory file locking via .lock files. The lock is NOT enforced
-* by the filesystem - all processes must cooperate by using this API.
-*
-* @typeParam T - Return type of the callback
-* @param path - Absolute path to the file to lock
-* @param callback - Async callback to execute while holding lock
-* @returns Result containing callback return value, ConflictError if locked, or InternalError on failure
-*/
-declare function withLock<T>(path: string, callback: () => Promise<T>): Promise<Result<T, InstanceType<typeof ConflictError> | InstanceType<typeof InternalError>>>;
-/**
-* Checks if a file is currently locked.
-*
-* Checks for the existence of a .lock file. Does not verify if the
-* process holding the lock is still running (no stale lock detection).
-*
-* @param path - Absolute path to check
-* @returns True if a lock file exists, false otherwise
-*/
-declare function isLocked(path: string): Promise<boolean>;
-/**
-* Writes content to a file atomically using temp-file-then-rename strategy.
-*
-* How it works:
-* 1. Creates a unique temp file in the same directory
-* 2. Writes content to temp file
-* 3. Renames temp file to target (atomic on most filesystems)
-* 4. Cleans up temp file on failure
-*
-* This prevents partial writes and file corruption. The file either
-* contains the old content or the new content, never a partial state.
-*
-* @param path - Absolute path to target file
-* @param content - String content to write
-* @param options - Write options including directory creation and permission handling
-* @returns Result indicating success, or InternalError on failure
-*/
-declare function atomicWrite(path: string, content: string, options?: AtomicWriteOptions): Promise<Result<void, InstanceType<typeof InternalError>>>;
-/**
-* Writes JSON data to a file atomically.
-*
-* Serializes data to JSON and writes using atomicWrite.
-* Returns ValidationError if serialization fails.
-*
-* @typeParam T - Type of data to serialize
-* @param path - Absolute path to target file
-* @param data - Data to serialize and write (must be JSON-serializable)
-* @param options - Write options including directory creation and permission handling
-* @returns Result indicating success, ValidationError if serialization fails, or InternalError on write failure
-*/
-declare function atomicWriteJson<T>(path: string, data: T, options?: AtomicWriteOptions): Promise<Result<void, InstanceType<typeof InternalError> | InstanceType<typeof ValidationError>>>;
-/**
-* Acquires a shared (reader) lock on a file.
-*
-* Multiple readers can hold shared locks simultaneously. Shared locks are
-* blocked by exclusive locks. Uses the same .lock file as exclusive locks
-* with a JSON format that distinguishes lock types.
-*
-* Important: This is advisory locking. All processes must cooperate by using
-* these locking APIs. The filesystem does not enforce the lock.
-*
-* @param path - Absolute path to the file to lock
-* @param options - Lock options including timeout and retry interval
-* @returns Result containing SharedFileLock on success, or ConflictError if blocked by exclusive lock
-*/
-declare function acquireSharedLock(path: string, options?: LockOptions): Promise<Result<SharedFileLock, InstanceType<typeof ConflictError>>>;
-/**
-* Releases a shared (reader) lock.
-*
-* Removes this process from the list of readers in the lock file.
-* If this is the last reader, the lock file is deleted.
-*
-* @param lock - Shared lock object returned from acquireSharedLock
-* @returns Result indicating success, or InternalError if lock file cannot be modified
-*/
-declare function releaseSharedLock(lock: SharedFileLock): Promise<Result<void, InstanceType<typeof InternalError>>>;
-/**
-* Executes a callback while holding a shared (reader) lock on a file.
-*
-* Lock is automatically released after callback completes, whether it
-* succeeds or throws an error. This is the recommended way to use shared locks.
-*
-* Multiple readers can hold shared locks simultaneously. Use this for
-* read-only operations that should not block other readers.
-*
-* @typeParam T - Return type of the callback
-* @param path - Absolute path to the file to lock
-* @param callback - Async callback to execute while holding lock
-* @param options - Lock options including timeout and retry interval
-* @returns Result containing callback return value, ConflictError if blocked, or InternalError on failure
-*/
-declare function withSharedLock<T>(path: string, callback: () => Promise<T>, options?: LockOptions): Promise<Result<T, InstanceType<typeof ConflictError> | InstanceType<typeof InternalError>>>;
+import { glob, globSync } from "./shared/@outfitter/file-ops-3kzghhjm.js";
+import { findWorkspaceRoot, getRelativePath, isInsideWorkspace } from "./shared/@outfitter/file-ops-b3v6xcnw.js";
+import { acquireSharedLock, releaseSharedLock, withSharedLock } from "./shared/@outfitter/file-ops-cpvpwwsr.js";
+import { isPathSafe, resolveSafePath, securePath } from "./shared/@outfitter/file-ops-ss4da105.js";
+import { acquireLock, isLocked, releaseLock, withLock } from "./shared/@outfitter/file-ops-9xg8rjay.js";
+import { atomicWrite, atomicWriteJson } from "./shared/@outfitter/file-ops-cp4q6s4n.js";
+import { AtomicWriteOptions, FileLock, FindWorkspaceRootOptions, GlobOptions, LockOptions, SharedFileLock } from "./shared/@outfitter/file-ops-f0bv7qk0.js";
 export { withSharedLock, withLock, securePath, resolveSafePath, releaseSharedLock, releaseLock, isPathSafe, isLocked, isInsideWorkspace, globSync, glob, getRelativePath, findWorkspaceRoot, atomicWriteJson, atomicWrite, acquireSharedLock, acquireLock, SharedFileLock, LockOptions, GlobOptions, FindWorkspaceRootOptions, FileLock, AtomicWriteOptions };