chore(tooling): enforce version sync, simplify release automation, add CI quality gates

.github/workflows/ci.yml

@@ -34,24 +34,52 @@ jobs:
             docs:
               - 'docs/**'
 
+  # Guards the manual versioning flow: every mirrored version source
+  # (package.json/composer.json/CHANGELOG/style.css/compatibility matrix/
+  # project.json) must agree before anything merges.
+  versions:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Check version sources are in sync
+        run: node scripts/check-versions.mjs
+
   core:
     needs: [changes]
     if: ${{ needs.changes.outputs.core == 'true' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
       - uses: actions/setup-node@v4
         with:
           node-version: '20'
       - name: Enable corepack
         run: corepack enable
       - name: Install core deps
-        run: pnpm install --ignore-scripts --filter './packages/webentor-core...'
+        # {dir}... selects the package AND its workspace dependencies, so
+        # webentor-configs gets its own deps installed (a bare './dir...'
+        # filter silently skips them and breaks eslint config resolution).
+        run: pnpm install --ignore-scripts --filter '{packages/webentor-core}...'
+      # NOTE: `typecheck` is not gated here yet — core has pre-existing tsc
+      # errors (missing @wordpress/* type deps + block typing issues). Add it
+      # to this job once `pnpm --filter './packages/webentor-core' typecheck`
+      # passes.
       - name: Lint/build/test core
         run: |
           pnpm --filter './packages/webentor-core' --if-present run lint
           pnpm --filter './packages/webentor-core' --if-present run build
           pnpm --filter './packages/webentor-core' --if-present run test
+      - name: PHP lint core (phpcs)
+        working-directory: packages/webentor-core
+        run: |
+          composer install --no-interaction --prefer-dist
+          composer lint
 
   configs:
     needs: [changes]
@@ -65,7 +93,7 @@ jobs:
       - name: Enable corepack
         run: corepack enable
       - name: Install configs deps
-        run: pnpm install --ignore-scripts --filter './packages/webentor-configs...'
+        run: pnpm install --ignore-scripts --filter '{packages/webentor-configs}...'
       - name: Lint/build/test configs
         run: |
           pnpm --filter './packages/webentor-configs' --if-present run lint
@@ -97,7 +125,7 @@ jobs:
       - name: Enable corepack
         run: corepack enable
       - name: Install codemods deps
-        run: pnpm install --filter './packages/webentor-codemods...'
+        run: pnpm install --filter '{packages/webentor-codemods}...'
       - name: Lint/test codemods
         run: |
           pnpm --filter './packages/webentor-codemods' --if-present run lint
@@ -112,18 +140,28 @@ jobs:
       - uses: shivammathur/setup-php@v2
         with:
           php-version: '8.3'
+          tools: phpcs
       - uses: actions/setup-node@v4
         with:
           node-version: '20'
       - name: Enable corepack
         run: corepack enable
-      - name: Install starter root dependencies
+      # A full starter `composer install` needs premium-plugin secrets
+      # (ACF Pro, Gravity Forms), so CI validates the manifest and lints
+      # instead of installing.
+      - name: Validate starter composer manifest
+        working-directory: packages/webentor-starter
+        run: composer validate --no-check-all --no-check-publish
+      - name: PHP lint starter (phpcs)
         working-directory: packages/webentor-starter
-        run: composer install --no-interaction --prefer-dist
+        run: phpcs
+      - name: PHP lint theme (phpcs)
+        working-directory: packages/webentor-starter/web/app/themes/webentor-theme-v2
+        run: phpcs --extensions=php --standard=PSR12 app
       - name: Build starter theme
         working-directory: packages/webentor-starter/web/app/themes/webentor-theme-v2
         run: |
-          pnpm install --ignore-scripts
+          pnpm install --ignore-workspace --ignore-scripts
           pnpm build
 
   docs:

.github/workflows/release.yml

@@ -4,13 +4,13 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: write
+  actions: write
+
 jobs:
   release:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      packages: write
-      pull-requests: write
     steps:
       - uses: actions/checkout@v4
         with:
@@ -20,17 +20,21 @@ jobs:
           node-version: '20'
       - name: Enable corepack
         run: corepack enable
-      - name: Install dependencies
-        run: pnpm install --ignore-scripts
 
-      # Changesets manages independent package versions in monorepo.
-      - name: Version and publish
-        uses: changesets/action@v1
-        with:
-          version: pnpm version-packages
-          publish: pnpm changeset publish
-          commit: 'chore(release): version packages'
-          title: 'chore(release): version packages'
+      # Versioning is manual (see AGENTS.md "Release Workflow"): a release is
+      # a reviewed commit that bumps version files. This workflow only acts on
+      # what is committed — it never decides versions itself.
+      - name: Check version sources are in sync
+        run: node scripts/check-versions.mjs
+
+      - name: Publish npm packages not yet on the registry
+        run: node scripts/publish-npm.mjs
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # Tag pushes with GITHUB_TOKEN don't trigger `on: push: tags`, so the
+      # script also dispatches the split workflows directly.
+      - name: Tag mirrored packages and dispatch split workflows
+        run: bash scripts/release-tags.sh
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.husky/pre-commit

@@ -13,6 +13,12 @@ if [ -z "$STAGED_CORE_FILES" ]; then
   exit 0
 fi
 
+echo "Linting staged webentor-core files..."
+if ! pnpm --filter './packages/webentor-core' exec lint-staged; then
+  echo "lint-staged failed. Commit aborted."
+  exit 1
+fi
+
 # Only rebuild when staged source or package metadata can change the bundle output.
 if printf "%s\n" "$STAGED_CORE_FILES" | grep -E '(^packages/webentor-core/.*\.(ts|tsx|js|jsx|css|scss|sass|less)$)|(^packages/webentor-core/package\.json$)' > /dev/null; then
   echo "webentor-core source changes detected, running package build..."

AGENTS.md

@@ -134,44 +134,53 @@ Shared release is not complete until demo CI is green.
 - Use independent semver per package; do not force shared version numbers across the monorepo.
 - On every release request, update `docs/src/compatibility-matrix.md` with the tested-together version set.
 
-## Release Workflow (Manual versioning)
+## Release Workflow (Manual versioning, automated rollout)
 
-For released packages in this monorepo, maintainers choose version bumps and write
-changelog entries manually. Do not rely on `.changeset` files or generated version PRs
-to decide release contents. The source of truth is the version and changelog files
-committed in the repository.
+Maintainers choose version bumps and write changelog entries manually — the
+committed version and changelog files are the source of truth. Everything
+after the merge is automated: publishing, tagging, and mirror splits react to
+what is committed on `main`.
 
 ### Release preparation
 
 1. Decide the semver bump for each affected package.
-2. Edit the authoritative version files listed in the "Version Source Map" below.
-3. Update the package changelog manually with a curated release entry.
-4. Keep every mirrored version field in sync for packages that have multiple version sources.
-5. Update `docs/src/compatibility-matrix.md` with the tested-together version set.
-6. Commit and push the release preparation through the normal review flow.
-
-### Existing release workflow
-
-- Keep the current release workflow structure in place after release preparation is merged.
-- `release.yml` remains the repository release automation entry point on push to `main`.
-- Push a namespaced tag to trigger split-mirror workflows when needed:
- - `core-v*` -> `split-webentor-core.yml` (also pings Packagist)
- - `setup-v*` -> `split-webentor-setup.yml`
- - `starter-v*` -> `split-webentor-starter.yml`
-- Example: `git tag core-v0.9.14 && git push origin core-v0.9.14`
+2. Run `pnpm release:prep <pkg>=<x.y.z> [...]` (pkg: `core`, `configs`,
+   `setup`, `codemods`, `starter`, `theme`). It stamps every mirrored version
+   source, scaffolds the changelog entry, inserts the compatibility-matrix
+   row, and updates `.webentor/project.json` baselines. Bump packages that
+   release together in ONE invocation so the matrix gains a single row.
+3. Replace the scaffolded TODO changelog line(s) with curated entries.
+4. Run `pnpm check:versions` (CI enforces the same check on every PR/push).
+5. Commit and push the release preparation through the normal review flow.
+
+### What happens on merge to `main`
+
+`release.yml` runs automatically:
+
+1. `scripts/check-versions.mjs` — aborts if any mirrored version source drifted.
+2. `scripts/publish-npm.mjs` — publishes any npm package (`core`, `configs`,
+   `codemods`) whose committed version is not on the registry yet.
+3. `scripts/release-tags.sh` — pushes the namespaced tag (`core-v*`,
+   `setup-v*`, `starter-v*`) for any mirrored package version that has no tag
+   yet and dispatches the matching split workflow:
+   - `core-v*` -> `split-webentor-core.yml` (also pings Packagist)
+   - `setup-v*` -> `split-webentor-setup.yml`
+   - `starter-v*` -> `split-webentor-starter.yml`
+
+No manual tag pushes are needed for a normal release. To re-run a mirror split
+manually, dispatch the split workflow with the tag as input, or push the tag
+by hand (`git tag core-v0.9.14 && git push origin core-v0.9.14`).
 
 ### AI agent release instructions
 
 When asked to release a package:
 
 1. Identify the affected package(s) and choose the correct bump level.
-2. Edit the version files directly in the repository.
-3. Update the relevant changelog file(s) manually.
-4. Keep all related version sources synchronized for that package.
-5. Update `docs/src/compatibility-matrix.md`.
-6. Commit and push through the normal release flow, then push the namespaced tag when needed.
-
-Manual version and changelog edits are expected for release work in this repository.
+2. Run `pnpm release:prep` with all packages releasing together.
+3. Replace the scaffolded TODO changelog line(s) with curated entries.
+4. Verify with `pnpm check:versions` and `pnpm test-release`.
+5. Commit and push through the normal review flow. Publishing and tagging
+   happen automatically after the merge to `main`.
 
 ## Version Source Map
 
@@ -196,15 +205,19 @@ Reference map for locating version sources per package.
   - npm publish via the existing release workflow (no Composer mirror)
 - `webentor-starter` (stable, `2.x`):
   - `packages/webentor-starter/composer.json` -> `"version"` (manual)
-  - `packages/webentor-starter/changelog.md` -> add new entry at top (manual)
+  - `packages/webentor-starter/CHANGELOG.md` -> add new entry at top (manual)
   - Runtime is mirrored via split workflow (no npm publish)
 - `webentor-theme-v2` (stable, `2.x`, inside starter):
   - `packages/webentor-starter/web/app/themes/webentor-theme-v2/package.json` -> `"version"` (manual)
   - `packages/webentor-starter/web/app/themes/webentor-theme-v2/composer.json` -> `"version"` (manual)
   - `packages/webentor-starter/web/app/themes/webentor-theme-v2/style.css` -> `Version:` header (manual)
-  - `packages/webentor-starter/web/app/themes/webentor-theme-v2/changelog.md` -> add new entry at top (manual)
+  - `packages/webentor-starter/web/app/themes/webentor-theme-v2/CHANGELOG.md` -> add new entry at top (manual)
   - Keep all theme version sources synchronized in the same bump
 
+`pnpm release:prep` edits all of these in one command; `pnpm check:versions`
+(and the `versions` CI job) fails on any mismatch, including the
+compatibility-matrix top row and `.webentor/project.json` baselines.
+
 ## Mirror Policy
 
 Mirror targets and workflows:
@@ -235,9 +248,11 @@ Before handoff, run relevant checks:
 
 - Shell syntax for setup scripts:
   - `find packages/webentor-setup -type f -name '*.sh' -print0 | xargs -0 -n1 bash -n`
-- Shell syntax for split mirror scripts:
+- Shell syntax for split mirror and release scripts:
   - `bash -n scripts/split-webentor-setup.sh`
   - `bash -n scripts/split-webentor-starter.sh`
+  - `bash -n scripts/release-tags.sh`
+- Version source consistency: `pnpm check:versions`
 - Setup CLI syntax:
   - `php -l packages/webentor-setup/src/webentor-setup.php`
 - JSON validity for changed `package.json` or manifest files.

package.json

@@ -27,13 +27,11 @@
     "test:teardown": "bash scripts/test-env-teardown.sh",
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",
-    "changeset": "changeset",
-    "version-packages": "changeset version && node scripts/sync-composer-versions.mjs",
+    "check:versions": "node scripts/check-versions.mjs",
+    "release:prep": "node scripts/release-prep.mjs",
     "prepare": "husky || true"
   },
   "devDependencies": {
-    "@changesets/changelog-github": "^0.5.1",
-    "@changesets/cli": "^2.29.7",
     "husky": "^9.1.7",
     "@playwright/test": "^1.58.2",
     "@wordpress/e2e-test-utils-playwright": "^1.41.0"

packages/webentor-core/composer.json

@@ -33,6 +33,12 @@
     "kucrut/vite-for-wp": "^0.11.6"
   },
   "require-dev": {
-    "php": ">=8.2"
+    "php": ">=8.2",
+    "squizlabs/php_codesniffer": "^3.8.0"
+  },
+  "scripts": {
+    "lint": [
+      "phpcs"
+    ]
   }
 }