@aspruyt/xfg 3.10.0 → 3.10.1

package/dist/shared/logger.d.ts

@@ -1,6 +1,7 @@
 import { FileStatus } from "../sync/diff-utils.js";
 export interface ILogger {
     info(message: string): void;
+    warn(message: string): void;
     debug(message: string): void;
     fileDiff(fileName: string, status: FileStatus, diffLines: string[]): void;
     diffSummary(newCount: number, modifiedCount: number, unchangedCount: number, deletedCount?: number): void;
@@ -21,6 +22,7 @@ export declare class Logger implements ILogger {
     setTotal(total: number): void;
     progress(current: number, repoName: string, message: string): void;
     info(message: string): void;
+    warn(message: string): void;
     debug(message: string): void;
     success(current: number, repoName: string, message: string): void;
     skip(current: number, repoName: string, reason: string): void;

package/dist/shared/logger.js

@@ -17,6 +17,9 @@ export class Logger {
     info(message) {
         console.log(chalk.gray(`    ${message}`));
     }
+    warn(message) {
+        console.log(chalk.yellow(`    ⚠ ${message}`));
+    }
     debug(message) {
         if (process.env.DEBUG || process.env.XFG_DEBUG) {
             console.log(chalk.dim(`    [debug] ${message}`));

package/dist/shared/retry-utils.js

@@ -8,6 +8,7 @@ import { sanitizeCredentials } from "./sanitize-utils.js";
  */
 export const DEFAULT_PERMANENT_ERROR_PATTERNS = [
     /permission\s*denied/i,
+    /not\s*accessible\s*by\s*integration/i,
     /authentication\s*failed/i,
     /bad\s*credentials/i,
     /invalid\s*(token|credentials)/i,

package/dist/sync/file-writer.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { convertContentToString } from "../config/formatter.js";
 import { interpolateXfgContent } from "./xfg-template.js";
 import { getFileStatus, generateDiff, createDiffStats, incrementDiffStats, } from "./diff-utils.js";
+import { hasGitHubAppCredentials } from "../vcs/commit-strategy-selector.js";
 /**
  * Determines if a file should be marked as executable.
  * .sh files are auto-executable unless explicit executable: false is set.
@@ -92,6 +93,11 @@ export class FileWriter {
                 continue;
             }
             if (shouldBeExecutable(file)) {
+                if (tracked?.action === "create" && hasGitHubAppCredentials()) {
+                    log.warn(`${file.fileName}: GitHub App commits cannot set executable mode on new files. ` +
+                        `The file will be created as non-executable (100644). ` +
+                        `See: https://anthony-spruyt.github.io/xfg/examples/executable-files/`);
+                }
                 log.info(`Setting executable: ${file.fileName}`);
                 await gitOps.setExecutable(file.fileName);
             }

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

@@ -30,6 +30,13 @@ export declare function validateBranchName(branchName: string): void;
  * This strategy is GitHub-only and requires the `gh` CLI to be authenticated.
  */
 export declare class GraphQLCommitStrategy implements ICommitStrategy {
+    /**
+     * GraphQL permanent error patterns for ref operations.
+     * Differs from DEFAULT_PERMANENT_ERROR_PATTERNS which has
+     * git-CLI-specific patterns (/remote\s*rejected/i) that don't
+     * apply to GraphQL responses.
+     */
+    private static readonly GRAPHQL_PERMANENT_ERROR_PATTERNS;
     private executor;
     constructor(executor?: ICommandExecutor);
     /**
@@ -48,6 +55,9 @@ export declare class GraphQLCommitStrategy implements ICommitStrategy {
      * Ensure the branch exists on the remote and matches local HEAD.
      * createCommitOnBranch requires the branch to already exist.
      *
+     * Uses GraphQL ref mutations instead of git push to support repos
+     * with required_signatures on all branches.
+     *
      * For PR branches (force=true): delete existing remote branch and recreate
      * from local HEAD to ensure a fresh start from main.
      *
@@ -66,4 +76,23 @@ export declare class GraphQLCommitStrategy implements ICommitStrategy {
      * This happens when the branch was updated between getting HEAD and making the commit.
      */
     private isHeadOidMismatchError;
+    /**
+     * Execute a GraphQL query or mutation for ref operations.
+     * Handles command construction, retry, error sanitization, and response parsing.
+     * Uses gh CLI's --input flag to pass GraphQL via stdin (same pattern as executeGraphQLMutation).
+     */
+    private executeGraphQLRefOp;
+    /**
+     * Query the remote for a repository's Node ID and a ref's Node ID.
+     * Returns repositoryId (always) and refId (null if branch doesn't exist).
+     */
+    private queryRemoteRef;
+    /**
+     * Create a branch ref on the remote via GraphQL createRef mutation.
+     */
+    private createRemoteRef;
+    /**
+     * Delete a branch ref on the remote via GraphQL deleteRef mutation.
+     */
+    private deleteRemoteRef;
 }

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

@@ -48,6 +48,24 @@ const OID_MISMATCH_PATTERNS = [
  * This strategy is GitHub-only and requires the `gh` CLI to be authenticated.
  */
 export class GraphQLCommitStrategy {
+    /**
+     * GraphQL permanent error patterns for ref operations.
+     * Differs from DEFAULT_PERMANENT_ERROR_PATTERNS which has
+     * git-CLI-specific patterns (/remote\s*rejected/i) that don't
+     * apply to GraphQL responses.
+     */
+    static GRAPHQL_PERMANENT_ERROR_PATTERNS = [
+        /not\s*found/i,
+        /unauthorized/i,
+        /permission\s*denied/i,
+        /not\s*accessible\s*by\s*integration/i,
+        /bad\s*credentials/i,
+        /invalid\s*(token|credentials)/i,
+        /401\b/,
+        /403\b/,
+        /does\s*not\s*exist/i,
+        /could\s*not\s*resolve/i,
+    ];
     executor;
     constructor(executor) {
         this.executor = executor ?? defaultExecutor;
@@ -85,7 +103,7 @@ export class GraphQLCommitStrategy {
         // Ensure the branch exists on remote and is up-to-date with local HEAD
         // createCommitOnBranch requires the branch to already exist
         // For PR branches (force=true), we force-update to ensure fresh start from main
-        await this.ensureBranchExistsOnRemote(branchName, workDir, options.force, gitOps);
+        await this.ensureBranchExistsOnRemote(branchName, workDir, options.force, githubInfo, token);
         // Retry loop for expectedHeadOid mismatch
         let lastError = null;
         for (let attempt = 0; attempt <= retries; attempt++) {
@@ -204,47 +222,31 @@ export class GraphQLCommitStrategy {
      * Ensure the branch exists on the remote and matches local HEAD.
      * createCommitOnBranch requires the branch to already exist.
      *
+     * Uses GraphQL ref mutations instead of git push to support repos
+     * with required_signatures on all branches.
+     *
      * For PR branches (force=true): delete existing remote branch and recreate
      * from local HEAD to ensure a fresh start from main.
      *
      * For direct mode (force=false): just ensure branch exists.
      */
-    async ensureBranchExistsOnRemote(branchName, workDir, force, gitOps) {
-        // Branch name was validated in commit(), safe for shell use
-        try {
-            // Check if the branch exists on remote
-            // Use skipRetry because failure is expected for new branches
-            if (gitOps) {
-                await gitOps.lsRemote(branchName, { skipRetry: true });
-            }
-            else {
-                await this.executor.exec(`git ls-remote --exit-code --heads origin ${escapeShellArg(branchName)}`, workDir);
-            }
-            // Branch exists - for PR branches, delete and recreate to ensure fresh from main
-            if (force) {
-                if (gitOps) {
-                    await gitOps.pushRefspec(branchName, { delete: true });
-                    // Now push fresh branch from local HEAD
-                    await gitOps.pushRefspec(`HEAD:${branchName}`);
-                }
-                else {
-                    await this.executor.exec(`git push origin --delete ${escapeShellArg(branchName)}`, workDir);
-                    // Now push fresh branch from local HEAD
-                    await this.executor.exec(`git push -u origin HEAD:${escapeShellArg(branchName)}`, workDir);
-                }
-            }
-            // For direct mode (force=false), leave existing branch as-is
+    async ensureBranchExistsOnRemote(branchName, workDir, force, repoInfo, token) {
+        if (!repoInfo) {
+            throw new Error("repoInfo is required for GraphQL ref operations");
         }
-        catch {
-            // Branch doesn't exist on remote, push it
-            // This pushes the current local branch to create it on remote
-            if (gitOps) {
-                await gitOps.pushRefspec(`HEAD:${branchName}`);
-            }
-            else {
-                await this.executor.exec(`git push -u origin HEAD:${escapeShellArg(branchName)}`, workDir);
-            }
+        const { repositoryId, refId } = await this.queryRemoteRef(repoInfo, branchName, workDir, token);
+        if (refId && force) {
+            // Branch exists + force: delete then recreate from local HEAD
+            await this.deleteRemoteRef(refId, workDir, repoInfo, token);
+            const sha = (await this.executor.exec("git rev-parse HEAD", workDir)).trim();
+            await this.createRemoteRef(repositoryId, branchName, sha, workDir, repoInfo, token);
+        }
+        else if (!refId) {
+            // Branch doesn't exist: create from local HEAD
+            const sha = (await this.executor.exec("git rev-parse HEAD", workDir)).trim();
+            await this.createRemoteRef(repositoryId, branchName, sha, workDir, repoInfo, token);
         }
+        // refId exists + !force: no-op (branch already exists)
     }
     /**
      * Sanitize command execution errors to remove the GraphQL payload.
@@ -284,4 +286,59 @@ export class GraphQLCommitStrategy {
             // GitHub may return this generic error for OID mismatches
             message.includes("was provided invalid value"));
     }
+    /**
+     * Execute a GraphQL query or mutation for ref operations.
+     * Handles command construction, retry, error sanitization, and response parsing.
+     * Uses gh CLI's --input flag to pass GraphQL via stdin (same pattern as executeGraphQLMutation).
+     */
+    async executeGraphQLRefOp(queryOrMutation, repoInfo, workDir, token) {
+        const requestBody = JSON.stringify({ query: queryOrMutation });
+        const hostnameArg = repoInfo.host !== "github.com"
+            ? `--hostname ${escapeShellArg(repoInfo.host)}`
+            : "";
+        const tokenPrefix = token ? `GH_TOKEN=${token} ` : "";
+        const command = `echo ${escapeShellArg(requestBody)} | ${tokenPrefix}gh api graphql ${hostnameArg} --input -`;
+        let response;
+        try {
+            response = await withRetry(() => this.executor.exec(command, workDir), {
+                permanentErrorPatterns: GraphQLCommitStrategy.GRAPHQL_PERMANENT_ERROR_PATTERNS,
+            });
+        }
+        catch (error) {
+            throw this.sanitizeCommandError(error, `${repoInfo.owner}/${repoInfo.repo}`);
+        }
+        const parsed = JSON.parse(response);
+        if (parsed.errors) {
+            throw new Error(`GraphQL error: ${parsed.errors.map((e) => e.message).join(", ")}`);
+        }
+        return parsed;
+    }
+    /**
+     * Query the remote for a repository's Node ID and a ref's Node ID.
+     * Returns repositoryId (always) and refId (null if branch doesn't exist).
+     */
+    async queryRemoteRef(repoInfo, branchName, workDir, token) {
+        const query = `{ repository(owner: ${JSON.stringify(repoInfo.owner)}, name: ${JSON.stringify(repoInfo.repo)}) { id ref(qualifiedName: ${JSON.stringify(`refs/heads/${branchName}`)}) { id } } }`;
+        const parsed = await this.executeGraphQLRefOp(query, repoInfo, workDir, token);
+        const repo = parsed.data?.repository;
+        const repositoryId = repo?.id;
+        if (!repositoryId) {
+            throw new Error(`GraphQL response missing repository ID for ${repoInfo.owner}/${repoInfo.repo}`);
+        }
+        return { repositoryId, refId: repo?.ref?.id ?? null };
+    }
+    /**
+     * Create a branch ref on the remote via GraphQL createRef mutation.
+     */
+    async createRemoteRef(repositoryId, branchName, oid, workDir, repoInfo, token) {
+        const mutation = `mutation { createRef(input: { repositoryId: ${JSON.stringify(repositoryId)}, name: ${JSON.stringify(`refs/heads/${branchName}`)}, oid: ${JSON.stringify(oid)} }) { clientMutationId } }`;
+        await this.executeGraphQLRefOp(mutation, repoInfo, workDir, token);
+    }
+    /**
+     * Delete a branch ref on the remote via GraphQL deleteRef mutation.
+     */
+    async deleteRemoteRef(refId, workDir, repoInfo, token) {
+        const mutation = `mutation { deleteRef(input: { refId: ${JSON.stringify(refId)} }) { clientMutationId } }`;
+        await this.executeGraphQLRefOp(mutation, repoInfo, workDir, token);
+    }
 }

package/dist/vcs/types.d.ts

@@ -96,7 +96,7 @@ export interface CommitOptions {
     force?: boolean;
     /** GitHub App installation token for authentication (used by GraphQLCommitStrategy) */
     token?: string;
-    /** Authenticated git operations wrapper (used by GraphQLCommitStrategy for network ops) */
+    /** Authenticated git operations wrapper (used by GraphQLCommitStrategy for fetchBranch() during OID mismatch retries) */
     gitOps?: IAuthenticatedGitOps;
 }
 export interface CommitResult {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "3.10.0",
+  "version": "3.10.1",
   "description": "Manage files, settings, and repositories across GitHub, Azure DevOps, and GitLab — declaratively, from a single YAML config",
   "type": "module",
   "main": "dist/index.js",