solid2-agent-kit 0.7.0 → 0.8.0

package/README.md

@@ -16,7 +16,7 @@ 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), and `<Dynamic>` (use `dynamic()`) |
+| 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`), and two-phase effects whose apply only writes a local signal (use a writable derivation) |
 | 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` |

package/bin/solid2-kit.mjs

@@ -274,6 +274,86 @@ function init() {
 
 // --- check ------------------------------------------------------------------
 
+// Balanced-scan helpers for the effect-sync check: regexes cannot pair the
+// parentheses of a createEffect(...) call, so scan (string-aware; comments
+// are already stripped) for the matching closer from an opening bracket.
+function scanBalanced(content, openIndex) {
+  let depth = 0;
+  let quote = null;
+  for (let i = openIndex; i < content.length; i += 1) {
+    const ch = content[i];
+    if (quote !== null) {
+      if (ch === '\\') i += 1;
+      else if (ch === quote) quote = null;
+    } else if (ch === "'" || ch === '"' || ch === '`') {
+      quote = ch;
+    } else if (ch === '(' || ch === '{' || ch === '[') {
+      depth += 1;
+    } else if (ch === ')' || ch === '}' || ch === ']') {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function splitTopLevelArgs(argsText) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let start = 0;
+  for (let i = 0; i < argsText.length; i += 1) {
+    const ch = argsText[i];
+    if (quote !== null) {
+      if (ch === '\\') i += 1;
+      else if (ch === quote) quote = null;
+    } else if (ch === "'" || ch === '"' || ch === '`') {
+      quote = ch;
+    } else if (ch === '(' || ch === '{' || ch === '[') {
+      depth += 1;
+    } else if (ch === ')' || ch === '}' || ch === ']') {
+      depth -= 1;
+    } else if (ch === ',' && depth === 0) {
+      parts.push(argsText.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(argsText.slice(start));
+  return parts;
+}
+
+// An apply phase that is nothing but one (optionally if-guarded) call to a
+// local signal setter is "a signal plus an effect that syncs it" — rule 4.
+// Restricting to setters declared via createSignal destructuring in the same
+// file keeps external set* functions (setDefaultOptions, setTimeout) out.
+function soleLocalSetterApply(apply, localSetters) {
+  const head = apply.match(
+    /^(?:async\s*)?(?:\([^()]*\)|[\w$]+)\s*=>\s*\{?\s*(?:if\s*\((?:[^()]|\([^()]*\))*\)\s*\{?\s*)?(set[A-Z][\w$]*)\s*\(/,
+  );
+  if (!head || !localSetters.has(head[1])) return false;
+  const close = scanBalanced(apply, head[0].length - 1);
+  if (close === -1) return false;
+  return /^[\s;}]*$/.test(apply.slice(close + 1));
+}
+
+const LOCAL_SETTER_DECL = /\[\s*[\w$]+\s*,\s*(set[A-Z][\w$]*)\s*\]\s*=\s*createSignal\b/g;
+
+function effectSyncFindings(content) {
+  const localSetters = new Set([...content.matchAll(LOCAL_SETTER_DECL)].map((m) => m[1]));
+  if (localSetters.size === 0) return [];
+  const matches = [];
+  for (const call of content.matchAll(/\bcreateEffect\s*(?:<[^>()]*>)?\s*\(/g)) {
+    const open = call.index + call[0].length - 1;
+    const close = scanBalanced(content, open);
+    if (close === -1) continue;
+    const args = splitTopLevelArgs(content.slice(open + 1, close));
+    if (args.length >= 2 && soleLocalSetterApply(args[1].trim(), localSetters)) {
+      matches.push({ index: call.index });
+    }
+  }
+  return matches;
+}
+
 const CHECKS = [
   {
     id: 'props-destructure-param',
@@ -298,6 +378,20 @@ const CHECKS = [
     message:
       'Solid 1.x import path. Stores/merge/omit come from "solid-js"; render/hydrate/Portal/Dynamic come from "@solidjs/web".',
   },
+  {
+    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".',
+  },
+  {
+    // A two-phase createEffect whose apply is nothing but one (optionally
+    // if-guarded) call to a setter declared via createSignal in this file.
+    id: 'effect-sync-signal',
+    find: effectSyncFindings,
+    message:
+      'Effect that only syncs a local signal — "state + effect" (rule 4). Derive the value instead; to reset state when another reactive value changes, use a writable derivation: createSignal(() => { source(); return initial; }).',
+  },
   {
     id: 'react-jsx-prop',
     pattern: /\b(?:className|htmlFor)=/g,
@@ -572,7 +666,7 @@ function fileFindings(file, relativeTo) {
   const lines = raw.split('\n');
   const findings = [];
   for (const rule of CHECKS) {
-    for (const match of content.matchAll(rule.pattern)) {
+    for (const match of rule.find ? rule.find(content) : content.matchAll(rule.pattern)) {
       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()}`,

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 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`.
+- 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 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).

package/files/shared/rules-body.md

@@ -25,7 +25,13 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
    (the function itself) into JSX and call it there.
 3. Signals are read by **calling** them: `{count()}` in JSX, not `{count}`.
 4. **Derived state is a function, not state + effect.** `const full = () => a() + b()`.
-   Never write "a signal plus an effect that syncs it". Use `createMemo` only for expensive
+   Never write "a signal plus an effect that syncs it". That includes **reset**: to clear
+   a signal when another reactive value changes, use a writable derivation —
+   `createSignal(() => { source(); return initial; })` (re-runs when `source()` changes;
+   the setter still works) — never a `createEffect` whose apply calls the setter. The
+   derivation also moves the `source()` read to the read site, under its boundaries.
+   Mechanically enforced by `solid2-kit check` (effects whose apply only writes a local
+   signal). Use `createMemo` only for expensive
    computations, multiple consumers, or an equality boundary. When several writes can land
    before a flush, use the setter updater (`setCount((c) => c + 1)`); `setCount(count() + 1)`
    reads the last *committed* value and drops the other staged writes. To store a *function*
@@ -175,7 +181,12 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     visible content — `clientOnly` is for components that must never run on the server.
     Pass a **function** to `render` / `hydrate` / `renderToString` / `renderToStream`
     (`render(() => <App />, root)`), never `render(<App />, root)`. `hydrate` when the
-    container already holds SSR HTML; `render` for an empty mount. `renderToString`
+    container already holds SSR HTML; `render` for an empty mount. Client mode (the
+    `@solidjs/vite-plugin` default) mounts with `render()` into an empty body — there is
+    **no server HTML and no hydration mismatch**, so React's mismatch defenses
+    ("server-safe" initial values adopted after mount, two-pass rendering) are unnecessary
+    and can clobber persisted state; read `localStorage` / `matchMedia` directly when
+    creating the signal. `renderToString`
     emits `<Loading>` fallbacks; async or lazy-route trees need
     `await renderToStream(() => <App />)` (one consumer: `pipe` / `pipeTo` / `readable`).
     When the app owns the document, emit `<HydrationScript />` once before app markup;
@@ -256,6 +267,7 @@ directory (default `src/`).
 | Never write (Solid 1.x) | Write instead (Solid 2) |
 |---|---|
 | `import ... from "solid-js/store"` or `"solid-js/web"` | stores/`merge`/`omit` from `"solid-js"`; `render`/`hydrate`/`Portal`/`Dynamic` from `"@solidjs/web"` |
+| `import type { JSX } from "solid-js"` / `JSX.Element` as the children type | `solid-js` exports no `JSX` namespace: children/returns are `Element` from `"solid-js"`; DOM-specific `JSX` types (`JSX.IntrinsicElements`, `JSX.CSSProperties`) from `"@solidjs/web"` |
 | `createResource` | async `createMemo` + `<Loading>`/`<Errored>`; `refresh()`, `latest()`, `isPending()` |
 | `createEffect(fn)` (one arg), `on(...)` | `createEffect(compute, apply)`; deps belong in `compute` |
 | `onMount` | `onSettled` (return cleanup from its callback) |

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

@@ -55,6 +55,7 @@ Most React `useEffect` code should NOT become `createEffect`:
 | Fetch data in an effect, copy into state | `createMemo(async () => ...)` + `<Loading>` |
 | React to a user interaction | do the work in the event handler or an `action` |
 | Sync one state into another | delete the second state; derive it |
+| Reset/clear state when another reactive value changes | writable derivation: `createSignal(() => { source(); return initial; })` — not an effect calling the setter |
 | Push a settled reactive value into a non-Solid system (DOM API, third-party widget, analytics, subscription) | `createEffect(compute, apply)` — this is the only real use |
 | One-time setup after mount (`onMount`) | `onSettled(() => { ...; return cleanup })` |
 | Measure DOM / observe size after paint | ref **directive factory** + `onSettled` (writes a *new* input; not an effect that copies state) |
@@ -222,6 +223,28 @@ Reads inside `apply` do not track. Extract every needed reactive value in `compu
 and reading `user.name` there *runs once* and never retriggers. Compute-phase errors can be
 intercepted with the bundle form `createEffect(compute, { effect, error })`.
 
+A two-phase effect whose apply only calls a local signal setter is "state + effect" in
+disguise — formally legal Solid 2, still rule 4 (`solid2-kit check` flags it). The reset
+form of a writable derivation replaces it, and moves the source read to the read site
+(under that site's boundaries) instead of an effect compute:
+
+```tsx
+// WRONG — signal synced by an effect; organizer() errors bypass the read site's <Errored>
+const [signInError, setSignInError] = createSignal<string | null>(null);
+createEffect(
+  () => organizer(),
+  (id) => {
+    if (id !== null) setSignInError(null);
+  },
+);
+
+// CORRECT — writable derivation: resets when organizer() changes; the setter still works
+const [signInError, setSignInError] = createSignal<string | null>(() => {
+  organizer();
+  return null;
+});
+```
+
 ### Async data
 
 ```tsx
@@ -533,6 +556,20 @@ To turn those dev diagnostics into a hard gate, patch `console.warn` in the test
 file to rethrow unexpected warnings — then any top-level reactive read or unowned write
 an agent sneaks in fails the suite instead of scrolling by.
 
+## Client mode: no server HTML, no hydration reflexes
+
+The `@solidjs/vite-plugin` default (client mode, the `bare` tier) serves an empty-body
+shell and mounts with `render()`. Nothing is server-rendered and nothing hydrates, so
+**React's hydration-mismatch playbook does not transfer**: do not start signals with a
+"server-safe" initial value and adopt `localStorage` / `matchMedia` after mount, do not
+two-pass render, and there is no `suppressHydrationWarning`. Read client sources directly
+when creating state — `createSignal(storedPreference())` is correct in client mode. A
+deferred "safe" initial value is worse than unnecessary: if anything persists the value
+(an effect writing `localStorage`), the placeholder **overwrites the user's stored
+preference** before the real value is adopted. Mismatch only becomes a concept in
+start/SSR mode, where `hydrate()` mounts onto server HTML — and the Solid answer there is
+`isServer` / `clientOnly`, still not React-style deferred adoption.
+
 ## App stack (only if the project has these packages)
 
 This kit's always-applied rules cover `solid-js` + `@solidjs/web` TSX. Official
@@ -547,8 +584,12 @@ Solid Router 0.x/1.x stand-ins.** Patterns below; fetch the matching pages from
 { "compilerOptions": { "jsx": "preserve", "jsxImportSource": "@solidjs/web" } }
 ```
 
-Import DOM `JSX` types from `@solidjs/web`; renderer-neutral `Component` /
-`ParentProps` from `solid-js`. Vite: `import solid from "@solidjs/vite-plugin"`
+`solid-js` does **not** export a `JSX` namespace — `import type { JSX } from "solid-js"`
+is a type error (TS2305), and `JSX.Element` as the children type is a React reflex.
+Children/return types are the renderer-neutral `Element` from `solid-js`
+(`children?: Element`), alongside `Component` / `ParentProps` / `Accessor` / `Setter`.
+DOM-specific `JSX` types (`JSX.IntrinsicElements`, `JSX.CSSProperties`) and
+`ComponentProps` come from `@solidjs/web`. Vite: `import solid from "@solidjs/vite-plugin"`
 with `start: true` / `ssr: true` / `serverFunctions: true` only when the
 project already uses start mode. Tiers are `bare` → `basic` (router) →
 `fullstack` (SSR + server functions); do not jump a tier without cause.
@@ -794,6 +835,8 @@ how to reuse. Prefer the form on the right.
 | `createMemo(() => { void save(); return x(); })` / an effect that calls an action | invoke actions from handlers, not from memos or effects |
 | `createSignal(props.value)` / `createStore(props.items)` | `createSignal(() => props.value)` / `createStore(() => props.items, fallback)` — a bare `props.x` at setup is a snapshot |
 | `createRenderEffect` / `createTrackedEffect` as the default effect | two-phase `createEffect(compute, apply)` |
+| `createEffect(() => source(), () => setError(null))` to reset a signal | `createSignal(() => { source(); return null; })` — the writable derivation resets on change; a sole-setter apply is rule 4 |
+| a "server-safe" initial value adopted after mount (React hydration-mismatch fix) | client mode mounts with `render()` into an empty body — no hydration, no mismatch; read `localStorage` / `matchMedia` directly at signal creation |
 
 ```tsx
 // WRONG — post-await read never subscribes; production can hang pending
@@ -913,7 +956,9 @@ always-applied rules installed alongside this skill.
 - [ ] No props destructuring; no `props.` at component-body top level.
 - [ ] Every reactive read (`signal()`, `props.x`, `store.x`) sits in JSX, a memo, an effect
       compute, or a boundary — not the component body.
-- [ ] No signal-synced-by-effect; derived values are functions or memos.
+- [ ] No signal-synced-by-effect; derived values are functions or memos. Reset-on-change
+      is a writable derivation (`createSignal(() => { source(); return initial; })`), not
+      an effect calling the setter.
 - [ ] Event handlers wrap setters (`onClick={() => setX(...)}`), use `currentTarget`,
       and `onInput` for keystrokes. `innerHTML` is sanitized and not mixed with children.
 - [ ] Async memos are passed as accessors (`user={user}`), not `user={user()}`, so
@@ -933,6 +978,8 @@ always-applied rules installed alongside this skill.
 - [ ] Rest props via `omit`, not `{ ...props }`. Conditional `class` via objects, not string concat.
 - [ ] Input filters write back to the DOM on reject (inputs do not rewind).
 - [ ] No Solid 1.x imports or APIs (`solid-js/store`, `createResource`, `onMount`, `Suspense`, ...).
+      No `JSX` imported from `solid-js` — children/return types are `Element` from
+      `solid-js`; DOM `JSX` types come from `@solidjs/web`.
 - [ ] Inspect children with `children()`; code-split with `lazy` + `<Loading>`; reactive
       component choice with `dynamic()`. No `React.lazy`, no effects inside ref callbacks.
 - [ ] Browser-only code uses `isServer` / `clientOnly`, not `typeof window`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid2-agent-kit",
-  "version": "0.7.0",
+  "version": "0.8.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",