docs(file-ops): add README, CHANGELOG, and TSDoc comments

[galligan]

Summary

Adds comprehensive documentation to @outfitter/file-ops package:

• README.md — Installation, quick start, security considerations, workspace detection, file locking, atomic writes
• CHANGELOG.md — Initial 0.1.0 release notes
• TSDoc comments — All exported functions, types, and interfaces documented with @param, @returns, and @example

Highlights

• Security documentation — Path traversal protection, null byte rejection, symlink detection
• Documents workspace marker priority (.git, package.json)
• Shows advisory file locking with withLock() pattern
• Covers atomic writes (temp file + rename)

Test plan

• bun run typecheck passes
• bun run build succeeds

🤖 Generated with Claude Code

[galligan]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• chore(outfitter): sync templates on pack #108
• chore(changesets): ignore app package #107
• fix(errors): avoid TaggedError extends warnings #106
• chore(release): align package versions to 0.1.0 #105
• docs: add README and CHANGELOG for testing, kit, outfitter #95
• feat(templates): add daemon project template #94
• feat(templates): add MCP server project template #93
• feat(templates): add CLI project template #92
• fix(cli): implement confirmDestructive prompts #104
• fix(cli): implement createCLI and command builder #103
• feat(kit): add @outfitter/kit meta-package #91
• docs(daemon): add README and CHANGELOG #90
• fix(daemon): fix locking module bugs (GREEN phase) #89
• test(daemon): add locking module tests (RED phase) #88
• feat(daemon): add errors, platform, and locking module stubs #87
• feat(outfitter): add doctor command for environment validation #86
• feat(outfitter): add init command with project scaffolding #85
• feat(daemon): add IPC communication and health checks #84
• feat(daemon): add types and lifecycle management #83
• feat(index): add FTS5 full-text search implementation #82
• feat(index): add types for FTS5 full-text search #81
• feat(testing): add MCP and CLI test harnesses #80
• feat(testing): add test fixture utilities #79
• feat(mcp): add MCP server implementation with typed handlers #78
• feat(mcp): add types and interfaces for MCP server #77
• feat(ui): add Shape discriminated union and render() #76
• feat(ui): add createTokens semantic color layer #75
• feat(state): add pagination helpers #74
• feat(logging): add DEFAULT_PATTERNS for common secret redaction #73
• feat(ui): add formatRelative() for human-readable timestamps #72
• feat(state): add encodeCursor/decodeCursor for pagination #71
• feat(types): add hashId() for deterministic short identifiers #70
• feat(contracts): add Logger.child() and fix AssertionError category #69
• feat(config): centralize environment variable access with Zod validation #42
• fix(logging): enable redaction by default when global rules exist #41
• docs(ui): add README, CHANGELOG, and TSDoc comments #39
• docs(state): add README, CHANGELOG, and TSDoc comments #38
• docs(file-ops): add README, CHANGELOG, and TSDoc comments #37 👈 (View in Graphite)
• docs(logging): add README, CHANGELOG, and TSDoc comments #36
• docs(config): add README, CHANGELOG, and TSDoc comments #35
• fix(cli): enforce cursor TTL #114
• fix(tests): remove placeholder tests #113
• chore(gitattributes): prefer ours for bun lockfiles #115
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

• Adds comprehensive documentation to @outfitter/file-ops package including README, CHANGELOG, and TSDoc comments for all exported functions, types, and interfaces
• Documentation covers critical security features like path traversal protection, workspace detection, file locking patterns, and atomic write operations
• Follows established project conventions with proper @param, @returns, @defaultValue annotations and Result-based error handling examples

Important Files Changed

Filename	Overview
packages/file-ops/src/index.ts	Added comprehensive TSDoc documentation to all exported functions and interfaces with security warnings and usage examples
packages/file-ops/README.md	New comprehensive API documentation with installation guide, security model, and detailed usage examples for all features
packages/file-ops/CHANGELOG.md	New changelog documenting initial 0.1.0 release with complete feature inventory

Confidence score: 5/5

• This PR is extremely safe to merge as it only adds documentation without any functional code changes
• Score reflects documentation-only changes with no risk to existing functionality or behavior
• No files require special attention as all changes are purely additive documentation

Sequence Diagram

sequenceDiagram
    participant User
    participant FileOps as "@outfitter/file-ops"
    participant FileSystem as "File System"
    participant BunGlob as "Bun.Glob"

    Note over User, FileSystem: Workspace Detection Flow
    User->>FileOps: "findWorkspaceRoot(startPath, options?)"
    FileOps->>FileOps: "resolve(startPath)"
    loop "Walk up directory tree"
        FileOps->>FileSystem: "stat(markerPath)"
        FileSystem-->>FileOps: "marker exists/not found"
        alt "marker found"
            FileOps-->>User: "Result.ok(workspaceRoot)"
        else "continue search"
            FileOps->>FileOps: "dirname(currentDir)"
        end
    end

    Note over User, FileSystem: Secure Path Validation Flow
    User->>FileOps: "securePath(path, basePath)"
    FileOps->>FileOps: "validate null bytes"
    FileOps->>FileOps: "check path traversal"
    FileOps->>FileOps: "normalize and join paths"
    FileOps->>FileOps: "verify within basePath"
    FileOps-->>User: "Result.ok(safePath)"

    Note over User, BunGlob: Glob Pattern Matching Flow
    User->>FileOps: "glob(pattern, options?)"
    FileOps->>BunGlob: "new Bun.Glob(pattern)"
    FileOps->>FileOps: "createIgnoreFilter(options.ignore)"
    FileOps->>BunGlob: "glob.scan(scanOptions)"
    loop "for each matched file"
        BunGlob-->>FileOps: "file path"
        FileOps->>FileOps: "apply ignore filter"
        FileOps->>FileOps: "resolve to absolute path"
    end
    FileOps-->>User: "Result.ok(absolutePaths[])"

    Note over User, FileSystem: File Locking Flow
    User->>FileOps: "withLock(path, callback)"
    FileOps->>FileOps: "acquireLock(path)"
    FileOps->>FileSystem: "writeFile(lockPath, metadata, {flag: 'wx'})"
    FileSystem-->>FileOps: "lock acquired"
    FileOps->>User: "execute callback()"
    User-->>FileOps: "callback result"
    FileOps->>FileSystem: "unlink(lockPath)"
    FileSystem-->>FileOps: "lock released"
    FileOps-->>User: "Result.ok(callbackResult)"

    Note over User, FileSystem: Atomic Write Flow
    User->>FileOps: "atomicWrite(path, content, options?)"
    FileOps->>FileSystem: "mkdir(parentDir, {recursive: true})"
    FileOps->>FileOps: "generate tempPath"
    FileOps->>FileSystem: "writeFile(tempPath, content)"
    FileSystem-->>FileOps: "temp file written"
    FileOps->>FileSystem: "rename(tempPath, path)"
    FileSystem-->>FileOps: "atomic rename complete"
    FileOps-->>User: "Result.ok()"

Loading