@opentabs-dev/opentabs-plugin-github 0.0.76 → 0.0.77

package/README.md

@@ -1,159 +1,105 @@
-# opentabs-plugin-github
+# GitHub
 
-OpenTabs plugin for GitHub
+OpenTabs plugin for GitHub — gives AI agents access to GitHub through your authenticated browser session.
 
-## Project Structure
+## Install
 
+```bash
+opentabs plugin install github
 ```
-github/
-├── package.json          # Plugin metadata (name, opentabs field, dependencies)
-├── icon.svg              # Optional custom icon (square SVG, max 8KB)
-├── icon-inactive.svg     # Optional manual inactive icon override
-├── src/
-│   ├── index.ts          # Plugin class (extends OpenTabsPlugin)
-│   └── tools/            # One file per tool (using defineTool)
-│       └── example.ts
-└── dist/                 # Build output (generated)
-    ├── adapter.iife.js   # Bundled adapter injected into matching tabs
-    └── tools.json        # Tool schemas for MCP registration
-```
-
-## Configuration
-
-Plugin metadata is defined in `package.json` under the `opentabs` field:
-
-```json
-{
-  "name": "opentabs-plugin-github",
-  "main": "dist/adapter.iife.js",
-  "opentabs": {
-    "displayName": "GitHub",
-    "description": "OpenTabs plugin for GitHub",
-    "urlPatterns": ["*://github.com/*"]
-  }
-}
-```
-
-- **`main`** — entry point for the bundled adapter IIFE
-- **`opentabs.displayName`** — human-readable name shown in the side panel
-- **`opentabs.description`** — short description of what the plugin does
-- **`opentabs.urlPatterns`** — Chrome match patterns for tabs where the adapter is injected
-
-## Custom Icons
 
-By default, the side panel shows a colored letter avatar for your plugin. To use a custom icon, place an `icon.svg` file in the plugin root (next to `package.json`):
+Or install globally via npm:
 
-```
-github/
-├── package.json
-├── icon.svg              ← custom icon (optional)
-├── icon-inactive.svg     ← manual inactive override (optional, requires icon.svg)
-├── src/
-│   └── ...
+```bash
+npm install -g @opentabs-dev/opentabs-plugin-github
 ```
 
-**How it works:**
+## Setup
 
-- `opentabs-plugin build` reads `icon.svg`, validates it, auto-generates a grayscale inactive variant, and embeds both in `dist/tools.json`
-- To override the auto-generated inactive icon, provide `icon-inactive.svg` (must use only grayscale colors)
-- If no `icon.svg` is provided, the letter avatar is used automatically
+1. Open [github.com](https://github.com) in Chrome and log in
+2. Open the OpenTabs side panel — the GitHub plugin should appear as **ready**
 
-**Icon requirements:**
+## Tools (35)
 
-- Square SVG with a `viewBox` attribute (e.g., `viewBox="0 0 32 32"`)
-- Maximum 8 KB file size
-- No embedded `<image>`, `<script>`, or event handler attributes (`onclick`, etc.)
-- Manual `icon-inactive.svg` must use only achromatic (grayscale) colors
+### Repositories (11)
 
-## Development
+| Tool | Description | Type |
+|---|---|---|
+| `list_repos` | List repositories for a user or organization | Read |
+| `get_repo` | Get details of a specific repository | Read |
+| `create_repo` | Create a new repository | Write |
+| `list_commits` | List commits for a repository | Read |
+| `compare_commits` | Compare two commits or branches | Write |
+| `list_releases` | List releases for a repository | Read |
+| `create_release` | Create a release in a repository | Write |
+| `list_branches` | List branches for a repository | Read |
+| `get_file_content` | Read a file from a repository | Read |
+| `create_or_update_file` | Create or update a file in a repository | Write |
+| `delete_file` | Delete a file from a repository | Write |
 
-```bash
-npm install
-npm run build       # tsc && opentabs-plugin build
-npm run dev         # watch mode (tsc --watch + opentabs-plugin build --watch)
-npm run type-check  # tsc --noEmit
-npm run lint        # biome
-```
+### Issues (7)
 
-## Adding Tools
-
-Create a new file in `src/tools/` using `defineTool`:
-
-```ts
-import { z } from 'zod';
-import { defineTool } from '@opentabs-dev/plugin-sdk';
-
-export const myTool = defineTool({
-  name: 'my_tool',
-  displayName: 'My Tool',
-  description: 'What this tool does',
-  icon: 'wrench',
-  input: z.object({ /* ... */ }),
-  output: z.object({ /* ... */ }),
-  handle: async (params) => {
-    // Tool implementation runs in the browser tab context
-    return { /* ... */ };
-  },
-});
-```
+| Tool | Description | Type |
+|---|---|---|
+| `list_issues` | List issues for a repository | Read |
+| `get_issue` | Get details of a specific issue | Read |
+| `create_issue` | Create a new issue in a repository | Write |
+| `update_issue` | Update an existing issue | Write |
+| `search_issues` | Search issues and pull requests | Read |
+| `list_labels` | List labels for a repository | Read |
+| `create_label` | Create a label in a repository | Write |
 
-Then register it in `src/index.ts` by adding it to the `tools` array.
+### Pull Requests (8)
 
-## Authentication
+| Tool | Description | Type |
+|---|---|---|
+| `list_pull_requests` | List pull requests for a repository | Read |
+| `get_pull_request` | Get details of a specific pull request | Read |
+| `create_pull_request` | Create a new pull request | Write |
+| `update_pull_request` | Update a pull request | Write |
+| `merge_pull_request` | Merge a pull request | Write |
+| `get_pull_request_diff` | Get the raw diff of a pull request | Read |
+| `list_pull_request_files` | List files changed in a pull request | Read |
+| `request_pull_request_review` | Request reviewers for a pull request | Write |
 
-Plugin tools run in the browser tab context, so they can read auth tokens directly from the page. The SDK provides utilities for the most common patterns:
+### Comments (2)
 
-```ts
-import { getLocalStorage, getCookie, getPageGlobal } from '@opentabs-dev/plugin-sdk';
+| Tool | Description | Type |
+|---|---|---|
+| `list_comments` | List comments on an issue or pull request | Read |
+| `create_comment` | Add a comment to an issue or pull request | Write |
 
-// localStorage — most common
-const token = getLocalStorage('token');
+### Users (3)
 
-// Cookies — session tokens, JWTs
-const session = getCookie('session_id');
+| Tool | Description | Type |
+|---|---|---|
+| `get_user_profile` | Get a user's profile information | Read |
+| `list_org_members` | List members of an organization | Read |
+| `list_notifications` | List notifications for the authenticated user | Read |
 
-// Page globals — SPA boot data (e.g., window.__APP_STATE__)
-const appState = getPageGlobal('__APP_STATE__');
-```
+### Actions (2)
 
-**Iframe fallback:** Some apps (e.g., Discord) delete `window.localStorage` after boot. `getLocalStorage` automatically tries a hidden same-origin iframe fallback before returning `null`, so you don't need to handle this case manually.
+| Tool | Description | Type |
+|---|---|---|
+| `list_workflow_runs` | List GitHub Actions workflow runs | Read |
+| `get_workflow_run` | Get a workflow run by ID | Read |
 
-**SPA hydration:** Auth tokens may not be available immediately on page load. Implement polling in `isReady()` to wait until the app has hydrated before your tools run. See the comments in `src/index.ts` for an example polling pattern.
+### Search (1)
 
-## Shared Schemas
+| Tool | Description | Type |
+|---|---|---|
+| `search_repos` | Search repositories on GitHub | Read |
 
-When 3 or more tools share the same input or output shape, extract common Zod schemas into a shared file to avoid duplication:
+### Reactions (1)
 
-```ts
-// src/schemas/channel.ts
-import { z } from 'zod';
+| Tool | Description | Type |
+|---|---|---|
+| `add_reaction` | Add a reaction to an issue or comment | Write |
 
-export const channelSchema = z.object({
-  id: z.string().describe('Channel ID'),
-  name: z.string().describe('Channel name'),
-});
+## How It Works
 
-export type Channel = z.infer<typeof channelSchema>;
-```
+This plugin runs inside your GitHub tab through the [OpenTabs](https://opentabs.dev) Chrome extension. It uses your existing browser session — no API tokens or OAuth apps required. All operations happen as you, with your permissions.
 
-Then import and reuse in your tools:
-
-```ts
-// src/tools/list-channels.ts
-import { channelSchema } from '../schemas/channel.js';
-
-export const listChannels = defineTool({
-  name: 'list_channels',
-  displayName: 'List Channels',
-  description: 'List all available channels',
-  icon: 'list',
-  input: z.object({}),
-  output: z.object({ channels: z.array(channelSchema) }),
-  handle: async () => {
-    // ...
-    return { channels: [] };
-  },
-});
-```
+## License
 
-This keeps your tool schemas DRY and makes it easy to evolve shared types in one place.
+MIT