solid2-agent-kit 0.14.0 → 0.16.0

package/README.md

@@ -16,11 +16,11 @@ Supported agents: **Cursor** and **Claude Code**.
 | Always-applied hard rules | `.cursor/rules/solid-2.mdc` (glob-attached to `*.tsx`/`*.jsx`) | managed block in `CLAUDE.md` | 23 hard rules + banned Solid 1.x API table + eslint-plugin-solid lint-heritage table. Injected without the agent having to decide to read anything |
 | Agent skill | `.cursor/skills/solid-2/` | `.claude/skills/solid-2/` | Execution-model primer, decision tables, canonical patterns, a “still runs / write the other form” table, review checklist, official-doc URL index |
 | Shared agent context | managed block in `AGENTS.md` | same (Claude Code users can reference it from `CLAUDE.md`) | Core principles and pointers, always in context |
-| Mechanical gate | `solid2-kit check` | same | Comment-stripped regex guard over `src/**/*.{ts,tsx,jsx}` (or explicit `[files...]`): fails on props destructuring (including multi-line signatures), `{ ...props }` rest copies, `{list().map(...)}` in JSX, React imports/hooks/JSX props/`React.lazy`/`useOptimistic`/`onDoubleClick`, Solid 1.x imports/APIs/components/JSX namespaces, `vite-plugin-solid`, old-router `<Route>`/`<A>`/`<HashRouter>`/`<FileRoutes>`, `MetaProvider`, `Context.Provider`, camelCase style keys, `key` props, `value()!` hand-narrowing, hand-rolled loading signals, `=== undefined` readiness branches, SolidStart leftovers (`@solidjs/start`, `h3`, `createAsync`, `useSubmission`, `"use client"`), Next.js imports/`useRouter`/`typeof window`, `history.pushState`, `render(<App />)` (pass a function), `isPending(user())` / `latest(user())` (pass the accessor), `<Dynamic>` (use `dynamic()`), `import type { JSX } from "solid-js"` (no `JSX` namespace there — `Element` from `solid-js`, DOM `JSX` types from `@solidjs/web`), two-phase effects whose apply only writes a local signal (use a writable derivation), core `action(async ...)` with a plain async function instead of a generator (only `yield` re-enters the transaction), and `setStore(async ...)` on a `createStore` / `createOptimisticStore` setter (the draft is a synchronous transaction; dev throws `[ASYNC_STORE_SETTER]`) |
+| Mechanical gate | `solid2-kit check` | same | Comment-stripped regex guard over `src/**/*.{ts,tsx,jsx}` (or explicit `[paths...]` — files are checked, directories are walked, a missing path fails): fails on props destructuring (including multi-line signatures), `{ ...props }` rest copies, `{list().map(...)}` in JSX, React imports/hooks/JSX props/`React.lazy`/`useOptimistic`/`onDoubleClick`, Solid 1.x imports/APIs/components/JSX namespaces (valueless `use:x` included), Solid 1.x `createEffect(fn)` / `createEffect(fn, init)` / `createMemo(fn, init)` signatures, `const [x] = createProjection(...)` (it returns the store, not a tuple), `vite-plugin-solid`, old-router `<Route>`/`<A>`/`<HashRouter>`/`<FileRoutes>`, `MetaProvider`, `Context.Provider`, camelCase style keys, `key` props (except on `@solidjs/meta` tags), `value()!` hand-narrowing, hand-rolled loading signals, `=== undefined` readiness branches, SolidStart leftovers (`@solidjs/start`, `h3`, `createAsync`, `useSubmission`, `"use client"`), Next.js imports/`useRouter`/`typeof window`, `history.pushState`, `render(<App />)` (pass a function), `isPending(user())` / `latest(user())` (pass the accessor), `<Dynamic>` (use `dynamic()`), `import type { JSX } from "solid-js"` (no `JSX` namespace there — import `JSX` from `@solidjs/web`, or use an aliased `Element` from `solid-js`), two-phase effects whose apply only writes a local signal (use a writable derivation), core `action(async ...)` with a plain async function instead of a generator (only `yield` re-enters the transaction), and `setStore(async ...)` on a `createStore` / `createOptimisticStore` setter (the draft is a synchronous transaction; dev throws `[ASYNC_STORE_SETTER]`) |
 | 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 1.x `solid-js` range, `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` / `@tanstack/solid-router` (declared, or installed from the `latest` tag — Solid 2 releases are on `next`; TanStack Router'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) |
 | 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
@@ -40,10 +40,15 @@ npx github:lightsound/solid2-agent-kit init
 npx github:lightsound/solid2-agent-kit init --cursor
 npx github:lightsound/solid2-agent-kit init --claude
 
-# run the mechanical pattern gate (default source dir: src; or name files)
+# run the mechanical pattern gate (default source dir: src; or name files and directories)
 npx github:lightsound/solid2-agent-kit check
 npx github:lightsound/solid2-agent-kit check --dir app
-npx github:lightsound/solid2-agent-kit check src/App.tsx
+npx github:lightsound/solid2-agent-kit check src/App.tsx src/routes
+
+# only the files a change touched: a missing path always fails (exit 2), so
+# --diff-filter=d keeps deleted files out of the list; -z / -0 keep paths with
+# spaces whole, -r skips the run on an empty (or delete-only) diff
+git diff --name-only -z --diff-filter=d main | xargs -0 -r npx github:lightsound/solid2-agent-kit check
 
 # check the project wiring (deps, tsconfig, root configs)
 npx github:lightsound/solid2-agent-kit doctor

package/bin/solid2-kit.mjs

@@ -4,7 +4,7 @@
 //
 //   solid2-kit init  [--cursor] [--claude] [--no-hooks] [--target <dir>]
 //   solid2-kit sync  [--cursor] [--claude] [--no-hooks] [--target <dir>]   (alias of init)
-//   solid2-kit check [--dir <srcdir>] [--target <dir>] [files...]
+//   solid2-kit check [--dir <srcdir>] [--target <dir>] [paths...]
 //   solid2-kit doctor [--target <dir>]
 //   solid2-kit hook (claude|cursor)          (stdin: agent hook JSON payload)
 //
@@ -19,6 +19,7 @@ import {
   readFileSync,
   readdirSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
@@ -404,6 +405,95 @@ function actionAsyncFindings(content) {
   }));
 }
 
+// Solid 1.x signatures: `createEffect(fn)` (Solid 2 needs compute + apply),
+// `createEffect(fn, initialValue)`, and `createMemo(fn, initialValue[, options])`
+// (Solid 2's second memo argument is the options object). A second argument
+// that is a primitive or array literal is an initial value; functions,
+// identifiers, and object literals are left alone. A name this file imports
+// from another library (effector's one-argument `createEffect`) or declares
+// itself is not Solid's.
+const INITIAL_VALUE_LITERAL = /^(?:-?\d|['"`[]|true\b|false\b|null\b|undefined\b)/;
+const NOT_SOLID_CORE_MODULE = /^(?!(?:solid-js|@solidjs\/signals)$)/;
+
+// Blank type-argument lists (`Record<string, number>`, `Map<K, () => void>`)
+// so their commas do not split arguments. `<` counts only right after an
+// identifier: formatted comparisons have a space before it.
+function blankTypeArguments(text) {
+  let previous;
+  do {
+    previous = text;
+    text = text.replace(/(?<=[\w$])<(?:=>|[^<>=])*>/g, (typeArgs) => ' '.repeat(typeArgs.length));
+  } while (text !== previous);
+  return text;
+}
+
+function solid1SignatureFindings(content) {
+  const foreign = importedNames(content, NOT_SOLID_CORE_MODULE);
+  const matches = [];
+  for (const call of content.matchAll(
+    /(?<![.\w$])create(Effect|Memo)\s*(?:<(?:=>|[^<>]|<(?:=>|[^<>])*>)*>)?\s*\(/g,
+  )) {
+    const name = `create${call[1]}`;
+    if (foreign.has(name)) continue;
+    if (new RegExp(`\\b(?:function\\s*\\*?|const|let|var|class)\\s+${name}\\b`).test(content)) continue;
+    const open = call.index + call[0].length - 1;
+    const close = scanBalanced(content, open);
+    if (close === -1) continue;
+    const args = splitTopLevelArgs(blankTypeArguments(content.slice(open + 1, close)))
+      .map((arg) => arg.trim())
+      .filter(Boolean);
+    const initialValue = args.length >= 2 && INITIAL_VALUE_LITERAL.test(args[1]);
+    const legacy =
+      call[1] === 'Effect' ? args.length === 1 || initialValue : args.length >= 3 || initialValue;
+    if (legacy) matches.push({ index: call.index });
+  }
+  return matches;
+}
+
+// `key` is meaningless in Solid JSX except on the Solid Meta tags, where it
+// names the tag's identity (`<Meta key="og-image" …>`). The enclosing tag is
+// the nearest `<Name` (or `<Namespace.Name`) before the attribute.
+const META_MODULE = /^@solidjs\/meta$/;
+
+function reactKeyPropFindings(content) {
+  const metaTags = importedNames(content, META_MODULE);
+  const metaNamespaces = new Set(
+    [...content.matchAll(/\bimport\s+\*\s+as\s+([\w$]+)\s+from\s*['"]@solidjs\/meta['"]/g)].map((m) => m[1]),
+  );
+  const matches = [];
+  for (const attr of content.matchAll(/\skey=\{/g)) {
+    const opener = [...content.slice(0, attr.index).matchAll(/<([A-Za-z][\w$.]*)/g)].pop();
+    const tag = opener?.[1] ?? '';
+    if (metaTags.has(tag) || metaNamespaces.has(tag.split('.')[0])) continue;
+    matches.push({ index: attr.index });
+  }
+  return matches;
+}
+
+// TanStack Router for Solid exports names the Next.js / Solid Router 1.x rules
+// target (`useRouter()`, `notFound()`, `<Navigate>`). A match is exempt only
+// when this file binds that exact local name from one of these modules, so a
+// stray Next or Router 1.x call in the same file is still reported. TanStack
+// Router 1.x (Solid 1) and 2.x (Solid 2) export the same names from the same
+// module, so the major is invisible here; doctor's tanstack-router-version
+// reads it from package.json / node_modules.
+const TANSTACK_ROUTER_MODULE = /^@tanstack\/(?:solid-router|router-core)$/;
+
+// Local names bound by `import [Default,] { a, b as c } from "<module>"`.
+function importedNames(content, moduleName) {
+  const names = new Set();
+  for (const decl of content.matchAll(
+    /\bimport\s+(?:type\s+)?(?:[\w$]+\s*,\s*)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g,
+  )) {
+    if (!moduleName.test(decl[2])) continue;
+    for (const specifier of decl[1].split(',')) {
+      const local = specifier.trim().replace(/^type\s+/, '').split(/\s+as\s+/).pop();
+      if (local) names.add(local);
+    }
+  }
+  return names;
+}
+
 const CHECKS = [
   {
     id: 'props-destructure-param',
@@ -432,7 +522,19 @@ const CHECKS = [
     id: 'jsx-namespace-import',
     pattern: /import\s+(?:type\s+)?\{[^}]*\bJSX\b[^}]*\}\s*from\s+['"]solid-js['"]/g,
     message:
-      'Solid 2 does not export a `JSX` namespace from "solid-js" (TS2305). Children/return types are `Element` from "solid-js"; DOM-specific JSX types (JSX.IntrinsicElements, JSX.CSSProperties) come from "@solidjs/web".',
+      'Solid 2 does not export a `JSX` namespace from "solid-js" (TS2305). Import `JSX` from "@solidjs/web" (JSX.Element, JSX.IntrinsicElements, JSX.CSSProperties), or use `Element` from "solid-js" (aliased, e.g. `type Element as SolidElement`, where the DOM Element is also used).',
+  },
+  {
+    id: 'solid1-effect-memo-signature',
+    find: solid1SignatureFindings,
+    message:
+      'Solid 1.x signature. createEffect takes (compute, apply) — a single argument is an error in Solid 2. createMemo(fn, initialValue) is gone: the second argument is the options object; give the compute a default parameter instead (createMemo((prev = 0) => ...)).',
+  },
+  {
+    id: 'projection-destructure',
+    pattern: /\b(?:const|let|var)\s*\[[^\]]*\]\s*=\s*createProjection\b/g,
+    message:
+      'createProjection returns the store itself, not a [store, setter] tuple — destructuring it takes the first row. Write `const rows = createProjection(...)`.',
   },
   {
     // A two-phase createEffect whose apply is nothing but one (optionally
@@ -486,8 +588,9 @@ const CHECKS = [
   },
   {
     id: 'react-key-prop',
-    pattern: /\skey=\{/g,
-    message: 'React `key` prop has no meaning in Solid. Row identity belongs on <For keyed={...}>.',
+    find: reactKeyPropFindings,
+    message:
+      'React `key` prop has no meaning in Solid. Row identity belongs on <For keyed={...}>. (Only the @solidjs/meta tags take `key`, as the tag identity.)',
   },
   {
     // `{todos().map((t) => <Row />)}` renders then recreates every row.
@@ -552,14 +655,21 @@ const CHECKS = [
     message: 'Solid 1.x Vite plugin. Import `solid` from "@solidjs/vite-plugin".',
   },
   {
+    // Valueless attributes count too (`<input use:autofocus />`): followed by
+    // `/>`, `>`, or another attribute, unlike an unspaced object key
+    // (`{ on:true }`, `{ on:x = false }`, `{ attr:v as string }`); `as="font"`
+    // and SVG `in="…"` are still attributes. `prop:` is still a Solid 2
+    // namespace and is not listed.
     id: 'solid1-jsx-namespace',
-    pattern: /\b(?:use|on|oncapture|attr|bool):[A-Za-z][\w-]*=/g,
+    pattern:
+      /(?<=\s)(?:use|on|oncapture|attr|bool):[A-Za-z][\w-]*(?==|\s*\/?>|\s+(?!(?:as|satisfies|in|instanceof)\b(?!\s*=))[A-Za-z_${])/g,
     message:
       'Solid 1.x JSX namespace. Use ref callbacks (and directive factories), camelCase event props, and standard attributes.',
   },
   {
     id: 'solid1-router',
     pattern: /<(?:HashRouter|MemoryRouter|Route|Navigate|A|FileRoutes|StartClient|StartServer)\b/g,
+    exemptImportsFrom: TANSTACK_ROUTER_MODULE,
     message:
       'Solid Router 0.x/1.x or SolidStart JSX. Define routes with createRouter({ routes }) / fileRoutes(pageRoutes) and plain <a href={Router.paths...}> (link state: automatic aria-current/data-active/data-pending + CSS, or useLinkState).',
   },
@@ -606,6 +716,7 @@ const CHECKS = [
     id: 'next-nav',
     pattern:
       /(?<![.\w])(?:useRouter|usePathname|revalidatePath|revalidateTag|notFound|hydrateRoot)\s*\(/g,
+    exemptImportsFrom: TANSTACK_ROUTER_MODULE,
     message:
       'Next.js / React DOM leftover. In-app navigation is useNavigate / <a href={Router.paths...}>; 404 is httpStatus(404); hydrate is hydrate(() => <App />, root).',
   },
@@ -716,11 +827,16 @@ function stripComments(content) {
   return out;
 }
 
+// Dependencies and dot-directories (.git, build caches, installed agent
+// guidance) are never project sources, so `check .` stays meaningful.
 function* walk(dir) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const path = join(dir, entry.name);
-    if (entry.isDirectory()) yield* walk(path);
-    else if (SOURCE_FILE.test(entry.name)) yield path;
+    if (entry.isDirectory()) {
+      if (entry.name !== 'node_modules' && !entry.name.startsWith('.')) yield* walk(path);
+    } else if (SOURCE_FILE.test(entry.name)) {
+      yield path;
+    }
   }
 }
 
@@ -733,7 +849,9 @@ function fileFindings(file, relativeTo) {
   const lines = raw.split('\n');
   const findings = [];
   for (const rule of CHECKS) {
+    const exempt = rule.exemptImportsFrom ? importedNames(content, rule.exemptImportsFrom) : null;
     for (const match of rule.find ? rule.find(content) : content.matchAll(rule.pattern)) {
+      if (exempt?.has(match[0].match(/[\w$]+/)[0])) continue;
       const lineNumber = content.slice(0, match.index).split('\n').length;
       findings.push(
         `${relative(relativeTo, file) || file}:${lineNumber} [${rule.id}] ${rule.message}\n  > ${lines[lineNumber - 1].trim()}`,
@@ -745,12 +863,35 @@ function fileFindings(file, relativeTo) {
 
 function check() {
   const target = resolve(flagValue('--target', '.'));
-  const fileArgs = positionalArgs();
+  const pathArgs = positionalArgs();
 
   let files;
-  if (fileArgs.length > 0) {
-    // Explicit file mode (used by agent hooks): check only the named sources.
-    files = fileArgs.map((file) => resolve(target, file)).filter((file) => SOURCE_FILE.test(file));
+  let scanned;
+  let walked = true;
+  if (pathArgs.length > 0) {
+    // Explicit path mode: named directories are walked, named files are
+    // checked when they are .ts/.tsx/.jsx sources.
+    files = [];
+    scanned = pathArgs;
+    walked = false;
+    // A missing path is always an error: a deleted file, a misspelled file, and
+    // a renamed source directory look the same here, and only the list's
+    // producer knows which it was.
+    for (const arg of pathArgs) {
+      const path = resolve(target, arg);
+      if (!existsSync(path)) {
+        console.error(
+          `solid2-kit check — path not found: ${path} (drop deleted files from a changed-file list with \`git diff --name-only --diff-filter=d\`)`,
+        );
+        process.exit(2);
+      }
+      if (statSync(path).isDirectory()) {
+        walked = true;
+        files.push(...walk(path));
+      } else if (SOURCE_FILE.test(path)) {
+        files.push(path);
+      }
+    }
   } else {
     const srcDir = resolve(target, flagValue('--dir', 'src'));
     if (!existsSync(srcDir)) {
@@ -758,6 +899,22 @@ function check() {
       process.exit(2);
     }
     files = [...walk(srcDir)];
+    scanned = [relative(target, srcDir) || '.'];
+  }
+
+  // A walk that found no sources points at the wrong tree; passing it would
+  // read as a clean gate in CI and in agent loops. A list of named files with
+  // no sources among them (changed-file pipelines on a docs-only change) has
+  // nothing to gate and passes.
+  if (files.length === 0 && !walked) {
+    console.log('solid2-kit check — OK (no .ts/.tsx/.jsx sources among the named files; nothing to check).');
+    return;
+  }
+  if (files.length === 0) {
+    console.error(
+      `solid2-kit check — no .ts/.tsx/.jsx sources found in ${scanned.join(', ')}; nothing was checked. Point --dir or [paths...] at the source tree.`,
+    );
+    process.exit(2);
   }
 
   let findings = 0;
@@ -1063,6 +1220,40 @@ const BANNED_DEPS = {
   vinxi: 'SolidStart 1.x toolchain. Solid 2 uses @solidjs/vite-plugin directly.',
 };
 
+// Packages whose npm `latest` dist-tag is still the Solid 1.x line (solid-js
+// 1.9, @solidjs/router 1.0, @solidjs/meta 0.29, @tanstack/solid-router 1.x):
+// a bare `pnpm add <name>` installs it. The Solid 2 releases are published
+// under `next` (TanStack: `rc`, 2.0.0-rc.x).
+const SOLID2_LINE_PACKAGES = [
+  { name: 'solid-js', id: 'solid-js-version', solid1: /^[\s^~=v]*[01](?:\.|$)/, fix: 'Install solid-js@next (^2).' },
+  {
+    name: '@solidjs/router',
+    id: 'router-version',
+    solid1: /^[\s^~=v]*[01](?:\.|$)/,
+    fix: 'Router 1.x is JSX <Route> with a solid-js ^1 peer; install @solidjs/router@next (2.x, createRouter({ routes })).',
+  },
+  {
+    name: '@solidjs/meta',
+    id: 'meta-version',
+    solid1: /^[\s^~=v]*0(?:\.|$)/,
+    fix: 'Meta 0.x is built for Solid 1 (<MetaProvider> required); install @solidjs/meta@next (1.x).',
+  },
+  {
+    name: '@tanstack/solid-router',
+    id: 'tanstack-router-version',
+    solid1: /^[\s^~=v]*[01](?:\.|$)/,
+    fix: 'TanStack Router 1.x has a solid-js ^1.9 peer; install @tanstack/solid-router@rc (2.x, solid-js 2 peer).',
+  },
+];
+
+function installedVersion(target, name) {
+  try {
+    return JSON.parse(readFileSync(join(target, 'node_modules', name, 'package.json'), 'utf8')).version;
+  } catch {
+    return undefined;
+  }
+}
+
 const CONFIG_SOURCE = /\.(?:m|c)?[jt]s$/;
 
 // Files installed by this kit that carry a version marker. When the kit
@@ -1079,9 +1270,21 @@ 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}`);
   }
-  const solidRange = deps['solid-js'];
-  if (typeof solidRange === 'string' && /^[\s^~=v]*[01]\./.test(solidRange)) {
-    report('solid-js-version', `package.json pins solid-js "${solidRange}" — this kit teaches Solid 2.x; upgrade to ^2.`);
+  for (const { name, id, solid1, fix } of SOLID2_LINE_PACKAGES) {
+    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}`);
+      continue;
+    }
+    // A range such as "latest" or "*" only shows its line once resolved.
+    if (range === undefined) continue;
+    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}`,
+      );
+    }
   }
 
   for (const entry of readdirSync(target, { withFileTypes: true })) {
@@ -1183,7 +1386,7 @@ switch (command) {
         'Usage:',
         '  solid2-kit init  [--cursor] [--claude] [--no-hooks] [--target <dir>]  install/update guidance + edit hooks (default: both tools)',
         '  solid2-kit sync  [--cursor] [--claude] [--no-hooks] [--target <dir>]  alias of init (idempotent)',
-        '  solid2-kit check [--dir <srcdir>] [--target <dir>] [files...]         mechanical React/Solid 1.x pattern gate (default dir: src)',
+        '  solid2-kit check [--dir <srcdir>] [--target <dir>] [paths...]         mechanical React/Solid 1.x pattern gate (default dir: src)',
         '  solid2-kit doctor [--target <dir>]                                    project-wiring gate: deps, tsconfig, root configs',
         '  solid2-kit hook (claude|cursor)                                       edit-time gate for agent hooks (stdin: hook JSON payload)',
       ].join('\n'),

package/files/commands/solid2-review.md

@@ -26,10 +26,29 @@ Steps:
      `Promise<User>` props;
    - `latest(selectedId)` as the default highlight (hold is the default);
      `isPending` treated as a global spinner instead of a per-expression question;
-   - treating `<Errored>` as a terminal ErrorBoundary, or routing per-row mutation
-     failures through it (those belong in the action / a projection-folded map);
+   - treating `<Errored>` as a terminal ErrorBoundary, or expecting it to catch
+     mutation failures (an error thrown out of an `action` reverts the overlay and
+     rejects the call — catch it in the action / a projection-folded map, or `.catch`
+     the call in the handler);
+   - effect `apply` functions with expression bodies (`(t) => (document.title = t)`,
+     `(v) => setX(v)`) — any return value but a cleanup halts reactivity; `onCleanup`
+     inside `apply` (never runs) or inside `onSettled`, and memos/effects/`flush()`
+     inside an `onSettled` callback (all throw);
+   - writes to a store outside its setter (`todos.push(x)`, `todo.done = ...` — silently
+     ignored) and `Map`/`Set`/`Date` fields mutated in a draft (not tracked);
+   - app-wide state as a module-level signal/store instead of a provider at the root
+     of `App` (shared across SSR requests);
+   - value-form `createOptimisticStore([])` / `createOptimistic(v)` holding durable
+     data (writes vanish on settle) instead of the function form refreshed after `yield`;
+   - route `preload` returning data read as `props.data` (captured once per match)
+     instead of `void getX(params.id)` + `createMemo(() => getX(props.params.id))`;
+   - `throw redirect()` / `return reload()` in server functions called without Solid
+     Router `action`/`query` (the caller gets a raw `Response` or `null`, never its
+     data), and POST forms built on a bare function's `.url` (TS2339) instead of a
+     router `action`;
      error reporting done as a side effect inside `fallback` instead of
-     `configureClientErrors` / `configureServerErrors` / `render(..., { onError })`;
+     `configureClientErrors` / `configureServerErrors` / `render(fn, root, undefined, { onError })`
+     (options are `render`'s 4th argument — a 3rd-argument object is `init`);
    - store setter callbacks that `await` (the draft closes when the callback returns —
      `[ASYNC_STORE_SETTER]`), store setters called at component-body top level, and
      `latest()` used as a null-safe read of an unsettled source;

package/files/shared/agents-section.md

@@ -5,4 +5,4 @@
 - After editing TSX, run the `solid2-kit check` mechanical gate — it fails on React/Solid 1.x tokens and props destructuring. Use the project's `lint:solid` script if one exists; otherwise `npx solid2-agent-kit check` (with the kit as a devDependency) or `npx github:lightsound/solid2-agent-kit check`. An edit-time hook may also run this gate automatically after each file edit — treat its findings as errors to fix immediately, not warnings. Do not install `eslint-plugin-solid` (built for Solid 1.x; misreads Solid 2 idioms).
 - After editing `package.json`, `tsconfig*.json`, or root config files (Vite, ESLint), run `solid2-kit doctor` — it fails on React/Solid 1.x wiring: `react`/`vite-plugin-solid`/`eslint-plugin-solid`/SolidStart dependencies, 1.x `solid-js` ranges, and `jsx`/`jsxImportSource` values other than `preserve`/`@solidjs/web`.
 - The kit's guidance and gate files (`.cursor/rules/solid-2.mdc`, the `solid-2` skill directories, hook entries, managed blocks in this file and `CLAUDE.md`) are guardrails, not obstacles. Never edit, weaken, bypass, or delete them to make a failure go away — fix the flagged code. If a guardrail seems wrong, stop and tell the user.
-- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass async values as values (`user={user()}`) — JSX props are lazy; types stay `User`, not `Promise<User>`. `<Loading>` wraps the read, not the memo. Nested fetches run in parallel (components do not suspend). `isPending` is a per-expression question (`isPending(() => props.story)` / `isPending(selectedId)`), not a global spinner; `latest(selectedId)` is opt-in so highlight and content stay consistent by default. `<Errored>` heals when the source succeeds. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup`. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`. Types: `solid-js` exports no `JSX` namespace — children/return types are `Element` from `solid-js`; DOM `JSX` types come from `@solidjs/web`. Reset-a-signal-on-change is a writable derivation (`createSignal(() => { source(); return initial; })`), never an effect calling the setter. Client mode mounts with `render()` into an empty body — no hydration mismatch exists, so never defer initial values to post-mount React-style (that can overwrite persisted state). Client → server is additive (same setters + `action` + server functions): do not rewrite App with loading/error branches, disable optimistic rows until ack, invent tRPC, or refetch in `hydrate`/`onSettled`. The graph continues across the wire (`live()` owns the client connection; `<Reveal>` not a delayed stream). A server bundle uses `handleRequest` / Fetchable `fetch`; client-only start is static `dist/client`. One browser-only value takes `ssrSource` on the memo/signal/derived store (`client`/`hybrid`), not a `clientOnly` component split. Router link state is automatic (`aria-current`/`data-active`/`data-pending` + CSS; `useLinkState`/`useIsRouting` in JSX); search params via `useSearchParams`; router forms validate on the server (`throw respond({issues},{400})`) with inline errors from `useSubmissions`. Confirmations on another channel — fire-and-forget sends, and mutations whose result is read through `live()` — wait with `yield until(predicate, {timeout})`, not `refresh()`. Declare `live(GET(fn))` (`live()` outermost). Debounce at the handler; inputs feeding a request bind `latest(query)`. Dev diagnostics are errors: `[STRICT_READ_UNTRACKED]` means a read outside a tracking scope, `[ASYNC_STORE_SETTER]` means a store setter callback awaited (the draft is a synchronous transaction — await first, then write), and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`. Error monitoring is `configureClientErrors` / `configureServerErrors` (or `render(..., { onError })`), not a side effect inside `<Errored fallback>`; the server hook must return a reference or nothing, never the error itself. `<Dynamic>` is deprecated — use `dynamic()`. Observability is on by default in development: whenever a change touches stores, lists, async, actions, or effects, keep the dev console free of `[CODE]` findings and run an attribution session (`/__solid/diagnostics` `begin` → interact → `whyDidRun` / `costs` → `end` with `@solidjs/diagnostics` installed, otherwise `isDev`-guarded `attribution.enable({ log: false })` + `why()` / `costs()`) before finishing. `vite dev` is always the dev build; `solid({ observe: true })` is a production opt-in.
+- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass async values as values (`user={user()}`) — JSX props are lazy; types stay `User`, not `Promise<User>`. `<Loading>` wraps the read, not the memo. Nested fetches run in parallel (components do not suspend). `isPending` is a per-expression question (`isPending(() => props.story)` / `isPending(selectedId)`), not a global spinner; `latest(selectedId)` is opt-in so highlight and content stay consistent by default. `<Errored>` heals when the source succeeds. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup` — return the cleanup; `onCleanup`, memo/effect creation, and `flush()` throw inside the `onSettled` callback in dev. Effect `apply` functions use block bodies (`(t) => { document.title = t; }`): any return value other than a cleanup function halts reactivity. Stores are written only through the setter's draft — writes to the store itself are silently ignored, and `Map`/`Set`/`Date` inside a store are not tracked. Shared state, app-wide included, is created in a provider at the root of `App` (`createContext<T>()` + `useX()`), never a module-level signal/store (one instance serves every SSR request). Errors thrown out of an `action` never reach `<Errored>` — catch them in the action or `.catch` the call. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`. Types: `solid-js` exports no `JSX` namespace — markup types are `JSX.Element` from `@solidjs/web` or `Element` from `solid-js` (alias it `SolidElement` next to DOM code). Reset-a-signal-on-change is a writable derivation (`createSignal(() => { source(); return initial; })`), never an effect calling the setter. Client mode mounts with `render()` into an empty body — no hydration mismatch exists, so never defer initial values to post-mount React-style (that can overwrite persisted state). Client → server is additive (same setters + `action` + server functions): do not rewrite App with loading/error branches, disable optimistic rows until ack, invent tRPC, or refetch in `hydrate`/`onSettled`. The graph continues across the wire (`live()` owns the client connection; `<Reveal>` not a delayed stream). A server bundle uses `handleRequest` / Fetchable `fetch`; client-only start is static `dist/client`. One browser-only value takes `ssrSource` on the memo/signal/derived store (`client`/`hybrid`), not a `clientOnly` component split. Router link state is automatic (`aria-current`/`data-active`/`data-pending` + CSS; `useLinkState`/`useIsRouting` in JSX); search params via `useSearchParams`; router forms validate on the server (`throw respond({issues},{400})`) with inline errors from `useSubmissions`. Confirmations on another channel — fire-and-forget sends, and mutations whose result is read through `live()` — wait with `yield until(predicate, {timeout})`, not `refresh()`. Declare `live(GET(fn))` (`live()` outermost). Debounce at the handler; inputs feeding a request bind `latest(query)`. Dev diagnostics are errors: `[STRICT_READ_UNTRACKED]` means a read outside a tracking scope, `[ASYNC_STORE_SETTER]` means a store setter callback awaited (the draft is a synchronous transaction — await first, then write), and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`. Error monitoring is `configureClientErrors` / `configureServerErrors` (or per root `render(fn, root, undefined, { onError })` — options are the 4th argument), not a side effect inside `<Errored fallback>`; the server hook must return a reference or nothing, never the error itself. `<Dynamic>` is deprecated — use `dynamic()`. Observability is on by default in development: whenever a change touches stores, lists, async, actions, or effects, keep the dev console free of `[CODE]` findings and run an attribution session (`/__solid/diagnostics` `begin` → interact → `whyDidRun` / `costs` → `end` with `@solidjs/diagnostics` installed, otherwise `isDev`-guarded `attribution.enable({ log: false })` + `why()` / `costs()`) before finishing. `vite dev` is always the dev build; `solid({ observe: true })` is a production opt-in.