@aspruyt/xfg 2.1.2 → 2.2.0

package/README.md

@@ -70,64 +70,6 @@ repos:
 
 **Result:** PRs are created in all three repos with identical `.prettierrc.json` files.
 
-## Features
-
-- **Multi-File Sync** - Sync multiple config files in a single run
-- **Multi-Format Output** - JSON, JSON5, YAML, or plain text based on filename extension
-- **Subdirectory Support** - Sync files to any path (e.g., `.github/workflows/ci.yaml`)
-- **Text Files** - Sync `.gitignore`, `.markdownlintignore`, etc. with string or lines array
-- **File References** - Use `@path/to/file` to load content from external template files
-- **Content Inheritance** - Define base config once, override per-repo as needed
-- **Multi-Repo Targeting** - Apply same config to multiple repos with array syntax
-- **Environment Variables** - Use `${VAR}` syntax for dynamic values
-- **Templating** - Use `${xfg:repo.name}` syntax for dynamic repo-specific content
-- **Merge Strategies** - Control how arrays merge (replace, append, prepend)
-- **Override Mode** - Skip merging entirely for specific repos
-- **Empty Files** - Create files with no content (e.g., `.prettierignore`)
-- **YAML Comments** - Add header comments and schema directives to YAML files
-- **Multi-Platform** - Works with GitHub (including GitHub Enterprise Server), Azure DevOps, and GitLab (including self-hosted)
-- **Auto-Merge PRs** - Automatically merge PRs when checks pass, or force merge with admin privileges
-- **Direct Push Mode** - Push directly to default branch without creating PRs
-- **Delete Orphaned Files** - Automatically remove files from repos when deleted from config (manifest-tracked)
-- **Dry-Run Mode** - Preview changes without creating PRs
-- **Error Resilience** - Continues processing if individual repos fail
-- **Automatic Retries** - Retries transient network errors with exponential backoff
-
-## Use Cases
-
-### Platform Engineering Teams
-
-Enforce organization-wide standards without requiring a monorepo. Push consistent tooling configs (linters, formatters, TypeScript settings) to hundreds of microservice repos from a single source of truth.
-
-### CI/CD Workflow Standardization
-
-Keep GitHub Actions workflows, Azure Pipelines, or GitLab CI configs in sync across all repos. Update a workflow once, create PRs everywhere.
-
-### Security & Compliance Governance
-
-Roll out security scanning configs (Dependabot, CodeQL, SAST tools) or compliance policies across your entire organization. Audit and update security settings from one place.
-
-### Developer Experience Consistency
-
-Sync `.editorconfig`, `.prettierrc`, `tsconfig.json`, and other DX configs so every repo feels the same. Onboard new team members faster with consistent tooling.
-
-### Open Source Maintainers
-
-Manage configuration across multiple related projects. Keep issue templates, contributing guidelines, and CI workflows consistent across your ecosystem.
-
-### Configuration Drift Prevention
-
-Detect and fix configuration drift automatically. Run xfg on a schedule to ensure repos stay in compliance with your standards.
-
-**[See detailed use cases with examples →](https://anthony-spruyt.github.io/xfg/use-cases/)**
-
 ## Documentation
 
-Visit **[anthony-spruyt.github.io/xfg](https://anthony-spruyt.github.io/xfg/)** for:
-
-- [Getting Started](https://anthony-spruyt.github.io/xfg/getting-started/) - Installation and prerequisites
-- [Configuration](https://anthony-spruyt.github.io/xfg/configuration/) - Full configuration reference
-- [Examples](https://anthony-spruyt.github.io/xfg/examples/) - Real-world usage examples
-- [Platforms](https://anthony-spruyt.github.io/xfg/platforms/) - GitHub, Azure DevOps, GitLab setup
-- [CI/CD Integration](https://anthony-spruyt.github.io/xfg/ci-cd/) - GitHub Actions, Azure Pipelines
-- [Troubleshooting](https://anthony-spruyt.github.io/xfg/troubleshooting/)
+See **[anthony-spruyt.github.io/xfg](https://anthony-spruyt.github.io/xfg/)** for configuration reference, examples, platform setup, and troubleshooting.

package/dist/repository-processor.d.ts

@@ -41,6 +41,8 @@ export declare class RepositoryProcessor {
     private gitOps;
     private readonly gitOpsFactory;
     private readonly log;
+    private retries;
+    private executor;
     /**
      * Creates a new RepositoryProcessor.
      * @param gitOpsFactory - Optional factory for creating GitOps instances (for testing)

package/dist/repository-processor.js

@@ -6,7 +6,7 @@ import { interpolateXfgContent } from "./xfg-template.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 { getPRStrategy, getCommitStrategy } from "./strategies/index.js";
 import { defaultExecutor } from "./command-executor.js";
 import { getFileStatus, generateDiff, createDiffStats, incrementDiffStats, } from "./diff-utils.js";
 import { loadManifest, saveManifest, updateManifest, MANIFEST_FILENAME, } from "./manifest.js";
@@ -28,6 +28,8 @@ export class RepositoryProcessor {
     gitOps = null;
     gitOpsFactory;
     log;
+    retries = 3;
+    executor = defaultExecutor;
     /**
      * Creates a new RepositoryProcessor.
      * @param gitOpsFactory - Optional factory for creating GitOps instances (for testing)
@@ -39,9 +41,14 @@ export class RepositoryProcessor {
     }
     async process(repoConfig, repoInfo, options) {
         const repoName = getRepoDisplayName(repoInfo);
-        const { branchName, workDir, dryRun, retries, prTemplate } = options;
-        const executor = options.executor ?? defaultExecutor;
-        this.gitOps = this.gitOpsFactory({ workDir, dryRun, retries });
+        const { branchName, workDir, dryRun, prTemplate } = options;
+        this.retries = options.retries ?? 3;
+        this.executor = options.executor ?? defaultExecutor;
+        this.gitOps = this.gitOpsFactory({
+            workDir,
+            dryRun,
+            retries: this.retries,
+        });
         // Determine merge mode early - affects workflow steps
         const mergeMode = repoConfig.prOptions?.merge ?? "auto";
         const isDirectMode = mergeMode === "direct";
@@ -64,13 +71,13 @@ export class RepositoryProcessor {
             // Skip for direct mode - no PR involved
             if (!dryRun && !isDirectMode) {
                 this.log.info("Checking for existing PR...");
-                const strategy = getPRStrategy(repoInfo, executor);
+                const strategy = getPRStrategy(repoInfo, this.executor);
                 const closed = await strategy.closeExistingPR({
                     repoInfo,
                     branchName,
                     baseBranch,
                     workDir,
-                    retries,
+                    retries: this.retries,
                 });
                 if (closed) {
                     this.log.info("Closed existing PR and deleted branch for fresh sync");
@@ -105,6 +112,8 @@ export class RepositoryProcessor {
             // Track pre-write actions for non-dry-run mode (issue #252)
             // We need to know if a file was created vs updated BEFORE writing it
             const preWriteActions = new Map();
+            // Track file changes for commit strategy (path -> content, null for deletion)
+            const fileChangesForCommit = new Map();
             for (const file of repoConfig.files) {
                 const filePath = join(workDir, file.fileName);
                 const fileExistsLocal = existsSync(filePath);
@@ -154,6 +163,8 @@ export class RepositoryProcessor {
                     // Write the file and store pre-write action for stats calculation
                     preWriteActions.set(file.fileName, action);
                     this.gitOps.writeFile(file.fileName, fileContent);
+                    // Track content for commit strategy
+                    fileChangesForCommit.set(file.fileName, fileContent);
                 }
             }
             // Step 5b: Set executable permission for files that need it
@@ -192,6 +203,8 @@ export class RepositoryProcessor {
                         else {
                             this.log.info(`Deleting orphaned file: ${fileName}`);
                             this.gitOps.deleteFile(fileName);
+                            // Track deletion for commit strategy
+                            fileChangesForCommit.set(fileName, null);
                         }
                         changedFiles.push({ fileName, action: "delete" });
                     }
@@ -206,6 +219,9 @@ export class RepositoryProcessor {
             if (hasAnyManagedFiles || existingManifest !== null) {
                 if (!dryRun) {
                     saveManifest(workDir, newManifest);
+                    // Track manifest content for commit strategy
+                    const manifestContent = JSON.stringify(newManifest, null, 2) + "\n";
+                    fileChangesForCommit.set(MANIFEST_FILENAME, manifestContent);
                 }
                 // Track manifest file as changed if it would be different
                 const existingConfigs = existingManifest?.configs ?? {};
@@ -289,45 +305,68 @@ export class RepositoryProcessor {
                     diffStats,
                 };
             }
-            // Step 7: Commit
-            this.log.info("Staging changes...");
+            // Step 7: Commit and Push using commit strategy
             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,
-                    diffStats,
-                };
-            }
-            this.log.info(`Committed: ${commitMessage}`);
-            // Step 8: Push
-            // In direct mode, push to default branch; otherwise push to sync branch
-            // Use force-with-lease for sync branch (PR modes) to handle divergent history
-            // Never force push to default branch (direct mode) - could overwrite others' work
             const pushBranch = isDirectMode ? baseBranch : branchName;
-            this.log.info(`Pushing to ${pushBranch}...`);
-            try {
-                await this.gitOps.push(pushBranch, { force: !isDirectMode });
+            if (dryRun) {
+                // In dry-run mode, just log what would happen
+                this.log.info("Staging changes...");
+                this.log.info(`Would commit: ${commitMessage}`);
+                this.log.info(`Would push to ${pushBranch}...`);
             }
-            catch (error) {
-                // Handle branch protection errors in direct mode
-                if (isDirectMode) {
-                    const errorMessage = error instanceof Error ? error.message : String(error);
-                    if (errorMessage.includes("rejected") ||
-                        errorMessage.includes("protected") ||
-                        errorMessage.includes("denied")) {
-                        return {
-                            success: false,
-                            repoName,
-                            message: `Push to '${baseBranch}' was rejected (likely branch protection). To use 'direct' mode, the target branch must allow direct pushes. Use 'merge: force' to create a PR and merge with admin privileges.`,
-                        };
+            else {
+                // Build file changes for commit strategy
+                const fileChanges = [];
+                for (const [path, content] of fileChangesForCommit.entries()) {
+                    fileChanges.push({ path, content });
+                }
+                // Check if there are actually staged changes (edge case handling)
+                // This handles scenarios where git status shows changes but git add doesn't stage anything
+                // (e.g., due to .gitattributes normalization)
+                this.log.info("Staging changes...");
+                await this.executor.exec("git add -A", workDir);
+                if (!(await this.gitOps.hasStagedChanges())) {
+                    this.log.info("No staged changes after git add -A, skipping commit");
+                    return {
+                        success: true,
+                        repoName,
+                        message: "No changes detected after staging",
+                        skipped: true,
+                        diffStats,
+                    };
+                }
+                // Use commit strategy (GitCommitStrategy or GraphQLCommitStrategy)
+                const commitStrategy = getCommitStrategy(repoInfo, this.executor);
+                this.log.info("Committing and pushing changes...");
+                try {
+                    const commitResult = await commitStrategy.commit({
+                        repoInfo,
+                        branchName: pushBranch,
+                        message: commitMessage,
+                        fileChanges,
+                        workDir,
+                        retries: this.retries,
+                        // Use force push (--force-with-lease) for PR branches, not for direct mode
+                        force: !isDirectMode,
+                    });
+                    this.log.info(`Committed: ${commitResult.sha} (verified: ${commitResult.verified})`);
+                }
+                catch (error) {
+                    // Handle branch protection errors in direct mode
+                    if (isDirectMode) {
+                        const errorMessage = error instanceof Error ? error.message : String(error);
+                        if (errorMessage.includes("rejected") ||
+                            errorMessage.includes("protected") ||
+                            errorMessage.includes("denied")) {
+                            return {
+                                success: false,
+                                repoName,
+                                message: `Push to '${baseBranch}' was rejected (likely branch protection). To use 'direct' mode, the target branch must allow direct pushes. Use 'merge: force' to create a PR and merge with admin privileges.`,
+                            };
+                        }
                     }
+                    throw error;
                 }
-                throw error;
             }
             // Direct mode: no PR creation, return success
             if (isDirectMode) {
@@ -348,9 +387,9 @@ export class RepositoryProcessor {
                 files: changedFiles,
                 workDir,
                 dryRun,
-                retries,
+                retries: this.retries,
                 prTemplate,
-                executor,
+                executor: this.executor,
             });
             // Step 10: Handle merge options if configured
             let mergeResult;
@@ -368,8 +407,8 @@ export class RepositoryProcessor {
                     mergeConfig,
                     workDir,
                     dryRun,
-                    retries,
-                    executor,
+                    retries: this.retries,
+                    executor: this.executor,
                 });
                 mergeResult = {
                     merged: result.merged ?? false,

package/dist/strategies/commit-strategy-selector.d.ts

@@ -0,0 +1,16 @@
+import { RepoInfo } from "../repo-detector.js";
+import { CommitStrategy } from "./commit-strategy.js";
+import { CommandExecutor } from "../command-executor.js";
+/**
+ * Factory function to get the appropriate commit strategy for a repository.
+ *
+ * For GitHub repositories with GH_INSTALLATION_TOKEN set, returns GraphQLCommitStrategy
+ * which creates verified commits via the GitHub GraphQL API.
+ *
+ * For all other cases (GitHub with PAT, Azure DevOps, GitLab), returns GitCommitStrategy
+ * which uses standard git commands.
+ *
+ * @param repoInfo - Repository information
+ * @param executor - Optional command executor for shell commands
+ */
+export declare function getCommitStrategy(repoInfo: RepoInfo, executor?: CommandExecutor): CommitStrategy;

package/dist/strategies/commit-strategy-selector.js

@@ -0,0 +1,21 @@
+import { isGitHubRepo } from "../repo-detector.js";
+import { GitCommitStrategy } from "./git-commit-strategy.js";
+import { GraphQLCommitStrategy } from "./graphql-commit-strategy.js";
+/**
+ * Factory function to get the appropriate commit strategy for a repository.
+ *
+ * For GitHub repositories with GH_INSTALLATION_TOKEN set, returns GraphQLCommitStrategy
+ * which creates verified commits via the GitHub GraphQL API.
+ *
+ * For all other cases (GitHub with PAT, Azure DevOps, GitLab), returns GitCommitStrategy
+ * which uses standard git commands.
+ *
+ * @param repoInfo - Repository information
+ * @param executor - Optional command executor for shell commands
+ */
+export function getCommitStrategy(repoInfo, executor) {
+    if (isGitHubRepo(repoInfo) && process.env.GH_INSTALLATION_TOKEN) {
+        return new GraphQLCommitStrategy(executor);
+    }
+    return new GitCommitStrategy(executor);
+}

package/dist/strategies/commit-strategy.d.ts

@@ -0,0 +1,31 @@
+import { RepoInfo } from "../repo-detector.js";
+export interface FileChange {
+    path: string;
+    content: string | null;
+}
+export interface CommitOptions {
+    repoInfo: RepoInfo;
+    branchName: string;
+    message: string;
+    fileChanges: FileChange[];
+    workDir: string;
+    retries?: number;
+    /** Use force push (--force-with-lease). Default: true for PR branches, false for direct push to main. */
+    force?: boolean;
+}
+export interface CommitResult {
+    sha: string;
+    verified: boolean;
+    pushed: boolean;
+}
+/**
+ * Strategy interface for creating commits.
+ * Implementations handle platform-specific commit mechanisms.
+ */
+export interface CommitStrategy {
+    /**
+     * Create a commit with the given file changes and push to remote.
+     * @returns Commit result with SHA and verification status
+     */
+    commit(options: CommitOptions): Promise<CommitResult>;
+}

package/dist/strategies/commit-strategy.js

@@ -0,0 +1 @@
+export {};

package/dist/strategies/git-commit-strategy.d.ts

@@ -0,0 +1,18 @@
+import { CommitStrategy, CommitOptions, CommitResult } from "./commit-strategy.js";
+import { CommandExecutor } from "../command-executor.js";
+/**
+ * Git-based commit strategy using standard git commands (add, commit, push).
+ * Used with PAT authentication. Commits via this strategy are NOT verified
+ * by GitHub (no signature).
+ */
+export declare class GitCommitStrategy implements CommitStrategy {
+    private executor;
+    constructor(executor?: CommandExecutor);
+    /**
+     * Create a commit with the given file changes and push to remote.
+     * Runs: git add -A, git commit, git push (with optional --force-with-lease)
+     *
+     * @returns Commit result with SHA and verified: false (no signature)
+     */
+    commit(options: CommitOptions): Promise<CommitResult>;
+}

package/dist/strategies/git-commit-strategy.js

@@ -0,0 +1,41 @@
+import { defaultExecutor } from "../command-executor.js";
+import { withRetry } from "../retry-utils.js";
+import { escapeShellArg } from "../shell-utils.js";
+/**
+ * Git-based commit strategy using standard git commands (add, commit, push).
+ * Used with PAT authentication. Commits via this strategy are NOT verified
+ * by GitHub (no signature).
+ */
+export class GitCommitStrategy {
+    executor;
+    constructor(executor) {
+        this.executor = executor ?? defaultExecutor;
+    }
+    /**
+     * Create a commit with the given file changes and push to remote.
+     * Runs: git add -A, git commit, git push (with optional --force-with-lease)
+     *
+     * @returns Commit result with SHA and verified: false (no signature)
+     */
+    async commit(options) {
+        const { branchName, message, workDir, retries = 3, force = true } = options;
+        // Stage all changes
+        await this.executor.exec("git add -A", workDir);
+        // Commit with the message (--no-verify to skip pre-commit hooks)
+        await this.executor.exec(`git commit --no-verify -m ${escapeShellArg(message)}`, workDir);
+        // Build push command - use --force-with-lease for PR branches, regular push for direct mode
+        const forceFlag = force ? "--force-with-lease " : "";
+        const pushCommand = `git push ${forceFlag}-u origin ${escapeShellArg(branchName)}`;
+        // Push with retry for transient network failures
+        await withRetry(() => this.executor.exec(pushCommand, workDir), {
+            retries,
+        });
+        // Get the commit SHA
+        const sha = await this.executor.exec("git rev-parse HEAD", workDir);
+        return {
+            sha: sha.trim(),
+            verified: false, // Git-based commits are not verified
+            pushed: true,
+        };
+    }
+}

package/dist/strategies/graphql-commit-strategy.d.ts

@@ -0,0 +1,58 @@
+import { CommitStrategy, CommitOptions, CommitResult } from "./commit-strategy.js";
+import { CommandExecutor } from "../command-executor.js";
+/**
+ * Maximum payload size for GitHub GraphQL API (50MB).
+ * Base64 encoding adds ~33% overhead, so raw content should be checked.
+ */
+export declare const MAX_PAYLOAD_SIZE: number;
+/**
+ * Pattern for valid git branch names that are also safe for shell commands.
+ * Git branch names have strict rules:
+ * - Cannot contain: space, ~, ^, :, ?, *, [, \, .., @{
+ * - Cannot start with: - or .
+ * - Cannot end with: / or .lock
+ * - Cannot contain consecutive slashes
+ *
+ * This pattern allows only alphanumeric chars, hyphens, underscores, dots, and slashes
+ * which covers all practical branch names and is shell-safe.
+ */
+export declare const SAFE_BRANCH_NAME_PATTERN: RegExp;
+/**
+ * Validates that a branch name is safe for use in shell commands.
+ * Throws an error if the branch name contains potentially dangerous characters.
+ */
+export declare function validateBranchName(branchName: string): void;
+/**
+ * GraphQL-based commit strategy using GitHub's createCommitOnBranch mutation.
+ * Used with GitHub App authentication. Commits via this strategy ARE verified
+ * by GitHub (signed by the GitHub App).
+ *
+ * This strategy is GitHub-only and requires the `gh` CLI to be authenticated.
+ */
+export declare class GraphQLCommitStrategy implements CommitStrategy {
+    private executor;
+    constructor(executor?: CommandExecutor);
+    /**
+     * Create a commit with the given file changes using GitHub's GraphQL API.
+     * Uses the createCommitOnBranch mutation for verified commits.
+     *
+     * @returns Commit result with SHA and verified: true
+     * @throws Error if repo is not GitHub, payload exceeds 50MB, or API fails
+     */
+    commit(options: CommitOptions): Promise<CommitResult>;
+    /**
+     * Execute the createCommitOnBranch GraphQL mutation.
+     */
+    private executeGraphQLMutation;
+    /**
+     * Ensure the branch exists on the remote.
+     * createCommitOnBranch requires the branch to already exist.
+     * If the branch doesn't exist, push it to create it.
+     */
+    private ensureBranchExistsOnRemote;
+    /**
+     * Check if an error is due to expectedHeadOid mismatch (optimistic locking failure).
+     * This happens when the branch was updated between getting HEAD and making the commit.
+     */
+    private isHeadOidMismatchError;
+}

package/dist/strategies/graphql-commit-strategy.js

@@ -0,0 +1,199 @@
+import { defaultExecutor } from "../command-executor.js";
+import { isGitHubRepo } from "../repo-detector.js";
+import { escapeShellArg } from "../shell-utils.js";
+/**
+ * Maximum payload size for GitHub GraphQL API (50MB).
+ * Base64 encoding adds ~33% overhead, so raw content should be checked.
+ */
+export const MAX_PAYLOAD_SIZE = 50 * 1024 * 1024;
+/**
+ * Pattern for valid git branch names that are also safe for shell commands.
+ * Git branch names have strict rules:
+ * - Cannot contain: space, ~, ^, :, ?, *, [, \, .., @{
+ * - Cannot start with: - or .
+ * - Cannot end with: / or .lock
+ * - Cannot contain consecutive slashes
+ *
+ * This pattern allows only alphanumeric chars, hyphens, underscores, dots, and slashes
+ * which covers all practical branch names and is shell-safe.
+ */
+export const SAFE_BRANCH_NAME_PATTERN = /^[a-zA-Z0-9][-a-zA-Z0-9_./]*$/;
+/**
+ * Validates that a branch name is safe for use in shell commands.
+ * Throws an error if the branch name contains potentially dangerous characters.
+ */
+export function validateBranchName(branchName) {
+    if (!SAFE_BRANCH_NAME_PATTERN.test(branchName)) {
+        throw new Error(`Invalid branch name for GraphQL commit strategy: "${branchName}". ` +
+            `Branch names must start with alphanumeric and contain only ` +
+            `alphanumeric characters, hyphens, underscores, dots, and forward slashes.`);
+    }
+}
+/**
+ * GraphQL-based commit strategy using GitHub's createCommitOnBranch mutation.
+ * Used with GitHub App authentication. Commits via this strategy ARE verified
+ * by GitHub (signed by the GitHub App).
+ *
+ * This strategy is GitHub-only and requires the `gh` CLI to be authenticated.
+ */
+export class GraphQLCommitStrategy {
+    executor;
+    constructor(executor) {
+        this.executor = executor ?? defaultExecutor;
+    }
+    /**
+     * Create a commit with the given file changes using GitHub's GraphQL API.
+     * Uses the createCommitOnBranch mutation for verified commits.
+     *
+     * @returns Commit result with SHA and verified: true
+     * @throws Error if repo is not GitHub, payload exceeds 50MB, or API fails
+     */
+    async commit(options) {
+        const { repoInfo, branchName, message, fileChanges, workDir, retries = 3, } = options;
+        // Validate this is a GitHub repo
+        if (!isGitHubRepo(repoInfo)) {
+            throw new Error(`GraphQL commit strategy requires GitHub repositories. Got: ${repoInfo.type}`);
+        }
+        // Validate branch name is safe for shell commands
+        validateBranchName(branchName);
+        const githubInfo = repoInfo;
+        // Separate additions from deletions
+        const additions = fileChanges.filter((fc) => fc.content !== null);
+        const deletions = fileChanges.filter((fc) => fc.content === null);
+        // Calculate payload size (base64 adds ~33% overhead)
+        const totalSize = additions.reduce((sum, fc) => {
+            const base64Size = Math.ceil((fc.content.length * 4) / 3);
+            return sum + base64Size;
+        }, 0);
+        if (totalSize > MAX_PAYLOAD_SIZE) {
+            throw new Error(`GraphQL payload exceeds 50 MB limit (${Math.round(totalSize / (1024 * 1024))} MB). ` +
+                `Consider using smaller files or the git commit strategy.`);
+        }
+        // Ensure the branch exists on remote before making GraphQL commit
+        // createCommitOnBranch requires the branch to already exist
+        await this.ensureBranchExistsOnRemote(branchName, workDir);
+        // Retry loop for expectedHeadOid mismatch
+        let lastError = null;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                // Fetch from remote to ensure we have the latest HEAD
+                // This is critical for expectedHeadOid to match
+                // Branch name was validated above, safe for shell use
+                await this.executor.exec(`git fetch origin ${branchName}:refs/remotes/origin/${branchName}`, workDir);
+                // Get the remote HEAD SHA for this branch (not local HEAD)
+                const headSha = await this.executor.exec(`git rev-parse origin/${branchName}`, workDir);
+                // Build and execute the GraphQL mutation
+                const result = await this.executeGraphQLMutation(githubInfo, branchName, message, headSha.trim(), additions, deletions, workDir);
+                return result;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Check if this is an expectedHeadOid mismatch error (retryable)
+                if (this.isHeadOidMismatchError(lastError) && attempt < retries) {
+                    // Retry - the next iteration will fetch and get fresh HEAD SHA
+                    continue;
+                }
+                // For other errors, throw immediately
+                throw lastError;
+            }
+        }
+        // Should not reach here, but just in case
+        throw lastError ?? new Error("Unexpected error in GraphQL commit");
+    }
+    /**
+     * Execute the createCommitOnBranch GraphQL mutation.
+     */
+    async executeGraphQLMutation(repoInfo, branchName, message, expectedHeadOid, additions, deletions, workDir) {
+        const repositoryNameWithOwner = `${repoInfo.owner}/${repoInfo.repo}`;
+        // Build file additions with base64 encoding
+        const fileAdditions = additions.map((fc) => ({
+            path: fc.path,
+            contents: Buffer.from(fc.content).toString("base64"),
+        }));
+        // Build file deletions (path only)
+        const fileDeletions = deletions.map((fc) => ({
+            path: fc.path,
+        }));
+        // Build the mutation (minified to avoid shell escaping issues with newlines)
+        const mutation = "mutation CreateCommit($input: CreateCommitOnBranchInput!) { createCommitOnBranch(input: $input) { commit { oid } } }";
+        // Build the input variables
+        // Note: GitHub API doesn't accept empty arrays, so only include fields when non-empty
+        const fileChanges = {};
+        if (fileAdditions.length > 0) {
+            fileChanges.additions = fileAdditions;
+        }
+        if (fileDeletions.length > 0) {
+            fileChanges.deletions = fileDeletions;
+        }
+        const variables = {
+            input: {
+                branch: {
+                    repositoryNameWithOwner,
+                    branchName,
+                },
+                expectedHeadOid,
+                message: {
+                    headline: message,
+                },
+                fileChanges,
+            },
+        };
+        // Build the GraphQL request body
+        const requestBody = JSON.stringify({
+            query: mutation,
+            variables,
+        });
+        // Build the gh api graphql command
+        // Use --input - to pass the JSON body via stdin (more reliable for complex nested JSON)
+        // Use --hostname for GitHub Enterprise
+        const hostnameArg = repoInfo.host !== "github.com"
+            ? `--hostname ${escapeShellArg(repoInfo.host)}`
+            : "";
+        const command = `echo ${escapeShellArg(requestBody)} | gh api graphql ${hostnameArg} --input -`;
+        const response = await this.executor.exec(command, workDir);
+        // Parse the response
+        const parsed = JSON.parse(response);
+        if (parsed.errors) {
+            throw new Error(`GraphQL error: ${parsed.errors.map((e) => e.message).join(", ")}`);
+        }
+        const oid = parsed.data?.createCommitOnBranch?.commit?.oid;
+        if (!oid) {
+            throw new Error("GraphQL response missing commit OID");
+        }
+        return {
+            sha: oid,
+            verified: true, // GraphQL commits via GitHub App are verified
+            pushed: true, // GraphQL commits are pushed directly
+        };
+    }
+    /**
+     * Ensure the branch exists on the remote.
+     * createCommitOnBranch requires the branch to already exist.
+     * If the branch doesn't exist, push it to create it.
+     */
+    async ensureBranchExistsOnRemote(branchName, workDir) {
+        // Branch name was validated in commit(), safe for shell use
+        try {
+            // Check if the branch exists on remote
+            await this.executor.exec(`git ls-remote --exit-code --heads origin ${branchName}`, workDir);
+            // Branch exists, nothing to do
+        }
+        catch {
+            // Branch doesn't exist on remote, push it
+            // This pushes the current local branch to create it on remote
+            await this.executor.exec(`git push -u origin HEAD:${branchName}`, workDir);
+        }
+    }
+    /**
+     * Check if an error is due to expectedHeadOid mismatch (optimistic locking failure).
+     * This happens when the branch was updated between getting HEAD and making the commit.
+     */
+    isHeadOidMismatchError(error) {
+        const message = error.message.toLowerCase();
+        return (message.includes("expected branch to point to") ||
+            message.includes("expectedheadoid") ||
+            message.includes("head oid") ||
+            // GitHub may return this generic error for OID mismatches
+            message.includes("was provided invalid value"));
+    }
+}

package/dist/strategies/index.d.ts

@@ -6,6 +6,10 @@ export { BasePRStrategy, PRWorkflowExecutor } from "./pr-strategy.js";
 export { GitHubPRStrategy } from "./github-pr-strategy.js";
 export { AzurePRStrategy } from "./azure-pr-strategy.js";
 export { GitLabPRStrategy } from "./gitlab-pr-strategy.js";
+export type { CommitStrategy, CommitOptions, CommitResult, FileChange, } from "./commit-strategy.js";
+export { GitCommitStrategy } from "./git-commit-strategy.js";
+export { GraphQLCommitStrategy, MAX_PAYLOAD_SIZE, } from "./graphql-commit-strategy.js";
+export { getCommitStrategy } from "./commit-strategy-selector.js";
 /**
  * Factory function to get the appropriate PR strategy for a repository.
  * @param repoInfo - Repository information

package/dist/strategies/index.js

@@ -6,6 +6,9 @@ export { BasePRStrategy, PRWorkflowExecutor } from "./pr-strategy.js";
 export { GitHubPRStrategy } from "./github-pr-strategy.js";
 export { AzurePRStrategy } from "./azure-pr-strategy.js";
 export { GitLabPRStrategy } from "./gitlab-pr-strategy.js";
+export { GitCommitStrategy } from "./git-commit-strategy.js";
+export { GraphQLCommitStrategy, MAX_PAYLOAD_SIZE, } from "./graphql-commit-strategy.js";
+export { getCommitStrategy } from "./commit-strategy-selector.js";
 /**
  * Factory function to get the appropriate PR strategy for a repository.
  * @param repoInfo - Repository information

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "CLI tool to sync JSON, JSON5, YAML, or text configuration files across multiple Git repositories via pull requests or direct push",
   "type": "module",
   "main": "dist/index.js",
@@ -31,6 +31,7 @@
     "test:integration:github": "npm run build && node --import tsx --test test/integration/github.test.ts",
     "test:integration:ado": "npm run build && node --import tsx --test test/integration/ado.test.ts",
     "test:integration:gitlab": "npm run build && node --import tsx --test test/integration/gitlab.test.ts",
+    "test:integration:github-app": "npm run build && node --import tsx --test test/integration/github-app.test.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [