@weavetab/plugin-github 1.0.1 → 1.2.0

package/dist/repoContext.d.ts

@@ -1,21 +1,18 @@
-import type { CdpSession, GithubError, RepoContext } from "./types.js";
+import type { CdpSession, DetailedRepoContext, GithubError, RepoContext } from "./types.js";
 /**
- * Parse a repo slug from a string that can be:
- *  - "owner/repo"
- *  - "https://github.com/owner/repo[/anything]"
- *
- * Returns null (instead of throwing) for any non-string input so callers never
- * encounter `TypeError: slug.trim is not a function`.
+ * Parses deep context from a GitHub URL string.
+ */
+export declare function parseDetailedUrl(urlStr: string): DetailedRepoContext | null;
+/**
+ * Parse a repo slug or full URL into a basic RepoContext.
  */
 export declare function parseRepoSlug(slug: unknown): RepoContext | null;
+/**
+ * Resolve detailed GitHub repository and route context.
+ */
+export declare function getDetailedRepoContext(session: CdpSession | undefined, repoSlug?: unknown): Promise<DetailedRepoContext | GithubError>;
 /**
  * Resolve the current GitHub repository target.
- *
- * @param session  - CDP session used only to read the active tab URL.
- * @param repoSlug - Optional "owner/repo" or full GitHub URL. When provided, it
- *                   is used directly and the active tab is never read or mutated.
- *
- * GitHub data is always fetched over HTTP, so the active tab is never navigated.
  */
 export declare function getRepoContext(session: CdpSession | undefined, repoSlug?: unknown): Promise<RepoContext | GithubError>;
 export declare function isGithubError(result: unknown): result is GithubError;

package/dist/repoContext.js

@@ -1,31 +1,58 @@
 /**
- * Parse a repo slug from a string that can be:
- *  - "owner/repo"
- *  - "https://github.com/owner/repo[/anything]"
- *
- * Returns null (instead of throwing) for any non-string input so callers never
- * encounter `TypeError: slug.trim is not a function`.
+ * Parses deep context from a GitHub URL string.
+ */
+export function parseDetailedUrl(urlStr) {
+    try {
+        const u = new URL(urlStr);
+        if (u.hostname !== "github.com" && u.hostname !== "www.github.com")
+            return null;
+        const parts = u.pathname.split("/").filter(Boolean);
+        if (parts.length < 2)
+            return null;
+        const owner = parts[0];
+        const repo = parts[1];
+        const section = parts[2];
+        const ctx = { owner, repo, section };
+        if (!section)
+            return ctx;
+        if (section === "pull" && parts[3]) {
+            const num = parseInt(parts[3], 10);
+            if (!Number.isNaN(num))
+                ctx.pullNumber = num;
+        }
+        else if (section === "issues" && parts[3]) {
+            const num = parseInt(parts[3], 10);
+            if (!Number.isNaN(num))
+                ctx.issueNumber = num;
+        }
+        else if (section === "commit" && parts[3]) {
+            ctx.commitSha = parts[3];
+        }
+        else if ((section === "blob" || section === "tree") && parts[3]) {
+            ctx.branch = parts[3];
+            if (parts.length > 4) {
+                ctx.filePath = parts.slice(4).join("/");
+            }
+        }
+        return ctx;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse a repo slug or full URL into a basic RepoContext.
  */
 export function parseRepoSlug(slug) {
-    // Runtime guard: MCP argument dispatch can forward an object / number / null
-    // when the model omits the field in some call patterns.
     if (typeof slug !== "string")
         return null;
     const trimmed = slug.trim();
     if (!trimmed)
         return null;
-    // Full GitHub URL
-    try {
-        const u = new URL(trimmed);
-        if (u.hostname === "github.com" || u.hostname === "www.github.com") {
-            const parts = u.pathname.split("/").filter(Boolean);
-            if (parts.length >= 2)
-                return { owner: parts[0], repo: parts[1] };
-        }
-    }
-    catch {
-        /* not a URL — fall through to shorthand parse */
-    }
+    // Try parsing full URL first
+    const detailed = parseDetailedUrl(trimmed);
+    if (detailed)
+        return { owner: detailed.owner, repo: detailed.repo };
     // "owner/repo" shorthand
     const parts = trimmed.split("/").filter(Boolean);
     if (parts.length >= 2)
@@ -33,18 +60,14 @@ export function parseRepoSlug(slug) {
     return null;
 }
 /**
- * Resolve the current GitHub repository target.
- *
- * @param session  - CDP session used only to read the active tab URL.
- * @param repoSlug - Optional "owner/repo" or full GitHub URL. When provided, it
- *                   is used directly and the active tab is never read or mutated.
- *
- * GitHub data is always fetched over HTTP, so the active tab is never navigated.
+ * Resolve detailed GitHub repository and route context.
  */
-export async function getRepoContext(session, repoSlug) {
+export async function getDetailedRepoContext(session, repoSlug) {
     const slugStr = typeof repoSlug === "string" && repoSlug.trim() !== "" ? repoSlug.trim() : undefined;
-    // Explicit slug wins over the current tab URL.
     if (slugStr) {
+        const detailed = parseDetailedUrl(slugStr);
+        if (detailed)
+            return detailed;
         const parsed = parseRepoSlug(slugStr);
         if (!parsed) {
             return {
@@ -57,7 +80,7 @@ export async function getRepoContext(session, repoSlug) {
     if (!session) {
         return {
             error: "NO_CONTEXT",
-            message: "No active browser session. Pass a 'repo' argument (e.g. \"owner/repo\") or open a github.com repository in the browser.",
+            message: "No active browser session. Pass a 'repo' argument (e.g. \"owner/repo\") or open a github.com page in the browser.",
         };
     }
     let urlStr;
@@ -77,27 +100,20 @@ export async function getRepoContext(session, repoSlug) {
     if (typeof urlStr !== "string" || !urlStr) {
         return { error: "CONTEXT_ERROR", message: "Active tab URL is empty." };
     }
-    let url;
-    try {
-        url = new URL(urlStr);
-    }
-    catch {
-        return { error: "INVALID_URL", message: "Active tab URL is invalid." };
-    }
-    if (url.hostname !== "github.com") {
-        return {
-            error: "NOT_ON_GITHUB_REPO",
-            message: "Navigate to a GitHub repository first, or pass a 'repo' argument (e.g. \"owner/repo\").",
-        };
-    }
-    const parts = url.pathname.split("/").filter(Boolean);
-    if (parts.length < 2) {
+    const detailed = parseDetailedUrl(urlStr);
+    if (!detailed) {
         return {
             error: "NOT_ON_GITHUB_REPO",
-            message: "Navigate to a specific GitHub repository first (e.g. github.com/owner/repo).",
+            message: "Active tab is not on a GitHub repository page. Pass a 'repo' argument (e.g. \"owner/repo\").",
         };
     }
-    return { owner: parts[0], repo: parts[1] };
+    return detailed;
+}
+/**
+ * Resolve the current GitHub repository target.
+ */
+export async function getRepoContext(session, repoSlug) {
+    return getDetailedRepoContext(session, repoSlug);
 }
 export function isGithubError(result) {
     return (!!result &&

package/dist/types.d.ts

@@ -6,7 +6,7 @@
  * and on the isolated storage contract exposed by the plugin runtime.
  */
 import type { PluginStorage } from "@weavetab/sdk";
-/** Minimal CDP client surface used to read the active tab URL. */
+/** Minimal CDP client surface used to read active tab URL and DOM. */
 export interface CdpSession {
     Runtime: {
         evaluate(params: {
@@ -19,11 +19,19 @@ export interface CdpSession {
         }>;
     };
 }
-/** A resolved GitHub repository target. */
+/** A resolved GitHub repository target with optional deep route context. */
 export interface RepoContext {
     owner: string;
     repo: string;
 }
+export interface DetailedRepoContext extends RepoContext {
+    section?: "pull" | "issues" | "blob" | "tree" | "commit" | "releases" | string;
+    issueNumber?: number;
+    pullNumber?: number;
+    commitSha?: string;
+    branch?: string;
+    filePath?: string;
+}
 /** Structured, non-throwing error returned to the MCP layer. */
 export interface GithubError {
     error: string;
@@ -56,12 +64,53 @@ export interface GithubRunContext {
     cacheTtlMs: number;
     maxReadLines: number;
     defaultIssueLimit: number;
+    token?: string;
+}
+export interface GithubAnalyzeArgs {
+    repo?: string;
+}
+export interface GithubReadArgs {
+    repo?: string;
+    paths?: string[];
+    branch?: string;
+    line_range?: number[];
+}
+export interface GithubIssuesArgs {
+    repo?: string;
+    number?: number;
+    search?: string;
+    labels?: string[];
+    state?: "open" | "closed" | "all";
+    limit?: number;
+}
+export interface GithubPullRequestArgs {
+    repo?: string;
+    number?: number;
+    state?: "open" | "closed" | "all";
+    limit?: number;
+}
+export interface GithubDiffArgs {
+    repo?: string;
+    pull_number?: number;
+    commit_sha?: string;
+    base?: string;
+    head?: string;
+    format?: "diff" | "patch";
+}
+export interface DiffStats {
+    files_changed: string[];
+    additions: number;
+    deletions: number;
+}
+export interface GithubActiveTabArgs {
+    scope?: "auto" | "summary" | "files" | "comments" | "raw";
 }
-/** The single tool's argument shape. */
+/** Backwards-compatible legacy single tool argument shape. */
 export interface GithubToolArgs {
     action: "analyze" | "read" | "issues" | "pr";
     repo?: string;
     paths?: string[];
+    branch?: string;
     line_range?: number[];
     number?: number;
     search?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@weavetab/plugin-github",
-  "version": "1.0.1",
-  "description": "Official Weavetab GitHub plugin - analyze repository structure, read raw source files, search and inspect issues, and examine pull requests over the GitHub API without burning browser turns.",
+  "version": "1.2.0",
+  "description": "Official Weavetab GitHub plugin - modular repository analysis, raw source reads, issues, pull requests, raw diffs, and active-tab DOM inspection without burning browser turns or API quota.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,11 +20,12 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "preflight": "weavetab preflight",
     "test": "node --test test/*.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@weavetab/sdk": "^2.5.1"
+    "@weavetab/sdk": "^2.6.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.0",

package/weavetab.json

@@ -1,11 +1,12 @@
 {
   "$schema": "https://weavetab.dev/schema/plugin.json",
   "name": "@weavetab/plugin-github",
-  "version": "1.0.1",
-  "description": "Official Weavetab GitHub plugin. Analyze repository structure, read raw source files, search and inspect issues, and examine pull requests over the public GitHub REST API — fetched directly over HTTP, so no browser turns are consumed.",
+  "displayName": "GitHub",
+  "version": "1.2.0",
+  "description": "Official Weavetab GitHub plugin. Modular tools to analyze repositories, read raw source files, search issues, inspect pull requests, fetch raw diffs, and inspect active tabs directly without burning browser turns or API quota.",
   "entry": "dist/index.js",
   "engines": {
-    "weavetab": "^2.5.1",
+    "weavetab": ">=2.6.0",
     "node": ">=18.0.0"
   },
   "environments": [
@@ -24,7 +25,8 @@
     "Developer Tools",
     "Repositories",
     "Issues",
-    "Pull Requests"
+    "Pull Requests",
+    "Diff"
   ],
   "links": {
     "github": "https://github.com/weavetab/plugin-github",
@@ -39,11 +41,11 @@
     "config": {
       "read": true,
       "write": true,
-      "reason": "Reads and persists the isolated plugin configuration (cache TTL, read limits, default issue limit) at ~/.weavetab/plugins/@weavetab_plugin-github/config.json."
+      "reason": "Reads and persists plugin configuration (cache TTL, read limits, issue limits, optional token) at ~/.weavetab/plugins/@weavetab_plugin-github/config.json."
     },
     "cdp": {
       "evaluate": true,
-      "reason": "Reads the active tab URL only, to infer the target repository when the optional 'repo' argument is omitted. Never navigates or mutates the page."
+      "reason": "Evaluates active tab URL and DOM on github.com to infer targets or inspect active views without API calls."
     },
     "network": {
       "domains": [
@@ -51,63 +53,161 @@
         "raw.githubusercontent.com",
         "github.com"
       ],
-      "reason": "Fetches repository metadata, file trees, raw source files, issues and pull requests from the public GitHub REST API and raw content CDN."
+      "reason": "Fetches repository metadata, file trees, raw source files, issues, pull requests, and raw git diffs from GitHub REST API, CDN, and web endpoints."
     },
     "tools": {
       "add": true,
-      "reason": "Registers the single 'plugin_github' MCP tool."
+      "reason": "Registers github_analyze, github_read, github_issues, github_pull_request, github_diff, and github_active_tab MCP tools."
     }
   },
   "tools": [
     {
-      "name": "plugin_github",
-      "description": "Interact with GitHub repositories without burning browser turns. Analyze a repo's file tree and README, read raw source files, list/search/inspect issues, and examine pull request details, changed files and comments — all fetched over the GitHub REST API.",
+      "name": "github_analyze",
+      "description": "Analyze a GitHub repository's metadata, default branch, recursive file tree, and README snippet over the GitHub REST API without burning browser turns.",
       "inputSchema": {
         "type": "object",
         "properties": {
-          "action": {
-            "type": "string",
-            "enum": ["analyze", "read", "issues", "pr"],
-            "description": "The GitHub operation to perform. 'analyze' = repository metadata, recursive file tree and README snippet. 'read' = raw file contents (requires 'paths'). 'issues' = list, search or inspect issues. 'pr' = list or inspect pull requests."
-          },
           "repo": {
             "type": "string",
-            "description": "Target repository as an 'owner/repo' slug or a full https://github.com/owner/repo URL. Optional — when omitted, the repository is inferred from the active browser tab (which must be on a github.com repo page)."
-          },
+            "description": "Target repository as 'owner/repo' or full github.com URL. When omitted, inferred from the active browser tab."
+          }
+        }
+      }
+    },
+    {
+      "name": "github_read",
+      "description": "Fetch raw source files from a GitHub repository directly over HTTP without burning browser turns or API search quota.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
           "paths": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "READ ONLY. File paths relative to the repository root to fetch (e.g. ['src/index.ts', 'README.md'])."
+            "description": "File paths relative to the repository root, e.g. ['src/index.ts', 'README.md']."
+          },
+          "repo": {
+            "type": "string",
+            "description": "Target repository as 'owner/repo' or full github.com URL. When omitted, inferred from active tab."
+          },
+          "branch": {
+            "type": "string",
+            "description": "Target branch or tag (defaults to 'main' or cached default branch). Avoids API discovery calls."
           },
           "line_range": {
             "type": "array",
             "items": { "type": "number" },
-            "description": "READ ONLY. Optional [start, end] 1-indexed line range to return from each file. When omitted, files longer than 'maxReadLines' are truncated from the top."
+            "description": "Optional [start, end] 1-indexed line range to return per file."
+          }
+        }
+      }
+    },
+    {
+      "name": "github_issues",
+      "description": "List, search, or inspect issues and comments in a GitHub repository without burning browser turns.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "repo": {
+            "type": "string",
+            "description": "Target repository as 'owner/repo' or full github.com URL."
           },
           "number": {
             "type": "number",
-            "description": "ISSUES / PR ONLY. Issue or pull request number to fetch the full detail and comments for. When omitted, a recent list is returned instead."
+            "description": "Specific issue number to fetch full details and timeline comments for."
           },
           "search": {
             "type": "string",
-            "description": "ISSUES ONLY. Free-text search query to find issues (uses the GitHub Search API, scoped to the target repo)."
+            "description": "Free-text query to search issues in the repository."
           },
           "labels": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "ISSUES ONLY. Restrict results to issues carrying all of the given labels."
+            "description": "Restrict results to these labels."
+          },
+          "state": {
+            "type": "string",
+            "enum": ["open", "closed", "all"],
+            "description": "Filter by issue state (default 'open')."
+          },
+          "limit": {
+            "type": "number",
+            "description": "Maximum number of issues to return (default 5)."
+          }
+        }
+      }
+    },
+    {
+      "name": "github_pull_request",
+      "description": "Examine pull request details, changed files, diff stats, and comments, or list recent pull requests in a GitHub repository without burning browser turns.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "repo": {
+            "type": "string",
+            "description": "Target repository as 'owner/repo' or full github.com URL."
+          },
+          "number": {
+            "type": "number",
+            "description": "Pull request number to fetch full detail, changed files, and comments for."
           },
           "state": {
             "type": "string",
             "enum": ["open", "closed", "all"],
-            "description": "ISSUES ONLY. Filter by issue state."
+            "description": "Filter pull requests by state (default 'all' when listing)."
           },
           "limit": {
             "type": "number",
-            "description": "ISSUES ONLY. Maximum number of issues to return when listing or searching (default 5)."
+            "description": "Maximum pull requests to return when listing (default 10)."
+          }
+        }
+      }
+    },
+    {
+      "name": "github_diff",
+      "description": "Fetch raw git diffs or patches for pull requests, commits, or branch comparisons directly from github.com without consuming REST API rate limits.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "repo": {
+            "type": "string",
+            "description": "Target repository as 'owner/repo' or full github.com URL."
+          },
+          "pull_number": {
+            "type": "number",
+            "description": "Pull request number to fetch the diff or patch for."
+          },
+          "commit_sha": {
+            "type": "string",
+            "description": "Commit SHA to fetch the diff or patch for."
+          },
+          "base": {
+            "type": "string",
+            "description": "Base branch or commit for compare diff (requires 'head')."
+          },
+          "head": {
+            "type": "string",
+            "description": "Head branch or commit for compare diff (requires 'base')."
+          },
+          "format": {
+            "type": "string",
+            "enum": ["diff", "patch"],
+            "description": "Output format: 'diff' (unified diff) or 'patch' (git patch with metadata). Default 'diff'."
+          }
+        }
+      }
+    },
+    {
+      "name": "github_active_tab",
+      "description": "Inspect the active browser tab on github.com via local CDP evaluation. Extracts repository overview, open PR/issue discussion, or file content directly from the browser DOM with ZERO API calls. Works on private repositories you are logged into.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "enum": ["auto", "summary", "files", "comments", "raw"],
+            "description": "Scope of data extraction from the page DOM (default 'auto')."
           }
-        },
-        "required": ["action"]
+        }
       }
     }
   ]