GitHub Integration

/**
 * GitHub integration plugin for releases and repository operations
 * Handles GitHub releases, asset uploads, and repository integration
 */
class GitHub extends Plugin {
  /** Initialize GitHub plugin with authentication and repository validation */
  init(): Promise<void>;
  
  /** Authentication and validation */
  isAuthenticated(): Promise<boolean>;
  isCollaborator(): Promise<boolean>;
  
  /** Get latest version from GitHub releases */
  getLatestVersion(): Promise<string>;
  
  /** Get changelog from GitHub commits and pull requests */
  getChangelog(): Promise<string>;
  
  /**
   * Create GitHub release
   * @returns Promise resolving to boolean indicating success
   */
  release(): Promise<boolean>;
  
  /** Log release URL after successful release */
  afterRelease(): void;
  
  /** Release management */
  createRelease(): Promise<Release>;
  updateRelease(): Promise<boolean>;
  getLatestRelease(): Promise<Release>;
  createWebRelease(): Promise<void>;
  generateWebUrl(): Promise<string>;
  
  /** Asset management */
  uploadAsset(filePath: string): Promise<any>;
  uploadAssets(): Promise<void>;
  
  /** Repository information */
  getWebUrl(): string;
  getReleaseUrlFallback(tagName: string): string;
  
  /** Comments and interaction */
  commentOnResolvedItems(): Promise<void>;
  getCommits(): Promise<any[]>;
  renderReleaseNotes(releaseNotes: any): Promise<string>;
  
  /** Client and utilities */
  get client(): any;
  retry(fn: () => Promise<any>): Promise<any>;
  handleError(err: any, bail: boolean): void;
  getOctokitReleaseOptions(options?: any): Promise<any>;
}

/**
 * Create GitHub release with notes and assets
 * @param options - Release creation options
 * @returns Promise resolving to GitHub release object
 */
createRelease(options: CreateReleaseOptions): Promise<GitHubRelease>;

/**
 * Upload assets to existing GitHub release
 * @param releaseId - GitHub release ID
 * @param assets - Array of asset file paths or glob patterns
 * @returns Promise that resolves when all assets are uploaded
 */
uploadAssets(releaseId: number, assets: string[]): Promise<void>;

/**
 * Get GitHub release by tag name
 * @param tag - Git tag name
 * @returns Promise resolving to release object or null if not found
 */
getReleaseByTag(tag: string): Promise<GitHubRelease | null>;

/**
 * Update existing GitHub release
 * @param releaseId - GitHub release ID
 * @param options - Update options
 * @returns Promise resolving to updated release object
 */
updateRelease(releaseId: number, options: UpdateReleaseOptions): Promise<GitHubRelease>;

interface CreateReleaseOptions extends ReleaseOptions {
  /** Release tag name */
  tag_name: string;
  /** Release name/title */
  name?: string;
  /** Release description/body */
  body?: string;
  /** Whether this is a draft release */
  draft?: boolean;
  /** Whether this is a pre-release */
  prerelease?: boolean;
  /** Commit SHA or branch name for release */
  target_commitish?: string;
}

interface UpdateReleaseOptions {
  /** Updated release name */
  name?: string;
  /** Updated release body */
  body?: string;
  /** Updated draft status */
  draft?: boolean;
  /** Updated pre-release status */
  prerelease?: boolean;
}

interface GitHubRelease {
  /** Release ID */
  id: number;
  /** Release tag name */
  tag_name: string;
  /** Release name */
  name: string;
  /** Release body/description */
  body: string;
  /** Draft status */
  draft: boolean;
  /** Pre-release status */
  prerelease: boolean;
  /** Release HTML URL */
  html_url: string;
  /** Upload URL for assets */
  upload_url: string;
  /** Array of release assets */
  assets: GitHubAsset[];
}

interface GitHubAsset {
  /** Asset ID */
  id: number;
  /** Asset name */
  name: string;
  /** Asset download URL */
  browser_download_url: string;
  /** Asset size in bytes */
  size: number;
  /** Asset content type */
  content_type: string;
}

/**
 * Get GitHub repository web URL
 * @returns Repository web URL string
 */
getWebUrl(): string;

/**
 * Get GitHub repository API URL  
 * @returns Repository API URL string
 */
getApiUrl(): string;

/**
 * Get GitHub repository information
 * @returns Promise resolving to repository object
 */
getRepository(): Promise<GitHubRepository>;

/**
 * Get GitHub repository owner and name
 * @returns Object with owner and repository name
 */
getRepositoryInfo(): { owner: string; repo: string };

interface GitHubRepository {
  /** Repository ID */
  id: number;
  /** Repository name */
  name: string;
  /** Repository full name (owner/repo) */
  full_name: string;
  /** Repository description */
  description: string;
  /** Repository HTML URL */
  html_url: string;
  /** Repository clone URL */
  clone_url: string;
  /** Repository SSH URL */
  ssh_url: string;
  /** Default branch name */
  default_branch: string;
  /** Repository visibility */
  private: boolean;
}

/**
 * Validate and resolve asset file paths
 * @param assets - Array of file paths or glob patterns
 * @returns Promise resolving to array of resolved file paths
 */
resolveAssets(assets: string[]): Promise<string[]>;

/**
 * Upload single asset file to release
 * @param uploadUrl - GitHub upload URL from release
 * @param filePath - Path to asset file
 * @returns Promise resolving to uploaded asset object
 */
uploadAsset(uploadUrl: string, filePath: string): Promise<GitHubAsset>;

/**
 * Get MIME type for asset file
 * @param filePath - Path to asset file
 * @returns MIME type string
 */
getAssetContentType(filePath: string): string;

interface GitHubOptions {
  /** Enable/disable GitHub plugin entirely */
  disabled?: boolean;
  
  /** Enable/disable GitHub release creation */
  release?: boolean;
  
  /** GitHub personal access token for authentication */
  token?: string;
  
  /** Release name template (supports context interpolation) */
  releaseName?: string;
  
  /** Release body/notes template (supports context interpolation) */
  releaseNotes?: string;
  
  /** Create draft release (default: false) */
  draft?: boolean;
  
  /** Mark as pre-release for pre-release versions (default: auto-detect) */
  preRelease?: boolean;
  
  /** Auto-generate release notes using GitHub's API */
  autoGenerate?: boolean;
  
  /** Asset files to upload (file paths or glob patterns) */
  assets?: string[];
  
  /** GitHub API host (for GitHub Enterprise) */
  host?: string;
  
  /** GitHub API path prefix (for GitHub Enterprise) */
  pathPrefix?: string;
  
  /** HTTP proxy configuration */
  proxy?: string;
  
  /** Request timeout in milliseconds */
  timeout?: number;
  
  /** Number of retry attempts for failed requests */
  retries?: number;
  
  /** Minimum timeout between retries in milliseconds */
  retryMinTimeout?: number;
  
  /** Update existing release if tag already exists */
  update?: boolean;
  
  /** Comments configuration for issue/PR processing */
  comments?: {
    /** Submit comments on resolved issues */
    submit?: boolean;
    /** Include resolved issues in release notes */
    issue?: string;
    /** Include merged PRs in release notes */
    pr?: string;
  };
  
  /** Web configuration */
  web?: boolean;
}

// Basic GitHub release configuration
const result = await runTasks({
  github: {
    release: true,
    releaseName: "Release ${version}",
    assets: ["dist/*.zip", "docs/*.pdf"]
  }
});

// Advanced GitHub configuration with custom templates
const result = await runTasks({
  github: {
    release: true,
    releaseName: "🚀 ${name} v${version}",
    releaseNotes: "## Changes\n\n${changelog}\n\n## Installation\n\nnpm install ${name}@${version}",
    draft: false,
    preRelease: false,
    assets: [
      "dist/bundle.min.js",
      "dist/bundle.min.css",
      "docs/api.md"
    ],
    autoGenerate: true,
    update: true
  }
});

// GitHub Enterprise configuration
const result = await runTasks({
  github: {
    release: true,
    token: process.env.GITHUB_TOKEN,
    host: "github.internal.company.com",
    pathPrefix: "/api/v3",
    proxy: "http://proxy.company.com:8080"
  }
});

// GitHub with issue/PR comments
const result = await runTasks({
  github: {
    release: true,
    comments: {
      submit: true,
      issue: "Released in ${version}: ${releaseUrl}",
      pr: "🎉 Merged PR is now available in ${version}"
    }
  }
});