@matimo/github 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tallclub
+
+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

@@ -0,0 +1,392 @@
+# @matimo/github — GitHub Tools for Matimo
+
+Comprehensive GitHub REST API integration for Matimo. Execute 22 focused tools across search, issues, repositories, pull requests, commits, collaborators, releases, and code scanning.
+
+## Installation
+
+```bash
+npm install @matimo/github
+# or
+pnpm add @matimo/github
+```
+
+## Quick Start
+
+### Factory Pattern
+
+```typescript
+import { MatimoInstance } from '@matimo/core';
+
+const matimo = await MatimoInstance.init({
+  autoDiscover: true  // Auto-loads @matimo/github from node_modules
+});
+
+// Search repositories
+const repos = await matimo.execute('github-search-repositories', {
+  query: 'language:typescript stars:>1000'
+});
+
+// Create issue
+const issue = await matimo.execute('github-create-issue', {
+  owner: 'nodejs',
+  repo: 'node',
+  title: 'Bug: Memory leak in event loop',
+  body: 'Description of the issue...'
+});
+
+// Merge pull request
+const merged = await matimo.execute('github-merge-pull-request', {
+  owner: 'nodejs',
+  repo: 'node',
+  pull_number: 42,
+  merge_method: 'squash'
+});
+```
+
+### Decorator Pattern
+
+```typescript
+import { MatimoInstance, setGlobalMatimoInstance, tool } from '@matimo/core';
+
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+setGlobalMatimoInstance(matimo);
+
+class GitHubAgent {
+  @tool('github-search-repositories')
+  async searchRepos(query: string) { /* auto-executed */ }
+
+  @tool('github-create-issue')
+  async createIssue(owner: string, repo: string, title: string, body: string) {
+    /* auto-executed */
+  }
+}
+
+const agent = new GitHubAgent();
+await agent.searchRepos('language:typescript');
+```
+
+### LangChain Integration
+
+```typescript
+import { MatimoInstance } from '@matimo/core';
+
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+// Get all GitHub tools as LangChain function schemas
+const ghTools = matimo.listTools()
+  .filter(t => t.name.startsWith('github-'))
+  .map(tool => ({
+    type: 'function',
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: {
+        type: 'object',
+        properties: tool.parameters || {},
+        required: Object.entries(tool.parameters || {})
+          .filter(([_, p]) => p.required)
+          .map(([name]) => name)
+      }
+    }
+  }));
+
+// Use with your LLM + function calling
+```
+
+## Available Tools
+
+| Tool | Description | HTTP Method |
+|------|-------------|------------|
+| **Search** | | |
+| `github-search-repositories` | Search repositories by name, stars, topics | GET |
+| `github-search-code` | Search code across repositories | GET |
+| `github-search-issues` | Search issues and pull requests | GET |
+| `github-search-users` | Search users by location, followers | GET |
+| **Issues** | | |
+| `github-list-issues` | List repository issues with filtering | GET |
+| `github-create-issue` | Create a new issue | POST |
+| `github-get-issue` | Get specific issue details | GET |
+| `github-update-issue` | Update issue title, body, state | PATCH |
+| **Repositories** | | |
+| `github-list-repositories` | List organization/user repositories | GET |
+| `github-create-repository` | Create new repository | POST |
+| `github-get-repository` | Get repository details (120+ fields) | GET |
+| `github-delete-repository` | Delete repository (admin only) | DELETE |
+| **Pull Requests** | | |
+| `github-list-pull-requests` | List pull requests with filtering | GET |
+| `github-create-pull-request` | Create new pull request | POST |
+| `github-merge-pull-request` | Merge pull request | PUT |
+| **Commits** | | |
+| `github-list-commits` | List repository commits | GET |
+| **Collaborators** | | |
+| `github-list-collaborators` | List repository collaborators | GET |
+| `github-add-collaborator` | Add user as collaborator | PUT |
+| **Releases** | | |
+| `github-list-releases` | List repository releases | GET |
+| `github-create-release` | Create new release | POST |
+| **Code Scanning** | | |
+| `github-list-code-alerts` | List security scanning alerts | GET |
+| `github-update-code-alert` | Update alert status (dismiss/reopen) | PATCH |
+
+## Authentication
+
+### Personal Access Token (PAT)
+
+1. Create token at https://github.com/settings/tokens
+2. Choose scopes:
+   - **repo** — Full access to repositories
+   - **gist** — Full access to gists
+   - **user** — Read user profile
+   - **admin:org_hook** — Write organization webhooks (optional)
+   - **security_events** — Read code scanning alerts
+
+3. Set environment variable:
+
+```bash
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+```
+
+### Fine-grained Personal Access Token
+
+1. Create at https://github.com/settings/personal-access-tokens/new
+2. Minimum required permissions:
+   - Repository (selected): Code, Commit, Issues, Pull Requests, Releases, Security events
+3. Set environment variable:
+
+```bash
+export GITHUB_TOKEN=github_pat_xxxxxxxxxxxxxxxx
+```
+
+### OAuth2 (GitHub App)
+
+1. Create GitHub App at https://github.com/settings/apps
+2. Get Client ID from app settings
+3. Use OAuth2Handler for authorization:
+
+```typescript
+import { OAuth2Handler } from '@matimo/core';
+
+const handler = new OAuth2Handler('github');
+const { authorize_url, state } = handler.getAuthorizationUrl();
+
+// Redirect user to authorize_url
+// Handle callback with authorization code
+const tokens = await handler.exchangeAuthorizationCode(code, state);
+
+// tokens.access_token ready for use
+process.env.GITHUB_TOKEN = tokens.access_token;
+```
+
+## Rate Limiting
+
+GitHub has multiple rate limits:
+
+- **Primary**: 5,000 requests/hour (authenticated), 60/hour (unauthenticated)
+- **Search**: 30 requests/minute (general), 10 requests/minute (code search)
+- **Secondary**: 100 concurrent requests, 900 points/minute
+
+### Handling Rate Limits
+
+Tools include exponential backoff and retry logic. When you hit rate limits:
+- Get reset time from response header: `x-ratelimit-reset` (Unix timestamp)
+- Wait until reset time, then retry
+- Check remaining quota with `x-ratelimit-remaining` header
+
+```typescript
+// Automatic retry with exponential backoff
+try {
+  const result = await matimo.execute('github-search-code', {
+    query: 'language:python'
+  });
+} catch (error) {
+  // If 429 (rate limited), solution automatically retries with backoff
+  // If still fails after retries, throws MatimoError with details
+}
+```
+
+## Error Handling
+
+All tools throw `MatimoError` with structured error information:
+
+```typescript
+import { MatimoError } from '@matimo/core';
+
+try {
+  await matimo.execute('github-create-issue', { /* ... */ });
+} catch (error) {
+  if (error instanceof MatimoError) {
+    console.error('Code:', error.code);           // EXECUTION_FAILED
+    console.error('Message:', error.message);     // User-friendly message
+    console.error('Details:', error.details);     // { statusCode: 404, toolName: '...' }
+    
+    // Handle specific scenarios
+    if (error.code === 'EXECUTION_FAILED' && error.details?.statusCode === 404) {
+      console.error('Repository not found');
+    }
+  }
+}
+```
+
+Common GitHub API errors:
+- **401 Unauthorized** — Invalid or expired token
+- **403 Forbidden** — Insufficient permissions, rate limited, or GHSA disabled
+- **404 Not Found** — Repository, issue, or user doesn't exist
+- **422 Unprocessable Entity** — Invalid parameters
+- **429 Too Many Requests** — Rate limit exceeded
+
+## Examples
+
+### Search and Report
+
+```typescript
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+// Find high-quality TypeScript projects
+const results = await matimo.execute('github-search-repositories', {
+  query: 'language:typescript stars:>5000'
+});
+
+console.log(`Found ${results.total_count} matching repositories`);
+results.items?.slice(0, 5).forEach(repo => {
+  console.log(`- ${repo.full_name}: ⭐ ${repo.stargazers_count}`);
+});
+```
+
+### Create and Manage Issues
+
+```typescript
+// Create an issue
+const issue = await matimo.execute('github-create-issue', {
+  owner: 'myorg',
+  repo: 'myrepo',
+  title: 'Feature request: Add dark mode',
+  body: '# Description\nUsers want a dark mode theme\n\n# Solution\nImplement CSS dark mode support'
+});
+
+console.log(`Created issue #${issue.number}: ${issue.html_url}`);
+
+// Update the issue
+await matimo.execute('github-update-issue', {
+  owner: 'myorg',
+  repo: 'myrepo',
+  issue_number: issue.number,
+  state: 'closed'
+});
+```
+
+### Pull Request Workflow
+
+```typescript
+// List open PRs
+const prs = await matimo.execute('github-list-pull-requests', {
+  owner: 'kubernetes',
+  repo: 'kubernetes',
+  state: 'open',
+  sort: 'updated'
+});
+
+// Merge a PR
+if (prs.length > 0) {
+  const merged = await matimo.execute('github-merge-pull-request', {
+    owner: 'kubernetes',
+    repo: 'kubernetes',
+    pull_number: prs[0].number,
+    merge_method: 'squash'
+  });
+  
+  console.log(`Merged as commit ${merged.sha}`);
+}
+```
+
+### Security Scanning
+
+```typescript
+// List critical security alerts
+const alerts = await matimo.execute('github-list-code-alerts', {
+  owner: 'myorg',
+  repo: 'myrepo',
+  state: 'open',
+  severity: 'critical'
+});
+
+// Dismiss false positives
+for (const alert of alerts.filter(a => a.rule.id === 'false-positive')) {
+  await matimo.execute('github-update-code-alert', {
+    owner: 'myorg',
+    repo: 'myrepo',
+    alert_number: alert.number,
+    state: 'dismissed',
+    dismissed_reason: 'false positive'
+  });
+}
+```
+
+## Troubleshooting
+
+### "401 Unauthorized"
+- Verify `GITHUB_TOKEN` is set: `echo $GITHUB_TOKEN`
+- Token may be expired or revoked — create new one
+- For fine-grained PAT, verify it hasn't been expired
+
+### "403 Forbidden" for private repos
+- Ensure token has `repo` scope
+- For fine-grained tokens, ensure organization/repository is added
+- Check GitHub Advanced Security is enabled (for code scanning)
+
+### "404 Not Found"
+- Verify owner/repo names are correct
+- Check repository exists and is accessible with token
+- For code scanning, ensure Advanced Security is enabled
+
+### Rate limited (429)
+- Wait for `x-ratelimit-reset` timestamp
+- Consider implementing request queuing for bulk operations
+- Use search filters to reduce unnecessary API calls
+- For Enterprise, higher rate limits (15,000/hour) available
+
+### Code scanning not available
+- Requires GitHub Advanced Security (Enterprise or public repos with premium)
+- Verify `security_events:read` scope in token
+- Check repository has security scanning enabled
+
+## API Reference
+
+### Parameters and Response Schemas
+
+Each tool accepts specific parameters documented in its definition. Common patterns:
+
+**Pagination**: `per_page` (1-100, default 30) and `page` (starting at 1)
+**Filtering**: `state`, `sort`, `direction`, `labels`, `assignee` (varies by tool)
+**Templating**: URL parameters use `{placeholders}` syntax
+
+Responses are validated against `output_schema` defined in each tool. All responses include status codes in `x-github-` headers for monitoring rate limits.
+
+### HTTP Headers
+
+All requests include:
+```
+Accept: application/vnd.github+json
+Authorization: Bearer {GITHUB_TOKEN}
+X-GitHub-Api-Version: 2022-11-28
+Content-Type: application/json (for POST/PATCH/PUT)
+```
+
+Rate limit headers in all responses:
+```
+x-ratelimit-limit: 5000
+x-ratelimit-remaining: 4999
+x-ratelimit-reset: 1234567890
+x-ratelimit-used: 1
+```
+
+## Contributing
+
+For bug reports, feature requests, or tool improvements, visit the main Matimo repository CONTRIBUTING guidelines.
+
+## License
+
+Part of the Matimo ecosystem. See main repository for licensing information.
+
+---
+
+**Need help?** Check the [Matimo documentation](https://matimo.dev) or open an issue in the main repository.

package/definition.yaml

@@ -0,0 +1,71 @@
+# GitHub OAuth2 Provider Definition
+#
+# This file defines the OAuth2 configuration for GitHub.
+# All GitHub tools reference this provider definition.
+#
+# Users can override these endpoints via:
+# 1. Runtime config (highest priority)
+# 2. Environment variables: OAUTH_GITHUB_AUTH_URL, OAUTH_GITHUB_TOKEN_URL, etc.
+# 3. This YAML definition (lowest priority)
+#
+# Pattern: Define once, use everywhere
+
+name: github-provider
+type: provider
+version: '1.0.0'
+
+description: |
+  GitHub OAuth2 Provider Configuration
+  
+  All GitHub tools use these endpoints for OAuth2 authorization.
+  
+  Setup:
+  1. Create GitHub OAuth App at https://github.com/settings/developers
+  2. Set Client ID and Client Secret
+  3. Set Authorization callback URL
+  4. Set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET environment variables
+  5. Set GITHUB_REDIRECT_URI to your callback URL
+  
+  For GitHub Enterprise Server (GHES), override the endpoints with your instance.
+
+provider:
+  name: github
+  displayName: GitHub
+
+  # OAuth2 Endpoints
+  # Standard GitHub.com endpoints - change for GitHub Enterprise Server
+  endpoints:
+    authorizationUrl: https://github.com/login/oauth/authorize
+    tokenUrl: https://github.com/login/oauth/access_token
+    revokeUrl: https://api.github.com/applications/{client_id}/grants/{grant_id}
+
+  # Standard scopes for common GitHub operations
+  # Tools can override with their own scopes
+  defaultScopes:
+    - repo:status
+    - repo_deployment
+    - public_repo
+    - repo
+    - gist
+    - notifications
+    - user
+    - delete_repo
+    - write:packages
+    - read:packages
+    - admin:org_hook
+    - write:org
+    - read:org
+    - admin:public_key
+    - write:public_key
+    - read:public_key
+    - admin:repo_hook
+    - write:repo_hook
+    - read:repo_hook
+    - admin:org
+    - admin:gpg_key
+    - write:gpg_key
+    - read:gpg_key
+
+  # Additional metadata
+  documentation: https://docs.github.com/en/rest
+  learnMore: https://docs.github.com/en/apps/creating-github-apps

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@matimo/github",
+  "version": "0.1.0-alpha.10",
+  "description": "GitHub API tools for Matimo - Full-featured GitHub integration with OAuth2 and PAT support",
+  "type": "module",
+  "files": [
+    "tools",
+    "README.md",
+    "definition.yaml"
+  ],
+  "peerDependencies": {
+    "matimo": "0.1.0-alpha.10"
+  },
+  "devDependencies": {
+    "@matimo/core": "0.1.0-alpha.10"
+  }
+}

package/tools/add-collaborator/definition.yaml

@@ -0,0 +1,73 @@
+name: github-add-collaborator
+description: Add a user as a collaborator to a repository
+version: '1.0.0'
+requires_approval: true
+
+parameters:
+  owner:
+    type: string
+    required: true
+    description: Repository owner username or organization
+  repo:
+    type: string
+    required: true
+    description: Repository name
+  username:
+    type: string
+    required: true
+    description: GitHub username to add
+  permission:
+    type: string
+    required: false
+    description: Permission level - pull, triage, push, maintain, or admin
+    default: push
+
+execution:
+  type: http
+  method: PUT
+  url: 'https://api.github.com/repos/{owner}/{repo}/collaborators/{username}'
+  headers:
+    Accept: application/vnd.github+json
+    Authorization: 'Bearer {GITHUB_TOKEN}'
+    X-GitHub-Api-Version: '2022-11-28'
+    Content-Type: application/json
+  body:
+    permission: '{permission}'
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  notes:
+    env: GITHUB_TOKEN
+    required: true
+    permission: Repository administration
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: number
+    invitee:
+      type: object
+    permissions:
+      type: string
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+examples:
+  - name: Add collaborator with push access
+    params:
+      owner: myorg
+      repo: myrepo
+      username: newuser
+      permission: push
+  - name: Add collaborator with admin access
+    params:
+      owner: myorg
+      repo: myrepo
+      username: admin_user
+      permission: admin

package/tools/create-issue/definition.yaml

@@ -0,0 +1,96 @@
+name: github-create-issue
+description: Create a new issue in a repository
+version: '1.0.0'
+requires_approval: true
+
+parameters:
+  owner:
+    type: string
+    required: true
+    description: Repository owner username or organization
+  repo:
+    type: string
+    required: true
+    description: Repository name
+  title:
+    type: string
+    required: true
+    description: Issue title
+  body:
+    type: string
+    required: false
+    description: Issue description (markdown supported)
+  assignees:
+    type: array
+    required: false
+    description: Array of github usernames to assign
+  labels:
+    type: array
+    required: false
+    description: Array of label names
+  milestone:
+    type: number
+    required: false
+    description: Milestone ID number
+
+execution:
+  type: http
+  method: POST
+  url: 'https://api.github.com/repos/{owner}/{repo}/issues'
+  headers:
+    Accept: application/vnd.github+json
+    Authorization: 'Bearer {GITHUB_TOKEN}'
+    X-GitHub-Api-Version: '2022-11-28'
+    Content-Type: application/json
+  body:
+    title: '{title}'
+    body: '{body}'
+    assignees: '{assignees}'
+    labels: '{labels}'
+    milestone: '{milestone}'
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  notes:
+    env: GITHUB_TOKEN
+    required: true
+    permission: Issues write
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: number
+    number:
+      type: number
+      description: Issue number in repository
+    title:
+      type: string
+    state:
+      type: string
+    html_url:
+      type: string
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+examples:
+  - name: Create simple issue
+    params:
+      owner: myorg
+      repo: myrepo
+      title: Bug in login flow
+      body: Users cannot log in with SSO
+  - name: Create issue with labels
+    params:
+      owner: myorg
+      repo: myrepo
+      title: Add dark mode
+      body: Implement dark theme
+      labels:
+        - enhancement
+        - ui