@weavetab/plugin-github 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fy2ne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# `@weavetab/plugin-github`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Official [Weavetab](https://weavetab.dev) plugin that gives the agent first-class GitHub
+> access — analyze repositories, read raw source, search and inspect issues, and examine pull
+> requests — **without burning browser turns**.
+
+[![Trust: Official](https://img.shields.io/badge/trust-official-1e3a8a.svg?style=flat-square)](https://weavetab.dev)
+[![Engine: Weavetab ^2.5.1](https://img.shields.io/badge/engine-weavetab_%5E2.5.1-black.svg?style=flat-square)](https://weavetab.dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+
+---
+
+## Why
+
+GitHub support ships as an official plugin rather than a built-in tool: the core server stays lean
+at **41 built-in tools**, and GitHub is delivered as the **independently versioned**
+`@weavetab/plugin-github` package that can be installed, updated and removed like any other plugin.
+It registers a single `github` tool (actions: `analyze`, `read`, `issues`, `pr`).
+
+All GitHub data is fetched directly over HTTP (`api.github.com` / `raw.githubusercontent.com`),
+so the active browser tab is **never navigated or mutated** and no browser turns are consumed.
+
+## Install
+
+```bash
+weavetab plugin add github         # resolves to the official @weavetab/plugin-github
+# or explicitly
+weavetab plugin add @weavetab/plugin-github
+```
+
+Because the package name starts with `@weavetab/plugin-`, it is automatically treated as
+**Official** — fully trusted, no verification prompt.
+
+Restart the Weavetab MCP server to activate the tool.
+
+## The `github` tool
+
+A single, well-organized action-dispatch tool.
+
+| Parameter | Applies to | Description |
+|---|---|---|
+| `action` *(required)* | all | `analyze` · `read` · `issues` · `pr` |
+| `repo` | all | `owner/repo` or a full `github.com` URL. Omit to use the active tab's repo. |
+| `paths` | `read` | File paths relative to the repo root. |
+| `line_range` | `read` | Optional `[start, end]`, 1-indexed. |
+| `number` | `issues`, `pr` | Issue / PR number for full detail + comments. |
+| `search` | `issues` | Free-text query (GitHub Search API, scoped to the repo). |
+| `labels` | `issues` | Restrict to issues carrying these labels. |
+| `state` | `issues` | `open` · `closed` · `all` |
+| `limit` | `issues` | Max issues returned (default `5`). |
+
+### Actions
+
+- **`analyze`** — repository metadata, recursive default-branch file tree, and a README snippet.
+  Results are cached in the plugin's isolated storage (TTL configurable).
+- **`read`** — raw contents of the requested `paths`, with optional line ranges and automatic
+  truncation for large files.
+- **`issues`** — inspect one issue with its comments (`number`), or list / search issues.
+- **`pr`** — inspect one pull request with changed files, diff stats and comments (`number`),
+  or list recent pull requests.
+
+### Examples
+
+```jsonc
+// Analyze a repo
+{ "action": "analyze", "repo": "weavetab/mcp" }
+
+// Read two files, lines 1-40 of the first
+{ "action": "read", "repo": "weavetab/mcp", "paths": ["src/index.ts", "README.md"], "line_range": [1, 40] }
+
+// Search issues by label
+{ "action": "issues", "repo": "weavetab/mcp", "search": "rate limit", "labels": ["bug"], "state": "open" }
+
+// Inspect PR #42
+{ "action": "pr", "repo": "weavetab/mcp", "number": 42 }
+```
+
+## Configuration
+
+Written to `~/.weavetab/plugins/@weavetab_plugin-github/config.json` on first load:
+
+```json
+{
+  "cacheTtlMs": 1800000,
+  "maxReadLines": 200,
+  "defaultIssueLimit": 5
+}
+```
+
+| Key | Default | Meaning |
+|---|---|---|
+| `cacheTtlMs` | `1800000` (30 min) | How long an `analyze` result stays cached. |
+| `maxReadLines` | `200` | Files longer than this are truncated when no `line_range` is given. |
+| `defaultIssueLimit` | `5` | Default `limit` for the `issues` action. |
+
+## Permissions
+
+| Permission | Why |
+|---|---|
+| `config.read` / `config.write` | Read and persist isolated plugin settings. |
+| `cdp.evaluate` | Read the active tab URL **only**, to infer the target repo when `repo` is omitted. |
+| `network: api.github.com`, `raw.githubusercontent.com`, `github.com` | Fetch public repo data over HTTP. |
+| `tools.add` | Register the single `github` tool. |
+
+No filesystem access beyond the plugin's own sandbox, no HUD/overlay injection, no tab mutation.
+
+## Development
+
+```bash
+npm install
+npm run build      # tsc -> dist/
+npm test           # node:test manifest + schema + handler smoke tests
+npm run dev        # tsc --watch
+```
+
+### Project layout
+
+```text
+plugin-github/
+├── src/index.ts       # definePlugin + registerTool("github")
+├── src/github.ts      # action dispatcher
+├── src/{analyze,read,issues,pr}.ts
+├── src/{repoContext,cache,rateLimiter,types}.ts
+├── weavetab.json      # manifest (permissions + tool schema)
+├── test/              # node:test smoke tests
+└── dist/              # compiled output (generated)
+```
+
+> **Local development note.** Inside the Weavetab monorepo this package pins
+> `"@weavetab/sdk": "file:../../sdk"` so it builds against the in-repo SDK. In the standalone
+> published repository, pin the released SDK instead: `"@weavetab/sdk": "^2.5.1"`.
+
+---
+
+## License
+
+MIT © [Weavetab](https://github.com/Weavetab) & [fy2ne](https://github.com/fy2ne)

package/dist/analyze.d.ts

@@ -0,0 +1,6 @@
+import type { GithubError, GithubRepoCache, GithubRunContext } from "./types.js";
+/**
+ * `analyze` action — repository metadata, recursive default-branch file tree and
+ * a README snippet. Results are cached in the plugin's isolated storage.
+ */
+export declare function githubAnalyze(ctx: GithubRunContext, repoSlug?: unknown): Promise<GithubRepoCache | GithubError>;

package/dist/analyze.js

@@ -0,0 +1,100 @@
+import { getRepoContext, isGithubError } from "./repoContext.js";
+import { loadRepoCache, saveRepoCache } from "./cache.js";
+import { canMakeApiCall, handleApiResponse } from "./rateLimiter.js";
+const README_CANDIDATES = ["README.md", "README", "readme.md", "Readme.md", "README.txt"];
+const API_HEADERS = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "Weavetab-GitHub-Plugin",
+};
+/**
+ * `analyze` action — repository metadata, recursive default-branch file tree and
+ * a README snippet. Results are cached in the plugin's isolated storage.
+ */
+export async function githubAnalyze(ctx, repoSlug) {
+    const context = await getRepoContext(ctx.session, repoSlug);
+    if (isGithubError(context))
+        return context;
+    const { owner, repo } = context;
+    const cached = await loadRepoCache(owner, repo, ctx.store, ctx.cacheTtlMs);
+    if (cached)
+        return cached;
+    const rateLimitCheck = canMakeApiCall();
+    if (isGithubError(rateLimitCheck))
+        return rateLimitCheck;
+    // 1. Repo metadata
+    const repoRes = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
+        headers: API_HEADERS,
+    });
+    const handledRepoRes = handleApiResponse(repoRes);
+    if (isGithubError(handledRepoRes))
+        return handledRepoRes;
+    if (repoRes.status === 404) {
+        return {
+            error: "REPO_NOT_FOUND",
+            message: "Repository not found or not accessible. Note: only public repositories are supported.",
+        };
+    }
+    if (!repoRes.ok) {
+        return { error: "API_ERROR", message: `GitHub API error: ${repoRes.statusText}` };
+    }
+    const repoData = await repoRes.json();
+    const default_branch = repoData.default_branch || "main";
+    const description = repoData.description || null;
+    const language = repoData.language || null;
+    // 2. Recursive file tree
+    const rateLimitCheck2 = canMakeApiCall();
+    if (isGithubError(rateLimitCheck2))
+        return rateLimitCheck2;
+    let file_tree = [];
+    const treeRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/git/trees/${default_branch}?recursive=1`, { headers: API_HEADERS });
+    const handledTreeRes = handleApiResponse(treeRes);
+    if (isGithubError(handledTreeRes))
+        return handledTreeRes;
+    if (treeRes.ok) {
+        const treeData = await treeRes.json();
+        if (Array.isArray(treeData.tree)) {
+            // Flat structure — compact and easy to grep.
+            file_tree = treeData.tree.map((t) => ({
+                path: t.path,
+                mode: t.mode,
+                type: t.type,
+                sha: t.sha,
+                size: t.size,
+                url: t.url,
+            }));
+        }
+    }
+    // 3. README snippet (first 100 lines)
+    let readme_snippet = "";
+    const readmeEntry = file_tree.find((f) => README_CANDIDATES.includes(f.path));
+    if (readmeEntry) {
+        const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${default_branch}/${readmeEntry.path}`;
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 10_000);
+            const rawRes = await fetch(rawUrl, { signal: controller.signal });
+            clearTimeout(timeout);
+            if (rawRes.ok) {
+                const lines = (await rawRes.text()).split("\n");
+                readme_snippet = lines.slice(0, 100).join("\n");
+                if (lines.length > 100)
+                    readme_snippet += "\n\n... (truncated)";
+            }
+        }
+        catch {
+            /* best-effort — README is optional */
+        }
+    }
+    const cacheData = {
+        owner,
+        repo,
+        default_branch,
+        description,
+        language,
+        file_tree,
+        readme_snippet,
+        analyzed_at: Date.now(),
+    };
+    await saveRepoCache(cacheData, ctx.store);
+    return cacheData;
+}

package/dist/cache.d.ts

@@ -0,0 +1,9 @@
+import type { PluginStorage } from "@weavetab/sdk";
+import type { GithubRepoCache } from "./types.js";
+/**
+ * Load a previously analyzed repository from the plugin's isolated storage.
+ * Returns null when absent, malformed, or older than `ttlMs`.
+ */
+export declare function loadRepoCache(owner: string, repo: string, store: PluginStorage, ttlMs: number): Promise<GithubRepoCache | null>;
+/** Persist an analysis result into the plugin's isolated storage. */
+export declare function saveRepoCache(data: GithubRepoCache, store: PluginStorage): Promise<void>;

package/dist/cache.js

@@ -0,0 +1,23 @@
+const CACHE_SUBDIR = "github_cache";
+function safeSegment(value) {
+    return value.replace(/[^a-zA-Z0-9.-]/g, "_");
+}
+function cacheFile(owner, repo) {
+    return `${CACHE_SUBDIR}/${safeSegment(owner)}_${safeSegment(repo)}.json`;
+}
+/**
+ * Load a previously analyzed repository from the plugin's isolated storage.
+ * Returns null when absent, malformed, or older than `ttlMs`.
+ */
+export async function loadRepoCache(owner, repo, store, ttlMs) {
+    const data = await store.getJSON(cacheFile(owner, repo));
+    if (!data || typeof data.analyzed_at !== "number")
+        return null;
+    if (Date.now() - data.analyzed_at > ttlMs)
+        return null; // stale
+    return data;
+}
+/** Persist an analysis result into the plugin's isolated storage. */
+export async function saveRepoCache(data, store) {
+    await store.setJSON(cacheFile(data.owner, data.repo), data);
+}

package/dist/github.d.ts

@@ -0,0 +1,11 @@
+import type { GithubError, GithubRunContext, GithubToolArgs } from "./types.js";
+import { githubAnalyze } from "./analyze.js";
+import { githubRead } from "./read.js";
+import { githubIssues } from "./issues.js";
+import { githubGetPr } from "./pr.js";
+/**
+ * Single entry point for the `github` MCP tool. Dispatches to the matching
+ * action handler and funnels every result through a plain serializable value.
+ */
+export declare function runGithub(ctx: GithubRunContext, args: GithubToolArgs): Promise<any | GithubError>;
+export { githubAnalyze, githubRead, githubIssues, githubGetPr };

package/dist/github.js

@@ -0,0 +1,41 @@
+import { githubAnalyze } from "./analyze.js";
+import { githubRead } from "./read.js";
+import { githubIssues } from "./issues.js";
+import { githubGetPr } from "./pr.js";
+/**
+ * Single entry point for the `github` MCP tool. Dispatches to the matching
+ * action handler and funnels every result through a plain serializable value.
+ */
+export async function runGithub(ctx, args) {
+    switch (args.action) {
+        case "analyze":
+            return githubAnalyze(ctx, args.repo);
+        case "read": {
+            const paths = Array.isArray(args.paths) ? args.paths.filter((p) => typeof p === "string") : [];
+            if (paths.length === 0) {
+                return {
+                    error: "MISSING_PATHS",
+                    message: "action 'read' requires a 'paths' array with at least one file path.",
+                };
+            }
+            return githubRead(ctx, { repo: args.repo, paths, line_range: args.line_range });
+        }
+        case "issues":
+            return githubIssues(ctx, {
+                repo: args.repo,
+                search: args.search,
+                number: args.number,
+                labels: args.labels,
+                state: args.state,
+                limit: args.limit,
+            });
+        case "pr":
+            return githubGetPr(ctx, { repo: args.repo, number: args.number, state: args.state, limit: args.limit });
+        default:
+            return {
+                error: "INVALID_ACTION",
+                message: `Unknown action: ${args.action}. Must be 'analyze', 'read', 'issues', or 'pr'.`,
+            };
+    }
+}
+export { githubAnalyze, githubRead, githubIssues, githubGetPr };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @weavetab/plugin-github
+ * Official Weavetab GitHub plugin — repository analysis, raw file reads, issue
+ * search/inspection and pull request inspection over the GitHub REST API.
+ *
+ * All GitHub data is fetched over HTTP, so no browser turns are consumed and the
+ * active tab is never navigated or mutated.
+ *
+ * Author: fy2ne
+ * License: MIT
+ */
+export * from "./types.js";
+export { runGithub } from "./github.js";
+export declare const githubPlugin: import("@weavetab/sdk").WeavetabPluginDefinition;
+export default githubPlugin;
+export declare const plugin: import("@weavetab/sdk").WeavetabPluginDefinition;

package/dist/index.js

@@ -0,0 +1,99 @@
+/**
+ * @weavetab/plugin-github
+ * Official Weavetab GitHub plugin — repository analysis, raw file reads, issue
+ * search/inspection and pull request inspection over the GitHub REST API.
+ *
+ * All GitHub data is fetched over HTTP, so no browser turns are consumed and the
+ * active tab is never navigated or mutated.
+ *
+ * Author: fy2ne
+ * License: MIT
+ */
+import { definePlugin, defineTool, z } from "@weavetab/sdk";
+import { runGithub } from "./github.js";
+export * from "./types.js";
+export { runGithub } from "./github.js";
+const DEFAULT_CACHE_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_MAX_READ_LINES = 200;
+const DEFAULT_ISSUE_LIMIT = 5;
+const TOOL_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.";
+/** Coerce a possibly-string config value into a positive integer. */
+function positiveInt(value, fallback) {
+    const n = typeof value === "string" ? parseInt(value, 10) : value;
+    return typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+export const githubPlugin = definePlugin({
+    name: "@weavetab/plugin-github",
+    version: "1.0.0",
+    description: "Official Weavetab GitHub plugin — analyze repositories, read raw source, inspect issues and pull requests over the GitHub API.",
+    defaultConfig: {
+        cacheTtlMs: DEFAULT_CACHE_TTL_MS,
+        maxReadLines: DEFAULT_MAX_READ_LINES,
+        defaultIssueLimit: DEFAULT_ISSUE_LIMIT,
+    },
+    async onLoad(ctx) {
+        const cacheTtlMs = positiveInt(ctx.config?.cacheTtlMs, DEFAULT_CACHE_TTL_MS);
+        const maxReadLines = positiveInt(ctx.config?.maxReadLines, DEFAULT_MAX_READ_LINES);
+        const defaultIssueLimit = positiveInt(ctx.config?.defaultIssueLimit, DEFAULT_ISSUE_LIMIT);
+        ctx.mcp.registerTool(defineTool({
+            name: "github",
+            description: TOOL_DESCRIPTION,
+            requiresSession: false,
+            schema: {
+                action: z
+                    .enum(["analyze", "read", "issues", "pr"])
+                    .describe("The GitHub operation to perform. 'analyze' = repo metadata, file tree & README; 'read' = raw file contents (needs 'paths'); 'issues' = list/search/inspect issues; 'pr' = list/inspect pull requests."),
+                repo: z
+                    .string()
+                    .optional()
+                    .describe("Target repository as 'owner/repo' or a full github.com URL. Optional — when omitted, it is inferred from the active browser tab."),
+                paths: z
+                    .array(z.string())
+                    .optional()
+                    .describe("READ: file paths relative to the repo root, e.g. ['src/index.ts', 'README.md']."),
+                line_range: z
+                    .array(z.number())
+                    .length(2)
+                    .optional()
+                    .describe("READ: optional [start, end] 1-indexed line range per file."),
+                number: z
+                    .number()
+                    .optional()
+                    .describe("ISSUES / PR: issue or pull request number to fetch full detail and comments."),
+                search: z
+                    .string()
+                    .optional()
+                    .describe("ISSUES: free-text query to search issues in the target repository."),
+                labels: z.array(z.string()).optional().describe("ISSUES: restrict results to these labels."),
+                state: z
+                    .enum(["open", "closed", "all"])
+                    .optional()
+                    .describe("ISSUES / PR: filter by state."),
+                limit: z
+                    .number()
+                    .optional()
+                    .describe(`ISSUES / PR: max items to return when listing/searching (default ${DEFAULT_ISSUE_LIMIT} for issues, 10 for pull requests).`),
+            },
+            handler: async (args, session) => {
+                const result = await runGithub({
+                    session: session,
+                    store: ctx.storage,
+                    cacheTtlMs,
+                    maxReadLines,
+                    defaultIssueLimit,
+                }, args);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            },
+        }));
+        ctx.logger?.info(`@weavetab/plugin-github ready — tool "github" registered (cacheTtlMs=${cacheTtlMs}, maxReadLines=${maxReadLines}, defaultIssueLimit=${defaultIssueLimit}).`);
+    },
+    async onUnload(ctx) {
+        ctx.logger?.info("@weavetab/plugin-github unloaded.");
+    },
+});
+export default githubPlugin;
+export const plugin = githubPlugin;

package/dist/issues.d.ts

@@ -0,0 +1,15 @@
+import type { GithubRunContext } from "./types.js";
+interface IssueArgs {
+    repo?: string;
+    search?: string;
+    number?: number;
+    labels?: string[];
+    state?: "open" | "closed" | "all";
+    limit?: number;
+}
+/**
+ * `issues` action — inspect a single issue (with comments) when `number` is
+ * given, otherwise list or search issues in the target repository.
+ */
+export declare function githubIssues(ctx: GithubRunContext, args: IssueArgs): Promise<any>;
+export {};

package/dist/issues.js

@@ -0,0 +1,94 @@
+import { getRepoContext, isGithubError } from "./repoContext.js";
+import { canMakeApiCall, handleApiResponse } from "./rateLimiter.js";
+const API_HEADERS = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "Weavetab-GitHub-Plugin",
+};
+/**
+ * `issues` action — inspect a single issue (with comments) when `number` is
+ * given, otherwise list or search issues in the target repository.
+ */
+export async function githubIssues(ctx, args) {
+    const context = await getRepoContext(ctx.session, args.repo);
+    if (isGithubError(context))
+        return context;
+    const { owner, repo } = context;
+    const limit = args.limit || ctx.defaultIssueLimit;
+    const rateLimitCheck = canMakeApiCall();
+    if (isGithubError(rateLimitCheck))
+        return rateLimitCheck;
+    // Single issue + comments
+    if (args.number) {
+        const issueRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${args.number}`, { headers: API_HEADERS });
+        const handledIssueRes = handleApiResponse(issueRes);
+        if (isGithubError(handledIssueRes))
+            return handledIssueRes;
+        if (!issueRes.ok) {
+            return {
+                error: "FETCH_FAILED",
+                status: issueRes.status,
+                message: `Failed to fetch issue #${args.number}`,
+            };
+        }
+        const issueData = await issueRes.json();
+        let comments = [];
+        if (issueData.comments > 0) {
+            const rateLimitCheck2 = canMakeApiCall();
+            if (!isGithubError(rateLimitCheck2)) {
+                const commentsRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${args.number}/comments`, { headers: API_HEADERS });
+                const handledCommentsRes = handleApiResponse(commentsRes);
+                if (!isGithubError(handledCommentsRes) && commentsRes.ok) {
+                    const commentsData = await commentsRes.json();
+                    comments = commentsData.map((c) => ({
+                        id: c.id,
+                        user: c.user?.login,
+                        body: c.body,
+                        created_at: c.created_at,
+                    }));
+                }
+            }
+        }
+        return {
+            number: issueData.number,
+            title: issueData.title,
+            state: issueData.state,
+            user: issueData.user?.login,
+            body: issueData.body,
+            created_at: issueData.created_at,
+            labels: issueData.labels?.map((l) => l.name),
+            comments,
+        };
+    }
+    // List or search issues
+    let urlStr = `https://api.github.com/repos/${owner}/${repo}/issues?per_page=${limit}`;
+    if (args.state)
+        urlStr += `&state=${args.state}`;
+    if (args.labels && args.labels.length > 0)
+        urlStr += `&labels=${args.labels.join(",")}`;
+    if (args.search) {
+        let q = `repo:${owner}/${repo} is:issue ${args.search}`;
+        if (args.state && args.state !== "all")
+            q += ` is:${args.state}`;
+        if (args.labels)
+            args.labels.forEach((l) => (q += ` label:"${l}"`));
+        urlStr = `https://api.github.com/search/issues?q=${encodeURIComponent(q)}&per_page=${limit}`;
+    }
+    const listRes = await fetch(urlStr, { headers: API_HEADERS });
+    const handledListRes = handleApiResponse(listRes);
+    if (isGithubError(handledListRes))
+        return handledListRes;
+    if (!listRes.ok) {
+        return { error: "FETCH_FAILED", status: listRes.status, message: "Failed to list/search issues" };
+    }
+    const listData = await listRes.json();
+    const items = args.search ? listData.items : listData;
+    return items.map((i) => ({
+        number: i.number,
+        title: i.title,
+        state: i.state,
+        user: i.user?.login,
+        labels: i.labels?.map((l) => l.name),
+        created_at: i.created_at,
+        comments_count: i.comments,
+    }));
+}

package/dist/pr.d.ts

@@ -0,0 +1,13 @@
+import type { GithubRunContext } from "./types.js";
+interface PrArgs {
+    repo?: string;
+    number?: number;
+    state?: "open" | "closed" | "all";
+    limit?: number;
+}
+/**
+ * `pr` action — inspect a single pull request (changed files, diff stats and
+ * comments) when `number` is given, otherwise list recent pull requests.
+ */
+export declare function githubGetPr(ctx: GithubRunContext, args: PrArgs): Promise<any>;
+export {};

package/dist/pr.js

@@ -0,0 +1,97 @@
+import { getRepoContext, isGithubError } from "./repoContext.js";
+import { canMakeApiCall, handleApiResponse } from "./rateLimiter.js";
+const DEFAULT_PR_LIMIT = 10;
+const API_HEADERS = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "Weavetab-GitHub-Plugin",
+};
+/**
+ * `pr` action — inspect a single pull request (changed files, diff stats and
+ * comments) when `number` is given, otherwise list recent pull requests.
+ */
+export async function githubGetPr(ctx, args) {
+    const context = await getRepoContext(ctx.session, args.repo);
+    if (isGithubError(context))
+        return context;
+    const { owner, repo } = context;
+    const rateLimitCheck = canMakeApiCall();
+    if (isGithubError(rateLimitCheck))
+        return rateLimitCheck;
+    if (args.number) {
+        const prRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls/${args.number}`, {
+            headers: API_HEADERS,
+        });
+        const handledPrRes = handleApiResponse(prRes);
+        if (isGithubError(handledPrRes))
+            return handledPrRes;
+        if (!prRes.ok) {
+            return {
+                error: "FETCH_FAILED",
+                status: prRes.status,
+                message: `Failed to fetch PR #${args.number}`,
+            };
+        }
+        const prData = await prRes.json();
+        let files_changed = [];
+        const rateLimitCheck2 = canMakeApiCall();
+        if (!isGithubError(rateLimitCheck2)) {
+            const filesRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls/${args.number}/files`, { headers: API_HEADERS });
+            const handledFilesRes = handleApiResponse(filesRes);
+            if (!isGithubError(handledFilesRes) && filesRes.ok) {
+                const filesData = await filesRes.json();
+                files_changed = filesData.map((f) => f.filename);
+            }
+        }
+        let comments = [];
+        if (prData.comments > 0) {
+            const rateLimitCheck3 = canMakeApiCall();
+            if (!isGithubError(rateLimitCheck3)) {
+                const commentsRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${args.number}/comments`, { headers: API_HEADERS });
+                const handledCommentsRes = handleApiResponse(commentsRes);
+                if (!isGithubError(handledCommentsRes) && commentsRes.ok) {
+                    const commentsData = await commentsRes.json();
+                    comments = commentsData.map((c) => ({
+                        id: c.id,
+                        user: c.user?.login,
+                        body: c.body,
+                        created_at: c.created_at,
+                    }));
+                }
+            }
+        }
+        return {
+            number: prData.number,
+            title: prData.title,
+            state: prData.state,
+            user: prData.user?.login,
+            body: prData.body,
+            created_at: prData.created_at,
+            merged: prData.merged,
+            mergeable: prData.mergeable,
+            additions: prData.additions,
+            deletions: prData.deletions,
+            changed_files: prData.changed_files,
+            files: files_changed,
+            comments,
+        };
+    }
+    // List recent pull requests
+    const limit = args.limit && args.limit > 0 ? Math.min(args.limit, 100) : DEFAULT_PR_LIMIT;
+    const state = args.state || "all";
+    const listRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls?state=${state}&per_page=${limit}`, { headers: API_HEADERS });
+    const handledListRes = handleApiResponse(listRes);
+    if (isGithubError(handledListRes))
+        return handledListRes;
+    if (!listRes.ok) {
+        return { error: "FETCH_FAILED", status: listRes.status, message: "Failed to list PRs" };
+    }
+    const listData = await listRes.json();
+    return listData.map((pr) => ({
+        number: pr.number,
+        title: pr.title,
+        state: pr.state,
+        user: pr.user?.login,
+        created_at: pr.created_at,
+        updated_at: pr.updated_at,
+    }));
+}

package/dist/rateLimiter.d.ts

@@ -0,0 +1,8 @@
+import type { GithubError } from "./types.js";
+/**
+ * Guard that refuses new API calls once the remaining quota drops below a safety
+ * threshold, so we never trip GitHub's hard rate limit mid-flow.
+ */
+export declare function canMakeApiCall(): true | GithubError;
+export declare function recordApiCall(headers: Headers): void;
+export declare function handleApiResponse(response: Response): Response | GithubError;

package/dist/rateLimiter.js

@@ -0,0 +1,47 @@
+const SAFETY_THRESHOLD = 5;
+const state = { remaining: 60, resetAt: null };
+/**
+ * Guard that refuses new API calls once the remaining quota drops below a safety
+ * threshold, so we never trip GitHub's hard rate limit mid-flow.
+ */
+export function canMakeApiCall() {
+    const nowSec = Math.floor(Date.now() / 1000);
+    if (state.resetAt && nowSec >= state.resetAt) {
+        // We've passed the reset window, assume quota is restored.
+        state.remaining = 60;
+        state.resetAt = null;
+    }
+    if (state.remaining < SAFETY_THRESHOLD) {
+        const resetTime = state.resetAt ? new Date(state.resetAt * 1000).toISOString() : "unknown";
+        return {
+            error: "RATE_LIMIT_LOW",
+            message: `GitHub API hourly rate limit is too low (remaining: ${state.remaining}). Please wait until ${resetTime} before making more API calls. Note: read actions (api.github.com / raw.githubusercontent.com GETs) do NOT consume the rate-limited Search API quota.`,
+            remaining: state.remaining,
+            reset_at: state.resetAt,
+        };
+    }
+    return true;
+}
+export function recordApiCall(headers) {
+    const remainingStr = headers.get("x-ratelimit-remaining");
+    const resetStr = headers.get("x-ratelimit-reset");
+    if (remainingStr) {
+        state.remaining = parseInt(remainingStr, 10) || state.remaining;
+    }
+    if (resetStr) {
+        state.resetAt = parseInt(resetStr, 10) || state.resetAt;
+    }
+}
+export function handleApiResponse(response) {
+    recordApiCall(response.headers);
+    if (response.status === 403 || response.status === 429) {
+        const resetTime = state.resetAt ? new Date(state.resetAt * 1000).toISOString() : "unknown";
+        return {
+            error: "RATE_LIMIT_EXCEEDED",
+            message: `GitHub API rate limit exceeded. Please wait until ${resetTime}.`,
+            remaining: state.remaining,
+            reset_at: state.resetAt,
+        };
+    }
+    return response;
+}

package/dist/read.d.ts

@@ -0,0 +1,14 @@
+import type { GithubRunContext } from "./types.js";
+interface ReadArgs {
+    repo?: string;
+    paths: string[];
+    line_range?: number[];
+}
+/**
+ * `read` action — fetch raw file contents from the default branch.
+ *
+ * Ensures an analysis (and thus `default_branch` + `file_tree`) exists first,
+ * then fetches each requested path in parallel over raw.githubusercontent.com.
+ */
+export declare function githubRead(ctx: GithubRunContext, args: ReadArgs): Promise<any>;
+export {};

package/dist/read.js

@@ -0,0 +1,69 @@
+import { getRepoContext, isGithubError } from "./repoContext.js";
+import { loadRepoCache } from "./cache.js";
+import { githubAnalyze } from "./analyze.js";
+/**
+ * `read` action — fetch raw file contents from the default branch.
+ *
+ * Ensures an analysis (and thus `default_branch` + `file_tree`) exists first,
+ * then fetches each requested path in parallel over raw.githubusercontent.com.
+ */
+export async function githubRead(ctx, args) {
+    const context = await getRepoContext(ctx.session, args.repo);
+    if (isGithubError(context))
+        return context;
+    const { owner, repo } = context;
+    let cached = await loadRepoCache(owner, repo, ctx.store, ctx.cacheTtlMs);
+    if (!cached) {
+        const analyzed = await githubAnalyze(ctx, args.repo);
+        if (isGithubError(analyzed))
+            return analyzed;
+        cached = analyzed;
+    }
+    const default_branch = cached.default_branch;
+    const file_tree = cached.file_tree;
+    const results = [];
+    const warnings = [];
+    const fetchPromises = args.paths.map(async (rawPath) => {
+        const path = rawPath.replace(/\\/g, "/").replace(/^\/+/, "");
+        if (path.includes("..") || path.includes("\0")) {
+            return { path: rawPath, error: "INVALID_PATH", message: "Path traversal or null bytes detected." };
+        }
+        if (!file_tree.some((entry) => entry.path === path)) {
+            warnings.push(`Path '${path}' was not found in the cached file tree. Branch contents may differ.`);
+        }
+        const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${default_branch}/${path}`;
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 10_000);
+            const res = await fetch(rawUrl, { signal: controller.signal });
+            clearTimeout(timeout);
+            if (!res.ok) {
+                return { path, error: "FETCH_FAILED", status: res.status, message: res.statusText };
+            }
+            const lines = (await res.text()).split("\n");
+            const total_lines = lines.length;
+            let returnedContent = lines.join("\n");
+            let truncated = false;
+            if (Array.isArray(args.line_range) && args.line_range.length === 2) {
+                const start = Math.max(0, args.line_range[0] - 1); // 1-indexed -> 0-indexed
+                const end = Math.min(total_lines, args.line_range[1]);
+                returnedContent = lines.slice(start, end).join("\n");
+                truncated = start > 0 || end < total_lines;
+            }
+            else if (total_lines > ctx.maxReadLines) {
+                returnedContent = lines.slice(0, ctx.maxReadLines).join("\n");
+                truncated = true;
+            }
+            return { path, total_lines, truncated, content: returnedContent };
+        }
+        catch (err) {
+            return { path, error: "FETCH_ERROR", message: err?.message };
+        }
+    });
+    const pathResults = await Promise.all(fetchPromises);
+    results.push(...pathResults);
+    return {
+        warnings: warnings.length > 0 ? warnings : undefined,
+        files: results,
+    };
+}

package/dist/repoContext.d.ts

@@ -0,0 +1,21 @@
+import type { CdpSession, 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`.
+ */
+export declare function parseRepoSlug(slug: unknown): RepoContext | 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.
+ */
+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

@@ -0,0 +1,108 @@
+/**
+ * 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`.
+ */
+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 */
+    }
+    // "owner/repo" shorthand
+    const parts = trimmed.split("/").filter(Boolean);
+    if (parts.length >= 2)
+        return { owner: parts[0], repo: parts[1] };
+    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.
+ */
+export async function getRepoContext(session, repoSlug) {
+    const slugStr = typeof repoSlug === "string" && repoSlug.trim() !== "" ? repoSlug.trim() : undefined;
+    // Explicit slug wins over the current tab URL.
+    if (slugStr) {
+        const parsed = parseRepoSlug(slugStr);
+        if (!parsed) {
+            return {
+                error: "INVALID_REPO_SLUG",
+                message: `Cannot parse a GitHub owner/repo from "${slugStr}". Use "owner/repo" or a full github.com URL.`,
+            };
+        }
+        return parsed;
+    }
+    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.",
+        };
+    }
+    let urlStr;
+    try {
+        const { result } = await session.Runtime.evaluate({
+            expression: "window.location.href",
+            returnByValue: true,
+        });
+        urlStr = result.value;
+    }
+    catch {
+        return {
+            error: "CONTEXT_ERROR",
+            message: "Failed to evaluate window.location.href on the active tab.",
+        };
+    }
+    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) {
+        return {
+            error: "NOT_ON_GITHUB_REPO",
+            message: "Navigate to a specific GitHub repository first (e.g. github.com/owner/repo).",
+        };
+    }
+    return { owner: parts[0], repo: parts[1] };
+}
+export function isGithubError(result) {
+    return (!!result &&
+        typeof result === "object" &&
+        "error" in result &&
+        "message" in result &&
+        typeof result.message === "string");
+}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared types for @weavetab/plugin-github.
+ *
+ * The plugin is intentionally decoupled from the Weavetab MCP internals: it only
+ * depends on the minimal CDP surface it actually uses (`session.Runtime.evaluate`)
+ * 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. */
+export interface CdpSession {
+    Runtime: {
+        evaluate(params: {
+            expression: string;
+            returnByValue?: boolean;
+        }): Promise<{
+            result: {
+                value: unknown;
+            };
+        }>;
+    };
+}
+/** A resolved GitHub repository target. */
+export interface RepoContext {
+    owner: string;
+    repo: string;
+}
+/** Structured, non-throwing error returned to the MCP layer. */
+export interface GithubError {
+    error: string;
+    message: string;
+    [key: string]: unknown;
+}
+export interface TreeEntry {
+    path: string;
+    mode: string;
+    type: string;
+    sha: string;
+    size?: number;
+    url: string;
+}
+/** Cached result of the `analyze` action. */
+export interface GithubRepoCache {
+    owner: string;
+    repo: string;
+    default_branch: string;
+    description: string | null;
+    language: string | null;
+    file_tree: TreeEntry[];
+    readme_snippet: string;
+    analyzed_at: number;
+}
+/** Runtime dependencies injected into every GitHub action. */
+export interface GithubRunContext {
+    session?: CdpSession;
+    store: PluginStorage;
+    cacheTtlMs: number;
+    maxReadLines: number;
+    defaultIssueLimit: number;
+}
+/** The single tool's argument shape. */
+export interface GithubToolArgs {
+    action: "analyze" | "read" | "issues" | "pr";
+    repo?: string;
+    paths?: string[];
+    line_range?: number[];
+    number?: number;
+    search?: string;
+    labels?: string[];
+    state?: "open" | "closed" | "all";
+    limit?: number;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Shared types for @weavetab/plugin-github.
+ *
+ * The plugin is intentionally decoupled from the Weavetab MCP internals: it only
+ * depends on the minimal CDP surface it actually uses (`session.Runtime.evaluate`)
+ * and on the isolated storage contract exposed by the plugin runtime.
+ */
+export {};

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@weavetab/plugin-github",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "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.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "weavetab.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@weavetab/sdk": "^2.5.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "typescript": "^5.5.0"
+  },
+  "keywords": [
+    "weavetab",
+    "weavetab-plugin",
+    "weavetab-official",
+    "mcp",
+    "github",
+    "repository",
+    "issues",
+    "pull-requests",
+    "browser-automation"
+  ],
+  "author": "Weavetab (https://weavetab.dev)",
+  "license": "MIT",
+  "homepage": "https://github.com/Weavetab/plugin-github",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Weavetab/plugin-github.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Weavetab/plugin-github/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/weavetab.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://weavetab.dev/schema/plugin.json",
+  "name": "@weavetab/plugin-github",
+  "version": "1.0.0",
+  "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.",
+  "entry": "dist/index.js",
+  "engines": {
+    "weavetab": "^2.5.1",
+    "node": ">=18.0.0"
+  },
+  "environments": [
+    "mcp"
+  ],
+  "authors": [
+    {
+      "name": "fy2ne",
+      "role": "Author & Maintainer",
+      "url": "https://github.com/fy2ne"
+    }
+  ],
+  "license": "MIT",
+  "tags": [
+    "GitHub",
+    "Developer Tools",
+    "Repositories",
+    "Issues",
+    "Pull Requests"
+  ],
+  "links": {
+    "github": "https://github.com/weavetab/plugin-github",
+    "npm": "https://www.npmjs.com/package/@weavetab/plugin-github"
+  },
+  "defaultConfig": {
+    "cacheTtlMs": 1800000,
+    "maxReadLines": 200,
+    "defaultIssueLimit": 5
+  },
+  "permissions": {
+    "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."
+    },
+    "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."
+    },
+    "network": {
+      "domains": [
+        "api.github.com",
+        "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."
+    },
+    "tools": {
+      "add": true,
+      "reason": "Registers the single 'github' MCP tool."
+    }
+  },
+  "tools": [
+    {
+      "name": "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.",
+      "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)."
+          },
+          "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'])."
+          },
+          "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."
+          },
+          "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."
+          },
+          "search": {
+            "type": "string",
+            "description": "ISSUES ONLY. Free-text search query to find issues (uses the GitHub Search API, scoped to the target repo)."
+          },
+          "labels": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "ISSUES ONLY. Restrict results to issues carrying all of the given labels."
+          },
+          "state": {
+            "type": "string",
+            "enum": ["open", "closed", "all"],
+            "description": "ISSUES ONLY. Filter by issue state."
+          },
+          "limit": {
+            "type": "number",
+            "description": "ISSUES ONLY. Maximum number of issues to return when listing or searching (default 5)."
+          }
+        },
+        "required": ["action"]
+      }
+    }
+  ]
+}