/** * GitHub CLI Wrapper for SpecWeave (Multi-Project Support) * * Profile-based GitHub client that supports: * - Multiple repositories via sync profiles * - Time range filtering for syncs * - Rate limiting protection * - Secure command execution (no shell injection) */ import { GitHubIssue, GitHubMilestone, GitHubExternalChange } from './types'; import { SyncProfile, TimeRangePreset } from '../../../../../src/core/types/sync-profile'; export declare class GitHubClientV2 { private owner; private repo; private fullRepo; private token?; private projectRoot?; private static issueCache; private static searchCache; private static readonly CACHE_TTL_MS; /** * Create GitHub client from sync profile */ constructor(profile: SyncProfile, projectRoot?: string); /** * Get environment object with GH_TOKEN for gh CLI commands. * This ensures the token from .env is passed to all gh operations, * regardless of `gh auth` status. * * @returns Environment object with GH_TOKEN set if token available */ private getGhEnv; /** * Turn a failed `gh` write (create/edit/close/comment/label) into a clear error. * * When the failure looks like an auth/access problem (notably a 404 masking a * wrong-account token), resolve the token's account + write access and * explain exactly what to fix ("token has no write access to owner/repo"); * otherwise fall back to the raw gh error. */ private buildWriteError; /** * Set the project root for rate-limit budget tracking. * When set, all API calls check the shared budget before executing. */ setProjectRoot(root: string): void; /** * Budget-gated wrapper around execFileNoThrow. * Checks shared rate-limit budget before making API calls. * Skips the call with a warning if budget is exhausted. */ private execWithBudget; /** * Create client from owner/repo directly */ static fromRepo(owner: string, repo: string): GitHubClientV2; /** * Get repository owner */ getOwner(): string; /** * Get repository name */ getRepo(): string; /** * Check if GitHub CLI is installed and authenticated */ static checkCLI(): Promise<{ installed: boolean; authenticated: boolean; error?: string; }>; /** * Auto-detect repository from git remote */ static detectRepo(cwd?: string): Promise<{ owner: string; repo: string; } | null>; /** * Create or get existing milestone */ createOrGetMilestone(title: string, description?: string, daysFromNow?: number): Promise; /** * Get milestone by title */ private getMilestoneByTitle; /** * Validate issue title format * * CRITICAL: Enforces correct data flow architecture * - ✅ CORRECT: "[FS-XXX][US-YYY] Title" (User Story - STANDARD) * - ✅ CORRECT: "[FS-XXX] Title" (Feature-level, rare) * - ❌ WRONG: "[Increment XXXX] Title" (deprecated old format) * - ❌ WRONG: "[0001] Title" (plain increment ID without FS- prefix) * - ❌ WRONG: "[BUG] Title" (type prefixes are labels, not title) * - ❌ WRONG: "[HOTFIX] Title" (type prefixes are labels, not title) * - ❌ WRONG: "[FEATURE] Title" (type prefixes are labels, not title) * * @throws Error if title uses invalid format */ private validateIssueTitle; /** * Create User Story issue (for automatic GitHub sync) * * CRITICAL: This is the CORRECT format for User Story GitHub issues * Title format: [FS-XXX][US-YYY] User Story Title * * Used by: SyncCoordinator.createGitHubIssuesForUserStories() * * @param params - User story issue parameters * @returns Created GitHub issue */ createUserStoryIssue(params: { featureId: string; userStoryId: string; title: string; body: string; labels?: string[]; milestone?: number | null; }): Promise; /** * Create epic issue (increment-level) * * CRITICAL: Includes duplicate detection to prevent creating duplicate issues */ createEpicIssue(title: string, body: string, milestone?: number | string, labels?: string[], options?: { skipDuplicateCheck?: boolean; }): Promise; /** * Create task issue (linked to epic) */ createTaskIssue(title: string, body: string, epicNumber: number, milestone?: number | string, labels?: string[]): Promise; /** * Get issue details */ getIssue(issueNumber: number): Promise; /** * Search for issue by exact title match * * IDEMPOTENCY: Use this before creating issues to prevent duplicates * * @param title - Title pattern to search for (e.g., "[FS-136][US-001]") * @param includeClosedIssues - If true, searches all issues (open+closed). Default: false (open only) */ searchIssueByTitle(title: string, includeClosedIssues?: boolean): Promise; /** * Edit issue body directly without fetching current state first. * Use this for already-linked issues where we know the issue exists. * Saves 1 API call compared to the fetch-then-edit pattern. */ editIssueBody(issueNumber: number, newBody: string): Promise; /** * Update issue body */ updateIssueBody(issueNumber: number, newBody: string): Promise; /** * Close issue */ closeIssue(issueNumber: number, comment?: string): Promise; /** * Reopen a closed issue (NEW in v0.28.33) * * Used by GitHub reconciliation when increment is resumed/reopened * and the GitHub issue should reflect that state. */ reopenIssue(issueNumber: number, comment?: string): Promise; /** * Add comment to issue */ addComment(issueNumber: number, comment: string): Promise; /** * Get last comment on issue (for idempotency check) * * Returns the most recent comment body, or null if no comments exist */ getLastComment(issueNumber: number): Promise<{ body: string; author: string; } | null>; /** * Get issue details AND last comment in a single GraphQL call. * * Replaces sequential getIssue() + getLastComment() to halve API usage. * Falls back to sequential REST calls if GraphQL fails. * * @param issueNumber - GitHub issue number * @returns Issue data + last comment (or null if no comments) */ getIssueWithLastComment(issueNumber: number): Promise<{ issue: GitHubIssue; lastComment: { body: string; author: string; } | null; }>; /** * Add labels to issue */ addLabels(issueNumber: number, labels: string[]): Promise; /** * Bulk-fetch issue states for all SpecWeave-managed issues in a single search call. * Returns a Map so the reconciler can skip * per-issue getIssue() API calls. * * @param limit Max results — 100 for default mode, 1000 for --full */ bulkFetchIssueStates(limit?: number): Promise>; /** * Search for issues by feature ID and user story pattern (NEW in v0.28.33) * * Searches for issues with title matching pattern: [FS-XXX][US-YYY] * Used by GitHubReconciler to find issues not stored in metadata.json */ searchIssuesByFeature(featureId: string, userStoryId?: string): Promise; /** * List issues within a time range */ listIssuesInTimeRange(timeRange: TimeRangePreset, customStart?: string, customEnd?: string): Promise; /** * Calculate date range from time range preset */ private calculateTimeRange; /** * Check rate limit status */ checkRateLimit(): Promise<{ remaining: number; limit: number; reset: Date; }>; /** * Batch create issues with rate limit handling */ batchCreateIssues(issues: Array<{ title: string; body: string; labels?: string[]; }>, milestone?: number | string, epicNumber?: number, options?: { batchSize?: number; delayMs?: number; }): Promise; private sleep; /** * Fetch recently changed issues for pull sync * * Uses GitHub Issues API with `since` parameter to find issues * that have been updated since a given timestamp. * * @param since - Timestamp to query changes from * @param linkedIssueNumbers - Optional list of issue numbers to filter (linked items only) * @returns Array of external changes with changedAt, changedBy, and current values */ fetchRecentChanges(since: Date, linkedIssueNumbers?: number[]): Promise; /** * Get issue events for detailed change tracking * * Use this for detailed changelog when needed. * GET /repos/{owner}/{repo}/issues/{issue_number}/events * * @param issueNumber - Issue number * @param perPage - Limit number of events * @returns Array of events with action details */ getIssueEvents(issueNumber: number, perPage?: number): Promise; } //# sourceMappingURL=github-client-v2.d.ts.map