@aigne/afs-github 1.11.0-beta.6

package/LICENSE.md

@@ -0,0 +1,26 @@
+# Proprietary License
+
+Copyright (c) 2024-2025 ArcBlock, Inc. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
+
+The Software is provided for internal use only within ArcBlock, Inc. and its
+authorized affiliates.
+
+## No License Granted
+
+No license, express or implied, is granted to any party for any purpose.
+All rights are reserved by ArcBlock, Inc.
+
+## Public Artifact Distribution
+
+Portions of this Software may be released publicly under separate open-source
+licenses (such as MIT License) through designated public repositories. Such
+public releases are governed by their respective licenses and do not affect
+the proprietary nature of this repository.
+
+## Contact
+
+For licensing inquiries, contact: legal@arcblock.io

package/README.md

@@ -0,0 +1,342 @@
+# @aigne/afs-github
+
+**@aigne/afs-github** is an AFS provider that enables access to GitHub Issues, Pull Requests, and Actions through the AFS virtual file system interface. It transforms GitHub's REST API into a familiar path-based structure.
+
+## Overview
+
+AFSGitHub allows AI agents to interact with GitHub repositories using the same file-system-like API as other AFS modules. Browse issues like directories, read PR details like files, and navigate repository data through intuitive paths.
+
+## Features
+
+- **GitHub API Integration**: Full access to Issues, Pull Requests, and more
+- **Path-Based Access**: Navigate GitHub data using familiar paths
+- **Single/Multi-Repo Modes**: Work with one repository or multiple
+- **Built-in Caching**: Reduce API calls with configurable cache
+- **Rate Limit Handling**: Automatic retry with exponential backoff
+- **World Mapping Capable**: Supports dynamic mapping configuration
+- **Enterprise Support**: Compatible with GitHub Enterprise
+
+## Installation
+
+```bash
+npm install @aigne/afs-github @aigne/afs
+# or
+yarn add @aigne/afs-github @aigne/afs
+# or
+pnpm add @aigne/afs-github @aigne/afs
+```
+
+## Quick Start
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSGitHub } from "@aigne/afs-github";
+
+// Create AFS instance
+const afs = new AFS();
+
+// Mount GitHub provider for a single repository
+afs.mount(new AFSGitHub({
+  auth: { token: process.env.GITHUB_TOKEN },
+  owner: "aigne",
+  repo: "afs",
+}));
+// Accessible at /modules/github
+
+// List issues
+const { data: issues } = await afs.list("/modules/github/issues");
+
+// Read a specific issue
+const { data: issue } = await afs.read("/modules/github/issues/123");
+console.log(issue.summary);  // Issue title
+console.log(issue.content);  // Issue body
+
+// List pull requests
+const { data: prs } = await afs.list("/modules/github/pulls");
+
+// Read a specific PR
+const { data: pr } = await afs.read("/modules/github/pulls/456");
+```
+
+## Configuration
+
+### AFSGitHubOptions
+
+```typescript
+interface AFSGitHubOptions {
+  // Module identification
+  name?: string;              // Module name (default: "github")
+  description?: string;       // Description for AI agents
+
+  // Authentication
+  auth?: {
+    token?: string;           // Personal Access Token
+  };
+
+  // Repository settings
+  owner?: string;             // Repository owner (required for single-repo mode)
+  repo?: string;              // Repository name (required for single-repo mode)
+  mode?: "single-repo" | "multi-repo";  // Access mode (default: "single-repo")
+
+  // API settings
+  accessMode?: "readonly" | "readwrite";  // Access level (default: "readonly")
+  baseUrl?: string;           // API base URL (default: "https://api.github.com")
+  mappingPath?: string;       // Custom mapping configuration path
+
+  // Performance
+  cache?: {
+    enabled?: boolean;        // Enable caching (default: true)
+    ttl?: number;             // Cache TTL in ms (default: 60000)
+  };
+  rateLimit?: {
+    autoRetry?: boolean;      // Auto-retry on rate limit (default: true)
+    maxRetries?: number;      // Max retry attempts (default: 3)
+  };
+}
+```
+
+### Single-Repo Mode (Default)
+
+Access a specific repository without including owner/repo in paths:
+
+```typescript
+const github = new AFSGitHub({
+  auth: { token: process.env.GITHUB_TOKEN },
+  owner: "aigne",
+  repo: "afs",
+});
+
+// Paths are relative to the repository
+await afs.list("/modules/github/issues");      // Lists aigne/afs issues
+await afs.read("/modules/github/issues/123");  // Reads aigne/afs#123
+```
+
+### Multi-Repo Mode
+
+Access multiple repositories by including owner/repo in paths:
+
+```typescript
+const github = new AFSGitHub({
+  auth: { token: process.env.GITHUB_TOKEN },
+  mode: "multi-repo",
+});
+
+// Include owner/repo in paths
+await afs.list("/modules/github/aigne/afs/issues");
+await afs.list("/modules/github/facebook/react/pulls");
+```
+
+## Path Structure
+
+### Issues
+
+```
+/issues                    # List all issues
+/issues?state=open         # Filter by state
+/issues?state=closed
+/issues/{number}           # Read specific issue
+```
+
+### Pull Requests
+
+```
+/pulls                     # List all PRs
+/pulls?state=open          # Filter by state
+/pulls?state=closed
+/pulls?state=merged
+/pulls/{number}            # Read specific PR
+```
+
+## Operations
+
+### list(path, options?)
+
+List issues or pull requests:
+
+```typescript
+// List open issues (default)
+const { data } = await afs.list("/modules/github/issues");
+
+// List closed issues
+const { data } = await afs.list("/modules/github/issues", {
+  filter: { state: "closed" },
+});
+
+// List open pull requests
+const { data } = await afs.list("/modules/github/pulls");
+
+// Each entry includes:
+// - id: Issue/PR number
+// - path: Full AFS path
+// - summary: Title
+// - content: Body text
+// - metadata: { type, state, author }
+```
+
+### read(path)
+
+Read a specific issue or PR:
+
+```typescript
+const { data } = await afs.read("/modules/github/issues/123");
+
+// Returns:
+// {
+//   id: "123",
+//   path: "/issues/123",
+//   summary: "Issue title",
+//   content: "Issue body text...",
+//   metadata: {
+//     type: "issue",
+//     state: "open",
+//     author: "username"
+//   }
+// }
+```
+
+## Integration with AI Agents
+
+AFSGitHub integrates seamlessly with AIGNE agents:
+
+```typescript
+import { AIAgent, AIGNE } from "@aigne/core";
+import { AFS } from "@aigne/afs";
+import { AFSGitHub } from "@aigne/afs-github";
+import { OpenAIChatModel } from "@aigne/openai";
+
+const aigne = new AIGNE({
+  model: new OpenAIChatModel({ apiKey: process.env.OPENAI_API_KEY }),
+});
+
+const afs = new AFS();
+afs.mount(new AFSGitHub({
+  auth: { token: process.env.GITHUB_TOKEN },
+  owner: "aigne",
+  repo: "afs",
+  description: "AFS GitHub repository issues and PRs",
+}));
+
+const agent = AIAgent.from({
+  name: "github-assistant",
+  instructions: "You help users manage GitHub issues and pull requests",
+  afs: afs,
+});
+
+const context = aigne.newContext();
+const result = await context.invoke(agent, {
+  message: "What are the open issues in this repository?",
+});
+```
+
+## World Mapping
+
+AFSGitHub implements the `AFSWorldMappingCapable` interface, allowing dynamic mapping configuration:
+
+```typescript
+const github = new AFSGitHub({
+  auth: { token: process.env.GITHUB_TOKEN },
+  owner: "aigne",
+  repo: "afs",
+});
+
+// Get mapping status
+const status = github.getMappingStatus();
+// { loaded: true, routes: 4, operations: 4, ... }
+
+// Load custom mapping
+await github.loadMapping("/path/to/custom-mapping");
+
+// Reload mapping
+await github.reloadMapping();
+
+// Resolve path to external reference
+const ref = github.resolve("/issues/123");
+// { type: "http", target: "https://api.github.com/repos/...", method: "GET", ... }
+```
+
+## GitHub Enterprise
+
+For GitHub Enterprise installations:
+
+```typescript
+const github = new AFSGitHub({
+  auth: { token: process.env.GHE_TOKEN },
+  owner: "my-org",
+  repo: "my-repo",
+  baseUrl: "https://github.mycompany.com/api/v3",
+});
+```
+
+## Authentication
+
+### Personal Access Token
+
+Create a token at https://github.com/settings/tokens with appropriate scopes:
+
+- `repo` - Full control of private repositories
+- `public_repo` - Access public repositories only
+
+```typescript
+const github = new AFSGitHub({
+  auth: { token: process.env.GITHUB_TOKEN },
+  owner: "aigne",
+  repo: "afs",
+});
+```
+
+### Without Authentication
+
+Public repositories can be accessed without authentication (with lower rate limits):
+
+```typescript
+const github = new AFSGitHub({
+  owner: "facebook",
+  repo: "react",
+});
+```
+
+## Rate Limiting
+
+GitHub API has rate limits. AFSGitHub handles this automatically:
+
+```typescript
+const github = new AFSGitHub({
+  auth: { token: process.env.GITHUB_TOKEN },
+  owner: "aigne",
+  repo: "afs",
+  rateLimit: {
+    autoRetry: true,    // Automatically retry on 429
+    maxRetries: 3,      // Maximum retry attempts
+  },
+});
+```
+
+## Caching
+
+Reduce API calls with built-in caching:
+
+```typescript
+const github = new AFSGitHub({
+  auth: { token: process.env.GITHUB_TOKEN },
+  owner: "aigne",
+  repo: "afs",
+  cache: {
+    enabled: true,      // Enable caching
+    ttl: 60000,         // 60 second TTL
+  },
+});
+```
+
+## Related Packages
+
+- [@aigne/afs](../../packages/core/README.md) - AFS core package
+- [@aigne/afs-mapping](../../packages/mapping/README.md) - Mapping DSL compiler
+- [@aigne/afs-git](../git/README.md) - Git repository provider (file access)
+
+## TypeScript Support
+
+This package includes full TypeScript type definitions:
+
+```typescript
+import type { AFSGitHub, AFSGitHubOptions, AuthOptions } from "@aigne/afs-github";
+```