devharness 0.8.0

package/build/mcp-supervisor.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * Dependency-free MCP hot-reload supervisor.
+ *
+ * This is the package's `bin` entry point - both this repo's own .mcp.json
+ * and every other project's `npx devharness@latest` launch THIS process
+ * instead of the real server directly. This process keeps that stdio
+ * connection alive forever and manages the real server (index.js, resolved
+ * next to this file - see below) as a restartable child, so:
+ * - a crash gets auto-relaunched with backoff, instead of leaving every
+ *   project's MCP connection dead until a manual /mcp reconnect;
+ * - in this repo specifically, a rebuild (package.json's `postbuild` script)
+ *   or a manual `kill -USR2 <pid>` restarts the real server live;
+ * - an idle session's server can be dropped entirely - along with its Chrome
+ *   instances, dev servers and monitor buffers - while this process keeps the
+ *   client's connection alive and respawns on the next request (issue #138);
+ * - a tree whose client is gone shuts itself down instead of living for days.
+ *
+ * The child script path is resolved relative to THIS file's own location
+ * (__dirname), not process.cwd() - process.cwd() is this repo's root when
+ * launched via its own .mcp.json, but is whatever *other* project's
+ * directory Claude Code happened to launch from when installed globally/via
+ * npx, which has no build/index.js of its own. Same-directory resolution
+ * works correctly in both cases, since index.js always ships right next to
+ * this file. Override with MCP_SUPERVISOR_CHILD_SCRIPT for testing; every
+ * other argv is passed straight through to the child.
+ *
+ * See /Users/joshua/.claude/plans/zesty-coalescing-tome.md for the full
+ * design and its rationale.
+ *
+ * Usage: node build/mcp-supervisor.js [...extraChildArgs]
+ */
+import * as path from 'path';
+import * as os from 'os';
+import { fileURLToPath } from 'url';
+import { getOutputPath, getConfigPath } from './helpers/paths.js';
+import { atomicWriteFile } from './atomic-write.js';
+import { ChildManager } from './supervisor/child-manager.js';
+import { RestartCoordinator } from './supervisor/restart-coordinator.js';
+import { NdjsonReader } from './supervisor/ndjson-reader.js';
+import { removeOwnPidFile } from './supervisor/pidfile.js';
+import { ClientWatcher } from './supervisor/client-watcher.js';
+import { readSupervisorSessionConfig, idleCheckIntervalMs } from './supervisor/idle-config.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function logStderr(message) {
+    process.stderr.write(`[mcp-supervisor] ${message}\n`);
+}
+async function main() {
+    const scriptPath = process.env.MCP_SUPERVISOR_CHILD_SCRIPT
+        ? path.resolve(process.cwd(), process.env.MCP_SUPERVISOR_CHILD_SCRIPT)
+        : path.join(__dirname, 'index.js');
+    const extraArgs = process.argv.slice(2);
+    const pidFilePath = getOutputPath('mcp-supervisor.pid');
+    await atomicWriteFile(pidFilePath, String(process.pid));
+    // Overridable so the stress harness can watch the escalation path without
+    // sitting out the full grace period (scripts/stress-suspend.mjs).
+    const suspendGraceMs = Number(process.env.CDP_TOOLS_SUSPEND_GRACE_MS);
+    const childManager = new ChildManager({
+        execPath: process.execPath,
+        scriptPath,
+        extraArgs,
+        cwd: process.cwd(),
+        suspendGraceMs: Number.isFinite(suspendGraceMs) && suspendGraceMs > 0 ? suspendGraceMs : undefined,
+    });
+    // Always points at the currently-running child's stdin, so writeToChild
+    // routes to whichever process is actually alive right now.
+    let currentChildStdin = null;
+    // Last time this session did anything at all, in either direction - what the
+    // idle-suspend timer measures against.
+    let lastActivityAt = Date.now();
+    const coordinator = new RestartCoordinator({
+        writeToChild: (line) => {
+            if (!currentChildStdin) {
+                logStderr('Dropping message meant for child - no child is currently running');
+                return;
+            }
+            currentChildStdin.write(line + (line.endsWith('\n') ? '' : '\n'));
+        },
+        writeToHost: (line) => {
+            // Traffic in either direction means the session is working, so a tool
+            // call that runs longer than the idle threshold isn't suspended the
+            // moment it finally answers.
+            lastActivityAt = Date.now();
+            process.stdout.write(line.endsWith('\n') ? line : line + '\n');
+        },
+        killChild: () => childManager.kill(),
+        suspendChild: () => childManager.suspend(),
+        spawnChild: () => spawnAndWireChild(),
+        logStderr,
+    }, {});
+    function spawnAndWireChild() {
+        const { stdout, stdin } = childManager.spawn();
+        currentChildStdin = stdin;
+        stdin.on('error', (err) => logStderr(`Child stdin error (ignored): ${err}`));
+        const reader = new NdjsonReader();
+        stdout.on('data', (chunk) => {
+            reader.push(chunk);
+            for (const line of reader.readAllLines()) {
+                coordinator.handleChildLine(line);
+            }
+        });
+        stdout.on('close', () => {
+            if (currentChildStdin === stdin) {
+                currentChildStdin = null;
+            }
+            coordinator.onChildStdoutClosed();
+        });
+    }
+    childManager.onExit(({ code, signal }) => {
+        logStderr(`Child exited (code=${code}, signal=${signal})`);
+        coordinator.onChildExit();
+    });
+    // Host (Claude Code) -> supervisor -> child
+    const hostReader = new NdjsonReader();
+    process.stdin.on('data', (chunk) => {
+        hostReader.push(chunk);
+        for (const line of hostReader.readAllLines()) {
+            lastActivityAt = Date.now();
+            coordinator.handleHostLine(line);
+        }
+    });
+    const sessionConfig = readSupervisorSessionConfig({
+        configPath: getConfigPath(),
+        globalConfigPath: path.join(os.homedir(), '.cdp-tools', 'config.json'),
+    });
+    // Suspend an idle session. The editor window this was launched from is often
+    // left open for days; without this the child sits on its Chrome instances,
+    // dev servers and monitor buffers for all of that time (issue #138). The
+    // supervisor itself stays on the host's stdio, so the connection survives
+    // and the next request spawns a fresh child.
+    let idleCheckTimer = null;
+    if (sessionConfig.idleSuspendMinutes > 0) {
+        const idleThresholdMs = sessionConfig.idleSuspendMinutes * 60_000;
+        const checkIntervalMs = idleCheckIntervalMs(idleThresholdMs);
+        logStderr(`Idle suspend after ${sessionConfig.idleSuspendMinutes} minute(s) without host activity`);
+        idleCheckTimer = setInterval(() => {
+            if (!childManager.isRunning())
+                return;
+            const idleMs = Date.now() - lastActivityAt;
+            if (idleMs < idleThresholdMs)
+                return;
+            coordinator.suspend(`idle for ${Math.round(idleMs / 60_000)} minute(s)`);
+        }, checkIntervalMs);
+        idleCheckTimer.unref?.();
+    }
+    else {
+        logStderr('Idle suspend disabled by config');
+    }
+    // Reap the whole tree when the client that launched it is gone. stdin
+    // end/close is supposed to catch that, but never fires when an `npm exec`
+    // wrapper sits in between and outlives the client still holding our pipe -
+    // which is how trees end up alive for days after their window closed.
+    const clientWatcher = new ClientWatcher({
+        pollIntervalMs: sessionConfig.clientPollSeconds * 1000,
+        logStderr,
+    });
+    clientWatcher.start(process.pid, (client) => {
+        void shutdown(`client PID ${client.pid} exited`);
+    });
+    // Manual restart trigger (also wired to package.json's `postbuild` script).
+    process.on('SIGUSR2', () => {
+        logStderr('Received SIGUSR2, restarting child');
+        coordinator.requestRestart('signal');
+    });
+    let shuttingDown = false;
+    const shutdown = async (reason) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logStderr(`Shutting down (${reason})`);
+        clientWatcher.stop();
+        if (idleCheckTimer)
+            clearInterval(idleCheckTimer);
+        coordinator.prepareForShutdown();
+        try {
+            // Every path into here means the session itself is over - a signal, the
+            // host's stdin closing, or the client being gone - so the child gets the
+            // release teardown rather than a bare kill, and takes the dev servers it
+            // owns with it. A rebuild restart does NOT come through here: it goes via
+            // requestRestart(), which kills shallowly so the next child can reattach.
+            await childManager.suspend();
+        }
+        catch (err) {
+            logStderr(`Error stopping child during shutdown: ${err}`);
+        }
+        // Only if it is still OURS: a newer supervisor may own it by now, and
+        // taking that one's pidfile away silently breaks its hot reload.
+        await removeOwnPidFile(pidFilePath, process.pid);
+        process.exit(0);
+    };
+    process.on('SIGINT', () => void shutdown('SIGINT'));
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+    process.on('SIGHUP', () => void shutdown('SIGHUP'));
+    // Claude Code exiting without sending a signal still closes its end of stdin.
+    process.stdin.on('end', () => void shutdown('host stdin ended'));
+    process.stdin.on('close', () => void shutdown('host stdin closed'));
+    process.on('uncaughtException', (error) => {
+        logStderr(`Uncaught exception: ${error?.stack || error}`);
+    });
+    process.on('unhandledRejection', (reason) => {
+        logStderr(`Unhandled rejection: ${reason}`);
+    });
+    logStderr(`Starting (PID: ${process.pid}), child script: ${scriptPath}`);
+    spawnAndWireChild();
+}
+main().catch((error) => {
+    logStderr(`Fatal error during startup: ${error?.stack || error}`);
+    process.exit(1);
+});
+//# sourceMappingURL=mcp-supervisor.js.map

package/build/mcp-supervisor.js.map

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

package/build/messages.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Message template system for cdp-tools
+ *
+ * Loads and formats user-facing messages from docs/messages.md
+ */
+interface MessageTemplate {
+    id: string;
+    type: 'error' | 'success' | 'warning' | 'info' | 'list';
+    code?: string;
+    summary?: string;
+    content: string;
+    suggestions?: string[];
+    note?: string;
+    example?: string;
+}
+declare class MessageManager {
+    private messages;
+    private loaded;
+    /**
+     * Load messages from docs/messages.md
+     */
+    private loadMessages;
+    /**
+     * Parse messages from markdown content
+     */
+    private parseMessages;
+    /**
+     * Load fallback messages if markdown file can't be loaded
+     */
+    private loadFallbackMessages;
+    /**
+     * Get a message by ID with variable substitution
+     */
+    getMessage(id: string, variables?: Record<string, any>): string;
+    /**
+     * Get a complete message template with metadata
+     */
+    getMessageTemplate(id: string): MessageTemplate | undefined;
+    /**
+     * Format an error message with suggestions and examples
+     * Uses the same Status + Key detail format as getFormattedResponse
+     */
+    getErrorMessage(id: string, variables?: Record<string, any>): string;
+    /**
+     * Resolve a dotted path to a value in the variables object
+     */
+    private resolveVariable;
+    /**
+     * Format a message template with variable substitution
+     * Supports:
+     * - {{variable}} - simple substitution
+     * - {{object.property}} - nested access
+     * - {{#variable}}...{{/variable}} - conditional (truthy)
+     * - {{^variable}}...{{/variable}} - inverted conditional (falsy)
+     * - {{#if condition}}...{{/if}} - explicit if blocks
+     * - {{#each array}}...{{/each}} - iteration over arrays
+     */
+    private formatMessage;
+    /**
+     * Process conditionals within a given context (used by #each)
+     */
+    private processConditionals;
+    /**
+     * Get message code for error responses
+     */
+    getMessageCode(id: string): string | undefined;
+    /**
+     * Check if a message exists
+     */
+    hasMessage(id: string): boolean;
+    /**
+     * Format data as a JSON code block
+     */
+    formatCodeBlock(data: any, language?: string): string;
+    /**
+     * Format an array as a markdown bullet list
+     */
+    formatList(items: string[]): string;
+    /**
+     * Get a complete markdown-only response for a tool
+     * Combines message template with optional data formatting
+     *
+     * Output format:
+     * Line 1: Status line (Success/Error/Warning/Info: Brief description)
+     * Line 2: Key detail (most important info like location, ID, count)
+     * Line 3+: Additional content (suggestions, notes, data)
+     */
+    getFormattedResponse(id: string, variables?: Record<string, any>, data?: any): string;
+}
+export declare const messages: MessageManager;
+/**
+ * Helper function to get a formatted message
+ */
+export declare function getMessage(id: string, variables?: Record<string, any>): string;
+/**
+ * Helper function to get a formatted error message with suggestions
+ */
+export declare function getErrorMessage(id: string, variables?: Record<string, any>): string;
+/**
+ * Helper function to get message code
+ */
+export declare function getMessageCode(id: string): string | undefined;
+/**
+ * Helper function to get a complete markdown-only response
+ */
+export declare function getFormattedResponse(id: string, variables?: Record<string, any>, data?: any): string;
+/**
+ * Helper function to format data as a code block
+ */
+export declare function formatCodeBlock(data: any, language?: string): string;
+/**
+ * Helper function to format an array as a markdown list
+ */
+export declare function formatList(items: string[]): string;
+import type { ToolResponseMeta } from './tool-response.js';
+/**
+ * MCP Response type
+ */
+interface MCPResponse {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+    /** Structured metadata for programmatic use (validation, replay). Decoupled from text output. */
+    _meta?: ToolResponseMeta;
+    /**
+     * Message template id behind an error, for callers that must classify a
+     * failure rather than display it. In-process only - the replay executor reads
+     * the handler's return value (and ToolError's captured response) before
+     * anything is serialized, so it need not survive the wire.
+     */
+    _errorId?: string;
+}
+/**
+ * Create an error response in MCP format with markdown content
+ */
+export declare function createErrorResponse(messageId: string, variables?: Record<string, any>): MCPResponse;
+/**
+ * Whether a tool failure means "that element isn't on the page", as opposed to
+ * any other failure. Prefers the response's `_errorId`; the text forms are for
+ * a failure that arrived without one. Lives beside the ELEMENT_NOT_FOUND
+ * template so a reword is caught here rather than in every caller that
+ * classifies one.
+ */
+export declare function isElementNotFoundFailure(failure: {
+    errorId?: string;
+    text?: string;
+}): boolean;
+/**
+ * Create a success response in MCP format with markdown content
+ */
+export declare function createSuccessResponse(messageId: string, variables?: Record<string, any>, data?: any): MCPResponse;
+/**
+ * Format a tool success response (for tools that don't use message templates)
+ * Uses Status + Key detail format
+ */
+export declare function formatToolSuccess(message: string, data?: any): MCPResponse;
+/**
+ * Format a tool error response (for tools that don't use message templates)
+ * Uses Status + Key detail format
+ */
+export declare function formatToolError(code: string, message: string, data?: any): MCPResponse;
+export {};
+//# sourceMappingURL=messages.d.ts.map

package/build/messages.d.ts.map

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