solid2-agent-kit 0.17.0 → 0.18.0

package/README.md

@@ -20,7 +20,7 @@ Supported agents: **Cursor** and **Claude Code**.
 | Edit-time hook | `postToolUse` entry in `.cursor/hooks.json` | `PostToolUse` entry in `.claude/settings.json` (matcher includes `Bash`) | Runs the mechanical gate automatically on **every agent file edit — including edits made through shell commands** (sed, heredocs, codemods; source paths mentioned in the command are checked after it ran) — and feeds findings straight back into the conversation (Cursor: `additional_context`; Claude Code: stderr + exit 2), so enforcement does not depend on the agent remembering to run `check`. Wired only when the kit is a local devDependency; opt out with `--no-hooks` |
 | Turn-end gate | — | `Stop` entry in `.claude/settings.json` | Whole-project `check` + `doctor` when the agent tries to end its turn: with findings in place the stop is blocked (exit 2) and the findings are fed back, so a turn cannot finish with React/Solid 1.x patterns left behind. Loop-safe via `stop_hook_active` (one forced continuation, never an infinite loop) |
 | Pre-execution guard | `preToolUse` + `beforeShellExecution` entries in `.cursor/hooks.json` | `PreToolUse` entry in `.claude/settings.json` | Denies actions **before they run**: edits/deletes of kit-owned guardrail files (an agent blocked by a gate will try to remove the gate), edits that would strip the kit's hook entries or managed blocks, uninspectable shell rewrites of those files, and `npm/pnpm/yarn/bun install` of banned dependencies (`react`, `vite-plugin-solid`, `eslint-plugin-solid`, SolidStart, ...) — caught proactively instead of post-hoc by `doctor` |
-| Project-wiring gate | `solid2-kit doctor` | same | Config drift the source gate cannot see: React / `vite-plugin-solid` / `eslint-plugin-solid` / SolidStart deps in `package.json`, a Solid 1.x line of `solid-js` / `@solidjs/router` / `@solidjs/meta` / `@solidjs/testing-library` / `@tanstack/solid-router` / `@tanstack/solid-query` (declared, or installed from the `latest` tag — Solid 2 releases are on `next`; TanStack Router's and Query's on `rc`), `jsx` ≠ `preserve` or `jsxImportSource` ≠ `@solidjs/web` in tsconfig, Solid 1.x wiring in root config files, and stale installed guidance (kit updated but `sync` not re-run) |
+| Project-wiring gate | `solid2-kit doctor` | same | Config drift the source gate cannot see: React / `vite-plugin-solid` / `eslint-plugin-solid` / SolidStart deps in `package.json`, a Solid 1.x line of `solid-js` / `@solidjs/router` / `@solidjs/meta` / `@solidjs/testing-library` / `@tanstack/solid-router` / `@tanstack/solid-query` (declared, or installed from the `latest` tag — Solid 2 releases are on `next`; TanStack Router's and Query's on `rc`), a Solid 2 prerelease older than the kit's baseline in `bin/baseline.mjs` (`@solidjs/web` / `@solidjs/signals` / `@solidjs/diagnostics` `latest` is an older rc than `next`), `jsx` ≠ `preserve` or `jsxImportSource` ≠ `@solidjs/web` in tsconfig, Solid 1.x wiring in root config files, and stale installed guidance (kit updated but `sync` not re-run) |
 | Review command | `.cursor/commands/solid2-review.md` | `.claude/commands/solid2-review.md` | `/solid2-review` — on-demand deep review: runs both gates, then walks the diff against the skill checklist targeting the semantic failure classes regexes cannot see (post-`await` reads, effect misuse, unkeyed server rows, boundary placement, context snapshots) |
 
 Managed blocks are delimited with `<!-- solid2-agent-kit:*:start/end -->` markers; everything
@@ -169,6 +169,7 @@ markdown with an `.md` suffix).
 
 ```
 bin/solid2-kit.mjs                 CLI: init / sync / check / doctor / hook
+bin/baseline.mjs                   Solid 2 versions the kit is verified against (doctor + check:upstream)
 files/shared/rules-body.md         hard rules (rendered into .mdc and CLAUDE.md)
 files/shared/agents-section.md     AGENTS.md managed-block content
 files/skills/solid-2/              SKILL.md + references/official-docs.md

package/bin/baseline.mjs

@@ -0,0 +1,41 @@
+// The Solid 2 releases the kit's guidance is verified against, shared by
+// `solid2-kit doctor` (a project on an older release is flagged) and
+// check:upstream (scripts/upstream-probes/registry.mjs: a newer release is
+// flagged). `line` is the major the kit targets: check:upstream installs the
+// newest dist-tagged version on it. `baseline` is the version every upstream
+// probe was verified against — bump it (and fix any marked claim that changed)
+// after re-verifying.
+//
+// npm dist-tags lag each other on these prereleases (@solidjs/web, @solidjs/signals
+// and @solidjs/diagnostics `latest` is an older 2.0 rc than `next`;
+// @solidjs/vite-plugin's `next` is behind `latest`), so a bare install can
+// resolve a release older than the baseline.
+export const BASELINE = {
+  'solid-js': { line: 2, baseline: '2.0.0-rc.9' },
+  '@solidjs/web': { line: 2, baseline: '2.0.0-rc.9' },
+  '@solidjs/signals': { line: 2, baseline: '2.0.0-rc.9' },
+  '@solidjs/diagnostics': { line: 2, baseline: '2.0.0-rc.9' },
+  '@solidjs/router': { line: 2, baseline: '2.0.0-next.27' },
+  '@solidjs/vite-plugin': { line: 3, baseline: '3.0.0-next.44' },
+  '@solidjs/testing-library': { line: 1, baseline: '1.0.0-beta.3' },
+};
+
+export function parseVersion(version) {
+  const [core, pre] = version.split('+')[0].split(/-(.*)/s);
+  return { core: core.split('.').map(Number), pre: pre ? pre.split('.') : [] };
+}
+
+// Semver precedence, prerelease-aware (2.0.0-rc.10 > 2.0.0-rc.9 < 2.0.0).
+export function compareVersions(a, b) {
+  const x = parseVersion(a);
+  const y = parseVersion(b);
+  for (let i = 0; i < 3; i++) if (x.core[i] !== y.core[i]) return x.core[i] - y.core[i];
+  if (!x.pre.length || !y.pre.length) return y.pre.length - x.pre.length;
+  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+    const [p, q] = [x.pre[i], y.pre[i]];
+    if (p === undefined || q === undefined) return p === undefined ? -1 : 1;
+    const numeric = /^\d+$/.test(p) && /^\d+$/.test(q);
+    if (p !== q) return numeric ? Number(p) - Number(q) : /^\d+$/.test(p) ? -1 : /^\d+$/.test(q) ? 1 : p < q ? -1 : 1;
+  }
+  return 0;
+}

package/bin/solid2-kit.mjs

@@ -24,6 +24,7 @@ import {
 } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { BASELINE, compareVersions } from './baseline.mjs';
 
 const KIT_ROOT = fileURLToPath(new URL('..', import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(KIT_ROOT, 'package.json'), 'utf8')).version;
@@ -273,7 +274,7 @@ function init() {
   if (hooksNote) console.log(`  note: ${hooksNote}`);
   if (!hasDiagnosticsDependency(target)) {
     console.log(
-      '  note: the solid-2 skill\'s development loop drives the dev server\'s /__solid/diagnostics endpoint; add "@solidjs/diagnostics" to devDependencies so @solidjs/vite-plugin serves it (auto-on when declared). Without it the fallback is an isDev-guarded attribution.enable({ log: false }).',
+      `  note: the solid-2 skill's development loop drives the dev server's /__solid/diagnostics endpoint; add "@solidjs/diagnostics" to devDependencies (install @solidjs/diagnostics@^${BASELINE['@solidjs/diagnostics'].baseline} — npm \`latest\` can be an older rc) so @solidjs/vite-plugin serves it (auto-on when declared). Without it the fallback is an isDev-guarded attribution.enable({ log: false }).`,
     );
   }
 }
@@ -1259,6 +1260,31 @@ const SOLID2_LINE_PACKAGES = [
   },
 ];
 
+// Packages doctor checks the version of: the Solid 1.x lines above, then any
+// release older than the kit's baseline (bin/baseline.mjs) — a bare
+// `npm i @solidjs/web` installs `latest`, 2.0.0-rc.0, which the current
+// @solidjs/vite-plugin's `@solidjs/web ^2.0.0-rc.9` peer rejects.
+const VERSION_CHECKED = [...new Set([...SOLID2_LINE_PACKAGES.map((p) => p.name), ...Object.keys(BASELINE)])];
+
+// The lower bound of a single-comparator range ("^2.0.0-rc.0", "~2.0.0-rc.8",
+// ">=2.0.0-rc.0", "2.0.0-rc.0") or an installed version. Dist-tags, "*",
+// unions and protocol specs have no bound to read; their install is checked.
+const LOWER_BOUND = /^\s*(?:[\^~]|>=|=)?\s*v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)\s*$/;
+
+// `declared` ranges are judged by their floor: npm installs the `latest` tag
+// whenever it satisfies the range, so "^2.0.0-rc.0" resolves to rc.0 today.
+function versionProblem(name, version, declared) {
+  const line = SOLID2_LINE_PACKAGES.find((p) => p.name === name);
+  if (line?.solid1.test(version)) return `the Solid 1.x line; this kit teaches Solid 2.x. ${line.fix}`;
+  const baseline = BASELINE[name]?.baseline;
+  const lowest = version.match(LOWER_BOUND)?.[1];
+  if (baseline && lowest && compareVersions(lowest, baseline) < 0) {
+    const older = declared ? 'allows releases older than' : 'older than';
+    return `${older} ${baseline}, the release this kit's guidance is verified against (npm dist-tags lag on the Solid 2 prereleases, so a bare install can resolve an older one). Install ${name}@^${baseline}.`;
+  }
+  return null;
+}
+
 function installedVersion(target, name) {
   try {
     return JSON.parse(readFileSync(join(target, 'node_modules', name, 'package.json'), 'utf8')).version;
@@ -1283,21 +1309,19 @@ function doctorFindings(target) {
   for (const [name, message] of Object.entries(BANNED_DEPS)) {
     if (name in deps) report(`dep-${name.replace(/[@/]/g, '')}`, `package.json depends on "${name}". ${message}`);
   }
-  for (const { name, id, solid1, fix } of SOLID2_LINE_PACKAGES) {
+  for (const name of VERSION_CHECKED) {
+    const id = SOLID2_LINE_PACKAGES.find((p) => p.name === name)?.id ?? `${name.replace('@solidjs/', '')}-version`;
     const range = deps[name];
-    if (typeof range === 'string' && solid1.test(range)) {
-      report(id, `package.json pins ${name} "${range}" — the Solid 1.x line; this kit teaches Solid 2.x. ${fix}`);
+    if (typeof range !== 'string') continue;
+    const declared = versionProblem(name, range, true);
+    if (declared) {
+      report(id, `package.json pins ${name} "${range}" — ${declared}`);
       continue;
     }
-    // A range such as "latest" or "*" only shows its line once resolved.
-    if (range === undefined) continue;
+    // A range such as "latest" or "*" only shows its version once resolved.
     const installed = installedVersion(target, name);
-    if (installed && solid1.test(installed)) {
-      report(
-        id,
-        `node_modules has ${name} ${installed} (package.json: "${range}") — the Solid 1.x line; this kit teaches Solid 2.x. ${fix}`,
-      );
-    }
+    const resolved = installed && versionProblem(name, installed, false);
+    if (resolved) report(id, `node_modules has ${name} ${installed} (package.json: "${range}") — ${resolved}`);
   }
 
   for (const entry of readdirSync(target, { withFileTypes: true })) {

package/files/skills/solid-2/SKILL.md

@@ -1179,7 +1179,8 @@ effects** — a pure markup or styling change does not need it.
 2. **Name the scopes you changed** (`createMemo(fn, { name: "total" })`,
    `createStore(v, { name: "cart" })`) so chains and tables refer to them by name.
 3. **Record the interaction and ask.** First choice — no app code — is the diagnostics
-   endpoint: with `@solidjs/diagnostics` in `devDependencies`, the Vite plugin's
+   endpoint: with `@solidjs/diagnostics` in `devDependencies` at the same version as
+   `solid-js` (npm `latest` can lag; `solid2-kit doctor` flags an older one), the Vite plugin's
    `diagnostics` option (auto-on when the package is declared; dev server only, never
    under vitest, `vite build`, or preview) injects the capture bridge and serves
    `/__solid/diagnostics`. `begin` enables attribution with `log: false` for the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid2-agent-kit",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Teach AI coding agents (Cursor, Claude Code) to write correct Solid 2.0 instead of React or Solid 1.x — always-applied rules, an agent skill, and a mechanical pattern gate.",
   "type": "module",
   "license": "MIT",