Runtime matrix: test the release package, formatter parity, and write routes; add dev write-API Playground

[dknauss]

Summary

What changed?

1. The runtime matrix tests what users install.

• The matrix used to mount the source checkout, which has no vendor/, so citeproc-php was missing in every cell and the formatter never ran on PHP 7.4–8.4.
• Each cell now runs npm run package:release and mounts the package (WP_BIBLIO_PLUGIN_DIR), with its production-only vendor/.
• The workflow gains two steps in both jobs: set up PHP 8.3 with Composer, then package the release.

2. New smoke steps in every cell (scripts/runtime-matrix/smoke.sh):

• Formatter parity (format-styles.php, run with wp eval-file). It formats tests/fixtures/csl-styles/items.json in all nine styles on that cell's PHP version and compares the output byte for byte with the reviewed goldens. Until now, PHPUnit pinned the styles on PHP 8.3 only.

• Write routes over real HTTP. A test-only mu-plugin enables the routes and an application password authenticates, with WP_ENVIRONMENT_TYPE=local. The step:

  • runs a dry run, whose ETag must equal the read route's;
  • expects 428 without If-Match and 412 with a stale ETag;
  • makes a real write, which must return a new ETag;
  • checks the new entry in the text route (full Chicago form) and on the front end;
  • checks with check-blocks.php that the rewritten block's markup equals save()'s.

  Real HTTP also shows that Authorization, ETag, and If-Match survive both Apache and nginx.

3. A development-only Playground for the write routes (playground/blueprint-write-api.json, not linked from any badge).

• It boots the main build with the routes enabled, plus a borgesWrite helper in the block editor's browser console (playground/dev/, fetched from main).
• Every call makes a dry run first. With { commit: true } it writes, sending the dry run's ETag, then reloads the editor so a stale editor can't overwrite the write on save.
• The blueprint is generated like the others by npm run playground:build, and src/playground-demo.test.js keeps it in sync.

Once merged, open it with: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/dknauss/Borges/main/playground/blueprint-write-api.json

Docs: README (the matrix section and blueprint maintenance), CLAUDE.md, docs/rest-write-routes.md (a new "Trying it" section), and the CHANGELOG.

Why? To close the gaps named after #104: the formatter and the write routes had no coverage across PHP and WordPress versions, and there was no easy way to try the write routes by hand.

Validation

• npm run lint:js passes
• npm run lint:css: no CSS changes
• npm run lint:i18n: no source strings changed
• npm run test passes (873)
• composer test:php (310) and verify-metrics.sh pass
• Tested locally in Playground (CLI 3.1.40, WordPress trunk), mounting the packaged release rather than the checkout:
  • format-styles.php: styles-ok 180;
  • the smoke script's own HTTP write sequence, extracted verbatim, passes: dry run, 428, 412, commit, text route, front end;
  • check-blocks.php: blocks-ok 1;
  • the dev blueprint's console helper works: list(), the add and patch dry runs, the clear 409 message on an APA reorder, and a committed add. The editor then reopens with every block valid and nothing unsaved.
• The Docker matrix itself: I couldn't run it here, because Docker Hub rate-limited the mariadb pull and the mirror's CDN is blocked. This PR's CI runs the 3-cell PR subset, and the full 10 cells run on merge.

Checklist

• Linked issue or explained why none was needed: requested directly (matrix smoke step and dev blueprint).
• No sensitive details disclosed publicly

🤖 Generated with Claude Code

https://claude.ai/code/session_01KbVuMPN7YTcV27vwsG3LZ2

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.20%. Comparing base (685a083) to head (b4968fa).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #105   +/-   ##
=======================================
  Coverage   87.20%   87.20%           
=======================================
  Files          54       54           
  Lines        5847     5847           
  Branches      597      597           
=======================================
  Hits         5099     5099           
  Misses        267      267           
  Partials      481      481           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.