@outfitter/file-ops 0.1.0-rc.1

package/README.md

@@ -0,0 +1,365 @@
+# @outfitter/file-ops
+
+Workspace detection, secure path handling, glob patterns, file locking, and atomic write utilities for Outfitter projects.
+
+## Installation
+
+```bash
+bun add @outfitter/file-ops
+```
+
+## Quick Start
+
+```typescript
+import {
+  findWorkspaceRoot,
+  securePath,
+  glob,
+  withLock,
+  atomicWrite
+} from "@outfitter/file-ops";
+
+// Find workspace root by marker files (.git, package.json)
+const rootResult = await findWorkspaceRoot(process.cwd());
+if (rootResult.isOk()) {
+  const root = rootResult.value;
+
+  // Secure path resolution (prevents traversal attacks)
+  const pathResult = securePath("src/config.json", root);
+  if (pathResult.isOk()) {
+    console.log("Safe path:", pathResult.value);
+  }
+}
+
+// Find files with glob patterns
+const files = await glob("**/*.ts", {
+  cwd: "/project",
+  ignore: ["node_modules/**", "**/*.test.ts"]
+});
+
+// Atomic write with file locking
+await withLock("/path/to/file.json", async () => {
+  await atomicWrite("/path/to/file.json", JSON.stringify(data));
+});
+```
+
+## API Reference
+
+### Workspace Detection
+
+#### `findWorkspaceRoot(startPath, options?)`
+
+Finds the workspace root by searching for marker files/directories.
+
+```typescript
+const result = await findWorkspaceRoot("/project/src/lib");
+if (result.isOk()) {
+  console.log("Workspace:", result.value); // "/project"
+}
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `markers` | `string[]` | `[".git", "package.json"]` | Marker files/directories to search for |
+| `stopAt` | `string` | filesystem root | Stop searching at this directory |
+
+```typescript
+// Custom markers for Rust or Python projects
+const result = await findWorkspaceRoot(startPath, {
+  markers: ["Cargo.toml", "pyproject.toml"],
+  stopAt: "/home/user"
+});
+```
+
+#### `getRelativePath(absolutePath)`
+
+Returns the path relative to the workspace root.
+
+```typescript
+const result = await getRelativePath("/project/src/lib/utils.ts");
+if (result.isOk()) {
+  console.log(result.value); // "src/lib/utils.ts"
+}
+```
+
+#### `isInsideWorkspace(path, workspaceRoot)`
+
+Checks if a path is inside a workspace directory.
+
+```typescript
+const inside = await isInsideWorkspace("/project/src/file.ts", "/project");
+console.log(inside); // true
+
+const outside = await isInsideWorkspace("/etc/passwd", "/project");
+console.log(outside); // false
+```
+
+### Path Security
+
+**IMPORTANT**: These functions protect against path traversal attacks. Always use them when handling user-provided paths.
+
+#### Security Model
+
+| Attack Vector | Protection |
+|--------------|------------|
+| Path traversal (`../`) | Blocked by all security functions |
+| Null bytes (`\x00`) | Rejected immediately |
+| Absolute paths | Blocked when relative expected |
+| Escape from base directory | Defense-in-depth verification |
+
+#### `securePath(path, basePath)`
+
+Validates and secures a user-provided path, preventing path traversal attacks.
+
+```typescript
+// SAFE: Validates path stays within basePath
+const result = securePath("data/file.json", "/app/workspace");
+if (result.isOk()) {
+  // Safe to use: /app/workspace/data/file.json
+  console.log(result.value);
+}
+
+// These all return ValidationError:
+securePath("../etc/passwd", base);      // Traversal sequence
+securePath("/etc/passwd", base);        // Absolute path
+securePath("file\x00.txt", base);       // Null byte
+```
+
+**UNSAFE pattern - never do this:**
+
+```typescript
+// DON'T: User input directly in path.join
+const bad = path.join("/base", userInput); // VULNERABLE!
+
+// DO: Always validate with securePath first
+const result = securePath(userInput, "/base");
+if (result.isOk()) {
+  // Now safe to use
+}
+```
+
+#### `isPathSafe(path, basePath)`
+
+Quick boolean check for path safety.
+
+```typescript
+if (isPathSafe(userInput, basePath)) {
+  // Safe to proceed
+}
+```
+
+#### `resolveSafePath(basePath, ...segments)`
+
+Safely joins multiple path segments.
+
+```typescript
+const result = resolveSafePath("/app", "data", "users", "profile.json");
+if (result.isOk()) {
+  console.log(result.value); // "/app/data/users/profile.json"
+}
+
+// Rejects dangerous segments
+resolveSafePath("/app", "..", "etc");     // Error: traversal
+resolveSafePath("/app", "/etc/passwd");   // Error: absolute segment
+```
+
+### Glob Patterns
+
+#### `glob(pattern, options?)`
+
+Finds files matching a glob pattern. Uses `Bun.Glob` internally.
+
+```typescript
+// Find all TypeScript files
+const result = await glob("**/*.ts", { cwd: "/project" });
+
+// Exclude test files and node_modules
+const result = await glob("**/*.ts", {
+  cwd: "/project",
+  ignore: ["**/*.test.ts", "**/node_modules/**"]
+});
+
+// Include dot files
+const result = await glob("**/.*", { cwd: "/project", dot: true });
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cwd` | `string` | `process.cwd()` | Base directory for matching |
+| `ignore` | `string[]` | `[]` | Patterns to exclude |
+| `followSymlinks` | `boolean` | `false` | Follow symbolic links |
+| `dot` | `boolean` | `false` | Include dot files |
+
+**Pattern Syntax:**
+
+| Pattern | Matches |
+|---------|---------|
+| `*` | Any characters except `/` |
+| `**` | Any characters including `/` (recursive) |
+| `{a,b}` | Alternation (matches `a` or `b`) |
+| `[abc]` | Character class (matches `a`, `b`, or `c`) |
+| `!pattern` | Negation (in ignore array) |
+
+```typescript
+// Negation patterns in ignore array
+const result = await glob("src/**/*.ts", {
+  cwd: "/project",
+  ignore: ["**/*.ts", "!**/index.ts"]  // Ignore all except index.ts
+});
+```
+
+#### `globSync(pattern, options?)`
+
+Synchronous version of `glob`.
+
+```typescript
+const result = globSync("src/*.ts", { cwd: "/project" });
+```
+
+### File Locking
+
+Advisory file locking for cross-process coordination. Uses `.lock` files to indicate locks.
+
+**Note**: This is advisory locking. All processes must cooperate by using these APIs.
+
+#### `withLock(path, callback)`
+
+Recommended approach. Executes a callback while holding an exclusive lock, with automatic release.
+
+```typescript
+const result = await withLock("/data/config.json", async () => {
+  const config = JSON.parse(await Bun.file("/data/config.json").text());
+  config.counter++;
+  await atomicWrite("/data/config.json", JSON.stringify(config));
+  return config.counter;
+});
+
+if (result.isOk()) {
+  console.log("New counter:", result.value);
+} else if (result.error._tag === "ConflictError") {
+  console.log("File is locked by another process");
+}
+```
+
+#### `acquireLock(path)` / `releaseLock(lock)`
+
+Manual lock management. Use `withLock` when possible.
+
+```typescript
+const lockResult = await acquireLock("/data/file.db");
+if (lockResult.isOk()) {
+  const lock = lockResult.value;
+  try {
+    // ... do work ...
+  } finally {
+    await releaseLock(lock);
+  }
+}
+```
+
+#### `isLocked(path)`
+
+Checks if a file is currently locked.
+
+```typescript
+if (await isLocked("/data/file.db")) {
+  console.log("File is in use");
+}
+```
+
+#### FileLock Interface
+
+```typescript
+interface FileLock {
+  path: string;      // Path to the locked file
+  lockPath: string;  // Path to the .lock file
+  pid: number;       // Process ID holding the lock
+  timestamp: number; // When lock was acquired
+}
+```
+
+### Atomic Writes
+
+Write files atomically using temp-file-then-rename strategy. This prevents partial writes and corruption.
+
+#### `atomicWrite(path, content, options?)`
+
+Writes content to a file atomically.
+
+```typescript
+const result = await atomicWrite("/data/config.json", JSON.stringify(data));
+if (result.isErr()) {
+  console.error("Write failed:", result.error.message);
+}
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `createParentDirs` | `boolean` | `true` | Create parent directories if needed |
+| `preservePermissions` | `boolean` | `false` | Keep permissions from existing file |
+| `mode` | `number` | `0o644` | File mode for new files |
+
+```typescript
+// Preserve executable permissions
+await atomicWrite("/scripts/run.sh", newContent, {
+  preservePermissions: true
+});
+
+// Create nested directories automatically
+await atomicWrite("/data/deep/nested/file.json", content, {
+  createParentDirs: true
+});
+```
+
+#### `atomicWriteJson(path, data, options?)`
+
+Serializes and writes JSON data atomically.
+
+```typescript
+const result = await atomicWriteJson("/data/config.json", {
+  name: "app",
+  version: "1.0.0",
+  settings: { debug: false }
+});
+```
+
+## Error Handling
+
+All functions return `Result` types from `@outfitter/contracts`. Use `.isOk()` and `.isErr()` to handle outcomes.
+
+```typescript
+import type { Result } from "@outfitter/contracts";
+
+const result = await findWorkspaceRoot("/path");
+
+if (result.isOk()) {
+  const workspace = result.value;
+} else {
+  // result.error has _tag, message, and error-specific fields
+  console.error(result.error._tag, result.error.message);
+}
+```
+
+**Error Types:**
+
+| Error | Functions | When |
+|-------|-----------|------|
+| `NotFoundError` | `findWorkspaceRoot`, `getRelativePath` | No workspace marker found |
+| `ValidationError` | `securePath`, `isPathSafe`, `resolveSafePath`, `atomicWriteJson` | Invalid path or data |
+| `ConflictError` | `acquireLock`, `withLock` | File already locked |
+| `InternalError` | `glob`, `releaseLock`, `withLock`, `atomicWrite` | Filesystem or system error |
+
+## Dependencies
+
+- `@outfitter/contracts` - Result types and error classes
+- `@outfitter/types` - Type utilities
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,276 @@
+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;
+	/**
+	* Patterns to exclude from results.
+	* Supports negation with "!" prefix to re-include previously excluded files.
+	*/
+	ignore?: string[];
+	/**
+	* Follow symbolic links when scanning directories.
+	* @defaultValue false
+	*/
+	followSymlinks?: boolean;
+	/**
+	* Include files and directories starting with a dot in results.
+	* @defaultValue false
+	*/
+	dot?: boolean;
+}
+/**
+* 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;
+	/**
+	* Preserve file permissions from existing file.
+	* If the target file does not exist, falls back to the mode option.
+	* @defaultValue false
+	*/
+	preservePermissions?: boolean;
+	/**
+	* Unix file mode for newly created files.
+	* @defaultValue 0o644
+	*/
+	mode?: number;
+}
+/**
+* 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 {
+	/** Absolute path to the locked file */
+	path: string;
+	/** Path to the .lock file that indicates the lock */
+	lockPath: string;
+	/** Process ID of the lock holder */
+	pid: number;
+	/** Unix timestamp (milliseconds) when the lock was acquired */
+	timestamp: 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 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.
+*
+* 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
+* @returns Result containing FileLock on success, or ConflictError if already locked
+*/
+declare function acquireLock(path: string): 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>>>;
+export { withLock, securePath, resolveSafePath, releaseLock, isPathSafe, isLocked, isInsideWorkspace, globSync, glob, getRelativePath, findWorkspaceRoot, atomicWriteJson, atomicWrite, acquireLock, GlobOptions, FindWorkspaceRootOptions, FileLock, AtomicWriteOptions };

package/dist/index.js

@@ -0,0 +1,349 @@
+// src/index.ts
+import {
+  writeFile as fsWriteFile,
+  mkdir,
+  rename,
+  stat,
+  unlink
+} from "node:fs/promises";
+import {
+  dirname,
+  isAbsolute,
+  join,
+  normalize,
+  relative,
+  resolve,
+  sep
+} from "node:path";
+import {
+  ConflictError,
+  InternalError,
+  NotFoundError,
+  Result,
+  ValidationError
+} from "@outfitter/contracts";
+async function markerExistsAt(dir, marker) {
+  try {
+    const markerPath = join(dir, marker);
+    await stat(markerPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findWorkspaceRoot(startPath, options) {
+  const markers = options?.markers ?? [".git", "package.json"];
+  const stopAt = options?.stopAt;
+  let currentDir = resolve(startPath);
+  const root = resolve("/");
+  while (true) {
+    for (const marker of markers) {
+      if (await markerExistsAt(currentDir, marker)) {
+        return Result.ok(currentDir);
+      }
+    }
+    if (stopAt && currentDir === resolve(stopAt)) {
+      break;
+    }
+    if (currentDir === root) {
+      break;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+  return Result.err(new NotFoundError({
+    message: "No workspace root found",
+    resourceType: "workspace",
+    resourceId: startPath
+  }));
+}
+async function getRelativePath(absolutePath) {
+  const workspaceResult = await findWorkspaceRoot(dirname(absolutePath));
+  if (workspaceResult.isErr()) {
+    return workspaceResult;
+  }
+  const relativePath = relative(workspaceResult.value, absolutePath);
+  return Result.ok(relativePath.split(sep).join("/"));
+}
+function isInsideWorkspace(path, workspaceRoot) {
+  const resolvedPath = resolve(path);
+  const resolvedRoot = resolve(workspaceRoot);
+  return resolvedPath.startsWith(resolvedRoot + sep) || resolvedPath === resolvedRoot;
+}
+function securePath(path, basePath) {
+  if (path.includes("\x00")) {
+    return Result.err(new ValidationError({
+      message: "Path contains null bytes",
+      field: "path"
+    }));
+  }
+  const normalizedPath = path.replace(/\\/g, "/");
+  if (normalizedPath.includes("..")) {
+    return Result.err(new ValidationError({
+      message: "Path contains traversal sequence",
+      field: "path"
+    }));
+  }
+  if (normalizedPath.startsWith("/")) {
+    return Result.err(new ValidationError({
+      message: "Absolute paths are not allowed",
+      field: "path"
+    }));
+  }
+  const cleanPath = normalizedPath.replace(/^\.\//, "");
+  const resolvedPath = join(basePath, cleanPath);
+  const normalizedResolved = normalize(resolvedPath);
+  const normalizedBase = normalize(basePath);
+  if (!normalizedResolved.startsWith(normalizedBase)) {
+    return Result.err(new ValidationError({
+      message: "Path escapes base directory",
+      field: "path"
+    }));
+  }
+  return Result.ok(resolvedPath);
+}
+function isPathSafe(path, basePath) {
+  return Result.isOk(securePath(path, basePath));
+}
+function resolveSafePath(basePath, ...segments) {
+  for (const segment of segments) {
+    if (segment.includes("\x00")) {
+      return Result.err(new ValidationError({
+        message: "Path segment contains null bytes",
+        field: "path"
+      }));
+    }
+    if (segment.includes("..")) {
+      return Result.err(new ValidationError({
+        message: "Path segment contains traversal sequence",
+        field: "path"
+      }));
+    }
+    if (isAbsolute(segment)) {
+      return Result.err(new ValidationError({
+        message: "Absolute path segments are not allowed",
+        field: "path"
+      }));
+    }
+  }
+  const resolvedPath = join(basePath, ...segments);
+  const normalizedResolved = normalize(resolvedPath);
+  const normalizedBase = normalize(basePath);
+  if (normalizedResolved !== normalizedBase && !normalizedResolved.startsWith(normalizedBase + sep)) {
+    return Result.err(new ValidationError({
+      message: "Path escapes base directory",
+      field: "path"
+    }));
+  }
+  return Result.ok(resolvedPath);
+}
+function createIgnoreFilter(ignore, cwd) {
+  if (!ignore || ignore.length === 0) {
+    return () => true;
+  }
+  const ignorePatterns = [];
+  const negationPatterns = [];
+  for (const pattern of ignore) {
+    if (pattern.startsWith("!")) {
+      negationPatterns.push(pattern.slice(1));
+    } else {
+      ignorePatterns.push(pattern);
+    }
+  }
+  return (filePath) => {
+    const relativePath = relative(cwd, filePath);
+    let isIgnored = false;
+    for (const pattern of ignorePatterns) {
+      const glob = new Bun.Glob(pattern);
+      if (glob.match(relativePath)) {
+        isIgnored = true;
+        break;
+      }
+    }
+    if (isIgnored) {
+      for (const pattern of negationPatterns) {
+        const glob = new Bun.Glob(pattern);
+        if (glob.match(relativePath)) {
+          isIgnored = false;
+          break;
+        }
+      }
+    }
+    return !isIgnored;
+  };
+}
+async function glob(pattern, options) {
+  try {
+    const cwd = options?.cwd ?? process.cwd();
+    const bunGlob = new Bun.Glob(pattern);
+    const files = [];
+    const ignoreFilter = createIgnoreFilter(options?.ignore, cwd);
+    const scanOptions = {
+      cwd,
+      ...options?.dot !== undefined && { dot: options.dot },
+      ...options?.followSymlinks !== undefined && {
+        followSymlinks: options.followSymlinks
+      }
+    };
+    for await (const file of bunGlob.scan(scanOptions)) {
+      const absolutePath = join(cwd, file);
+      if (ignoreFilter(absolutePath)) {
+        files.push(absolutePath);
+      }
+    }
+    return Result.ok(files);
+  } catch (error) {
+    return Result.err(new InternalError({
+      message: error instanceof Error ? error.message : "Glob operation failed"
+    }));
+  }
+}
+function globSync(pattern, options) {
+  try {
+    const cwd = options?.cwd ?? process.cwd();
+    const bunGlob = new Bun.Glob(pattern);
+    const files = [];
+    const ignoreFilter = createIgnoreFilter(options?.ignore, cwd);
+    const scanOptions = {
+      cwd,
+      ...options?.dot !== undefined && { dot: options.dot },
+      ...options?.followSymlinks !== undefined && {
+        followSymlinks: options.followSymlinks
+      }
+    };
+    for (const file of bunGlob.scanSync(scanOptions)) {
+      const absolutePath = join(cwd, file);
+      if (ignoreFilter(absolutePath)) {
+        files.push(absolutePath);
+      }
+    }
+    return Result.ok(files);
+  } catch (error) {
+    return Result.err(new InternalError({
+      message: error instanceof Error ? error.message : "Glob operation failed"
+    }));
+  }
+}
+async function acquireLock(path) {
+  const lockPath = `${path}.lock`;
+  const lockFile = Bun.file(lockPath);
+  if (await lockFile.exists()) {
+    return Result.err(new ConflictError({
+      message: `File is already locked: ${path}`
+    }));
+  }
+  const lock = {
+    path,
+    lockPath,
+    pid: process.pid,
+    timestamp: Date.now()
+  };
+  try {
+    await fsWriteFile(lockPath, JSON.stringify({ pid: lock.pid, timestamp: lock.timestamp }), { flag: "wx" });
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+      return Result.err(new ConflictError({
+        message: `File is already locked: ${path}`
+      }));
+    }
+    throw error;
+  }
+  return Result.ok(lock);
+}
+async function releaseLock(lock) {
+  try {
+    await unlink(lock.lockPath);
+    return Result.ok(undefined);
+  } catch (error) {
+    return Result.err(new InternalError({
+      message: error instanceof Error ? error.message : "Failed to release lock"
+    }));
+  }
+}
+async function withLock(path, callback) {
+  const lockResult = await acquireLock(path);
+  if (lockResult.isErr()) {
+    return lockResult;
+  }
+  const lock = lockResult.value;
+  try {
+    const result = await callback();
+    const releaseResult = await releaseLock(lock);
+    if (releaseResult.isErr()) {
+      return releaseResult;
+    }
+    return Result.ok(result);
+  } catch (error) {
+    const releaseResult = await releaseLock(lock);
+    if (releaseResult.isErr()) {
+      return Result.err(new InternalError({
+        message: `Callback failed: ${error instanceof Error ? error.message : "Unknown error"}; lock release also failed: ${releaseResult.error.message}`
+      }));
+    }
+    return Result.err(new InternalError({
+      message: error instanceof Error ? error.message : "Callback failed"
+    }));
+  }
+}
+function isLocked(path) {
+  const lockPath = `${path}.lock`;
+  return Bun.file(lockPath).exists();
+}
+async function atomicWrite(path, content, options) {
+  const createParentDirs = options?.createParentDirs ?? true;
+  const parentDir = dirname(path);
+  const randomSuffix = Math.random().toString(36).slice(2, 10);
+  const tempPath = `${path}.${process.pid}.${Date.now()}.${randomSuffix}.tmp`;
+  try {
+    if (createParentDirs) {
+      await mkdir(parentDir, { recursive: true });
+    }
+    let mode = options?.mode ?? 420;
+    if (options?.preservePermissions) {
+      try {
+        const stats = await stat(path);
+        mode = stats.mode;
+      } catch {}
+    }
+    await fsWriteFile(tempPath, content, { mode });
+    await rename(tempPath, path);
+    return Result.ok(undefined);
+  } catch (error) {
+    try {
+      await unlink(tempPath);
+    } catch {}
+    return Result.err(new InternalError({
+      message: error instanceof Error ? error.message : "Atomic write failed"
+    }));
+  }
+}
+async function atomicWriteJson(path, data, options) {
+  try {
+    const content = JSON.stringify(data);
+    return await atomicWrite(path, content, options);
+  } catch (error) {
+    return Result.err(new ValidationError({
+      message: error instanceof Error ? error.message : "Failed to serialize JSON",
+      field: "data"
+    }));
+  }
+}
+export {
+  withLock,
+  securePath,
+  resolveSafePath,
+  releaseLock,
+  isPathSafe,
+  isLocked,
+  isInsideWorkspace,
+  globSync,
+  glob,
+  getRelativePath,
+  findWorkspaceRoot,
+  atomicWriteJson,
+  atomicWrite,
+  acquireLock
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@outfitter/file-ops",
+  "description": "Workspace detection, secure path handling, and file locking for Outfitter",
+  "version": "0.1.0-rc.1",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "bunup --filter @outfitter/file-ops",
+    "lint": "biome lint ./src",
+    "lint:fix": "biome lint --write ./src",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@outfitter/contracts": "workspace:*",
+    "@outfitter/types": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.8.0"
+  },
+  "keywords": [
+    "outfitter",
+    "file-ops",
+    "workspace",
+    "security",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/outfitter-dev/outfitter.git",
+    "directory": "packages/file-ops"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}