diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index db235d5..15eef76 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -23,7 +23,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 # The oldest PHP the plugin supports (Requires PHP in plugin.php, # and the live server). @@ -33,7 +33,7 @@ jobs: coverage: none - name: Cache Composer packages - uses: actions/cache@v4 + uses: actions/cache@v6 with: path: ~/.cache/composer/files key: composer-${{ hashFiles('composer.lock') }} @@ -63,7 +63,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 # PHPUnit 12's minimum. - uses: shivammathur/setup-php@v2 @@ -71,13 +71,13 @@ jobs: php-version: '8.3' coverage: none - - uses: actions/setup-node@v4 + - uses: actions/setup-node@v7 with: - node-version: 20 + node-version-file: .nvmrc cache: 'npm' - name: Cache Composer packages - uses: actions/cache@v4 + uses: actions/cache@v6 with: path: ~/.cache/composer/files key: composer-${{ hashFiles('composer.lock') }} @@ -97,11 +97,11 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 - - uses: actions/setup-node@v4 + - uses: actions/setup-node@v7 with: - node-version: 20 + node-version-file: .nvmrc cache: 'npm' - name: Install Node dependencies diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 2f1ea6c..1e1d55d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -14,10 +14,10 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 with: - node-version: 20 + node-version-file: .nvmrc cache: 'npm' - name: Install Node dependencies @@ -33,7 +33,7 @@ jobs: run: ./node_modules/.bin/wp-scripts plugin-zip - name: Release - uses: softprops/action-gh-release@v2 + uses: softprops/action-gh-release@v3 with: files: jc-core-functionality.zip generate_release_notes: true diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..a45fd52 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +24 diff --git a/CLAUDE.md b/CLAUDE.md index 2591024..8522806 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,33 +10,36 @@ A site-specific WordPress plugin for jasonchafin.com. It holds functionality tha ## Commands -Neither `vendor/` nor `node_modules/` is committed. Run `composer install` and `npm install` first. - -- PHP lint: `composer lint` (ruleset in `phpcs.xml.dist`: WordPress standard, `jc` prefix, `jc-core-functionality` text domain, `tests/` excluded). Auto-fix with `composer lint-fix`. Lint one file with `vendor/bin/phpcs `. -- Format: `npm run format` (wp-scripts/Prettier). `acf-json/` and `CHANGELOG.md` are excluded in `.prettierignore` because tools write them. -- Tests: - - JS/config checks: `npm run test:unit` (Node's built-in `node:test`, files in `tests/*.test.js`). Run one file with `node --test tests/.test.js`. - - PHP: `composer test` or `npm run test:php` (PHPUnit, files in `tests/php/`). Run one test with `vendor/bin/phpunit --filter `. - - The PHP tests run without WordPress. `tests/php/bootstrap.php` stubs only the WP functions the loaded feature files call, and records the calls. A new feature file under test needs its WP calls stubbed there and a `require_once` added. - - `npm test` runs both suites. - - PHPUnit 12 needs PHP 8.3, but the plugin supports 8.0 (`Requires PHP`). Keep plugin code 8.0-compatible; CI checks it with `php -l` on 8.0. -- Hooks and CI: `npm install` sets up a husky pre-commit hook that runs lint-staged (PHPCS on staged PHP, `wp-scripts format` on staged JS/JSON/YAML/Markdown). `.github/workflows/ci.yml` runs on every PR: PHP 8.0 syntax and PHPCS, tests on PHP 8.3, `lint:pkg-json` and a formatting check. -- Release zip: `npm run zip`. It packages only the `files` list in `package.json` into a `jc-core-functionality/` root folder. Run `composer install --no-dev` first, or dev dependencies end up in `vendor/` in the zip. -- Release: `npm run release` (commit-and-tag-version). It bumps `package.json`, `package-lock.json` and the `Version:` header in `plugin.php` (via `wp-plugin-version-updater.js`), updates `CHANGELOG.md` from Conventional Commits, and tags `vX.Y.Z`. Pushing the tag triggers `.github/workflows/release.yml`, which runs `composer install --no-dev` and `plugin-zip`, then attaches `jc-core-functionality.zip` to a GitHub release. -- Release candidates: `npm run release -- --prerelease rc` tags `vX.Y.Z-rc.N`. The workflow publishes `-rc` tags as GitHub prereleases. PUC reads `/releases/latest`, which skips prereleases, so installed sites never see RCs. To test an RC on staging, install its zip by hand. If an RC is ever published without the prerelease flag, every site with the updater is offered it. +Neither `vendor/` nor `node_modules/` is committed. Run `composer install` and `npm install` first. Use Node 24 (`.nvmrc`; `nvm use`), which CI and the release workflow also read; `engines.node` follows `@wordpress/scripts`. + +- PHP lint: `composer lint` (ruleset in `phpcs.xml.dist`: WordPress standard, `jc` prefix, `jc-core-functionality` text domain, `tests/` excluded). Auto-fix with `composer lint-fix`. Lint one file with `vendor/bin/phpcs `. +- Format: `npm run format` (wp-scripts/Prettier). `acf-json/` and `CHANGELOG.md` are excluded in `.prettierignore` because tools write them. +- Tests: + - JS/config checks: `npm run test:unit` (Node's built-in `node:test`, files in `tests/*.test.js`). Run one file with `node --test tests/.test.js`. + - PHP: `composer test` or `npm run test:php` (PHPUnit, files in `tests/php/`). Run one test with `vendor/bin/phpunit --filter `. + - The PHP tests run without WordPress. `tests/php/bootstrap.php` stubs only the WP functions the loaded feature files call, and records the calls. A new feature file under test needs its WP calls stubbed there and a `require_once` added. + - `npm test` runs both suites. + - PHPUnit 12 needs PHP 8.3, but the plugin supports 8.0 (`Requires PHP`). Keep plugin code 8.0-compatible; CI checks it with `php -l` on 8.0. +- Hooks and CI: `npm install` sets up a husky pre-commit hook that runs lint-staged (PHPCS on staged PHP, `wp-scripts format` on staged JS/JSON/YAML/Markdown). `.github/workflows/ci.yml` runs on every PR: PHP 8.0 syntax and PHPCS, tests on PHP 8.3, `lint:pkg-json` and a formatting check. +- Release zip: `npm run zip`. It packages only the `files` list in `package.json` into a `jc-core-functionality/` root folder. Run `composer install --no-dev` first, or dev dependencies end up in `vendor/` in the zip. +- Release: `npm run release` (commit-and-tag-version). It bumps `package.json`, `package-lock.json` and the `Version:` header in `plugin.php` (via `wp-plugin-version-updater.js`), updates `CHANGELOG.md` from Conventional Commits, and tags `vX.Y.Z`. Pushing the tag triggers `.github/workflows/release.yml`, which runs `composer install --no-dev` and `plugin-zip`, then attaches `jc-core-functionality.zip` to a GitHub release. +- Release candidates: `npm run release -- --prerelease rc` tags `vX.Y.Z-rc.N`. The workflow publishes `-rc` tags as GitHub prereleases. PUC reads `/releases/latest`, which skips prereleases, so installed sites never see RCs. To test an RC on staging, install its zip by hand. If an RC is ever published without the prerelease flag, every site with the updater is offered it. ## Architecture -- `plugin.php` is the only bootstrap. It defines `JC_DIR`, registers the update checker (below), adds a Settings link on the Plugins screen, and `include_once`s each file in `lib/functions/`. A new feature file needs its own include line added there. Nothing is namespaced or class-based: everything is global functions with a `jc_` prefix, hooked at file load. -- **Post types and custom fields live in `acf-json/`, not in PHP.** `general.php` redirects ACF's JSON load/save point to `JC_DIR . '/acf-json'`, and deliberately removes the theme's default load path, so the plugin is the only source of the content model. The `person` (People) and `quote` (Quotes) CPTs and their field groups are created by ACF from these JSON files. Edit them in the ACF admin UI so the JSON is rewritten, rather than by hand. -- Code depends on these ACF-defined objects by name. The `[quotes]` shortcode (`shortcodes.php`) queries post type `quote`. `general.php` registers the `subtitle` post meta for REST, and that name matches the ACF "Posts" field group. -- Block Bindings sources are registered in `general.php`: `jc/copyright` and `jc/user-data` (args `key` = `name|description|avatar` and `userId`). The settings page in `settings.php` is a static info page that documents features. Update it when you add user-facing features. -- **Updates come from GitHub releases** through plugin-update-checker (PUC), a Composer runtime dependency loaded from `vendor/`. It runs only in admin, cron and WP-CLI, and installs only the `jc-core-functionality.zip` release asset. The slug `jc-core-functionality` must match in `plugin.php`, `uninstall.php` (PUC's option, transient and cron names), `package.json` `name` and the release workflow. `tests/update-checker-config.test.js` enforces this. -- `uninstall.php` removes only PUC's data. By policy, `person` and `quote` content is never deleted. -- `gtm.php` loads GTM container `GTM-WNP9BDSD` by default (override with a `JC_GTM_ID` constant or the `jc_gtm_container_id` filter; `''` or an invalid ID disables it), and skips users with `manage_options`. `security-headers.php` builds a nonce-based CSP (`jc_csp_directives()`, filterable through `jc_csp_directives`) and sends it as Report-Only until `jc_csp_report_only` returns false. Admin and the Customizer preview are excluded. `csp-report.php` adds the `/wp-json/jc/v1/csp-report` endpoint, which logs violations as `[jc-csp]` lines in the PHP error log. Scripts must be printed through the script API to get the nonce; `tests/code-standards.test.js` rejects raw `