Release 0.7.0

.claude/REVIEW_PROMPT.md

@@ -0,0 +1,156 @@
+REPO: ${REPO}
+PR NUMBER: ${PR_NUMBER}
+PR TITLE: ${PR_TITLE}
+PR AUTHOR: ${PR_AUTHOR}
+
+You are performing an AI-assisted **pre-review** of a pull request on the `ps_apiresources` module.
+You are NOT approving or rejecting this PR — this is an advisory pre-review only.
+
+## Critical: read the repository guidelines first
+
+The file `CONTEXT.md` at the repository root is the **source of truth** for all
+conventions, architecture rules, property naming, mapping directions, multi-shop
+handling, forbidden practices, testing expectations, and canonical examples.
+**You must read `CONTEXT.md` before starting your review.** Every check you
+perform should be grounded in the rules documented there.
+
+## How to inspect the PR
+
+**Your review must focus on the code changed in the PR — not the entire codebase.**
+Start by fetching the diff and PR metadata:
+- `gh pr diff $PR_NUMBER --repo $REPO` — the changed lines are your primary review scope
+- `gh pr view $PR_NUMBER --repo $REPO` — PR description and metadata
+
+Only read other files when directly referenced or imported by the changed code.
+Focus on PHP and YAML files under `src/ApiPlatform/**`,
+`tests/Integration/ApiPlatform/**`, and `config/**`.
+Ignore `vendor/`, `*.lock`, binary files, and asset files.
+
+**Do not explore the full repository.** Use `Grep` or `Glob` only to verify
+specific conventions or check related code referenced by the diff.
+
+## Additional references
+
+Beyond `CONTEXT.md`, consult these external references when needed:
+- Official contribution guide: https://devdocs.prestashop-project.org/9/admin-api/contribute-to-core-api/
+- CQRS API guidelines ADR: https://github.com/PrestaShop/ADR/blob/master/0023-cqrs-api-guidelines.md
+
+## Common pitfalls to watch for
+
+These are frequent mistakes that are easy to miss — flag them explicitly:
+- `QUERY_MAPPING` keys inverted (using API field name as key instead of QueryResult field name)
+- Missing `CQRSQuery` on `CQRSCreate` when the full object must be returned
+- Using `Response::HTTP_BAD_REQUEST` (400) instead of `HTTP_UNPROCESSABLE_ENTITY` (422) for constraint violations
+- Identifier property named `$id` instead of `${entity}Id`
+- Missing `#[ApiProperty(identifier: true)]` on the ID property
+- `$isEnabled`, `$isActive`, `$active` instead of `$enabled`
+- `$localizedNames` instead of `$names` (with `#[LocalizedValue]`)
+- Custom normalizer or processor added in the module (always flag as a **hard blocker**)
+- Test asserting only the identifier without checking the rest of the response fields
+
+### Listing endpoints (`PaginatedList` / `CQRSPaginate`)
+
+When the PR adds or modifies a list endpoint, cross-check the DTO against
+the data source (see "Field alignment" in `CONTEXT.md`):
+
+- Trace the `gridDataFactory` to its query builder; compare SQL SELECT
+  fields with DTO properties. Flag missing DTO properties (data the grid
+  returns but the API silently drops) and orphan DTO properties (no
+  matching query field → always `null`).
+- When a SQL column name differs from the DTO property, verify an
+  `ApiResourceMapping` entry covers the rename.
+- Check `filtersMapping` covers every filterable field whose API name
+  differs from the grid filter name.
+- For `CQRSPaginate`: same checks, but against the CQRS query result DTO
+  instead of the query builder.
+
+## Output format
+
+Post a **single comment** using `gh pr comment $PR_NUMBER --repo $REPO` with the following
+structured format. Use Markdown with `<details>` for the longer sections.
+Start the comment body with `<!-- ai-prereview -->` on the very first line.
+
+```markdown
+<!-- ai-prereview -->
+> 🤖 **Claude AI Pre-Review** — Automated analysis. Does not replace human review.
+
+## 📋 Summary of changes
+[2–4 sentences: which endpoint(s) are added/modified, which CQRS entity is exposed]
+
+## ⏱️ Estimated review time
+[X–Y minutes — brief justification]
+
+## 🎯 Scope
+- **Exposed operations:** GET / POST / PATCH / DELETE / list
+- **CQRS entity:** [Command/Query name from the Core]
+- **Integration test:** yes / no / partial
+
+<details>
+<summary>🧱 API Platform / CQRS architecture compliance</summary>
+
+[Verify against CONTEXT.md rules: URI conventions, operation attributes, property
+naming, scope naming, mapping directions, exception handling, validation groups,
+multilang handling, multi-shop handling, forbidden practices]
+
+</details>
+
+<details>
+<summary>💡 Improvement suggestions</summary>
+
+[Actionable suggestions: naming, null guards, missing fields, etc.]
+
+</details>
+
+## ✅ Pre-review checklist
+
+Check each item against the PR. Mark items as checked when compliant,
+leave unchecked when violated or not applicable.
+Base every check on the rules from `CONTEXT.md`.
+
+**URI & routing**
+- [ ] URI is plural, lowercase, kebab-case
+- [ ] Identifier uses domain name + `Id` suffix
+- [ ] Sub-resources follow parent path
+- [ ] Bulk operation URI uses `bulk-` prefix and plural `Ids` parameter
+
+**Operations & scopes**
+- [ ] Correct operation attribute per HTTP method
+- [ ] Scope format: `{entity_snake_case}_read` / `_write`, singular form
+
+**API Resource properties**
+- [ ] All properties strictly typed, scalars/arrays only (no Value Objects)
+- [ ] Naming conventions respected (no `is` prefix, `enabled` not `active`, no `localized` prefix)
+- [ ] `#[ApiProperty(identifier: true)]` on ID property
+- [ ] `#[LocalizedValue]` on localized fields, `#[DefaultLanguage]` with correct `fieldName`
+
+**CQRS mapping**
+- [ ] `QUERY_MAPPING` direction: QueryResult field → API field
+- [ ] `CQRSCommandMapping` direction: API field → Command parameter
+- [ ] `CQRSQuery` present on `CQRSCreate`/`CQRSPartialUpdate` when full object must be returned
+- [ ] No `SerializedName` — mappings only
+
+**Forbidden practices (CI-enforced)**
+- [ ] No custom normalizers or processors in the module
+- [ ] No Value Objects in properties
+
+**Exception handling & validation**
+- [ ] `ConstraintException` → 422, `NotFoundException` → 404
+- [ ] Correct `validationContext` groups on Create / Update operations
+
+**Multi-shop**
+- [ ] `shopIds` present and mapped if entity is shop-associated, absent otherwise
+- [ ] Shop context (`[_context][shopId]`, `[_context][shopConstraint]`) passed when needed
+
+**Listing field alignment** (when PR includes a list endpoint)
+- [ ] DTO properties match fields from the grid query builder / CQRS query result
+- [ ] `ApiResourceMapping` covers every name mismatch between source fields and DTO
+- [ ] `filtersMapping` covers every filter name that differs from the API field name
+- [ ] No orphan DTO property (property with no matching source field → always `null`)
+
+**Integration test**
+- [ ] Extends `ApiTestCase`, `@depends` chain, asserts all fields
+- [ ] `testInvalid*` with `assertValidationErrors`
+- [ ] `getProtectedEndpoints()` lists all URIs
+- [ ] `DatabaseDump::restoreTables()` covers all affected tables
+- [ ] `declare(strict_types=1)` present
+```

.claude/skills/ps-api-endpoint/README.md

@@ -0,0 +1,68 @@
+# ps-api-endpoint skill
+
+Generates new PrestaShop Admin API endpoints for the `ps_apiresources` module — specifically, an **ApiResource PHP class** and a matching **integration test** — following the module's CQRS patterns and contribution guidelines.
+
+## Trigger
+
+Claude invokes this skill automatically when you express intent to:
+
+- Add a new REST endpoint to the Admin API
+- Expose a new entity via the Admin API
+- Contribute a new resource to `ps_apiresources`
+- Wire up a CQRS command or query to an API endpoint in PrestaShop 9
+
+Example phrases: `"I want to add TaxRule to the API"`, `"create an endpoint for Warehouse"`, `"how do I expose AttributeGroup via the Admin API?"`
+
+## Prerequisites
+
+Have the following ready before invoking:
+
+1. **Entity name** — PascalCase singular (e.g. `TaxRule`, `Warehouse`)
+2. **Operations** — which HTTP methods are needed: GET, POST, PATCH, DELETE, list (paginated), bulk operations
+3. **PrestaShop core path** — absolute path to a local PS 9.x checkout (e.g. `/home/user/prestashop-90x`), so the skill can discover CQRS classes. You can skip this if you already know the CQRS class names.
+
+## What it generates
+
+| File | Path |
+|------|------|
+| ApiResource class | `src/ApiPlatform/Resources/{Entity}/{Entity}.php` |
+| Integration test | `tests/Integration/ApiPlatform/{Entity}EndpointTest.php` |
+
+The **ApiResource class** contains:
+- `#[ApiResource]` attribute with all requested operations (`CQRSGet`, `CQRSCreate`, `CQRSPartialUpdate`, `CQRSDelete`, `PaginatedList`)
+- Public properties with strict types and Symfony validation constraints
+- `QUERY_MAPPING` — maps CQRS query result fields to API response fields
+- `CREATE_COMMAND_MAPPING` / `UPDATE_COMMAND_MAPPING` (or a shared `COMMAND_MAPPING`) — maps API request fields to CQRS command parameters
+- OAuth2 scopes (`{entity}_read`, `{entity}_write`) and exception-to-HTTP-status mappings
+
+The **integration test** contains:
+- Full CRUD test methods chained via `@depends`
+- A `testInvalid*` method covering validation errors
+- `getProtectedEndpoints()` verifying all endpoints require authentication
+- `setUpBeforeClass`/`tearDownAfterClass` with table restoration via `DatabaseDump`
+
+## Usage example
+
+```
+User:  I want to add a GET and POST endpoint for TaxRule.
+       My PS core is at /home/dev/prestashop.
+
+Claude: [invokes ps-api-endpoint skill]
+        — Asks for confirmation of operations and fields
+        — Reads /home/dev/prestashop/src/Core/Domain/TaxRule/...
+        — Generates src/ApiPlatform/Resources/TaxRule/TaxRule.php
+        — Generates tests/Integration/ApiPlatform/TaxRuleEndpointTest.php
+        — Reports file locations and how to run the tests
+```
+
+## Skill file structure
+
+```
+.claude/skills/ps-api-endpoint/
+├── README.md              # This file — human-facing orientation
+├── SKILL.md               # Skill logic executed by Claude (step-by-step instructions,
+│                          #   templates for ApiResource class and integration test)
+└── references/
+    └── conventions.md     # Naming and structural conventions (URI format, scope naming,
+                           #   property rules, mapping patterns, forbidden practices)
+```