feat: add content adapter pattern for dynamic and remote files

[davydog187]

Overview

Adds support for different file content backends via an adapter protocol, enabling function-backed, S3-backed, and other lazy content types.

Motivation

The virtual filesystem previously only supported static binary content. This PR enables:

• Dynamic files backed by functions (e.g., timestamps, computed values)
• Remote files backed by S3 or other storage (with user-provided clients)
• Deferred evaluation with explicit caching via materialization

Implementation

Architecture

Uses an Elixir Protocol (ContentAdapter) that dispatches on content data type:

• BitString - Identity implementation (existing binary content)
• FunctionContent - Calls function on each read (supports anonymous, captured, MFA)
• S3Content - Delegates to user-provided client (scaffold)

Key Design Decisions

1. Minimal blast radius - read_file/2 changed one line to use ContentAdapter.resolve(content). All 24+ commands work unchanged.
2. Explicit caching - materialize_files/1 for caching, not hidden in read_file/2
3. Protocol over Behaviour - Dispatch on data type (proper polymorphism)
4. Test-first - Followed CLAUDE.md convention strictly

Changes

New Files:

• lib/just_bash/fs/content_adapter.ex - Protocol definition + BitString impl
• lib/just_bash/fs/content/function_content.ex - Function-backed content
• lib/just_bash/fs/content/s3_content.ex - S3-backed content (scaffold)
• test/fs/content_adapter_test.exs - Protocol tests (17 tests)
• test/commands/content_adapter_integration_test.exs - Integration tests (35 tests)
• examples/content_adapters.exs - Usage examples

Modified Files:

• lib/just_bash/fs/in_memory_fs.ex - Use ContentAdapter protocol, add materialize functions
• lib/just_bash.ex - Support adapters in new/1, add materialize_files/1
• lib/just_bash/fs/fs.ex - Add materialize delegates
• lib/just_bash/commands/cat.ex - Add catch-all error clause
• README.md - Document content adapters
• test/in_memory_fs_test.exs - Add 61 tests for adapter functionality

Usage

# Function-backed file (called on each read)
bash = JustBash.new(files: %{
  "/timestamp.txt" => fn -> "Generated at #{DateTime.utc_now()}" end
})

{result, bash} = JustBash.exec(bash, "cat /timestamp.txt")
# Output: "Generated at 2026-02-13 19:07:20.146524Z"

# MFA tuple (serialization-friendly)
alias JustBash.Fs.Content.FunctionContent
bash = JustBash.new(files: %{
  "/upper.txt" => FunctionContent.new({String, :upcase, ["hello world"]})
})

# Materialize to cache results
{:ok, bash} = JustBash.materialize_files(bash)
# Now functions won't be called again

# S3-backed file (bring your own client)
alias JustBash.Fs.Content.S3Content
bash = JustBash.new(files: %{
  "/remote.txt" => S3Content.new(
    bucket: "my-bucket",
    key: "file.txt",
    client: MyS3Client
  )
})

Testing

• ✅ 113 new tests covering protocol implementations and integration
• ✅ All 2510 existing tests pass - No regressions
• ✅ Zero compilation warnings with --warnings-as-errors
• ✅ Example script demonstrates usage patterns

mix test                              # All pass
mix compile --warnings-as-errors      # Zero warnings
mix run examples/content_adapters.exs # Demonstrates features

Breaking Changes

None. The changes are fully backward compatible:

• Existing code using files: %{"/path" => "content"} works unchanged
• All existing commands work with new content types automatically
• API signatures preserved (return types unchanged)

Future Enhancements

Possible extensions:

• HTTP-backed content adapter
• Database-backed content adapter
• Content streaming for large files
• Content transformations (compression, encryption)

---

🤖 Generated with Claude Code

[davydog187]

what does this think this is, Haskell?

[AlexGx]

this is typespec for anon func with zero arity https://hexdocs.pm/elixir/typespecs.html#literals