V3: Insights (consent-based usage tracking) + commercial V3 Integration

[shazzad]

What V3 is

A new Shazzad\PluginUpdater\V3 namespace (src/V3/) that adds Insights: usage tracking on our own repo server, replacing what Appsero does for us today. Design: docs/superpowers/specs/2026-09-26-v3-insights-design.md, plan: docs/superpowers/plans/2026-09-26-v3-insights-plan.md.

It has two entry points:

• Free plugins (wordpress.org): V3\Insights. An Appsero-style consent notice (Allow / No thanks, nonce'd, manage_options). Nothing is sent until an admin clicks Allow. After that it sends a daily track plus activate / deactivate / upgrade / optin events to wp-repo/v4/products/{key}/track, and opt_out() asks the server to delete the site's data. It loads no update or license code. Free plugins ship only src/V3/Insights.php + src/V3/Insights/. The README has a tested build strip recipe.
• Commercial plugins: V3\Integration. This is the V2 entry point copied over, with the same config, option keys, transients, cron hook wprepo_sync_license_data_{name}, license page, notices and update-row message. A plugin moving V2 → V3 keeps every saved license. Tracking goes through the Insights parts in commercial mode: there is no consent step and no notice, and the license key is included. They are exposed as $insights_consent, $insights_collector, $insights_client and $insights_scheduler. Client::ping() is gone. The hourly sync now only checks the license, and activate / deactivate / upgrade send exactly one Insights track.
  • api_url is the plugin-repo wp-repo/v4 base, which serves updates, licensing and Insights (one URL, no derived Insights URL). An api_url still on wp-repo/v3 draws a _doing_it_wrong() notice and leaves tracking off; updates and licensing keep working.

Isolation guarantees

• V1 and V2 are byte-identical to main and to the 2.1.1 tag. Plugins that stay on them see no change:

  git diff main -- src/*.php src/V2          # empty (shell-expanded glob)
  git diff 2.1.1 -- src/*.php src/V2         # empty

• tests/V3/InsightsIsolationTest.php checks that the free files never reference Updater, License*, Admin\*, Integration, Tracker or V1/V2.
• tests/V3/CommercialIsolationTest.php checks that the commercial V3 files never reference Insights\Notice or the free entry point, never ping, and never V1/V2.
• A separate-process runtime test confirms that building a licensed V3\Integration and sending a track never loads Insights\Notice or V3\Insights. I made this test fail on purpose once, to confirm it can fail.

Server dependency

This needs shazzad/plugin-repo 2.8.0 (#79: wp-repo/v4 = all of v3 + track/optout) deployed on w4dev.com before any plugin ships on V3 — before that, v4 has no update, license or Insights routes there.

How to test

composer install
composer test                                                        # 415 tests, PHP 8.3
docker run --rm -v "$PWD":/app -w /app php:7.4-cli vendor/bin/phpunit # same 415 on PHP 7.4
composer lint   # V3 carries only the same pre-existing sniff classes as the V2 files it copies; PHPCompatibility 7.4- clean

• 204 of the 415 tests are in tests/V3/. The 9 "risky" warnings (no assertions: Mockery-only migration tests) already existed in V1/V2; the V3 copies inherit the same 3.
• End-to-end runs against the local stack (free + commercial test plugins) are covered by the overnight run's Task D. The manual QA sheet will be at docs/testing/v3-insights-manual-qa.md.

Not released

This is a draft. There is no version bump beyond the CHANGELOG 3.0.0 - Unreleased entry, no tag and no release. composer.json states no version.

🤖 Generated with Claude Code

Revised 2026-09-27: moved from the side namespace wp-repo-insights/v1 to wp-repo/v4; insights_api_url removed.

[shazzad]

Review fixes pushed (5 commits, 2815454..45451d2). Tests: 443 green on PHP 8.3 and 7.4 (was 415). V1/V2 diff against main is still empty.

1. Commercial in-place updates never tracked. Tracker::sync_license_data() (hourly, scheduled on every init) now re-creates the daily Insights cron if it is missing and calls run_daily(). The 20h MIN_INTERVAL guard stops double sends. 2815454
2. The notice under-disclosed. The list now covers every group in the payload: theme; plugin names and versions; users by role; WP memory limit and debug mode; multisite and local-site flags. "Usage statistics specific to {name}" is added automatically when meta/meta_callback is set. There is a new notice.items config key, validated like the other notice keys. A test ties the list to Collector::collect(). 950f0b8
3. Wording. Now reads "Your site's admin email address and administrator name". The E2E assertion is updated in plugin-updater-test#1 (db31e10).
4. Failed opt-out is no longer lost. It is stored in {slug}_insights_optout_pending and retried on admin_init (at most once an hour) and by the daily cron, which is kept for that. While pending, only {site_url, token} may be sent. The flag clears on success, on a missing token, on a new opt-in, or 7 days after the first failure. b23c447
5. Insights::uninstall( $file ) removes all 4 options and the cron on every site of a network. A network deactivation now clears the cron on every site; only the current site sends deactivate. 2b7a76d
6. Docs. The README migration note now covers the dropped $admin_email/$admin_name, the removed ping(), and the need to use setMeta()/setMetaCallback() after construction. The spec, CHANGELOG and QA sheet are updated. 45451d2

E2E: 22 passed, 2 failed, both on the server side. The shared local shazzad-plugin-repo checkout is on fix/lookup-hardening, which has another session's uncommitted work and no wp-repo-insights code. I left it alone. Re-run bin/insights-e2e once that checkout is back on feature/insights-api; expect 48 passed.

🤖 Generated with Claude Code