@aspruyt/xfg 1.0.0

package/dist/repo-detector.js

@@ -0,0 +1,98 @@
+// Type guards
+export function isGitHubRepo(info) {
+    return info.type === "github";
+}
+export function isAzureDevOpsRepo(info) {
+    return info.type === "azure-devops";
+}
+/**
+ * Valid URL patterns for supported repository types.
+ */
+const GITHUB_URL_PATTERNS = [/^git@github\.com:/, /^https?:\/\/github\.com\//];
+const AZURE_DEVOPS_URL_PATTERNS = [
+    /^git@ssh\.dev\.azure\.com:/,
+    /^https?:\/\/dev\.azure\.com\//,
+];
+export function detectRepoType(gitUrl) {
+    // Check for Azure DevOps formats
+    for (const pattern of AZURE_DEVOPS_URL_PATTERNS) {
+        if (pattern.test(gitUrl)) {
+            return "azure-devops";
+        }
+    }
+    // Check for GitHub formats
+    for (const pattern of GITHUB_URL_PATTERNS) {
+        if (pattern.test(gitUrl)) {
+            return "github";
+        }
+    }
+    // Throw for unrecognized URL formats
+    throw new Error(`Unrecognized git URL format: ${gitUrl}. Supported formats: GitHub (git@github.com: or https://github.com/) and Azure DevOps (git@ssh.dev.azure.com: or https://dev.azure.com/)`);
+}
+export function parseGitUrl(gitUrl) {
+    const type = detectRepoType(gitUrl);
+    if (type === "azure-devops") {
+        return parseAzureDevOpsUrl(gitUrl);
+    }
+    return parseGitHubUrl(gitUrl);
+}
+function parseGitHubUrl(gitUrl) {
+    // Handle SSH format: git@github.com:owner/repo.git
+    // Use (.+?) with end anchor to handle repo names with dots (e.g., my.repo.git)
+    const sshMatch = gitUrl.match(/git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/);
+    if (sshMatch) {
+        return {
+            type: "github",
+            gitUrl,
+            owner: sshMatch[1],
+            repo: sshMatch[2],
+        };
+    }
+    // Handle HTTPS format: https://github.com/owner/repo.git
+    // Use (.+?) with end anchor to handle repo names with dots
+    const httpsMatch = gitUrl.match(/https?:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/);
+    if (httpsMatch) {
+        return {
+            type: "github",
+            gitUrl,
+            owner: httpsMatch[1],
+            repo: httpsMatch[2],
+        };
+    }
+    throw new Error(`Unable to parse GitHub URL: ${gitUrl}`);
+}
+function parseAzureDevOpsUrl(gitUrl) {
+    // Handle SSH format: git@ssh.dev.azure.com:v3/organization/project/repo
+    // Use (.+?) with end anchor to handle repo names with dots
+    const sshMatch = gitUrl.match(/git@ssh\.dev\.azure\.com:v3\/([^/]+)\/([^/]+)\/(.+?)(?:\.git)?$/);
+    if (sshMatch) {
+        return {
+            type: "azure-devops",
+            gitUrl,
+            owner: sshMatch[1],
+            repo: sshMatch[3],
+            organization: sshMatch[1],
+            project: sshMatch[2],
+        };
+    }
+    // Handle HTTPS format: https://dev.azure.com/organization/project/_git/repo
+    // Use (.+?) with end anchor to handle repo names with dots
+    const httpsMatch = gitUrl.match(/https?:\/\/dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/(.+?)(?:\.git)?$/);
+    if (httpsMatch) {
+        return {
+            type: "azure-devops",
+            gitUrl,
+            owner: httpsMatch[1],
+            repo: httpsMatch[3],
+            organization: httpsMatch[1],
+            project: httpsMatch[2],
+        };
+    }
+    throw new Error(`Unable to parse Azure DevOps URL: ${gitUrl}`);
+}
+export function getRepoDisplayName(repoInfo) {
+    if (repoInfo.type === "azure-devops") {
+        return `${repoInfo.organization}/${repoInfo.project}/${repoInfo.repo}`;
+    }
+    return `${repoInfo.owner}/${repoInfo.repo}`;
+}

package/dist/repository-processor.d.ts

@@ -0,0 +1,47 @@
+import { RepoConfig } from "./config.js";
+import { RepoInfo } from "./repo-detector.js";
+import { GitOps, GitOpsOptions } from "./git-ops.js";
+import { ILogger } from "./logger.js";
+import { CommandExecutor } from "./command-executor.js";
+export interface ProcessorOptions {
+    branchName: string;
+    workDir: string;
+    dryRun?: boolean;
+    /** Number of retries for network operations (default: 3) */
+    retries?: number;
+    /** Command executor for shell commands (for testing) */
+    executor?: CommandExecutor;
+}
+/**
+ * Factory function type for creating GitOps instances.
+ * Allows dependency injection for testing.
+ */
+export type GitOpsFactory = (options: GitOpsOptions) => GitOps;
+export interface ProcessorResult {
+    success: boolean;
+    repoName: string;
+    message: string;
+    prUrl?: string;
+    skipped?: boolean;
+    mergeResult?: {
+        merged: boolean;
+        autoMergeEnabled?: boolean;
+        message: string;
+    };
+}
+export declare class RepositoryProcessor {
+    private gitOps;
+    private readonly gitOpsFactory;
+    private readonly log;
+    /**
+     * Creates a new RepositoryProcessor.
+     * @param gitOpsFactory - Optional factory for creating GitOps instances (for testing)
+     * @param log - Optional logger instance (for testing)
+     */
+    constructor(gitOpsFactory?: GitOpsFactory, log?: ILogger);
+    process(repoConfig: RepoConfig, repoInfo: RepoInfo, options: ProcessorOptions): Promise<ProcessorResult>;
+    /**
+     * Format commit message based on files changed (excludes skipped files)
+     */
+    private formatCommitMessage;
+}

package/dist/repository-processor.js

@@ -0,0 +1,245 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { convertContentToString, } from "./config.js";
+import { getRepoDisplayName } from "./repo-detector.js";
+import { GitOps } from "./git-ops.js";
+import { createPR, mergePR } from "./pr-creator.js";
+import { logger } from "./logger.js";
+import { getPRStrategy } from "./strategies/index.js";
+import { defaultExecutor } from "./command-executor.js";
+/**
+ * Determines if a file should be marked as executable.
+ * .sh files are auto-executable unless explicit executable: false is set.
+ * Non-.sh files are executable only if executable: true is explicitly set.
+ */
+function shouldBeExecutable(file) {
+    const isShellScript = file.fileName.endsWith(".sh");
+    if (file.executable !== undefined) {
+        // Explicit setting takes precedence
+        return file.executable;
+    }
+    // Default: .sh files are executable, others are not
+    return isShellScript;
+}
+export class RepositoryProcessor {
+    gitOps = null;
+    gitOpsFactory;
+    log;
+    /**
+     * Creates a new RepositoryProcessor.
+     * @param gitOpsFactory - Optional factory for creating GitOps instances (for testing)
+     * @param log - Optional logger instance (for testing)
+     */
+    constructor(gitOpsFactory, log) {
+        this.gitOpsFactory = gitOpsFactory ?? ((opts) => new GitOps(opts));
+        this.log = log ?? logger;
+    }
+    async process(repoConfig, repoInfo, options) {
+        const repoName = getRepoDisplayName(repoInfo);
+        const { branchName, workDir, dryRun, retries } = options;
+        const executor = options.executor ?? defaultExecutor;
+        this.gitOps = this.gitOpsFactory({ workDir, dryRun, retries });
+        try {
+            // Step 1: Clean workspace
+            this.log.info("Cleaning workspace...");
+            this.gitOps.cleanWorkspace();
+            // Step 2: Clone repo
+            this.log.info("Cloning repository...");
+            await this.gitOps.clone(repoInfo.gitUrl);
+            // Step 3: Get default branch for PR base
+            const { branch: baseBranch, method: detectionMethod } = await this.gitOps.getDefaultBranch();
+            this.log.info(`Default branch: ${baseBranch} (detected via ${detectionMethod})`);
+            // Step 3.5: Close existing PR if exists (fresh start approach)
+            // This ensures isolated sync attempts - each run starts from clean state
+            if (!dryRun) {
+                this.log.info("Checking for existing PR...");
+                const strategy = getPRStrategy(repoInfo, executor);
+                const closed = await strategy.closeExistingPR({
+                    repoInfo,
+                    branchName,
+                    baseBranch,
+                    workDir,
+                    retries,
+                });
+                if (closed) {
+                    this.log.info("Closed existing PR and deleted branch for fresh sync");
+                }
+            }
+            // Step 4: Create branch (always fresh from base branch)
+            this.log.info(`Creating branch: ${branchName}`);
+            await this.gitOps.createBranch(branchName);
+            // Step 5: Write all config files and track changes
+            const changedFiles = [];
+            for (const file of repoConfig.files) {
+                const filePath = join(workDir, file.fileName);
+                const fileExistsLocal = existsSync(filePath);
+                // Handle createOnly - check against BASE branch, not current working directory
+                // This ensures consistent behavior: createOnly means "only create if doesn't exist on main"
+                if (file.createOnly) {
+                    const existsOnBase = await this.gitOps.fileExistsOnBranch(file.fileName, baseBranch);
+                    if (existsOnBase) {
+                        this.log.info(`Skipping ${file.fileName} (createOnly: exists on ${baseBranch})`);
+                        changedFiles.push({ fileName: file.fileName, action: "skip" });
+                        continue;
+                    }
+                }
+                this.log.info(`Writing ${file.fileName}...`);
+                const fileContent = convertContentToString(file.content, file.fileName, {
+                    header: file.header,
+                    schemaUrl: file.schemaUrl,
+                });
+                // Determine action type (create vs update)
+                const action = fileExistsLocal
+                    ? "update"
+                    : "create";
+                if (dryRun) {
+                    // In dry-run, check if file would change without writing
+                    if (this.gitOps.wouldChange(file.fileName, fileContent)) {
+                        changedFiles.push({ fileName: file.fileName, action });
+                    }
+                }
+                else {
+                    // Write the file
+                    this.gitOps.writeFile(file.fileName, fileContent);
+                }
+            }
+            // Step 5b: Set executable permission for files that need it
+            const skippedFileNames = new Set(changedFiles.filter((f) => f.action === "skip").map((f) => f.fileName));
+            for (const file of repoConfig.files) {
+                // Skip files that were excluded (createOnly + exists)
+                if (skippedFileNames.has(file.fileName)) {
+                    continue;
+                }
+                if (shouldBeExecutable(file)) {
+                    this.log.info(`Setting executable: ${file.fileName}`);
+                    await this.gitOps.setExecutable(file.fileName);
+                }
+            }
+            // Step 6: Check for changes (exclude skipped files)
+            let hasChanges;
+            if (dryRun) {
+                hasChanges = changedFiles.filter((f) => f.action !== "skip").length > 0;
+            }
+            else {
+                hasChanges = await this.gitOps.hasChanges();
+                // If there are changes, determine which files changed
+                if (hasChanges) {
+                    // Rebuild the changed files list by checking git status
+                    // Skip files that were already marked as skipped (createOnly)
+                    const skippedFiles = new Set(changedFiles
+                        .filter((f) => f.action === "skip")
+                        .map((f) => f.fileName));
+                    for (const file of repoConfig.files) {
+                        if (skippedFiles.has(file.fileName)) {
+                            continue; // Already tracked as skipped
+                        }
+                        const filePath = join(workDir, file.fileName);
+                        const action = existsSync(filePath)
+                            ? "update"
+                            : "create";
+                        changedFiles.push({ fileName: file.fileName, action });
+                    }
+                }
+            }
+            if (!hasChanges) {
+                return {
+                    success: true,
+                    repoName,
+                    message: "No changes detected",
+                    skipped: true,
+                };
+            }
+            // Step 7: Commit
+            this.log.info("Staging changes...");
+            const commitMessage = this.formatCommitMessage(changedFiles);
+            const committed = await this.gitOps.commit(commitMessage);
+            if (!committed) {
+                this.log.info("No staged changes after git add -A, skipping commit");
+                return {
+                    success: true,
+                    repoName,
+                    message: "No changes detected after staging",
+                    skipped: true,
+                };
+            }
+            this.log.info(`Committed: ${commitMessage}`);
+            // Step 8: Push
+            this.log.info("Pushing to remote...");
+            await this.gitOps.push(branchName);
+            // Step 9: Create PR
+            this.log.info("Creating pull request...");
+            const prResult = await createPR({
+                repoInfo,
+                branchName,
+                baseBranch,
+                files: changedFiles,
+                workDir,
+                dryRun,
+                retries,
+            });
+            // Step 10: Handle merge options if configured
+            const mergeMode = repoConfig.prOptions?.merge ?? "auto";
+            let mergeResult;
+            if (prResult.success && prResult.url && mergeMode !== "manual") {
+                this.log.info(`Handling merge (mode: ${mergeMode})...`);
+                const mergeConfig = {
+                    mode: mergeMode,
+                    strategy: repoConfig.prOptions?.mergeStrategy ?? "squash",
+                    deleteBranch: repoConfig.prOptions?.deleteBranch ?? true,
+                    bypassReason: repoConfig.prOptions?.bypassReason,
+                };
+                const result = await mergePR({
+                    repoInfo,
+                    prUrl: prResult.url,
+                    mergeConfig,
+                    workDir,
+                    dryRun,
+                    retries,
+                });
+                mergeResult = {
+                    merged: result.merged ?? false,
+                    autoMergeEnabled: result.autoMergeEnabled,
+                    message: result.message,
+                };
+                if (!result.success) {
+                    this.log.info(`Warning: Merge operation failed - ${result.message}`);
+                }
+                else {
+                    this.log.info(result.message);
+                }
+            }
+            return {
+                success: prResult.success,
+                repoName,
+                message: prResult.message,
+                prUrl: prResult.url,
+                mergeResult,
+            };
+        }
+        finally {
+            // Always cleanup workspace on completion or failure
+            if (this.gitOps) {
+                try {
+                    this.gitOps.cleanWorkspace();
+                }
+                catch {
+                    // Ignore cleanup errors - best effort
+                }
+            }
+        }
+    }
+    /**
+     * Format commit message based on files changed (excludes skipped files)
+     */
+    formatCommitMessage(files) {
+        const changedFiles = files.filter((f) => f.action !== "skip");
+        if (changedFiles.length === 1) {
+            return `chore: sync ${changedFiles[0].fileName}`;
+        }
+        if (changedFiles.length <= 3) {
+            const fileNames = changedFiles.map((f) => f.fileName).join(", ");
+            return `chore: sync ${fileNames}`;
+        }
+        return `chore: sync ${changedFiles.length} config files`;
+    }
+}

package/dist/retry-utils.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Default patterns indicating permanent errors that should NOT be retried.
+ * These typically indicate configuration issues, auth failures, or invalid resources.
+ * Export allows customization for different environments.
+ */
+export declare const DEFAULT_PERMANENT_ERROR_PATTERNS: RegExp[];
+/**
+ * Default patterns indicating transient errors that SHOULD be retried.
+ * These typically indicate temporary network or service issues.
+ * Export allows customization for different environments.
+ */
+export declare const DEFAULT_TRANSIENT_ERROR_PATTERNS: RegExp[];
+export interface RetryOptions {
+    /** Maximum number of retries (default: 3) */
+    retries?: number;
+    /** Callback when a retry attempt fails */
+    onRetry?: (error: Error, attempt: number) => void;
+    /** Custom permanent error patterns (defaults to DEFAULT_PERMANENT_ERROR_PATTERNS) */
+    permanentErrorPatterns?: RegExp[];
+    /** Custom transient error patterns (defaults to DEFAULT_TRANSIENT_ERROR_PATTERNS) */
+    transientErrorPatterns?: RegExp[];
+}
+/**
+ * Classifies an error as permanent (should not retry) or transient (should retry).
+ * @param error The error to classify
+ * @param patterns Custom patterns to use (defaults to DEFAULT_PERMANENT_ERROR_PATTERNS)
+ * @returns true if the error is permanent, false if it might be transient
+ */
+export declare function isPermanentError(error: Error, patterns?: RegExp[]): boolean;
+/**
+ * Checks if an error matches known transient patterns.
+ * @param error The error to check
+ * @param patterns Custom patterns to use (defaults to DEFAULT_TRANSIENT_ERROR_PATTERNS)
+ * @returns true if the error appears to be transient
+ */
+export declare function isTransientError(error: Error, patterns?: RegExp[]): boolean;
+/**
+ * Wraps an async operation with retry logic using exponential backoff.
+ * Automatically classifies errors and aborts retries for permanent failures.
+ *
+ * @param fn The async function to run with retry
+ * @param options Retry configuration options
+ * @returns The result of the function if successful
+ * @throws AbortError for permanent failures, or the last error after all retries exhausted
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Wraps a synchronous operation in a Promise for use with retry logic.
+ * @param fn The sync function to run
+ * @returns A Promise that resolves/rejects with the sync result
+ */
+export declare function promisify<T>(fn: () => T): Promise<T>;
+export { AbortError } from "p-retry";

package/dist/retry-utils.js

@@ -0,0 +1,143 @@
+import pRetry, { AbortError } from "p-retry";
+import { logger } from "./logger.js";
+/**
+ * Default patterns indicating permanent errors that should NOT be retried.
+ * These typically indicate configuration issues, auth failures, or invalid resources.
+ * Export allows customization for different environments.
+ */
+export const DEFAULT_PERMANENT_ERROR_PATTERNS = [
+    /permission\s*denied/i,
+    /authentication\s*failed/i,
+    /bad\s*credentials/i,
+    /invalid\s*(token|credentials)/i,
+    /unauthorized/i,
+    /401\b/,
+    /403\b/,
+    /404\b/,
+    /not\s*found/i,
+    /does\s*not\s*exist/i,
+    /repository\s*not\s*found/i,
+    /no\s*such\s*(file|directory|remote|ref)/i,
+    /couldn't\s*find\s*remote\s*ref/i,
+    /invalid\s*remote/i,
+    /not\s*a\s*git\s*repository/i,
+    /non-fast-forward/i,
+    /remote\s*rejected/i,
+];
+/**
+ * Default patterns indicating transient errors that SHOULD be retried.
+ * These typically indicate temporary network or service issues.
+ * Export allows customization for different environments.
+ */
+export const DEFAULT_TRANSIENT_ERROR_PATTERNS = [
+    /timed?\s*out/i,
+    /ETIMEDOUT/,
+    /ECONNRESET/,
+    /ECONNREFUSED/,
+    /ENOTFOUND/,
+    /connection\s*(reset|refused|closed)/i,
+    /network\s*(error|unreachable)/i,
+    /rate\s*limit/i,
+    /too\s*many\s*requests/i,
+    /429\b/,
+    /500\b/,
+    /502\b/,
+    /503\b/,
+    /504\b/,
+    /service\s*unavailable/i,
+    /temporarily\s*unavailable/i,
+    /internal\s*server\s*error/i,
+    /temporary\s*(failure|error)/i,
+    /try\s*again/i,
+    /ssh_exchange_identification/i,
+    /could\s*not\s*resolve\s*host/i,
+    /unable\s*to\s*access/i,
+];
+/**
+ * Classifies an error as permanent (should not retry) or transient (should retry).
+ * @param error The error to classify
+ * @param patterns Custom patterns to use (defaults to DEFAULT_PERMANENT_ERROR_PATTERNS)
+ * @returns true if the error is permanent, false if it might be transient
+ */
+export function isPermanentError(error, patterns = DEFAULT_PERMANENT_ERROR_PATTERNS) {
+    const message = error.message;
+    const stderr = error.stderr?.toString() ?? "";
+    const combined = `${message} ${stderr}`;
+    // Check permanent patterns first - these always stop retries
+    for (const pattern of patterns) {
+        if (pattern.test(combined)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Checks if an error matches known transient patterns.
+ * @param error The error to check
+ * @param patterns Custom patterns to use (defaults to DEFAULT_TRANSIENT_ERROR_PATTERNS)
+ * @returns true if the error appears to be transient
+ */
+export function isTransientError(error, patterns = DEFAULT_TRANSIENT_ERROR_PATTERNS) {
+    const message = error.message;
+    const stderr = error.stderr?.toString() ?? "";
+    const combined = `${message} ${stderr}`;
+    for (const pattern of patterns) {
+        if (pattern.test(combined)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Wraps an async operation with retry logic using exponential backoff.
+ * Automatically classifies errors and aborts retries for permanent failures.
+ *
+ * @param fn The async function to run with retry
+ * @param options Retry configuration options
+ * @returns The result of the function if successful
+ * @throws AbortError for permanent failures, or the last error after all retries exhausted
+ */
+export async function withRetry(fn, options) {
+    const retries = options?.retries ?? 3;
+    const permanentPatterns = options?.permanentErrorPatterns;
+    return pRetry(async () => {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                isPermanentError(error, permanentPatterns)) {
+                // Wrap in AbortError to stop retrying immediately
+                throw new AbortError(error.message);
+            }
+            throw error;
+        }
+    }, {
+        retries,
+        onFailedAttempt: (context) => {
+            // Only log if this isn't the last attempt
+            if (context.retriesLeft > 0) {
+                const msg = context.error.message || "Unknown error";
+                logger.info(`Attempt ${context.attemptNumber}/${retries + 1} failed: ${msg}. Retrying...`);
+                options?.onRetry?.(context.error, context.attemptNumber);
+            }
+        },
+    });
+}
+/**
+ * Wraps a synchronous operation in a Promise for use with retry logic.
+ * @param fn The sync function to run
+ * @returns A Promise that resolves/rejects with the sync result
+ */
+export function promisify(fn) {
+    return new Promise((resolve, reject) => {
+        try {
+            resolve(fn());
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+// Re-export AbortError for use in custom error handling
+export { AbortError } from "p-retry";

package/dist/shell-utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Escapes a string for safe use as a shell argument.
+ * Uses single quotes and escapes any single quotes within the string.
+ *
+ * @param arg - The string to escape
+ * @returns The escaped string wrapped in single quotes
+ */
+export declare function escapeShellArg(arg: string): string;

package/dist/shell-utils.js

@@ -0,0 +1,12 @@
+/**
+ * Escapes a string for safe use as a shell argument.
+ * Uses single quotes and escapes any single quotes within the string.
+ *
+ * @param arg - The string to escape
+ * @returns The escaped string wrapped in single quotes
+ */
+export function escapeShellArg(arg) {
+    // Use single quotes and escape any single quotes within
+    // 'string' -> quote ends, escaped quote, quote starts again
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}

package/dist/strategies/azure-pr-strategy.d.ts

@@ -0,0 +1,16 @@
+import { PRResult } from "../pr-creator.js";
+import { BasePRStrategy, PRStrategyOptions, CloseExistingPROptions, MergeOptions, MergeResult } from "./pr-strategy.js";
+import { CommandExecutor } from "../command-executor.js";
+export declare class AzurePRStrategy extends BasePRStrategy {
+    constructor(executor?: CommandExecutor);
+    private getOrgUrl;
+    private buildPRUrl;
+    checkExistingPR(options: PRStrategyOptions): Promise<string | null>;
+    closeExistingPR(options: CloseExistingPROptions): Promise<boolean>;
+    create(options: PRStrategyOptions): Promise<PRResult>;
+    /**
+     * Extract PR ID and repo info from Azure DevOps PR URL.
+     */
+    private parsePRUrl;
+    merge(options: MergeOptions): Promise<MergeResult>;
+}