@noleemits/vision-builder-control-mcp 4.47.0 → 4.48.1

package/index.js

@@ -111,7 +111,7 @@ process.on('SIGINT', () => {
 // CONFIG
 // ================================================================
 
-const VERSION = '4.47.0';
+const VERSION = '4.48.1';
 const MIN_PLUGIN_VERSION = '4.13.0'; // Minimum WP plugin version required by this MCP server
 
 // ================================================================
@@ -3887,6 +3887,18 @@ function getToolDefinitions() {
                 },
                 required: ['page_id']
             }
+        },
+        // ── Class Registry ──
+        {
+            name: 'list_classes',
+            description: 'List all registered CSS classes in the NVBC class registry. Returns classes with name, description, category, and which element types they apply to. Use to discover available classes before applying them via update_element. Optionally filter by category or element type.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    category:   { type: 'string', enum: ['layout', 'cards', 'typography', 'hero', 'contact', 'decorative', 'utility'], description: 'Filter to a specific category.' },
+                    applies_to: { type: 'string', enum: ['container', 'widget', 'heading', 'button', 'image', 'any'], description: 'Filter to classes that apply to this element type.' }
+                }
+            }
         }
     ];
 }
@@ -7258,6 +7270,37 @@ async function handleToolCall(name, args) {
         return ok(`Front page set to "${r.front_page_title}" (ID: ${r.front_page_id})${r.blog_page_id ? `\nBlog page: ${r.blog_page_id}` : ''}`);
     }
 
+    case 'list_classes': {
+        const params = new URLSearchParams();
+        if (args.category)   params.set('category', args.category);
+        if (args.applies_to) params.set('applies_to', args.applies_to);
+
+        const r = await apiCall(`/class-registry?${params}`);
+
+        let msg = `=== CSS CLASS REGISTRY (${r.total} classes) ===\n`;
+        msg += `Categories: ${r.categories.join(', ')}\n\n`;
+
+        const byCategory = {};
+        for (const c of r.classes) {
+            if (!byCategory[c.category]) byCategory[c.category] = [];
+            byCategory[c.category].push(c);
+        }
+
+        for (const [cat, items] of Object.entries(byCategory)) {
+            msg += `── ${cat.toUpperCase()} ──\n`;
+            for (const c of items) {
+                const tags = c.applies_to.join(', ');
+                const src  = c.source === 'plugin' ? '[plugin]' : '[site]';
+                msg += `  .${c.name}  ${src}\n`;
+                msg += `    ${c.description}\n`;
+                msg += `    Applies to: ${tags}\n`;
+            }
+            msg += '\n';
+        }
+
+        return ok(msg);
+    }
+
     default:
         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
     }
@@ -7319,18 +7362,31 @@ async function startStdio() {
     // NVBC_MCP_PARENT_WATCH=0. No-op in HTTP mode (only called from stdio).
     startParentWatchdog();
 
-    // Monitor stdin/stdout lifecycle (diagnostic)
-    process.stdin.on('end', () => {
-        console.error('[LIFECYCLE] stdin ended');
-    });
-    process.stdin.on('close', () => {
-        console.error('[LIFECYCLE] stdin closed');
-    });
+    // Exit when the Claude session closes its end of the stdin pipe.
+    // This is the primary self-destruct mechanism — the parent-watchdog is backup
+    // for cases where Windows handle inheritance keeps stdin open after the parent dies.
+    // Grace period: 5s covers any brief reconnects, then we shut down cleanly.
+    let _exitScheduled = false;
+    const scheduleExit = (reason) => {
+        if (_exitScheduled) return;
+        _exitScheduled = true;
+        console.error(`[LIFECYCLE] ${reason} — exiting in 5s`);
+        clearInterval(global._mcpKeepAlive);
+        setTimeout(() => {
+            console.error('[LIFECYCLE] grace period elapsed, exiting');
+            process.exit(0);
+        }, 5000);
+    };
+
+    process.stdin.on('end', () => scheduleExit('stdin ended'));
+    process.stdin.on('close', () => scheduleExit('stdin closed'));
     process.stdin.on('error', (err) => {
         console.error('[LIFECYCLE] stdin error:', err.message);
+        scheduleExit('stdin error');
     });
     process.stdout.on('error', (err) => {
         console.error('[LIFECYCLE] stdout error:', err.message);
+        scheduleExit('stdout error');
     });
 
     _server = createMcpServer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noleemits/vision-builder-control-mcp",
-  "version": "4.47.0",
+  "version": "4.48.1",
   "description": "Vision Builder Control MCP server - design token-driven page builder tools for WordPress/Elementor websites",
   "type": "module",
   "main": "index.js",

package/parent-watchdog.js

@@ -1,120 +1,228 @@
 /**
  * Parent-watchdog for the stdio MCP server.
  *
- * Walks the parent-process chain at startup to find the "owning" session
- * (typically Claude Code / VS Code / Cursor / a terminal), then heartbeats
- * its existence every few seconds. When the owner dies — whether cleanly
- * or via SIGKILL / taskkill /F / OS crash — the watchdog terminates this
- * process. Solves the orphan-accumulation leak where the global keepalive
- * interval in index.js was preventing exit after the host crashed.
+ * Walks the parent process chain at startup to find a stable "session anchor"
+ * (the process that represents the owning Claude session). Watches that
+ * anchor by PID + creation-time fingerprint. When it dies, this process exits.
  *
- * Works regardless of intermediate wrappers (npx, npm.cmd, cmd.exe) because
- * the chain walk skips over them and locks onto the last non-system ancestor.
+ * Anchor selection (in priority order):
+ *   1. `claude.exe`   — Claude Desktop per-window process
+ *   2. A `node.exe` whose command line references claude-code / @anthropic CLI
+ *   3. First non-shell ancestor (skip `cmd.exe`, `conhost.exe`, `sh`, `bash`)
+ *   4. Direct parent (process.ppid) — last-resort fallback
  *
- * Disable per-process via NVBC_MCP_PARENT_WATCH=0.
+ * Why anchor selection matters:
+ *   - Watching `process.ppid` alone fails on Windows when invoked via `npx -y`.
+ *     The chain is: claude.exe → node(npx) → cmd.exe → node(MCP). `process.ppid`
+ *     points to the `cmd.exe` shim, which dies within milliseconds of startup.
+ *     Windows then recycles that PID, eventually assigning it to some unrelated
+ *     long-lived process. The watchdog then sees "parent alive" forever.
+ *   - Walking to the chain-top fails when running inside VS Code / Cursor: those
+ *     processes outlive individual Claude sessions, so the watchdog never fires.
+ *   - The fix is to pick a session-scoped anchor (claude.exe per window, or the
+ *     claude-code node in VS Code) and validate by creation-time to defeat
+ *     PID recycling.
+ *
+ * Env controls:
+ *   NVBC_MCP_PARENT_WATCH=0        Disable watchdog entirely
+ *   NVBC_MCP_WATCHDOG_OWNER_PID=N  Override anchor selection (use PID N)
+ *   NVBC_MCP_WATCHDOG_TRACE=1      Verbose logging of chain walk + ticks
  */
 
 import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { platform } from 'node:os';
 
 const CHECK_INTERVAL_MS = 7000;
-const MAX_CHAIN_DEPTH = 32;
-
-const SYSTEM_ROOTS_WIN = new Set([
-    'explorer.exe', 'services.exe', 'svchost.exe', 'wininit.exe',
-    'smss.exe', 'csrss.exe', 'lsass.exe', 'winlogon.exe',
-    'system', 'system idle process', 'registry', 'memory compression',
+// Re-verify creation time every N ticks (catches PID recycling within ~N*7s).
+const RECYCLE_CHECK_EVERY_N_TICKS = 8;
+const SHELL_NAMES = new Set([
+    'cmd.exe', 'conhost.exe', 'cmd', 'sh', 'bash', 'zsh', 'fish', 'dash', 'ksh'
 ]);
+const TRACE = process.env.NVBC_MCP_WATCHDOG_TRACE === '1';
 
-/**
- * Snapshot every process on the system in one syscall.
- * Returns Map<pid, { pid, ppid, name }>.
- * Spawning PowerShell once is ~400ms; spawning it N times is N × 400ms,
- * which is why per-step queries were timing out before the watchdog could arm.
- */
-function snapshotWindows() {
-    const out = execSync(
-        'powershell -NoProfile -Command "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name | ConvertTo-Json -Compress"',
-        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000, windowsHide: true, maxBuffer: 32 * 1024 * 1024 }
-    );
-    const data = JSON.parse(out);
+function trace(msg) {
+    if (TRACE) console.error(`[WATCHDOG:TRACE] ${msg}`);
+}
+
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (e) {
+        if (e.code === 'ESRCH') return false;
+        // EPERM: process exists but we can't signal it — still alive.
+        return true;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Process-snapshot helpers (one-shot at startup, then cheap PID checks)
+// ---------------------------------------------------------------------------
+
+function parseCimDate(v) {
+    if (v == null) return null;
+    if (typeof v === 'number') return v;
+    if (typeof v === 'object' && v.value != null) return parseCimDate(v.value);
+    const s = String(v);
+    // PowerShell ConvertTo-Json on a DateTime emits /Date(milliseconds)/
+    const m = s.match(/\/Date\((-?\d+)\)\//);
+    if (m) return parseInt(m[1], 10);
+    // Or ISO 8601
+    const t = Date.parse(s);
+    return Number.isFinite(t) ? t : null;
+}
+
+function snapshotWin32() {
+    // Single PowerShell call. ConvertTo-Json -Depth 2 keeps CreationDate as
+    // a /Date(...)/ string. Cap rows defensively in case of huge process tables.
+    const ps = [
+        'Get-CimInstance Win32_Process',
+        'Select-Object ProcessId,ParentProcessId,Name,CommandLine,CreationDate',
+        'ConvertTo-Json -Compress -Depth 2'
+    ].join(' | ');
+    const cmd = `powershell -NoProfile -NonInteractive -Command "${ps}"`;
+    const out = execSync(cmd, {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 15000,
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    const arr = JSON.parse(out);
+    const list = Array.isArray(arr) ? arr : [arr];
     const map = new Map();
-    for (const row of (Array.isArray(data) ? data : [data])) {
-        map.set(row.ProcessId, {
-            pid: row.ProcessId,
-            ppid: row.ParentProcessId,
-            name: String(row.Name || ''),
+    for (const p of list) {
+        if (!p || typeof p.ProcessId !== 'number') continue;
+        map.set(p.ProcessId, {
+            ppid: typeof p.ParentProcessId === 'number' ? p.ParentProcessId : 0,
+            name: p.Name || '',
+            cmdline: p.CommandLine || '',
+            createDate: parseCimDate(p.CreationDate),
         });
     }
     return map;
 }
 
 function snapshotPosix() {
-    // ps is universal. Single fork, all processes, parseable.
-    const out = execSync('ps -axo pid=,ppid=,comm=', {
-        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000, maxBuffer: 32 * 1024 * 1024,
+    // `ps -axo pid=,ppid=,lstart=,command=` is portable across Linux/macOS.
+    // lstart is 5 whitespace-separated tokens (Day Mon DD HH:MM:SS YYYY).
+    const out = execSync('ps -axo pid=,ppid=,lstart=,command=', {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 5000,
+        maxBuffer: 16 * 1024 * 1024,
     });
     const map = new Map();
     for (const line of out.split('\n')) {
-        const m = line.match(/^\s*(\d+)\s+(\d+)\s+(.*)$/);
+        const m = line.match(/^\s*(\d+)\s+(\d+)\s+(\S+\s+\S+\s+\S+\s+\S+\s+\S+)\s+(.+)$/);
         if (!m) continue;
         const pid = parseInt(m[1], 10);
         const ppid = parseInt(m[2], 10);
-        map.set(pid, { pid, ppid, name: m[3].trim() });
+        const lstart = m[3];
+        const cmdline = m[4];
+        const name = (cmdline.split(/\s+/)[0] || '').split('/').pop() || '';
+        const ts = Date.parse(lstart);
+        map.set(pid, {
+            ppid,
+            name,
+            cmdline,
+            createDate: Number.isFinite(ts) ? ts : null,
+        });
     }
     return map;
 }
 
-/**
- * Walk up from process.pid using an in-memory snapshot. Returns the last
- * non-system ancestor PID, or null.
- */
-function findOwningAncestor() {
-    const os = platform();
-    let snapshot;
+function snapshotProcesses() {
+    return process.platform === 'win32' ? snapshotWin32() : snapshotPosix();
+}
+
+// Single-PID creation-time refresh (used during recycle checks).
+function fetchCreateDate(pid) {
+    if (process.platform === 'win32') {
+        const cmd = `powershell -NoProfile -NonInteractive -Command "(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}').CreationDate"`;
+        const out = execSync(cmd, {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        }).trim();
+        if (!out) return null;
+        return parseCimDate(out);
+    }
+    // POSIX: use `ps -o lstart= -p <pid>` so the value matches snapshotPosix.
     try {
-        snapshot = os === 'win32' ? snapshotWindows() : snapshotPosix();
-    } catch (err) {
-        throw new Error(`process snapshot failed: ${err.message}`);
+        const out = execSync(`ps -o lstart= -p ${pid}`, {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 3000,
+        }).trim();
+        if (!out) return null;
+        const t = Date.parse(out);
+        return Number.isFinite(t) ? t : null;
+    } catch (e) {
+        if (e.status === 1) return null; // ps returns 1 when no such pid
+        throw e;
     }
+}
 
-    let cur = process.pid;
-    let lastNonSystem = null;
-    let depth = 0;
+// ---------------------------------------------------------------------------
+// Chain walking and anchor selection
+// ---------------------------------------------------------------------------
 
-    while (depth++ < MAX_CHAIN_DEPTH) {
+function walkChain(snapshot, startPid, maxDepth = 30) {
+    const chain = [];
+    const seen = new Set();
+    let cur = startPid;
+    for (let i = 0; i < maxDepth; i++) {
+        if (!cur || cur <= 1 || seen.has(cur)) break;
+        seen.add(cur);
         const info = snapshot.get(cur);
-        if (!info || !info.ppid) break;
+        if (!info) break;
+        chain.push({ pid: cur, ...info });
+        cur = info.ppid;
+    }
+    return chain;
+}
 
-        const ppid = info.ppid;
-        if (ppid === 0) break; // Windows pseudo-root.
-        if (os !== 'win32' && ppid === 1) break; // POSIX init/systemd/launchd.
+function lower(s) { return (s || '').toLowerCase(); }
 
-        if (os === 'win32') {
-            const parentInfo = snapshot.get(ppid);
-            if (!parentInfo) break;
-            if (SYSTEM_ROOTS_WIN.has((parentInfo.name || '').toLowerCase())) break;
-        }
+function looksLikeClaudeCodeNode(entry) {
+    const name = lower(entry.name);
+    if (!/^node(\.exe)?$/.test(name)) return false;
+    const cmd = lower(entry.cmdline);
+    if (!cmd) return false;
+    // Match common ways the Claude Code CLI appears in the command line.
+    return (
+        cmd.includes('claude-code') ||
+        cmd.includes('@anthropic') ||
+        /[\\/]claude(?:\.cmd|\.js)?(?:\s|$)/.test(cmd) ||
+        cmd.includes('claude/cli.js') ||
+        cmd.includes('claude\\cli.js')
+    );
+}
 
-        lastNonSystem = ppid;
-        cur = ppid;
-    }
+function findAnchor(chain) {
+    if (chain.length === 0) return null;
 
-    return lastNonSystem;
-}
+    // 1. Claude Desktop per-window process.
+    const claudeDesktop = chain.find(x => /^claude\.exe$/i.test(x.name));
+    if (claudeDesktop) return { ...claudeDesktop, reason: 'claude_desktop' };
 
-function isAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    } catch (e) {
-        if (e.code === 'ESRCH') return false;
-        // EPERM: process exists, we just can't signal it. Still alive.
-        return true;
-    }
+    // 2. Claude Code CLI node process (VS Code / terminal).
+    const claudeCli = chain.find(looksLikeClaudeCodeNode);
+    if (claudeCli) return { ...claudeCli, reason: 'claude_code_cli' };
+
+    // 3. First non-shell ancestor (skips cmd.exe between npx and the real MCP).
+    //    chain[0] is ourselves — start the search at index 1.
+    const nonShell = chain.slice(1).find(x => !SHELL_NAMES.has(lower(x.name)));
+    if (nonShell) return { ...nonShell, reason: 'first_non_shell_ancestor' };
+
+    // 4. Last-resort: direct parent.
+    if (chain[1]) return { ...chain[1], reason: 'direct_parent_fallback' };
+    return null;
 }
 
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
 /**
  * Start the parent-watchdog. Should only be called from stdio mode.
  *
@@ -126,38 +234,102 @@ export function startParentWatchdog() {
         return { ownerPid: null, enabled: false, reason: 'env_disabled' };
     }
 
-    let ownerPid = null;
+    let snapshot;
+    try {
+        snapshot = snapshotProcesses();
+    } catch (e) {
+        console.error(`[WATCHDOG] snapshot failed: ${e.message} — falling back to ppid`);
+        return startFallbackPpidWatch();
+    }
 
-    // Explicit override — watch this PID instead of walking the chain.
-    // Escape hatch for unusual process trees (tmux, screen, supervisor).
+    // Walk our chain.
+    const chain = walkChain(snapshot, process.pid);
+    if (TRACE) {
+        for (const entry of chain) {
+            trace(`chain pid=${entry.pid} ppid=${entry.ppid} name=${entry.name} createDate=${entry.createDate}`);
+        }
+    }
+
+    // Optional override via env var.
+    let anchor = null;
     const override = parseInt(process.env.NVBC_MCP_WATCHDOG_OWNER_PID || '', 10);
     if (Number.isFinite(override) && override > 0) {
-        ownerPid = override;
+        const info = snapshot.get(override);
+        anchor = info
+            ? { pid: override, ...info, reason: 'env_override' }
+            : { pid: override, name: 'unknown', cmdline: '', createDate: null, ppid: 0, reason: 'env_override_unsnapshot' };
     } else {
-        try {
-            ownerPid = findOwningAncestor();
-        } catch (err) {
-            console.error(`[WATCHDOG] ancestry walk failed: ${err.message} — watchdog disabled`);
-            return { ownerPid: null, enabled: false, reason: 'walk_failed' };
-        }
+        anchor = findAnchor(chain);
     }
 
-    if (!ownerPid) {
-        console.error('[WATCHDOG] no non-system ancestor found — watchdog disabled (daemonized run?)');
-        return { ownerPid: null, enabled: false, reason: 'no_ancestor' };
+    if (!anchor || !anchor.pid || anchor.pid <= 1) {
+        console.error('[WATCHDOG] could not identify anchor process — watchdog disabled');
+        return { ownerPid: null, enabled: false, reason: 'no_anchor' };
     }
 
-    console.error(`[WATCHDOG] watching parent session pid=${ownerPid} (interval=${CHECK_INTERVAL_MS}ms)`);
+    const cachedCreateDate = anchor.createDate;
+    console.error(
+        `[WATCHDOG] anchor pid=${anchor.pid} name=${anchor.name} reason=${anchor.reason}` +
+        ` createDate=${cachedCreateDate ?? 'unknown'} (interval=${CHECK_INTERVAL_MS}ms)`
+    );
 
+    let tick = 0;
     const interval = setInterval(() => {
-        if (!isAlive(ownerPid)) {
-            console.error(`[WATCHDOG] parent pid=${ownerPid} is gone — shutting down`);
-            // Bypass the global keepalive + beforeExit safety net in index.js.
+        tick++;
+        // Fast existence check.
+        if (!isAlive(anchor.pid)) {
+            console.error(`[WATCHDOG] anchor pid=${anchor.pid} (${anchor.name}) is gone — shutting down`);
             process.exit(0);
+            return;
+        }
+
+        // Periodic creation-time re-verification to catch PID recycling.
+        if (cachedCreateDate && tick % RECYCLE_CHECK_EVERY_N_TICKS === 0) {
+            try {
+                const current = fetchCreateDate(anchor.pid);
+                if (current == null) {
+                    console.error(`[WATCHDOG] anchor pid=${anchor.pid} creation-date lookup returned empty — assuming gone, shutting down`);
+                    process.exit(0);
+                    return;
+                }
+                // Allow 2s slop for clock formatting differences.
+                if (Math.abs(current - cachedCreateDate) > 2000) {
+                    console.error(
+                        `[WATCHDOG] anchor pid=${anchor.pid} was recycled` +
+                        ` (createDate cached=${cachedCreateDate} current=${current}) — shutting down`
+                    );
+                    process.exit(0);
+                    return;
+                }
+                trace(`recycle-check ok (tick=${tick}, pid=${anchor.pid})`);
+            } catch (e) {
+                console.error(`[WATCHDOG] recycle-check failed (${e.message}) — shutting down to be safe`);
+                process.exit(0);
+            }
         }
     }, CHECK_INTERVAL_MS);
 
+    // unref so this interval doesn't prevent exit if everything else finishes.
     interval.unref();
 
-    return { ownerPid, enabled: true };
+    return { ownerPid: anchor.pid, enabled: true, reason: anchor.reason };
+}
+
+// Fallback used when the process snapshot itself fails (PowerShell missing,
+// ps unavailable, etc.). Watches process.ppid only — the pre-v4.48.1 behavior.
+function startFallbackPpidWatch() {
+    const ownerPid = process.ppid;
+    if (!ownerPid || ownerPid <= 1) {
+        console.error('[WATCHDOG] no valid parent pid — disabled');
+        return { ownerPid: null, enabled: false, reason: 'no_parent' };
+    }
+    console.error(`[WATCHDOG] fallback: watching direct parent pid=${ownerPid} (interval=${CHECK_INTERVAL_MS}ms)`);
+    const interval = setInterval(() => {
+        if (!isAlive(ownerPid)) {
+            console.error(`[WATCHDOG] parent pid=${ownerPid} is gone — shutting down`);
+            process.exit(0);
+        }
+    }, CHECK_INTERVAL_MS);
+    interval.unref();
+    return { ownerPid, enabled: true, reason: 'fallback_ppid' };
 }