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 JWT Authentication** is an open-source WordPress plugin that adds JWT (JSON Web Token) authentication support to CoCart. It enables stateless authentication for headless and decoupled storefronts using CoCart's REST API.
18 
19- **Plugin file:** `cocart-jwt-authentication.php`
20- **Main class:** `CoCart\JWTAuthentication\Plugin` (namespaced)
21- **Autoloader:** PSR-4 via Composer (`CoCart\JWTAuthentication\` → `includes/classes/`)
22- **Constant:** `COCART_JWT_AUTHENTICATION_FILE`
23- **Text domain:** `cocart-jwt-authentication`
24- **PHP minimum:** 7.4
25- **WordPress minimum:** 6.0
26- **WooCommerce minimum:** 7.0
27- **CoCart minimum:** 4.3
28- **Default branch:** `master`
29- **License:** GPLv3 — public repository, open-source
30 
31## Repository Structure
32 
33```text
34cocart-jwt-authentication.php       # Main plugin file — defines constants, boots plugin
35includes/
36├── class-cocart-jwt-authentication.php   # Boots CoCart\JWTAuthentication\Plugin
37├── abstracts/                            # Abstract base classes
38└── classes/                             # All feature classes (namespaced)
39    ├── class-cocart-jwt-plugin.php       # Main plugin class (singleton)
40    └── rest-api/                         # REST API controllers and auth handlers
41assets/
42├── scss/                               # SCSS source — only this is tracked in git
43├── css/                                # Compiled CSS — generated by CI, not tracked
44├── js/                                 # JS source; *.min.js compiled by CI, not tracked
45└── images/                             # Static images
46languages/                              # Only README.md tracked; .pot/.po/.mo generated by CI
47tests/
48└── unit/                               # PHPUnit unit test classes
49bin/
50└── install-wp-tests.sh                 # WordPress test environment installer
51```
52 
53## Key Conventions
54 
55### PHP
56 
57- Follow [WordPress Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/)
58- All classes use the `CoCart\JWTAuthentication\` namespace — do not add global class names
59- Use `cocart-jwt-authentication` as the text domain in all translatable strings
60- Use numbered arguments in `printf`/`sprintf` when replacing more than one value: `%1$s`, `%2$s`
61- Use sentence case for translatable strings: `Some thing` not `Some Thing`
62- Avoid HTML in strings — insert via `sprintf` instead
63- Do not call deprecated functions from plugin source; use replacement functions directly
64- Use `COCART_JWT_AUTHENTICATION_FILE` constant — do not hardcode the plugin path
65 
66### REST API
67 
68- Authentication handlers live in `includes/classes/rest-api/`
69- CoCart uses WooCommerce Data Stores API for session management — not WooCommerce default sessions
70- This plugin extends CoCart's authentication layer — do not bypass CoCart's auth hooks
71- JWT tokens are issued and validated here — do not duplicate logic in controllers
72 
73### CSS/JS
74 
75- Edit SCSS source in `assets/scss/` — never edit compiled CSS in `assets/css/`
76- Compiled CSS and minified JS are generated by CI (`npx grunt css js`) — do not commit them
77- RTL CSS is auto-generated from compiled CSS — do not create RTL files manually
78 
79## Build Commands
80 
81```bash
82# Install dependencies
83npm ci
84composer install
85 
86# Compile CSS and JS
87npx grunt css js
88 
89# Watch for changes during development
90npx grunt watch
91 
92# Code standards
93composer phpcs          # Check PHP coding standards
94composer phpcbf         # Auto-fix coding standards issues
95composer phpstan        # Static analysis
96 
97# Download translations
98npx grunt get-translations
99 
100# Fix text domain references
101npm run fix:textdomain
102```
103 
104## Development Workflow
105 
1061. Make code changes
1072. Run `composer phpcs` on changed PHP files — fix all violations before continuing
1083. Run `composer phpstan` on changed PHP files — fix errors in code, never add to baseline
1094. Run `vendor/bin/phpunit` — all tests must pass before committing
1105. Compile assets if SCSS/JS changed: `npx grunt css js`
1116. Commit only after checks are clean
1127. Open a pull request against `master`
113 
114### Pre-commit Checks
115 
116**Before committing PHP changes**, run these to avoid CI failures:
117 
118```bash
119# Check coding standards on changed files
120composer phpcs
121 
122# Static analysis
123composer phpstan
124 
125# Run the test suite
126vendor/bin/phpunit
127```
128 
129**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.
130 
131## Known Constraints
132 
133### Project Structure
134 
135- Never add standalone global functions — all code must use the `CoCart\JWTAuthentication\` namespace
136- Never modify `CHANGELOG.md` — updated by the CoCart team only
137- Never commit compiled CSS (`assets/css/`) or minified JS (`assets/js/**/*.min.js`) — generated by CI
138- Never commit `.pot` files — generated by CI
139- Never edit RTL CSS files manually — auto-generated from compiled CSS
140- All new classes go in `includes/classes/` under the appropriate subdirectory
141 
142### JavaScript
143 
144- Never write inline JavaScript — all JS must live in enqueued script files so it can be compiled, linted, and minified
145- Never use dynamic code execution functions (`call`, `apply`, `Function` constructor, or similar patterns that execute strings as code)
146- Never enqueue scripts or styles outside the designated admin class
147 
148### PHP Constraints
149 
150- Never use `var_dump()`, `print_r()`, or `error_log()` in committed code — remove all debug output before committing
151- Never access `$_GET`, `$_POST`, or `$_SERVER` directly in REST API controllers — use `WP_REST_Request` parameter methods
152- Never write raw database queries — use WooCommerce Data Stores or existing CoCart abstractions
153- Never use `wp_die()` inside REST API controllers — return a `WP_Error` instance instead
154- Never output unescaped content — use `esc_html()`, `esc_attr()`, `wp_json_encode()`, or the appropriate escaping function
155- Never hardcode credentials, tokens, or API keys — use WordPress options or constants defined outside the codebase
156 
157## What Not to Touch
158 
159- **`CHANGELOG.md`** — updated by the CoCart team, not contributors
160- **`languages/*.pot`** — generated by CI (`wp i18n make-pot`), not tracked in git
161- **`assets/css/`** — compiled by CI, not tracked in git
162- **`assets/js/**/*.min.js`** — compiled by CI, not tracked in git
163- **`vendor/`** — managed by Composer, not tracked in git
164- **`node_modules/`** — managed by npm, not tracked in git
165 
166## Creating Branches
167 
168Branch names follow this structure (`{short-slug}` = brief descriptor of the change):
169 
170- `release/{version}` — release branches
171- `refactor/{short-slug}` — refactors
172- `test/{short-slug}` — test-only changes
173- `fix/{issue-number}-{short-slug}` — bug fixes (always include the issue number)
174- `add/{short-slug}` — new features
175 
176## Commits
177 
178- Each commit should address one atomic unit of work
179- Subject line: imperative mood, no trailing period, max 50 characters (e.g. `Fix token expiry on guest checkout`)
180- Blank line between subject and body
181- Body lines: max 72 characters
182- Explain *what* and *why*, not just *how* — only explain *how* if it isn't obvious
183- Reference the related issue number in the commit body (e.g. `Fixes #123`)
184- Do not amend published commits
185 
186## Agent Rules
187 
188- Run pre-commit checks before every commit — do not skip them for any reason
189- Do not modify generated files (`assets/css/`, `*.min.js`, `*.pot`) — CI overwrites them
190- Do not add entries to the PHPStan baseline — fix the error in code instead
191- Do not create new files when an existing class can be extended or modified
192- Do not reach past a CoCart abstraction to call WordPress or WooCommerce directly — use the abstraction
193- Do not amend commits that have already been pushed
194- Check [What Not to Touch](#what-not-to-touch) before modifying any file you are uncertain about
195- Check [Known Constraints](#known-constraints) before writing any new PHP, JS, or SQL
196