Two files, one repository
cocart-headless/cocart-jwt-authentication ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.
CompareAGENTS.md ↔ Cursor rules
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 2 | 26 | 0 | 7% |
| Commands | 0 | 9 | 0 | 0% |
| Section tags | 2 | 9 | 0 | 18% |
What each file covers
Sections
2 shared · 26 only in A · 0 only in B- − AGENTS.md
- − Navigation
- − Project Overview
- − Repository Structure
- − Key Conventions
- − PHP
- − REST API
- − CSS/JS
- − Build Commands
- − Install dependencies
- − Compile CSS and JS
- − Watch for changes during development
- − Code standards
- − Download translations
- − Fix text domain references
- − Development Workflow
- − Pre-commit Checks
- − Check coding standards on changed files
- − Static analysis
- − Run the test suite
- − Known Constraints
- − Project Structure
- − JavaScript
- − PHP Constraints
- − What Not to Touch
- − Agent Rules
- Creating Branches
- Commits
Commands
0 shared · 9 only in A · 0 only in B- − npm ci
- − composer install
- − npx grunt css js
- − npx grunt watch
- − composer phpcs
- − composer phpcbf
- − composer phpstan
- − npx grunt get-translations
- − npm run fix:textdomain
Section tags
2 shared · 9 only in A · 0 only in B- − setup
- − build
- − test
- − code-style
- − architecture
- − dependencies
- − api
- − ui
- − do-not
- git-pr
- agent-behaviour
Line diff
cocart-headless/cocart-jwt-authentication · AGENTS.md
@@ −1 @@
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
cocart-headless/cocart-jwt-authentication · .cursor/rules/git.mdc
@@ +1 @@
1---
2description: Rules for various git actions that happen with this project.
3globs:
4---
5
6# Creating Branches
7
8Branch names should go by the following structure (anything in "{}" brackets is a placeholder). "{short-slug}" should be replaced with a short name that best describes the changes - do ask for confirmation if needed.
9- `release/{version}` for release branches.
10- `refactor/{short-slug}` for refactors.
11- `test/{short-slug}` for changes that are only test updates or additions.
12- `fix/{short-slug}` for changes that fix a bug. Prompt the user for the issue number the fix is for and include that in the branch name.
13- `add/{short-slug}` for changes that are adding a new feature.
14
15# Commits
16
17Make sure each commit addresses an atomic unit of work that independently works.
18
19Make sure the commit message has a subject line which includes a brief description of the change and (if needed), why it was necessary. Write the subject in the imperative, start with a verb, and do not end with a period. The subject line should be no longer than 50 characters.
20
21There must be an empty line between the subject line and the rest of the commit message (if any). The commit body should be no longer than 72 characters.
22
23The commit message should explain what caused the problem and what its consequences are (if helpful for understanding the changes).
24
25The commit message should explain how the changes achieve the goal, but only if it isn't obvious.
26
@@ −1 +1 @@
1−# AGENTS.md
1+---
2+description: Rules for various git actions that happen with this project.
3+globs:
4+---
25
3−This file provides guidance for AI coding agents (Claude Code, Codex, Gemini CLI, etc.) working in this repository.
6+# Creating Branches
47
5−## Navigation
8+Branch names should go by the following structure (anything in "{}" brackets is a placeholder). "{short-slug}" should be replaced with a short name that best describes the changes - do ask for confirmation if needed.
9+- `release/{version}` for release branches.
10+- `refactor/{short-slug}` for refactors.
11+- `test/{short-slug}` for changes that are only test updates or additions.
12+- `fix/{short-slug}` for changes that fix a bug. Prompt the user for the issue number the fix is for and include that in the branch name.
13+- `add/{short-slug}` for changes that are adding a new feature.
614
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)
15+# Commits
1416
15−## Project Overview
17+Make sure each commit addresses an atomic unit of work that independently works.
1618
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.
19+Make sure the commit message has a subject line which includes a brief description of the change and (if needed), why it was necessary. Write the subject in the imperative, start with a verb, and do not end with a period. The subject line should be no longer than 50 characters.
1820
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
21+There must be an empty line between the subject line and the rest of the commit message (if any). The commit body should be no longer than 72 characters.
3022
31−## Repository Structure
23+The commit message should explain what caused the problem and what its consequences are (if helpful for understanding the changes).
3224
33−```text
34−cocart-jwt-authentication.php # Main plugin file — defines constants, boots plugin
35−includes/
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
41−assets/
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
46−languages/ # Only README.md tracked; .pot/.po/.mo generated by CI
47−tests/
48−└── unit/ # PHPUnit unit test classes
49−bin/
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
83−npm ci
84−composer install
85−
86−# Compile CSS and JS
87−npx grunt css js
88−
89−# Watch for changes during development
90−npx grunt watch
91−
92−# Code standards
93−composer phpcs # Check PHP coding standards
94−composer phpcbf # Auto-fix coding standards issues
95−composer phpstan # Static analysis
96−
97−# Download translations
98−npx grunt get-translations
99−
100−# Fix text domain references
101−npm run fix:textdomain
102−```
103−
104−## Development Workflow
105−
106−1. Make code changes
107−2. Run `composer phpcs` on changed PHP files — fix all violations before continuing
108−3. Run `composer phpstan` on changed PHP files — fix errors in code, never add to baseline
109−4. Run `vendor/bin/phpunit` — all tests must pass before committing
110−5. Compile assets if SCSS/JS changed: `npx grunt css js`
111−6. Commit only after checks are clean
112−7. 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
120−composer phpcs
121−
122−# Static analysis
123−composer phpstan
124−
125−# Run the test suite
126−vendor/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−
168−Branch 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
25+The commit message should explain how the changes achieve the goal, but only if it isn't obvious.
19626
