From ed3404ff6e02c7a1fe61e72d3844d95a25c7ebc2 Mon Sep 17 00:00:00 2001 From: Tim Goudriaan Date: Thu, 19 Mar 2026 13:25:36 +0100 Subject: [PATCH 1/4] Add Composer script to prepare the Symfony test environment --- contributing.md => CONTRIBUTING.md | 20 +++++++++++--------- README.md | 2 +- composer.json | 10 ++++++++-- 3 files changed, 20 insertions(+), 12 deletions(-) rename contributing.md => CONTRIBUTING.md (74%) diff --git a/contributing.md b/CONTRIBUTING.md similarity index 74% rename from contributing.md rename to CONTRIBUTING.md index 8eb7d868..c9c15fc4 100644 --- a/contributing.md +++ b/CONTRIBUTING.md @@ -26,20 +26,22 @@ symfony server:start -d ## Lint & test your code -### Running PHPUnit tests - -Before running the tests, make sure the testing database is ready: - ```shell -symfony console --env=test doctrine:database:create --if-not-exists -symfony console --env=test doctrine:schema:update --force -symfony console --env=test doctrine:fixtures:load --no-interaction +# Run all linters +symfony composer lint ``` -Run the PHPUnit tests: +### Running PHPUnit tests ```shell -symfony run bin/phpunit +# Before running the tests, make sure the testing database is ready +symfony composer tests:setup + +# Run PHP tests +symfony composer tests:php + +# Run tests on Docker images +symfony composer tests:docker ``` [codedmonkey-sponsor]: https://www.codedmonkey.com/sponsor?project=dirigent diff --git a/README.md b/README.md index e650d165..97fd7bd4 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ until it's second anniversary. See our [full license][license] for more details. ## Contributing -Feel free to report issues and make suggestions on [GitHub][github-issues] or follow our [contribution guide](contributing.md). +Feel free to report issues and make suggestions on [GitHub][github-issues] or follow our [contribution guide](CONTRIBUTING.md). ## About Me diff --git a/composer.json b/composer.json index 50a6ecb7..b72a2f93 100644 --- a/composer.json +++ b/composer.json @@ -144,7 +144,12 @@ "@tests:php:functional" ], "tests:php:functional": "bin/phpunit tests/FunctionalTests", - "tests:php:unit": "bin/phpunit tests/UnitTests" + "tests:php:unit": "bin/phpunit tests/UnitTests", + "tests:setup": [ + "bin/console --env=test doctrine:database:create --if-not-exists", + "bin/console --env=test doctrine:schema:update --force", + "bin/console --env=test doctrine:fixtures:load --no-interaction" + ] }, "scripts-descriptions": { "build:standalone": "Build the standalone image", @@ -162,7 +167,8 @@ "tests:docker:standalone": "Run tests in the standalone image", "tests:php": "Run all PHP tests", "tests:php:functional": "Run the functional test suite", - "tests:php:unit": "Run the unit test suite" + "tests:php:unit": "Run the unit test suite", + "tests:setup": "Prepare the Symfony test environment" }, "config": { "allow-plugins": { From c56df8f0b1c1717cb3be1d347c73a5d4d9d1ed19 Mon Sep 17 00:00:00 2001 From: Tim Goudriaan Date: Thu, 19 Mar 2026 13:26:31 +0100 Subject: [PATCH 2/4] Update sponsor URL --- CONTRIBUTING.md | 2 +- README.md | 2 +- templates/dashboard/credits.html.twig | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c9c15fc4..99a475a0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,5 +44,5 @@ symfony composer tests:php symfony composer tests:docker ``` -[codedmonkey-sponsor]: https://www.codedmonkey.com/sponsor?project=dirigent +[codedmonkey-sponsor]: https://github.com/sponsors/codedmonkey [dirigent-docs-install-source]: https://dirigent.dev/docs/installation/source diff --git a/README.md b/README.md index 97fd7bd4..9486ecd5 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ Feel free to report issues and make suggestions on [GitHub][github-issues] or fo Dirigent is developed by [Coded Monkey][codedmonkey]. [codedmonkey]: https://www.codedmonkey.com -[codedmonkey-sponsor]: https://www.codedmonkey.com/sponsor?project=dirigent +[codedmonkey-sponsor]: https://github.com/sponsors/codedmonkey [composer]: https://getcomposer.org [dirigent]: https://dirigent.dev [docs]: docs/readme.md diff --git a/templates/dashboard/credits.html.twig b/templates/dashboard/credits.html.twig index 998a970d..bd021d4e 100644 --- a/templates/dashboard/credits.html.twig +++ b/templates/dashboard/credits.html.twig @@ -20,7 +20,7 @@

Sponsors

- Dirigent is looking for sponsors. Click here + Dirigent is looking for sponsors. Click here to sponsor development of Dirigent.

From 9ba7bcbaba0d7a64abb53aaaa24741bd060ed309 Mon Sep 17 00:00:00 2001 From: Tim Goudriaan Date: Thu, 19 Mar 2026 21:17:20 +0100 Subject: [PATCH 3/4] Create initial AGENTS.md and improve CONTRIBUTING.md --- AGENTS.md | 86 ++++++++++++++++++++++++++ CLAUDE.md | 3 + CONTRIBUTING.md | 85 +++++++++++++++++++++---- docs/installation/docker-standalone.md | 2 +- docs/installation/source.md | 20 ++++-- 5 files changed, 179 insertions(+), 17 deletions(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..601da4fe --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,86 @@ +# Agent guidelines for Dirigent development + +Dirigent is a free and open package registry for Composer, the PHP package manager. It allows users to publish private packages and mirror packages from external registries like Packagist. + +### Project structure + +``` +assets/ # Frontend assets +config/ # Symfony configuration +migrations/ # Doctrine migrations (PostgreSQL) +src/ +├── Attribute/ # PHP attributes +├── Command/ # Symfony console commands +├── Composer/ # Composer integration logic +├── Controller/ # HTTP controllers +│ └── Dashboard/ # EasyAdmin dashboard controllers +├── Doctrine/ +│ ├── Entity/ # Doctrine ORM entities +│ ├── Repository/ # Doctrine repositories +│ ├── Type/ # Custom Doctrine types +│ └── DataFixtures/ # Database fixtures +├── Encryption/ # Encryption utilities +├── Entity/ # Enums (UserRole, PackageUpdateSource) +├── EventListener/ # Symfony event listeners +├── Form/ # Symfony form types +├── Message/ # Symfony messenger messages and handlers (async jobs) +├── Package/ # Package management services +├── Routing/ # Symfony routing logic +├── Twig/ # Twig extensions +└── Validator/ # Symfony validators +templates/ # Twig templates +tests/ +├── UnitTests/ # Unit tests +├── FunctionalTests/ # Functional/Integration tests +└── Docker/ # Docker image tests +``` + +## Coding style + +### Project + +- Environment variables are stored in `.env.dirigent` and `.env.dirigent.*` (not `.env`). + +### PHP + +- Follow the PER coding style and the Symfony coding standards. +- Organize services into domain-specific namespaces. +- Always use strict comparisons (`===`, `!==`). +- Enforce the use of DateTimeImmutable over DateTime. +- Always use spaces in concatenation (`$a . $b`). +- Always use imports. Use aliases when collisions occur or the imported name is unclear. +- Don't use blank lines between import groups. + +## Commands + +### Linting & code quality + +```shell +# Run all linting jobs +symfony composer lint + +# Individual linters +symfony composer lint:refactor # Rector (automatically applies changes) +symfony composer lint:coding-style # PHP-CS-Fixer (automatically applies changes) +symfony composer lint:static-analysis # PHPStan level 5 +symfony composer lint:container # Symfony container validation +symfony composer lint:templates # Twig template validation +``` + +### Testing + +```shell +# Prepare the Symfony test environment for tests (if the database schema changed) +symfony composer tests:setup + +# Run all tests +symfony composer tests + +# Run only PHP tests +symfony composer tests:php +symfony composer tests:php:unit +symfony composer tests:php:functional + +# Run tests for Docker images +symfony composer tests:docker +``` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..193e536a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +# Agent guidelines for Dirigent development in Claude Code + +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99a475a0..3b2b839c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,9 +3,40 @@ Dirigent is an open-source project, contributions of all kind are welcome, including [financial contributions][codedmonkey-sponsor]. +This guide contains technical information and instructions about the development process of the project that you should +follow when contributing code. + +## Project information + +### Technology stack + +- **Languages & frameworks**: + - PHP 8.3+ + - Symfony 7.3 + - PostgreSQL 16.x (via Doctrine ORM 3.x) + - TypeScript +- **Development requirements**: + - Docker + - Symfony CLI +- **Package managers**: + - **PHP**: Composer + - **TypeScript**: NPM +- **Frontend**: Twig, EasyAdmin 4.x +- **Frontend (JavaScript)**: Webpack Encore, Stimulus +- **Linting**: Rector, PHP-CS-Fixer, PHPStan +- **Testing**: PHPUnit 12.x, Testcontainers + +### Coding style + +#### PHP + +Dirigent follows the [PER coding style][per-coding-style] and the [Symfony coding standards][symfony-coding-standards]. + ## Running Dirigent locally -To run Dirigent locally, follow the [Running from source code][dirigent-docs-install-source] guide in the documentation, +### Installation + +To run Dirigent locally, follow the [Running from source code][docs-install-source] guide in the documentation, up to the *Configure services* section. Additional requirements: @@ -13,36 +44,66 @@ Additional requirements: - Symfony binary - Docker + ```shell # Optionally, copy the example Docker Compose configuration override file -cp compose.override.example.yaml composer.override.yaml +cp compose.override.example.yaml compose.override.yaml + +# Install dependencies +composer install +npm install -# Start Docker services +# Build frontend assets +npm run build # or watch for changes with: npm run watch + +# Run services through Docker Compose docker compose up -d -# Start Symfony local server +# Run the Symfony development server symfony server:start -d + +# Create & fill the development database +symfony console doctrine:database:create --if-not-exists +symfony console doctrine:schema:update --force +symfony console doctrine:fixtures:load --no-interaction ``` -## Lint & test your code +## Lint & validate the code ```shell -# Run all linters +# Run all linting jobs symfony composer lint + +# Individual linters +symfony composer lint:refactor # Rector (automatically applies changes) +symfony composer lint:coding-style # PHP-CS-Fixer (automatically applies changes) +symfony composer lint:static-analysis # PHPStan level 5 +symfony composer lint:container # Symfony container validation +symfony composer lint:templates # Twig template validation ``` -### Running PHPUnit tests +### Running tests ```shell -# Before running the tests, make sure the testing database is ready +# Prepare the Symfony test environment (if the database schema changed) symfony composer tests:setup +``` + +```shell +# Run all tests +symfony composer tests -# Run PHP tests +# Run only PHP tests symfony composer tests:php +symfony composer tests:php:unit +symfony composer tests:php:functional -# Run tests on Docker images -symfony composer tests:docker +# Run tests for Docker images +symfony composer tests:docker +symfony composer tests:docker:standalone ``` [codedmonkey-sponsor]: https://github.com/sponsors/codedmonkey -[dirigent-docs-install-source]: https://dirigent.dev/docs/installation/source +[docs-install-source]: ./docs/installation/source.md +[per-coding-style]: https://www.php-fig.org/per/coding-style/ +[symfony-coding-standards]: https://symfony.com/doc/current/contributing/code/standards.html diff --git a/docs/installation/docker-standalone.md b/docs/installation/docker-standalone.md index 67f6fdcc..4e36fb20 100644 --- a/docs/installation/docker-standalone.md +++ b/docs/installation/docker-standalone.md @@ -13,7 +13,7 @@ Dirigent into one, including a web server, database and a background worker. The ### Docker command -```bash +```shell docker volume create dirigent-data docker container run -d \ diff --git a/docs/installation/source.md b/docs/installation/source.md index 78cd2caa..8d3bda9e 100644 --- a/docs/installation/source.md +++ b/docs/installation/source.md @@ -11,27 +11,31 @@ This page is a stub. ::: -Running the project from source code is not guaranteed to work on every system. +Running the project from the source code is not guaranteed to work on every system. ## Requirements -To install Dirigent on your system from source you need to following packages: +To install Dirigent on your system from source you need to have the following packages installed on your system: - Git - PHP 8.3 or higher - Composer 2 - Web server (like Nginx or Caddy) - PHP-FPM -- PostgreSQL -- Node +- PostgreSQL 16 +- Node 23 ## Download source code +The recommended way to download Dirigent is through Git: + ```shell git clone https://github.com/codedmonkey/dirigent.git cd dirigent ``` +You can also download the source code directly from the [Releases][github-releases] page on GitHub. + ## Install build tools ```shell @@ -44,4 +48,12 @@ npm install npm run production ``` +:::note + +Stop here if you're following the "Contributing to Dirigent" guide. + +::: + ## Configure services + +[github-releases]: https://github.com/codedmonkey/dirigent/releases From 99604cfb1f4b7405976554cb9ef6f688cc354b6e Mon Sep 17 00:00:00 2001 From: Tim Goudriaan Date: Thu, 19 Mar 2026 22:15:04 +0100 Subject: [PATCH 4/4] Add custom code-review Claude command Stolen from https://github.com/anthropics/claude-code/tree/db8834ba1d72e9a26fba30ac85f3bc4316bb0689/plugins/code-review --- .claude/commands/code-review.md | 109 ++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 .claude/commands/code-review.md diff --git a/.claude/commands/code-review.md b/.claude/commands/code-review.md new file mode 100644 index 00000000..ef6a39e8 --- /dev/null +++ b/.claude/commands/code-review.md @@ -0,0 +1,109 @@ +--- +allowed-tools: Bash(gh issue view:*), Bash(gh search:*), Bash(gh issue list:*), Bash(gh pr comment:*), Bash(gh pr diff:*), Bash(gh pr view:*), Bash(gh pr list:*), mcp__github_inline_comment__create_inline_comment +description: Code review a pull request +--- + +Provide a code review for the given pull request. + +**Agent assumptions (applies to all agents and subagents):** +- All tools are functional and will work without error. Do not test tools or make exploratory calls. Make sure this is clear to every subagent that is launched. +- Only call a tool if it is required to complete the task. Every tool call should have a clear purpose. + +To do this, follow these steps precisely: + +1. Launch a haiku agent to check if any of the following are true: + - The pull request is closed + - The pull request is a draft + - The pull request does not need code review (e.g. automated PR, trivial change that is obviously correct) + - Claude has already commented on this PR (check `gh pr view --comments` for comments left by claude) + + If any condition is true, stop and do not proceed. + +Note: Still review Claude generated PR's. + +2. Launch a haiku agent to return a list of file paths (not their contents) for all relevant CLAUDE.md files including: + - The root CLAUDE.md file, if it exists + - Any CLAUDE.md files in directories containing files modified by the pull request + +3. Launch a sonnet agent to view the pull request and return a summary of the changes + +4. Launch 4 agents in parallel to independently review the changes. Each agent should return the list of issues, where each issue includes a description and the reason it was flagged (e.g. "CLAUDE.md adherence", "bug"). The agents should do the following: + + Agents 1 + 2: CLAUDE.md compliance sonnet agents + Audit changes for CLAUDE.md compliance in parallel. Note: When evaluating CLAUDE.md compliance for a file, you should only consider CLAUDE.md files that share a file path with the file or parents. + + Agent 3: Opus bug agent (parallel subagent with agent 4) + Scan for obvious bugs. Focus only on the diff itself without reading extra context. Flag only significant bugs; ignore nitpicks and likely false positives. Do not flag issues that you cannot validate without looking at context outside of the git diff. + + Agent 4: Opus bug agent (parallel subagent with agent 3) + Look for problems that exist in the introduced code. This could be security issues, incorrect logic, etc. Only look for issues that fall within the changed code. + + **CRITICAL: We only want HIGH SIGNAL issues.** Flag issues where: + - The code will fail to compile or parse (syntax errors, type errors, missing imports, unresolved references) + - The code will definitely produce wrong results regardless of inputs (clear logic errors) + - Clear, unambiguous CLAUDE.md violations where you can quote the exact rule being broken + + Do NOT flag: + - Code style or quality concerns + - Potential issues that depend on specific inputs or state + - Subjective suggestions or improvements + + If you are not certain an issue is real, do not flag it. False positives erode trust and waste reviewer time. + + In addition to the above, each subagent should be told the PR title and description. This will help provide context regarding the author's intent. + +5. For each issue found in the previous step by agents 3 and 4, launch parallel subagents to validate the issue. These subagents should get the PR title and description along with a description of the issue. The agent's job is to review the issue to validate that the stated issue is truly an issue with high confidence. For example, if an issue such as "variable is not defined" was flagged, the subagent's job would be to validate that is actually true in the code. Another example would be CLAUDE.md issues. The agent should validate that the CLAUDE.md rule that was violated is scoped for this file and is actually violated. Use Opus subagents for bugs and logic issues, and sonnet agents for CLAUDE.md violations. + +6. Filter out any issues that were not validated in step 5. This step will give us our list of high signal issues for our review. + +7. Output a summary of the review findings to the terminal: + - If issues were found, list each issue with a brief description. + - If no issues were found, state: "No issues found. Checked for bugs and CLAUDE.md compliance." + + If `--comment` argument was NOT provided, stop here. Do not post any GitHub comments. + + If `--comment` argument IS provided and NO issues were found, post a summary comment using `gh pr comment` and stop. + + If `--comment` argument IS provided and issues were found, continue to step 8. + +8. Create a list of all comments that you plan on leaving. This is only for you to make sure you are comfortable with the comments. Do not post this list anywhere. + +9. Post inline comments for each issue using `mcp__github_inline_comment__create_inline_comment` with `confirmed: true`. For each comment: + - Provide a brief description of the issue + - For small, self-contained fixes, include a committable suggestion block + - For larger fixes (6+ lines, structural changes, or changes spanning multiple locations), describe the issue and suggested fix without a suggestion block + - Never post a committable suggestion UNLESS committing the suggestion fixes the issue entirely. If follow up steps are required, do not leave a committable suggestion. + + **IMPORTANT: Only post ONE comment per unique issue. Do not post duplicate comments.** + +Use this list when evaluating issues in Steps 4 and 5 (these are false positives, do NOT flag): + +- Pre-existing issues +- Something that appears to be a bug but is actually correct +- Pedantic nitpicks that a senior engineer would not flag +- Issues that a linter will catch (do not run the linter to verify) +- General code quality concerns (e.g., lack of test coverage, general security issues) unless explicitly required in CLAUDE.md +- Issues mentioned in CLAUDE.md but explicitly silenced in the code (e.g., via a lint ignore comment) + +Notes: + +- Use gh CLI to interact with GitHub (e.g., fetch pull requests, create comments). Do not use web fetch. +- Create a todo list before starting. +- You must cite and link each issue in inline comments (e.g., if referring to a CLAUDE.md, include a link to it). +- If no issues are found and `--comment` argument is provided, post a comment with the following format: + +--- + +## Code review + +No issues found. Checked for bugs and CLAUDE.md compliance. + +--- + +- When linking to code in inline comments, follow the following format precisely, otherwise the Markdown preview won't render correctly: https://github.com/anthropics/claude-code/blob/c21d3c10bc8e898b7ac1a2d745bdc9bc4e423afe/package.json#L10-L15 + - Requires full git sha + - You must provide the full sha. Commands like `https://github.com/owner/repo/blob/$(git rev-parse HEAD)/foo/bar` will not work, since your comment will be directly rendered in Markdown. + - Repo name must match the repo you're code reviewing + - # sign after the file name + - Line range format is L[start]-L[end] + - Provide at least 1 line of context before and after, centered on the line you are commenting about (eg. if you are commenting about lines 5-6, you should link to `L4-7`) \ No newline at end of file