Merge pull request #1 from devitools/copilot/add-main-branch

CLAUDE.md

@@ -25,53 +25,6 @@ Both projects share:
 
 The key difference is that Effulgence leverages Laravel's ecosystem (Eloquent, service providers, middleware, artisan commands, etc.) instead of Hyperf's (annotations, coroutines, config providers).
 
-## Serendipity Reference Architecture
-
-Use Serendipity's structure as a reference for the capabilities Effulgence should provide, adapted to Laravel idioms:
-
-```
-serendipity/src/
-├── Domain/                     # Pure business logic (framework-agnostic)
-│   ├── Collection/             # Type-safe collections
-│   ├── Contract/               # Interfaces (Adapter, Support, Testing)
-│   │   └── Adapter/            # Serializer/Deserializer contracts
-│   ├── Event/                  # Domain events
-│   ├── Exception/              # Domain exceptions
-│   └── Support/                # Domain utilities
-├── Infrastructure/             # Technical implementations
-│   ├── Adapter/                # Serialize/Deserialize implementations
-│   ├── Database/               # Database concerns
-│   ├── File/                   # File handling
-│   ├── Http/                   # HTTP client concerns
-│   ├── Logging/                # Logging infrastructure
-│   └── Repository/             # Repository implementations
-│       ├── Repository.php      #   Base repository
-│       ├── PostgresRepository.php
-│       ├── MongoRepository.php
-│       ├── HttpRepository.php
-│       └── SleekDBRepository.php
-├── Presentation/               # External interfaces
-│   ├── Input/                  # Input handling
-│   ├── Output/                 # Output formatting
-│   ├── Input.php               # Base input (validation rules)
-│   ├── Output.php              # Base output
-│   └── ReflectorInput.php      # Reflection-based input
-├── Hyperf/                     # **Hyperf-specific bindings** (Effulgence replaces this with Laravel/)
-│   ├── Command/
-│   ├── Database/
-│   ├── Event/
-│   ├── Exception/
-│   ├── Listener/
-│   ├── Logging/
-│   ├── Middleware/
-│   ├── Request/
-│   ├── Support/
-│   └── Testing/
-├── Testing/                    # Test utilities
-├── Example/                    # Reference implementations
-└── ConfigProvider.php          # Hyperf config (Effulgence uses ServiceProvider)
-```
-
 ### Mapping Hyperf concepts to Laravel
 
 | Serendipity (Hyperf) | Effulgence (Laravel) |
@@ -86,44 +39,82 @@ serendipity/src/
 
 ## Repository Status
 
-This project is in its initial stage. The structure below will evolve as development progresses.
+The core implementation is complete with **119 source files** and a comprehensive test suite with **332 tests** and **878 assertions**. The project covers all major DDD layers and Laravel integrations.
 
-## Expected Directory Structure
+## Directory Structure
 
 ```
 effulgence/
 ├── src/
-│   ├── Domain/                 # Pure business logic (can mirror Serendipity's Domain/)
-│   │   ├── Collection/
-│   │   ├── Contract/
-│   │   ├── Event/
-│   │   ├── Exception/
-│   │   └── Support/
-│   ├── Infrastructure/         # Technical implementations
-│   │   ├── Adapter/
-│   │   ├── Database/
-│   │   ├── File/
-│   │   ├── Http/
-│   │   ├── Logging/
-│   │   └── Repository/
-│   ├── Presentation/           # Input/Output handling
-│   │   ├── Input/
-│   │   └── Output/
-│   ├── Laravel/                # Laravel-specific bindings (replaces Hyperf/)
-│   │   ├── Command/
-│   │   ├── Database/
-│   │   ├── Event/
-│   │   ├── Exception/
-│   │   ├── Listener/
-│   │   ├── Logging/
-│   │   ├── Middleware/
-│   │   ├── Request/
-│   │   ├── Support/
-│   │   └── Testing/
-│   ├── Testing/
-│   └── EffulgenceServiceProvider.php
-├── config/
+│   ├── Domain/                          # Pure business logic (framework-agnostic)
+│   │   ├── Collection/                  # Type-safe collections (Collection)
+│   │   ├── Contract/                    # Interfaces
+│   │   │   ├── Adapter/                 # Serializer/Deserializer contracts
+│   │   │   ├── Support/                 # ThrownFactory contract
+│   │   │   └── Testing/                 # Faker, Helper contracts
+│   │   ├── Event/                       # Domain events (RequestExecuted, ValidationFailed)
+│   │   ├── Exception/                   # Domain exceptions and parsing
+│   │   │   └── Parser/                  # Thrown, Additional, DefaultThrownFactory
+│   │   └── Support/                     # Domain utilities (Task, Truncate)
+│   ├── Infrastructure/                  # Technical implementations
+│   │   ├── Adapter/                     # Serialize/Deserialize via Constructo
+│   │   │   ├── Deserialize/             # Demolisher
+│   │   │   └── Serialize/               # Builder
+│   │   ├── Database/                    # Database concerns
+│   │   │   ├── Document/                # MongoDB/SleekDB (conditions, search, factories)
+│   │   │   │   └── Mongo/              # Condition parser, search engine
+│   │   │   │       └── Condition/      # Between, Equal, In, Regex conditions
+│   │   │   └── Relational/             # Connection, ConnectionChecker, ConnectionFactory
+│   │   ├── File/                        # File handling (RulesGenerator)
+│   │   ├── Http/                        # HTTP concerns (JsonFormatter, ExceptionResponseNormalizer)
+│   │   ├── Logging/                     # StdoutLogger, GoogleCloudLogger, AbstractLogger
+│   │   └── Repository/                  # Repository implementations
+│   │       ├── Adapter/                 # Mongo/Relational serializer factories
+│   │       ├── Formatter/               # Type-specific formatters (datetime, json, arrays)
+│   │       ├── HttpRepository.php       # Guzzle-based HTTP repository
+│   │       ├── MongoRepository.php      # MongoDB repository
+│   │       ├── PostgresRepository.php   # PostgreSQL repository
+│   │       ├── Repository.php           # Base repository
+│   │       └── SleekDBRepository.php    # SleekDB repository
+│   ├── Presentation/                    # Input/Output handling
+│   │   ├── Input/                       # Mapped, Params, Resolver
+│   │   ├── Output/                      # JSend-style response classes
+│   │   │   ├── Error/                   # 5xx error responses (10 classes)
+│   │   │   └── Fail/                    # 4xx fail responses (25+ classes)
+│   │   ├── Input.php                    # Base input (validation rules)
+│   │   ├── Output.php                   # Base output
+│   │   └── ReflectorInput.php           # Reflection-based input
+│   ├── Laravel/                         # Laravel-specific bindings
+│   │   ├── Command/                     # Artisan commands (GenerateRules)
+│   │   ├── Database/                    # Laravel DB implementations
+│   │   │   ├── Document/               # LaravelMongoFactory, LaravelSleekDBFactory
+│   │   │   └── Relational/             # LaravelConnection, Checker, Factory
+│   │   │       └── Support/            # HasPostgresUniqueConstraint
+│   │   ├── Event/                       # HTTP handle events
+│   │   ├── Exception/                   # Exception handlers (General, Validation)
+│   │   ├── Listener/                    # SentryHttpListener
+│   │   ├── Logging/                     # Logger factories (Stdout, GoogleCloud)
+│   │   ├── Middleware/                  # CORS, ConnectionChecker, Task, HttpHandler
+│   │   ├── Request/                     # LaravelFormRequest
+│   │   ├── Support/                     # Specs, Thrown, Types factories
+│   │   └── Testing/                     # Test extensions and mocks
+│   │       ├── Extension/               # Input, Logger, Make extensions
+│   │       ├── Mock/                    # Extension mocks
+│   │       └── Observability/           # InMemoryLogger for testing
+│   ├── Testing/                         # Framework-agnostic test utilities
+│   │   ├── Extension/                   # ResourceExtension
+│   │   ├── Mock/                        # ResourceExtensionMock
+│   │   └── Resource/                    # AbstractHelper
+│   ├── _/runtime.php                    # Runtime functions (invoke, dispatch)
+│   └── EffulgenceServiceProvider.php    # Laravel service provider
 ├── tests/
+│   ├── Domain/Entity/                   # Entity tests
+│   ├── Infrastructure/                  # Adapter, Database, Exception, Http, Logger, Repository tests
+│   ├── Presentation/                    # Output tests (Success, Fail, Error parametrized)
+│   ├── Laravel/                         # Exception, Middleware, Support, Logging, Database tests
+│   ├── Testing/                         # Test stubs and fixtures
+│   ├── _/                               # Runtime function tests
+│   └── bootstrap.php                    # Test bootstrap
 ├── composer.json
 ├── phpstan.neon
 ├── phpunit.xml
@@ -146,31 +137,42 @@ composer install          # Install dependencies
 composer test             # Run tests
 composer lint             # Run static analysis (PHPStan, Psalm, etc.)
 composer fix              # Auto-fix code style
+composer ci               # Run lint + test
 ```
 
 ### Testing
 
-- **Framework**: PHPUnit
+- **Framework**: PHPUnit 11
+- **Tests**: 332 tests, 878 assertions
+- **Skipped**: 3 tests require `ext-mongodb` (annotated with `#[RequiresPhpExtension('mongodb')]`)
 - Run: `composer test` or `./vendor/bin/phpunit`
-- Mirror Serendipity's quality standards: PHPStan, Psalm, PHP CS Fixer, PHPMD, Rector
+- Run without coverage: `./vendor/bin/phpunit --no-coverage`
+- Test namespace: `Effulgence\Test\`
+- Bootstrap: `tests/bootstrap.php`
 
 ### Key Dependencies
 
 | Package | Purpose |
 |---|---|
 | `devitools/constructo` | Metaprogramming foundation (shared with Serendipity) |
-| `laravel/framework` | Core framework |
+| `laravel/framework` | Core framework (^11.0 or ^12.0) |
+| `mongodb/mongodb` | MongoDB driver |
+| `guzzlehttp/guzzle` | HTTP client for HttpRepository |
+| `mustache/mustache` | Template engine for StdoutLogger |
+| `rakibtg/sleekdb` | Flat-file NoSQL database |
+| `sentry/sentry-laravel` | Error tracking |
 | `phpstan/phpstan` | Static analysis |
-| `phpunit/phpunit` | Testing |
+| `phpunit/phpunit` | Testing (^10.5 or ^11.0) |
 | `vimeo/psalm` | Type checking |
+| `orchestra/testbench` | Laravel package testing |
 
 ## Key Conventions
 
 ### Code Style
 
 - PHP 8.3+ with strict types (`declare(strict_types=1)`)
 - Readonly classes and properties for entities
-- Use PHP 8 attributes for metadata (validation rules, serialization hints)
+- Use PHP 8 attributes for metadata (validation rules, serialization hints, test requirements)
 - PSR-4 autoloading under the `Effulgence\` namespace
 - Follow the same patterns established in Serendipity
 
@@ -181,14 +183,26 @@ composer fix              # Auto-fix code style
 - **Presentation** handles input validation and output formatting
 - **Laravel/** contains all framework-specific bindings and adapters
 - Contracts (interfaces) live in `Domain/Contract/`, implementations in `Infrastructure/`
+- Runtime functions (`invoke`, `dispatch`) live in `src/_/runtime.php`
 
 ### Naming
 
 - Namespace: `Effulgence\`
+- Test namespace: `Effulgence\Test\`
 - Service provider: `EffulgenceServiceProvider`
 - Follow Laravel conventions for artisan commands, middleware, events, etc.
 - Follow Serendipity conventions for domain concepts (entities, repositories, collections)
 
+### Testing Patterns
+
+- Tests mirror the `src/` directory structure under `tests/`
+- Test stubs and fixtures live in `tests/Testing/Stub/`
+- Repository tests use concrete mock classes (e.g., `HttpRepositoryTestMock`) to expose protected methods
+- Parametrized tests use PHPUnit `#[DataProvider]` for Success/Fail/Error output classes
+- Tests requiring Laravel container set up `Container::getInstance()` with needed bindings in `setUp()`
+- Tests requiring facades set up `Facade::setFacadeApplication()` and clean up in `tearDown()`
+- MongoDB-dependent tests use `#[RequiresPhpExtension('mongodb')]` to skip gracefully
+
 ## For AI Assistants
 
 When working in this repository: