# AGENTS.md

## Cursor Cloud specific instructions

### Project overview
Security Ninja is a premium WordPress security plugin (v5.271). It runs exclusively within a WordPress installation and has no standalone mode. The codebase is PHP-only with Composer for dependency management; there is no Node.js/npm build pipeline.

### Development environment
- **Stack**: PHP 8.2, Composer, MariaDB 10.11, Apache 2.4, WordPress 6.9.1
- **WordPress install**: `/var/www/html` with the plugin symlinked at `wp-content/plugins/security-ninja -> /workspace`
- **WordPress admin**: http://localhost/wp-admin/ (user: `admin`, password: `admin123`)
- **wp-config.php** must include `define('FS_METHOD', 'direct');` for the plugin to work properly (avoids FTP filesystem prompts)
- The plugin is symlinked and activated. To re-activate after a reset: `cd /var/www/html && sudo wp plugin activate security-ninja --allow-root`

### Starting services
After a fresh VM boot, MariaDB and Apache need to be started before WordPress/the plugin can be tested:
```bash
sudo mkdir -p /run/mysqld && sudo chown mysql:mysql /run/mysqld
sudo mysqld_safe &
sleep 2
sudo apachectl start
```

### Lint and code quality
CI runs three checks (see `.github/workflows/php-test.yml`):
1. **PHP Syntax** (critical, must pass): `find . -name "*.php" -not -path "./vendor/*" -exec php -l {} \;`
2. **WordPress Coding Standards** (non-blocking): `vendor/bin/phpcs --standard=WordPress-Extra --extensions=php --ignore=vendor,node_modules .`
3. **PHP Compatibility** (non-blocking): `vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.2 --extensions=php --ignore=vendor,node_modules .`

Before running PHPCS, install coding standards: `composer run install-standards`

### Gotchas
- The `composer install` pre-install scripts run `find` on `./vendor` which may emit harmless errors on first run when vendor doesn't exist yet.
- The Imposter plugin rewrites vendor namespaces during `composer install`/`update`; this is expected behavior.
- File ownership: if `www-data` takes ownership of workspace files (e.g. from Apache writes), reset with `sudo chown -R ubuntu:ubuntu /workspace` before git operations.
- There are no automated unit/integration tests (no PHPUnit); testing is manual via the WordPress admin or WP-CLI.
