@vurb/core 3.2.0

package/dist/sandbox/SandboxGuard.d.ts

@@ -0,0 +1,47 @@
+/**
+ * SandboxGuard — Fail-Fast Syntax Checker for LLM-Provided Code
+ *
+ * Provides quick feedback BEFORE sending code to the isolated-vm engine.
+ * This is NOT a security boundary — security comes from the empty V8
+ * Context (no `process`, `require`, `fs`, or `globalThis` injected).
+ *
+ * Purpose:
+ * - Validate that the code is syntactically valid JavaScript
+ * - Check that it looks like a function expression / arrow function
+ * - Provide fast, descriptive error messages to the LLM
+ *
+ * Properties:
+ * - Zero runtime dependencies (pure string analysis)
+ * - Fail-fast: rejects obviously broken code before V8 boot
+ * - NOT a security gate (LLMs can obfuscate; the Isolate is the real wall)
+ *
+ * @module
+ * @internal
+ */
+export interface GuardResult {
+    /** Whether the code passed the fail-fast check */
+    readonly ok: boolean;
+    /** Human-readable reason for rejection (present when `ok` is false) */
+    readonly violation?: string;
+}
+/**
+ * Validate LLM-provided code before sending it to the sandbox.
+ *
+ * Performs two checks:
+ * 1. **Shape check**: The code must look like a function expression
+ * 2. **Suspicious pattern check**: Fail-fast for obviously unsandboxable patterns
+ *
+ * @param code - The JavaScript code string from the LLM
+ * @returns A `GuardResult` indicating whether the code passed
+ *
+ * @example
+ * ```typescript
+ * const result = validateSandboxCode('(data) => data.filter(d => d.x > 5)');
+ * // { ok: true }
+ *
+ * const bad = validateSandboxCode('require("fs").readFileSync("/etc/passwd")');
+ * // { ok: false, violation: 'Code must be a function expression...' }
+ * ```
+ */
+export declare function validateSandboxCode(code: string): GuardResult;
+//# sourceMappingURL=SandboxGuard.d.ts.map

package/dist/sandbox/SandboxGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxGuard.d.ts","sourceRoot":"","sources":["../../src/sandbox/SandboxGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,WAAW,WAAW;IACxB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC/B;AAqCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CA2C7D"}

package/dist/sandbox/SandboxGuard.js

@@ -0,0 +1,127 @@
+/**
+ * SandboxGuard — Fail-Fast Syntax Checker for LLM-Provided Code
+ *
+ * Provides quick feedback BEFORE sending code to the isolated-vm engine.
+ * This is NOT a security boundary — security comes from the empty V8
+ * Context (no `process`, `require`, `fs`, or `globalThis` injected).
+ *
+ * Purpose:
+ * - Validate that the code is syntactically valid JavaScript
+ * - Check that it looks like a function expression / arrow function
+ * - Provide fast, descriptive error messages to the LLM
+ *
+ * Properties:
+ * - Zero runtime dependencies (pure string analysis)
+ * - Fail-fast: rejects obviously broken code before V8 boot
+ * - NOT a security gate (LLMs can obfuscate; the Isolate is the real wall)
+ *
+ * @module
+ * @internal
+ */
+// ── Constants ────────────────────────────────────────────
+/**
+ * Patterns that indicate the code is NOT a pure function.
+ * These are fail-fast hints, not security barriers.
+ * The V8 Isolate with an empty Context is the real security wall.
+ */
+const SUSPICIOUS_PATTERNS = [
+    { pattern: /\bimport\s*\(/, reason: 'Dynamic import() is not available in the sandbox.' },
+    { pattern: /\bimport\s+/, reason: 'ES module imports are not available in the sandbox.' },
+    { pattern: /\brequire\s*\(/, reason: 'require() is not available in the sandbox.' },
+    // Bug #139: fail-fast for eval()/Function() — no security risk (empty Context),
+    // but provides immediate, actionable feedback to the LLM.
+    { pattern: /\beval\s*\(/, reason: 'eval() has no effect in the sandbox — use direct expressions instead.' },
+    { pattern: /\bnew\s+Function\s*\(/, reason: 'new Function() has no effect in the sandbox — use direct expressions instead.' },
+];
+/**
+ * The code must start with one of these patterns to be recognized
+ * as a function expression or arrow function.
+ */
+const FUNCTION_PATTERNS = [
+    /^\s*\(.*\)\s*=>/s, // (x) => ...
+    /^\s*[a-zA-Z_$]\w*\s*=>/, // x => ...
+    /^\s*function\s*\(/, // function(x) { ... }
+    /^\s*function\s+\w+\s*\(/, // function name(x) { ... }
+    // Async patterns kept for shape recognition — SUSPICIOUS_PATTERNS
+    // will reject them before they reach execution (Bug #16)
+    /^\s*async\s+\(.*\)\s*=>/s, // async (x) => ...
+    /^\s*async\s+function\s*\(/, // async function(x) { ... }
+    /^\s*async\s+[a-zA-Z_$]\w*\s*=>/, // async x => ...
+];
+// ── Guard Implementation ─────────────────────────────────
+/**
+ * Validate LLM-provided code before sending it to the sandbox.
+ *
+ * Performs two checks:
+ * 1. **Shape check**: The code must look like a function expression
+ * 2. **Suspicious pattern check**: Fail-fast for obviously unsandboxable patterns
+ *
+ * @param code - The JavaScript code string from the LLM
+ * @returns A `GuardResult` indicating whether the code passed
+ *
+ * @example
+ * ```typescript
+ * const result = validateSandboxCode('(data) => data.filter(d => d.x > 5)');
+ * // { ok: true }
+ *
+ * const bad = validateSandboxCode('require("fs").readFileSync("/etc/passwd")');
+ * // { ok: false, violation: 'Code must be a function expression...' }
+ * ```
+ */
+export function validateSandboxCode(code) {
+    if (!code || typeof code !== 'string') {
+        return { ok: false, violation: 'Code must be a non-empty string.' };
+    }
+    const trimmed = code.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, violation: 'Code must be a non-empty string.' };
+    }
+    // Shape check: must look like a function
+    const looksLikeFunction = FUNCTION_PATTERNS.some(p => p.test(trimmed));
+    if (!looksLikeFunction) {
+        return {
+            ok: false,
+            violation: 'Code must be a function expression or arrow function. ' +
+                'Example: (data) => data.filter(d => d.value > 10)',
+        };
+    }
+    // Suspicious pattern check (fail-fast hints, not security)
+    for (const { pattern, reason } of SUSPICIOUS_PATTERNS) {
+        if (pattern.test(trimmed)) {
+            return { ok: false, violation: reason };
+        }
+    }
+    // Bug #136: detect `async` anywhere in the code (not just at the start).
+    // Strip string literals first to avoid false positives on e.g. "async".
+    if (containsAsyncKeyword(trimmed)) {
+        return {
+            ok: false,
+            violation: 'Async functions are not supported in the sandbox. ' +
+                'The sandbox uses synchronous JSON.stringify(fn(input)) — ' +
+                'an async function would serialize to \'{}\'. ' +
+                'Use a synchronous function instead.',
+        };
+    }
+    return { ok: true };
+}
+// ── Helpers ──────────────────────────────────────────────
+/**
+ * Strip string literals (single, double, template) to avoid
+ * false positives when scanning for keywords like `async`.
+ * Replaces each string literal with empty quotes of the same kind.
+ * @internal
+ */
+function stripStringLiterals(code) {
+    // Match single-quoted, double-quoted, and back-tick strings
+    // (respects escape sequences: \' \" \` don't close the string)
+    return code.replace(/(?:'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|`(?:[^`\\]|\\.)*`)/gs, '""');
+}
+/**
+ * Check if `async` appears as a keyword anywhere in the code,
+ * ignoring occurrences inside string literals (Bug #136).
+ * @internal
+ */
+function containsAsyncKeyword(code) {
+    return /\basync\b/.test(stripStringLiterals(code));
+}
+//# sourceMappingURL=SandboxGuard.js.map

package/dist/sandbox/SandboxGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxGuard.js","sourceRoot":"","sources":["../../src/sandbox/SandboxGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH,4DAA4D;AAE5D;;;;GAIG;AACH,MAAM,mBAAmB,GAAuD;IAC5E,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,mDAAmD,EAAE;IACzF,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,qDAAqD,EAAE;IACzF,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,4CAA4C,EAAE;IACnF,gFAAgF;IAChF,0DAA0D;IAC1D,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,uEAAuE,EAAE;IAC3G,EAAE,OAAO,EAAE,uBAAuB,EAAE,MAAM,EAAE,+EAA+E,EAAE;CAChI,CAAC;AAEF;;;GAGG;AACH,MAAM,iBAAiB,GAA0B;IAC7C,kBAAkB,EAAe,aAAa;IAC9C,wBAAwB,EAAQ,WAAW;IAC3C,mBAAmB,EAAc,sBAAsB;IACvD,yBAAyB,EAAQ,2BAA2B;IAC5D,kEAAkE;IAClE,yDAAyD;IACzD,0BAA0B,EAAO,mBAAmB;IACpD,2BAA2B,EAAM,4BAA4B;IAC7D,gCAAgC,EAAE,iBAAiB;CACtD,CAAC;AAEF,4DAA4D;AAE5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC5C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,kCAAkC,EAAE,CAAC;IACxE,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAE5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,kCAAkC,EAAE,CAAC;IACxE,CAAC;IAED,yCAAyC;IACzC,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IACvE,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACrB,OAAO;YACH,EAAE,EAAE,KAAK;YACT,SAAS,EACL,wDAAwD;gBACxD,mDAAmD;SAC1D,CAAC;IACN,CAAC;IAED,2DAA2D;IAC3D,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,mBAAmB,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAC5C,CAAC;IACL,CAAC;IAED,yEAAyE;IACzE,wEAAwE;IACxE,IAAI,oBAAoB,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,OAAO;YACH,EAAE,EAAE,KAAK;YACT,SAAS,EACL,oDAAoD;gBACpD,2DAA2D;gBAC3D,+CAA+C;gBAC/C,qCAAqC;SAC5C,CAAC;IACN,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAED,4DAA4D;AAE5D;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,IAAY;IACrC,4DAA4D;IAC5D,+DAA+D;IAC/D,OAAO,IAAI,CAAC,OAAO,CAAC,6DAA6D,EAAE,IAAI,CAAC,CAAC;AAC7F,CAAC;AAED;;;;GAIG;AACH,SAAS,oBAAoB,CAAC,IAAY;IACtC,OAAO,WAAW,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Sandbox — Barrel Export
+ *
+ * Zero-Trust Computation Delegation via isolated-vm.
+ * Allows LLMs to send JavaScript functions to be executed
+ * in a sealed V8 isolate on the client's machine.
+ *
+ * The `isolated-vm` package is an optional peerDependency.
+ * The framework works fully without it — sandbox is a power add-on.
+ */
+export { SandboxEngine, resetIvmCache } from './SandboxEngine.js';
+export type { SandboxConfig, SandboxResult, SandboxErrorCode } from './SandboxEngine.js';
+export { validateSandboxCode } from './SandboxGuard.js';
+export type { GuardResult } from './SandboxGuard.js';
+/**
+ * System instruction auto-injected into the tool description
+ * when `.sandboxed()` is used. Teaches the LLM how to send
+ * JavaScript functions for server-side computation delegation.
+ *
+ * @internal
+ */
+export declare const SANDBOX_SYSTEM_INSTRUCTION: string;
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAKiC,CAAC"}

package/dist/sandbox/index.js

@@ -0,0 +1,26 @@
+/**
+ * Sandbox — Barrel Export
+ *
+ * Zero-Trust Computation Delegation via isolated-vm.
+ * Allows LLMs to send JavaScript functions to be executed
+ * in a sealed V8 isolate on the client's machine.
+ *
+ * The `isolated-vm` package is an optional peerDependency.
+ * The framework works fully without it — sandbox is a power add-on.
+ */
+export { SandboxEngine, resetIvmCache } from './SandboxEngine.js';
+export { validateSandboxCode } from './SandboxGuard.js';
+// ── HATEOAS Auto-Prompting Instruction ───────────────────
+/**
+ * System instruction auto-injected into the tool description
+ * when `.sandboxed()` is used. Teaches the LLM how to send
+ * JavaScript functions for server-side computation delegation.
+ *
+ * @internal
+ */
+export const SANDBOX_SYSTEM_INSTRUCTION = '\n\n[SYSTEM: This tool supports Zero-Trust Compute. ' +
+    'You MUST pass a valid, pure, synchronous JavaScript arrow function as a string ' +
+    'to filter/map the data on the server before receiving it. ' +
+    'E.g.: (data) => data.filter(d => d.value > 10). ' +
+    'Do not use markdown formatting, async/await, or external imports.]';
+//# sourceMappingURL=index.js.map

package/dist/sandbox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAElE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGxD,4DAA4D;AAE5D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GACnC,sDAAsD;IACtD,iFAAiF;IACjF,4DAA4D;IAC5D,kDAAkD;IAClD,oEAAoE,CAAC"}

package/dist/server/DevServer.d.ts

@@ -0,0 +1,120 @@
+/** Duck-typed MCP server that supports notifications */
+interface McpServerLike {
+    notification(notification: {
+        method: string;
+    }): Promise<void>;
+    sendNotification?(notification: {
+        method: string;
+    }): Promise<void>;
+}
+/** Duck-typed ToolRegistry */
+interface ToolRegistryLike {
+    register(builder: unknown): void;
+    getBuilders?(): unknown[];
+    /** Optional: clear all builders before re-registering (for hot-reload) */
+    clear?(): void;
+}
+/**
+ * Configuration for the development server.
+ */
+export interface DevServerConfig {
+    /**
+     * Directory to watch for file changes.
+     * Relative paths are resolved from the current working directory.
+     */
+    readonly dir: string;
+    /**
+     * File extension filter for watched files.
+     * @default ['.ts', '.js', '.mjs', '.mts']
+     */
+    readonly extensions?: string[];
+    /**
+     * Debounce interval in milliseconds.
+     * Prevents rapid-fire reloads when editors save multiple files.
+     * @default 300
+     */
+    readonly debounce?: number;
+    /**
+     * Setup callback invoked on every reload.
+     *
+     * Receives a fresh ToolRegistry. The callback should:
+     * 1. Import/define all tools
+     * 2. Register them on the registry
+     *
+     * This is called on initial startup and on every file change.
+     */
+    readonly setup: (registry: ToolRegistryLike) => void | Promise<void>;
+    /**
+     * Optional callback when a reload occurs.
+     * Useful for logging or triggering downstream updates.
+     */
+    readonly onReload?: (changedFile: string) => void;
+    /**
+     * Optional MCP server reference for sending tool list change notifications.
+     * When provided, the dev server sends `notifications/tools/list_changed`
+     * on every reload, so the LLM client picks up changes automatically.
+     */
+    readonly server?: McpServerLike;
+    /**
+     * Optional real ToolRegistry reference for hot-reload.
+     *
+     * When provided, builders collected during `setup()` are automatically
+     * transferred to this registry after each reload, making hot-reload
+     * effective. Without this, the user must close over their own registry
+     * in the setup callback (fragile and undocumented pattern).
+     *
+     * If the registry implements `clear()`, old builders are removed
+     * before re-registration to avoid duplicates.
+     */
+    readonly registry?: ToolRegistryLike;
+}
+/**
+ * Interface for a running dev server instance.
+ */
+export interface DevServer {
+    /** Start watching and perform initial load */
+    start(): Promise<void>;
+    /** Stop the watcher and clean up */
+    stop(): void;
+    /** Force a manual reload (useful from CLI) */
+    reload(reason?: string): Promise<void>;
+}
+/**
+ * Create a cache-busting import URL for ESM modules.
+ * Appends a timestamp query to force the module to be re-evaluated.
+ *
+ * Use this inside a DevServer `setup` callback to re-import ESM modules:
+ * ```ts
+ * const mod = await import(cacheBustUrl('./src/tools.ts'));
+ * ```
+ */
+export declare function cacheBustUrl(filePath: string): string;
+/**
+ * Create an HMR-enabled MCP development server.
+ *
+ * Watches a directory for file changes and automatically reloads
+ * tools, then notifies the connected MCP client via the native
+ * `notifications/tools/list_changed` notification.
+ *
+ * @param config - Dev server configuration
+ * @returns A {@link DevServer} instance with start/stop/reload controls
+ *
+ * @example
+ * ```typescript
+ * import { createDevServer, autoDiscover, ToolRegistry } from 'vurb';
+ *
+ * const devServer = createDevServer({
+ *   dir: './src/tools',
+ *   setup: async (registry) => {
+ *     await autoDiscover(registry, './src/tools');
+ *   },
+ *   onReload: (file) => console.log(`[HMR] Reloaded: ${file}`),
+ * });
+ *
+ * await devServer.start();
+ * // File changes → auto-reload → LLM client gets notification
+ * ```
+ */
+export declare function createDevServer(config: DevServerConfig): DevServer;
+export {};
+//# sourceMappingURL=DevServer.d.ts.map

package/dist/server/DevServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DevServer.d.ts","sourceRoot":"","sources":["../../src/server/DevServer.ts"],"names":[],"mappings":"AAkDA,wDAAwD;AACxD,UAAU,aAAa;IACnB,YAAY,CAAC,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,gBAAgB,CAAC,CAAC,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAED,8BAA8B;AAC9B,UAAU,gBAAgB;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAEjC,WAAW,CAAC,IAAI,OAAO,EAAE,CAAC;IAC1B,0EAA0E;IAC1E,KAAK,CAAC,IAAI,IAAI,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAElD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,8CAA8C;IAC9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,oCAAoC;IACpC,IAAI,IAAI,IAAI,CAAC;IACb,8CAA8C;IAC9C,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAgED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrD;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CA6HlE"}

package/dist/server/DevServer.js

@@ -0,0 +1,252 @@
+/**
+ * DevServer — HMR-enabled MCP Development Server
+ *
+ * The "killer feature" for MCP DX: `vurb dev` starts a
+ * development server that watches for file changes and performs
+ * automatic Hot Module Replacement without requiring the LLM client
+ * (Claude Desktop, Cursor, etc.) to be restarted.
+ *
+ * ## How It Works
+ *
+ * 1. The dev server starts an MCP stdio server with your tools
+ * 2. When a `.ts`/`.js` file changes, the module cache is invalidated
+ * 3. Tools are re-registered from the updated modules
+ * 4. The MCP `notifications/tools/list_changed` notification is sent
+ * 5. The LLM client picks up the new tool definitions transparently
+ *
+ * ## Usage
+ *
+ * ```bash
+ * # Auto-detects src/server.ts
+ * vurb dev
+ *
+ * # Explicit entrypoint + custom watch dir
+ * vurb dev --server ./src/server.ts --dir ./src/tools
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using the programmatic API
+ * import { createDevServer } from 'vurb/dev';
+ *
+ * const devServer = createDevServer({
+ *   dir: './src/tools',
+ *   setup: async (registry) => {
+ *     // Your setup logic — called on every reload
+ *     await autoDiscover(registry, './src/tools');
+ *   },
+ * });
+ *
+ * await devServer.start();
+ * ```
+ *
+ * @module
+ */
+import { watch } from 'node:fs';
+import { resolve, join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+// ── Module Cache Invalidation ────────────────────────────
+/**
+ * Invalidate Node.js ESM module cache for a given file.
+ *
+ * ESM modules are cached by URL. We use an import timestamp trick
+ * to force re-evaluation on next import.
+ *
+ * For CJS, we clear `require.cache` if available.
+ *
+ * @internal
+ */
+function invalidateModule(filePath) {
+    const absolutePath = resolve(filePath);
+    // CJS cache invalidation (when running in CJS mode)
+    if (typeof require !== 'undefined' && require.cache) {
+        invalidateCjsTree(absolutePath);
+    }
+    // ESM modules can't be uncached directly — use a cache-busting
+    // query parameter so the next dynamic import() re-evaluates the module.
+    lastCacheBustUrl = cacheBustUrl(absolutePath);
+}
+/**
+ * The last cache-busted URL produced by `invalidateModule()`.
+ * The setup callback can use this to re-import an ESM module that was invalidated.
+ * @internal
+ */
+let lastCacheBustUrl;
+/**
+ * Recursively invalidate a CJS module and all modules that depend on it.
+ *
+ * Walks `require.cache` to find modules whose `children` include the
+ * changed module (i.e., importers / dependents), and removes them so
+ * the next `require()` re-evaluates the entire dependency chain.
+ *
+ * @internal
+ */
+function invalidateCjsTree(entryPath) {
+    const visited = new Set();
+    const queue = [entryPath];
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (visited.has(current))
+            continue;
+        visited.add(current);
+        delete require.cache[current];
+        // Find all cached modules that imported `current`
+        for (const [key, mod] of Object.entries(require.cache)) {
+            if (!mod)
+                continue;
+            const children = mod.children ?? [];
+            if (children.some(c => c.id === current)) {
+                queue.push(key);
+            }
+        }
+    }
+}
+/**
+ * Create a cache-busting import URL for ESM modules.
+ * Appends a timestamp query to force the module to be re-evaluated.
+ *
+ * Use this inside a DevServer `setup` callback to re-import ESM modules:
+ * ```ts
+ * const mod = await import(cacheBustUrl('./src/tools.ts'));
+ * ```
+ */
+export function cacheBustUrl(filePath) {
+    const url = pathToFileURL(resolve(filePath));
+    url.searchParams.set('t', String(Date.now()));
+    return url.href;
+}
+// ── Dev Server Factory ───────────────────────────────────
+/**
+ * Create an HMR-enabled MCP development server.
+ *
+ * Watches a directory for file changes and automatically reloads
+ * tools, then notifies the connected MCP client via the native
+ * `notifications/tools/list_changed` notification.
+ *
+ * @param config - Dev server configuration
+ * @returns A {@link DevServer} instance with start/stop/reload controls
+ *
+ * @example
+ * ```typescript
+ * import { createDevServer, autoDiscover, ToolRegistry } from 'vurb';
+ *
+ * const devServer = createDevServer({
+ *   dir: './src/tools',
+ *   setup: async (registry) => {
+ *     await autoDiscover(registry, './src/tools');
+ *   },
+ *   onReload: (file) => console.log(`[HMR] Reloaded: ${file}`),
+ * });
+ *
+ * await devServer.start();
+ * // File changes → auto-reload → LLM client gets notification
+ * ```
+ */
+export function createDevServer(config) {
+    const { dir, extensions = ['.ts', '.js', '.mjs', '.mts'], debounce = 300, setup, onReload, server, } = config;
+    const absoluteDir = resolve(dir);
+    let watcher;
+    let debounceTimer;
+    let reloadCount = 0;
+    /**
+     * Perform a full reload: clear caches, re-run setup, notify MCP client.
+     */
+    async function performReload(changedFile) {
+        reloadCount++;
+        // Invalidate CJS cache for all watched files
+        invalidateModule(changedFile);
+        // Re-run the user's setup callback
+        // Provide a duck-typed registry that satisfies the interface.
+        // The user's setup may use this or close over their own registry.
+        const builders = [];
+        const reloadRegistry = {
+            register(builder) { builders.push(builder); },
+            getBuilders() { return builders; },
+        };
+        try {
+            await setup(reloadRegistry);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // eslint-disable-next-line no-console
+            console.error(`[vurb dev] Reload failed: ${message}`);
+            return;
+        }
+        // Transfer collected builders to the real registry (Bug #42 fix)
+        if (builders.length > 0 && config.registry) {
+            if (typeof config.registry.clear === 'function') {
+                config.registry.clear();
+            }
+            for (const b of builders) {
+                config.registry.register(b);
+            }
+        }
+        // Notify MCP client about tool list changes
+        if (server) {
+            const notification = { method: 'notifications/tools/list_changed' };
+            try {
+                if (typeof server.sendNotification === 'function') {
+                    await server.sendNotification(notification);
+                }
+                else if (typeof server.notification === 'function') {
+                    await server.notification(notification);
+                }
+            }
+            catch {
+                // Connection might not be established yet — ignore
+            }
+        }
+        // User callback
+        onReload?.(changedFile);
+    }
+    return {
+        async start() {
+            // Perform initial load
+            await performReload('(initial)');
+            // Start watching
+            const watchOptions = { recursive: true };
+            // Bug #128: warn on Linux with Node.js < 20 where recursive watch is unsupported
+            if (process.platform === 'linux' && parseInt(process.versions.node, 10) < 20) {
+                // eslint-disable-next-line no-console
+                console.warn('[vurb dev] Warning: recursive fs.watch() is not fully supported on Linux with Node.js < 20. ' +
+                    'File changes in subdirectories may not be detected. Consider upgrading to Node.js 20+.');
+            }
+            watcher = watch(absoluteDir, watchOptions, (_eventType, filename) => {
+                if (!filename)
+                    return;
+                // Filter by extension
+                const ext = '.' + filename.split('.').pop();
+                if (!extensions.includes(ext))
+                    return;
+                // Skip test/spec files
+                if (/\.(test|spec|d)\./.test(filename))
+                    return;
+                // Debounce rapid changes
+                if (debounceTimer)
+                    clearTimeout(debounceTimer);
+                debounceTimer = setTimeout(() => {
+                    const fullPath = join(absoluteDir, filename);
+                    void performReload(relative(process.cwd(), fullPath));
+                }, debounce);
+            });
+            watcher.on('error', (err) => {
+                // eslint-disable-next-line no-console
+                console.error(`[vurb dev] Watcher error: ${err instanceof Error ? err.message : String(err)}`);
+            });
+            // eslint-disable-next-line no-console
+            console.log(`[vurb dev] Watching ${relative(process.cwd(), absoluteDir)} for changes...`);
+        },
+        stop() {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            watcher?.close();
+            watcher = undefined;
+            // eslint-disable-next-line no-console
+            console.log(`[vurb dev] Stopped. ${reloadCount} reload(s) performed.`);
+        },
+        async reload(reason) {
+            await performReload(reason ?? '(manual)');
+        },
+    };
+}
+//# sourceMappingURL=DevServer.js.map

package/dist/server/DevServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DevServer.js","sourceRoot":"","sources":["../../src/server/DevServer.ts"],"names":[],"mappings":"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"}