AGENTS.md

1# AGENTS.md
2 
3This file provides guidance for AI coding agents (Claude Code, Codex, Gemini CLI, etc.) working in this repository.
4 
5## Navigation
6 
7- Locating files or understanding structure → [Repository Structure](#repository-structure)
8- Writing or reviewing PHP → [Key Conventions → PHP](#php) + [Known Constraints → PHP Constraints](#php-constraints)
9- Working on REST API controllers → [Key Conventions → REST API](#rest-api)
10- Editing styles or scripts → [Key Conventions → CSS/JS](#cssjs) + [Known Constraints → JavaScript](#javascript)
11- Checks required before committing → [Development Workflow](#development-workflow)
12- Branch naming or commit format → [Creating Branches](#creating-branches) + [Commits](#commits)
13- Verifying whether a file is safe to modify → [What Not to Touch](#what-not-to-touch)
14 
15## Project Overview
16 
17**CoCart Community** is an open-source, developer-first REST API plugin for WooCommerce. It exposes product browsing, cart management, and session handling as a WordPress REST API — purpose-built for headless and decoupled storefronts.
18 
19- **Plugin file:** `cart-rest-api-for-woocommerce.php`
20- **Main class:** `includes/class-cocart.php` → singleton via `CoCart()`
21- **Autoloader:** `includes/class-cocart-autoloader.php` (PSR-4 from `includes/`)
22- **Text domain:** `cart-rest-api-for-woocommerce`
23- **PHP minimum:** 8.2
24- **WordPress minimum:** 6.7
25- **WooCommerce minimum:** 9.0
26- **Default branch:** `trunk`
27- **License:** GPLv3+
28 
29## Repository Structure
30 
31```text
32cart-rest-api-for-woocommerce.php   # Main plugin file — defines constants, boots plugin
33load-package.php                    # Package loader
34uninstall.php                       # Uninstall cleanup
35includes/
36├── class-cocart.php                # Main class — hooks, init, load sequence
37├── class-cocart-autoloader.php     # PSR-4 autoloader
38├── cocart-*.php                    # Standalone function files (formatting, deprecated, etc.)
39├── abstracts/                      # Abstract base classes
40├── classes/
41│   ├── rest-api/                   # REST API controllers, authentication, caching, responses
42│   ├── admin/                      # WordPress admin UI, notices, setup wizard, update checks
43│   ├── cli/                        # WP-CLI commands
44│   └── integrations/               # Third-party plugin compatibility handlers
45└── utilities/                      # Shared utility helpers
46assets/
47├── scss/                           # SCSS source — only this is tracked in git
48├── css/                            # Compiled CSS — generated by CI, not tracked
49├── js/                             # JS source; *.min.js compiled by CI, not tracked
50└── images/                         # Static images
51languages/                          # Only README.md tracked; .pot/.po/.mo generated by CI
52bin/                                # Release and build shell scripts
53```
54 
55## Key Conventions
56 
57### PHP
58 
59- Follow [WordPress Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/)
60- Use `cart-rest-api-for-woocommerce` as the text domain in all translatable strings
61- Use numbered arguments in `printf`/`sprintf` when replacing more than one value: `%1$s`, `%2$s`
62- Use sentence case for translatable strings: `Some thing` not `Some Thing`
63- Avoid HTML in strings — insert via `sprintf` instead
64- Do not call deprecated functions from plugin source; use replacement functions directly
65- Use `COCART_FILE` and `COCART_SLUG` constants — do not hardcode the plugin path or slug
66 
67### REST API
68 
69- REST API controllers live in `includes/classes/rest-api/`
70- CoCart uses WooCommerce Data Stores API for session management — not WooCommerce default sessions
71- ETag support, cache headers, and CORS handling are built-in — do not bypass them
72- Authentication is via JWT or Basic Auth only — no cookie/nonce auth for API requests
73 
74### CSS/JS
75 
76- Edit SCSS source in `assets/scss/` — never edit compiled CSS in `assets/css/`
77- Compiled CSS and minified JS are generated by CI (`npx grunt css js`) — do not commit them
78- RTL CSS is auto-generated from compiled CSS — do not create RTL files manually
79 
80## Build Commands
81 
82```bash
83# Install dependencies
84npm ci
85composer install
86 
87# Compile CSS and JS
88npx grunt css js
89 
90# Watch for changes during development
91npx grunt watch
92 
93# Code standards
94composer phpcs          # Check PHP coding standards
95composer phpcbf         # Auto-fix coding standards issues
96composer phpstan        # Static analysis
97 
98# Fix text domain references
99npm run fix:textdomain
100```
101 
102## Development Workflow
103 
1041. Make code changes
1052. Run `composer phpcs` on changed PHP files — fix all violations before continuing
1063. Run `composer phpstan` on changed PHP files — fix errors in code, never add to baseline
1074. Compile assets if SCSS/JS changed: `npx grunt css js`
1085. Commit only after checks are clean
1096. Open a pull request against `trunk`
110 
111### Pre-commit Checks
112 
113**Before committing PHP changes**, run these to avoid CI failures:
114 
115```bash
116# Check coding standards on changed files
117composer phpcs
118 
119# Static analysis
120composer phpstan
121```
122 
123**PHPStan baseline policy:** The baseline file (`phpstan-baseline.neon`) must never grow. If PHPStan reports a new error, fix it in the code. If your fix resolves a previously baselined error, remove the corresponding entry from the baseline. The baseline should only shrink over time.
124 
125## Known Constraints
126 
127### Project Structure
128 
129- Never add standalone global functions outside the designated `includes/cocart-*.php` function files
130- Never modify `CHANGELOG.md` — updated by the CoCart team only
131- Never commit compiled CSS (`assets/css/`) or minified JS (`assets/js/**/*.min.js`) — generated by CI
132- Never commit `.pot` files — generated by CI
133- Never edit RTL CSS files manually — auto-generated from compiled CSS
134- All new classes go in `includes/classes/` under the appropriate subdirectory
135- `includes/` legacy function files should only be modified when no class-based alternative exists
136 
137### JavaScript
138 
139- Never write inline JavaScript — all JS must live in enqueued script files so it can be compiled, linted, and minified
140- Never use dynamic code execution functions (`call`, `apply`, `Function` constructor, or similar patterns that execute strings as code)
141- Never enqueue scripts or styles outside the designated admin class
142 
143### PHP Constraints
144 
145- Never use `var_dump()`, `print_r()`, or `error_log()` in committed code — remove all debug output before committing
146- Never access `$_GET`, `$_POST`, or `$_SERVER` directly in REST API controllers — use `WP_REST_Request` parameter methods
147- Never write raw database queries — use WooCommerce Data Stores or existing CoCart abstractions
148- Never use `wp_die()` inside REST API controllers — return a `WP_Error` instance instead
149- Never output unescaped content — use `esc_html()`, `esc_attr()`, `wp_json_encode()`, or the appropriate escaping function
150- Never hardcode credentials, tokens, or API keys — use WordPress options or constants defined outside the codebase
151- Never read options directly where a CoCart settings abstraction already exists — use the abstraction
152 
153## What Not to Touch
154 
155- **`CHANGELOG.md`** — updated by the CoCart team, not contributors
156- **`languages/*.pot`** — generated by CI (`wp i18n make-pot`), not tracked in git
157- **`assets/css/`** — compiled by CI, not tracked in git
158- **`assets/js/**/*.min.js`** — compiled by CI, not tracked in git
159- **`vendor/`** — managed by Composer, not tracked in git
160- **`node_modules/`** — managed by npm, not tracked in git
161- **`.phpcs.xml.dist`** — do not change coding standard rules without discussion
162 
163## Creating Branches
164 
165Branch names follow this structure (`{short-slug}` = brief descriptor of the change):
166 
167- `release/{version}` — release branches
168- `refactor/{short-slug}` — refactors
169- `test/{short-slug}` — test-only changes
170- `fix/{issue-number}-{short-slug}` — bug fixes (always include the issue number)
171- `add/{short-slug}` — new features
172 
173## Commits
174 
175- Each commit should address one atomic unit of work
176- Subject line: imperative mood, no trailing period, max 50 characters (e.g. `Fix session expiry on guest checkout`)
177- Blank line between subject and body
178- Body lines: max 72 characters
179- Explain *what* and *why*, not just *how* — only explain *how* if it isn't obvious
180- Reference the related issue number in the commit body (e.g. `Fixes #123`)
181- Do not amend published commits
182 
183## Agent Rules
184 
185- Run pre-commit checks before every commit — do not skip them for any reason
186- Do not modify generated files (`assets/css/`, `*.min.js`, `*.pot`) — CI overwrites them
187- Do not add entries to the PHPStan baseline — fix the error in code instead
188- Do not create new files when an existing class can be extended or modified
189- Do not reach past a CoCart abstraction to call WordPress or WooCommerce directly — use the abstraction
190- Do not amend commits that have already been pushed
191- Check [What Not to Touch](#what-not-to-touch) before modifying any file you are uncertain about
192- Check [Known Constraints](#known-constraints) before writing any new PHP, JS, or SQL
193