@elizaos/plugin-github 1.2.9 → 2.0.0-alpha.2

package/README.md

@@ -1,658 +0,0 @@
-# ElizaOS GitHub Plugin
-
-A comprehensive GitHub integration plugin for ElizaOS that provides repository
-management, issue tracking, pull request workflows, and activity monitoring
-capabilities.
-
-## Features
-
-### 🏗️ Repository Management
-
-- **Get Repository Info**: Retrieve detailed information about any GitHub
-  repository
-- **List Repositories**: View your repositories with filtering and sorting
-  options
-- **Create Repositories**: Create new repositories with customizable settings
-- **Search Repositories**: Find repositories across GitHub using advanced
-  queries
-
-### 🐛 Issue Management
-
-- **Get Issue Details**: Fetch comprehensive information about specific issues
-- **List Issues**: View issues with state, label, and milestone filtering
-- **Create Issues**: Submit new issues with labels, assignees, and milestones
-- **Search Issues**: Find issues across repositories using powerful search
-  queries
-
-### 🔄 Pull Request Workflows
-
-- **Get PR Details**: Retrieve detailed pull request information
-- **List Pull Requests**: View PRs with state and branch filtering
-- **Create Pull Requests**: Open new PRs from feature branches
-- **Merge Pull Requests**: Merge approved PRs with different merge strategies
-
-### 📊 Activity Tracking & Monitoring
-
-- **Activity Dashboard**: Real-time tracking of all GitHub operations performed
-  by the agent
-- **Rate Limit Monitoring**: Track GitHub API usage and remaining quota
-- **Error Handling**: Comprehensive error tracking and reporting
-- **Success Metrics**: Monitor operation success rates and performance
-
-### 🔄 State Management & Chaining
-
-- **Contextual State**: Actions automatically update and chain state between
-  operations
-- **Smart Defaults**: Use previous operation results to inform subsequent
-  actions
-- **Provider Integration**: Rich context providers for repositories, issues, and
-  PRs
-
-### 🔔 Webhook Integration & Real-Time Events
-
-- **Ngrok Integration**: Automatic tunnel creation for local development
-- **Webhook Management**: Create, list, delete, and test repository webhooks
-- **Event Processing**: Real-time handling of GitHub events (issues, PRs,
-  comments)
-- **Signature Verification**: Secure webhook payload validation
-
-### 🤖 Auto-Coding Capabilities
-
-- **Issue Analysis**: AI-powered analysis of GitHub issues for automation
-  potential
-- **Automated PRs**: Create pull requests to fix simple issues automatically
-- **Smart Mentions**: Respond when @mentioned in issues or comments
-- **Complexity Detection**: Identifies when human intervention is needed
-
-## Installation
-
-```bash
-# Add to your ElizaOS project
-elizaos install @elizaos/plugin-github
-
-# Or manually add to package.json
-npm install @elizaos/plugin-github
-```
-
-## Configuration
-
-The plugin uses `runtime.getSetting` to retrieve configuration values, with
-fallback to environment variables.
-
-### Runtime Configuration (Recommended)
-
-```typescript
-// Configure via agent settings
-const agent = new Agent({
-  settings: {
-    GITHUB_TOKEN: 'ghp_your_personal_access_token_here',
-    GITHUB_TOKEN: 'github_pat_your_fine_grained_token', // Alternative
-    GITHUB_OWNER: 'your-username-or-org', // Optional default
-  },
-});
-```
-
-### Environment Variables (Fallback)
-
-```bash
-# GitHub Personal Access Token (required)
-GITHUB_TOKEN=ghp_your_personal_access_token_here
-
-# Alternative: GitHub PAT (legacy support)
-GITHUB_TOKEN=ghp_your_personal_access_token_here
-
-# Optional: Default GitHub username/organization
-GITHUB_OWNER=your-username-or-org
-```
-
-The plugin will check for tokens in this order:
-
-1. `runtime.getSetting('GITHUB_TOKEN')`
-2. `runtime.getSetting('GITHUB_TOKEN')`
-3. Global configuration object
-4. Environment variables (`process.env.GITHUB_TOKEN` or
-   `process.env.GITHUB_TOKEN`)
-
-### Token Types Supported
-
-1. **Personal Access Tokens (PAT)**: `ghp_...`
-2. **Fine-grained Personal Access Tokens**: `github_pat_...`
-3. **GitHub App tokens**: `ghs_...`
-4. **OAuth App tokens**: `gho_...`
-5. **User-to-server tokens**: `ghu_...`
-6. **Server-to-server tokens**: `ghr_...`
-
-### Token Permissions Required
-
-For full functionality, your token needs these permissions:
-
-- `repo` - Full repository access
-- `read:user` - Read user profile information
-- `read:org` - Read organization membership (if using organization repos)
-
-## Usage Examples
-
-### Repository Operations
-
-```typescript
-// Get repository information
-await runtime.executeAction('GET_GITHUB_REPOSITORY', {
-  owner: 'elizaOS',
-  repo: 'eliza',
-});
-
-// List your repositories
-await runtime.executeAction('LIST_GITHUB_REPOSITORIES', {
-  type: 'owner',
-  sort: 'updated',
-  limit: 10,
-});
-
-// Create a new repository
-await runtime.executeAction('CREATE_GITHUB_REPOSITORY', {
-  name: 'my-new-project',
-  description: 'A new project created by ElizaOS',
-  private: false,
-  auto_init: true,
-});
-
-// Search for repositories
-await runtime.executeAction('SEARCH_GITHUB_REPOSITORIES', {
-  query: 'language:typescript elizaos',
-  sort: 'stars',
-  limit: 5,
-});
-```
-
-### Issue Management
-
-```typescript
-// Get issue details
-await runtime.executeAction('GET_GITHUB_ISSUE', {
-  owner: 'elizaOS',
-  repo: 'eliza',
-  issue_number: 42,
-});
-
-// Create a new issue
-await runtime.executeAction('CREATE_GITHUB_ISSUE', {
-  owner: 'elizaOS',
-  repo: 'eliza',
-  title: 'Bug: Authentication not working',
-  body: 'Detailed description of the issue...',
-  labels: ['bug', 'authentication'],
-  assignees: ['maintainer'],
-});
-
-// List open issues
-await runtime.executeAction('LIST_GITHUB_ISSUES', {
-  owner: 'elizaOS',
-  repo: 'eliza',
-  state: 'open',
-  labels: 'bug',
-});
-
-// Search issues globally
-await runtime.executeAction('SEARCH_GITHUB_ISSUES', {
-  query: 'is:issue is:open label:bug repo:elizaOS/eliza',
-  sort: 'updated',
-});
-```
-
-### Pull Request Workflows
-
-```typescript
-// Create a pull request
-await runtime.executeAction('CREATE_GITHUB_PULL_REQUEST', {
-  owner: 'elizaOS',
-  repo: 'eliza',
-  title: 'Add new GitHub integration',
-  head: 'feature/github-integration',
-  base: 'main',
-  body: 'This PR adds comprehensive GitHub integration...',
-  draft: false,
-});
-
-// Get PR details
-await runtime.executeAction('GET_GITHUB_PULL_REQUEST', {
-  owner: 'elizaOS',
-  repo: 'eliza',
-  pull_number: 25,
-});
-
-// Merge a pull request
-await runtime.executeAction('MERGE_GITHUB_PULL_REQUEST', {
-  owner: 'elizaOS',
-  repo: 'eliza',
-  pull_number: 25,
-  merge_method: 'squash',
-});
-```
-
-### Activity Monitoring
-
-```typescript
-// View recent activity
-await runtime.executeAction('GET_GITHUB_ACTIVITY', {
-  limit: 20,
-  filter: 'all',
-});
-
-// Check rate limit status
-await runtime.executeAction('GET_GITHUB_RATE_LIMIT');
-
-// Clear activity log
-await runtime.executeAction('CLEAR_GITHUB_ACTIVITY');
-```
-
-## Natural Language Interface
-
-The plugin supports natural language commands:
-
-```
-"Get information about the elizaOS/eliza repository"
-"Create a new repository called my-awesome-project"
-"List my open issues"
-"Create an issue in elizaOS/eliza about authentication bugs"
-"Show me recent GitHub activity"
-"What's my current GitHub rate limit?"
-```
-
-## State Management & Action Chaining
-
-The plugin automatically manages state between operations, enabling powerful
-action chaining:
-
-### Basic State Management
-
-```typescript
-// First, get a repository (stores in state)
-await getRepositoryAction.handler(runtime, message, state, {
-  owner: 'elizaOS',
-  repo: 'eliza',
-});
-
-// Then, create an issue (automatically uses the repository from state)
-await createIssueAction.handler(runtime, message, updatedState, {
-  title: 'New issue',
-  body: 'Issue description',
-  // owner and repo automatically filled from state
-});
-```
-
-### Advanced Action Chaining
-
-Actions can be chained together for complex workflows:
-
-```typescript
-// Example: Search → Analyze → Create Issue workflow
-const workflow = async () => {
-  // Step 1: Search for repositories
-  const searchResult = await runtime.executeAction(
-    'SEARCH_GITHUB_REPOSITORIES',
-    {
-      query: 'language:typescript stars:>1000',
-      sort: 'stars',
-    }
-  );
-
-  // Step 2: Get details of the top repository
-  const topRepo = searchResult.repositories[0];
-  const repoDetails = await runtime.executeAction('GET_GITHUB_REPOSITORY', {
-    owner: topRepo.owner.login,
-    repo: topRepo.name,
-  });
-
-  // Step 3: Check existing issues
-  const issues = await runtime.executeAction('LIST_GITHUB_ISSUES', {
-    owner: topRepo.owner.login,
-    repo: topRepo.name,
-    state: 'open',
-    labels: 'enhancement',
-  });
-
-  // Step 4: Create a new issue based on analysis
-  if (issues.issues.length < 5) {
-    await runtime.executeAction('CREATE_GITHUB_ISSUE', {
-      owner: topRepo.owner.login,
-      repo: topRepo.name,
-      title: 'Consider adding TypeScript strict mode',
-      body: `Based on analysis, this repository could benefit from TypeScript strict mode.
-             Current stars: ${repoDetails.repository.stargazers_count}
-             Open enhancement issues: ${issues.issues.length}`,
-    });
-  }
-};
-```
-
-### Complex Multi-Step Workflows
-
-```typescript
-// Repository Health Check Workflow
-const checkRepositoryHealth = async (owner: string, repo: string) => {
-  // Check rate limit first
-  const rateLimit = await runtime.executeAction('GET_GITHUB_RATE_LIMIT');
-
-  if (rateLimit.rateLimit.remaining < 10) {
-    throw new Error('Rate limit too low for health check');
-  }
-
-  // Get repository info
-  const repository = await runtime.executeAction('GET_GITHUB_REPOSITORY', {
-    owner,
-    repo,
-  });
-
-  // Check open issues
-  const openIssues = await runtime.executeAction('LIST_GITHUB_ISSUES', {
-    owner,
-    repo,
-    state: 'open',
-    per_page: 100,
-  });
-
-  // Check open PRs
-  const openPRs = await runtime.executeAction('LIST_GITHUB_PULL_REQUESTS', {
-    owner,
-    repo,
-    state: 'open',
-    per_page: 100,
-  });
-
-  // Search for stale issues
-  const staleIssues = await runtime.executeAction('SEARCH_GITHUB_ISSUES', {
-    query: `repo:${owner}/${repo} is:open updated:<${new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0]}`,
-  });
-
-  return {
-    repository: repository.repository,
-    health: {
-      stars: repository.repository.stargazers_count,
-      openIssues: openIssues.issues.length,
-      openPRs: openPRs.pullRequests.length,
-      staleIssues: staleIssues.total_count,
-      lastUpdate: repository.repository.updated_at,
-    },
-    recommendations: generateRecommendations(
-      repository,
-      openIssues,
-      openPRs,
-      staleIssues
-    ),
-  };
-};
-```
-
-## HTTP API Endpoints
-
-When the plugin is loaded, it exposes these HTTP endpoints:
-
-- `GET /api/github/status` - Plugin status and authentication info
-- `GET /api/github/activity` - Recent GitHub activity with statistics
-- `GET /api/github/rate-limit` - Current GitHub API rate limit status
-
-## Provider Context
-
-The plugin provides rich context through these providers:
-
-- **GITHUB_REPOSITORY_CONTEXT** - Current repository information
-- **GITHUB_ISSUES_CONTEXT** - Recent issues and current issue details
-- **GITHUB_PULL_REQUESTS_CONTEXT** - PR information and merge status
-- **GITHUB_ACTIVITY_CONTEXT** - Activity statistics and recent operations
-- **GITHUB_USER_CONTEXT** - Authenticated user information
-
-## Actions Reference
-
-### Repository Actions
-
-| Action                       | Description                | Parameters                             |
-| ---------------------------- | -------------------------- | -------------------------------------- |
-| `GET_GITHUB_REPOSITORY`      | Get repository information | `owner`, `repo`                        |
-| `LIST_GITHUB_REPOSITORIES`   | List user repositories     | `type`, `sort`, `limit`                |
-| `CREATE_GITHUB_REPOSITORY`   | Create new repository      | `name`, `description`, `private`, etc. |
-| `SEARCH_GITHUB_REPOSITORIES` | Search repositories        | `query`, `sort`, `limit`               |
-
-### Issue Actions
-
-| Action                 | Description            | Parameters                                 |
-| ---------------------- | ---------------------- | ------------------------------------------ |
-| `GET_GITHUB_ISSUE`     | Get issue details      | `owner`, `repo`, `issue_number`            |
-| `LIST_GITHUB_ISSUES`   | List repository issues | `owner`, `repo`, `state`, `labels`         |
-| `CREATE_GITHUB_ISSUE`  | Create new issue       | `owner`, `repo`, `title`, `body`, `labels` |
-| `SEARCH_GITHUB_ISSUES` | Search issues          | `query`, `sort`, `limit`                   |
-
-### Pull Request Actions
-
-| Action                       | Description         | Parameters                                       |
-| ---------------------------- | ------------------- | ------------------------------------------------ |
-| `GET_GITHUB_PULL_REQUEST`    | Get PR details      | `owner`, `repo`, `pull_number`                   |
-| `LIST_GITHUB_PULL_REQUESTS`  | List repository PRs | `owner`, `repo`, `state`, `head`, `base`         |
-| `CREATE_GITHUB_PULL_REQUEST` | Create new PR       | `owner`, `repo`, `title`, `head`, `base`, `body` |
-| `MERGE_GITHUB_PULL_REQUEST`  | Merge PR            | `owner`, `repo`, `pull_number`, `merge_method`   |
-
-### Activity Actions
-
-| Action                  | Description           | Parameters                         |
-| ----------------------- | --------------------- | ---------------------------------- |
-| `GET_GITHUB_ACTIVITY`   | Get activity log      | `limit`, `filter`, `resource_type` |
-| `CLEAR_GITHUB_ACTIVITY` | Clear activity log    | None                               |
-| `GET_GITHUB_RATE_LIMIT` | Get rate limit status | None                               |
-
-## Integration with Other Plugins
-
-This plugin is designed to work seamlessly with other ElizaOS plugins:
-
-### Plugin Manager Integration
-
-The GitHub plugin provides all the functionality needed by
-`plugin-plugin-manager`:
-
-```typescript
-// The plugin-plugin-manager can use GitHub service directly
-const githubService = runtime.getService<GitHubService>('github');
-
-// All GitHub operations are available
-await githubService.createRepository(options);
-await githubService.getRepository(owner, repo);
-await githubService.createPullRequest(owner, repo, prOptions);
-```
-
-### Security Features
-
-- **Token Validation**: Automatic validation of GitHub token formats
-- **Rate Limiting**: Built-in rate limit monitoring and handling
-- **Error Handling**: Comprehensive error handling with user-friendly messages
-- **Input Sanitization**: All inputs are validated and sanitized
-- **Activity Logging**: All operations are logged for audit purposes
-
-## Testing
-
-The plugin includes comprehensive test coverage with multiple test suites:
-
-### Unit Tests
-
-```bash
-# Run unit tests
-npm test
-
-# Or with elizaos
-elizaos test component
-```
-
-### Integration Tests
-
-Test how components work together:
-
-```bash
-npm test integration.test.ts
-```
-
-### Action Chaining Tests
-
-Test complex workflows and state management:
-
-```bash
-npm test action-chaining.test.ts
-```
-
-### Runtime Scenario Tests
-
-Test various runtime configurations:
-
-```bash
-npm test runtime-scenarios.test.ts
-```
-
-### End-to-End Tests (Requires GitHub Token)
-
-Test with real GitHub API:
-
-```bash
-# Set your GitHub token first
-export GITHUB_TOKEN=ghp_your_token_here
-
-# Run E2E tests
-npm test e2e.test.ts
-
-# Or with elizaos
-elizaos test e2e
-```
-
-**Note**: E2E tests will interact with real GitHub repositories. Use a test
-account or be prepared for actual API calls.
-
-### Webhook E2E Tests (Real GitHub Events)
-
-Test complete webhook functionality with live events:
-
-```bash
-# Set up environment
-export GITHUB_TOKEN=ghp_your_token_here
-export GITHUB_OWNER=your-username
-export TEST_REPO=test-webhook-repo
-
-# Start your ElizaOS agent first
-elizaos start --character github-agent.json
-
-# Run automated E2E webhook tests
-npm run test:e2e
-```
-
-This will:
-
-- ✅ Create webhooks via Ngrok tunnel
-- ✅ Test real GitHub issue mentions
-- ✅ Verify auto-coding PR creation
-- ✅ Test complex issue handling
-- ✅ Validate webhook signature verification
-- ✅ Clean up test artifacts
-
-See [E2E_TESTING.md](./E2E_TESTING.md) for detailed testing instructions.
-
-### Test Coverage
-
-- **Unit Tests**: Individual component functionality
-- **Integration Tests**: Component interactions
-- **E2E Tests**: Real GitHub API operations
-- **Action Chaining**: Complex workflow validation
-- **Runtime Scenarios**: Various configuration tests
-
-### Writing Custom Tests
-
-```typescript
-// Example test for your own workflows
-describe('Custom GitHub Workflow', () => {
-  it('should perform repository analysis', async () => {
-    const runtime = createTestRuntime({
-      settings: {
-        GITHUB_TOKEN: process.env.GITHUB_TOKEN,
-      },
-    });
-
-    // Your test logic here
-    const result = await runtime.executeAction('SEARCH_GITHUB_REPOSITORIES', {
-      query: 'your-search-query',
-    });
-
-    expect(result.repositories).toBeDefined();
-  });
-});
-```
-
-## Development
-
-### Local Development
-
-```bash
-# Start development mode with hot reload
-elizaos dev
-
-# Build the plugin
-elizaos build
-
-# Run linting
-elizaos lint
-```
-
-### Environment Setup
-
-1. Create a `.env` file with your GitHub token:
-
-   ```bash
-   GITHUB_TOKEN=your_github_token_here
-   GITHUB_OWNER=your_username
-   ```
-
-2. Ensure your token has the required permissions for testing
-
-## Troubleshooting
-
-### Common Issues
-
-**Authentication Failed**
-
-- Verify your GitHub token is valid and not expired
-- Check that your token has the required permissions
-- Ensure the token format is correct (`ghp_...` or `github_pat_...`)
-
-**Rate Limit Exceeded**
-
-- Check your rate limit status: `GET_GITHUB_RATE_LIMIT`
-- Wait for the rate limit to reset
-- Consider using a GitHub App token for higher limits
-
-**Permission Denied**
-
-- Verify your token has access to the repository
-- Check if the repository is private and your token has `repo` scope
-- Ensure organization permissions if working with org repositories
-
-**Network Issues**
-
-- Check your internet connection
-- Verify GitHub's status at [status.github.com](https://status.github.com)
-- Try again with exponential backoff
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for your changes
-4. Ensure all tests pass
-5. Submit a pull request
-
-## License
-
-This project is licensed under the same license as ElizaOS.
-
-## Support
-
-For support and questions:
-
-- Create an issue in the ElizaOS repository
-- Join the ElizaOS Discord community
-- Check the ElizaOS documentation
-
----
-
-**Built with ❤️ for the ElizaOS ecosystem**