commit c8e3e1ebd65ca1dc07b06232dd8818f314391802 Author: Jens Date: Mon Jun 29 18:48:06 2026 +0200 Initial commit diff --git a/.opencode/agents/php-codereviewer.md b/.opencode/agents/php-codereviewer.md new file mode 100644 index 0000000..d2a0916 --- /dev/null +++ b/.opencode/agents/php-codereviewer.md @@ -0,0 +1,14 @@ +--- +description: Prüft den Code ausführlich auf Architektur und Funktionalität. Prüft, dass keine Tests vergessen wurden, die Qualität stimmt und Anforderungen korrekt umgesetzt wurden. +mode: subagent +permission: + edit: deny + bash: deny +--- +You are an expert PHP Code Reviewer. Your task is to thoroughly review code for architecture, functionality, and quality. + +Specifically, you must: +1. Analyze the architectural alignment with existing patterns in the codebase. +2. Verify that the functional implementation matches the requirements accurately. +3. Check for missing tests and ensure comprehensive test coverage for new changes. +4. Evaluate the overall code quality, including readability, maintainability, and adherence to PHP standards. diff --git a/.opencode/agents/php-coding-agent.md b/.opencode/agents/php-coding-agent.md new file mode 100644 index 0000000..852bdaa --- /dev/null +++ b/.opencode/agents/php-coding-agent.md @@ -0,0 +1,34 @@ +# PHP Coding Agent + +## Purpose +Develop high-quality PHP code following Test-Driven Development (TDD) principles within a Symfony environment. + +## Core Principles +- **Test-Driven Development**: Always follow the Red-Green-Refactor cycle. + 1. **Red**: Write a failing test for the smallest possible unit of functionality before implementing any production code. + 2. **Green**: Implement the minimum amount of code required to make the test pass. + 3. **Refactor**: Clean up the code while ensuring all tests remain green. +- **Code Quality**: Adhere strictly to PSR-12 coding standards and Symfony best practices. +- **Verification**: Every change must be verified before completion. + +## Technical Stack & Tools +- **Framework**: Symfony +- **Standard**: PSR-12 +- **Testing**: PHPUnit +- **Static Analysis**: PHPStan + +## Operational Workflow +1. **Analyze Requirements**: Understand the feature or bug fix required. +2. **Test First (Red)**: Write a PHPUnit test case that defines the desired behavior and verify it fails. +3. **Implement (Green)**: Write the production code to satisfy the test. +4. **Verify & Refactor**: + - Run the tests again to ensure they pass. + - Run PHPStan to ensure type safety and static correctness. + - Refactor for readability and performance without breaking tests. +5. **Final Check**: Perform a final run of all tools before declaring the task complete. + +## Verification Requirements +The agent MUST execute the following checks after every implementation: +- `vendor/bin/phpunit` (or project equivalent) to ensure behavior is correct. +- `vendor/bin/phpstan analyze` (or project equivalent) to ensure static analysis passes. +- Verify PSR-12 compliance via available linting tools. diff --git a/.opencode/agents/php-test-agent.md b/.opencode/agents/php-test-agent.md new file mode 100644 index 0000000..eac5a93 --- /dev/null +++ b/.opencode/agents/php-test-agent.md @@ -0,0 +1,34 @@ +# PHP Test Agent + +## Purpose +Validate the application's correctness, quality, and architectural integrity by executing a comprehensive test suite and static analysis tools to identify bugs or regressions missed during development. + +## Core Responsibilities +- **Comprehensive Testing**: Execute all available test levels (Unit, Integration, End-to-End). +- **Quality Assurance**: Run static analysis tools to ensure code health. +- **Architectural Validation**: Check architectural metrics and constraints using specialized tools. +- **Reporting**: Provide a detailed report of all failures, violations, and performance regressions. + +## Technical Stack & Tools +- **Testing**: PHPUnit (and any existing E2E/Integration suites). +- **Static Analysis**: PHPStan. +- **Architecture Metrics**: `php deeptrac`. + +## Operational Workflow +1. **Environment Setup**: Ensure the test environment is correctly configured. +2. **Execution Phase**: + - Run all tests via `vendor/bin/phpunit` (or project equivalent). + - Execute static analysis via `vendor/bin/phpstan analyze`. + - Analyze architecture metrics using `php deeptrac`. +3. **Analysis**: Evaluate the output of all tools to identify patterns, regressions, or critical failures. +4. **Reporting**: Consolidate findings into a clear report highlighting: + - Failed test cases (with stack traces). + - PHPStan analysis errors. + - Architecture violations identified by `php deeptrac`. + +## Output Format +The agent must return a concise report structured as follows: +- **Test Results**: Pass/Fail rate and list of failing tests. +- **Static Analysis**: Summary of PHPStan levels and specific issues found. +- **Architecture Report**: Key metrics from `php deeptrac` and any flagged architectural violations. +- **Conclusion**: Overall health status of the application. diff --git a/.opencode/skills/create-skill/SKILL.md b/.opencode/skills/create-skill/SKILL.md new file mode 100644 index 0000000..d71f49d --- /dev/null +++ b/.opencode/skills/create-skill/SKILL.md @@ -0,0 +1,47 @@ +--- +name: create-skill +description: Guidelines for creating and defining new OpenCode agent skills. +compatibility: opencode +--- + +# Create Skill Skill + +This skill provides the standardized process for developing reusable behavioral patterns (Skills) in OpenCode. + +## Workflow +1. **Identify a Reusable Pattern**: Find a task that is performed repeatedly across sessions or projects (e.g., "Git Release Process", "API Documentation Generation"). +2. **Create the Skill Directory**: + - Path: `.opencode/skills//` + - Ensure `` follows naming rules: lowercase alphanumeric, single hyphens, no leading/trailing hyphens. +3. **Define the `SKILL.md` file**: + - Create a `SKILL.md` file inside the directory. + - **Frontmatter (Required)**: + - `name`: Must match the directory name exactly. + - `description`: A concise explanation of what the skill does and when to use it (1-1024 chars). + - `compatibility`: Optional, typically set to `opencode`. + - **Content**: Write detailed instructions, checklists, or examples that guide the agent's behavior. +4. **Testing & Validation**: + - Call the skill using the `skill` tool: `skill({ name: "" })`. + - Verify that the agent follows the guidelines defined in the content. + +## Naming Constraints +- 1–64 characters. +- Regex: `^[a-z0-9]+(-[a-z0-9]+)*$` + +## Example Implementation +**Directory**: `.opencode/skills/api-doc-gen/` +**File**: `SKILL.md` +```markdown +--- +name: api-doc-gen +description: Generates standardized API documentation from source code analysis. +compatibility: opencode +--- + +# API Documentation Generation + +## Steps +1. Analyze the existing endpoints and their request/response bodies. +2. Follow the project's format (e.g., OpenAPI 3.0). +3. Ensure all authentication requirements are documented. +``` diff --git a/.opencode/skills/create-subagent/SKILL.md b/.opencode/skills/create-subagent/SKILL.md new file mode 100644 index 0000000..d011167 --- /dev/null +++ b/.opencode/skills/create-subagent/SKILL.md @@ -0,0 +1,52 @@ +--- +name: create-subagent +description: Guidelines for creating and configuring new subagents in OpenCode. +compatibility: opencode +--- + +# Create Subagent Skill + +This skill provides a standardized workflow for adding new specialized subagents to an OpenCode project. + +## Workflow +1. **Analyze Requirements**: Determine the specific specialized task the agent should handle (e.g., "Security Auditor", "Documentation Specialist"). +2. **Define Configuration**: + - **Name**: Use lowercase alphanumeric with single hyphen separators (e.g., `security-auditor`). + - **Mode**: Set to `subagent`. + - **Description**: Write a clear, concise description of what the agent does and when it should be used. This is CRITICAL as primary agents use this to decide when to invoke it. + - **Model**: Choose a model optimized for the task (if different from the primary agent). + - **Permissions**: Define strict permissions (`allow`, `deny`, `ask`) based on the principle of least privilege. Read-only agents should have `edit: deny`. +3. **Implementation**: + - **Preferred Method**: Create a Markdown file in `.opencode/agents/.md`. + - **Alternative**: Add to `opencode.json` under the `"agent"` key. +4. **Verification**: + - Ensure the file is saved with the correct frontmatter and system prompt. + - Test the agent by calling it via `@` in a session. + +## Configuration Example (Markdown) +```markdown +--- +description: Performs security audits on the codebase +mode: subagent +model: anthropic/claude-sonnet-4-20250514 +permission: + edit: deny + bash: deny +--- +You are a security expert. Focus on identifying potential vulnerabilities, +input validation issues, and authentication flaws. +``` + +## Configuration Example (JSON) +```json +{ + "agent": { + "security-auditor": { + "description": "Performs security audits on the codebase", + "mode": "subagent", + "model": "anthropic/claude-sonnet-4-20250514", + "permission": { "edit": "deny" } + } + } +} +``` diff --git a/.opencode/skills/php-deptrac/SKILL.md b/.opencode/skills/php-deptrac/SKILL.md new file mode 100644 index 0000000..8bf50d9 --- /dev/null +++ b/.opencode/skills/php-deptrac/SKILL.md @@ -0,0 +1,40 @@ +--- +name: php-deptrac +description: Guidelines for analyzing, defining, and enforcing PHP architectural rules using Deptrac. +compatibility: opencode +--- + +# PHP Architecture Enforcement with Deptrac + +This skill provides a workflow for maintaining clean architecture in PHP projects using Deptrac. + +## Workflow + +### 1. Setup & Installation +- Check if `deptrac/deptrac` is present in `composer.json`. +- If not installed, suggest: `composer require --dev deptrac/deptrac`. +- Ensure `vendor/bin/deptrac` is executable. + +### 2. Configuration & Layer Definition +- **Initialization**: Use `vendor/bin/deptrac init` to generate a template if no config exists. +- **Config File**: Work with `deptrac.yaml` (or `deptrac.php`). +- **Defining Layers**: + - Identify logical layers (e.g., `Domain`, `Application`, `Infrastructure`, `UI`). + - Use collectors to map namespaces or directories to these layers. +- **Defining Rules**: + - Establish allowed dependencies (e.g., `Application` can depend on `Domain`, but `Domain` cannot depend on `Application`). + - Forbid direct dependency between siblings if required. + +### 3. Analysis & Violation Handling +- **Run Analysis**: Execute `vendor/bin/deptrac analyse`. +- **Interpret Results**: + - Analyze the violation report to identify which class is breaking which rule. + - Check the source code to determine if it's a legitimate architectural leak or a misconfiguration. +- **Correction**: + - Refactor the code to remove the illegal dependency (Preferred). + - Adjust the rules in `deptrac.yaml` if the architecture has evolved. + - Use baselines (`deptrac.baseline.yaml`) for legacy code that cannot be fixed immediately. + +### 4. Integration & Verification +- Ensure Deptrac is part of the CI pipeline or local linting process. +- Run `vendor/bin/deptrac` as a final check before completing architectural refactoring tasks. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c807646 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,8 @@ +# AGENTS.md + +This repository is a project template for OpenCode agents. + +## Structure +- `docs/architecture`: System architecture and design documentation. +- `.opencode/agents`: Definitions and guidelines for SubAgents used in projects. +- `.opencode/skills`: Reusable skill definitions for agent extension. diff --git a/docs/architecture/symfony-architecture.md b/docs/architecture/symfony-architecture.md new file mode 100644 index 0000000..7992621 --- /dev/null +++ b/docs/architecture/symfony-architecture.md @@ -0,0 +1,117 @@ +# 🌿 Architektur-Dokumentation: Symfony Template + +## 1. Vision & Kernprinzipien +Das Ziel dieser Architektur ist eine strikte Trennung zwischen technischer Infrastruktur, Geschäftslogik und den Liefermechanismen. Wir verfolgen einen Ansatz, der an **Clean Architecture** und **Hexagonal Architecture** angelehnt ist. + +### Grundregeln: +* **Unidirektionaler Fluss:** `UI` $\rightarrow$ `Logic` $\rightarrow$ `Data`. Ein Layer darf niemals Informationen aus einem übergeordneten Layer importieren. +* **Dependency Inversion:** Die `Logic`-Schicht definiert die Anforderungen (Interfaces). Die `Data`-Schicht implementiert diese. Die Logik ist somit unabhängig von der Datenbank-Technologie. +* **Model-Zentrierung:** Das Model ist das Herzstück der Applikation. Es ist ein anämisches POPO (Plain Old PHP Object) und wird primär im gesamten System verwendet. +* **Atomarität:** Business-Operationen sind atomar. Entweder alles wird gespeichert oder nichts (Transaction Management). + +--- + +## 2. Die Schichtenarchitektur + +### 🟢 UI Layer (Delivery Mechanisms) +Die UI-Schicht ist die dünne Eintrittspforte. Sie besitzt keine Geschäftslogik. +* **Einstiegspunkte:** `Http` (Controller), `Console` (Commands), `Queue` (MessageHandlers). +* **Verantwortlichkeiten:** + * Mapping von Input auf **DTOs**. + * Syntaktische Validierung via Symfony Constraints am DTO. + * Grobe Autorisierungsprüfung (Rollen-basiert, z.B. `ROLE_USER`). + * Aufruf des entsprechenden **UseCase**. + +### 🔵 Logic Layer (Business Core) +Hier wird definiert, *was* das System tut. Die Logik ist in Orchestrierung und zustandslose Fachlogik unterteilt. + +#### A. Orchestrierung & State +* **UseCase:** Der Dirigent eines Business-Prozesses. Er koordiniert den Ablauf: `Authorization` $\rightarrow$ `Validation` $\rightarrow$ `Calculation` $\rightarrow$ `Save`. Er steuert die Transaktionsgrenzen via `TransactionManagerInterface`. +* **Manager:** Zuständig für das **State Management**. Er implementiert das *Cache-Aside Pattern* (prüft Cache vor dem Provider) und steuert die Cache-Invalidierung nach Schreibvorgängen. + +#### B. Spezialisierte Logik (Stateless Services) +Um "Fat Managers" zu vermeiden, wird Fachlogik in spezialisierte Klassen ausgelagert: +* **Calculators:** Pure Functions für Berechnungen $\rightarrow$ gibt Werte zurück. +* **Policies:** Business-Regelprüfungen $\rightarrow$ gibt `boolean` zurück. +* **Validators:** Komplexe Zustandsprüfungen $\rightarrow$ wirft `ValidationException`. +* **Strategies:** Kapselung austauschbarer Algorithmen. + +#### C. Domain Objekte +* **Models:** Die primären Datencontainer (z.B. `GardenPlan`). Anämisch und unabhängig von der DB. +* **DTOs:** Transportobjekte zwischen UI und Logic. +* **Domain Events:** Dünne Ereignisse (ID & Typ), die via `DomainEventCollector` gesammelt und nach dem Commit gefeuert werden. + +### 🔴 Data Layer (Infrastructure) +Die technische Realisierung. Alles hier ist austauschbar, solange die Interfaces der Logic-Schicht erfüllt werden. +* **Provider / Processor:** Implementierungen der in der Logic definierten Interfaces. Provider = Lesen | Processor = Schreiben. +* **Entities:** Die technischen Repräsentationen für Doctrine (z.B. `GardenPlanEntity`). +* **Mappers:** Explizite Klassen, die zwischen `Entity` $\leftrightarrow$ `Model` transformieren. + +--- + +## 3. Technischer Workflow & Pipeline + +### Der Schreib-Pfad (Write Flow) +`UI (Controller/Command)` $\rightarrow$ `DTO` $\rightarrow$ `UseCase (Start Transaction)` $\rightarrow$ `Auth Check (Voter)` $\rightarrow$ `Validator` $\rightarrow$ `Policy` $\rightarrow$ `Calculator` $\rightarrow$ `Manager` $\rightarrow$ `Processor` $\rightarrow$ `Mapper` $\rightarrow$ `Entity` $\rightarrow$ `DB`. + +### Der Lese-Pfad (Read Flow) +`UI` $\rightarrow$ `UseCase` $\rightarrow$ `Manager (Cache check)` $\rightarrow$ `Provider Interface` $\rightarrow$ `Implementation` $\rightarrow$ `Mapper` $\rightarrow$ `Model` $\rightarrow$ `UI`. + +--- + +## 4. Querschnittsfunktionen + +### Transaktionssteuerung & Fehler +* **Transaction Management:** Der UseCase nutzt ein `TransactionManagerInterface`, um sicherzustellen, dass alle Änderungen innerhalb eines Prozesses atomar erfolgen. +* **Error Handling:** Eigene Domain-Exceptions in der Logic. Ein zentraler **Symfony ExceptionListener** mappt diese auf HTTP-Statuscodes (400, 403, 404, etc.). + +### Asynchronität (Messenger) +* **Inbound:** `Message` $\rightarrow$ `Handler` $\rightarrow$ `DTO` $\rightarrow$ `UseCase`. +* **Outbound:** Nachrichten werden erst **nach** dem erfolgreichen Commit der Transaktion verschickt (Post-Commit Trigger), um "Ghost Notifications" zu vermeiden. + +--- + +## 5. Namensmusterkatalog + +| Komponente | Muster | Beispiel | +| :--- | :--- | :--- | +| **Model** | `[Entity]` | `GardenPlan` | +| **Entity** | `[Entity]Entity` | `GardenPlanEntity` | +| **UseCase** | `[Action][Entity]UseCase` | `CreateGardenPlanUseCase` | +| **Manager** | `[Entity]Manager` | `GardenPlanManager` | +| **Calculator** | `[Topic]Calculator` | `SpacingCalculator` | +| **Policy** | `[Rule]Policy` | `CompatibilityPolicy` | +| **Validator** | `[Entity]Validator` | `GardenLayoutValidator` | +| **Provider Interface**| `[Entity]ProviderInterface` | `GardenPlanProviderInterface` | +| **Processor Interface**| `[Entity]ProcessorInterface`| `GardenPlanProcessorInterface`| +| **Mapper** | `[Src]To[Tgt]Mapper` | `GardenPlanEntityToModelMapper`| +| **DTO** | `[Action][Entity]Dto` | `UpdateGardenPlanDto` | + +--- + +## 6. Ordnerstruktur (Hybrid-Feature Ansatz) + +```text +src/ +├── UI/ +│ ├── Http/Controller/[Feature]/ # z.B. /Planning/GardenPlanController.php +│ ├── Console/Command/[Feature]/ # z.B. /Irrigation/StartWateringCommand.php +│ └── Queue/MessageHandler/[Feature]/ # z.B. /Notification/SendMailHandler.php +│ +├── Logic/ +│ ├── UseCase/[Feature]/ # z.B. /Planning/CreateGardenPlanUseCase.php +│ ├── Manager/[Feature]/ # z.B. /Planning/GardenPlanManager.php +│ ├── Domain/ +│ │ ├── Model/[Feature]/ # z.B. /Planning/GardenPlan.php +│ │ ├── DTO/[Feature]/ # z.B. /Planning/UpdatePlanDto.php +│ │ └── Service/[Feature]/ # Calculator, Policy, Validator, Strategy +│ └── InfrastructureInterface/ # Provider & Processor Interfaces +│ +├── Data/ +│ ├── Doctrine/ +│ │ ├── Entity/[Feature]/ # z.B. /Planning/GardenPlanEntity.php +│ │ └── Mapping/[Feature]/ # z.B. /Planning/GardenPlanMapper.php +│ └── Implementation/ +│ ├── Provider/[Feature]/ # Realisierung der Interfaces +│ └── Processor/[Feature]/ # Realisierung der Interfaces +```