what-devtools-mcp 0.6.0 → 0.7.0

package/src/client.js

@@ -21,7 +21,7 @@ function logGrouped(badge, badgeStyle, title, data) {
   console.groupEnd();
 }
 
-export function connectDevToolsMCP({ port = 9229 } = {}) {
+export function connectDevToolsMCP({ port = 9229, token = '' } = {}) {
   // Never connect in production
   if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') {
     return { disconnect() {}, isConnected: false, eventCount: 0 };
@@ -42,19 +42,46 @@ export function connectDevToolsMCP({ port = 9229 } = {}) {
   let hasLoggedDisconnect = false;
   let reconnectAttempts = 0;
   let unsubscribeFn = null;
+  let flushEventBatch = null; // Hoisted — set during subscription, called by set-signal
+  let discoveredToken = token;
+  let discoveredPort = port;
 
   // Startup banner
   console.log(
-    '%c⚡ What DevTools MCP %c Client v0.1.0',
+    '%c⚡ What DevTools MCP %c Client v0.2.0',
     'background:linear-gradient(135deg,#6366f1,#a855f7);color:#fff;padding:4px 10px;border-radius:4px;font-weight:bold;font-size:13px',
     'color:#a855f7;font-weight:bold'
   );
+
+  // --- Token Auto-Discovery ---
+  // If no token is provided, try to discover it from the bridge's HTTP endpoint.
+  // The bridge serves GET http://localhost:{port+1}/__what_mcp_token
+  async function discoverToken() {
+    if (discoveredToken) return true; // Already have a token
+
+    const discoveryPort = port + 1;
+    try {
+      const res = await fetch(`http://localhost:${discoveryPort}/__what_mcp_token`);
+      if (res.ok) {
+        const data = await res.json();
+        discoveredToken = data.token;
+        discoveredPort = data.wsPort || port;
+        log('MCP', BADGE, `Token discovered automatically from bridge`);
+        return true;
+      }
+    } catch {
+      // Discovery endpoint not available — bridge may not be running yet
+    }
+    return false;
+  }
+
   log('MCP', BADGE, `Connecting to bridge on ws://localhost:${port}`);
 
   function connect() {
     reconnectAttempts++;
     try {
-      ws = new WebSocket(`ws://localhost:${port}`);
+      const tokenParam = discoveredToken ? `?token=${encodeURIComponent(discoveredToken)}` : '';
+      ws = new WebSocket(`ws://localhost:${discoveredPort}${tokenParam}`);
     } catch {
       if (reconnectAttempts <= 1) {
         log('MCP', BADGE_WARN, 'Bridge not available — retrying silently in background');
@@ -91,18 +118,18 @@ export function connectDevToolsMCP({ port = 9229 } = {}) {
         let eventBatch = [];
         let batchTimer = null;
 
-        function flushEventBatch() {
+        // Hoisted so set-signal can call it to flush after programmatic writes
+        flushEventBatch = function() {
           if (eventBatch.length === 0) return;
           if (eventBatch.length === 1) {
-            // Single event — send normally for compatibility
             const item = eventBatch[0];
             send({ type: 'event', event: item.event, data: item.data });
           } else {
             send({ type: 'events', batch: eventBatch });
           }
           eventBatch = [];
-          batchTimer = null;
-        }
+          if (batchTimer) { clearTimeout(batchTimer); batchTimer = null; }
+        };
 
         unsubscribeFn = devtools.subscribe((event, data) => {
           eventCount++;
@@ -187,6 +214,8 @@ export function connectDevToolsMCP({ port = 9229 } = {}) {
           if (entry) {
             const prev = entry.ref.peek();
             entry.ref(value);
+            // Flush event batch immediately so what_watch captures programmatic writes
+            if (flushEventBatch) setTimeout(flushEventBatch, 0);
             result = { previous: devtools.safeSerialize(prev), current: devtools.safeSerialize(value) };
             log('AI →', BADGE_CMD, `${label} — signal #${signalId} "${entry.name}": ${JSON.stringify(prev)} → ${JSON.stringify(value)}`);
           } else {
@@ -221,9 +250,17 @@ export function connectDevToolsMCP({ port = 9229 } = {}) {
         // Try extended command handlers
         let extResult = null;
         try {
-          const { handleExtendedCommand } = await import('./client-commands.js');
-          extResult = handleExtendedCommand(command, args, devtools);
-        } catch {}
+          const { handleExtendedCommand, initEventTracking } = await import('./client-commands.js');
+          // Auto-initialize event tracking on first extended command so
+          // what_signal_trace always has write history (not just after what_watch)
+          initEventTracking(devtools);
+          extResult = await handleExtendedCommand(command, args, devtools);
+        } catch (importErr) {
+          // Don't silently swallow — report the real error so it's not
+          // misdiagnosed as "Unknown command"
+          extResult = { error: `Command handler failed: ${importErr.message}` };
+          log('AI →', BADGE_WARN, `Extended command "${command}" threw:`, importErr);
+        }
 
         if (extResult !== null) {
           result = extResult;
@@ -248,9 +285,12 @@ export function connectDevToolsMCP({ port = 9229 } = {}) {
       hasLoggedDisconnect = true;
     }
     const delay = reconnectAttempts >= 5 ? MAX_RECONNECT_DELAY : reconnectDelay;
-    reconnectTimer = setTimeout(() => {
+    reconnectTimer = setTimeout(async () => {
       reconnectTimer = null;
       reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_DELAY);
+      // Try to discover token before each reconnect attempt
+      // (bridge may have started since last attempt)
+      await discoverToken();
       connect();
     }, delay);
   }
@@ -273,7 +313,8 @@ export function connectDevToolsMCP({ port = 9229 } = {}) {
     log('MCP', BADGE, 'Disconnected');
   }
 
-  connect();
+  // Initial connect — try token discovery first, then connect
+  discoverToken().then(() => connect());
 
   return {
     disconnect,

package/src/index.js

@@ -138,6 +138,8 @@ server.resource(
       mimeType: 'text/markdown',
       text: `# What Framework API Reference
 
+> **Signal style note:** WhatFW signals support both \`sig(newValue)\` and \`sig.set(newValue)\`. The idiomatic pattern is the function-call style: \`sig(newValue)\` to write, \`sig()\` to read.
+
 ## Reactive Primitives
 - \`signal(initial, debugName?)\` — create reactive value. Read: \`sig()\`. Write: \`sig(newVal)\` or \`sig(prev => next)\`.
 - \`computed(fn)\` — derived value (lazy, only recomputes when deps change AND it's read)
@@ -617,6 +619,391 @@ function UserProfile({ userId }) {
   })
 );
 
+// --- Routing Resource (ported from mcp-server) ---
+server.resource(
+  'routing-guide',
+  'what://docs/routing',
+  { description: 'File-based and programmatic routing in What Framework: routes, params, nested layouts, navigation' },
+  async () => ({
+    contents: [{
+      uri: 'what://docs/routing',
+      mimeType: 'text/markdown',
+      text: `# What Framework Routing
+
+## Declaring Routes
+
+\`\`\`js
+import { Router, Link, navigate, route } from 'what-framework/router';
+
+h(Router, {
+  routes: [
+    { path: '/', component: Home },
+    { path: '/about', component: About },
+    { path: '/users/:id', component: User },
+    { path: '/blog/*', component: BlogLayout },
+  ],
+  fallback: h(NotFound),
+});
+\`\`\`
+
+## Navigation
+
+\`\`\`js
+// Declarative link
+h(Link, { href: '/about' }, 'About');
+
+// Programmatic navigation
+navigate('/dashboard');
+navigate('/login', { replace: true });
+\`\`\`
+
+## Reactive Route State
+
+\`\`\`js
+route.path();    // current path (signal — call to read)
+route.params();  // { id: '123' }
+route.query();   // { page: '1' }
+\`\`\`
+
+## Nested Layouts
+
+\`\`\`js
+{
+  path: '/dashboard',
+  component: DashboardLayout,
+  children: [
+    { path: '', component: DashboardHome },
+    { path: 'settings', component: Settings },
+  ],
+}
+\`\`\`
+
+## File-Based Routing
+
+Drop files in \`src/pages/\` and routes are generated automatically:
+
+| File | Route |
+|------|-------|
+| \`src/pages/index.jsx\` | \`/\` |
+| \`src/pages/about.jsx\` | \`/about\` |
+| \`src/pages/users/[id].jsx\` | \`/users/:id\` |
+| \`src/pages/blog/[...slug].jsx\` | \`/blog/*\` |
+
+## Route Guards
+
+\`\`\`js
+{
+  path: '/admin',
+  component: AdminPanel,
+  beforeEnter: (to, from) => {
+    if (!isAuthenticated()) return '/login';
+  },
+}
+\`\`\`
+`,
+    }],
+  })
+);
+
+// --- SSR/SSG Resource (ported from mcp-server) ---
+server.resource(
+  'ssr-ssg-guide',
+  'what://docs/ssr-ssg',
+  { description: 'Server-side rendering, static site generation, and hybrid rendering in What Framework' },
+  async () => ({
+    contents: [{
+      uri: 'what://docs/ssr-ssg',
+      mimeType: 'text/markdown',
+      text: `# What Framework SSR / SSG
+
+## Render Modes
+
+| Mode | Description |
+|------|-------------|
+| \`'static'\` | Pre-rendered at build time (SSG) |
+| \`'server'\` | Rendered on each request (SSR) |
+| \`'client'\` | Client-only rendering (SPA) |
+| \`'hybrid'\` | Static shell + client hydration |
+
+## Render to String (SSR)
+
+\`\`\`js
+import { renderToString } from 'what-framework/server';
+
+const html = await renderToString(h(App));
+\`\`\`
+
+## Stream Rendering
+
+\`\`\`js
+import { renderToStream } from 'what-framework/server';
+
+for await (const chunk of renderToStream(h(App))) {
+  response.write(chunk);
+}
+\`\`\`
+
+## Per-Page Configuration
+
+\`\`\`js
+import { definePage } from 'what-framework/server';
+
+export const page = definePage({
+  mode: 'static',  // 'static' | 'server' | 'client' | 'hybrid'
+});
+\`\`\`
+
+## Server-Only Components
+
+\`\`\`js
+import { server } from 'what-framework/server';
+
+const Header = server(({ title }) => h('header', null, title));
+// This component never ships JS to the client
+\`\`\`
+
+## Islands + SSR
+
+Combine SSR with islands for zero-JS-by-default pages that hydrate interactive parts on demand:
+
+\`\`\`js
+import { island, Island } from 'what-framework/server';
+
+island('cart', () => import('./islands/cart.js'), {
+  mode: 'action',  // Hydrate on first interaction
+});
+
+function Page() {
+  return h('div', null,
+    h('nav', null, 'Static nav — no JS'),
+    h(Island, { name: 'cart' }),
+    h('footer', null, 'Static footer — no JS'),
+  );
+}
+\`\`\`
+
+### Hydration Modes
+- \`'idle'\`: Hydrate when browser is idle
+- \`'visible'\`: Hydrate when visible (IntersectionObserver)
+- \`'action'\`: Hydrate on first click/focus
+- \`'media'\`: Hydrate when media query matches
+- \`'load'\`: Hydrate immediately
+- \`'static'\`: Never hydrate (server only)
+`,
+    }],
+  })
+);
+
+// --- CLI Resource (ported from mcp-server) ---
+server.resource(
+  'cli-guide',
+  'what://docs/cli',
+  { description: 'What Framework CLI commands and project configuration' },
+  async () => ({
+    contents: [{
+      uri: 'what://docs/cli',
+      mimeType: 'text/markdown',
+      text: `# What Framework CLI
+
+## Commands
+
+\`\`\`bash
+what dev        # Dev server with HMR
+what build      # Production build
+what preview    # Preview production build
+what generate   # Static site generation
+\`\`\`
+
+## Configuration
+
+\`\`\`js
+// what.config.js
+export default {
+  mode: 'hybrid',       // 'static' | 'server' | 'client' | 'hybrid'
+  pagesDir: 'src/pages',
+  outDir: 'dist',
+  islands: true,
+  port: 3000,
+};
+\`\`\`
+
+## Environment Variables
+
+- \`WHAT_MCP_PORT\` — Port for the devtools MCP bridge (default: 9229)
+- \`NODE_ENV\` — \`'development'\` enables devtools instrumentation and error collection
+`,
+    }],
+  })
+);
+
+// --- Testing Resource ---
+server.resource(
+  'testing-guide',
+  'what://docs/testing',
+  { description: 'How to test What Framework components, signals, and effects' },
+  async () => ({
+    contents: [{
+      uri: 'what://docs/testing',
+      mimeType: 'text/markdown',
+      text: `# Testing What Framework Apps
+
+## Unit Testing Signals
+
+\`\`\`js
+import { signal, computed, effect, flushSync } from 'what-framework';
+import { describe, it, assert } from 'node:test';
+
+describe('Counter signal', () => {
+  it('increments', () => {
+    const count = signal(0);
+    count(1);
+    assert.strictEqual(count(), 1);
+  });
+
+  it('computed derives correctly', () => {
+    const count = signal(2);
+    const doubled = computed(() => count() * 2);
+    assert.strictEqual(doubled(), 4);
+    count(5);
+    assert.strictEqual(doubled(), 10);
+  });
+});
+\`\`\`
+
+## Testing Effects
+
+Effects flush asynchronously via microtask. Use \`flushSync()\` to force synchronous execution in tests:
+
+\`\`\`js
+import { signal, effect, flushSync } from 'what-framework';
+
+it('effect tracks signal changes', () => {
+  const name = signal('Alice');
+  let captured = '';
+  effect(() => { captured = name(); });
+  flushSync();
+  assert.strictEqual(captured, 'Alice');
+
+  name('Bob');
+  flushSync();
+  assert.strictEqual(captured, 'Bob');
+});
+\`\`\`
+
+## Testing Components
+
+\`\`\`js
+import { mount } from 'what-framework';
+
+it('renders component', () => {
+  const container = document.createElement('div');
+  mount(<Counter />, container);
+  assert.ok(container.querySelector('button'));
+  assert.strictEqual(container.textContent.includes('0'), true);
+});
+\`\`\`
+
+## Testing with MCP Devtools
+
+Use the MCP tools for integration-level debugging:
+1. \`what_lint { code: "..." }\` — static analysis on code before running
+2. \`what_validate { code: "..." }\` — compile check + lint in one call
+3. \`what_snapshot { diff: true }\` — verify state changes after an action
+`,
+    }],
+  })
+);
+
+// --- Project Structure Resource ---
+server.resource(
+  'project-structure',
+  'what://docs/project-structure',
+  { description: 'Recommended project structure and file conventions for What Framework apps' },
+  async () => ({
+    contents: [{
+      uri: 'what://docs/project-structure',
+      mimeType: 'text/markdown',
+      text: `# What Framework Project Structure
+
+## Recommended Layout
+
+\`\`\`
+my-app/
+  what.config.js          # Framework configuration
+  src/
+    pages/                # File-based routes (auto-discovered)
+      index.jsx           # /
+      about.jsx           # /about
+      users/
+        [id].jsx          # /users/:id
+        index.jsx         # /users
+    components/           # Shared components
+      Header.jsx
+      Footer.jsx
+    islands/              # Interactive islands (hydrated on demand)
+      Cart.jsx
+      SearchBar.jsx
+    stores/               # Global stores and shared state
+      auth.js
+      cart.js
+    lib/                  # Utilities, API clients, helpers
+      api.js
+      format.js
+    styles/               # Global styles
+      global.css
+  public/                 # Static assets (copied as-is)
+    favicon.ico
+  dist/                   # Build output (generated)
+\`\`\`
+
+## Naming Conventions
+
+- **Components**: PascalCase (\`MyComponent.jsx\`)
+- **Pages**: lowercase or kebab-case (\`about.jsx\`, \`blog-post.jsx\`)
+- **Islands**: PascalCase, in \`islands/\` directory, export \`.island = true\`
+- **Stores**: camelCase (\`authStore.js\`)
+- **Signals**: camelCase variable names with optional debug name: \`signal(0, 'count')\`
+
+## Import Conventions
+
+Always import from \`'what-framework'\`, not \`'what'\`:
+
+\`\`\`js
+import { signal, effect, computed, onMount } from 'what-framework';
+import { Router, Link, navigate } from 'what-framework/router';
+import { renderToString, definePage } from 'what-framework/server';
+\`\`\`
+`,
+    }],
+  })
+);
+
+// --- Tool Pipeline Guide Resource ---
+server.resource(
+  'tool-pipelines',
+  'what://docs/tool-pipelines',
+  { description: 'How to call MCP tools efficiently: recommended pipelines, token costs, anti-patterns, cascade rules' },
+  async () => {
+    // Load from the markdown file at build time
+    let text;
+    try {
+      const { readFileSync } = await import('node:fs');
+      const { fileURLToPath } = await import('node:url');
+      const path = fileURLToPath(new URL('../TOOL-PIPELINES.md', import.meta.url));
+      text = readFileSync(path, 'utf-8');
+    } catch {
+      text = '# Tool Pipeline Guide\n\nFailed to load TOOL-PIPELINES.md. Check the package installation.';
+    }
+    return {
+      contents: [{
+        uri: 'what://docs/tool-pipelines',
+        mimeType: 'text/markdown',
+        text,
+      }],
+    };
+  }
+);
+
 // Import and register extended tools if available
 try {
   const { registerExtendedTools } = await import('./tools-extended.js');
@@ -633,5 +1020,68 @@ try {
   // Agent tools not yet available — that's fine
 }
 
+// --- MCP Prompts: agent guidance ---
+
+server.prompt(
+  'what-devtools-guide',
+  'How to use WhatFW MCP DevTools effectively. Read this first.',
+  {},
+  async () => ({
+    messages: [{
+      role: 'user',
+      content: {
+        type: 'text',
+        text: `# WhatFW MCP DevTools — Quick Reference
+
+You have access to 28 MCP tools for inspecting and debugging a live What Framework app running in the browser.
+
+## Connection Check
+Always start with: \`what_connection_status\` — confirms the browser is connected and shows signal/effect/component counts.
+
+## Top 5 Tools (use these most)
+
+1. **what_diagnose** — One-call health check. Finds errors, performance issues, and reactivity problems.
+2. **what_explain** {componentId} — Everything about one component: its signals, effects, DOM, and errors.
+3. **what_look** {componentId} — Visual inspection WITHOUT a screenshot: computed styles, dimensions, layout classification, child elements, accessibility.
+4. **what_signals** — List all reactive signals with current values. Filter by name.
+5. **what_lint** {code} — Static analysis before saving code. Catches 7 common mistakes.
+
+## Visual Tools (cheapest first)
+- \`what_look\` — Text description of styles/layout (~400 tokens). Use FIRST.
+- \`what_page_map\` — Full page skeleton with landmarks, buttons, headings (~800 tokens).
+- \`what_screenshot\` {componentId} — Cropped image of ONE component (5-20KB). Use only if text isn't enough.
+
+## State Debugging
+- \`what_signals\` — See all signal values
+- \`what_signal_trace\` {signalId} — "Why did this signal change?" Shows which effects wrote to it.
+- \`what_dependency_graph\` {signalId} — Full reactive graph: signal → effects → downstream.
+- \`what_watch\` — Observe reactive events over a time window.
+
+## Actions
+- \`what_set_signal\` {signalId, value} — Directly change a signal value in the live app.
+- \`what_navigate\` {path} — Navigate to a different route.
+
+## Code Quality
+- \`what_lint\` — Check code for signal-read-without-(), effect cycles, missing cleanup, etc.
+- \`what_scaffold\` {type, name} — Generate idiomatic component/page/form/store boilerplate.
+- \`what_fix\` {errorCode} — Get diagnosis + fix + code example for any WhatFW error.
+
+## Anti-Patterns
+- DON'T screenshot first — use what_look (10x cheaper)
+- DON'T call what_signals + what_effects + what_dom_inspect separately — use what_explain
+- DON'T use what_eval for state inspection — use the structured tools
+
+## What Framework Basics
+- Components run ONCE (not on every render like React)
+- \`signal(value, 'name')\` for state — read with \`sig()\`, write with \`sig(newValue)\`
+- \`effect(() => { ... })\` for side effects — auto-tracks signal reads
+- \`computed(() => ...)\` for derived values — lazy, cached
+- Import from \`'what-framework'\`
+`,
+      },
+    }],
+  })
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);