6869: Add agents.md and Claude Code configuration #62
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,146 @@ | ||
| { | ||
| "$schema": "https://json.schemastore.org/claude-code-settings.json", | ||
| "env": { | ||
| "COMPOSE_USER": "deploy" | ||
| }, | ||
| "permissions": { | ||
| "allow": [ | ||
| "Bash(cat:*)", | ||
| "Bash(diff:*)", | ||
| "Bash(echo:*)", | ||
| "Bash(find:*)", | ||
| "Bash(gh:*)", | ||
| "Bash(git:*)", | ||
| "Bash(grep:*)", | ||
| "Bash(head:*)", | ||
| "Bash(ls:*)", | ||
| "Bash(pwd)", | ||
| "Bash(tail:*)", | ||
| "Bash(task:*)", | ||
| "Bash(tree:*)", | ||
| "Bash(wc:*)", | ||
| "Bash(which:*)", | ||
| "Bash(docker compose exec:*)", | ||
| "Bash(docker compose run:*)", | ||
| "Bash(docker compose up:*)", | ||
| "Bash(docker compose ps:*)", | ||
| "Bash(docker compose logs:*)", | ||
| "Bash(docker compose top:*)", | ||
| "Bash(docker compose config:*)", | ||
| "Bash(docker compose pull:*)", | ||
| "Bash(docker compose images:*)", | ||
| "Bash(docker network:*)" | ||
| ], | ||
| "deny": [ | ||
| "Bash(rm -rf:*)", | ||
| "Bash(gh issue delete:*)", | ||
| "Bash(gh release delete:*)", | ||
| "Bash(gh repo delete:*)", | ||
| "Bash(gh label delete:*)", | ||
| "Read(./.env.local)", | ||
| "Read(./.env.local.*)", | ||
| "Read(./config/secrets/*)" | ||
| ], | ||
| "ask": [ | ||
| "Bash(docker compose down:*)", | ||
| "Bash(docker compose stop:*)", | ||
| "Bash(docker compose rm:*)", | ||
| "Bash(docker compose restart:*)", | ||
| "Bash(gh issue create:*)", | ||
| "Bash(gh issue close:*)", | ||
| "Bash(gh issue edit:*)", | ||
| "Bash(gh issue comment:*)", | ||
| "Bash(gh pr create:*)", | ||
| "Bash(gh pr close:*)", | ||
| "Bash(gh pr merge:*)", | ||
| "Bash(gh pr edit:*)", | ||
| "Bash(gh pr comment:*)", | ||
| "Bash(gh pr review:*)", | ||
| "Bash(gh release create:*)", | ||
| "Bash(gh release edit:*)", | ||
| "Bash(gh repo create:*)", | ||
| "Bash(gh label create:*)", | ||
| "Bash(gh label edit:*)", | ||
| "Bash(git push:*)", | ||
| "Bash(git branch -d:*)", | ||
| "Bash(git branch -D:*)", | ||
| "Bash(git tag -d:*)", | ||
| "Bash(git tag -a:*)", | ||
| "Bash(git tag :*)", | ||
| "Bash(git reset:*)", | ||
| "Bash(git rebase:*)", | ||
| "Bash(git merge:*)", | ||
| "Bash(git stash drop:*)", | ||
| "Bash(git clean:*)", | ||
| "Bash(git checkout -- :*)", | ||
| "Bash(git restore:*)", | ||
| "Bash(git commit:*)" | ||
| ] | ||
| }, | ||
| "hooks": { | ||
| "SessionStart": [ | ||
| { | ||
| "matcher": "startup", | ||
| "hooks": [ | ||
| { | ||
| "type": "command", | ||
| "command": "docker compose up --detach --quiet-pull 2>/dev/null || true", | ||
| "timeout": 60, | ||
| "statusMessage": "Starting Docker services..." | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "PostToolUse": [ | ||
| { | ||
| "matcher": "Write|Edit", | ||
| "hooks": [ | ||
| { | ||
| "type": "command", | ||
| "command": "case \"$CLAUDE_FILE_PATH\" in *.php) docker compose exec -T phpfpm vendor/bin/php-cs-fixer fix --quiet \"$CLAUDE_FILE_PATH\" 2>/dev/null || true ;; esac", | ||
| "timeout": 30 | ||
| }, | ||
| { | ||
| "type": "command", | ||
| "command": "case \"$CLAUDE_FILE_PATH\" in *.php) docker compose exec -T phpfpm vendor/bin/phpstan analyse --no-progress --error-format=raw \"$CLAUDE_FILE_PATH\" 2>/dev/null || true ;; esac", | ||
| "timeout": 30 | ||
| }, | ||
| { | ||
| "type": "command", | ||
| "command": "case \"$CLAUDE_FILE_PATH\" in *.twig) docker compose exec -T phpfpm vendor/bin/twig-cs-fixer lint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true ;; esac", | ||
| "timeout": 15 | ||
| }, | ||
| { | ||
| "type": "command", | ||
| "command": "case \"$CLAUDE_FILE_PATH\" in */composer.json) docker compose exec -T phpfpm composer normalize --quiet 2>/dev/null || true ;; esac", | ||
| "timeout": 30 | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "Stop": [ | ||
| { | ||
| "hooks": [ | ||
| { | ||
| "type": "command", | ||
| "command": "docker compose exec -T phpfpm bin/console lint:container 2>/dev/null || true", | ||
| "timeout": 30, | ||
| "statusMessage": "Validating Symfony DI container..." | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| }, | ||
| "enabledPlugins": { | ||
| "php-lsp@claude-plugins-official": true, | ||
| "code-simplifier@claude-plugins-official": true, | ||
| "context7@claude-plugins-official": true, | ||
| "code-review@claude-plugins-official": true, | ||
| "security-guidance@claude-plugins-official": true, | ||
| "playwright@claude-plugins-official": true, | ||
| "feature-dev@claude-plugins-official": true, | ||
| "itkdev-skills@itkdev-marketplace": true | ||
| }, | ||
| "alwaysThinkingEnabled": true, | ||
| "defaultMode": "acceptEdits" | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,142 @@ | ||
| # 🤖 Code Agents - DevOps ITKsites | ||
|
Contributor
There was a problem hiding this comment. Note this file is not read by claude, this is jetbrains only |
||
|
|
||
| ## Project Overview | ||
|
|
||
| **DevOps ITKsites** is an internal Symfony application for server and site | ||
| registration/monitoring at ITK Dev. It receives `DetectionResults` from the | ||
| [ITK sites server harvester](https://github.com/itk-dev/devops_itkServerHarvest) | ||
| and processes them asynchronously to track servers, sites, domains, Docker | ||
| images, packages, modules, CVEs, and git repositories. | ||
|
|
||
| ## Technology Stack | ||
|
|
||
| - **Language**: PHP 8.4+ (Symfony 7.3) | ||
| - **API**: API Platform 4.0 (REST) | ||
| - **Admin UI**: EasyAdmin 4.x | ||
| - **Database**: Doctrine ORM 3.x / DBAL 4.x with MariaDB | ||
| - **Messaging**: Symfony Messenger (AMQP/RabbitMQ) | ||
| - **Auth**: OpenID Connect (`itk-dev/openid-connect-bundle`) | ||
| - **Frontend**: Webpack Encore, Stimulus.js | ||
| - **Testing**: PHPUnit 11+ | ||
| - **Code Quality**: PHP-CS-Fixer, PHPStan, Rector | ||
|
|
||
| ## Architecture | ||
|
|
||
| ```mermaid | ||
| graph TD | ||
| A[Harvester] -->|POST DetectionResult| B[API Platform REST endpoint] | ||
| B --> C[Symfony Messenger] | ||
| C --> D[Async Message Handlers] | ||
| D --> D1[DirectoryHandler] | ||
| D --> D2[DockerImageHandler] | ||
| D --> D3[DrupalHandler] | ||
| D --> D4[GitHandler] | ||
| D --> D5[NginxHandler] | ||
| D --> D6[SymfonyHandler] | ||
| D1 & D2 & D3 & D4 & D5 & D6 --> E[Doctrine ORM] | ||
| E --> F[MariaDB] | ||
| F --> G[EasyAdmin UI] | ||
| ``` | ||
|
|
||
| ### Key Directories | ||
|
|
||
| | Directory | Purpose | | ||
| |---|---| | ||
| | `src/Entity/` | ~20 Doctrine entities (Server, Site, Domain, Installation, Package, DockerImage, Advisory, etc.) | | ||
| | `src/Handler/` | DetectionResult handlers (Directory, Docker, Drupal, Git, Nginx, Symfony) | | ||
| | `src/MessageHandler/` | Async message processing (PersistDetectionResult, ProcessDetectionResult) | | ||
| | `src/Admin/` | EasyAdmin CRUD controllers | | ||
| | `src/ApiResource/` | API Platform resource definitions | | ||
| | `src/Service/` | Factories (PackageVersion, ModuleVersion, Advisory) and export services | | ||
| | `src/Repository/` | Doctrine repositories | | ||
| | `config/packages/` | Bundle configurations | | ||
| | `migrations/` | Doctrine migrations | | ||
| | `fixtures/` | Hautelook/Alice test fixtures | | ||
| | `tests/` | PHPUnit tests (Api, Controller, MessageHandler) | | ||
|
|
||
| ### Data Flow | ||
|
|
||
| All analyzed data (sites, installations, domains, packages, etc.) can be | ||
| truncated and rebuilt by replaying DetectionResults. Manually maintained data | ||
| (Servers, OIDC setups, Service Certificates) is separate and must be preserved. | ||
|
|
||
| ## Development Environment | ||
|
|
||
| ```sh | ||
| # Start services (MariaDB, PHP-FPM 8.4, Nginx, Mailpit) | ||
| docker compose pull && docker compose up --detach | ||
|
|
||
| # Install dependencies | ||
| docker compose exec phpfpm composer install | ||
|
|
||
| # Run migrations | ||
| docker compose exec phpfpm bin/console doctrine:migrations:migrate --no-interaction | ||
|
|
||
| # Load fixtures | ||
| docker compose exec phpfpm composer fixtures | ||
|
|
||
| # Login as admin (after fixtures) | ||
| docker compose exec phpfpm bin/console itk-dev:openid-connect:login admin@example.com | ||
|
|
||
| # Process message queues | ||
| docker compose exec phpfpm composer queues | ||
|
|
||
| # Build frontend assets | ||
| docker compose run --rm node yarn install && docker compose run --rm node yarn build | ||
| ``` | ||
|
|
||
| ## Quality Checks | ||
|
|
||
| All commands run inside Docker containers: | ||
|
|
||
| ```sh | ||
| # PHP coding standards (PHP-CS-Fixer) | ||
| docker compose exec phpfpm composer coding-standards-check | ||
| docker compose exec phpfpm composer coding-standards-apply | ||
|
|
||
| # PHPUnit tests (creates test DB, runs migrations, executes tests) | ||
| docker compose exec phpfpm composer tests | ||
|
|
||
| # Frontend coding standards | ||
| docker compose run --rm node yarn coding-standards-check | ||
|
|
||
| # API spec export (must be committed) | ||
| docker compose exec phpfpm composer update-api-spec | ||
| ``` | ||
|
|
||
| ## CI/CD | ||
|
|
||
| ### GitHub Actions (`pr.yaml`) | ||
|
|
||
| Pull requests run these checks: | ||
|
|
||
| 1. **Composer validation** - validates and installs (prod + dev) | ||
| 2. **Doctrine schema validation** - migrations + schema check against MariaDB | ||
| 3. **PHP-CS-Fixer** - coding standards | ||
| 4. **PHPUnit** - unit/integration tests with MariaDB | ||
| 5. **API spec validation** - ensures exported OpenAPI spec is up to date | ||
| 6. **Fixtures** - verifies fixtures load successfully | ||
| 7. **Asset build** - verifies frontend assets compile | ||
| 8. **Changelog** - ensures CHANGELOG.md is updated | ||
|
|
||
| ### Woodpecker CI (deployment) | ||
|
|
||
| - `stg.yml` - Deploys to staging on push to develop | ||
| - `prod.yml` - Deploys to production on release (Ansible playbook, runs migrations + transport setup) | ||
|
|
||
| ## PR Guidelines | ||
|
|
||
| - PRs must link to a ticket | ||
| - Code must pass all CI checks (tests, coding standards, static analysis) | ||
| - CHANGELOG.md must be updated | ||
| - UI changes require screenshots | ||
| - Base branch: `develop` | ||
|
|
||
| ## Important Conventions | ||
|
|
||
| - Entity classes extend `AbstractBaseEntity` (provides `id`, `createdAt`, `updatedAt`) | ||
| - Detection handlers implement `DetectionResultHandlerInterface` | ||
| - Handlers are auto-tagged and injected via tagged iterator in `services.yaml` | ||
| - Async processing uses Symfony Messenger with AMQP transport | ||
| - Environment-specific config goes in `.env.local` (not committed) | ||
| - API specs (`public/api-spec-v1.yaml` and `.json`) must be regenerated and committed when API changes | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do not think this should be the default behavior, it will not match all users workflow. The "alwaysThinkingEnabled" will burn tokens and time way to fast. It is better to do "ultrathink" when you need it.