Fix: support Node 22 CLI installs (#361)

Lower the CLI engine floor to Node 22.12 so npx no longer falls back to stale 2.x releases for Node 22/23 users.

Add Node 22.12 CI coverage while preserving the stable required test check, and document the 3.2.1 CLI release notes including the detector and installer fixes already waiting on main.

AI-assisted-by: Codex

.github/workflows/ci.yml

@@ -41,9 +41,14 @@ jobs:
           GITHUB_EVENT_BEFORE: ${{ github.event.before }}
         run: node scripts/ci-test-plan.mjs
 
-  test:
+  test-matrix:
+    name: test (Node ${{ matrix.node-version }})
     runs-on: ubuntu-latest
     needs: changes
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [22.12.0, 24]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v7
@@ -51,7 +56,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v6
         with:
-          node-version: 24
+          node-version: ${{ matrix.node-version }}
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
@@ -104,13 +109,26 @@ jobs:
       - name: Upload build artifacts
         uses: actions/upload-artifact@v7
         with:
-          name: impeccable-dist
+          name: impeccable-dist-node-${{ matrix.node-version }}
           # Ship the packaged zips, not the unpacked Firefox staging tree.
           path: |
             dist/
             !dist/extension-firefox/
           retention-days: 7
 
+  test:
+    runs-on: ubuntu-latest
+    needs: test-matrix
+    if: always()
+    steps:
+      - name: Verify Node test matrix
+        run: |
+          if [ "${{ needs.test-matrix.result }}" != "success" ]; then
+            echo "test-matrix result: ${{ needs.test-matrix.result }}"
+            exit 1
+          fi
+          echo "test matrix passed"
+
   cli-remote-e2e:
     runs-on: ubuntu-latest
     needs: changes

README.npm.md

@@ -75,7 +75,7 @@ impeccable detect [options] [file-or-dir-or-url...]
 
 ## Requirements
 
-- Node.js 24+
+- Node.js 22.12+
 - `jsdom` (included as dependency, used for HTML scanning)
 - `puppeteer` (optional, only needed for URL scanning)
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "impeccable",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "author": "Paul Bakaus",
   "description": "Design skills, commands, and anti-pattern detection for AI coding agents",
   "keywords": [
@@ -24,7 +24,7 @@
     "url": "git+https://github.com/pbakaus/impeccable.git"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=22.12.0"
   },
   "type": "module",
   "bin": {

site/pages/changelog.astro

@@ -132,6 +132,18 @@ import '../styles/changelog-faq-kinpaku.css';
       </ul>
     </article>
 
+    <article id="cli-v3.2.1" class="cf-entry">
+      <header class="cf-entry-head"><span class="cf-version">CLI v3.2.1</span><span class="cf-date">July 9, 2026</span></header>
+      <p class="cf-entry-lead">A compatibility release for Node 22/23 that also ships the detector and installer fixes already waiting on main.</p>
+      <ul class="cf-items">
+        <li><strong>Node 22 and 23 install cleanly again.</strong> The CLI now declares <code>"node": "&gt;=22.12.0"</code> and CI runs the main test/build lane on Node 22.12 and Node 24. The ZIP installer has used <code>fflate</code> since v3.0.2, so the old <code>extract-zip</code> stream bug no longer requires avoiding Node 22/23.</li>
+        <li><strong><code>npx</code> no longer falls back to stale 2.x on modern LTS Node.</strong> Because current releases are engine-compatible with Node 22.12+, <code>npx impeccable install</code> stays on the latest CLI instead of selecting an older Node-18-compatible release that does not understand the top-level <code>install</code> command.</li>
+        <li><strong>Detector pre-scans can target typography or layout.</strong> <code>impeccable detect --scope type</code> and <code>--scope layout</code> narrow findings to the design domain a command is about to edit, and the new <code>design-system-font-size</code> rule flags literal sizes outside the <code>DESIGN.md</code> typography ramp. Brings the deterministic rule set to 46.</li>
+        <li><strong>Google Fonts and detector ignores are sharper.</strong> <code>fonts.googleapis.com/css2</code> URLs with multiple families, axes, and encoded names now feed the overused-font and single-font checks correctly, and file-scoped wildcard ignores now suppress findings that do not carry a value, such as side tabs.</li>
+        <li><strong>Pi global installs land in the right directory.</strong> User-scope installs, updates, and checks now use <code>~/.pi/agent/skills</code> while project installs continue to use <code>.pi/skills</code>, so Pi users get the same install/update behavior as the other harnesses.</li>
+      </ul>
+    </article>
+
     <article id="cli-v3.2.0" class="cf-entry">
       <header class="cf-entry-head"><span class="cf-version">CLI v3.2.0</span><span class="cf-date">July 1, 2026</span></header>
       <ul class="cf-items">

site/pages/index.astro

@@ -645,7 +645,7 @@ import '../styles/testimonials.css';
                 <span>Copy</span>
               </button>
             </div>
-            <p class="downloads-rebuild-method-note">Installs the build tailored to your harness and model. Requires <strong title="On older Node, npx resolves an outdated release that fails to install.">Node 24+</strong>.</p>
+            <p class="downloads-rebuild-method-note">Installs the build tailored to your harness and model. Requires <strong title="Node 22.12+ keeps npx on the current CLI instead of falling back to outdated releases.">Node 22.12+</strong>.</p>
 
             <details class="downloads-rebuild-branch">
               <summary class="downloads-rebuild-branch-summary">