patchwork-os 0.2.0-alpha.0

package/dist/tools/vscodeCommands.js

@@ -0,0 +1,112 @@
+import { ExtensionTimeoutError, } from "../extensionClient.js";
+import { error, extensionRequired, requireString, successStructured, } from "./utils.js";
+export function createExecuteVSCodeCommandTool(extensionClient, config) {
+    return {
+        schema: {
+            name: "executeVSCodeCommand",
+            extensionRequired: true,
+            description: "Execute VS Code command by ID. Use listVSCodeCommands to discover IDs.",
+            inputSchema: {
+                $schema: "http://json-schema.org/draft-07/schema#",
+                type: "object",
+                required: ["command"],
+                properties: {
+                    command: {
+                        type: "string",
+                        description: "VS Code command ID to execute",
+                    },
+                    args: {
+                        type: "array",
+                        description: "Arguments to pass to the command",
+                        items: {},
+                    },
+                },
+                additionalProperties: false,
+            },
+            outputSchema: {
+                type: "object",
+            },
+        },
+        async handler(args) {
+            if (!extensionClient.isConnected()) {
+                return extensionRequired("executeVSCodeCommand");
+            }
+            const command = requireString(args, "command", 256);
+            // Allowlist enforcement (bridge-side) — default-deny when no allowlist is configured.
+            // VS Code commands are a broad attack surface; require explicit opt-in for each command.
+            if (config.vscodeCommandAllowlist.length === 0) {
+                return error("executeVSCodeCommand requires an explicit allowlist. " +
+                    "Use --vscode-allow-command <command-id> to permit specific commands. " +
+                    "Run listVSCodeCommands to discover available command IDs.");
+            }
+            // Normalize to lowercase for case-insensitive comparison — consistent with
+            // runCommand allowlist behavior (prevents case-variation bypass).
+            const commandLower = command.toLowerCase();
+            if (!config.vscodeCommandAllowlist.some((a) => a.toLowerCase() === commandLower)) {
+                return error(`Command "${command}" is not in the vscodeCommandAllowlist. ` +
+                    `Allowed: ${config.vscodeCommandAllowlist.join(", ")}. ` +
+                    `Use --vscode-allow-command ${command} to add it.`);
+            }
+            const cmdArgs = Array.isArray(args.args) ? args.args : [];
+            try {
+                const result = await extensionClient.executeVSCodeCommand(command, cmdArgs);
+                if (result === null)
+                    return error(`Command "${command}" returned null or failed`);
+                return successStructured(result);
+            }
+            catch (err) {
+                if (err instanceof ExtensionTimeoutError) {
+                    return error(`Extension timed out executing "${command}"`);
+                }
+                throw err;
+            }
+        },
+    };
+}
+export function createListVSCodeCommandsTool(extensionClient) {
+    return {
+        schema: {
+            name: "listVSCodeCommands",
+            extensionRequired: true,
+            description: "List all registered VS Code commands (up to 2000). Filter by substring to find IDs.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                $schema: "http://json-schema.org/draft-07/schema#",
+                type: "object",
+                properties: {
+                    filter: {
+                        type: "string",
+                        description: "Optional substring filter on command IDs",
+                    },
+                },
+                additionalProperties: false,
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    commands: { type: "array", items: { type: "string" } },
+                    count: { type: "integer" },
+                },
+            },
+        },
+        async handler(args) {
+            if (!extensionClient.isConnected()) {
+                return extensionRequired("listVSCodeCommands");
+            }
+            const filter = typeof args.filter === "string" ? args.filter : undefined;
+            try {
+                const result = await extensionClient.listVSCodeCommands(filter);
+                if (result === null)
+                    return error("Failed to list VS Code commands");
+                return successStructured(result);
+            }
+            catch (err) {
+                if (err instanceof ExtensionTimeoutError) {
+                    return error("Extension timed out listing commands");
+                }
+                throw err;
+            }
+        },
+    };
+}
+//# sourceMappingURL=vscodeCommands.js.map

package/dist/tools/vscodeCommands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vscodeCommands.js","sourceRoot":"","sources":["../../src/tools/vscodeCommands.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,EACL,iBAAiB,EACjB,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,MAAM,UAAU,8BAA8B,CAC5C,eAAgC,EAChC,MAAc;IAEd,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,sBAAsB;YAC5B,iBAAiB,EAAE,IAAI;YACvB,WAAW,EACT,wEAAwE;YAC1E,WAAW,EAAE;gBACX,OAAO,EAAE,yCAAyC;gBAClD,IAAI,EAAE,QAAiB;gBACvB,QAAQ,EAAE,CAAC,SAAS,CAAC;gBACrB,UAAU,EAAE;oBACV,OAAO,EAAE;wBACP,IAAI,EAAE,QAAiB;wBACvB,WAAW,EAAE,+BAA+B;qBAC7C;oBACD,IAAI,EAAE;wBACJ,IAAI,EAAE,OAAgB;wBACtB,WAAW,EAAE,kCAAkC;wBAC/C,KAAK,EAAE,EAAE;qBACV;iBACF;gBACD,oBAAoB,EAAE,KAAc;aACrC;YACD,YAAY,EAAE;gBACZ,IAAI,EAAE,QAAQ;aACf;SACF;QACD,KAAK,CAAC,OAAO,CAAC,IAA6B;YACzC,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,EAAE,CAAC;gBACnC,OAAO,iBAAiB,CAAC,sBAAsB,CAAC,CAAC;YACnD,CAAC;YACD,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;YAEpD,sFAAsF;YACtF,yFAAyF;YACzF,IAAI,MAAM,CAAC,sBAAsB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC/C,OAAO,KAAK,CACV,uDAAuD;oBACrD,uEAAuE;oBACvE,2DAA2D,CAC9D,CAAC;YACJ,CAAC;YACD,2EAA2E;YAC3E,kEAAkE;YAClE,MAAM,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YAC3C,IACE,CAAC,MAAM,CAAC,sBAAsB,CAAC,IAAI,CACjC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,YAAY,CACxC,EACD,CAAC;gBACD,OAAO,KAAK,CACV,YAAY,OAAO,0CAA0C;oBAC3D,YAAY,MAAM,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;oBACxD,8BAA8B,OAAO,aAAa,CACrD,CAAC;YACJ,CAAC;YAED,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1D,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,oBAAoB,CACvD,OAAO,EACP,OAAO,CACR,CAAC;gBACF,IAAI,MAAM,KAAK,IAAI;oBACjB,OAAO,KAAK,CAAC,YAAY,OAAO,2BAA2B,CAAC,CAAC;gBAC/D,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;YACnC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,qBAAqB,EAAE,CAAC;oBACzC,OAAO,KAAK,CAAC,kCAAkC,OAAO,GAAG,CAAC,CAAC;gBAC7D,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,eAAgC;IAC3E,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,oBAAoB;YAC1B,iBAAiB,EAAE,IAAI;YACvB,WAAW,EACT,qFAAqF;YACvF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;YACnC,WAAW,EAAE;gBACX,OAAO,EAAE,yCAAyC;gBAClD,IAAI,EAAE,QAAiB;gBACvB,UAAU,EAAE;oBACV,MAAM,EAAE;wBACN,IAAI,EAAE,QAAiB;wBACvB,WAAW,EAAE,0CAA0C;qBACxD;iBACF;gBACD,oBAAoB,EAAE,KAAc;aACrC;YACD,YAAY,EAAE;gBACZ,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;oBACtD,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;iBAC3B;aACF;SACF;QACD,KAAK,CAAC,OAAO,CAAC,IAA6B;YACzC,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,EAAE,CAAC;gBACnC,OAAO,iBAAiB,CAAC,oBAAoB,CAAC,CAAC;YACjD,CAAC;YACD,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;YACzE,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;gBAChE,IAAI,MAAM,KAAK,IAAI;oBAAE,OAAO,KAAK,CAAC,iCAAiC,CAAC,CAAC;gBACrE,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;YACnC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,qBAAqB,EAAE,CAAC;oBACzC,OAAO,KAAK,CAAC,sCAAsC,CAAC,CAAC;gBACvD,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/vscodeTasks.d.ts

@@ -0,0 +1,102 @@
+import { type ExtensionClient } from "../extensionClient.js";
+export declare function createListVSCodeTasksTool(extensionClient: ExtensionClient): {
+    schema: {
+        name: string;
+        extensionRequired: boolean;
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+        };
+        inputSchema: {
+            type: "object";
+            properties: {
+                type: {
+                    type: "string";
+                    description: string;
+                };
+            };
+            additionalProperties: false;
+        };
+        outputSchema: {
+            type: string;
+            properties: {
+                tasks: {
+                    type: string;
+                };
+            };
+        };
+    };
+    handler: (args: Record<string, unknown>, _signal?: AbortSignal) => Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        structuredContent: unknown;
+    } | {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError: true;
+    }>;
+};
+export declare function createRunVSCodeTaskTool(extensionClient: ExtensionClient): {
+    schema: {
+        name: string;
+        extensionRequired: boolean;
+        description: string;
+        annotations: {
+            destructiveHint: boolean;
+        };
+        inputSchema: {
+            type: "object";
+            required: string[];
+            properties: {
+                name: {
+                    type: "string";
+                    description: string;
+                };
+                type: {
+                    type: "string";
+                    description: string;
+                };
+                timeout: {
+                    type: "integer";
+                    description: string;
+                };
+            };
+            additionalProperties: false;
+        };
+        outputSchema: {
+            type: string;
+            properties: {
+                success: {
+                    type: string;
+                };
+                exitCode: {
+                    type: string;
+                };
+                name: {
+                    type: string;
+                };
+                error: {
+                    type: string;
+                };
+            };
+        };
+    };
+    timeoutMs: number;
+    handler: (args: Record<string, unknown>, _signal?: AbortSignal) => Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        structuredContent: unknown;
+    } | {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError: true;
+    }>;
+};

package/dist/tools/vscodeTasks.js

@@ -0,0 +1,110 @@
+import { ExtensionTimeoutError, } from "../extensionClient.js";
+import { error, extensionRequired, optionalInt, optionalString, requireString, successStructured, } from "./utils.js";
+export function createListVSCodeTasksTool(extensionClient) {
+    return {
+        schema: {
+            name: "listVSCodeTasks",
+            extensionRequired: true,
+            description: "List VS Code tasks from tasks.json and extensions. Returns name, type, group, source.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                properties: {
+                    type: {
+                        type: "string",
+                        description: "Filter tasks by type (e.g. 'shell', 'npm')",
+                    },
+                },
+                additionalProperties: false,
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    tasks: { type: "array" },
+                },
+            },
+        },
+        handler: async (args, _signal) => {
+            if (!extensionClient.isConnected()) {
+                return extensionRequired("listVSCodeTasks");
+            }
+            const type = optionalString(args, "type", 64);
+            try {
+                const result = await extensionClient.listTasks(type);
+                if (result === null) {
+                    return error("Extension did not respond — ensure the VS Code extension is running");
+                }
+                return successStructured(result);
+            }
+            catch (err) {
+                if (err instanceof ExtensionTimeoutError) {
+                    return error("Extension timed out — task features may be unavailable");
+                }
+                throw err;
+            }
+        },
+    };
+}
+export function createRunVSCodeTaskTool(extensionClient) {
+    return {
+        schema: {
+            name: "runVSCodeTask",
+            extensionRequired: true,
+            description: "Run VS Code task by name. Waits for completion, returns exit code. For build/test/lint tasks.",
+            annotations: { destructiveHint: true },
+            inputSchema: {
+                type: "object",
+                required: ["name"],
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "Name of the task to run",
+                    },
+                    type: {
+                        type: "string",
+                        description: "Task type filter (e.g. 'shell', 'npm') to disambiguate tasks with the same name",
+                    },
+                    timeout: {
+                        type: "integer",
+                        description: "Seconds to wait for task completion (default: 60, max: 300)",
+                    },
+                },
+                additionalProperties: false,
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    success: { type: "boolean" },
+                    exitCode: { type: "integer" },
+                    name: { type: "string" },
+                    error: { type: "string" },
+                },
+            },
+        },
+        // Extension adds a 5s buffer — raise ceiling so response arrives before MCP cancels
+        timeoutMs: 610_000,
+        handler: async (args, _signal) => {
+            if (!extensionClient.isConnected()) {
+                return extensionRequired("runVSCodeTask");
+            }
+            const name = requireString(args, "name", 256);
+            const type = optionalString(args, "type", 256);
+            const timeoutSec = optionalInt(args, "timeout", 1, 300) ?? 60;
+            const timeoutMs = timeoutSec * 1_000;
+            try {
+                const result = await extensionClient.runTask(name, type, timeoutMs);
+                if (result === null) {
+                    return error("Extension did not respond — ensure the VS Code extension is running");
+                }
+                return successStructured(result);
+            }
+            catch (err) {
+                if (err instanceof ExtensionTimeoutError) {
+                    return error("Extension timed out waiting for task completion");
+                }
+                throw err;
+            }
+        },
+    };
+}
+//# sourceMappingURL=vscodeTasks.js.map

package/dist/tools/vscodeTasks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vscodeTasks.js","sourceRoot":"","sources":["../../src/tools/vscodeTasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,EACL,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,MAAM,UAAU,yBAAyB,CAAC,eAAgC;IACxE,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,iBAAiB;YACvB,iBAAiB,EAAE,IAAI;YACvB,WAAW,EACT,uFAAuF;YACzF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;YACnC,WAAW,EAAE;gBACX,IAAI,EAAE,QAAiB;gBACvB,UAAU,EAAE;oBACV,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAiB;wBACvB,WAAW,EAAE,4CAA4C;qBAC1D;iBACF;gBACD,oBAAoB,EAAE,KAAc;aACrC;YACD,YAAY,EAAE;gBACZ,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;iBACzB;aACF;SACF;QACD,OAAO,EAAE,KAAK,EAAE,IAA6B,EAAE,OAAqB,EAAE,EAAE;YACtE,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,EAAE,CAAC;gBACnC,OAAO,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;YAC9C,CAAC;YACD,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;YAC9C,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;gBACrD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;oBACpB,OAAO,KAAK,CACV,qEAAqE,CACtE,CAAC;gBACJ,CAAC;gBACD,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;YACnC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,qBAAqB,EAAE,CAAC;oBACzC,OAAO,KAAK,CACV,wDAAwD,CACzD,CAAC;gBACJ,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,eAAgC;IACtE,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,eAAe;YACrB,iBAAiB,EAAE,IAAI;YACvB,WAAW,EACT,+FAA+F;YACjG,WAAW,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE;YACtC,WAAW,EAAE;gBACX,IAAI,EAAE,QAAiB;gBACvB,QAAQ,EAAE,CAAC,MAAM,CAAC;gBAClB,UAAU,EAAE;oBACV,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAiB;wBACvB,WAAW,EAAE,yBAAyB;qBACvC;oBACD,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAiB;wBACvB,WAAW,EACT,iFAAiF;qBACpF;oBACD,OAAO,EAAE;wBACP,IAAI,EAAE,SAAkB;wBACxB,WAAW,EACT,6DAA6D;qBAChE;iBACF;gBACD,oBAAoB,EAAE,KAAc;aACrC;YACD,YAAY,EAAE;gBACZ,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;oBAC5B,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;oBAC7B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACxB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;iBAC1B;aACF;SACF;QACD,oFAAoF;QACpF,SAAS,EAAE,OAAO;QAClB,OAAO,EAAE,KAAK,EAAE,IAA6B,EAAE,OAAqB,EAAE,EAAE;YACtE,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,EAAE,CAAC;gBACnC,OAAO,iBAAiB,CAAC,eAAe,CAAC,CAAC;YAC5C,CAAC;YACD,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;YAC9C,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;YAC/C,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;YAC9D,MAAM,SAAS,GAAG,UAAU,GAAG,KAAK,CAAC;YAErC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;gBACpE,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;oBACpB,OAAO,KAAK,CACV,qEAAqE,CACtE,CAAC;gBACJ,CAAC;gBACD,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;YACnC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,qBAAqB,EAAE,CAAC;oBACzC,OAAO,KAAK,CAAC,iDAAiD,CAAC,CAAC;gBAClE,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/watchDiagnostics.d.ts

@@ -0,0 +1,64 @@
+import type { ExtensionClient } from "../extensionClient.js";
+import type { ProbeResults } from "../probe.js";
+import type { ToolHandler } from "../transport.js";
+export declare function createWatchDiagnosticsTool(workspace: string, extensionClient: ExtensionClient, probes?: ProbeResults, linterFilter?: string[]): {
+    schema: {
+        name: string;
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+        };
+        inputSchema: {
+            $schema: string;
+            type: "object";
+            additionalProperties: false;
+            properties: {
+                filePath: {
+                    type: "string";
+                    description: string;
+                };
+                timeoutMs: {
+                    type: "integer";
+                    description: string;
+                };
+                sinceTimestamp: {
+                    type: "integer";
+                    description: string;
+                };
+            };
+        };
+        outputSchema: {
+            type: string;
+            properties: {
+                changed: {
+                    type: string;
+                };
+                timestamp: {
+                    type: string;
+                };
+                diagnostics: {
+                    type: string;
+                };
+                count: {
+                    type: string;
+                };
+                source: {
+                    type: string;
+                };
+                linters: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                };
+                note: {
+                    type: string;
+                };
+            };
+            required: string[];
+            description: string;
+        };
+    };
+    timeoutMs: number;
+    handler: ToolHandler;
+};

package/dist/tools/watchDiagnostics.js

@@ -0,0 +1,270 @@
+import { uriToAbsPath } from "../fp/brandedTypes.js";
+import { createBlameResolver } from "./blame-utils.js";
+import { biomeLinter } from "./linters/biome.js";
+/** Maximum concurrent git-blame subprocesses per enrichDiagnostics call. */
+const BLAME_CONCURRENCY = 8;
+import { cargoLinter } from "./linters/cargo.js";
+import { eslintLinter } from "./linters/eslint.js";
+import { govetLinter } from "./linters/govet.js";
+import { pyrightLinter } from "./linters/pyright.js";
+import { ruffLinter } from "./linters/ruff.js";
+import { typescriptLinter } from "./linters/typescript.js";
+import { optionalInt, optionalString, resolveFilePath, successStructured, toFileUri, } from "./utils.js";
+const ALL_LINTERS = [
+    typescriptLinter,
+    eslintLinter,
+    pyrightLinter,
+    ruffLinter,
+    cargoLinter,
+    govetLinter,
+    biomeLinter,
+];
+export function createWatchDiagnosticsTool(workspace, extensionClient, probes, linterFilter) {
+    // Per-instance blame cache — scoped to this tool instance to prevent
+    // cross-test pollution. Backed by the shared blame-utils helper.
+    const { getIntroducedByCommit } = createBlameResolver(workspace);
+    // Per-instance diagnostic history: "file:line:message_prefix" → { firstSeenAt, recurrenceCount }
+    // Capped to prevent unbounded growth in long-running sessions.
+    const DIAG_HISTORY_MAX_SIZE = 5_000;
+    const diagHistory = new Map();
+    async function enrichOneDiagnostic(d) {
+        const file = typeof d.file === "string" ? d.file : "";
+        const line = typeof d.line === "number"
+            ? d.line
+            : typeof d.range === "object" && d.range !== null
+                ? (d.range.start?.line ?? 0)
+                : 0;
+        // Truncate message to 120 chars to keep map keys bounded
+        const msgRaw = typeof d.message === "string" ? d.message : "";
+        const message = msgRaw.slice(0, 120);
+        const key = `${file}:${line}:${message}`;
+        const now = Date.now();
+        const existing = diagHistory.get(key);
+        if (existing) {
+            existing.recurrenceCount += 1;
+        }
+        else {
+            // Evict oldest entry before inserting when at cap
+            if (diagHistory.size >= DIAG_HISTORY_MAX_SIZE) {
+                const oldest = diagHistory.keys().next().value;
+                if (oldest !== undefined)
+                    diagHistory.delete(oldest);
+            }
+            diagHistory.set(key, { firstSeenAt: now, recurrenceCount: 1 });
+        }
+        const entry = diagHistory.get(key) ?? {
+            firstSeenAt: now,
+            recurrenceCount: 1,
+        };
+        const enriched = {
+            ...d,
+            firstSeenAt: entry.firstSeenAt,
+            recurrenceCount: entry.recurrenceCount,
+        };
+        if (file && line > 0) {
+            const commit = await getIntroducedByCommit(file, line);
+            if (commit)
+                enriched.introducedByCommit = commit;
+        }
+        return enriched;
+    }
+    async function enrichDiagnostics(diagnostics) {
+        // Process in batches to cap concurrent git-blame subprocesses
+        const results = [];
+        for (let i = 0; i < diagnostics.length; i += BLAME_CONCURRENCY) {
+            const batch = diagnostics.slice(i, i + BLAME_CONCURRENCY);
+            const enriched = await Promise.all(batch.map(enrichOneDiagnostic));
+            results.push(...enriched);
+        }
+        return results;
+    }
+    /** Shared error handler for floating enrichment promises. */
+    function onEnrichError(_err) {
+        // enrichDiagnostics is best-effort; swallow errors silently
+    }
+    // Detect available linters at registration time (same logic as getDiagnostics)
+    const availableLinters = probes
+        ? ALL_LINTERS.filter((l) => {
+            if (linterFilter && linterFilter.length > 0) {
+                return linterFilter.includes(l.name) && l.detect(workspace, probes);
+            }
+            return l.detect(workspace, probes);
+        })
+        : [];
+    return {
+        schema: {
+            name: "watchDiagnostics",
+            description: "Long-poll for diagnostic changes. Use after edits to wait for LSP re-validation.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                $schema: "http://json-schema.org/draft-07/schema#",
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    filePath: {
+                        type: "string",
+                        description: "Optional: only watch diagnostics for this specific file",
+                    },
+                    timeoutMs: {
+                        type: "integer",
+                        description: "Max wait time in milliseconds (default: 10000, max: 30000)",
+                    },
+                    sinceTimestamp: {
+                        type: "integer",
+                        description: "Only return if diagnostics changed after this timestamp (from a previous watchDiagnostics call)",
+                    },
+                },
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    changed: { type: "boolean" },
+                    timestamp: { type: "integer" },
+                    diagnostics: { type: "array" },
+                    count: { type: "integer" },
+                    source: { type: "string" },
+                    linters: { type: "array", items: { type: "string" } },
+                    note: { type: "string" },
+                },
+                required: ["changed", "timestamp", "diagnostics", "count"],
+                description: "Diagnostic entries from extension path include firstSeenAt, recurrenceCount, and optional introducedByCommit fields.",
+            },
+        },
+        timeoutMs: 120_000,
+        handler: (async (args, signal) => {
+            const rawPath = optionalString(args, "filePath");
+            const resolvedPath = rawPath
+                ? resolveFilePath(rawPath, workspace)
+                : undefined;
+            const timeoutMs = Math.min(optionalInt(args, "timeoutMs", 1000, 30_000) ?? 10_000, 30_000);
+            const sinceTimestamp = optionalInt(args, "sinceTimestamp", 0, Number.MAX_SAFE_INTEGER);
+            // --- Extension path: real-time long-poll ---
+            if (extensionClient.isConnected()) {
+                // Check if already changed since requested timestamp.
+                // Use explicit undefined check — sinceTimestamp=0 is valid and must not be skipped.
+                if (sinceTimestamp !== undefined &&
+                    extensionClient.lastDiagnosticsUpdate > sinceTimestamp) {
+                    const rawDiagnostics = extensionClient.getCachedDiagnostics(resolvedPath);
+                    const diagnostics = await enrichDiagnostics(rawDiagnostics);
+                    return successStructured({
+                        changed: true,
+                        timestamp: extensionClient.lastDiagnosticsUpdate,
+                        diagnostics,
+                        count: diagnostics.length,
+                    });
+                }
+                // Long-poll: wait for change or timeout
+                return new Promise((resolve) => {
+                    // Fast-path: if the signal is already aborted before we enter the
+                    // executor, settle immediately without allocating the timer or
+                    // registering the diagnostics listener.
+                    if (signal?.aborted) {
+                        const rawDiagnostics = extensionClient.getCachedDiagnostics(resolvedPath);
+                        enrichDiagnostics(rawDiagnostics)
+                            .then((diagnostics) => {
+                            resolve(successStructured({
+                                changed: false,
+                                timestamp: extensionClient.lastDiagnosticsUpdate,
+                                diagnostics,
+                                count: diagnostics.length,
+                            }));
+                        })
+                            .catch(onEnrichError);
+                        return;
+                    }
+                    let settled = false;
+                    // All cleanup-state variables are fully assigned BEFORE any listener
+                    // registration or TOCTOU re-check so that cleanup() is safe to call
+                    // from settle() at any point after this block.
+                    let timer;
+                    let abortHandler;
+                    let unsubscribe;
+                    const cleanup = () => {
+                        if (timer !== undefined)
+                            clearTimeout(timer);
+                        if (abortHandler !== undefined)
+                            signal?.removeEventListener("abort", abortHandler);
+                        unsubscribe?.();
+                    };
+                    const settle = (changed) => {
+                        if (settled)
+                            return;
+                        settled = true;
+                        cleanup();
+                        const rawDiagnostics = extensionClient.getCachedDiagnostics(resolvedPath);
+                        enrichDiagnostics(rawDiagnostics)
+                            .then((diagnostics) => {
+                            resolve(successStructured({
+                                changed,
+                                timestamp: extensionClient.lastDiagnosticsUpdate,
+                                diagnostics,
+                                count: diagnostics.length,
+                            }));
+                        })
+                            .catch(onEnrichError);
+                    };
+                    // Step 1: set up the timeout timer FIRST so cleanup() is never called
+                    // with an uninitialized timer reference.
+                    timer = setTimeout(() => settle(false), timeoutMs);
+                    // Step 2: set up the abort handler and register it BEFORE subscribing
+                    // so cleanup() can always remove it.
+                    abortHandler = () => settle(false);
+                    signal?.addEventListener("abort", abortHandler);
+                    // Step 3: register the diagnostics listener.
+                    unsubscribe = extensionClient.addDiagnosticsListener((file) => {
+                        if (!resolvedPath || file === resolvedPath) {
+                            settle(true);
+                        }
+                    });
+                    // Step 4 (TOCTOU re-check): MUST happen AFTER subscription — a
+                    // diagnosticsChanged notification could have fired between the initial
+                    // timestamp check (above) and addDiagnosticsListener (just above).
+                    // If so, settle immediately rather than waiting for timeout.
+                    if (sinceTimestamp !== undefined &&
+                        extensionClient.lastDiagnosticsUpdate > sinceTimestamp) {
+                        settle(true);
+                        return;
+                    }
+                });
+            }
+            // --- Native fallback: run CLI linters immediately ---
+            // Cannot replicate real-time watching without the extension; return a point-in-time snapshot.
+            const now = Date.now();
+            if (availableLinters.length === 0) {
+                return successStructured({
+                    changed: false,
+                    timestamp: now,
+                    diagnostics: [],
+                    count: 0,
+                    source: "cli",
+                    note: "No linters detected — install tsc, eslint, or biome to get CLI diagnostics",
+                });
+            }
+            const results = await Promise.all(availableLinters.map((l) => l.run(workspace, signal).catch(() => [])));
+            let diagnostics = results.flat();
+            // Filter by file path if specified
+            if (resolvedPath) {
+                const normalizedUri = toFileUri(resolvedPath);
+                diagnostics = diagnostics.filter((d) => {
+                    const diagUri = d.file.startsWith("file://")
+                        ? d.file
+                        : toFileUri(d.file);
+                    // normalise both sides to AbsPath so file:// vs plain-path mismatches
+                    // are caught without a string-replace
+                    const diagAbs = uriToAbsPath(diagUri);
+                    const normAbs = uriToAbsPath(normalizedUri);
+                    return diagAbs === normAbs;
+                });
+            }
+            return successStructured({
+                changed: true,
+                timestamp: now,
+                diagnostics,
+                count: diagnostics.length,
+                source: "cli",
+                linters: availableLinters.map((l) => l.name),
+            });
+        }),
+    };
+}
+//# sourceMappingURL=watchDiagnostics.js.map