create-what 0.6.0 → 0.7.0

package/index.js

@@ -128,6 +128,7 @@ function generatePackageJson(projectName, { reactCompat, cssApproach }) {
   const devDeps = {
     vite: '^6.0.0',
     'what-compiler': '^0.6.0',
+    'what-devtools-mcp': '^0.6.0',
     '@babel/core': '^7.23.0',
   };
 
@@ -181,6 +182,10 @@ function generateViteConfig({ reactCompat, cssApproach }) {
     plugins.push('what()');
   }
 
+  // MCP DevTools — auto-injects devtools client in dev mode for AI agent debugging
+  imports.push(`import whatDevTools from 'what-devtools-mcp/vite-plugin';`);
+  plugins.push('whatDevTools()');
+
   if (cssApproach === 'tailwind') {
     imports.push(`import tailwindcss from '@tailwindcss/vite';`);
     plugins.push('tailwindcss()');
@@ -841,9 +846,220 @@ async function main() {
 
   mkdirSync(join(root, 'src'), { recursive: true });
   mkdirSync(join(root, 'public'), { recursive: true });
-  // MCP config dirs — created but left empty until what-devtools-mcp is published
-  // mkdirSync(join(root, '.claude'), { recursive: true });
-  // mkdirSync(join(root, '.cursor'), { recursive: true });
+  // MCP DevTools config — lets AI agents (Claude Code, Cursor, etc.) connect to the running app
+  writeFileSync(join(root, '.mcp.json'), JSON.stringify({
+    mcpServers: {
+      'what-devtools-mcp': {
+        command: 'npx',
+        args: ['what-devtools-mcp'],
+      },
+    },
+  }, null, 2) + '\n');
+
+  // CLAUDE.md — agent instructions for Claude Code (also useful for other AI tools)
+  writeFileSync(join(root, 'CLAUDE.md'), `# ${projectName}
+
+Built with What Framework — signal-based reactivity, components run once.
+
+## Writing Code
+
+\`\`\`js
+import { signal, effect, computed, batch, onMount, h, mount } from 'what-framework';
+
+const count = signal(0, 'count');  // state
+count()           // read
+count(5)          // write
+count(c => c + 1) // update
+
+const doubled = computed(() => count() * 2);  // derived
+effect(() => console.log(count()));           // side effect
+\`\`\`
+
+Components run ONCE. Use \`signal()\` for state, \`() =>\` in JSX for reactive text.
+
+**Signal scope:** \`signal()\` works anywhere — module scope (shared state), component scope (local state). Components run once, so signal declarations execute exactly once.
+
+## MCP DevTools
+
+This project includes MCP devtools that connect to the running app in the browser.
+
+### Quick Start (First 5 Minutes)
+
+1. \`what_connection_status\` — am I connected? how big is the app?
+2. \`what_diagnose\` — any errors or issues?
+3. \`what_page_map\` — what's on the page?
+4. \`what_components\` -> \`what_explain\` on a leaf component — deep dive
+5. \`what_signals({filter: "name", named_only: true})\` — check key state
+
+### Decision Tree
+
+| I want to... | Use this |
+|---|---|
+| Get oriented / check connection | \`what_connection_status\` |
+| Health check (errors + perf + reactivity) | \`what_diagnose\` |
+| Find a component by name | \`what_components {filter}\` |
+| Understand one component deeply | \`what_explain {componentId}\` |
+| See the component hierarchy | \`what_component_tree\` |
+| Check a signal's current value | \`what_signals {filter, named_only: true}\` |
+| See all effects and their run counts | \`what_effects {minRunCount}\` |
+| Understand why a signal changed | \`what_signal_trace {signalId}\` |
+| See what depends on a signal | \`what_dependency_graph {signalId, direction: "downstream"}\` |
+| See what an effect depends on | \`what_dependency_graph {effectId, direction: "upstream"}\` |
+| Find runtime errors | \`what_errors\` |
+| Get component layout/styles (no image) | \`what_look {componentId}\` |
+| Get full page structure | \`what_page_map\` |
+| Get a visual screenshot | \`what_screenshot {componentId}\` (use after what_look) |
+| Inspect raw DOM | \`what_dom_inspect {componentId, depth}\` |
+| Find performance issues | \`what_perf {threshold}\` |
+| Compare before/after state | \`what_diff_snapshot {action: "save"}\` then \`{action: "diff"}\` |
+| Change a signal live | \`what_set_signal {signalId, value}\` |
+| Validate code before saving | \`what_lint {code}\` |
+| Generate boilerplate | \`what_scaffold {type, name}\` |
+| Diagnose an error code | \`what_fix {errorCode}\` |
+
+### Workflows
+
+**Find and inspect a component:**
+\`what_components({filter:"Stats"})\` -> get ID -> \`what_explain({componentId: 4})\`
+
+**Debug a signal's reactive graph:**
+\`what_signals({filter:"count"})\` -> get ID -> \`what_dependency_graph({signalId: 1, direction: "downstream"})\`
+
+**Before/after comparison:**
+\`what_diff_snapshot({action:"save"})\` -> make change -> \`what_diff_snapshot({action:"diff"})\`
+
+**Performance audit:**
+\`what_perf({threshold: 3})\` -> \`what_effects({minRunCount: 2})\` -> \`what_dependency_graph({effectId: N})\`
+
+**Visual/layout audit:**
+\`what_page_map\` -> \`what_look({componentId: N})\` on key components -> \`what_screenshot\` only if needed
+
+**Disconnected reactivity (UI parts that should update together but don't):**
+\`what_dependency_graph({signalId: N, direction: "downstream"})\` -> check ALL expected effects appear. Missing edges = component won't react to that signal.
+
+**Multi-signal interaction (order-of-operations bugs):**
+\`what_diff_snapshot(save)\` -> set signal A -> \`diff\` -> save -> set signal B -> \`diff\`. Compare cascades.
+
+**Build & test new features:**
+\`what_look\` to match styling -> \`what_scaffold\` for structure -> write code -> \`what_lint\` -> \`what_diff_snapshot(save)\` -> \`what_set_signal\` to simulate trigger -> \`what_diff_snapshot(diff)\` to verify cascade.
+
+**Stale subscription (effect should fire but doesn't):**
+If dep graph shows an edge but diff shows 0 re-runs, the effect lost its subscription during a remount. Fix: move effect to module scope or use \`computed()\`.
+
+### Understanding Diagnostics
+
+- **"N signals with no subscribers"** — Normal. Signals in \`() => ...\` reactive text bindings (\`<!--fn-->\` in DOM) update the DOM directly, bypassing tracked effects. Only investigate if a signal should trigger an effect but isn't.
+- **"N effects with no signal dependencies"** — Normal. One-shot setup effects that run once during component creation (DOM init, event listeners). Expected in "components run once" model.
+- **Components with signalCount=0** — Module-scope signals (shared stores) don't appear on any component. Use \`what_signals\` directly.
+- **\`<!--fn-->\` in DOM** — Reactive text binding markers. The primary reactivity mechanism in templates.
+
+### Key Parameters
+
+| Param | Type | Notes |
+|---|---|---|
+| \`what_signals\` \`named_only\` | boolean | \`true\`/\`false\`, not a string |
+| \`what_effects\` \`minRunCount\` | number | Filter effects that ran >= N times |
+| \`what_dependency_graph\` \`direction\` | \`"upstream"\` \`"downstream"\` \`"both"\` | Default: both |
+| \`what_dom_inspect\` \`depth\` | number | DOM traversal depth (default: 3) |
+| \`what_perf\` \`threshold\` | number | Flag effects with >= N subscribers |
+
+### Efficiency
+
+**Parallel-safe (batch these):** \`what_perf\`, \`what_effects\`, \`what_signals\`, \`what_components\`, \`what_dependency_graph\`, \`what_explain\`, \`what_look\`, \`what_page_map\`, \`what_diagnose\`, \`what_lint\`, \`what_scaffold\`. NOT safe to parallelize: \`what_set_signal\` calls on signals that share effects.
+
+**Diff output:** \`effectsTriggered\` = re-ran. \`effectsAdded\` = new mounts. \`effectsRemoved\` = unmounts. \`what_perf\` includes \`largestSubscribers\` — skip \`what_signals\` if you only need hot signals.
+
+### Principles
+1. \`what_connection_status\` first — always orient before diving in
+2. \`what_explain\` over individual calls — replaces separate signals + effects + DOM lookups
+3. \`what_look\` before \`what_screenshot\` — 10x cheaper, usually sufficient
+4. \`what_signals\` with \`filter\` and \`named_only: true\` — never dump unfiltered
+5. \`what_lint\` before saving generated code
+6. Text tools before visual tools — orient with data, then confirm visually
+7. Re-fetch component IDs after state changes — IDs are ephemeral after mount/unmount cycles
+8. \`what_set_signal\` can cascade — use \`what_diff_snapshot\` to see full impact
+
+### Troubleshooting
+- **Not connected:** Open the app in a browser, wait 2-3s, retry. \`what_lint\`/\`what_scaffold\`/\`what_fix\` work offline.
+- **"Component N not found":** Re-fetch IDs with \`what_components\` after signal changes that alter the component tree.
+- **Screenshot fails:** Use \`what_look\` instead (usually sufficient without an image).
+- **\`what_lint\` false positive on \`signal-write-in-render\`:** Both named handlers and inline \`onClick={() => sig(val)}\` trigger this. Safe to ignore if signal write is inside an event handler. Re-run with \`rules\` excluding that rule to confirm.
+`);
+
+  // AGENTS.md — model-agnostic instructions for OpenCode, Codex, Gemini, Cursor, etc.
+  writeFileSync(join(root, 'AGENTS.md'), `# ${projectName} — Agent Instructions
+
+> Model-agnostic guide for AI agents using MCP DevTools with What Framework.
+
+## Framework Basics
+
+Signal-based reactivity. Components run **once**. \`signal()\` for state, \`() =>\` in JSX for reactive text.
+
+\`\`\`js
+import { signal, effect, computed, h, mount } from 'what-framework';
+const count = signal(0, 'count');
+count()           // read
+count(5)          // write
+count(c => c + 1) // update
+\`\`\`
+
+## MCP DevTools
+
+**Always start:** \`what_connection_status\` — returns app info, tool list, next steps.
+
+### Pick the Right Tool
+
+| Goal | Tool | Key params |
+|------|------|------------|
+| Orient / check connection | \`what_connection_status\` | none |
+| Health check | \`what_diagnose\` | none |
+| Find a component | \`what_components\` | \`filter\` (regex string) |
+| Deep-dive one component | \`what_explain\` | \`componentId\` (number) |
+| Check signal values | \`what_signals\` | \`filter\` (string), \`named_only\` (boolean) |
+| See effect run counts | \`what_effects\` | \`minRunCount\` (number) |
+| Signal dependency graph | \`what_dependency_graph\` | \`signalId\`/\`effectId\` (number), \`direction\` |
+| Page layout | \`what_page_map\` | none |
+| Component styling | \`what_look\` | \`componentId\` (number) |
+| Performance issues | \`what_perf\` | \`threshold\` (number) |
+| Before/after state | \`what_diff_snapshot\` | \`action\`: \`"save"\` then \`"diff"\` |
+| Change a signal | \`what_set_signal\` | \`signalId\` (number), \`value\` (any) |
+| Validate code | \`what_lint\` | \`code\` (string) |
+| Generate boilerplate | \`what_scaffold\` | \`type\`, \`name\` (strings) |
+
+### Recipes
+
+**Find component:** \`what_components({filter:"Name"})\` -> \`what_explain({componentId: N})\`
+**Debug signal:** \`what_signals({filter:"name"})\` -> \`what_dependency_graph({signalId: N, direction: "downstream"})\`
+**Before/after:** \`what_diff_snapshot({action:"save"})\` -> change -> \`what_diff_snapshot({action:"diff"})\`
+**Build feature:** \`what_look\` (match styling) -> \`what_scaffold\` -> write code -> \`what_lint\` -> \`what_diff_snapshot\` (save/set/diff)
+
+### Parameter Types (common mistakes)
+
+| Param | Correct | Wrong |
+|-------|---------|-------|
+| \`named_only\` | \`true\` (boolean) | \`"true"\` (string) |
+| \`componentId\` | \`4\` (number) | \`"4"\` (string) |
+| \`direction\` | \`"downstream"\` | \`downstream\` |
+
+### Pitfalls
+
+- **Not connected:** Open app in browser, wait 3s, retry
+- **Component IDs change** after signal mutations — re-fetch with \`what_components\`
+- **\`what_lint\` FP on \`signal-write-in-render\`:** Handlers in event callbacks are safe
+- **\`what_set_signal\` cascades:** Use \`what_diff_snapshot\` to see full impact
+- **"N signals with no subscribers":** Normal — reactive text bindings bypass tracked effects
+`);
+
+  // Also generate a .cursor/mcp.json for Cursor users
+  mkdirSync(join(root, '.cursor'), { recursive: true });
+  writeFileSync(join(root, '.cursor', 'mcp.json'), JSON.stringify({
+    mcpServers: {
+      'what-devtools-mcp': {
+        command: 'npx',
+        args: ['what-devtools-mcp'],
+      },
+    },
+  }, null, 2) + '\n');
 
   // .gitignore
   writeFileSync(join(root, '.gitignore'), `node_modules\ndist\n.DS_Store\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-what",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Scaffold a new What Framework project",
   "type": "module",
   "bin": {