@herdctl/core 0.0.1

package/dist/work-sources/adapters/github.d.ts

@@ -0,0 +1,290 @@
+/**
+ * GitHub Work Source Adapter
+ *
+ * Provides work items from GitHub Issues. Uses labels to identify
+ * work that is ready for agents and to track in-progress work.
+ *
+ * Includes robust handling of GitHub API edge cases:
+ * - Exponential backoff for rate limit errors (HTTP 403 with X-RateLimit-Remaining: 0)
+ * - Rate limit status detection and surfacing
+ * - Network error retries (max 3 attempts)
+ * - Graceful handling of 404 errors (issue deleted/moved)
+ * - PAT scope validation
+ * - Warnings for approaching rate limit (< 100 remaining)
+ */
+import type { WorkSourceAdapter } from "../index.js";
+import type { FetchOptions, FetchResult, ClaimResult, WorkResult, ReleaseOptions, ReleaseResult, WorkItem } from "../types.js";
+import type { WorkSourceConfig } from "../registry.js";
+import { WorkSourceError } from "../errors.js";
+/**
+ * GitHub API rate limit information extracted from response headers
+ */
+export interface RateLimitInfo {
+    /** Maximum number of requests allowed per hour */
+    limit: number;
+    /** Number of requests remaining in current window */
+    remaining: number;
+    /** Unix timestamp when rate limit resets */
+    reset: number;
+    /** Resource type (core, search, graphql, etc.) */
+    resource: string;
+}
+/**
+ * Options for rate limit warning callback
+ */
+export interface RateLimitWarningOptions {
+    /** Threshold below which warnings are triggered (default: 100) */
+    warningThreshold?: number;
+    /** Callback invoked when rate limit is approaching */
+    onWarning?: (info: RateLimitInfo) => void;
+}
+/**
+ * Configuration for retry behavior
+ */
+export interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Base delay in milliseconds for exponential backoff (default: 1000) */
+    baseDelayMs?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelayMs?: number;
+    /** Jitter factor (0-1) to randomize delays (default: 0.1) */
+    jitterFactor?: number;
+}
+/**
+ * Configuration specific to GitHub work source
+ */
+export interface GitHubWorkSourceConfig extends WorkSourceConfig {
+    type: "github";
+    /** GitHub repository owner */
+    owner?: string;
+    /** GitHub repository name */
+    repo?: string;
+    /** GitHub API token (defaults to GITHUB_TOKEN env var) */
+    token?: string;
+    /** GitHub API base URL (defaults to https://api.github.com) */
+    apiBaseUrl?: string;
+    /** Label configuration for work item states */
+    labels?: {
+        /** Label that marks issues as ready for agent work (default: "ready") */
+        ready?: string;
+        /** Label applied when an agent claims the issue (default: "agent-working") */
+        in_progress?: string;
+    };
+    /** Labels to exclude from fetched issues (default: ["blocked", "wip"]) */
+    exclude_labels?: string[];
+    /** Re-add ready label when releasing work on failure (default: true) */
+    cleanup_on_failure?: boolean;
+    /** Retry configuration for handling transient failures */
+    retry?: RetryOptions;
+    /** Rate limit warning configuration */
+    rateLimitWarning?: RateLimitWarningOptions;
+}
+/**
+ * GitHub API issue response structure
+ */
+export interface GitHubIssue {
+    number: number;
+    title: string;
+    body: string | null;
+    html_url: string;
+    state: "open" | "closed";
+    labels: Array<{
+        name: string;
+    }>;
+    created_at: string;
+    updated_at: string;
+    assignee: {
+        login: string;
+    } | null;
+    assignees: Array<{
+        login: string;
+    }>;
+    milestone: {
+        title: string;
+        number: number;
+    } | null;
+    user: {
+        login: string;
+    } | null;
+}
+/**
+ * Error thrown when GitHub API requests fail
+ */
+export declare class GitHubAPIError extends WorkSourceError {
+    /** HTTP status code from the API response */
+    readonly statusCode?: number;
+    /** The API endpoint that was called */
+    readonly endpoint?: string;
+    /** Rate limit information if available */
+    readonly rateLimitInfo?: RateLimitInfo;
+    /** Whether this error was caused by rate limiting */
+    readonly isRateLimitError: boolean;
+    /** Timestamp when rate limit resets (for rate limit errors) */
+    readonly rateLimitResetAt?: Date;
+    constructor(message: string, options?: {
+        cause?: Error;
+        statusCode?: number;
+        endpoint?: string;
+        rateLimitInfo?: RateLimitInfo;
+        isRateLimitError?: boolean;
+    });
+    /**
+     * Check if this error is retryable (rate limit or network error)
+     */
+    isRetryable(): boolean;
+    /**
+     * Check if this is a not found error (404)
+     */
+    isNotFound(): boolean;
+    /**
+     * Check if this is a permission error (403 without rate limit)
+     */
+    isPermissionDenied(): boolean;
+    /**
+     * Get time in milliseconds until rate limit resets
+     */
+    getTimeUntilReset(): number | undefined;
+}
+/**
+ * Error thrown when PAT validation fails
+ */
+export declare class GitHubAuthError extends WorkSourceError {
+    /** The scopes that were found */
+    readonly foundScopes: string[];
+    /** The scopes that were required */
+    readonly requiredScopes: string[];
+    /** The missing scopes */
+    readonly missingScopes: string[];
+    constructor(message: string, options: {
+        cause?: Error;
+        foundScopes: string[];
+        requiredScopes: string[];
+    });
+}
+/**
+ * Extract rate limit information from GitHub API response headers
+ */
+export declare function extractRateLimitInfo(headers: Headers): RateLimitInfo | undefined;
+/**
+ * Check if a response indicates rate limiting
+ */
+export declare function isRateLimitResponse(response: Response): boolean;
+/**
+ * Calculate delay with exponential backoff and jitter
+ */
+export declare function calculateBackoffDelay(attempt: number, options: Required<RetryOptions>, rateLimitResetMs?: number): number;
+/**
+ * Work source adapter for GitHub Issues
+ *
+ * Fetches issues with a specific label and allows claiming/completing them.
+ * Uses the GitHub REST API to manage issue labels and comments.
+ */
+export declare class GitHubWorkSourceAdapter implements WorkSourceAdapter {
+    readonly type: "github";
+    private readonly config;
+    private readonly labels;
+    private readonly excludeLabels;
+    private readonly apiBaseUrl;
+    private readonly retryOptions;
+    private readonly rateLimitWarningThreshold;
+    private readonly onRateLimitWarning?;
+    /** Last known rate limit info, updated after each request */
+    private _lastRateLimitInfo?;
+    constructor(config: GitHubWorkSourceConfig);
+    /**
+     * Get the last known rate limit information
+     */
+    get lastRateLimitInfo(): RateLimitInfo | undefined;
+    /**
+     * Get the GitHub API token from config or environment
+     */
+    private getToken;
+    /**
+     * Get required owner and repo from config
+     */
+    private getOwnerRepo;
+    /**
+     * Validate PAT has required scopes for GitHub adapter functionality
+     *
+     * Makes a request to check the token scopes and verifies
+     * that the required scopes (repo) are present.
+     *
+     * @throws GitHubAuthError if required scopes are missing
+     * @throws GitHubAPIError if the validation request fails
+     */
+    validateToken(): Promise<{
+        scopes: string[];
+        valid: boolean;
+    }>;
+    /**
+     * Check rate limit and invoke warning callback if below threshold
+     */
+    private checkRateLimitWarning;
+    /**
+     * Make an authenticated request to the GitHub API with retry logic
+     *
+     * Implements:
+     * - Exponential backoff for rate limit errors (HTTP 403 with X-RateLimit-Remaining: 0)
+     * - Network error retries (max 3 attempts by default)
+     * - Rate limit status tracking and warnings
+     */
+    private apiRequest;
+    /**
+     * Make an authenticated request to the GitHub API with retry logic, returning both data and headers
+     *
+     * This variant returns the response headers along with the data, useful for
+     * pagination (Link header) and other response metadata.
+     */
+    private apiRequestWithHeaders;
+    /**
+     * Extract the issue number from a work item ID
+     */
+    private parseWorkItemId;
+    /**
+     * Convert a GitHub issue to a WorkItem
+     */
+    private issueToWorkItem;
+    /**
+     * Infer priority from issue labels
+     */
+    private inferPriority;
+    /**
+     * Build the query string for fetching issues
+     */
+    private buildIssueQuery;
+    /**
+     * Extract pagination cursor from Link header
+     */
+    private extractNextPage;
+    /**
+     * Fetch available work items from GitHub Issues
+     *
+     * Queries issues with the ready label, excludes issues with blocked/wip labels,
+     * and returns them sorted by creation date (oldest first).
+     *
+     * Includes retry logic for transient failures and rate limit handling.
+     */
+    fetchAvailableWork(options?: FetchOptions): Promise<FetchResult>;
+    /**
+     * Claim a work item by adding the in-progress label and removing the ready label
+     */
+    claimWork(workItemId: string): Promise<ClaimResult>;
+    /**
+     * Complete a work item by posting a comment with the result and optionally closing the issue
+     */
+    completeWork(workItemId: string, result: WorkResult): Promise<void>;
+    /**
+     * Release a claimed work item by removing in-progress label and re-adding ready label
+     */
+    releaseWork(workItemId: string, options?: ReleaseOptions): Promise<ReleaseResult>;
+    /**
+     * Get a specific work item by ID
+     */
+    getWork(workItemId: string): Promise<WorkItem | undefined>;
+}
+/**
+ * Factory function for creating GitHub adapters
+ */
+export declare function createGitHubAdapter(config: WorkSourceConfig): WorkSourceAdapter;
+//# sourceMappingURL=github.d.ts.map

package/dist/work-sources/adapters/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../src/work-sources/adapters/github.ts"],"names":[],"mappings":"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"}