feat(workspace-fs): implement async FileSystem trait with 24 methods

[miguelramos]

Define the core FileSystem trait using native async fn (no async-trait crate). The trait requires Send + Sync and provides complete filesystem abstraction: read/write ops, metadata queries, directory management, file operations, path resolution, symlink handling, and recursive directory traversal.

• traits.rs: 24 async methods with full doc comments and FR references
• lib.rs: enable pub use traits::FileSystem re-export
• docs/DECISIONS.md: ADR-001 documenting native async trait decision

Bead: workspace-node-tools-kzd.1

Summary by CodeRabbit

Release Notes

• New Features

  • FileSystem trait is now publicly available, providing asynchronous operations for reading, writing, file metadata, and directory management.

• Documentation

  • Added architecture decision documentation for FileSystem trait design.

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

The pull request introduces a comprehensive FileSystem trait with 24+ native async methods for filesystem operations, exports it as public API, and documents the architectural decision to use native async fn instead of async_trait macros.

Changes

Cohort / File(s)	Summary
Trait Definition & Public Exposure crates/filesystem/src/traits.rs, crates/filesystem/src/lib.rs	Introduces a new public FileSystem trait with 24+ async methods covering read, write, append, metadata, symlink, directory, and path operations using native async fn. Re-exports the trait from lib.rs to expose it as public API.
Architectural Documentation docs/DECISIONS.md	Adds ADR-001 documenting the decision to use native async fn over async_trait, outlining context, rationale (zero overhead, no proc-macro dependency), consequences, mitigations, and alternative approaches for future dyn support.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A filesystem trait so clean and bright,
With async methods, native and light,
No macros needed, just pure Rust code,
Pathways of data on a swift, steady road,
The API stands tall, exposing with care! ✨

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch kzd1/filesystem-trait

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[miguelramos]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.