@aigne/afs-github 1.11.0-beta.6 → 1.11.0-beta.7

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { Octokit } from "@octokit/rest";
+import { AFSEntry, AFSExecOptions, AFSExecResult, AFSExplainOptions, AFSExplainResult, AFSListOptions, AFSListResult, AFSModule, AFSReadOptions, AFSReadResult, AFSRoot, AFSSearchOptions, AFSSearchResult, AFSStatOptions, AFSStatResult, AFSWorldMappingCapable, ExternalRef, MappingStatus, MutateAction, MutateResult, ProjectionContext } from "@aigne/afs";
 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
 /**
@@ -352,6 +352,11 @@ declare class AFSGitHub implements AFSModule, AFSWorldMappingCapable {
    * Returns the available resource types (issues, pulls, repo)
    */
   private getVirtualDirectories;
+  /**
+   * Check if path points to a file (leaf node) like /issues/{n} or /pulls/{n}
+   * These are individual issues/PRs that don't have children.
+   */
+  private isFilePath;
   /**
    * Check if path is root or empty
    */
@@ -395,11 +400,18 @@ declare class AFSGitHub implements AFSModule, AFSWorldMappingCapable {
    * - /repo -> list all branches
    * - /repo/{branch} -> list branch root
    * - /repo/{branch}/path -> list contents at path
+   *
+   * @throws AFSNotFoundError if path does not exist
    */
   private listViaContentsAPI;
   /**
-   * Read file content via GitHub Contents API
-   * Path format: /repo/{branch}/{filePath}
+   * Read via GitHub Contents API
+   * Supports:
+   * - /repo - return repo virtual directory
+   * - /repo/{branch} - return branch directory entry
+   * - /repo/{branch}/{path} - return file/directory entry
+   *
+   * @throws AFSNotFoundError if path does not exist
    */
   private readViaContentsAPI;
   /**
@@ -411,20 +423,115 @@ declare class AFSGitHub implements AFSModule, AFSWorldMappingCapable {
    * Fetch all repos with pagination support
    */
   private fetchAllRepos;
+  /**
+   * Apply limit to entries array
+   */
+  private applyLimit;
+  /**
+   * List immediate children at a path (maxDepth=1 only)
+   */
+  private listImmediate;
+  /**
+   * Check if a path represents a directory (has children)
+   */
+  private isDirectoryPath;
   /**
    * List entries at a path
+   *
+   * Per AFS semantics:
+   * - maxDepth=0: return empty array (no children)
+   * - maxDepth=1: return immediate children
+   * - maxDepth>1: recursively include deeper levels
+   * - limit: maximum number of entries to return
+   *
+   * @throws AFSNotFoundError if path does not exist
    */
   list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+  /**
+   * Check if path is a .meta path and extract the target path
+   */
+  private isMetaPath;
+  /**
+   * Get entry info for a virtual directory path
+   */
+  private getVirtualDirectoryEntry;
   /**
    * Read a single entry
+   *
+   * Supports:
+   * - Directory paths (returns entry info)
+   * - .meta paths (returns metadata)
+   * - Issue/PR paths (returns content via API)
+   * - Repo file paths (returns content via Contents API)
+   *
+   * @throws AFSNotFoundError if path does not exist
    */
   read(path: string, options?: AFSReadOptions): Promise<AFSReadResult>;
+  /**
+   * Read metadata for a path
+   * Returns an entry with meta field containing the metadata
+   *
+   * @throws AFSNotFoundError if path does not exist
+   */
+  private readMeta;
   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>;
+  /**
+   * Get metadata for a path without content.
+   * Supports issues, PRs, and virtual directories.
+   */
+  stat(path: string, _options?: AFSStatOptions): Promise<AFSStatResult>;
+  private statIssue;
+  private statPR;
+  /**
+   * Search issues and PRs using the GitHub Search API.
+   * Path determines scope: /issues searches issues, /pulls searches PRs, / searches both.
+   */
+  search(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
+  /**
+   * Provide human/LLM-readable explanation of a path.
+   */
+  explain(path: string, _options?: AFSExplainOptions): Promise<AFSExplainResult>;
+  private explainRoot;
+  private explainIssuesDir;
+  private explainPullsDir;
+  private explainIssue;
+  private explainPR;
+  private readCapabilities;
+  /**
+   * Get enriched metadata for an issue or PR path.
+   * Returns labels, assignees, milestone, reactions from GitHub API.
+   */
+  private getEnrichedMeta;
+  private extractReactions;
+  private zeroReactions;
+  /**
+   * Parse a path to determine if it's an issue or PR path.
+   * Returns { type, number } or null.
+   */
+  private parseIssuePRPath;
+  /**
+   * List available actions at a path.
+   * Returns null if the path is not an .actions path.
+   */
+  private listActions;
+  /**
+   * Execute an action at a path.
+   * Path format: /{resource}/.actions/{action-name}
+   */
+  exec(path: string, args: Record<string, unknown>, _options: AFSExecOptions): Promise<AFSExecResult>;
+  private execRootAction;
+  private execIssueAction;
+  private execPRAction;
+  /**
+   * Handle errors from action execution.
+   * Sanitizes error messages to prevent token leaks.
+   */
+  private handleExecError;
 }
 //#endregion
 export { AFSGitHub, AFSGitHubOptions, AFSGitHubOptionsParsed, AFSGitHubOptionsResolved, AccessMode, AuthOptions, BranchItem, CacheOptions, ContentsItem, ContentsResponse, GitHubClient, GitHubClientOptions, OwnerType, RateLimitOptions, RepoMode, accessModeSchema, afsGitHubOptionsSchema, authOptionsSchema, cacheOptionsSchema, ownerTypeSchema, rateLimitOptionsSchema, repoModeSchema };

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/client.ts","../src/github.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/client.ts","../src/github.ts"],"mappings":"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"}