pipecraft 0.0.0-releaseit → 0.26.0

package/dist/utils/config.js

@@ -1,4 +1,43 @@
+/**
+ * Configuration Loading and Validation Utilities
+ *
+ * This module provides functions to load and validate PipeCraft configuration files.
+ * It uses cosmiconfig to search for configuration in multiple locations:
+ * - .pipecraftrc.json
+ * - .pipecraftrc (JSON or YAML)
+ * - pipecraft.config.js
+ * - package.json (pipecraft key)
+ *
+ * The configuration is validated to ensure all required fields are present
+ * and have valid values before being used to generate workflows.
+ *
+ * @module utils/config
+ */
 import { cosmiconfigSync } from 'cosmiconfig';
+/**
+ * Load PipeCraft configuration from filesystem.
+ *
+ * Uses cosmiconfig to search for configuration files in standard locations.
+ * If no path is provided, searches the current directory and ancestors for
+ * configuration files in this order:
+ * 1. .pipecraftrc.json
+ * 2. .pipecraftrc
+ * 3. pipecraft.config.js
+ * 4. package.json (pipecraft key)
+ *
+ * @param configPath - Optional explicit path to configuration file
+ * @returns Parsed configuration object
+ * @throws {Error} If no configuration file is found
+ *
+ * @example
+ * ```typescript
+ * // Search for config in current directory and ancestors
+ * const config = loadConfig()
+ *
+ * // Load from explicit path
+ * const config = loadConfig('./my-config.json')
+ * ```
+ */
 export const loadConfig = (configPath) => {
     const explorer = cosmiconfigSync('pipecraft');
     const result = configPath ? explorer.load(configPath) : explorer.search();
@@ -7,25 +46,56 @@ export const loadConfig = (configPath) => {
     }
     return result.config;
 };
+/**
+ * Validate PipeCraft configuration structure and values.
+ *
+ * Performs comprehensive validation including:
+ * - Presence of all required fields
+ * - Valid enum values (ciProvider, mergeStrategy)
+ * - Branch flow structure (minimum 2 branches)
+ * - Domain configuration (paths, testable, deployable)
+ *
+ * Also sets default values for optional domain properties:
+ * - testable defaults to true
+ * - deployable defaults to true
+ *
+ * @param config - Configuration object to validate (untyped to allow validation)
+ * @returns true if validation passes
+ * @throws {Error} If validation fails with detailed error message
+ *
+ * @example
+ * ```typescript
+ * const config = loadConfig()
+ * validateConfig(config) // Throws if invalid
+ * // Safe to use config as PipecraftConfig after this point
+ * ```
+ */
 export const validateConfig = (config) => {
+    // Check for all required top-level fields
     const requiredFields = ['ciProvider', 'mergeStrategy', 'requireConventionalCommits', 'initialBranch', 'finalBranch', 'branchFlow', 'domains'];
     for (const field of requiredFields) {
         if (!(field in config)) {
             throw new Error(`Missing required field: ${field}`);
         }
     }
+    // Validate ciProvider enum
     if (!['github', 'gitlab'].includes(config.ciProvider)) {
         throw new Error('ciProvider must be either "github" or "gitlab"');
     }
+    // Validate mergeStrategy enum
     if (!['fast-forward', 'merge'].includes(config.mergeStrategy)) {
         throw new Error('mergeStrategy must be either "fast-forward" or "merge"');
     }
+    // Validate branchFlow is a non-empty array with at least 2 branches
+    // (minimum trunk-based flow requires at least develop → main)
     if (!Array.isArray(config.branchFlow) || config.branchFlow.length < 2) {
         throw new Error('branchFlow must be an array with at least 2 branches');
     }
+    // Validate domains structure
     if (typeof config.domains !== 'object') {
         throw new Error('domains must be an object');
     }
+    // Validate each domain configuration
     for (const [domainName, domainConfig] of Object.entries(config.domains)) {
         if (!domainConfig || typeof domainConfig !== 'object') {
             throw new Error(`Domain "${domainName}" must be an object`);
@@ -37,6 +107,7 @@ export const validateConfig = (config) => {
             throw new Error(`Domain "${domainName}" must have at least one path pattern`);
         }
         // Set defaults for optional properties
+        // By default, domains are both testable and deployable
         if (domainConfig.testable === undefined) {
             domainConfig.testable = true;
         }

package/dist/utils/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAG7C,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,UAAmB,EAAE,EAAE;IAChD,MAAM,QAAQ,GAAG,eAAe,CAAC,WAAW,CAAC,CAAA;IAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAA;IAEzE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,0CAA0C,UAAU,IAAI,mBAAmB,EAAE,CAAC,CAAA;IAChG,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAA;AACtB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAW,EAAE,EAAE;IAC5C,MAAM,cAAc,GAAG,CAAC,YAAY,EAAE,eAAe,EAAE,4BAA4B,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,CAAC,CAAA;IAE7I,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,2BAA2B,KAAK,EAAE,CAAC,CAAA;QACrD,CAAC;IACH,CAAC;IAED,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAA;IACnE,CAAC;IAED,IAAI,CAAC,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;IAC3E,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAA;IACzE,CAAC;IAED,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAA;IAC9C,CAAC;IAED,KAAK,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAA6B,EAAE,CAAC;QACpG,IAAI,CAAC,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,WAAW,UAAU,qBAAqB,CAAC,CAAA;QAC7D,CAAC;QAED,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CAAC,WAAW,UAAU,6BAA6B,CAAC,CAAA;QACrE,CAAC;QAED,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,WAAW,UAAU,uCAAuC,CAAC,CAAA;QAC/E,CAAC;QAED,uCAAuC;QACvC,IAAI,YAAY,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACxC,YAAY,CAAC,QAAQ,GAAG,IAAI,CAAA;QAC9B,CAAC;QACD,IAAI,YAAY,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAC1C,YAAY,CAAC,UAAU,GAAG,IAAI,CAAA;QAChC,CAAC;IACH,CAAC;IAGD,OAAO,IAAI,CAAA;AACb,CAAC,CAAA"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"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"}

package/dist/utils/github-setup.d.ts

@@ -1,35 +1,234 @@
+/**
+ * GitHub Repository Setup and Configuration
+ *
+ * This module provides utilities for setting up and configuring GitHub repositories
+ * for use with PipeCraft workflows. It handles:
+ * - Repository information extraction from git remotes
+ * - GitHub authentication token management
+ * - Workflow permissions configuration
+ * - Repository merge settings (strategies, auto-merge, PR updates)
+ * - Merge commit message format settings
+ * - Branch protection rules setup
+ * - Auto-merge enablement (two-layer system)
+ *
+ * These setup utilities ensure that GitHub repositories have the correct permissions
+ * and settings for PipeCraft workflows to function properly, including:
+ * - Workflows can create pull requests
+ * - Merge commits always use PR titles (not individual commit messages)
+ * - Auto-merge is enabled based on .pipecraftrc.json config
+ * - Branch protection is configured appropriately
+ * - Required status checks are enforced
+ *
+ * ## Auto-Merge Two-Layer System
+ *
+ * Auto-merge in GitHub works with two layers:
+ *
+ * 1. **Repository-Level Setting** (`allow_auto_merge`):
+ *    - Must be ON for auto-merge to be available at all
+ *    - Controls whether the "Enable auto-merge" button appears on PRs
+ *    - Configured by this module based on .pipecraftrc.json
+ *
+ * 2. **Per-PR Activation**:
+ *    - Must be explicitly enabled on each PR (via button, CLI, or API)
+ *    - Pipecraft workflows automatically enable it for configured branches
+ *    - Configured per-branch in .pipecraftrc.json autoMerge setting
+ *
+ * Example config:
+ * ```json
+ * {
+ *   "branchFlow": ["develop", "staging", "main"],
+ *   "autoMerge": {
+ *     "staging": true,  // Auto-merge PRs to staging
+ *     "main": true      // Auto-merge PRs to main
+ *   }
+ * }
+ * ```
+ * Result: develop requires manual review, staging and main auto-merge when checks pass
+ *
+ * @module utils/github-setup
+ */
+/**
+ * GitHub Actions workflow permissions configuration.
+ *
+ * Controls what permissions workflows have when executing in the repository.
+ * PipeCraft workflows need 'write' permissions to create PRs and manage branches.
+ */
 interface WorkflowPermissions {
+    /**
+     * Default permissions for GITHUB_TOKEN in workflow runs.
+     * - 'read': Read-only access (insufficient for PipeCraft)
+     * - 'write': Read-write access (required for PipeCraft)
+     */
     default_workflow_permissions: 'read' | 'write';
+    /**
+     * Whether workflows can approve pull request reviews.
+     * Should be false to require human approval.
+     */
     can_approve_pull_request_reviews: boolean;
 }
+/**
+ * Repository identification information extracted from git remote.
+ *
+ * Used for GitHub API calls and workflow configuration.
+ */
 interface RepositoryInfo {
+    /** GitHub organization or user name */
     owner: string;
+    /** Repository name */
     repo: string;
+    /** Full git remote URL */
     remote: string;
 }
+/**
+ * GitHub repository merge and PR settings.
+ *
+ * Controls merge strategies, auto-merge, PR branch updates, and commit message formats.
+ * These settings determine how PRs can be merged and what commit messages are created.
+ */
+interface RepositorySettings {
+    /**
+     * Allow auto-merge feature (let PRs auto-merge when checks pass)
+     */
+    allow_auto_merge?: boolean;
+    /**
+     * Always suggest updating pull request branches (keep PRs up to date with base)
+     */
+    allow_update_branch?: boolean;
+    /**
+     * Allow merge commits (creates a merge commit)
+     */
+    allow_merge_commit?: boolean;
+    /**
+     * Allow rebase merging (rebases and fast-forwards)
+     */
+    allow_rebase_merge?: boolean;
+    /**
+     * Allow squash merging (squashes all commits into one)
+     */
+    allow_squash_merge?: boolean;
+    /**
+     * Default title format for squash merge commits.
+     * - 'PR_TITLE': Use the pull request title
+     * - 'COMMIT_OR_PR_TITLE': Use commit message if single commit, PR title otherwise
+     */
+    squash_merge_commit_title?: 'PR_TITLE' | 'COMMIT_OR_PR_TITLE';
+    /**
+     * Default message format for squash merge commits.
+     * - 'PR_BODY': Use the pull request body
+     * - 'COMMIT_MESSAGES': Use all commit messages
+     * - 'BLANK': Leave message blank
+     */
+    squash_merge_commit_message?: 'PR_BODY' | 'COMMIT_MESSAGES' | 'BLANK';
+    /**
+     * Default title format for merge commits.
+     * - 'PR_TITLE': Use the pull request title
+     * - 'MERGE_MESSAGE': Use default merge message
+     */
+    merge_commit_title?: 'PR_TITLE' | 'MERGE_MESSAGE';
+    /**
+     * Default message format for merge commits.
+     * - 'PR_BODY': Use the pull request body
+     * - 'PR_TITLE': Use the pull request title
+     * - 'BLANK': Leave message blank
+     */
+    merge_commit_message?: 'PR_BODY' | 'PR_TITLE' | 'BLANK';
+}
+/**
+ * Type alias for backwards compatibility with existing functions.
+ * @deprecated Use RepositorySettings instead
+ */
+type MergeCommitSettings = RepositorySettings;
+/**
+ * GitHub branch protection rule configuration.
+ *
+ * Defines protection requirements for a branch including status checks,
+ * review requirements, and restrictions on force pushes/deletions.
+ * PipeCraft recommends specific settings for trunk-based workflows.
+ */
 interface BranchProtectionRules {
+    /**
+     * Required status checks that must pass before merging.
+     * PipeCraft sets this to enforce test jobs.
+     */
     required_status_checks: null | {
+        /** Whether branch must be up to date before merging */
         strict: boolean;
+        /** Names of required status checks (job names from workflow) */
         contexts: string[];
     };
+    /** Whether administrators are subject to branch protection rules */
     enforce_admins: boolean;
+    /**
+     * Pull request review requirements.
+     * PipeCraft typically disables this for automated promotions.
+     */
     required_pull_request_reviews: null | {
+        /** Dismiss stale reviews when new commits are pushed */
         dismiss_stale_reviews: boolean;
+        /** Require review from code owners */
         require_code_owner_reviews: boolean;
+        /** Number of approving reviews required */
         required_approving_review_count: number;
     };
+    /** User/team restrictions for who can push (null = no restrictions) */
     restrictions: null;
+    /** Allow force pushes to the branch */
     allow_force_pushes: boolean;
+    /** Allow branch deletion */
     allow_deletions: boolean;
+    /** Require linear commit history (no merge commits) */
     required_linear_history: boolean;
+    /** Require all conversations to be resolved before merging */
     required_conversation_resolution: boolean;
 }
 /**
- * Get repository information from git remote
+ * Extract GitHub repository information from git remote configuration.
+ *
+ * Parses the git remote URL for the 'origin' remote to extract owner and
+ * repository name. Supports both HTTPS and SSH GitHub URLs:
+ * - HTTPS: https://github.com/owner/repo.git
+ * - SSH: git@github.com:owner/repo.git
+ *
+ * This information is required for GitHub API calls to configure repository
+ * settings and permissions.
+ *
+ * @returns Repository information object
+ * @throws {Error} If origin remote is not configured
+ * @throws {Error} If remote URL is not a valid GitHub URL
+ *
+ * @example
+ * ```typescript
+ * const info = getRepositoryInfo()
+ * console.log(`Owner: ${info.owner}, Repo: ${info.repo}`)
+ * // Owner: jamesvillarrubia, Repo: pipecraft
+ * ```
  */
 export declare function getRepositoryInfo(): RepositoryInfo;
 /**
- * Get GitHub token from environment or gh CLI
+ * Get GitHub authentication token from environment or GitHub CLI.
+ *
+ * Attempts to retrieve a GitHub personal access token from multiple sources
+ * in this order:
+ * 1. GITHUB_TOKEN environment variable
+ * 2. GH_TOKEN environment variable
+ * 3. GitHub CLI (`gh auth token`) if authenticated
+ *
+ * The token is required for GitHub API calls to configure repository settings.
+ * Token must have 'repo' and 'workflow' scopes.
+ *
+ * @returns GitHub personal access token
+ * @throws {Error} If no token is found in any source
+ *
+ * @example
+ * ```typescript
+ * // Set token via environment
+ * process.env.GITHUB_TOKEN = 'ghp_xxxxxxxxxxxx'
+ * const token = getGitHubToken()
+ *
+ * // Or authenticate with GitHub CLI first
+ * // $ gh auth login
+ * const token = getGitHubToken() // Uses gh CLI token
+ * ```
  */
 export declare function getGitHubToken(): string;
 /**
@@ -50,6 +249,128 @@ export declare function getRequiredPermissionChanges(currentPermissions: Workflo
  * Returns: changes object if user accepted changes, 'declined' if user declined, null if already correct
  */
 export declare function promptPermissionChanges(currentPermissions: WorkflowPermissions): Promise<Partial<WorkflowPermissions> | null | 'declined'>;
+/**
+ * Get current merge commit message settings for the repository.
+ *
+ * Retrieves the default formats for merge and squash commit messages.
+ * These settings control how GitHub formats commit messages when PRs are merged.
+ *
+ * @param owner - Repository owner (organization or user)
+ * @param repo - Repository name
+ * @param token - GitHub authentication token
+ * @returns Current merge commit settings
+ * @throws {Error} If the API call fails
+ *
+ * @example
+ * ```typescript
+ * const settings = await getMergeCommitSettings('owner', 'repo', token)
+ * console.log(settings.squash_merge_commit_title) // 'PR_TITLE' or 'COMMIT_OR_PR_TITLE'
+ * ```
+ */
+export declare function getMergeCommitSettings(owner: string, repo: string, token: string): Promise<MergeCommitSettings>;
+/**
+ * Update merge commit message settings for the repository.
+ *
+ * Configures how GitHub formats commit messages when PRs are merged.
+ * PipeCraft recommends using PR_TITLE to ensure consistent commit messages
+ * regardless of whether a PR has one or multiple commits.
+ *
+ * @param owner - Repository owner (organization or user)
+ * @param repo - Repository name
+ * @param token - GitHub authentication token
+ * @param settings - Merge commit settings to apply
+ * @throws {Error} If the API call fails
+ *
+ * @example
+ * ```typescript
+ * await updateMergeCommitSettings('owner', 'repo', token, {
+ *   squash_merge_commit_title: 'PR_TITLE',
+ *   merge_commit_title: 'PR_TITLE'
+ * })
+ * ```
+ */
+export declare function updateMergeCommitSettings(owner: string, repo: string, token: string, settings: MergeCommitSettings): Promise<void>;
+/**
+ * Determine required merge commit setting changes without prompting.
+ *
+ * Checks if merge commit settings match PipeCraft's recommended configuration:
+ * - Always use PR title for squash and merge commits
+ * - This ensures consistent commit messages regardless of commit count
+ * - Only configures settings for enabled merge strategies
+ *
+ * @param currentSettings - Current merge commit settings
+ * @returns Changes object if changes needed, null if already correct
+ *
+ * @example
+ * ```typescript
+ * const settings = await getMergeCommitSettings(owner, repo, token)
+ * const changes = getRequiredMergeCommitChanges(settings)
+ * if (changes) {
+ *   await updateMergeCommitSettings(owner, repo, token, changes)
+ * }
+ * ```
+ */
+export declare function getRequiredMergeCommitChanges(currentSettings: MergeCommitSettings): MergeCommitSettings | null;
+/**
+ * Display current merge commit settings and prompt for changes.
+ *
+ * Shows the user their current merge commit message format settings and
+ * asks if they want to change them to PipeCraft's recommended configuration.
+ * Only prompts for settings that are relevant to enabled merge strategies.
+ *
+ * @param currentSettings - Current merge commit settings
+ * @returns Changes object if user accepted, 'declined' if declined, null if already correct
+ *
+ * @example
+ * ```typescript
+ * const settings = await getMergeCommitSettings(owner, repo, token)
+ * const changes = await promptMergeCommitChanges(settings)
+ * if (changes && changes !== 'declined') {
+ *   await updateMergeCommitSettings(owner, repo, token, changes)
+ * }
+ * ```
+ */
+export declare function promptMergeCommitChanges(currentSettings: MergeCommitSettings): Promise<MergeCommitSettings | null | 'declined'>;
+/**
+ * Check if auto-merge should be enabled based on .pipecraftrc.json config.
+ *
+ * Auto-merge should be enabled at the repository level if ANY branch
+ * has autoMerge configured in the config file.
+ */
+export declare function shouldEnableAutoMerge(): boolean;
+/**
+ * Get Pipecraft's recommended repository settings.
+ *
+ * These are the settings that work best with Pipecraft workflows:
+ * - Allow auto-merge: ON if any branch has autoMerge in config, OFF otherwise
+ * - Always suggest updating PR branches: ON
+ * - Allow merge commits: OFF
+ * - Allow rebase merging: OFF
+ * - Allow squash merging: ON
+ * - Squash merge commit title: PR_TITLE
+ * - Squash merge commit message: COMMIT_MESSAGES (PR title + commit details)
+ */
+export declare function getRecommendedRepositorySettings(): RepositorySettings;
+/**
+ * Get current repository settings from GitHub API.
+ */
+export declare function getRepositorySettings(owner: string, repo: string, token: string): Promise<RepositorySettings>;
+/**
+ * Update repository settings via GitHub API.
+ */
+export declare function updateRepositorySettings(owner: string, repo: string, token: string, settings: Partial<RepositorySettings>): Promise<void>;
+/**
+ * Compare current settings with recommended settings and return differences.
+ */
+export declare function getSettingsGaps(current: RepositorySettings, recommended: RepositorySettings): Partial<RepositorySettings>;
+/**
+ * Display a comparison table of current vs recommended settings.
+ */
+export declare function displaySettingsComparison(current: RepositorySettings, recommended: RepositorySettings, gaps: Partial<RepositorySettings>): void;
+/**
+ * Prompt user whether to apply recommended settings.
+ */
+export declare function promptApplySettings(gaps: Partial<RepositorySettings>): Promise<'apply' | 'declined'>;
 /**
  * Get branch protection rules
  */

package/dist/utils/github-setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"github-setup.d.ts","sourceRoot":"","sources":["../../src/utils/github-setup.ts"],"names":[],"mappings":"AAKA,UAAU,mBAAmB;IAC3B,4BAA4B,EAAE,MAAM,GAAG,OAAO,CAAA;IAC9C,gCAAgC,EAAE,OAAO,CAAA;CAC1C;AAED,UAAU,cAAc;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAED,UAAU,qBAAqB;IAC7B,sBAAsB,EAAE,IAAI,GAAG;QAC7B,MAAM,EAAE,OAAO,CAAA;QACf,QAAQ,EAAE,MAAM,EAAE,CAAA;KACnB,CAAA;IACD,cAAc,EAAE,OAAO,CAAA;IACvB,6BAA6B,EAAE,IAAI,GAAG;QACpC,qBAAqB,EAAE,OAAO,CAAA;QAC9B,0BAA0B,EAAE,OAAO,CAAA;QACnC,+BAA+B,EAAE,MAAM,CAAA;KACxC,CAAA;IACD,YAAY,EAAE,IAAI,CAAA;IAClB,kBAAkB,EAAE,OAAO,CAAA;IAC3B,eAAe,EAAE,OAAO,CAAA;IACxB,uBAAuB,EAAE,OAAO,CAAA;IAChC,gCAAgC,EAAE,OAAO,CAAA;CAC1C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAqBlD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAuBvC;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,mBAAmB,CAAC,CAkB9B;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,OAAO,CAAC,mBAAmB,CAAC,GACxC,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,kBAAkB,EAAE,mBAAmB,GACtC,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAoBrC;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,kBAAkB,EAAE,mBAAmB,GACtC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI,GAAG,UAAU,CAAC,CA6D3D;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAuBvC;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CA2ClB;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,IAAI,CAAC,CA2Ff;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,SAAS,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAmFtF"}
+{"version":3,"file":"github-setup.d.ts","sourceRoot":"","sources":["../../src/utils/github-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAOH;;;;;GAKG;AACH,UAAU,mBAAmB;IAC3B;;;;OAIG;IACH,4BAA4B,EAAE,MAAM,GAAG,OAAO,CAAA;IAE9C;;;OAGG;IACH,gCAAgC,EAAE,OAAO,CAAA;CAC1C;AAED;;;;GAIG;AACH,UAAU,cAAc;IACtB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAA;IAEb,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAA;IAEZ,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,UAAU,kBAAkB;IAC1B;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAE1B;;OAEG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAE7B;;OAEG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAE5B;;OAEG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAE5B;;OAEG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAE5B;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,UAAU,GAAG,oBAAoB,CAAA;IAE7D;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,SAAS,GAAG,iBAAiB,GAAG,OAAO,CAAA;IAErE;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,UAAU,GAAG,eAAe,CAAA;IAEjD;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,CAAA;CACxD;AAED;;;GAGG;AACH,KAAK,mBAAmB,GAAG,kBAAkB,CAAA;AAE7C;;;;;;GAMG;AACH,UAAU,qBAAqB;IAC7B;;;OAGG;IACH,sBAAsB,EAAE,IAAI,GAAG;QAC7B,uDAAuD;QACvD,MAAM,EAAE,OAAO,CAAA;QAEf,gEAAgE;QAChE,QAAQ,EAAE,MAAM,EAAE,CAAA;KACnB,CAAA;IAED,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAA;IAEvB;;;OAGG;IACH,6BAA6B,EAAE,IAAI,GAAG;QACpC,wDAAwD;QACxD,qBAAqB,EAAE,OAAO,CAAA;QAE9B,sCAAsC;QACtC,0BAA0B,EAAE,OAAO,CAAA;QAEnC,2CAA2C;QAC3C,+BAA+B,EAAE,MAAM,CAAA;KACxC,CAAA;IAED,uEAAuE;IACvE,YAAY,EAAE,IAAI,CAAA;IAElB,uCAAuC;IACvC,kBAAkB,EAAE,OAAO,CAAA;IAE3B,4BAA4B;IAC5B,eAAe,EAAE,OAAO,CAAA;IAExB,uDAAuD;IACvD,uBAAuB,EAAE,OAAO,CAAA;IAEhC,8DAA8D;IAC9D,gCAAgC,EAAE,OAAO,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAyBlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAuBvC;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,mBAAmB,CAAC,CAkB9B;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,OAAO,CAAC,mBAAmB,CAAC,GACxC,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,kBAAkB,EAAE,mBAAmB,GACtC,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAoBrC;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,kBAAkB,EAAE,mBAAmB,GACtC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI,GAAG,UAAU,CAAC,CA6D3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,mBAAmB,CAAC,CA2B9B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,mBAAmB,GACnC,mBAAmB,GAAG,IAAI,CAgB5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,wBAAwB,CAC5C,eAAe,EAAE,mBAAmB,GACnC,OAAO,CAAC,mBAAmB,GAAG,IAAI,GAAG,UAAU,CAAC,CAyDlD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAsB/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gCAAgC,IAAI,kBAAkB,CAUrE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,kBAAkB,CAAC,CA6B7B;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,CAAC,kBAAkB,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,kBAAkB,GAC9B,OAAO,CAAC,kBAAkB,CAAC,CAgC7B;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,kBAAkB,EAC/B,IAAI,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAChC,IAAI,CA8EN;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAChC,OAAO,CAAC,OAAO,GAAG,UAAU,CAAC,CAe/B;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAuBvC;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CA2ClB;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,IAAI,CAAC,CA+Ef;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,SAAS,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAuItF"}