@aigne/afs-github 1.11.0-beta.6

package/dist/index.d.mts

@@ -0,0 +1,431 @@
+import { Octokit } from "@octokit/rest";
+import { WorldMappingCore } from "@aigne/afs-world-mapping";
+import { z } from "zod";
+import { AFSEntry, AFSListOptions, AFSListResult, AFSModule, AFSReadOptions, AFSReadResult, AFSRoot, AFSWorldMappingCapable, ExternalRef, MappingStatus, MutateAction, MutateResult, ProjectionContext } from "@aigne/afs";
+
+//#region src/types.d.ts
+/**
+ * Authentication options
+ */
+declare const authOptionsSchema: z.ZodObject<{
+  /** Personal Access Token */token: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  token?: string | undefined;
+}, {
+  token?: string | undefined;
+}>;
+type AuthOptions = z.infer<typeof authOptionsSchema>;
+/**
+ * Cache configuration
+ */
+declare const cacheOptionsSchema: z.ZodObject<{
+  /** Enable caching */enabled: z.ZodDefault<z.ZodBoolean>; /** Cache TTL in milliseconds */
+  ttl: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+  enabled: boolean;
+  ttl: number;
+}, {
+  enabled?: boolean | undefined;
+  ttl?: number | undefined;
+}>;
+type CacheOptions = z.infer<typeof cacheOptionsSchema>;
+/**
+ * Rate limiting configuration
+ */
+declare const rateLimitOptionsSchema: z.ZodObject<{
+  /** Enable automatic retry on rate limit */autoRetry: z.ZodDefault<z.ZodBoolean>; /** Maximum retry attempts */
+  maxRetries: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+  autoRetry: boolean;
+  maxRetries: number;
+}, {
+  autoRetry?: boolean | undefined;
+  maxRetries?: number | undefined;
+}>;
+type RateLimitOptions = z.infer<typeof rateLimitOptionsSchema>;
+/**
+ * Access mode for the provider
+ */
+declare const accessModeSchema: z.ZodDefault<z.ZodEnum<["readonly", "readwrite"]>>;
+type AccessMode = z.infer<typeof accessModeSchema>;
+/**
+ * Repository mode
+ * - single-repo: Access a single repository (requires owner and repo)
+ * - multi-repo: Access multiple repositories with full paths
+ * - org: Access all repositories in an organization (requires owner only)
+ */
+declare const repoModeSchema: z.ZodDefault<z.ZodEnum<["single-repo", "multi-repo", "org"]>>;
+type RepoMode = z.infer<typeof repoModeSchema>;
+/**
+ * Owner type for org mode
+ * - org: GitHub organization (uses /orgs/{org}/repos endpoint)
+ * - user: GitHub user account (uses /users/{username}/repos endpoint)
+ * - undefined: Auto-detect (tries org first, falls back to user)
+ */
+declare const ownerTypeSchema: z.ZodOptional<z.ZodEnum<["org", "user"]>>;
+type OwnerType = z.infer<typeof ownerTypeSchema>;
+/**
+ * Full options schema for AFSGitHub
+ */
+declare const afsGitHubOptionsSchema: z.ZodObject<{
+  /** Module name */name: z.ZodDefault<z.ZodString>; /** Module description */
+  description: z.ZodOptional<z.ZodString>; /** Authentication */
+  auth: z.ZodOptional<z.ZodObject<{
+    /** Personal Access Token */token: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    token?: string | undefined;
+  }, {
+    token?: string | undefined;
+  }>>; /** Repository owner (required for single-repo mode) */
+  owner: z.ZodOptional<z.ZodString>; /** Repository name (required for single-repo mode) */
+  repo: z.ZodOptional<z.ZodString>; /** Access mode */
+  accessMode: z.ZodOptional<z.ZodDefault<z.ZodEnum<["readonly", "readwrite"]>>>; /** Repository mode */
+  mode: z.ZodOptional<z.ZodDefault<z.ZodEnum<["single-repo", "multi-repo", "org"]>>>; /** Owner type (org or user). If not set, auto-detects by trying org first. */
+  ownerType: z.ZodOptional<z.ZodOptional<z.ZodEnum<["org", "user"]>>>; /** GitHub API base URL (for Enterprise) */
+  baseUrl: z.ZodDefault<z.ZodString>; /** Custom mapping path (overrides default) */
+  mappingPath: z.ZodOptional<z.ZodString>; /** Cache configuration */
+  cache: z.ZodOptional<z.ZodObject<{
+    /** Enable caching */enabled: z.ZodDefault<z.ZodBoolean>; /** Cache TTL in milliseconds */
+    ttl: z.ZodDefault<z.ZodNumber>;
+  }, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    ttl: number;
+  }, {
+    enabled?: boolean | undefined;
+    ttl?: number | undefined;
+  }>>; /** Rate limiting configuration */
+  rateLimit: z.ZodOptional<z.ZodObject<{
+    /** Enable automatic retry on rate limit */autoRetry: z.ZodDefault<z.ZodBoolean>; /** Maximum retry attempts */
+    maxRetries: z.ZodDefault<z.ZodNumber>;
+  }, "strip", z.ZodTypeAny, {
+    autoRetry: boolean;
+    maxRetries: number;
+  }, {
+    autoRetry?: boolean | undefined;
+    maxRetries?: number | undefined;
+  }>>; /** Default branch/ref for Contents API (optional) */
+  ref: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  name: string;
+  baseUrl: string;
+  description?: string | undefined;
+  auth?: {
+    token?: string | undefined;
+  } | undefined;
+  owner?: string | undefined;
+  repo?: string | undefined;
+  accessMode?: "readonly" | "readwrite" | undefined;
+  mode?: "single-repo" | "multi-repo" | "org" | undefined;
+  ownerType?: "org" | "user" | undefined;
+  mappingPath?: string | undefined;
+  cache?: {
+    enabled: boolean;
+    ttl: number;
+  } | undefined;
+  rateLimit?: {
+    autoRetry: boolean;
+    maxRetries: number;
+  } | undefined;
+  ref?: string | undefined;
+}, {
+  name?: string | undefined;
+  description?: string | undefined;
+  auth?: {
+    token?: string | undefined;
+  } | undefined;
+  owner?: string | undefined;
+  repo?: string | undefined;
+  accessMode?: "readonly" | "readwrite" | undefined;
+  mode?: "single-repo" | "multi-repo" | "org" | undefined;
+  ownerType?: "org" | "user" | undefined;
+  baseUrl?: string | undefined;
+  mappingPath?: string | undefined;
+  cache?: {
+    enabled?: boolean | undefined;
+    ttl?: number | undefined;
+  } | undefined;
+  rateLimit?: {
+    autoRetry?: boolean | undefined;
+    maxRetries?: number | undefined;
+  } | undefined;
+  ref?: string | undefined;
+}>;
+/**
+ * Input options type (what users provide, with optional fields)
+ */
+type AFSGitHubOptions = z.input<typeof afsGitHubOptionsSchema>;
+/**
+ * Output options type (after Zod parsing, with defaults applied)
+ */
+type AFSGitHubOptionsParsed = z.infer<typeof afsGitHubOptionsSchema>;
+/**
+ * Validated options with defaults applied
+ */
+interface AFSGitHubOptionsResolved {
+  name: string;
+  description?: string;
+  auth?: AuthOptions;
+  owner?: string;
+  repo?: string;
+  accessMode: AccessMode;
+  mode: RepoMode;
+  ownerType?: OwnerType;
+  baseUrl: string;
+  mappingPath?: string;
+  cache: CacheOptions;
+  rateLimit: RateLimitOptions;
+  ref?: string;
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * GitHub Contents API item
+ */
+interface ContentsItem {
+  name: string;
+  path: string;
+  type: "file" | "dir" | "symlink" | "submodule";
+  size: number;
+  sha: string;
+  download_url: string | null;
+  /** Base64 encoded content, only for files <1MB */
+  content?: string;
+  /** Encoding type, typically "base64" when content is present */
+  encoding?: string;
+}
+/**
+ * Response from Contents API - can be single item or array
+ */
+type ContentsResponse = ContentsItem | ContentsItem[];
+/**
+ * GitHub Branch item
+ */
+interface BranchItem {
+  name: string;
+  commit: {
+    sha: string;
+    url: string;
+  };
+  protected: boolean;
+}
+/**
+ * Options for GitHubClient
+ */
+interface GitHubClientOptions {
+  auth?: AuthOptions;
+  baseUrl?: string;
+  cache?: CacheOptions;
+  rateLimit?: RateLimitOptions;
+}
+/**
+ * GitHub API client with throttling, retry, and caching
+ */
+declare class GitHubClient {
+  private octokit;
+  private cache;
+  private cacheConfig;
+  constructor(options: GitHubClientOptions);
+  /**
+   * Make a request to the GitHub API
+   */
+  request<T = unknown>(route: string, params?: Record<string, unknown>): Promise<{
+    data: T;
+    status: number;
+    headers: Record<string, string>;
+  }>;
+  /**
+   * Generate cache key from route and params
+   */
+  private getCacheKey;
+  /**
+   * Get from cache if not expired
+   */
+  private getFromCache;
+  /**
+   * Set cache entry
+   */
+  private setCache;
+  /**
+   * Clear the cache
+   */
+  clearCache(): void;
+  /**
+   * Get the underlying Octokit instance (for advanced usage)
+   */
+  getOctokit(): Octokit;
+  /**
+   * Get repository contents at a path
+   * @param owner Repository owner
+   * @param repo Repository name
+   * @param path Path within the repository (empty string for root)
+   * @param ref Optional branch, tag, or commit SHA
+   * @returns Contents item(s) - array for directories, single item for files
+   */
+  getContents(owner: string, repo: string, path: string, ref?: string): Promise<ContentsResponse>;
+  /**
+   * Get blob content for large files (>1MB)
+   * @param owner Repository owner
+   * @param repo Repository name
+   * @param sha Blob SHA
+   * @returns Decoded content as string
+   */
+  getBlob(owner: string, repo: string, sha: string): Promise<string>;
+  /**
+   * Get repository branches
+   * @param owner Repository owner
+   * @param repo Repository name
+   * @returns Array of branch items
+   */
+  getBranches(owner: string, repo: string): Promise<BranchItem[]>;
+  /**
+   * Get default branch for a repository
+   * @param owner Repository owner
+   * @param repo Repository name
+   * @returns Default branch name
+   */
+  getDefaultBranch(owner: string, repo: string): Promise<string>;
+}
+//#endregion
+//#region src/github.d.ts
+/**
+ * AFSGitHub Provider
+ *
+ * Provides access to GitHub Issues, Pull Requests, and Actions through AFS.
+ *
+ * @example
+ * ```typescript
+ * const github = new AFSGitHub({
+ *   auth: { token: process.env.GITHUB_TOKEN },
+ *   owner: "aigne",
+ *   repo: "afs",
+ * });
+ *
+ * // Mount to AFS
+ * afs.mount("/github", github);
+ *
+ * // List issues
+ * const issues = await afs.list("/github/issues");
+ * ```
+ */
+declare class AFSGitHub implements AFSModule, AFSWorldMappingCapable {
+  readonly name: string;
+  readonly description?: string;
+  readonly accessMode: "readonly" | "readwrite";
+  private options;
+  private client;
+  private compiled;
+  private mappingPath;
+  private mappingLoadedAt?;
+  private mappingError?;
+  /** World mapping core for schema-level path resolution and field projection (Level 1) */
+  readonly worldCore: WorldMappingCore;
+  constructor(options: AFSGitHubOptions);
+  /**
+   * Load the default mapping configuration
+   */
+  private loadDefaultMapping;
+  /**
+   * Get default route definitions
+   * This is used when loading mapping synchronously
+   */
+  private getDefaultRoutes;
+  /**
+   * Get default world schema for GitHub
+   * Defines Issue, PullRequest, Comment as world kinds
+   */
+  private getDefaultWorldSchema;
+  /**
+   * Get default world binding for GitHub
+   * Maps world fields to GitHub API response fields
+   */
+  private getDefaultWorldBinding;
+  onMount?(_root: AFSRoot): void;
+  /**
+   * Resolve a path based on mode
+   * - single-repo: prepend owner/repo
+   * - org: prepend owner (org name)
+   * - multi-repo: pass through
+   */
+  resolvePath(path: string): string;
+  /**
+   * Get virtual directory structure for root path
+   * Returns the available resource types (issues, pulls, repo)
+   */
+  private getVirtualDirectories;
+  /**
+   * Check if path is root or empty
+   */
+  private isRootPath;
+  /**
+   * Get root entry (the mount point itself)
+   */
+  private getRootEntry;
+  /**
+   * Get virtual directories for a repo (issues, pulls, repo)
+   */
+  private getRepoVirtualDirectories;
+  /**
+   * Check if a path represents a repo root in org mode
+   * e.g., "/reponame" without /issues or /pulls suffix
+   */
+  private isRepoRootPath;
+  /**
+   * Format a user-friendly error message based on the error type
+   */
+  private formatErrorMessage;
+  /**
+   * Check if a path is a repo path (should be routed to Contents API)
+   * - Single-repo mode: /repo or /repo/*
+   * - Org mode: /{repoName}/repo or /{repoName}/repo/*
+   */
+  private isRepoPath;
+  /**
+   * Parse a repo path into owner, repo name, branch, and file path
+   * Structure: /repo/{branch}/{filePath}
+   * - Single-repo mode: /repo/main/src/index.ts -> { owner, repo, branch: "main", filePath: "src/index.ts" }
+   * - Org mode: /afs/repo/main/src/index.ts -> { owner, repo: "afs", branch: "main", filePath: "src/index.ts" }
+   */
+  private parseRepoPath;
+  /**
+   * Build the path prefix for a repo entry
+   */
+  private getRepoPathPrefix;
+  /**
+   * List repository contents via GitHub Contents API
+   * - /repo -> list all branches
+   * - /repo/{branch} -> list branch root
+   * - /repo/{branch}/path -> list contents at path
+   */
+  private listViaContentsAPI;
+  /**
+   * Read file content via GitHub Contents API
+   * Path format: /repo/{branch}/{filePath}
+   */
+  private readViaContentsAPI;
+  /**
+   * List organization or user repositories
+   * Uses ownerType if specified, otherwise tries org endpoint first and falls back to user
+   */
+  private listOrgRepos;
+  /**
+   * Fetch all repos with pagination support
+   */
+  private fetchAllRepos;
+  /**
+   * List entries at a path
+   */
+  list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+  /**
+   * Read a single entry
+   */
+  read(path: string, options?: AFSReadOptions): Promise<AFSReadResult>;
+  loadMapping(mappingPath: string): Promise<void>;
+  reloadMapping(): Promise<void>;
+  getMappingStatus(): MappingStatus;
+  resolve(path: string): ExternalRef | null;
+  project(externalData: unknown, context: ProjectionContext): AFSEntry[];
+  mutate(_path: string, _action: MutateAction, _payload: unknown): Promise<MutateResult>;
+}
+//#endregion
+export { AFSGitHub, AFSGitHubOptions, AFSGitHubOptionsParsed, AFSGitHubOptionsResolved, AccessMode, AuthOptions, BranchItem, CacheOptions, ContentsItem, ContentsResponse, GitHubClient, GitHubClientOptions, OwnerType, RateLimitOptions, RepoMode, accessModeSchema, afsGitHubOptionsSchema, authOptionsSchema, cacheOptionsSchema, ownerTypeSchema, rateLimitOptionsSchema, repoModeSchema };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/client.ts","../src/github.ts"],"mappings":";;;;;;;;AASA;cAAa,iBAAA,EAAiB,CAAA,CAAA,SAAA;;;;;;;KAKlB,WAAA,GAAc,CAAA,CAAE,KAAA,QAAa,iBAAA;;;;cAK5B,kBAAA,EAAkB,CAAA,CAAA,SAAA;;;;;;;;;;KAOnB,YAAA,GAAe,CAAA,CAAE,KAAA,QAAa,kBAAA;;;;cAK7B,sBAAA,EAAsB,CAAA,CAAA,SAAA;EAjBuB,kFAUxD;;;;;;;;;KAcU,gBAAA,GAAmB,CAAA,CAAE,KAAA,QAAa,sBAAA;;;;cAKjC,gBAAA,EAAgB,CAAA,CAAA,UAAA,CAAA,CAAA,CAAA,OAAA;AAAA,KAEjB,UAAA,GAAa,CAAA,CAAE,KAAA,QAAa,gBAAA;;;;;;;cAQ3B,cAAA,EAAc,CAAA,CAAA,UAAA,CAAA,CAAA,CAAA,OAAA;AAAA,KAEf,QAAA,GAAW,CAAA,CAAE,KAAA,QAAa,cAAA;;;;;;;cAQzB,eAAA,EAAe,CAAA,CAAA,WAAA,CAAA,CAAA,CAAA,OAAA;AAAA,KAEhB,SAAA,GAAY,CAAA,CAAE,KAAA,QAAa,eAAA;;;;cAK1B,sBAAA,EAAsB,CAAA,CAAA,SAAA;EA5CN,mDAA+B;2CAK/C;;IAKX;;;;;OALiC;qCAAA;;;;;;;;;;;;;;;;OAOF;;IAAmC,kFAKvD;;;;;;;;OAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2B7B;;KA4CY,gBAAA,GAAmB,CAAA,CAAE,KAAA,QAAa,sBAAA;;;;KAKlC,sBAAA,GAAyB,CAAA,CAAE,KAAA,QAAa,sBAAA;;;;UAKnC,wBAAA;EACf,IAAA;EACA,WAAA;EACA,IAAA,GAAO,WAAA;EACP,KAAA;EACA,IAAA;EACA,UAAA,EAAY,UAAA;EACZ,IAAA,EAAM,QAAA;EACN,SAAA,GAAY,SAAA;EACZ,OAAA;EACA,WAAA;EACA,KAAA,EAAO,YAAA;EACP,SAAA,EAAW,gBAAA;EACX,GAAA;AAAA;;;;;;UCnHe,YAAA;EACf,IAAA;EACA,IAAA;EACA,IAAA;EACA,IAAA;EACA,GAAA;EACA,YAAA;;EAEA,OAAA;;EAEA,QAAA;AAAA;;;;KAMU,gBAAA,GAAmB,YAAA,GAAe,YAAA;;;ADxB9C;UC6BiB,UAAA;EACf,IAAA;EACA,MAAA;IACE,GAAA;IACA,GAAA;EAAA;EAEF,SAAA;AAAA;AD9BF;;;AAAA,UCoCiB,mBAAA;EACf,IAAA,GAAO,WAAA;EACP,OAAA;EACA,KAAA,GAAQ,YAAA;EACR,SAAA,GAAY,gBAAA;AAAA;;;;cAMD,YAAA;EAAA,QACH,OAAA;EAAA,QACA,KAAA;EAAA,QACA,WAAA;cAEI,OAAA,EAAS,mBAAA;;;;EAgDf,OAAA,aAAA,CACJ,KAAA,UACA,MAAA,GAAS,MAAA,oBACR,OAAA;IAAU,IAAA,EAAM,CAAA;IAAG,MAAA;IAAgB,OAAA,EAAS,MAAA;EAAA;;;;UAgCvC,WAAA;;;AD/HV;UCsIU,YAAA;;;;UAeA,QAAA;EDrJgC;;;EC+JxC,UAAA,CAAA;EDrJA;;;EC4JA,UAAA,CAAA,GAAc,OAAA;;;;;;;;;EAcR,WAAA,CACJ,KAAA,UACA,IAAA,UACA,IAAA,UACA,GAAA,YACC,OAAA,CAAQ,gBAAA;;;;;;;;EA0BL,OAAA,CAAQ,KAAA,UAAe,IAAA,UAAc,GAAA,WAAc,OAAA;;;;;;;EAgBnD,WAAA,CAAY,KAAA,UAAe,IAAA,WAAe,OAAA,CAAQ,UAAA;;;ADvN1D;;;;ECqPQ,gBAAA,CAAiB,KAAA,UAAe,IAAA,WAAe,OAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;AD7QvD;cE2Ca,SAAA,YAAqB,SAAA,EAAW,sBAAA;EAAA,SAClC,IAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA;EAAA,QAED,OAAA;EAAA,QACA,MAAA;EAAA,QACA,QAAA;EAAA,QACA,WAAA;EAAA,QACA,eAAA;EAAA,QACA,YAAA;;WAGC,SAAA,EAAW,gBAAA;cAER,OAAA,EAAS,gBAAA;;;;UAgEb,kBAAA;EFrHqB;;;;EAAA,QEuJrB,gBAAA;;;;;UA6GA,qBAAA;;;;;UAqDA,sBAAA;EA6BR,OAAA,CAAA,CAAS,KAAA,EAAO,OAAA;;;;;;;EAUhB,WAAA,CAAY,IAAA;EFzVU;;;;EAAA,QEoYd,qBAAA;EFpYgC;;;EAAA,QEuahC,UAAA;EF7ZR;;;EAAA,QEqaQ,YAAA;;;;UA6BA,yBAAA;EFvcyB;;;;EAAA,QE2ezB,cAAA;;;;UAWA,kBAAA;;;;;;UAuCA,UAAA;;;;;;;UAuBA,aAAA;EF7iBE;;;EAAA,QE+lBF,iBAAA;EF/lBqB;;;;;AAK/B;EAL+B,QEymBf,kBAAA;;;;;UA+FA,kBAAA;EFnsBa;;;AAE7B;EAF6B,QEywBb,YAAA;;;;UAmEA,aAAA;EF10BwB;;;EEw4BhC,IAAA,CAAK,IAAA,UAAc,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,aAAA;EFh4BmC;;;EEk/BzF,IAAA,CAAK,IAAA,UAAc,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAkFtD,WAAA,CAAY,WAAA,WAAsB,OAAA;EAalC,aAAA,CAAA,GAAiB,OAAA;EAevB,gBAAA,CAAA,GAAoB,aAAA;EAgBpB,OAAA,CAAQ,IAAA,WAAe,WAAA;EA6BvB,OAAA,CAAQ,YAAA,WAAuB,OAAA,EAAS,iBAAA,GAAoB,QAAA;EAOtD,MAAA,CAAO,KAAA,UAAe,OAAA,EAAS,YAAA,EAAc,QAAA,YAAoB,OAAA,CAAQ,YAAA;AAAA"}