From fd63dbe2de07c887cc1027ea9a1b7402850c00aa Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:37:12 +0530 Subject: [PATCH 01/25] fix(encryptor): reject payloads shorter than the IV plus a full tag OpenSSL verifies a truncated GCM tag at its truncated length. A forged 13-byte payload (12-byte IV, 1 tag byte, empty ciphertext) therefore decrypted to an empty string for 1 in 256 tag values instead of failing, and payloads shorter than the IV reached OpenSSL with a short IV. decrypt() now returns false for any decoded payload shorter than IV_LENGTH + TAG_LENGTH before calling OpenSSL. The new tests try all 256 one-byte tags, cover short payload lengths, and confirm an encrypted empty string (the smallest valid 28-byte payload) still round-trips. --- inc/Utils/Encryptor.php | 8 ++++++ tests/Utils/EncryptorTest.php | 47 +++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) diff --git a/inc/Utils/Encryptor.php b/inc/Utils/Encryptor.php index 23a22e6..f81510b 100644 --- a/inc/Utils/Encryptor.php +++ b/inc/Utils/Encryptor.php @@ -125,6 +125,14 @@ public function decrypt( string $raw_value ): string|false { return false; } + // A valid payload always carries a full IV and a full-length tag. Reject + // anything shorter before it reaches OpenSSL: GCM verifies a truncated tag + // at its truncated length, so a 13-byte payload (IV + 1 tag byte, empty + // ciphertext) would decrypt to '' for 1 in 256 forged tags. + if ( strlen( $decoded_value ) < static::IV_LENGTH + static::TAG_LENGTH ) { + return false; + } + $iv = substr( $decoded_value, 0, static::IV_LENGTH ); $tag = substr( $decoded_value, static::IV_LENGTH, static::TAG_LENGTH ); $ciphertext = substr( $decoded_value, static::IV_LENGTH + static::TAG_LENGTH ); diff --git a/tests/Utils/EncryptorTest.php b/tests/Utils/EncryptorTest.php index 1509efb..85fe68c 100644 --- a/tests/Utils/EncryptorTest.php +++ b/tests/Utils/EncryptorTest.php @@ -90,6 +90,53 @@ public function test_decrypt_returns_false_for_tampered_ciphertext(): void { $this->assertFalse( $encryptor->decrypt( $tampered ) ); } + public function test_decrypt_rejects_a_truncated_tag_for_every_tag_value(): void { + // Regression: a payload holding only the IV plus a 1-byte "tag" left the + // ciphertext empty, and OpenSSL authenticates a truncated GCM tag at its + // truncated length, so 1 of these 256 forgeries decrypted to ''. Every + // candidate must be rejected now, not just most of them. + $encryptor = $this->encryptor(); + $iv = str_repeat( "\x01", 12 ); + + for ( $byte = 0; $byte < 256; $byte++ ) { + $forged = base64_encode( $iv . chr( $byte ) ); + + $this->assertFalse( $encryptor->decrypt( $forged ), sprintf( 'Tag byte 0x%02x was accepted.', $byte ) ); + } + } + + /** + * @dataProvider data_short_payload_lengths + * + * @param int $length Decoded payload length, shorter than IV + tag. + */ + public function test_decrypt_rejects_payloads_shorter_than_iv_plus_tag( int $length ): void { + $this->assertFalse( $this->encryptor()->decrypt( base64_encode( str_repeat( 'x', $length ) ) ) ); + } + + /** + * @return array + */ + public function data_short_payload_lengths(): array { + return [ + 'empty' => [ 0 ], + 'shorter than the IV' => [ 5 ], + 'IV only' => [ 12 ], + 'IV plus partial tag' => [ 27 ], + ]; + } + + public function test_empty_plaintext_roundtrips(): void { + // The smallest legitimate payload is IV + full tag with no ciphertext; + // the length guard must still let it through. + $encryptor = $this->encryptor(); + $encrypted = $encryptor->encrypt( '' ); + + $this->assertIsString( $encrypted ); + $this->assertSame( 28, strlen( (string) base64_decode( $encrypted, true ) ) ); + $this->assertSame( '', $encryptor->decrypt( $encrypted ) ); + } + public function test_key_seam_can_be_overridden_by_a_subclass(): void { // A subclass can source the key from anywhere via the key() seam, while // reusing the crypto unchanged. From c5b834034138cfda7a43ae3e47b2f135589df9f2 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:37:12 +0530 Subject: [PATCH 02/25] test(encryptor): cover the fail-closed path when OpenSSL is missing encrypt() and decrypt() return false with a _doing_it_wrong() notice when the OpenSSL extension is absent, but extension_loaded() cannot be faked, so those 12 lines were never executed by the suite. Route the check through a protected is_openssl_available() seam and test both methods through a subclass that reports OpenSSL as unavailable. --- inc/Utils/Encryptor.php | 17 +++++++++++++++-- tests/Utils/EncryptorTest.php | 28 ++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 2 deletions(-) diff --git a/inc/Utils/Encryptor.php b/inc/Utils/Encryptor.php index f81510b..369773f 100644 --- a/inc/Utils/Encryptor.php +++ b/inc/Utils/Encryptor.php @@ -69,7 +69,7 @@ public function __construct( * @throws \RuntimeException If no encryption key is available. */ public function encrypt( string $raw_value ): string|false { - if ( ! extension_loaded( 'openssl' ) ) { + if ( ! $this->is_openssl_available() ) { _doing_it_wrong( __METHOD__, 'OpenSSL extension is not loaded. Encryption cannot proceed.', @@ -105,7 +105,7 @@ public function encrypt( string $raw_value ): string|false { * @throws \RuntimeException If no encryption key is available. */ public function decrypt( string $raw_value ): string|false { - if ( ! extension_loaded( 'openssl' ) ) { + if ( ! $this->is_openssl_available() ) { _doing_it_wrong( __METHOD__, 'OpenSSL extension is not loaded. Decryption cannot proceed.', @@ -147,6 +147,19 @@ public function decrypt( string $raw_value ): string|false { ); } + /** + * Whether the OpenSSL extension is available. + * + * A seam rather than an inline extension_loaded() call so the "no OpenSSL" + * path, which makes encrypt() and decrypt() fail closed, can be exercised by + * a subclass in tests. + * + * @return bool True when OpenSSL can be used. + */ + protected function is_openssl_available(): bool { + return extension_loaded( 'openssl' ); + } + /** * Resolve the raw secret. * diff --git a/tests/Utils/EncryptorTest.php b/tests/Utils/EncryptorTest.php index 85fe68c..4e92969 100644 --- a/tests/Utils/EncryptorTest.php +++ b/tests/Utils/EncryptorTest.php @@ -137,6 +137,34 @@ public function test_empty_plaintext_roundtrips(): void { $this->assertSame( '', $encryptor->decrypt( $encrypted ) ); } + /** + * An Encryptor that behaves as if the OpenSSL extension were missing. + */ + private function encryptor_without_openssl(): Encryptor { + return new class( self::KEY ) extends Encryptor { + protected function is_openssl_available(): bool { + return false; + } + }; + } + + public function test_encrypt_fails_closed_without_openssl(): void { + $encryptor = $this->encryptor_without_openssl(); + $this->setExpectedIncorrectUsage( Encryptor::class . '::encrypt' ); + + $this->assertFalse( $encryptor->encrypt( 'secret' ) ); + } + + public function test_decrypt_fails_closed_without_openssl(): void { + $encrypted = $this->encryptor()->encrypt( 'secret' ); + $this->assertIsString( $encrypted ); + + $encryptor = $this->encryptor_without_openssl(); + $this->setExpectedIncorrectUsage( Encryptor::class . '::decrypt' ); + + $this->assertFalse( $encryptor->decrypt( $encrypted ) ); + } + public function test_key_seam_can_be_overridden_by_a_subclass(): void { // A subclass can source the key from anywhere via the key() seam, while // reusing the crypto unchanged. From 7f593d1e1e46aa54c4e5282eefe468b5e80e8e41 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:37:22 +0530 Subject: [PATCH 03/25] fix(transients): hash names past the 172-character transient limit A DB-backed transient is stored as _transient_{name} and _transient_timeout_{name}, and option_name is varchar(191), so WordPress documents a 172-character limit on the name. A longer namespaced key was truncated by the options table: the value was never found again on the next request, or, just past the limit, its expiry was silently dropped. resolve_key() now maps a namespaced name longer than MAX_NAME_LENGTH to h:. Names within the limit are unchanged, and a hashed name can never equal an unhashed one, which always starts with digits. Tests flush the object cache between write and read to force the database path, which is what used to lose the value. --- inc/Utils/Transients.php | 22 +++++++++++++-- tests/Utils/TransientsTest.php | 49 ++++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+), 2 deletions(-) diff --git a/inc/Utils/Transients.php b/inc/Utils/Transients.php index d2c015d..61c1da1 100644 --- a/inc/Utils/Transients.php +++ b/inc/Utils/Transients.php @@ -35,6 +35,15 @@ */ class Transients { + /** + * Longest transient name WordPress can store. + * + * A DB-backed transient is two option rows, `_transient_{name}` and + * `_transient_timeout_{name}`, and `option_name` is varchar(191), so the name + * itself must be 172 characters or fewer (see set_transient()). + */ + protected const MAX_NAME_LENGTH = 172; + /** * Construct a Transients wrapper bound to a key prefix. * @@ -92,14 +101,23 @@ public function delete( string $key ): bool { * `( 'mod', 'a_b' )` and `( 'mod_a', 'b' )` would both collapse to `mod_a_b` and * silently target the same WordPress transient. * + * A namespaced key longer than {@see Transients::MAX_NAME_LENGTH} is replaced by + * `h:`. WordPress cannot store such a name: the + * option rows are truncated, so the value is never found again (or, just past + * the limit, its expiry is silently lost). Keys within the limit are unchanged, + * and a hashed key can never equal an unhashed one, which always starts with + * digits. + * * Protected override seam (mirrors {@see Cache::resolve_group()}): subclass to - * change the namespacing scheme — for instance a multisite / site-transient variant. + * change the namespacing scheme, for instance a multisite / site-transient variant. * * @param string $key Logical key supplied by the caller. * * @return string Fully namespaced key passed to WordPress's transient API. */ protected function resolve_key( string $key ): string { - return strlen( $this->prefix ) . ':' . $this->prefix . '_' . $key; + $name = strlen( $this->prefix ) . ':' . $this->prefix . '_' . $key; + + return strlen( $name ) > static::MAX_NAME_LENGTH ? 'h:' . md5( $name ) : $name; } } diff --git a/tests/Utils/TransientsTest.php b/tests/Utils/TransientsTest.php index 2a105ac..9d3c18d 100644 --- a/tests/Utils/TransientsTest.php +++ b/tests/Utils/TransientsTest.php @@ -73,6 +73,55 @@ public function test_prefix_key_boundary_is_unambiguous(): void { $this->assertSame( 'two', $two->get( 'y' ) ); } + public function test_over_long_key_still_round_trips_through_the_database(): void { + // Regression: a namespaced name past 172 characters was truncated by the + // options table, so once the in-request option cache was gone (a new request) + // the value could never be read back. Flushing the object cache simulates that. + $store = new Transients( 'rt_long' ); + $key = str_repeat( 'k', 200 ); + + $this->assertTrue( $store->set( $key, 'long-value', HOUR_IN_SECONDS ) ); + + wp_cache_flush(); + + $this->assertSame( 'long-value', $store->get( $key ) ); + $this->assertTrue( $store->delete( $key ) ); + $this->assertFalse( $store->get( $key ) ); + } + + public function test_over_long_keys_stay_distinct_and_within_the_limit(): void { + $store = new Transients( 'rt_long_distinct' ); + $first = str_repeat( 'a', 180 ) . '-one'; + $other = str_repeat( 'a', 180 ) . '-two'; + + $store->set( $first, 'one' ); + $store->set( $other, 'two' ); + wp_cache_flush(); + + $this->assertSame( 'one', $store->get( $first ) ); + $this->assertSame( 'two', $store->get( $other ) ); + + $resolve = new \ReflectionMethod( Transients::class, 'resolve_key' ); + $name = $resolve->invoke( $store, $first ); + + $this->assertLessThanOrEqual( 172, strlen( $name ) ); + $this->assertStringStartsWith( 'h:', $name ); + } + + public function test_key_at_the_limit_is_not_hashed(): void { + // '5:rt_ok_' is 8 characters, so a 164-character key lands exactly on 172. + $store = new Transients( 'rt_ok' ); + $key = str_repeat( 'k', 164 ); + $resolve = new \ReflectionMethod( Transients::class, 'resolve_key' ); + + $this->assertSame( '5:rt_ok_' . $key, $resolve->invoke( $store, $key ) ); + + $store->set( $key, 'at-limit', HOUR_IN_SECONDS ); + wp_cache_flush(); + + $this->assertSame( 'at-limit', $store->get( $key ) ); + } + public function test_value_is_stored_under_the_namespaced_key(): void { ( new Transients( 'rt_ns' ) )->set( 'thing', 'v' ); From 3210a023d3ac318f0176db1a26a63f2e1b538177 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:37:22 +0530 Subject: [PATCH 04/25] test: cover the remaining Cache, Timer and legacy-core registrar paths - Cache: a context-less instance passes groups through verbatim, flush_group() clears only its namespaced group, remember_swr() serves a fresh hit without calling back, and the cold-start lock wait both picks up a value the lock holder publishes and, when the lock never frees, falls back to the callback without releasing the other process's lock. - Timer: lap() with an empty label warns and records nothing. - AbstractAbilityRegistrar: on cores without the Abilities API (the 6.5 to 6.8 matrix cells) calling the callbacks directly is a silent no-op that touches no seam, while the hooks are still added. --- ...AbstractAbilityRegistrarLegacyCoreTest.php | 91 +++++++++++++++ tests/Utils/CacheTest.php | 107 ++++++++++++++++++ tests/Utils/TimerTest.php | 10 ++ 3 files changed, 208 insertions(+) create mode 100644 tests/Contracts/Abstracts/AbstractAbilityRegistrarLegacyCoreTest.php diff --git a/tests/Contracts/Abstracts/AbstractAbilityRegistrarLegacyCoreTest.php b/tests/Contracts/Abstracts/AbstractAbilityRegistrarLegacyCoreTest.php new file mode 100644 index 0000000..e1a0654 --- /dev/null +++ b/tests/Contracts/Abstracts/AbstractAbilityRegistrarLegacyCoreTest.php @@ -0,0 +1,91 @@ +markTestSkipped( 'Only meaningful on cores without the Abilities API (WordPress < 6.9).' ); + } + } + + /** + * A registrar that records every seam the callbacks touch. + */ + private function make_recording_registrar(): AbstractAbilityRegistrar { + return new class() extends AbstractAbilityRegistrar { + /** + * Seams that were called, in order. + * + * @var array + */ + public array $calls = []; + + protected function category_slug(): string { + $this->calls[] = 'category_slug'; + return 'legacy-plugin'; + } + + protected function abilities(): array { + $this->calls[] = 'abilities'; + return []; + } + + protected function category_description(): string { + $this->calls[] = 'category_description'; + return 'Never registered.'; + } + + protected function before_register(): void { + $this->calls[] = 'before_register'; + } + }; + } + + public function test_register_category_is_a_no_op_without_the_abilities_api(): void { + $registrar = $this->make_recording_registrar(); + + $registrar->register_category(); + + $this->assertSame( [], $registrar->calls, 'no seam may run when the API is missing' ); + } + + public function test_register_abilities_is_a_no_op_without_the_abilities_api(): void { + $registrar = $this->make_recording_registrar(); + + $registrar->register_abilities(); + + $this->assertSame( [], $registrar->calls, 'before_register() and abilities() must not run when the API is missing' ); + } + + public function test_hooks_are_still_added_so_a_later_core_upgrade_picks_them_up(): void { + $registrar = $this->make_recording_registrar(); + + $registrar->register_hooks(); + + $this->assertSame( 10, has_action( 'wp_abilities_api_categories_init', [ $registrar, 'register_category' ] ) ); + $this->assertSame( 10, has_action( 'wp_abilities_api_init', [ $registrar, 'register_abilities' ] ) ); + $this->assertSame( [], $registrar->calls, 'adding the hooks must not touch any seam' ); + } +} diff --git a/tests/Utils/CacheTest.php b/tests/Utils/CacheTest.php index c5f9bb9..d43d7dc 100644 --- a/tests/Utils/CacheTest.php +++ b/tests/Utils/CacheTest.php @@ -131,4 +131,111 @@ public function test_remember_swr_returns_stale_without_regenerating_when_lock_i $this->assertSame( 'old', $returned, 'a losing caller is served stale immediately' ); $this->assertFalse( wp_cache_get( 'k', 'ctx-swr-locked:g' ), 'the loser must not regenerate — that is the stampede prevention' ); } + + public function test_empty_context_passes_groups_through_verbatim(): void { + $cache = new Cache(); + + $this->assertTrue( $cache->set( 'k', 'v', 'raw-group' ) ); + $this->assertSame( 'v', wp_cache_get( 'k', 'raw-group' ) ); + $this->assertSame( 'v', $cache->get( 'k', 'raw-group' ) ); + + $this->assertTrue( $cache->delete( 'k', 'raw-group' ) ); + $this->assertFalse( wp_cache_get( 'k', 'raw-group' ) ); + } + + public function test_flush_group_clears_only_the_namespaced_group(): void { + $cache = new Cache( 'ctx-flush' ); + $cache->set( 'a', 1, 'g' ); + $cache->set( 'b', 2, 'g' ); + $cache->set( 'c', 3, 'other' ); + + // Core's non-persistent cache supports group flushing (WordPress 6.1+). + $this->assertTrue( wp_cache_supports( 'flush_group' ), 'precondition: core cache supports flush_group' ); + $this->assertTrue( $cache->flush_group( 'g' ) ); + + $found = null; + $cache->get( 'a', 'g', false, $found ); + $this->assertFalse( $found ); + $cache->get( 'b', 'g', false, $found ); + $this->assertFalse( $found ); + $this->assertSame( 3, $cache->get( 'c', 'other' ), 'flushing one group must not touch another' ); + } + + public function test_remember_swr_returns_a_fresh_hit_without_invoking_the_callback(): void { + $cache = new Cache( 'ctx-swr-hit' ); + $cache->set( 'k', 'fresh', 'g', 100 ); + + $calls = 0; + $returned = $cache->remember_swr( + 'k', + static function () use ( &$calls ): string { + ++$calls; + return 'regenerated'; + }, + 'g', + 100 + ); + + $this->assertSame( 'fresh', $returned ); + $this->assertSame( 0, $calls ); + } + + public function test_remember_swr_cold_start_falls_back_to_the_callback_when_the_lock_never_frees(): void { + $cache = new Cache( 'ctx-swr-wait' ); + // Another process holds the lock on a cold start (no fresh, no stale) and + // never finishes: after the bounded wait the caller regenerates itself. + $this->assertTrue( wp_cache_add( 'k_lock', 1, 'ctx-swr-wait:g', 30 ), 'precondition: hold the lock' ); + + $calls = 0; + $returned = $cache->remember_swr( + 'k', + static function () use ( &$calls ): string { + ++$calls; + return 'computed'; + }, + 'g', + 100 + ); + + $this->assertSame( 'computed', $returned ); + $this->assertSame( 1, $calls ); + $this->assertSame( 'computed', wp_cache_get( 'k', 'ctx-swr-wait:g' ), 'the last-resort value is still cached' ); + $this->assertSame( 1, wp_cache_get( 'k_lock', 'ctx-swr-wait:g' ), 'the other process\'s lock must not be released by the fallback' ); + } + + public function test_remember_swr_cold_start_waits_for_the_lock_holder_to_publish(): void { + // Simulate the lock holder finishing during our wait: the second read of + // the fresh key (the first retry) finds the value it published. + $cache = new class( 'ctx-swr-publish' ) extends Cache { + /** + * Reads of the fresh key so far. + * + * @var int + */ + public int $fresh_reads = 0; + + public function get( string $key, string $group = '', bool $force = false, ?bool &$found = null ): mixed { + if ( 'k' === $key && 2 === ++$this->fresh_reads ) { + parent::set( 'k', 'published', $group, 100 ); + } + + return parent::get( $key, $group, $force, $found ); + } + }; + $this->assertTrue( wp_cache_add( 'k_lock', 1, 'ctx-swr-publish:g', 30 ), 'precondition: hold the lock' ); + + $calls = 0; + $returned = $cache->remember_swr( + 'k', + static function () use ( &$calls ): string { + ++$calls; + return 'computed'; + }, + 'g', + 100 + ); + + $this->assertSame( 'published', $returned ); + $this->assertSame( 0, $calls, 'a caller that sees the published value must not regenerate' ); + } } diff --git a/tests/Utils/TimerTest.php b/tests/Utils/TimerTest.php index a3372bd..5ae6e68 100644 --- a/tests/Utils/TimerTest.php +++ b/tests/Utils/TimerTest.php @@ -126,6 +126,16 @@ public function test_lap_after_stop_warns(): void { $this->timer->lap( 'stopped_lap', 'too_late' ); } + public function test_lap_empty_label_warns_and_records_nothing(): void { + $this->setExpectedIncorrectUsage( Timer::class . '::lap' ); + + $this->timer->start( 'lap_target' ); + $this->timer->lap( '', 'split' ); + + $data = $this->timer->get( 'lap_target' ); + $this->assertEmpty( $data['laps'], 'an empty label must not record a lap on any timer' ); + } + public function test_lap_empty_name_warns_and_records_nothing(): void { $this->setExpectedIncorrectUsage( Timer::class . '::lap' ); From 40335db84c55f5cd65c3a6817ef2563a861224ba Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:37:22 +0530 Subject: [PATCH 05/25] chore(phpstan): raise static analysis to level 6 Level 6 reported a single error: the shortcode callback's $atts had no iterable value type. Document it as array|string (WordPress passes an empty string when the tag has no attributes) and raise the configured level; the codebase is clean at 6. --- inc/Contracts/Abstracts/AbstractShortcode.php | 4 ++-- phpstan.neon.dist | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/inc/Contracts/Abstracts/AbstractShortcode.php b/inc/Contracts/Abstracts/AbstractShortcode.php index 827252e..8bb7433 100644 --- a/inc/Contracts/Abstracts/AbstractShortcode.php +++ b/inc/Contracts/Abstracts/AbstractShortcode.php @@ -42,8 +42,8 @@ public function register_shortcode(): void { /** * Shortcode callback wrapper. Parses attributes and delegates to render(). * - * @param array|string $atts Shortcode attributes. - * @param string|null $content Enclosed content (if any). + * @param array|string $atts Shortcode attributes. WordPress passes an empty string when the tag has none. + * @param string|null $content Enclosed content (if any). * * @return string Rendered shortcode output. */ diff --git a/phpstan.neon.dist b/phpstan.neon.dist index ac2d988..a9c6d81 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -5,7 +5,7 @@ includes: - vendor/szepeviktor/phpstan-wordpress/extension.neon parameters: - level: 5 + level: 6 phpVersion: 80200 paths: From 8b015395881840614549ca190591a82ceb902a5f Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:37:35 +0530 Subject: [PATCH 06/25] ci: run on Node 24, pin the docs action and stop persisting credentials - Node 20 reached end of life in April 2026; the wp-env jobs now use the current LTS (the suite was verified on Node 24). - rtCamp/action-docusaurus-build was referenced by a mutable branch whose code only exists on an unmerged PR; pin it to commit b671d68 until that action is released and tagged. - No job pushes, so checkouts no longer persist the token (zizmor: artipacked), and $GITHUB_OUTPUT is quoted (shellcheck SC2086). - Drop the stale "temporary deployment test branch" comment. --- .github/workflows/documentation.yml | 6 ++++-- .github/workflows/test-measure.yml | 16 ++++++++++++---- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index a78cf18..01b02f1 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -2,7 +2,6 @@ name: Documentation on: push: - # Temporary deployment test branch; remove after verification. branches: [main] paths: - 'docs/**' @@ -44,7 +43,10 @@ jobs: - name: Build documentation id: docs - uses: rtCamp/action-docusaurus-build@codex/documentation-workflow + # Pinned to a commit: the action's code only lives on the unmerged + # codex/documentation-workflow branch (rtCamp/action-docusaurus-build#1). + # Move to a release tag once that PR merges and is tagged. + uses: rtCamp/action-docusaurus-build@b671d6800c68a74da8913edb9321422fe8afaedc # codex/documentation-workflow, 2026-09-17 with: site-title: ${{ vars.DOCS_SITE_TITLE }} site-config: ${{ vars.DOCS_SITE_CONFIG }} diff --git a/.github/workflows/test-measure.yml b/.github/workflows/test-measure.yml index d128b2e..5119a64 100644 --- a/.github/workflows/test-measure.yml +++ b/.github/workflows/test-measure.yml @@ -24,6 +24,8 @@ jobs: steps: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + with: + persist-credentials: false - name: Setup PHP uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2 @@ -34,7 +36,7 @@ jobs: - name: Get Composer Cache Directory id: composer-cache - run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT + run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT" - name: Configure Composer cache uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 @@ -59,6 +61,8 @@ jobs: steps: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + with: + persist-credentials: false - name: Setup PHP uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2 @@ -68,7 +72,7 @@ jobs: - name: Get Composer Cache Directory id: composer-cache - run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT + run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT" - name: Configure Composer cache uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 @@ -102,11 +106,13 @@ jobs: steps: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + with: + persist-credentials: false - name: Setup Node uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: '20' + node-version: '24' - name: Install Node dependencies run: npm ci @@ -128,11 +134,13 @@ jobs: steps: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + with: + persist-credentials: false - name: Setup Node uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: '20' + node-version: '24' - name: Install Node dependencies run: npm ci From 421494ef62d3cf49998646f4eb97384801c53112 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:37:36 +0530 Subject: [PATCH 07/25] ci: rebuild Dependabot auto-merge on the pull_request pattern The workflow_run job could never merge anything: every run failed with "Auto merge is not allowed for this repository", it did not check the triggering run's conclusion, and zizmor flags both the workflow_run trigger and the spoofable github.actor check as high severity. Follow GitHub's documented pattern instead: run on the Dependabot pull request itself, gate on the pull request author, read the update type from dependabot/fetch-metadata (pinned to the v3.1.0 commit) and enable auto-merge for minor and patch updates without checking out any code. Repository settings still need "Allow auto-merge" enabled, and the Test and Measure jobs should be required checks so a red run blocks it. --- .github/workflows/auto-merge.yml | 47 +++++++++++++++++++------------- 1 file changed, 28 insertions(+), 19 deletions(-) diff --git a/.github/workflows/auto-merge.yml b/.github/workflows/auto-merge.yml index 6bff7a3..1c1e6f3 100644 --- a/.github/workflows/auto-merge.yml +++ b/.github/workflows/auto-merge.yml @@ -1,33 +1,42 @@ -name: Pull Requests auto-merge +name: Dependabot auto-merge -on: - workflow_run: - workflows: ["Test and Measure"] - types: - - completed +# GitHub's documented pattern: run on the Dependabot pull request itself (no +# workflow_run, no checkout), read the update type from Dependabot's metadata and +# enable auto-merge for minor and patch updates. Auto-merge then waits for every +# ruleset requirement, so the "Test and Measure" jobs must be required status +# checks for a red run to block the merge. +# +# Repository prerequisites (Settings): "Allow auto-merge" enabled, and the main +# ruleset's required reviews satisfiable for Dependabot pull requests. + +on: pull_request permissions: - pull-requests: write - contents: write + contents: read concurrency: - group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch || github.run_id }} + group: ${{ github.workflow }}-${{ github.event.pull_request.number }} cancel-in-progress: true jobs: dependabot: name: Dependabot PR auto-merge runs-on: ubuntu-latest - if: ${{ github.actor == 'dependabot[bot]' }} + # The pull request author cannot be spoofed, unlike github.actor. + if: github.event.pull_request.user.login == 'dependabot[bot]' + permissions: + contents: write + pull-requests: write steps: - - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + - name: Fetch Dependabot metadata + id: metadata + uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0 - - name: Approve and merge the PR - if: | - contains( github.event.workflow_run.head_commit.message, 'version-update:semver-minor' ) || - contains( github.event.workflow_run.head_commit.message, 'version-update:semver-patch' ) - run: gh pr merge "$PR_NUMBER" --auto --merge --delete-branch + - name: Enable auto-merge for minor and patch updates + if: >- + steps.metadata.outputs.update-type == 'version-update:semver-minor' || + steps.metadata.outputs.update-type == 'version-update:semver-patch' + run: gh pr merge --auto --merge "$PR_URL" env: - PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} From 5b166f1adc4995673c9248533ffb2e1d3cbd1fe5 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:37:36 +0530 Subject: [PATCH 08/25] build: trim the dist archive and complete the Packagist metadata - export-ignore docs/, AGENTS.md, CONTRIBUTING.md and composer.lock, so a Composer dist install ships only inc/, ai/, bin/, composer.json, the README and the license. ai/ and bin/sync-ai-instructions.js stay in on purpose: consumers run them from vendor/ via npm run sync-ai. - composer.json gains a descriptive summary, keywords, the rtCamp author entry used by rtcamp/nginx-helper, and a support.docs link to the documentation site's post-rename path. --- .gitattributes | 7 +++++++ composer.json | 20 ++++++++++++++++++-- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/.gitattributes b/.gitattributes index eb86cfd..0c2cc1e 100644 --- a/.gitattributes +++ b/.gitattributes @@ -25,3 +25,10 @@ /phpcs.xml.dist export-ignore /phpstan.neon.dist export-ignore /phpunit.xml.dist export-ignore +/composer.lock export-ignore +/docs export-ignore +/AGENTS.md export-ignore +/CONTRIBUTING.md export-ignore + +# Ship on purpose: README.md and LICENSE.md, inc/, plus ai/ and +# bin/sync-ai-instructions.js, which consumers run from vendor/ via `npm run sync-ai`. diff --git a/composer.json b/composer.json index 1c02ee8..c363515 100644 --- a/composer.json +++ b/composer.json @@ -1,12 +1,28 @@ { "name": "rtcamp/wp-primitives", - "description": "Shared PHP utilities for rtCamp WordPress projects", + "description": "Contracts, loaders and utilities for building WordPress plugins and themes on a shared, tested base.", + "keywords": [ + "wordpress", + "wordpress-plugin", + "wordpress-theme", + "framework", + "library", + "rtcamp" + ], "type": "library", "license": "GPL-2.0-or-later", + "authors": [ + { + "name": "rtCamp", + "email": "support@rtcamp.com", + "homepage": "https://rtcamp.com" + } + ], "homepage": "https://github.com/rtCamp/wp-primitives", "support": { "issues": "https://github.com/rtCamp/wp-primitives/issues", - "source": "https://github.com/rtCamp/wp-primitives" + "source": "https://github.com/rtCamp/wp-primitives", + "docs": "https://opensource.rtcamp.com/wp-primitives/" }, "require": { "php": ">=8.2" From 835e05a1962479c8c69396ccfe1eb54f920f608f Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:37:36 +0530 Subject: [PATCH 09/25] docs: make the install instructions Packagist-first The README, getting-started guide and troubleshooting table still said the package is not on public Packagist. With rtcamp/wp-primitives published there, composer require is the whole install; the VCS repositories entry stays documented as the fallback for installing from GitHub, and the troubleshooting row now points renamed-package errors at the 1.0.x to 2.0.0 upgrade guide. Land together with the Packagist submission. --- README.md | 18 ++++++++++-------- docs/getting-started.md | 18 ++++++++---------- docs/troubleshooting.md | 2 +- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 371c822..12cee97 100644 --- a/README.md +++ b/README.md @@ -28,8 +28,14 @@ Requirements: ## Install -Not on public Packagist — add the repository to the consuming project's -`composer.json`, then require it with a caret constraint: +```bash +composer require rtcamp/wp-primitives:^2.0 +``` + +The package is published on [Packagist](https://packagist.org/packages/rtcamp/wp-primitives), +so no extra configuration is needed. To install straight from GitHub instead (a +branch, a fork, or a project that does not use Packagist), add a VCS repository +before requiring it: ```json { @@ -39,12 +45,8 @@ Not on public Packagist — add the repository to the consuming project's } ``` -```bash -composer require rtcamp/wp-primitives:^2.0 -``` - -(The `repositories` entry is unnecessary when the project already resolves this -package through an rtCamp-hosted Composer registry.) +Upgrading from `rtcamp/wp-framework` 1.x? The package was renamed in 2.0.0; follow +[docs/upgrading.md](docs/upgrading.md#10x--200-package-rename). PSR-4 autoloading: `rtCamp\WPPrimitives\` → `inc/`. diff --git a/docs/getting-started.md b/docs/getting-started.md index f1b0987..357a32b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -21,8 +21,14 @@ APIs. `Encryptor` additionally requires the OpenSSL PHP extension when used. ## Install -The package is not published on public Packagist. Add the repository to the -consuming project's `composer.json` first, then require it: +```bash +composer require rtcamp/wp-primitives:^2.0 +``` + +The package is published on [Packagist](https://packagist.org/packages/rtcamp/wp-primitives), +so `composer require` is all a consumer needs. To install from GitHub instead (a +development branch, a fork, or a project that does not use Packagist), add the +repository to the consuming project's `composer.json` first: ```json { @@ -35,14 +41,6 @@ consuming project's `composer.json` first, then require it: } ``` -```bash -composer require rtcamp/wp-primitives:^2.0 -``` - -If the project is already wired to an rtCamp-hosted Composer registry that -serves this package, the `repositories` entry is unnecessary and -`composer require rtcamp/wp-primitives:^2.0` is enough on its own. - Pin with a caret constraint. `inc/Contracts/` is the public API and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html), so `^2.0` accepts additive releases and refuses the next major. Read diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f39adc5..a33c150 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -70,7 +70,7 @@ one you get is deliberate: | Symptom | Cause | Fix | |---|---|---| | `Class "rtCamp\WPPrimitives\…" not found` | The consumer's `vendor/autoload.php` was never required, or the package resolved from a stale `vendor/`. | Require the autoloader in the plugin/theme entry point; `composer update rtcamp/wp-primitives`. | -| Composer can't find the package | It is not on public Packagist. | Add the VCS `repositories` entry — see [getting-started.md](getting-started.md#install). | +| Composer can't find the package | The package was renamed from `rtcamp/wp-framework` to `rtcamp/wp-primitives` in 2.0.0, or the project installs from GitHub without a `repositories` entry. | Require `rtcamp/wp-primitives:^2.0` (see [upgrading.md](upgrading.md#10x--200-package-rename)); for GitHub installs add the VCS entry from [getting-started.md](getting-started.md#install). | | A missing abstract method only surfaces at runtime | The subclass doesn't implement everything the abstract declares. | Run PHPStan in the consuming package; it catches contract breaks before a request does. | Still stuck? The classes are small and heavily commented — `Loader::load()` in From 8187acbf6f7c7195a268152e5daba8e35b5e8d59 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:37:36 +0530 Subject: [PATCH 10/25] docs(changelog): complete the unreleased 2.0.0 entry Record what main already ships but the changelog missed (the Abilities API abstracts from #76), the two fixes on this branch (Encryptor under Security, Transients under Fixed), the dist, CI and analysis changes, and replace the stale "not on public Packagist" note. --- CHANGELOG.md | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 354ad36..9f58a8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- `AbstractAbility` and `AbstractAbilityRegistrar`, base classes for the WordPress + 6.9 Abilities API (#76). Abilities default to a fail-closed `manage_options` + permission check and opt in to REST or MCP exposure through `meta()`; a + registrar registers its category idempotently, so several registrars can share + one. Both are inert on WordPress older than 6.9. +- A protected `Encryptor::is_openssl_available()` seam, so the fail-closed + "OpenSSL missing" path of `encrypt()` and `decrypt()` is covered by tests. + +### Security + +- `Encryptor::decrypt()` now rejects any payload shorter than the IV plus a + full-length authentication tag. OpenSSL verifies a truncated GCM tag at its + truncated length, so a forged 13-byte payload (IV plus one tag byte, empty + ciphertext) decrypted to `''` for 1 in 256 tag values instead of failing. + +### Fixed + +- `Transients` now hashes a namespaced key longer than WordPress' 172-character + transient name limit to `h:`. Such names were truncated by the options + table, so the value was never found again on the next request (or, just past the + limit, its expiry was silently dropped). Keys within the limit are unchanged. + ### Changed - **BREAKING: renamed the package from `rtcamp/wp-framework` to `rtcamp/wp-primitives`.** @@ -28,6 +52,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 this package, so nothing in-repo breaks, but any consumer shipping translations for the old domain must retarget them. +### Build + +- Dist archives (Packagist and GitHub zipballs) no longer include `docs/`, + `AGENTS.md`, `CONTRIBUTING.md` or `composer.lock`. `ai/` and + `bin/sync-ai-instructions.js` still ship, because consumers run them from + `vendor/` via `npm run sync-ai`. +- CI runs on Node 24 (Node 20 reached end of life in April 2026), PHPStan runs at + level 6, the documentation action is pinned to a commit, and checkouts no longer + persist credentials. Dependabot auto-merge uses GitHub's documented + `pull_request` pattern instead of a `workflow_run` trigger with a spoofable + `github.actor` check. + ### Documentation - Added implementor getting-started and maintainer workflow guides; corrected @@ -36,8 +72,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added `docs/upgrading.md` (versioning promise and the 1.0.0 → 1.0.1 `Singleton` migration) and `docs/troubleshooting.md` (symptom → cause for the framework's exceptions, `_doing_it_wrong()` notices, and silent no-ops). -- Documented the real install path: the package is not on public Packagist, so - the consumer needs a VCS `repositories` entry and a `^2.0` constraint. +- Install docs are Packagist-first (`composer require rtcamp/wp-primitives:^2.0`), + with a VCS `repositories` fallback for installing straight from GitHub. - Added a worked WP-CLI example to `docs/contracts.md`, the only contract that had none, and a quick-look snippet to the README. - Corrected the `Loader::load()` snippet in `docs/architecture.md` to match the From d4265132204704786c681fc5299aa54a7a1504c5 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:41:02 +0530 Subject: [PATCH 11/25] fix(sync-ai): prune only generated legacy files, and log the real path refreshPackage() deleted a package's framework-php.instructions.md whenever the file existed, so a hand-written file that happened to share the pre-2.0 name was lost on upgrade. It now requires the legacy GENERATED marker, the same test the root prune step already applies. The prune log line also printed the wp-content root followed by .github/instructions/..., naming a file that was not the one deleted; it now prints the deleted file's path relative to the root. Smoke-tested on a two-package wp-content tree: the generated legacy copy is pruned, a hand-written one is kept, and --check reports in sync. --- bin/sync-ai-instructions.js | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/bin/sync-ai-instructions.js b/bin/sync-ai-instructions.js index 20e0c32..d69b09c 100644 --- a/bin/sync-ai-instructions.js +++ b/bin/sync-ai-instructions.js @@ -195,11 +195,13 @@ const refreshPackage = ( base, relRoot ) => { writeIfChanged( dest, withMarker( fs.readFileSync( src, 'utf8' ) ), relRoot, 'refresh' ); // Migration from <2.0: drop the superseded filename so it is not projected to the root - // and so Copilot does not read two copies of the same rules. + // and so Copilot does not read two copies of the same rules. Only a copy the old + // sync generated (it carries LEGACY_MARKER) is removed; a hand-written file that + // happens to share the name is left alone, matching the root prune below. const legacy = path.join( base, '.github', 'instructions', LEGACY_INSTRUCTION_FILE ); - if ( fs.existsSync( legacy ) ) { + if ( fs.existsSync( legacy ) && fs.readFileSync( legacy, 'utf8' ).includes( LEGACY_MARKER ) ) { drift = true; - log.push( color.red( ` prune ${ relRoot }/.github/instructions/${ LEGACY_INSTRUCTION_FILE }` ) ); + log.push( color.red( ` prune ${ path.relative( relRoot, legacy ) }` ) ); if ( ! isCheck ) { fs.unlinkSync( legacy ); } From 2d1c3c6e27836d99b326f54620d821c257ae7af4 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:43:52 +0530 Subject: [PATCH 12/25] build: alias dev-main as 2.x-dev #98 aliased dev-main to 2.0.x-dev. That alias stops matching as soon as main carries 2.1 work: a consumer asking for ^2.1@dev could not resolve the branch. 2.x-dev covers every 2.y line without a bump after each minor release, and still satisfies ^2.0@dev before the v2.0.0 tag exists. Only the lock's content-hash changes. --- composer.json | 2 +- composer.lock | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/composer.json b/composer.json index c363515..ad30d06 100644 --- a/composer.json +++ b/composer.json @@ -76,7 +76,7 @@ }, "extra": { "branch-alias": { - "dev-main": "2.0.x-dev" + "dev-main": "2.x-dev" } }, "minimum-stability": "stable", diff --git a/composer.lock b/composer.lock index ad7ebbe..02107e6 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "90832f0a54275b28f76520bf5a51f693", + "content-hash": "d2ae57078b8d948435c060fa2ae5963c", "packages": [], "packages-dev": [ { From 73219adea7e5b23ec2acc7f1ea871d21fa6fae79 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:43:53 +0530 Subject: [PATCH 13/25] build(deps-dev): patch the PHPCS toolchain security advisories composer audit reported three advisories in the dev toolchain that CI runs on every pull request, including ones from forks: - squizlabs/php_codesniffer < 3.13.6 (CVE-2026-67434, OS command injection) - phpcsstandards/phpcsutils < 1.2.3 (CVE-2026-65954, arbitrary code execution) - wp-coding-standards/wpcs < 3.4.1 (CVE-2026-45293, arbitrary code execution) Update them (with automattic/vipwpcs 3.1.0 and phpcsextra 1.5.1, which the new WPCS floor pulls in). composer audit is clean and PHPCS still reports no violations. Supersedes Dependabot #84, #88 and #99 and the PHPCS part of #93. --- composer.lock | 74 +++++++++++++++++++++++++-------------------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/composer.lock b/composer.lock index 02107e6..8450153 100644 --- a/composer.lock +++ b/composer.lock @@ -9,32 +9,32 @@ "packages-dev": [ { "name": "automattic/vipwpcs", - "version": "3.0.1", + "version": "3.1.0", "source": { "type": "git", "url": "https://github.com/Automattic/VIP-Coding-Standards.git", - "reference": "2b1d206d81b74ed999023cffd924f862ff2753c8" + "reference": "9c47cd036754e0e5f354a9914568f052043c3f30" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/Automattic/VIP-Coding-Standards/zipball/2b1d206d81b74ed999023cffd924f862ff2753c8", - "reference": "2b1d206d81b74ed999023cffd924f862ff2753c8", + "url": "https://api.github.com/repos/Automattic/VIP-Coding-Standards/zipball/9c47cd036754e0e5f354a9914568f052043c3f30", + "reference": "9c47cd036754e0e5f354a9914568f052043c3f30", "shasum": "" }, "require": { - "php": ">=5.4", - "phpcsstandards/phpcsextra": "^1.2.1", - "phpcsstandards/phpcsutils": "^1.0.11", - "sirbrillig/phpcs-variable-analysis": "^2.11.18", - "squizlabs/php_codesniffer": "^3.9.2", - "wp-coding-standards/wpcs": "^3.1.0" + "php": ">=7.4", + "phpcsstandards/phpcsextra": "^1.5.1", + "phpcsstandards/phpcsutils": "^1.2.3", + "sirbrillig/phpcs-variable-analysis": "^2.13.0", + "squizlabs/php_codesniffer": "^3.13.5", + "wp-coding-standards/wpcs": "^3.4.1" }, "require-dev": { "php-parallel-lint/php-console-highlighter": "^1.0.0", - "php-parallel-lint/php-parallel-lint": "^1.3.2", + "php-parallel-lint/php-parallel-lint": "^1.4.0", "phpcompatibility/php-compatibility": "^9", - "phpcsstandards/phpcsdevtools": "^1.0", - "phpunit/phpunit": "^4 || ^5 || ^6 || ^7 || ^8 || ^9" + "phpcsstandards/phpcsdevtools": "^1.2.3", + "phpunit/phpunit": "^9" }, "type": "phpcodesniffer-standard", "notification-url": "https://packagist.org/downloads/", @@ -59,7 +59,7 @@ "source": "https://github.com/Automattic/VIP-Coding-Standards", "wiki": "https://github.com/Automattic/VIP-Coding-Standards/wiki" }, - "time": "2024-05-10T20:31:09+00:00" + "time": "2026-07-27T14:33:48+00:00" }, { "name": "dealerdirect/phpcodesniffer-composer-installer", @@ -730,21 +730,21 @@ }, { "name": "phpcsstandards/phpcsextra", - "version": "1.5.0", + "version": "1.5.1", "source": { "type": "git", "url": "https://github.com/PHPCSStandards/PHPCSExtra.git", - "reference": "b598aa890815b8df16363271b659d73280129101" + "reference": "39467533fdb742446d68c1d10ac33d625ee0311c" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/PHPCSStandards/PHPCSExtra/zipball/b598aa890815b8df16363271b659d73280129101", - "reference": "b598aa890815b8df16363271b659d73280129101", + "url": "https://api.github.com/repos/PHPCSStandards/PHPCSExtra/zipball/39467533fdb742446d68c1d10ac33d625ee0311c", + "reference": "39467533fdb742446d68c1d10ac33d625ee0311c", "shasum": "" }, "require": { "php": ">=5.4", - "phpcsstandards/phpcsutils": "^1.2.0", + "phpcsstandards/phpcsutils": "^1.2.3", "squizlabs/php_codesniffer": "^3.13.5 || ^4.0.1" }, "require-dev": { @@ -808,20 +808,20 @@ "type": "thanks_dev" } ], - "time": "2025-11-12T23:06:57+00:00" + "time": "2026-07-27T11:13:17+00:00" }, { "name": "phpcsstandards/phpcsutils", - "version": "1.2.2", + "version": "1.2.3", "source": { "type": "git", "url": "https://github.com/PHPCSStandards/PHPCSUtils.git", - "reference": "c216317e96c8b3f5932808f9b0f1f7a14e3bbf55" + "reference": "5f35d9408c54d7b529501f3c688b6eae562aea1f" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/PHPCSStandards/PHPCSUtils/zipball/c216317e96c8b3f5932808f9b0f1f7a14e3bbf55", - "reference": "c216317e96c8b3f5932808f9b0f1f7a14e3bbf55", + "url": "https://api.github.com/repos/PHPCSStandards/PHPCSUtils/zipball/5f35d9408c54d7b529501f3c688b6eae562aea1f", + "reference": "5f35d9408c54d7b529501f3c688b6eae562aea1f", "shasum": "" }, "require": { @@ -901,7 +901,7 @@ "type": "thanks_dev" } ], - "time": "2025-12-08T14:27:58+00:00" + "time": "2026-07-27T10:28:41+00:00" }, { "name": "phpstan/phpstan", @@ -2466,16 +2466,16 @@ }, { "name": "squizlabs/php_codesniffer", - "version": "3.13.5", + "version": "3.13.6", "source": { "type": "git", "url": "https://github.com/PHPCSStandards/PHP_CodeSniffer.git", - "reference": "0ca86845ce43291e8f5692c7356fccf3bcf02bf4" + "reference": "4c378e1a528ea066890fc2397cbdd2f94eb2fc91" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/PHPCSStandards/PHP_CodeSniffer/zipball/0ca86845ce43291e8f5692c7356fccf3bcf02bf4", - "reference": "0ca86845ce43291e8f5692c7356fccf3bcf02bf4", + "url": "https://api.github.com/repos/PHPCSStandards/PHP_CodeSniffer/zipball/4c378e1a528ea066890fc2397cbdd2f94eb2fc91", + "reference": "4c378e1a528ea066890fc2397cbdd2f94eb2fc91", "shasum": "" }, "require": { @@ -2541,7 +2541,7 @@ "type": "thanks_dev" } ], - "time": "2025-11-04T16:30:35+00:00" + "time": "2026-08-06T00:17:32+00:00" }, { "name": "szepeviktor/phpstan-wordpress", @@ -2658,16 +2658,16 @@ }, { "name": "wp-coding-standards/wpcs", - "version": "3.4.0", + "version": "3.4.1", "source": { "type": "git", "url": "https://github.com/WordPress/WordPress-Coding-Standards.git", - "reference": "469c18ceab4d642b15bad4c65ebf3b307bfd55ab" + "reference": "ec2ff942335f33683a5957a85d138753876a05cf" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/WordPress/WordPress-Coding-Standards/zipball/469c18ceab4d642b15bad4c65ebf3b307bfd55ab", - "reference": "469c18ceab4d642b15bad4c65ebf3b307bfd55ab", + "url": "https://api.github.com/repos/WordPress/WordPress-Coding-Standards/zipball/ec2ff942335f33683a5957a85d138753876a05cf", + "reference": "ec2ff942335f33683a5957a85d138753876a05cf", "shasum": "" }, "require": { @@ -2676,8 +2676,8 @@ "ext-tokenizer": "*", "ext-xmlreader": "*", "php": ">=7.2", - "phpcsstandards/phpcsextra": "^1.5.0", - "phpcsstandards/phpcsutils": "^1.2.2", + "phpcsstandards/phpcsextra": "^1.5.1", + "phpcsstandards/phpcsutils": "^1.2.3", "squizlabs/php_codesniffer": "^3.13.5" }, "require-dev": { @@ -2720,7 +2720,7 @@ "type": "custom" } ], - "time": "2026-07-16T13:05:29+00:00" + "time": "2026-07-27T11:53:23+00:00" }, { "name": "wp-phpunit/wp-phpunit", From 67d93c044a373fcd9e2f08f0cf844b721d1666d5 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:44:02 +0530 Subject: [PATCH 14/25] docs(maintainers): document the release procedure The maintainer guide said the repository had no authoritative release procedure. With Packagist reading versions from tags, write one down: changelog PR, annotated tag on main, GitHub release from the changelog section, and a Packagist check, plus the rule never to move a published tag and to leave the v1.0.x tags alone for ^1.0 consumers. --- docs/maintainers.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/docs/maintainers.md b/docs/maintainers.md index 1c92029..447c46a 100644 --- a/docs/maintainers.md +++ b/docs/maintainers.md @@ -145,6 +145,35 @@ Use the repository pull-request template. A change is ready for review when: - `CHANGELOG.md` contains an `[Unreleased]` entry; - commits follow Conventional Commits. -Branching, release targeting, version selection, and package publication are not -defined here because the repository does not currently establish one complete, -authoritative release procedure. +## Releasing + +The package is published on Packagist as `rtcamp/wp-primitives`, which reads +versions straight from git tags through the repository's Packagist webhook. +A release is therefore a tag on `main`: + +1. Open a pull request that moves the `[Unreleased]` entries under a new + `## [X.Y.Z] - YYYY-MM-DD` heading and updates the compare links at the bottom + of `CHANGELOG.md`. Pick the version from the changes: anything breaking in + `inc/Contracts/` or in documented behaviour is a major, new API is a minor, + fixes only is a patch. +2. Merge it, then tag the merge commit with an annotated tag and push the tag: + + ```bash + git switch main && git pull + git tag -a vX.Y.Z -m "vX.Y.Z" + git push origin vX.Y.Z + ``` + +3. Create the GitHub release from that tag and paste the version's changelog + section as the notes (`gh release create vX.Y.Z --title vX.Y.Z --notes-file + notes.md`). `.github/release.yml` keeps Dependabot pull requests out of + generated notes if you use `--generate-notes` instead. +4. Confirm Packagist picked the tag up: `composer show rtcamp/wp-primitives --all` + lists the new version within a minute or two. If it does not, check the + webhook delivery under the repository's Settings > Webhooks. + +Never move, delete or re-push a published tag: consumers and Packagist have +already resolved it. Fix forward with a patch release instead. The `v1.0.x` +tags are the last releases under the old `rtcamp/wp-framework` name and stay +untouched for consumers still on `^1.0`. + From 261244f1087846b6d537fee7f72082b19a7a1b2f Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:48:19 +0530 Subject: [PATCH 15/25] docs: add a security policy for the public package There was no SECURITY.md here or in the org's .github repository, so a reporter landing on the public repo had no private channel to use. Private vulnerability reporting is already enabled on the repository; point reporters at it, list which versions get fixes (2.x yes, the pre-rename 1.0.x line no), and say what a useful report contains. Keep the file out of the dist archive like the other repository docs. --- .gitattributes | 1 + SECURITY.md | 25 +++++++++++++++++++++++++ 2 files changed, 26 insertions(+) create mode 100644 SECURITY.md diff --git a/.gitattributes b/.gitattributes index 0c2cc1e..d50f1e3 100644 --- a/.gitattributes +++ b/.gitattributes @@ -29,6 +29,7 @@ /docs export-ignore /AGENTS.md export-ignore /CONTRIBUTING.md export-ignore +/SECURITY.md export-ignore # Ship on purpose: README.md and LICENSE.md, inc/, plus ai/ and # bin/sync-ai-instructions.js, which consumers run from vendor/ via `npm run sync-ai`. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..fa49b79 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,25 @@ +# Security policy + +## Supported versions + +| Version | Package | Supported | +|---|---|---| +| 2.x | `rtcamp/wp-primitives` | Yes | +| 1.0.x | `rtcamp/wp-framework` (the pre-rename name) | No further releases; upgrade to 2.x | + +## Reporting a vulnerability + +Please do not report security issues in public issues, pull requests or +discussions. + +Report them privately through GitHub instead: open the repository's +**Security** tab and choose **Report a vulnerability**, or go straight to +. The report +stays visible only to you and the maintainers, and the fix, the release and +the advisory are coordinated in that same thread. + +Include what you can of: + +- the affected class or method and the package version; +- the impact, and the conditions an attacker needs; +- steps or a minimal proof of concept that reproduce it. From cb370b95f6ca6b4c5b2ae7b39995e1129f227c67 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:48:27 +0530 Subject: [PATCH 16/25] build(deps-dev): bump @wordpress/env to 11.16.0 npm audit reported 9 advisories (5 high) in the wp-env test harness, including extract-zip under @wordpress/env itself. 11.16.0, the latest release on the same major, clears 6 of them; the remaining 3 are moderate (qs via express via @wp-playground/cli) and have no fix in the current dependency range yet. Verified on the dev VM: the full suite passes under 11.16.0 with coverage on PHP 8.3 / WP 7.0 and on PHP 8.2 / WP 6.5. --- package-lock.json | 247 +++++++++++----------------------------------- package.json | 2 +- 2 files changed, 56 insertions(+), 193 deletions(-) diff --git a/package-lock.json b/package-lock.json index 6e58386..7f6f259 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ "version": "0.0.1", "license": "GPL-2.0-or-later", "devDependencies": { - "@wordpress/env": "11.7.0" + "@wordpress/env": "11.16.0" } }, "node_modules/@inquirer/ansi": { @@ -686,6 +686,7 @@ "integrity": "sha512-/g2d4sW9nUDJOMz3mabVQvOGhVa4e/BN/Um7yca9Bb2XTzPPnfTWHWQg+IsEYO7M3Vx+EXvaM/I2pJWIMun1bg==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@octokit/auth-token": "^4.0.0", "@octokit/graphql": "^7.1.0", @@ -1466,32 +1467,31 @@ } }, "node_modules/@wordpress/env": { - "version": "11.7.0", - "resolved": "https://registry.npmjs.org/@wordpress/env/-/env-11.7.0.tgz", - "integrity": "sha512-BR4qAFZ5xrsQM00K5RJtnUqL86cd9opLMPthXi1uLVJqUXYNVf3YHtsptUgwL1wdZ/aON2jn5QWgKyiRL+0bVw==", + "version": "11.16.0", + "resolved": "https://registry.npmjs.org/@wordpress/env/-/env-11.16.0.tgz", + "integrity": "sha512-B09FByMnGleYaBa4LESZ9Bp/71/EOvovjqvwhXhZjZk25fLIsed4gslZXW9c3EodD2oxF5loHUCMzCAqotGRBg==", "dev": true, "license": "GPL-2.0-or-later", "dependencies": { "@inquirer/prompts": "^7.2.0", "@wp-playground/cli": "^3.0.48", - "chalk": "^4.0.0", + "adm-zip": "^0.6.1", + "chalk": "^4.1.1", "copy-dir": "^1.3.0", "cross-spawn": "^7.0.6", "docker-compose": "^0.24.3", - "extract-zip": "^1.6.7", "got": "^11.8.5", - "js-yaml": "^3.13.1", + "js-yaml": "^3.15.2", "ora": "^4.0.2", "rimraf": "^5.0.10", - "simple-git": "^3.5.0", + "simple-git": "^3.32.3", "yargs": "^17.3.0" }, "bin": { "wp-env": "bin/wp-env" }, "engines": { - "node": ">=18.12.0", - "npm": ">=8.19.2" + "node": ">=18.12.0" } }, "node_modules/@wp-playground/blueprints": { @@ -1646,6 +1646,16 @@ "node": ">= 0.6" } }, + "node_modules/adm-zip": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/adm-zip/-/adm-zip-0.6.1.tgz", + "integrity": "sha512-Xwrja8nx9e5o2N1my4DsKCeKpdrnACyr1wtbPxBDgGzKzKyE9kRtBFA8mWldI+RVlD7CBZNWY/wQ2+ydwOR6kQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=14.0" + } + }, "node_modules/aggregate-error": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/aggregate-error/-/aggregate-error-3.1.0.tgz", @@ -1792,9 +1802,9 @@ "license": "Apache-2.0" }, "node_modules/body-parser": { - "version": "1.20.6", - "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.6.tgz", - "integrity": "sha512-p5tAzS57i5MV9fZFDj9LeIiTZEufbSe2eDozP+ElheSUq1m74CRq1jI4mYNDdVs9vQztXFLuk/Gd6BWTdwRJ5g==", + "version": "1.20.8", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.8.tgz", + "integrity": "sha512-JNcyFQ64OiijEkPzUBTCe+hyPXUD/3LEldGQ6iF5LR1w00mx9o7xtDWHXBY2iItjdCFGoilOLNQbH943ut7pHA==", "dev": true, "license": "MIT", "dependencies": { @@ -1806,7 +1816,7 @@ "http-errors": "~2.0.1", "iconv-lite": "~0.4.24", "on-finished": "~2.4.1", - "qs": "~6.15.1", + "qs": "~6.16.0", "raw-body": "~2.5.3", "type-is": "~1.6.18", "unpipe": "~1.0.0" @@ -1829,6 +1839,23 @@ "node": ">=0.10.0" } }, + "node_modules/body-parser/node_modules/qs": { + "version": "6.16.0", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.16.0.tgz", + "integrity": "sha512-h6fhOIaRrID2CbEY2fqs+7t+UXZo+MLAnU5gRIq85uFtdiUPCdsApMlHhXogKVM4HM2DVbIjGNTTYH2OcmP1vA==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "es-define-property": "^1.0.1", + "side-channel": "^1.1.1" + }, + "engines": { + "node": ">=0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, "node_modules/bottleneck": { "version": "2.19.5", "resolved": "https://registry.npmjs.org/bottleneck/-/bottleneck-2.19.5.tgz", @@ -1837,9 +1864,9 @@ "license": "MIT" }, "node_modules/brace-expansion": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.1.tgz", - "integrity": "sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA==", + "version": "2.1.7", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.7.tgz", + "integrity": "sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g==", "dev": true, "license": "MIT", "dependencies": { @@ -1878,16 +1905,6 @@ "ieee754": "^1.2.1" } }, - "node_modules/buffer-crc32": { - "version": "0.2.13", - "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-0.2.13.tgz", - "integrity": "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": "*" - } - }, "node_modules/buffer-equal-constant-time": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz", @@ -1895,13 +1912,6 @@ "dev": true, "license": "BSD-3-Clause" }, - "node_modules/buffer-from": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz", - "integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==", - "dev": true, - "license": "MIT" - }, "node_modules/bytes": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", @@ -2166,22 +2176,6 @@ "dev": true, "license": "MIT" }, - "node_modules/concat-stream": { - "version": "1.6.2", - "resolved": "https://registry.npmjs.org/concat-stream/-/concat-stream-1.6.2.tgz", - "integrity": "sha512-27HBghJxjiZtIk3Ycvn/4kbJk/1uZuJFfuPEns6LaEvpvG1f0hTea8lilrouyo9mVc2GWdcEZ8OLoGmSADlrCw==", - "dev": true, - "engines": [ - "node >= 0.8" - ], - "license": "MIT", - "dependencies": { - "buffer-from": "^1.0.0", - "inherits": "^2.0.3", - "readable-stream": "^2.2.2", - "typedarray": "^0.0.6" - } - }, "node_modules/content-disposition": { "version": "0.5.4", "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-0.5.4.tgz", @@ -2229,13 +2223,6 @@ "dev": true, "license": "MIT" }, - "node_modules/core-util-is": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz", - "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==", - "dev": true, - "license": "MIT" - }, "node_modules/crc-32": { "version": "1.2.2", "resolved": "https://registry.npmjs.org/crc-32/-/crc-32-1.2.2.tgz", @@ -2609,22 +2596,6 @@ "url": "https://opencollective.com/express" } }, - "node_modules/extract-zip": { - "version": "1.7.0", - "resolved": "https://registry.npmjs.org/extract-zip/-/extract-zip-1.7.0.tgz", - "integrity": "sha512-xoh5G1W/PB0/27lXgMQyIhP5DSY/LhoCsOyZgb+6iMmRtCwVBo55uKaMoEYrDCKQhWvqEip5ZPKAc6eFNyf/MA==", - "dev": true, - "license": "BSD-2-Clause", - "dependencies": { - "concat-stream": "^1.6.2", - "debug": "^2.6.9", - "mkdirp": "^0.5.4", - "yauzl": "^2.10.0" - }, - "bin": { - "extract-zip": "cli.js" - } - }, "node_modules/fast-deep-equal": { "version": "3.1.3", "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", @@ -2633,9 +2604,9 @@ "license": "MIT" }, "node_modules/fast-uri": { - "version": "3.1.4", - "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.4.tgz", - "integrity": "sha512-8JnbkQ4juDyvYs4mgFGQqg4yCYtFDtUtmp2QIQq11ZZe5CFQ5wcqm1rqDgAh/QdMySuBnPzMUiJUNZG5N/AiQw==", + "version": "3.1.8", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.8.tgz", + "integrity": "sha512-GZMtZUTNRpOVIECoXwLNZS5xUGE+mVNbTB8h/7Rwh2TFWcBQiPzTgyZi05BF9UMZKkLJv8XBRJTlU7zg8+ZfMg==", "dev": true, "funding": [ { @@ -2689,16 +2660,6 @@ "fxparser": "src/cli/cli.js" } }, - "node_modules/fd-slicer": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/fd-slicer/-/fd-slicer-1.1.0.tgz", - "integrity": "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g==", - "dev": true, - "license": "MIT", - "dependencies": { - "pend": "~1.2.0" - } - }, "node_modules/finalhandler": { "version": "1.3.2", "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-1.3.2.tgz", @@ -3184,13 +3145,6 @@ "url": "https://github.com/sponsors/ljharb" } }, - "node_modules/isarray": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz", - "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==", - "dev": true, - "license": "MIT" - }, "node_modules/isexe": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", @@ -3268,9 +3222,9 @@ } }, "node_modules/js-yaml": { - "version": "3.15.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.0.tgz", - "integrity": "sha512-ttBQIIQPDeLjpPOohtUdXuXUVoA2uIB6fEH9HyJ7234s5mBJ5wTx20njxplLZQgLaOfpmPQA7X2t5AX6tIPbog==", + "version": "3.15.2", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.2.tgz", + "integrity": "sha512-6EuL879VkRA+1Cz578mKMiKvjPNEuk6+r1JaFzoSWejZmtf7xWbIyw1e3KkxlkzTIt9Taw6JBhEppG7utc1P+w==", "dev": true, "license": "MIT", "dependencies": { @@ -3671,19 +3625,6 @@ "node": ">=16 || 14 >=14.17" } }, - "node_modules/mkdirp": { - "version": "0.5.6", - "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.6.tgz", - "integrity": "sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw==", - "dev": true, - "license": "MIT", - "dependencies": { - "minimist": "^1.2.6" - }, - "bin": { - "mkdirp": "bin/cmd.js" - } - }, "node_modules/ms": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", @@ -3940,13 +3881,6 @@ "dev": true, "license": "MIT" }, - "node_modules/pend": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz", - "integrity": "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==", - "dev": true, - "license": "MIT" - }, "node_modules/pify": { "version": "4.0.1", "resolved": "https://registry.npmjs.org/pify/-/pify-4.0.1.tgz", @@ -3977,13 +3911,6 @@ "node": ">= 0.6.0" } }, - "node_modules/process-nextick-args": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz", - "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==", - "dev": true, - "license": "MIT" - }, "node_modules/proxy-addr": { "version": "2.0.7", "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz", @@ -4010,13 +3937,14 @@ } }, "node_modules/qs": { - "version": "6.15.2", - "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.2.tgz", - "integrity": "sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==", + "version": "6.15.3", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.3.tgz", + "integrity": "sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==", "dev": true, "license": "BSD-3-Clause", "dependencies": { - "side-channel": "^1.1.0" + "es-define-property": "^1.0.1", + "side-channel": "^1.1.1" }, "engines": { "node": ">=0.6" @@ -4077,29 +4005,6 @@ "node": ">=0.10.0" } }, - "node_modules/readable-stream": { - "version": "2.3.8", - "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz", - "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==", - "dev": true, - "license": "MIT", - "dependencies": { - "core-util-is": "~1.0.0", - "inherits": "~2.0.3", - "isarray": "~1.0.0", - "process-nextick-args": "~2.0.0", - "safe-buffer": "~5.1.1", - "string_decoder": "~1.1.1", - "util-deprecate": "~1.0.1" - } - }, - "node_modules/readable-stream/node_modules/safe-buffer": { - "version": "5.1.2", - "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", - "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", - "dev": true, - "license": "MIT" - }, "node_modules/require-directory": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", @@ -4541,23 +4446,6 @@ "node": ">= 0.8" } }, - "node_modules/string_decoder": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz", - "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==", - "dev": true, - "license": "MIT", - "dependencies": { - "safe-buffer": "~5.1.0" - } - }, - "node_modules/string_decoder/node_modules/safe-buffer": { - "version": "5.1.2", - "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", - "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", - "dev": true, - "license": "MIT" - }, "node_modules/string-width": { "version": "5.1.2", "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz", @@ -4765,13 +4653,6 @@ "node": ">= 0.4" } }, - "node_modules/typedarray": { - "version": "0.0.6", - "resolved": "https://registry.npmjs.org/typedarray/-/typedarray-0.0.6.tgz", - "integrity": "sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==", - "dev": true, - "license": "MIT" - }, "node_modules/undici-types": { "version": "7.24.6", "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz", @@ -4817,13 +4698,6 @@ "node": ">= 0.8" } }, - "node_modules/util-deprecate": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", - "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", - "dev": true, - "license": "MIT" - }, "node_modules/utils-merge": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/utils-merge/-/utils-merge-1.0.1.tgz", @@ -5123,17 +4997,6 @@ "node": ">=8" } }, - "node_modules/yauzl": { - "version": "2.10.0", - "resolved": "https://registry.npmjs.org/yauzl/-/yauzl-2.10.0.tgz", - "integrity": "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g==", - "dev": true, - "license": "MIT", - "dependencies": { - "buffer-crc32": "~0.2.3", - "fd-slicer": "~1.1.0" - } - }, "node_modules/yoctocolors-cjs": { "version": "2.1.3", "resolved": "https://registry.npmjs.org/yoctocolors-cjs/-/yoctocolors-cjs-2.1.3.tgz", diff --git a/package.json b/package.json index d633eef..8da3808 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,6 @@ "test:php:coverage": "wp-env run tests-cli --env-cwd=wp-content/wp-primitives-rt -- vendor/bin/phpunit -c phpunit.xml.dist --coverage-html coverage" }, "devDependencies": { - "@wordpress/env": "11.7.0" + "@wordpress/env": "11.16.0" } } From 3b376b8d10d49e48ed52a899031bdb66a2e27771 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:52:32 +0530 Subject: [PATCH 17/25] fix(sync-ai): discover site-repo packages through the vendored framework discoverPackages() only listed packages that already had a .github/instructions/ directory. A site repository that commits only the root projection (its packages have no per-package directory) therefore got "Nothing to do", and after the rename its root framework-php.instructions.md was never replaced or pruned. A package now also qualifies when it vendors rtcamp/wp-primitives; refreshPackage() creates its directory on the first run, and the root projection skips a package whose directory does not exist yet under --check, where the refresh step has already reported the drift. The "nothing to do" message now says to run composer install first. docs/upgrading.md gains the two steps a site repository hits while upgrading: repoint each consumer's own bin/sync-ai.js wrapper at vendor/rtcamp/wp-primitives, and run composer install in every package before npm run sync-ai. Smoke-tested on a site-style tree (two packages with vendored framework, no per-package directories, a legacy root projection and a hand-written root structure file): --check reports drift, sync replaces and prunes the legacy projection, keeps the hand-written file, and --check is then clean. --- bin/sync-ai-instructions.js | 16 +++++++++++++--- docs/upgrading.md | 22 +++++++++++++++++++--- 2 files changed, 32 insertions(+), 6 deletions(-) diff --git a/bin/sync-ai-instructions.js b/bin/sync-ai-instructions.js index d69b09c..e306ebf 100644 --- a/bin/sync-ai-instructions.js +++ b/bin/sync-ai-instructions.js @@ -90,8 +90,13 @@ const discoverPackages = ( root ) => { } fs.readdirSync( container ).forEach( ( slug ) => { const base = path.join( container, slug ); - if ( fs.existsSync( path.join( base, '.github', 'instructions' ) ) ) { - found.push( { type, slug, base, dir: path.join( base, '.github', 'instructions' ) } ); + const dir = path.join( base, '.github', 'instructions' ); + // A package qualifies when it already carries instructions or when it vendors + // the framework, because refreshPackage() creates its .github/instructions/ on + // the first run. Site repos often commit only the root projection, so a fresh + // checkout has no per-package directory and would otherwise be skipped forever. + if ( fs.existsSync( dir ) || fs.existsSync( path.join( base, FRAMEWORK_SRC ) ) ) { + found.push( { type, slug, base, dir } ); } } ); } ); @@ -219,6 +224,11 @@ const refreshPackage = ( base, relRoot ) => { const projectToRoot = ( root, packages ) => { const groups = new Map(); packages.forEach( ( { type, slug, dir } ) => { + // Under --check a package discovered through its vendored framework has no + // directory yet; refreshPackage() has already reported that as drift. + if ( ! fs.existsSync( dir ) ) { + return; + } const prefix = `${ type }/${ slug }`; fs.readdirSync( dir ) .filter( ( f ) => f.endsWith( '.instructions.md' ) ) @@ -277,7 +287,7 @@ const main = () => { } else { const packages = discoverPackages( root ); if ( 0 === packages.length ) { - console.log( color.yellow( 'No packages with .github/instructions/ under plugins/ or themes/. Nothing to do.' ) ); + console.log( color.yellow( 'No package under plugins/ or themes/ has .github/instructions/ or a vendored rtcamp/wp-primitives. Run `composer install` in each package, then re-run. Nothing to do.' ) ); process.exit( 0 ); } packages.forEach( ( p ) => refreshPackage( p.base, root ) ); diff --git a/docs/upgrading.md b/docs/upgrading.md index 38283a5..a9ef020 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -70,9 +70,25 @@ cannot cross it. 4. Retarget any translations from the `wp-framework` text domain to `wp-primitives`. -5. Run `npm run sync-ai`. It now writes - `.github/instructions/primitives-php.instructions.md` and deletes the superseded - `framework-php.instructions.md`. +5. If the consumer has its own `bin/sync-ai.js` wrapper (every package scaffolded + from the 1.x skeletons does), point it at the new path: + + ```diff + -const script = 'vendor/rtcamp/wp-framework/bin/sync-ai-instructions.js'; + +const script = 'vendor/rtcamp/wp-primitives/bin/sync-ai-instructions.js'; + ``` + + Otherwise `npm run sync-ai` reports the framework as "not installed yet" and + silently skips. + +6. Run `composer install` in every package, then `npm run sync-ai` from any one of + them. It writes `.github/instructions/primitives-php.instructions.md` and deletes + the superseded `framework-php.instructions.md` copies the old sync generated. + In a site repository (one wp-content root holding several packages) this also + works when only the root projection was committed: packages are discovered + through their vendored `rtcamp/wp-primitives`, not only through an existing + `.github/instructions/` directory. Hand-written instruction files are never + deleted. Projects that are not ready can stay on `^1.0`, which continues to resolve from the `v1.0.0` and `v1.0.1` tags. Those tags are immutable and still declare the old package From d256dffa8ec2af9e3bdc25eaba5799708a526ebd Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:55:05 +0530 Subject: [PATCH 18/25] test(asset-loader): cover a malformed manifest on the pre-6.8 fallback On WordPress 6.5 to 6.7 register_block_manifest() reads the manifest itself and must ignore one that does not evaluate to an array. That guard was the last uncovered branch in AssetLoader; the test runs on the legacy cells of the matrix and is skipped on 6.8+, where core reads the manifest instead. --- tests/AssetLoaderTest.php | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/tests/AssetLoaderTest.php b/tests/AssetLoaderTest.php index 88391b3..92e3385 100644 --- a/tests/AssetLoaderTest.php +++ b/tests/AssetLoaderTest.php @@ -204,6 +204,28 @@ public function test_register_block_manifest_registers_collection(): void { \WP_Block_Type_Registry::get_instance()->unregister( 'wp-primitives/example' ); } + public function test_legacy_fallback_ignores_a_manifest_that_is_not_an_array(): void { + // Only the 6.5 to 6.7 fallback reads the manifest itself; on 6.8+ core + // does, so the guard under test only exists on older cores. + if ( function_exists( 'wp_register_block_types_from_metadata_collection' ) ) { + $this->markTestSkipped( 'The per-block fallback only runs on WordPress < 6.8.' ); + } + + $this->write_asset( + 'build/blocks/example/block.json', + '{"$schema":"https://schemas.wp.org/trunk/block.json","apiVersion":3,"name":"wp-primitives/example","title":"Example","category":"widgets"}' + ); + // A manifest that evaluates to something other than an array. + $this->write_asset( 'build/blocks-manifest.php', 'loader->register_block_manifest( 'build/blocks', 'build/blocks-manifest.php' ); + + $this->assertFalse( + \WP_Block_Type_Registry::get_instance()->is_registered( 'wp-primitives/example' ), + 'a malformed manifest must register nothing rather than fatal' + ); + } + public function test_missing_block_manifest_warns_and_skips_registration(): void { $this->setExpectedIncorrectUsage( AssetLoader::class ); From cc487f01ed849cffd194c9399bc8c6698dfe6561 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:55:05 +0530 Subject: [PATCH 19/25] fix(block): fall back to the block name when the build dir is missing register_block() passed get_block_dir() to register_block_type() whenever it was non-empty. Before npm run build (a fresh clone, CI's test-php job, a deploy that lost its build) the directory has no block.json, so WordPress treated the path as a block name and raised "Block type names must contain a namespace prefix" on every request, registering nothing. The plugin skeleton's PHPUnit bootstrap hit this on WP 6.7 and 7.0. Register from the directory only when it holds a block.json, otherwise register by get_name() so the server-side render keeps working. The new test fails on any unexpected _doing_it_wrong(), so it also guards against the notice coming back. --- inc/Contracts/Abstracts/AbstractBlock.php | 9 +++++- .../Contracts/Abstracts/AbstractBlockTest.php | 32 +++++++++++++++++++ 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/inc/Contracts/Abstracts/AbstractBlock.php b/inc/Contracts/Abstracts/AbstractBlock.php index 88627f8..3639a1f 100644 --- a/inc/Contracts/Abstracts/AbstractBlock.php +++ b/inc/Contracts/Abstracts/AbstractBlock.php @@ -52,6 +52,13 @@ public function register_hooks(): void { /** * Register the block type with WordPress. + * + * Registers from get_block_dir() when that directory holds a block.json, and + * by name otherwise. A configured directory without a block.json (a fresh + * clone or a CI run before `npm run build`, or a deploy that lost its build) + * falls back to registering by name: the server-side render still works, and + * WordPress no longer receives the directory path as a block name, which it + * rejected with a "must contain a namespace prefix" notice on every request. */ public function register_block(): void { $args = $this->get_block_args(); @@ -60,7 +67,7 @@ public function register_block(): void { $args['render_callback'] = [ $this, 'render' ]; $block_dir = $this->get_block_dir(); - if ( $block_dir ) { + if ( $block_dir && file_exists( trailingslashit( $block_dir ) . 'block.json' ) ) { register_block_type( $block_dir, $args ); } else { register_block_type( static::get_name(), $args ); diff --git a/tests/Contracts/Abstracts/AbstractBlockTest.php b/tests/Contracts/Abstracts/AbstractBlockTest.php index 3f90490..99ad27c 100644 --- a/tests/Contracts/Abstracts/AbstractBlockTest.php +++ b/tests/Contracts/Abstracts/AbstractBlockTest.php @@ -72,6 +72,38 @@ public function test_render_returns_markup(): void { $this->assertSame( '
rendered
', $output ); } + public function test_block_dir_without_block_json_falls_back_to_the_block_name(): void { + // Regression: an unbuilt block directory used to reach register_block_type() + // as a "block name", so WordPress rejected it with a namespace-prefix + // notice and nothing was registered. WP_UnitTestCase fails the test on any + // unexpected _doing_it_wrong(), so the absence of a notice is asserted too. + $dir = sys_get_temp_dir() . '/wpf-unbuilt-' . str_replace( '.', '', uniqid( '', true ) ); + mkdir( $dir, 0777, true ); + + $block = new class( $dir ) extends AbstractBlock { + public function __construct( private string $dir ) {} + + public static function get_name(): string { + return 'wp-primitives-test/block'; + } + + public function render( array $attributes, string $content, \WP_Block $block ): string { + return 'fallback'; + } + + protected function get_block_dir(): ?string { + return $this->dir; + } + }; + + $block->register_block(); + rmdir( $dir ); + + $type = WP_Block_Type_Registry::get_instance()->get_registered( self::BLOCK_NAME ); + $this->assertNotNull( $type, 'the block must still register by name' ); + $this->assertSame( [ $block, 'render' ], $type->render_callback ); + } + public function test_register_block_uses_block_dir_when_provided(): void { $dir = sys_get_temp_dir() . '/wpf-block-' . str_replace( '.', '', uniqid( '', true ) ); mkdir( $dir, 0777, true ); From 9e3ded1cff4cc40978b33eb83784339edd18d06f Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:55:05 +0530 Subject: [PATCH 20/25] build(deps-dev): update PHPStan, the WordPress stubs and wp-phpunit phpstan/phpstan 2.2.16, szepeviktor/phpstan-wordpress 2.0.4 with php-stubs/wordpress-stubs 7.1.0, and wp-phpunit/wp-phpunit 7.1.1: the rest of Dependabot group #93 after the PHPCS security updates. PHPStan stays clean at level 6 against the WordPress 7.1 stubs. --- composer.lock | 52 +++++++++++++++++++++++++-------------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/composer.lock b/composer.lock index 8450153..f81b6be 100644 --- a/composer.lock +++ b/composer.lock @@ -465,16 +465,16 @@ }, { "name": "php-stubs/wordpress-stubs", - "version": "v6.9.4", + "version": "v7.1.0", "source": { "type": "git", "url": "https://github.com/php-stubs/wordpress-stubs.git", - "reference": "90a9412826b9944f93b10bf41d795b5fe68abcd5" + "reference": "394570301894799e69a4aa117c9c995427e3ba04" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/php-stubs/wordpress-stubs/zipball/90a9412826b9944f93b10bf41d795b5fe68abcd5", - "reference": "90a9412826b9944f93b10bf41d795b5fe68abcd5", + "url": "https://api.github.com/repos/php-stubs/wordpress-stubs/zipball/394570301894799e69a4aa117c9c995427e3ba04", + "reference": "394570301894799e69a4aa117c9c995427e3ba04", "shasum": "" }, "conflict": { @@ -484,13 +484,13 @@ "dealerdirect/phpcodesniffer-composer-installer": "^1.0", "nikic/php-parser": "^5.5", "php": "^7.4 || ^8.0", - "php-stubs/generator": "^0.8.6", + "php-stubs/generator": "^0.9", "phpdocumentor/reflection-docblock": "^6.0", - "phpstan/phpstan": "^2.1", + "phpstan/phpstan": "^2.2", "phpunit/phpunit": "^9.5", "symfony/polyfill-php80": "*", - "szepeviktor/phpcs-psr-12-neutron-hybrid-ruleset": "^1.1.1", - "wp-coding-standards/wpcs": "3.1.0 as 2.3.0" + "szepeviktor/phpcs-psr-12-neutron-hybrid-ruleset": "^1.2", + "wp-coding-standards/wpcs": "3.4.1 as 2.3.0" }, "suggest": { "paragonie/sodium_compat": "Pure PHP implementation of libsodium", @@ -511,9 +511,9 @@ ], "support": { "issues": "https://github.com/php-stubs/wordpress-stubs/issues", - "source": "https://github.com/php-stubs/wordpress-stubs/tree/v6.9.4" + "source": "https://github.com/php-stubs/wordpress-stubs/tree/v7.1.0" }, - "time": "2026-05-01T20:36:01+00:00" + "time": "2026-08-28T00:32:06+00:00" }, { "name": "phpcompatibility/php-compatibility", @@ -905,11 +905,11 @@ }, { "name": "phpstan/phpstan", - "version": "2.2.5", + "version": "2.2.16", "dist": { "type": "zip", - "url": "https://api.github.com/repos/phpstan/phpstan/zipball/909c1e5fef7989ac0d0c1c5c42e32a5c4f6198a0", - "reference": "909c1e5fef7989ac0d0c1c5c42e32a5c4f6198a0", + "url": "https://api.github.com/repos/phpstan/phpstan/zipball/46a6d9060e5a7763adfcc21ebcb8b504ebdbcb92", + "reference": "46a6d9060e5a7763adfcc21ebcb8b504ebdbcb92", "shasum": "" }, "require": { @@ -965,7 +965,7 @@ "type": "github" } ], - "time": "2026-07-05T06:31:06+00:00" + "time": "2026-09-25T09:31:51+00:00" }, { "name": "phpunit/php-code-coverage", @@ -2545,21 +2545,21 @@ }, { "name": "szepeviktor/phpstan-wordpress", - "version": "v2.0.3", + "version": "v2.0.4", "source": { "type": "git", "url": "https://github.com/szepeviktor/phpstan-wordpress.git", - "reference": "aa722f037b2d034828cd6c55ebe9e5c74961927e" + "reference": "84577e2ea1e4c2a95537fe5ea2ac8e18f4ceab1a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/szepeviktor/phpstan-wordpress/zipball/aa722f037b2d034828cd6c55ebe9e5c74961927e", - "reference": "aa722f037b2d034828cd6c55ebe9e5c74961927e", + "url": "https://api.github.com/repos/szepeviktor/phpstan-wordpress/zipball/84577e2ea1e4c2a95537fe5ea2ac8e18f4ceab1a", + "reference": "84577e2ea1e4c2a95537fe5ea2ac8e18f4ceab1a", "shasum": "" }, "require": { "php": "^7.4 || ^8.0", - "php-stubs/wordpress-stubs": "^6.6.2", + "php-stubs/wordpress-stubs": ">=6.6.2", "phpstan/phpstan": "^2.0" }, "require-dev": { @@ -2602,9 +2602,9 @@ ], "support": { "issues": "https://github.com/szepeviktor/phpstan-wordpress/issues", - "source": "https://github.com/szepeviktor/phpstan-wordpress/tree/v2.0.3" + "source": "https://github.com/szepeviktor/phpstan-wordpress/tree/v2.0.4" }, - "time": "2025-09-14T02:58:22+00:00" + "time": "2026-05-22T16:22:09+00:00" }, { "name": "theseer/tokenizer", @@ -2724,16 +2724,16 @@ }, { "name": "wp-phpunit/wp-phpunit", - "version": "7.0.2", + "version": "7.1.1", "source": { "type": "git", "url": "https://github.com/wp-phpunit/wp-phpunit.git", - "reference": "0d17335392d78b12b3e7e6b519cd53db728df52a" + "reference": "797edc710afc958854852d859c93d9aa1de6447d" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/wp-phpunit/wp-phpunit/zipball/0d17335392d78b12b3e7e6b519cd53db728df52a", - "reference": "0d17335392d78b12b3e7e6b519cd53db728df52a", + "url": "https://api.github.com/repos/wp-phpunit/wp-phpunit/zipball/797edc710afc958854852d859c93d9aa1de6447d", + "reference": "797edc710afc958854852d859c93d9aa1de6447d", "shasum": "" }, "type": "library", @@ -2768,7 +2768,7 @@ "issues": "https://github.com/wp-phpunit/issues", "source": "https://github.com/wp-phpunit/wp-phpunit" }, - "time": "2026-07-10T02:38:55+00:00" + "time": "2026-08-20T00:59:59+00:00" }, { "name": "yoast/phpunit-polyfills", From 755ccc3c2e9e80f9432304bd14dabbc1cb76a9a6 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:55:05 +0530 Subject: [PATCH 21/25] ci: test WordPress 7.1 and correct the action version comments WordPress 7.1 is the current stable release (7.1.2), but the matrix stopped at 7.0, so the core most sites run was never tested. Add it for PHP 8.2 to 8.4. The checkout pins were labelled v6 but the SHA is v7.0.1 (the docs workflow already said so), and the deploy-pages pin is v4.0.5. The SHAs do not change. --- .github/workflows/documentation.yml | 2 +- .github/workflows/test-measure.yml | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 01b02f1..7ac9ebc 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -80,4 +80,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4 + uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5 diff --git a/.github/workflows/test-measure.yml b/.github/workflows/test-measure.yml index 5119a64..7b583f7 100644 --- a/.github/workflows/test-measure.yml +++ b/.github/workflows/test-measure.yml @@ -23,7 +23,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false @@ -60,7 +60,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false @@ -95,7 +95,7 @@ jobs: fail-fast: false matrix: php: ['8.2', '8.3', '8.4'] - wp: ['6.5', '6.6', '6.7', '6.8', '6.9', '7.0'] + wp: ['6.5', '6.6', '6.7', '6.8', '6.9', '7.0', '7.1'] exclude: # WordPress added PHP 8.4 support in 6.7. - { php: '8.4', wp: '6.5' } @@ -105,7 +105,7 @@ jobs: WP_ENV_CORE: WordPress/WordPress#${{ matrix.wp }} steps: - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false @@ -133,7 +133,7 @@ jobs: WP_ENV_PHP_VERSION: '8.3' steps: - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false From ba80c9211de1b9a7eca945871aa5bbf057d40af9 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 06:56:27 +0530 Subject: [PATCH 22/25] ci(docs): bump actions/deploy-pages to v5.0.1 v5 moves the action to the Node 24 runtime; v4 runs on Node 20, which GitHub is retiring for actions. Same change as Dependabot #97, applied here because this branch already edits the workflow. --- .github/workflows/documentation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 7ac9ebc..d67d755 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -80,4 +80,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5 + uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 From 45f4162ef5a69c8a2310f2d3291bc9835e3d860f Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 18:58:00 +0530 Subject: [PATCH 23/25] docs(changelog): list the block and sync-ai fixes, correct the upgrade note --- CHANGELOG.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9f58a8d..499978e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 transient name limit to `h:`. Such names were truncated by the options table, so the value was never found again on the next request (or, just past the limit, its expiry was silently dropped). Keys within the limit are unchanged. +- `AbstractBlock` registers by block name when the build directory has no + `block.json` (a fresh clone, or before `npm run build`). It used to pass the + directory to `register_block_type()`, which raised a "Block type names must + contain a namespace prefix" notice on every request and registered nothing. +- `sync-ai` also finds packages in site repositories that commit only the root + instructions projection, by detecting packages that vendor + `rtcamp/wp-primitives`. Before, such repositories got "Nothing to do" and kept + the legacy root file after upgrading. +- `sync-ai` prunes only the legacy files it generated and logs the real path of + each file it removes. ### Changed @@ -38,8 +48,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 repository moves to `rtCamp/wp-primitives`, and the AI rules file shipped to consumers is renamed from `ai/framework-php.instructions.md` to `ai/primitives-php.instructions.md` (synced into consumers as `.github/instructions/primitives-php.instructions.md`). - Consumers must move to a `^2.0` constraint; `^1.0` continues to resolve from the - existing `v1.0.0` / `v1.0.1` tags, which keep the old package name. + Consumers must move to a `^2.0` constraint. Existing installs keep working from + their `composer.lock`, but once this release is on `main`, `composer update` no + longer resolves `rtcamp/wp-framework`; move to `rtcamp/wp-primitives:^2.0` to keep + receiving updates. - **BREAKING: `AssetLoader::HANDLE_PREFIX` default changes from `wp-framework-` to `wp-primitives-`.** Any consumer that did not override the constant will see every From 193caf36690a7b1e2a20d05ed35ed3042146ffdd Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 19:35:26 +0530 Subject: [PATCH 24/25] docs: keep the package rename to the changelog Drop the rename notes from the README, the security policy, the maintainers guide, troubleshooting and the upgrading guide. The CHANGELOG 2.0.0 entry already records the rename and its breaking changes. --- README.md | 3 --- SECURITY.md | 8 +++--- docs/maintainers.md | 4 +-- docs/troubleshooting.md | 2 +- docs/upgrading.md | 56 ----------------------------------------- 5 files changed, 6 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 12cee97..cea69f2 100644 --- a/README.md +++ b/README.md @@ -45,9 +45,6 @@ before requiring it: } ``` -Upgrading from `rtcamp/wp-framework` 1.x? The package was renamed in 2.0.0; follow -[docs/upgrading.md](docs/upgrading.md#10x--200-package-rename). - PSR-4 autoloading: `rtCamp\WPPrimitives\` → `inc/`. ## Quick look diff --git a/SECURITY.md b/SECURITY.md index fa49b79..cac244c 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,10 +2,10 @@ ## Supported versions -| Version | Package | Supported | -|---|---|---| -| 2.x | `rtcamp/wp-primitives` | Yes | -| 1.0.x | `rtcamp/wp-framework` (the pre-rename name) | No further releases; upgrade to 2.x | +| Version | Supported | +|---|---| +| 2.x | Yes | +| 1.0.x | No further releases; upgrade to 2.x | ## Reporting a vulnerability diff --git a/docs/maintainers.md b/docs/maintainers.md index 447c46a..52973e3 100644 --- a/docs/maintainers.md +++ b/docs/maintainers.md @@ -173,7 +173,5 @@ A release is therefore a tag on `main`: webhook delivery under the repository's Settings > Webhooks. Never move, delete or re-push a published tag: consumers and Packagist have -already resolved it. Fix forward with a patch release instead. The `v1.0.x` -tags are the last releases under the old `rtcamp/wp-framework` name and stay -untouched for consumers still on `^1.0`. +already resolved it. Fix forward with a patch release instead. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index a33c150..b8d7236 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -70,7 +70,7 @@ one you get is deliberate: | Symptom | Cause | Fix | |---|---|---| | `Class "rtCamp\WPPrimitives\…" not found` | The consumer's `vendor/autoload.php` was never required, or the package resolved from a stale `vendor/`. | Require the autoloader in the plugin/theme entry point; `composer update rtcamp/wp-primitives`. | -| Composer can't find the package | The package was renamed from `rtcamp/wp-framework` to `rtcamp/wp-primitives` in 2.0.0, or the project installs from GitHub without a `repositories` entry. | Require `rtcamp/wp-primitives:^2.0` (see [upgrading.md](upgrading.md#10x--200-package-rename)); for GitHub installs add the VCS entry from [getting-started.md](getting-started.md#install). | +| Composer can't find the package | The project installs from GitHub without a `repositories` entry. | Add the VCS entry from [getting-started.md](getting-started.md#install). | | A missing abstract method only surfaces at runtime | The subclass doesn't implement everything the abstract declares. | Run PHPStan in the consuming package; it catches contract breaks before a request does. | Still stuck? The classes are small and heavily commented — `Loader::load()` in diff --git a/docs/upgrading.md b/docs/upgrading.md index a9ef020..4276060 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -38,62 +38,6 @@ Then run the consumer's own test suite. Static analysis catches the majority of contract breaks (a missing abstract implementation, a changed signature) before runtime does. -## 1.0.x → 2.0.0 (package rename) - -**Affects:** every consumer. 2.0.0 renames the package, so `composer update` alone -cannot cross it. - -1. Replace the requirement and the VCS repository entry in the consumer's - `composer.json`: - - ```diff - -"rtcamp/wp-framework": "^1.0" - +"rtcamp/wp-primitives": "^2.0" - ``` - - ```diff - -{ "type": "vcs", "url": "https://github.com/rtCamp/wp-framework.git", "no-api": true } - +{ "type": "vcs", "url": "https://github.com/rtCamp/wp-primitives.git", "no-api": true } - ``` - - Then `composer remove rtcamp/wp-framework && composer require rtcamp/wp-primitives:^2.0`. - The GitHub redirect keeps the old URL resolving, but the package name it serves has - changed, so the requirement must be edited by hand. - -2. Rewrite the namespace across the consumer: `rtCamp\WPFramework\` becomes - `rtCamp\WPPrimitives\` in every `namespace` declaration, `use` statement, PHPDoc - annotation and class-string. - -3. If you subclass `AssetLoader` without overriding `HANDLE_PREFIX`, every default - asset handle changes from `wp-framework-*` to `wp-primitives-*`. Audit any handle - referenced as a literal string. - -4. Retarget any translations from the `wp-framework` text domain to `wp-primitives`. - -5. If the consumer has its own `bin/sync-ai.js` wrapper (every package scaffolded - from the 1.x skeletons does), point it at the new path: - - ```diff - -const script = 'vendor/rtcamp/wp-framework/bin/sync-ai-instructions.js'; - +const script = 'vendor/rtcamp/wp-primitives/bin/sync-ai-instructions.js'; - ``` - - Otherwise `npm run sync-ai` reports the framework as "not installed yet" and - silently skips. - -6. Run `composer install` in every package, then `npm run sync-ai` from any one of - them. It writes `.github/instructions/primitives-php.instructions.md` and deletes - the superseded `framework-php.instructions.md` copies the old sync generated. - In a site repository (one wp-content root holding several packages) this also - works when only the root projection was committed: packages are discovered - through their vendored `rtcamp/wp-primitives`, not only through an existing - `.github/instructions/` directory. Hand-written instruction files are never - deleted. - -Projects that are not ready can stay on `^1.0`, which continues to resolve from the -`v1.0.0` and `v1.0.1` tags. Those tags are immutable and still declare the old package -name, so they keep working; they will not receive further releases. - ## 1.0.0 → 1.0.1 **Affects:** any class using the `Singleton` trait. From ec3c13e76f8d03cbc0d6be1eae22bd64cb2d97b8 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Thu, 1 Oct 2026 22:06:26 +0530 Subject: [PATCH 25/25] docs(changelog): cut 2.0.0 and fold the rename into one entry - Moves the unreleased notes under [2.0.0] - 2026-10-01 and adds the 2.0.0 compare link, as docs/maintainers.md describes. - The rename is one breaking entry that lists what the new name changes: namespace, AssetLoader::HANDLE_PREFIX, ComponentLoader::get_context() (its hooks and component asset handles were not listed before), the text domain and the AI rules file. - The text domain covers 22 translated strings; the 23rd wp-primitives literal is the ComponentLoader context. --- CHANGELOG.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 499978e..8379b65 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.0.0] - 2026-10-01 + ### Added - `AbstractAbility` and `AbstractAbilityRegistrar`, base classes for the WordPress @@ -43,26 +45,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed -- **BREAKING: renamed the package from `rtcamp/wp-framework` to `rtcamp/wp-primitives`.** - The PHP namespace moves from `rtCamp\WPFramework\` to `rtCamp\WPPrimitives\`, the - repository moves to `rtCamp/wp-primitives`, and the AI rules file shipped to consumers - is renamed from `ai/framework-php.instructions.md` to `ai/primitives-php.instructions.md` - (synced into consumers as `.github/instructions/primitives-php.instructions.md`). - Consumers must move to a `^2.0` constraint. Existing installs keep working from - their `composer.lock`, but once this release is on `main`, `composer update` no - longer resolves `rtcamp/wp-framework`; move to `rtcamp/wp-primitives:^2.0` to keep - receiving updates. - -- **BREAKING: `AssetLoader::HANDLE_PREFIX` default changes from `wp-framework-` to - `wp-primitives-`.** Any consumer that did not override the constant will see every - default asset handle change, so `wp_add_inline_script()`, `wp_localize_script()`, - dependency arrays and dequeue calls that referenced a `wp-framework-*` handle by - string must be updated. Override `HANDLE_PREFIX` in your subclass to keep the old - handles. -- **BREAKING: the gettext text domain changes from `wp-framework` to `wp-primitives`** - across the 23 translated strings in `inc/`. No `.pot`, `.po` or `.mo` files ship with - this package, so nothing in-repo breaks, but any consumer shipping translations for - the old domain must retarget them. +- **BREAKING: the package is now `rtcamp/wp-primitives`** (previously + `rtcamp/wp-framework`). Require `rtcamp/wp-primitives:^2.0`. Existing installs keep + working from their `composer.lock`, but `composer update` no longer resolves the old + name. The new name also changes these defaults: + - PHP namespace: `rtCamp\WPPrimitives\`. + - `AssetLoader::HANDLE_PREFIX`: `wp-primitives-`. Default asset handles change, so + handles referenced by string in `wp_add_inline_script()`, `wp_localize_script()`, + dependency arrays or dequeue calls must be updated. Override the constant to keep + the 1.x handles. + - `ComponentLoader::get_context()`: `wp-primitives`. Subclasses that do not override + it get `wp-primitives/component_*` hooks (`before_render`, `after_render`, + `asset_handle`, `should_enqueue`) and `wp-primitives-component-*` asset handles. + Override `get_context()` to keep the 1.x names. + - Text domain of the 22 translated strings in `inc/`: `wp-primitives`. No + translation files ship with this package; retarget any you maintain. + - AI rules file: `ai/primitives-php.instructions.md`, synced into consumers as + `.github/instructions/primitives-php.instructions.md`. ### Build @@ -148,6 +147,7 @@ Initial release. Requires PHP 8.2+. - Reference documentation under `docs/`, a GPL-2.0-or-later `LICENSE.md`, and a WordPress integration test suite running against `@wordpress/env`. -[Unreleased]: https://github.com/rtCamp/wp-primitives/compare/v1.0.1...HEAD +[Unreleased]: https://github.com/rtCamp/wp-primitives/compare/v2.0.0...HEAD +[2.0.0]: https://github.com/rtCamp/wp-primitives/compare/v1.0.1...v2.0.0 [1.0.1]: https://github.com/rtCamp/wp-primitives/compare/v1.0.0...v1.0.1 [1.0.0]: https://github.com/rtCamp/wp-primitives/releases/tag/v1.0.0