patchwork-os 0.2.0-alpha.0

package/dist/tools/getAIComments.d.ts

@@ -0,0 +1,79 @@
+import { type ExtensionClient } from "../extensionClient.js";
+export declare function createGetAICommentsTool(extensionClient: ExtensionClient): {
+    schema: {
+        name: string;
+        description: string;
+        extensionRequired: boolean;
+        annotations: {
+            readOnlyHint: boolean;
+        };
+        inputSchema: {
+            $schema: string;
+            type: "object";
+            additionalProperties: false;
+        };
+        outputSchema: {
+            type: "object";
+            properties: {
+                count: {
+                    type: "integer";
+                };
+                comments: {
+                    type: "array";
+                    items: {
+                        type: "object";
+                        properties: {
+                            file: {
+                                type: "string";
+                            };
+                            line: {
+                                type: "integer";
+                            };
+                            comment: {
+                                type: "string";
+                            };
+                            syntax: {
+                                type: "string";
+                            };
+                            fullLine: {
+                                type: "string";
+                            };
+                            severity: {
+                                type: "string";
+                                enum: string[];
+                            };
+                        };
+                        required: string[];
+                    };
+                };
+                summary: {
+                    type: "object";
+                    additionalProperties: {
+                        type: "integer";
+                    };
+                };
+                message: {
+                    type: "string";
+                };
+                tip: {
+                    type: "string";
+                };
+            };
+            required: string[];
+        };
+    };
+    timeoutMs: number;
+    handler(): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        structuredContent: unknown;
+    } | {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError: true;
+    }>;
+};

package/dist/tools/getAIComments.js

@@ -0,0 +1,93 @@
+import { ExtensionTimeoutError, } from "../extensionClient.js";
+import { error, successStructured } from "./utils.js";
+export function createGetAICommentsTool(extensionClient) {
+    return {
+        schema: {
+            name: "getAIComments",
+            description: "Scan open docs for AI-tagged comments (// AI: <severity>: <msg>). Severity: fix/todo/question/warn/task.",
+            extensionRequired: true,
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                $schema: "http://json-schema.org/draft-07/schema#",
+                type: "object",
+                additionalProperties: false,
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    count: { type: "integer" },
+                    comments: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                file: { type: "string" },
+                                line: { type: "integer" },
+                                comment: { type: "string" },
+                                syntax: { type: "string" },
+                                fullLine: { type: "string" },
+                                severity: {
+                                    type: "string",
+                                    enum: ["fix", "todo", "question", "warn", "task"],
+                                },
+                            },
+                            required: ["file", "line", "comment", "syntax", "fullLine"],
+                        },
+                    },
+                    summary: {
+                        type: "object",
+                        additionalProperties: { type: "integer" },
+                    },
+                    message: { type: "string" },
+                    tip: { type: "string" },
+                },
+                required: ["count", "comments"],
+            },
+        },
+        timeoutMs: 10_000,
+        async handler() {
+            if (!extensionClient.isConnected()) {
+                return error("Extension not connected. Open a VS Code/Windsurf/Cursor window with the claude-ide-bridge extension active.");
+            }
+            let comments = null;
+            try {
+                comments = await extensionClient.getAIComments();
+            }
+            catch (err) {
+                if (!(err instanceof ExtensionTimeoutError))
+                    throw err;
+                return error("Extension timed out while scanning for AI comments. Try again.");
+            }
+            if (comments === null) {
+                return error("Extension disconnected while scanning for AI comments.");
+            }
+            // Update the shared cache so createGithubIssueFromAIComment can find them
+            extensionClient.latestAIComments.clear();
+            for (const comment of comments) {
+                const existing = extensionClient.latestAIComments.get(comment.file) ?? [];
+                existing.push(comment);
+                extensionClient.latestAIComments.set(comment.file, existing);
+            }
+            if (comments.length === 0) {
+                return successStructured({
+                    count: 0,
+                    comments: [],
+                    message: "No AI comments found in open documents. Add `// AI: fix: <message>` style comments to flag work items.",
+                });
+            }
+            // Group by severity for a useful summary
+            const bySeverity = {};
+            for (const c of comments) {
+                const sev = c.severity ?? "task";
+                bySeverity[sev] = (bySeverity[sev] ?? 0) + 1;
+            }
+            return successStructured({
+                count: comments.length,
+                comments,
+                summary: bySeverity,
+                tip: "Use createGithubIssueFromAIComment to file a GitHub issue for a specific comment.",
+            });
+        },
+    };
+}
+//# sourceMappingURL=getAIComments.js.map

package/dist/tools/getAIComments.js.map

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

package/dist/tools/getAnalyticsReport.d.ts

@@ -0,0 +1,102 @@
+import type { ActivityLog } from "../activityLog.js";
+import type { ClaudeOrchestrator } from "../claudeOrchestrator.js";
+/**
+ * getAnalyticsReport — surfaces existing analytics data as structured output.
+ *
+ * No new data collection — exposes what ActivityLog and ClaudeOrchestrator
+ * already capture: top tools by call count, lifecycle hook events in the last
+ * windowHours, and recent automation task summaries.
+ */
+export declare function createGetAnalyticsReportTool(activityLog: ActivityLog, orchestrator: ClaudeOrchestrator | null): {
+    schema: {
+        name: string;
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+        };
+        inputSchema: {
+            type: "object";
+            additionalProperties: false;
+            properties: {
+                windowHours: {
+                    type: "number";
+                    description: string;
+                    minimum: number;
+                    maximum: number;
+                };
+            };
+        };
+        outputSchema: {
+            type: string;
+            properties: {
+                generatedAt: {
+                    type: string;
+                };
+                windowHours: {
+                    type: string;
+                };
+                topTools: {
+                    type: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            tool: {
+                                type: string;
+                            };
+                            calls: {
+                                type: string;
+                            };
+                            errors: {
+                                type: string;
+                            };
+                            avgMs: {
+                                type: string;
+                            };
+                        };
+                        required: string[];
+                    };
+                };
+                hooksLast24h: {
+                    type: string;
+                };
+                recentAutomationTasks: {
+                    type: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            id: {
+                                type: string;
+                            };
+                            status: {
+                                type: string;
+                            };
+                            triggerSource: {
+                                type: string;
+                            };
+                            durationMs: {
+                                type: string;
+                            };
+                            createdAt: {
+                                type: string;
+                            };
+                        };
+                        required: string[];
+                    };
+                };
+                hint: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    handler: (params: {
+        windowHours?: number;
+    }) => Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        structuredContent: unknown;
+    }>;
+};

package/dist/tools/getAnalyticsReport.js

@@ -0,0 +1,137 @@
+import { successStructured } from "./utils.js";
+const DEFAULT_WINDOW_HOURS = 24;
+const TOP_TOOLS_LIMIT = 10;
+const RECENT_TASKS_LIMIT = 20;
+const TIMELINE_QUERY_LIMIT = 500;
+/**
+ * getAnalyticsReport — surfaces existing analytics data as structured output.
+ *
+ * No new data collection — exposes what ActivityLog and ClaudeOrchestrator
+ * already capture: top tools by call count, lifecycle hook events in the last
+ * windowHours, and recent automation task summaries.
+ */
+export function createGetAnalyticsReportTool(activityLog, orchestrator) {
+    return {
+        schema: {
+            name: "getAnalyticsReport",
+            description: "Session analytics: top tools by call count, hook events, recent automation tasks.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    windowHours: {
+                        type: "number",
+                        description: "How many hours back to count lifecycle hook events. Default: 24.",
+                        minimum: 1,
+                        maximum: 168,
+                    },
+                },
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    generatedAt: { type: "string" },
+                    windowHours: { type: "number" },
+                    topTools: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                tool: { type: "string" },
+                                calls: { type: "number" },
+                                errors: { type: "number" },
+                                avgMs: { type: "number" },
+                            },
+                            required: ["tool", "calls", "errors", "avgMs"],
+                        },
+                    },
+                    hooksLast24h: { type: "number" },
+                    recentAutomationTasks: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                id: { type: "string" },
+                                status: { type: "string" },
+                                triggerSource: { type: "string" },
+                                durationMs: { type: "number" },
+                                createdAt: { type: "string" },
+                            },
+                            required: ["id", "status", "createdAt"],
+                        },
+                    },
+                    hint: { type: "string" },
+                },
+                required: [
+                    "generatedAt",
+                    "windowHours",
+                    "topTools",
+                    "hooksLast24h",
+                    "recentAutomationTasks",
+                    "hint",
+                ],
+            },
+        },
+        handler: async (params) => {
+            const windowHours = typeof params.windowHours === "number" && params.windowHours >= 1
+                ? params.windowHours
+                : DEFAULT_WINDOW_HOURS;
+            // --- topTools: from activityLog.stats(), sorted by count desc, top 10 ---
+            const statsMap = activityLog.stats();
+            const topTools = Object.entries(statsMap)
+                .map(([tool, s]) => ({
+                tool,
+                calls: s.count,
+                errors: s.errors,
+                avgMs: s.avgDurationMs,
+            }))
+                .sort((a, b) => b.calls - a.calls)
+                .slice(0, TOP_TOOLS_LIMIT);
+            // --- hooksLast24h: lifecycle entries within windowHours ---
+            const cutoff = Date.now() - windowHours * 3_600 * 1_000;
+            const timeline = activityLog.queryTimeline({
+                last: TIMELINE_QUERY_LIMIT,
+            });
+            const hooksLast24h = timeline.filter((e) => e.kind === "lifecycle" && new Date(e.timestamp).getTime() > cutoff).length;
+            // --- recentAutomationTasks: last 20 tasks from orchestrator ---
+            const recentAutomationTasks = orchestrator !== null
+                ? orchestrator
+                    .list()
+                    .sort((a, b) => b.createdAt - a.createdAt)
+                    .slice(0, RECENT_TASKS_LIMIT)
+                    .map((t) => ({
+                    id: t.id,
+                    status: t.status,
+                    ...(t.triggerSource !== undefined && {
+                        triggerSource: t.triggerSource,
+                    }),
+                    ...(t.startedAt !== undefined &&
+                        t.doneAt !== undefined && {
+                        durationMs: t.doneAt - t.startedAt,
+                    }),
+                    createdAt: new Date(t.createdAt).toISOString(),
+                    // Include truncated output so sidebar can show it without
+                    // hitting the session-scoped getClaudeTaskStatus tool.
+                    ...(t.output !== undefined && {
+                        output: t.output.slice(0, 2000),
+                    }),
+                    ...(t.errorMessage !== undefined && {
+                        errorMessage: t.errorMessage,
+                    }),
+                }))
+                : [];
+            return successStructured({
+                generatedAt: new Date().toISOString(),
+                windowHours,
+                topTools,
+                hooksLast24h,
+                recentAutomationTasks,
+                hint: "Use windowHours to adjust the hook-event lookback window. " +
+                    "topTools shows all-time session stats. " +
+                    "recentAutomationTasks lists the last 20 orchestrator tasks sorted newest first.",
+            });
+        },
+    };
+}
+//# sourceMappingURL=getAnalyticsReport.js.map

package/dist/tools/getAnalyticsReport.js.map

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

package/dist/tools/getArchitectureContext.d.ts

@@ -0,0 +1,85 @@
+/**
+ * getArchitectureContext — codebase-memory-augmented architectural summary tool.
+ *
+ * Provides a compact architectural overview by describing what codebase-memory
+ * queries to run. This tool acts as a guided prompt for Claude to invoke the
+ * codebase-memory MCP tools in sequence and synthesize the results into a
+ * structured architectural summary.
+ *
+ * Designed to be called at session start or via the onInstructionsLoaded hook
+ * to give every session architectural grounding without re-deriving it from source.
+ */
+export declare function createGetArchitectureContextTool(workspace: string): {
+    schema: {
+        name: string;
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+        };
+        inputSchema: {
+            type: "object";
+            properties: {
+                aspects: {
+                    type: "array";
+                    items: {
+                        type: "string";
+                    };
+                    description: string;
+                };
+                maxNodes: {
+                    type: "integer";
+                    description: string;
+                    minimum: number;
+                    maximum: number;
+                };
+            };
+            additionalProperties: false;
+        };
+        outputSchema: {
+            type: string;
+            properties: {
+                workspace: {
+                    type: string;
+                };
+                aspects: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                };
+                queries: {
+                    type: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            aspect: {
+                                type: string;
+                            };
+                            tool: {
+                                type: string;
+                            };
+                            params: {
+                                type: string;
+                            };
+                            description: {
+                                type: string;
+                            };
+                        };
+                        required: string[];
+                    };
+                };
+                hint: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    handler: (args: Record<string, unknown>) => Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        structuredContent: unknown;
+    }>;
+};

package/dist/tools/getArchitectureContext.js

@@ -0,0 +1,135 @@
+import { successStructured } from "./utils.js";
+/**
+ * getArchitectureContext — codebase-memory-augmented architectural summary tool.
+ *
+ * Provides a compact architectural overview by describing what codebase-memory
+ * queries to run. This tool acts as a guided prompt for Claude to invoke the
+ * codebase-memory MCP tools in sequence and synthesize the results into a
+ * structured architectural summary.
+ *
+ * Designed to be called at session start or via the onInstructionsLoaded hook
+ * to give every session architectural grounding without re-deriving it from source.
+ */
+export function createGetArchitectureContextTool(workspace) {
+    return {
+        schema: {
+            name: "getArchitectureContext",
+            description: "Architectural overview via codebase-memory graph: module boundaries, dependencies, " +
+                "ADRs, hotspot files. Returns structured query plan. Requires codebase-memory connected.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                properties: {
+                    aspects: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Aspects to include: 'modules', 'dependencies', 'adrs', 'hotspots', 'all' (default: ['all'])",
+                    },
+                    maxNodes: {
+                        type: "integer",
+                        description: "Max graph nodes to return per aspect (default: 20)",
+                        minimum: 1,
+                        maximum: 100,
+                    },
+                },
+                additionalProperties: false,
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    workspace: { type: "string" },
+                    aspects: { type: "array", items: { type: "string" } },
+                    queries: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                aspect: { type: "string" },
+                                tool: { type: "string" },
+                                params: { type: "object" },
+                                description: { type: "string" },
+                            },
+                            required: ["aspect", "tool", "params", "description"],
+                        },
+                    },
+                    hint: { type: "string" },
+                },
+                required: ["workspace", "aspects", "queries", "hint"],
+            },
+        },
+        handler: async (args) => {
+            const aspectsArg = Array.isArray(args.aspects)
+                ? args.aspects
+                : ["all"];
+            const maxNodes = typeof args.maxNodes === "number"
+                ? Math.min(Math.max(args.maxNodes, 1), 100)
+                : 20;
+            const includeAll = aspectsArg.includes("all");
+            const include = (aspect) => includeAll || aspectsArg.includes(aspect);
+            // Derive project ID from workspace path (mirrors codebase-memory naming convention)
+            const projectId = workspace
+                .replace(/^\/+/, "")
+                .replace(/\//g, "-")
+                .replace(/\s+/g, " ");
+            const queries = [];
+            if (include("modules") || include("dependencies")) {
+                queries.push({
+                    aspect: "architecture",
+                    tool: "mcp__codebase-memory__get_architecture",
+                    params: {
+                        project: projectId,
+                        aspects: ["packages", "services", "dependencies"],
+                    },
+                    description: "Module boundaries, service topology, and dependency direction",
+                });
+            }
+            if (include("adrs")) {
+                queries.push({
+                    aspect: "adrs",
+                    tool: "mcp__codebase-memory__manage_adr",
+                    params: { project: projectId, mode: "list" },
+                    description: "Active Architecture Decision Records — design constraints and rationale",
+                });
+            }
+            if (include("hotspots")) {
+                queries.push({
+                    aspect: "hotspots",
+                    tool: "mcp__codebase-memory__query_graph",
+                    params: {
+                        project: projectId,
+                        query: "MATCH (f:File)-[r:FILE_CHANGES_WITH]-(g:File) RETURN f.path, count(r) as changes ORDER BY changes DESC LIMIT " +
+                            maxNodes,
+                    },
+                    description: "Files that frequently change together — high coupling / churn risk",
+                });
+            }
+            if (include("modules")) {
+                queries.push({
+                    aspect: "god-objects",
+                    tool: "mcp__codebase-memory__query_graph",
+                    params: {
+                        project: projectId,
+                        query: "MATCH (n)-[r:CALLS]->(m) WITH m, count(r) as inbound WHERE inbound > 10 RETURN m.name, m.path, inbound ORDER BY inbound DESC LIMIT " +
+                            maxNodes,
+                    },
+                    description: "Highly-called nodes — God objects or core utilities",
+                });
+            }
+            const activeAspects = includeAll
+                ? ["architecture", "adrs", "hotspots", "god-objects"]
+                : aspectsArg;
+            return successStructured({
+                workspace,
+                aspects: activeAspects,
+                queries,
+                hint: "Run each query in sequence using the specified tool. " +
+                    "Synthesize results into: (1) module ownership map, " +
+                    "(2) dependency direction summary, " +
+                    "(3) active design constraints from ADRs, " +
+                    "(4) high-risk files to watch. " +
+                    "If codebase-memory is not indexed, run mcp__codebase-memory__index_repository first.",
+            });
+        },
+    };
+}
+//# sourceMappingURL=getArchitectureContext.js.map

package/dist/tools/getArchitectureContext.js.map

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