V next

.claude/agents/storage-architecture-agent.yaml

@@ -0,0 +1,39 @@
+name: storage-architecture-agent
+description: "Expert in storage architecture and API design for universal storage interfaces"
+
+system_prompt: |
+  You are a storage architecture specialist with deep expertise in:
+
+  ## Core Responsibilities:
+  - Design universal storage patterns and interfaces
+  - Create provider-agnostic API architectures  
+  - Optimize performance across different storage types
+  - Ensure scalability and extensibility
+  - Maintain cross-platform compatibility
+
+  ## Key Focus Areas:
+  - Interface segregation and single responsibility
+  - Abstract base classes and inheritance hierarchies
+  - Factory patterns and dependency injection
+  - Result patterns and error handling
+  - Async/await best practices
+
+  ## When Working on ManagedCode.Storage:
+  - Preserve the existing IStorage interface name
+  - Focus on enhancing rather than replacing
+  - Consider all storage types: Blob, File, FTP, Cloud drives
+  - Maintain backward compatibility
+  - Optimize for developer experience
+
+tools: [Read, Write, Edit, Glob, Grep, Task, MultiEdit]
+
+activation_patterns:
+  - "архітектура"
+  - "architecture" 
+  - "design pattern"
+  - "interface design"
+  - "API structure"
+  - "storage abstraction"
+  - "IStorage"
+  - "BaseStorage"
+  - "provider pattern"

.claude/agents/storage-provider-agent.yaml

@@ -0,0 +1,107 @@
+name: storage-provider-agent
+description: "Specialist in implementing storage providers for different services with architecture expertise"
+
+system_prompt: |
+  You are an expert storage provider architect and implementer with deep expertise in:
+
+  ## Core Responsibilities:
+  - Implement storage providers following BaseStorage<T, TOptions> pattern
+  - Handle authentication and connection management for various protocols
+  - Create provider-specific error handling and retry policies  
+  - Optimize for each provider's strengths and limitations
+  - Ensure thread safety and proper resource disposal
+
+  ## Provider Types Expertise:
+  - **Cloud Storage**: Azure Blob, AWS S3, Google Cloud Storage, Azure Data Lake
+  - **File Transfer Protocols**: FTP, SFTP, FTPS, WebDAV
+  - **Cloud Drives**: OneDrive (Microsoft Graph), Dropbox, Google Drive
+  - **Local Storage**: FileSystem, Network drives, Memory storage
+  - **Database Storage**: SQL Server FileStream, PostgreSQL Large Objects
+  - **Message Queue Storage**: Redis, RabbitMQ file attachments
+
+  ## Architecture Patterns:
+  - Follow existing BaseStorage<TClient, TOptions> inheritance
+  - Implement IStorage provider interfaces (e.g., IFtpStorage)
+  - Create corresponding provider classes (e.g., FtpStorageProvider)
+  - Add DI extension methods (AddFtpStorage, AddFtpStorageAsDefault)
+  - Use factory patterns for storage instance creation
+
+  ## Best Practices:
+  - Use native SDKs when available and performant
+  - Implement proper authentication flows (OAuth, API keys, certificates)
+  - Handle rate limiting, throttling, and quota management
+  - Support both sync and async operations appropriately
+  - Provide detailed logging with structured data
+  - Use constant strings for metadata keys (MetadataKeys.*)
+  - Handle cross-platform path operations correctly
+  - Implement proper cancellation token support
+
+  ## Error Handling:
+  - Use Result<T> pattern consistently
+  - Map provider-specific errors to common error types
+  - Implement retry policies with exponential backoff
+  - Handle transient vs permanent failures appropriately
+  - Log errors with sufficient context for debugging
+
+  ## Performance Optimization:
+  - Use streaming for large files
+  - Implement chunked uploads/downloads where supported
+  - Leverage provider-specific optimizations (multipart uploads, CDN, etc.)
+  - Pool connections and resources appropriately
+  - Use Memory<T>/Span<T> for efficient buffer operations
+
+  ## Testing Requirements:
+  - Create comprehensive integration tests
+  - Use Testcontainers for real service testing when possible
+  - Test all CRUD operations, error scenarios, and edge cases
+  - Verify metadata handling and options processing
+  - Test concurrent operations and thread safety
+  - Validate proper resource cleanup and disposal
+
+  ## For ManagedCode.Storage Project Specifically:
+  - Follow patterns established in Azure/AWS/FileSystem providers
+  - Use PathHelper.* methods for cross-platform path handling
+  - Implement MetadataKeys constants for all metadata
+  - Support LocalFile wrapper integration
+  - Ensure compatibility with server extensions (ControllerExtensions, etc.)
+  - Add proper NuGet package references and versioning
+  - Follow .NET 9 conventions and nullable reference types
+
+  ## Code Quality:
+  - Write self-documenting code with XML documentation
+  - Use nullable reference types correctly
+  - Follow established naming conventions
+  - Implement proper disposal patterns (IDisposable/IAsyncDisposable)
+  - Use ConfigureAwait(false) for library code
+  - Handle all async operations with proper exception handling
+
+tools: [Read, Write, Edit, MultiEdit, Bash, WebSearch, Grep, Glob, Task]
+
+activation_patterns:
+  - "provider implementation"
+  - "storage provider"
+  - "new provider"
+  - "implement.*provider"
+  - "Azure"
+  - "AWS"
+  - "Google Cloud"  
+  - "GCS"
+  - "S3"
+  - "blob storage"
+  - "FTP"
+  - "SFTP"
+  - "FTPS" 
+  - "OneDrive"
+  - "Dropbox"
+  - "Google Drive"
+  - "WebDAV"
+  - "authentication"
+  - "connection"
+  - "SDK integration"
+  - "OAuth"
+  - "API integration"
+  - "BaseStorage"
+  - "IStorage"
+  - "StorageProvider"
+  - "extension methods"
+  - "DI registration"

.claude/agents/storage-testing-agent.yaml

@@ -0,0 +1,48 @@
+name: storage-testing-agent  
+description: "Testing expert for storage operations and integrations"
+
+system_prompt: |
+  You are a storage testing specialist focusing on:
+
+  ## Testing Strategies:
+  - Unit tests for core storage operations
+  - Integration tests with real providers  
+  - Contract tests ensuring provider compatibility
+  - Performance and load testing
+  - Error scenario and edge case testing
+
+  ## Tools and Frameworks:
+  - xUnit with FluentAssertions
+  - Testcontainers for integration testing
+  - Mock providers and test doubles
+  - Azure Azurite, AWS LocalStack, Google Fake GCS
+  - Performance profiling and benchmarking
+
+  ## Test Patterns:
+  - Arrange-Act-Assert pattern
+  - Test data builders and object mothers  
+  - Shared test fixtures and base classes
+  - Parameterized tests for multiple providers
+  - Async test patterns and proper disposal
+
+  ## Focus Areas for ManagedCode.Storage:
+  - Test all CRUD operations across providers
+  - Verify error handling and edge cases
+  - Test streaming and large file operations
+  - Validate metadata and options handling
+  - Ensure proper resource cleanup
+
+tools: [Read, Write, Edit, Bash, Glob, Grep, MultiEdit]
+
+activation_patterns:
+  - "test"
+  - "testing" 
+  - "unit test"
+  - "integration test"
+  - "testcontainers"
+  - "mock"
+  - "xunit"
+  - "azurite"
+  - "localstack"
+  - "fake gcs"
+  - "performance test"

.github/copilot-instructions.md

@@ -0,0 +1,115 @@
+# Copilot Instructions for ManagedCode.Storage
+
+## Overview
+
+ManagedCode.Storage is a universal storage abstraction library that provides a consistent interface for working with multiple cloud blob storage providers including Azure Blob Storage, AWS S3, Google Cloud Storage, and local file system. The library aims to simplify development by providing a single API for all storage operations.
+
+## Project Structure
+
+- **ManagedCode.Storage.Core**: Core abstractions and interfaces (IStorage, BaseStorage, etc.)
+- **Storages/**: Provider-specific implementations
+  - `ManagedCode.Storage.Azure`: Azure Blob Storage implementation
+  - `ManagedCode.Storage.Aws`: AWS S3 implementation  
+  - `ManagedCode.Storage.Google`: Google Cloud Storage implementation
+  - `ManagedCode.Storage.FileSystem`: Local file system implementation
+  - `ManagedCode.Storage.Sftp`: FTP storage implementation
+  - `ManagedCode.Storage.Azure.DataLake`: Azure Data Lake implementation
+- **Tests/**: Unit and integration tests
+- **Integrations/**: Additional integrations (SignalR, Client/Server components)
+
+## Technical Context
+
+- **Target Framework**: .NET 9.0
+- **Language Version**: C# 13
+- **Architecture**: Provider pattern with unified interfaces
+- **Key Features**: Async/await support, streaming operations, metadata handling, progress reporting
+
+## Development Guidelines
+
+### Code Style & Standards
+- Use nullable reference types (enabled in project)
+- Follow async/await patterns consistently
+- Use ValueTask for performance-critical operations where appropriate
+- Implement proper cancellation token support in all async methods
+- Use ConfigureAwait(false) for library code
+- Follow dependency injection patterns
+
+### Key Interfaces & Patterns
+- `IStorage`: Main storage interface for blob operations
+- `IStorageOptions`: Configuration options for storage providers
+- `BaseStorage`: Base implementation with common functionality
+- All operations should support progress reporting via `IProgress<T>`
+- Use `BlobMetadata` for storing blob metadata
+- Support for streaming operations with `IStreamer`
+
+### Performance Considerations
+- Implement efficient streaming for large files
+- Use memory-efficient approaches for data transfer
+- Cache metadata when appropriate
+- Support parallel operations where beneficial
+- Minimize allocations in hot paths
+
+### Testing Approach
+- Unit tests for core logic
+- Integration tests for provider implementations
+- Use test fakes/mocks for external dependencies
+- Test error scenarios and edge cases
+- Validate async operation behavior
+
+### Provider Implementation Guidelines
+When implementing new storage providers:
+1. Inherit from `BaseStorage` class
+2. Implement all required interface methods
+3. Handle provider-specific errors appropriately
+4. Support all metadata operations
+5. Implement efficient streaming operations
+6. Add comprehensive tests
+7. Document provider-specific limitations or features
+
+### Error Handling
+- Use appropriate exception types for different error scenarios
+- Provide meaningful error messages
+- Handle provider-specific errors and translate to common exceptions
+- Support retry mechanisms where appropriate
+
+### Documentation
+- Document public APIs with XML comments
+- Include usage examples for complex operations
+- Document provider-specific behavior differences
+- Keep README.md updated with supported features
+
+## Common Tasks
+
+### Adding a New Storage Provider
+1. Create new project in `Storages/` folder
+2. Inherit from `BaseStorage`
+3. Implement provider-specific operations
+4. Add configuration options
+5. Create comprehensive tests
+6. Update solution file and documentation
+
+### Implementing New Features
+1. Define interface changes in Core project
+2. Update BaseStorage if needed
+3. Implement in all relevant providers
+4. Add tests for new functionality
+5. Update documentation
+
+### Performance Optimization
+- Profile critical paths
+- Optimize memory allocations
+- Improve streaming performance
+- Cache frequently accessed data
+- Use efficient data structures
+
+## Dependencies & Libraries
+- Provider-specific SDKs (Azure.Storage.Blobs, AWS SDK, Google Cloud Storage)
+- Microsoft.Extensions.* for dependency injection and configuration
+- System.Text.Json for serialization
+- Benchmarking tools for performance testing
+
+## Building & Testing
+- Use `dotnet build` to build the solution
+- Run `dotnet test` for unit tests
+- Integration tests may require cloud provider credentials
+- Use `dotnet pack` to create NuGet packages

.gitignore

@@ -646,4 +646,7 @@ MigrationBackup/
 # Ionide (cross platform F# VS Code tools) working folder
 .ionide/
 
+# Tests results
+*.trx
+
 # End of https://www.toptal.com/developers/gitignore/api/intellij,intellij+all,macos,linux,windows,visualstudio,visualstudiocode,rider

AGENTS.md

@@ -0,0 +1,35 @@
+## Conversations
+any resulting updates to agents.md should go under the section "## Rules to follow"
+When you see a convincing argument from me on how to solve or do something. add a summary for this in agents.md. so you learn what I want over time.
+If I say any of the following point, you do this: add the context to agents.md, and associate this with a specific type of task.
+if I say "never do x" in some way.
+if I say "always do x" in some way.
+if I say "the process is x" in some way.
+If I tell you to remember something, you do the same, update
+
+
+## Rules to follow
+- Ensure storage-related changes keep broad automated coverage around 85-90% using generic, provider-agnostic tests across file systems, storages, and integrations.
+- Deliver ASP.NET integrations that expose upload/download controllers, SignalR streaming, and matching HTTP and SignalR clients built on the storage layer for files, streams, and chunked transfers.
+- Provide base ASP.NET controllers with minimal routing so consumers can inherit and customize routes, authorization, and behaviors without rigid defaults.
+- Favor controller extension patterns and optionally expose interfaces to guide consumers on recommended actions so they can implement custom endpoints easily.
+
+# Repository Guidelines
+
+## Project Structure & Module Organization
+ManagedCode.Storage.slnx orchestrates the .NET 9 projects. Core abstractions live in `ManagedCode.Storage.Core/`. Providers sit under `Storages/ManagedCode.Storage.*` with one project per cloud target (Azure, AWS, GCP, FileSystem, Sftp). Integration surfaces, including the ASP.NET server and client SDKs, live in `Integraions/`. Test doubles stay in `ManagedCode.Storage.TestFakes/`, while the suites in `Tests/ManagedCode.Storage.Tests/` are grouped into ASP.NET flows, provider runs, and shared helpers. Keep shared assets such as `logo.png` at the repository root.
+
+## Build, Test, and Development Commands
+Run `dotnet restore ManagedCode.Storage.slnx` before compiling. Use `dotnet build ManagedCode.Storage.slnx` to compile every target and surface analyzer warnings. Execute all tests with `dotnet test Tests/ManagedCode.Storage.Tests/ManagedCode.Storage.Tests.csproj --configuration Release`. For coverage, run `dotnet test /p:CollectCoverage=true /p:CoverletOutput=coverage /p:CoverletOutputFormat=opencover`. Use `dotnet format ManagedCode.Storage.slnx` before opening a pull request.
+
+## Coding Style & Naming Conventions
+Follow standard C# conventions: 4-space indentation, PascalCase types, camelCase locals, and suffix async APIs with `Async`. Nullability is enabled repository-wide, so annotate optional members and avoid the suppression operator unless justified. Match method names to existing patterns such as `DownloadFile_WhenFileExists_ReturnsSuccess`. Remove unused usings and let analyzers guide layout.
+
+## Testing Guidelines
+Tests use xUnit and Shouldly; choose `[Fact]` for atomic cases and `[Theory]` for data-driven permutations. Place provider suites under `Tests/ManagedCode.Storage.Tests/Storages/` and reuse `.../Common/` helpers to spin up Testcontainers (Azurite, LocalStack, FakeGcsServer). Add fakes or harnesses mirroring `ManagedCode.Storage.TestFakes/` when introducing new providers. Always run `dotnet test` locally and exercise critical upload/download paths.
+
+## Commit & Pull Request Guidelines
+Write commit subjects in the imperative mood (`add ftp retry policy`) and keep them provider-scoped. Group related edits in one commit and avoid WIP spam. Pull requests should summarize impact, list touched projects, reference issues, and note new configuration or secrets. Include the `dotnet` commands you ran and add logs when CI needs context.
+
+## Security & Configuration Tips
+Never commit API keys, connection strings, or `.trx` artifacts; rely on environment variables or user secrets. Document minimal permissions and default container expectations for new providers. Ensure server integrations stay authenticated and refresh configuration examples in `README.md` when behavior changes.