@aspruyt/xfg 5.6.0 → 6.0.0

package/dist/cli/sync-command.js

@@ -420,9 +420,9 @@ export async function runSync(options, deps = {}) {
     getLogger().log(`Found ${config.repos.length} repositories to process`);
     getLogger().log(`Target files: ${formatFileNames(fileNames)}`);
     getLogger().log(`Branch: ${branchName}\n`);
-    const tokenManager = createTokenManager(process.env.XFG_GITHUB_APP_ID && process.env.XFG_GITHUB_APP_PRIVATE_KEY
+    const tokenManager = createTokenManager(process.env.XFG_GITHUB_CLIENT_ID && process.env.XFG_GITHUB_APP_PRIVATE_KEY
         ? {
-            appId: process.env.XFG_GITHUB_APP_ID,
+            clientId: process.env.XFG_GITHUB_CLIENT_ID,
             privateKey: process.env.XFG_GITHUB_APP_PRIVATE_KEY,
         }
         : undefined);

package/dist/lifecycle/github-lifecycle-provider.js

@@ -316,6 +316,7 @@ export class GitHubLifecycleProvider {
         const command = parts.join(" ");
         await withRetry(() => this.executor.exec(command, this.cwd, { env: tokenEnv }), {
             retries: this.retries,
+            permanentErrorPatterns: POST_CREATE_PERMANENT_PATTERNS,
         });
     }
     /**

package/dist/settings/repo-settings/github-repo-settings-strategy.d.ts

@@ -15,6 +15,7 @@ export declare class GitHubRepoSettingsStrategy implements IRepoSettingsStrategy
     setVulnerabilityAlerts(repoInfo: RepoInfo, enable: boolean, options?: GhApiOptions): Promise<void>;
     setAutomatedSecurityFixes(repoInfo: RepoInfo, enable: boolean, options?: GhApiOptions): Promise<void>;
     setPrivateVulnerabilityReporting(repoInfo: RepoInfo, enable: boolean, options?: GhApiOptions): Promise<void>;
+    branchExists(repoInfo: RepoInfo, branch: string, options?: GhApiOptions): Promise<boolean>;
     private getVulnerabilityAlerts;
     private getAutomatedSecurityFixes;
     private getPrivateVulnerabilityReporting;

package/dist/settings/repo-settings/github-repo-settings-strategy.js

@@ -104,6 +104,20 @@ export class GitHubRepoSettingsStrategy {
         const method = enable ? "PUT" : "DELETE";
         await this.api.call(method, endpoint, { options });
     }
+    async branchExists(repoInfo, branch, options) {
+        assertGitHubRepo(repoInfo, "GitHub Repo Settings strategy");
+        const endpoint = `/repos/${repoInfo.owner}/${repoInfo.repo}/branches/${encodeURIComponent(branch)}`;
+        try {
+            await this.api.call("GET", endpoint, { options });
+            return true;
+        }
+        catch (error) {
+            if (isHttp404Error(error)) {
+                return false;
+            }
+            throw error;
+        }
+    }
     async getVulnerabilityAlerts(github, options) {
         const endpoint = `/repos/${github.owner}/${github.repo}/vulnerability-alerts`;
         try {

package/dist/settings/repo-settings/processor.js

@@ -47,6 +47,22 @@ export class RepoSettingsProcessor {
                 changes: { create: 0, update: 0, delete: 0, unchanged: unchangedCount },
             };
         }
+        // Validate defaultBranch target exists before attempting to apply
+        const defaultBranchChange = changes.find((c) => c.property === "defaultBranch" && c.action !== "unchanged");
+        if (defaultBranchChange) {
+            const targetBranch = String(defaultBranchChange.newValue);
+            const exists = await this.strategy.branchExists(githubRepo, targetBranch, strategyOptions);
+            if (!exists) {
+                const currentBranch = defaultBranchChange.oldValue
+                    ? String(defaultBranchChange.oldValue)
+                    : "unknown";
+                return {
+                    success: false,
+                    repoName,
+                    message: `Failed: Cannot set default branch to '${targetBranch}': branch '${targetBranch}' does not exist (current: '${currentBranch}'). Create or rename the branch first.`,
+                };
+            }
+        }
         // Format plan output
         const planOutput = formatRepoSettingsPlan(changes);
         const changeCounts = {

package/dist/settings/repo-settings/types.d.ts

@@ -63,4 +63,8 @@ export interface IRepoSettingsStrategy {
      * Enables or disables private vulnerability reporting.
      */
     setPrivateVulnerabilityReporting(repoInfo: RepoInfo, enable: boolean, options?: GhApiOptions): Promise<void>;
+    /**
+     * Checks whether a branch exists in the repository.
+     */
+    branchExists(repoInfo: RepoInfo, branch: string, options?: GhApiOptions): Promise<boolean>;
 }

package/dist/shared/gh-api-utils.d.ts

@@ -36,6 +36,15 @@ export declare function parseResponseBody(raw: string): string;
  * No-op if stdout is absent or does not contain a numeric Retry-After header.
  */
 export declare function attachRetryAfter(error: unknown): void;
+/**
+ * Extracts GitHub API validation error details from `gh api --include` stdout
+ * and appends them to the error message. This surfaces the descriptive error
+ * messages that GitHub returns in 422 responses (e.g., "The branch main was
+ * not found") which are otherwise lost when only stderr is shown.
+ *
+ * No-op if stdout is absent or does not contain parseable error JSON.
+ */
+export declare function attachValidationDetails(error: unknown): void;
 /**
  * Encapsulates executor + retries for GitHub API calls.
  * Strategies compose with this instead of duplicating ghApi wrappers.

package/dist/shared/gh-api-utils.js

@@ -48,6 +48,42 @@ export function attachRetryAfter(error) {
         error.retryAfter = parseInt(match[1], 10);
     }
 }
+/**
+ * Extracts GitHub API validation error details from `gh api --include` stdout
+ * and appends them to the error message. This surfaces the descriptive error
+ * messages that GitHub returns in 422 responses (e.g., "The branch main was
+ * not found") which are otherwise lost when only stderr is shown.
+ *
+ * No-op if stdout is absent or does not contain parseable error JSON.
+ */
+export function attachValidationDetails(error) {
+    const stdout = error.stdout;
+    if (!stdout)
+        return;
+    const stdoutStr = typeof stdout === "string" ? stdout : stdout.toString();
+    const body = parseResponseBody(stdoutStr);
+    try {
+        const parsed = JSON.parse(body);
+        const details = [];
+        if (parsed.errors && parsed.errors.length > 0) {
+            for (const err of parsed.errors) {
+                if (err.message) {
+                    const fieldPrefix = err.field ? `${err.field}: ` : "";
+                    details.push(`${fieldPrefix}${err.message}`);
+                }
+            }
+        }
+        else if (parsed.message) {
+            details.push(parsed.message);
+        }
+        if (details.length > 0 && error instanceof Error) {
+            error.message += ` [${details.join("; ")}]`;
+        }
+    }
+    catch {
+        // JSON parse failed — stdout is not a JSON error response
+    }
+}
 /**
  * Executes a GitHub API call using the gh CLI.
  * Shared by labels, rulesets, and repo-settings strategies.
@@ -81,6 +117,7 @@ async function ghApiCall(method, endpoint, opts) {
         catch (error) {
             if (!paginate) {
                 attachRetryAfter(error);
+                attachValidationDetails(error);
             }
             throw error;
         }

package/dist/shared/retry-utils.js

@@ -15,6 +15,7 @@ export const CORE_PERMANENT_ERROR_PATTERNS = [
     /401\b/,
     /403\b/,
     /404\b/,
+    /422\b/,
     /not\s*found/i,
     /does\s*not\s*exist/i,
     /repository\s*not\s*found/i,

package/dist/sync/commit-push-manager.js

@@ -18,7 +18,11 @@ export class CommitPushManager {
         }
         const changes = Array.from(fileChanges.entries())
             .filter(([, info]) => info.action !== "skip")
-            .map(([path, info]) => ({ path, content: info.content }));
+            .map(([path, info]) => ({
+            path,
+            content: info.content,
+            ...(info.mode ? { mode: info.mode } : {}),
+        }));
         this.log.info("Staging changes...");
         await gitOps.stageAll();
         if (!(await gitOps.hasStagedChanges())) {

package/dist/sync/file-writer.js

@@ -69,6 +69,9 @@ export class FileWriter {
                     fileName: file.fileName,
                     content: fileContent,
                     action,
+                    // mode is only set on changed files — unchanged files won't trigger a
+                    // fixup commit, which is correct since their mode was set on a prior sync
+                    ...(shouldBeExecutable(file) ? { mode: "100755" } : {}),
                 };
                 // Compute raw diff lines for text files (all modes)
                 if (!isBinaryFile(file.fileName)) {
@@ -95,11 +98,6 @@ export class FileWriter {
                 continue;
             }
             if (shouldBeExecutable(file)) {
-                if (tracked?.action === "create" && ctx.hasAppCredentials) {
-                    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/sync/types.d.ts

@@ -11,6 +11,9 @@ export interface FileWriteResult {
     content: string | null;
     action: "create" | "update" | "delete" | "skip";
     diffLines?: string[];
+    /** Git file mode. Only set for executable files ("100755"). "100644" is included
+     *  in the union for type completeness — non-executable files omit this field. */
+    mode?: "100755" | "100644";
 }
 export interface FileWriteContext {
     repoInfo: RepoInfo;
@@ -19,7 +22,7 @@ export interface FileWriteContext {
     dryRun: boolean;
     noDelete: boolean;
     configId: string;
-    /** True when using GraphQL commit strategy (GitHub App) which cannot set file modes */
+    /** True when using GraphQL commit strategy (GitHub App) */
     hasAppCredentials?: boolean;
 }
 export interface FileWriterDeps {
@@ -129,7 +132,7 @@ export interface ProcessorOptions {
     noDelete?: boolean;
     /** GitHub token for authentication (resolved by caller) */
     token?: string;
-    /** True when using GraphQL commit strategy (GitHub App) which cannot set file modes */
+    /** True when using GraphQL commit strategy (GitHub App) */
     hasAppCredentials?: boolean;
 }
 export interface FileChangeDetail {

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

@@ -3,7 +3,7 @@ import type { ICommitStrategy } from "./types.js";
 import { GitHubAppTokenManager } from "./github-app-token-manager.js";
 import type { ICommandExecutor } from "../shared/command-executor.js";
 interface GitHubAppCredentials {
-    appId: string;
+    clientId: string;
     privateKey: string;
 }
 /**
@@ -11,8 +11,9 @@ interface GitHubAppCredentials {
  */
 export declare function createTokenManager(credentials?: GitHubAppCredentials): GitHubAppTokenManager | null;
 /**
- * Returns GraphQLCommitStrategy for GitHub repos with App credentials (verified commits),
- * or GitCommitStrategy for all other cases.
+ * Returns FileModeFixupCommitStrategy (decorating GraphQLCommitStrategy) for
+ * GitHub repos with App credentials (verified commits + executable file mode
+ * support), or GitCommitStrategy for all other cases.
  */
 export declare function createCommitStrategy(repoInfo: RepoInfo, executor: ICommandExecutor, hasAppCredentials?: boolean): ICommitStrategy;
 export {};

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

@@ -1,6 +1,7 @@
 import { isGitHubRepo } from "../shared/repo-detector.js";
 import { GitCommitStrategy } from "./git-commit-strategy.js";
 import { GraphQLCommitStrategy } from "./graphql-commit-strategy.js";
+import { FileModeFixupCommitStrategy } from "./file-mode-fixup-commit-strategy.js";
 import { GitHubAppTokenManager } from "./github-app-token-manager.js";
 /**
  * Creates a GitHubAppTokenManager from credentials, or null if not provided.
@@ -9,15 +10,17 @@ export function createTokenManager(credentials) {
     if (!credentials) {
         return null;
     }
-    return new GitHubAppTokenManager(credentials.appId, credentials.privateKey);
+    return new GitHubAppTokenManager(credentials.clientId, credentials.privateKey);
 }
 /**
- * Returns GraphQLCommitStrategy for GitHub repos with App credentials (verified commits),
- * or GitCommitStrategy for all other cases.
+ * Returns FileModeFixupCommitStrategy (decorating GraphQLCommitStrategy) for
+ * GitHub repos with App credentials (verified commits + executable file mode
+ * support), or GitCommitStrategy for all other cases.
  */
 export function createCommitStrategy(repoInfo, executor, hasAppCredentials) {
     if (isGitHubRepo(repoInfo) && hasAppCredentials) {
-        return new GraphQLCommitStrategy(executor);
+        const inner = new GraphQLCommitStrategy(executor);
+        return new FileModeFixupCommitStrategy(inner, executor);
     }
     return new GitCommitStrategy(executor);
 }

package/dist/vcs/file-mode-fixup-commit-strategy.d.ts

@@ -0,0 +1,34 @@
+import type { ICommitStrategy, CommitOptions, CommitResult } from "./types.js";
+import type { ICommandExecutor } from "../shared/command-executor.js";
+import { GhApiClient } from "../shared/gh-api-utils.js";
+/** Factory type for GhApiClient — enables test injection. */
+export type GhApiClientFactory = (executor: ICommandExecutor, retries: number, cwd: string) => GhApiClient;
+/**
+ * Decorator that adds a follow-up commit to fix executable file modes.
+ *
+ * The GitHub GraphQL createCommitOnBranch mutation cannot set file modes.
+ * After the inner strategy (GraphQLCommitStrategy) creates the content commit,
+ * this decorator creates a second commit via the REST Git Data API that
+ * patches tree modes from 100644 to 100755 for executable files.
+ *
+ * Only activates when fileChanges contain entries with mode "100755".
+ * When no executable files are present, delegates directly to the inner strategy.
+ */
+export declare class FileModeFixupCommitStrategy implements ICommitStrategy {
+    private readonly inner;
+    private readonly executor;
+    private readonly clientFactory;
+    constructor(inner: ICommitStrategy, executor: ICommandExecutor, clientFactory?: GhApiClientFactory);
+    commit(options: CommitOptions): Promise<CommitResult>;
+    /**
+     * Create a fixup commit that changes file modes from 100644 to 100755.
+     *
+     * Flow:
+     * 1. GET the content commit to find its tree SHA
+     * 2. GET the tree (recursive) to find blob SHAs for executable files
+     * 3. POST a new tree with updated modes (base_tree carries forward unchanged)
+     * 4. POST a new commit with the new tree
+     * 5. PATCH the branch ref to point to the new commit
+     */
+    private createFixupCommit;
+}

package/dist/vcs/file-mode-fixup-commit-strategy.js

@@ -0,0 +1,127 @@
+import { isGitHubRepo } from "../shared/repo-detector.js";
+import { GhApiClient } from "../shared/gh-api-utils.js";
+import { parseApiJson } from "../shared/json-utils.js";
+import { SyncError } from "../shared/errors.js";
+const defaultClientFactory = (executor, retries, cwd) => new GhApiClient(executor, retries, cwd);
+/**
+ * Decorator that adds a follow-up commit to fix executable file modes.
+ *
+ * The GitHub GraphQL createCommitOnBranch mutation cannot set file modes.
+ * After the inner strategy (GraphQLCommitStrategy) creates the content commit,
+ * this decorator creates a second commit via the REST Git Data API that
+ * patches tree modes from 100644 to 100755 for executable files.
+ *
+ * Only activates when fileChanges contain entries with mode "100755".
+ * When no executable files are present, delegates directly to the inner strategy.
+ */
+export class FileModeFixupCommitStrategy {
+    inner;
+    executor;
+    clientFactory;
+    constructor(inner, executor, clientFactory = defaultClientFactory) {
+        this.inner = inner;
+        this.executor = executor;
+        this.clientFactory = clientFactory;
+    }
+    async commit(options) {
+        const innerResult = await this.inner.commit(options);
+        // Only non-deleted files can have their mode fixed (deletions have content === null)
+        const executableFiles = options.fileChanges.filter((fc) => fc.mode === "100755" && fc.content !== null);
+        if (executableFiles.length === 0) {
+            return innerResult;
+        }
+        // Safety net: only GitHub repos use the REST Git Data API for fixup.
+        // Currently only composed for GitHub repos in createCommitStrategy(),
+        // but guard defensively in case the decorator is reused elsewhere.
+        if (!isGitHubRepo(options.repoInfo)) {
+            return innerResult;
+        }
+        return await this.createFixupCommit(options.repoInfo, options.branchName, innerResult, executableFiles, options.workDir, options.retries ?? 3, options.token);
+    }
+    /**
+     * Create a fixup commit that changes file modes from 100644 to 100755.
+     *
+     * Flow:
+     * 1. GET the content commit to find its tree SHA
+     * 2. GET the tree (recursive) to find blob SHAs for executable files
+     * 3. POST a new tree with updated modes (base_tree carries forward unchanged)
+     * 4. POST a new commit with the new tree
+     * 5. PATCH the branch ref to point to the new commit
+     */
+    async createFixupCommit(repoInfo, branchName, innerResult, executableFiles, workDir, retries, token) {
+        const parentSha = innerResult.sha;
+        const client = this.clientFactory(this.executor, retries, workDir);
+        const apiOpts = {
+            token,
+            host: repoInfo.host,
+        };
+        const repoPath = `repos/${repoInfo.owner}/${repoInfo.repo}`;
+        // 1. Get the commit to find tree SHA
+        const commitRaw = await client.call("GET", `${repoPath}/git/commits/${parentSha}`, { options: apiOpts });
+        const commitData = parseApiJson(commitRaw, "GET git commit");
+        const treeSha = commitData.tree.sha;
+        // 2. Get tree entries to find blob SHAs
+        const treeRaw = await client.call("GET", `${repoPath}/git/trees/${treeSha}?recursive=1`, { options: apiOpts });
+        const treeData = parseApiJson(treeRaw, "GET git tree");
+        const executablePaths = new Set(executableFiles.map((f) => f.path));
+        const treeEntries = [];
+        for (const entry of treeData.tree) {
+            if (executablePaths.has(entry.path) &&
+                entry.type === "blob" &&
+                entry.mode !== "100755") {
+                treeEntries.push({
+                    path: entry.path,
+                    mode: "100755",
+                    type: "blob",
+                    sha: entry.sha,
+                });
+            }
+        }
+        // If tree was truncated (>100k entries), check that all executable files were found
+        if (treeData.truncated) {
+            const foundPaths = new Set(treeData.tree.filter((e) => e.type === "blob").map((e) => e.path));
+            const missing = [...executablePaths].filter((p) => !foundPaths.has(p));
+            if (missing.length > 0) {
+                throw new SyncError(`File mode fixup incomplete: tree response was truncated (>100k entries) ` +
+                    `and ${missing.length} executable file(s) were not found: ${missing.join(", ")}`);
+            }
+        }
+        if (treeEntries.length === 0) {
+            // All requested files are either already 100755 or absent from the tree.
+            // Absent files in a non-truncated tree means createCommitOnBranch did not
+            // include them (e.g., concurrent deletion) — safe to skip since there is
+            // no blob to patch.
+            return innerResult;
+        }
+        // 3. Create new tree with updated modes
+        const newTreeRaw = await client.call("POST", `${repoPath}/git/trees`, {
+            payload: { base_tree: treeSha, tree: treeEntries },
+            options: apiOpts,
+        });
+        const newTree = parseApiJson(newTreeRaw, "POST git tree");
+        // 4. Create fixup commit (message is not user-customizable; this is an
+        // internal implementation detail of the mode-patching decorator)
+        const newCommitRaw = await client.call("POST", `${repoPath}/git/commits`, {
+            payload: {
+                message: "chore: set executable file modes",
+                tree: newTree.sha,
+                parents: [parentSha],
+            },
+            options: apiOpts,
+        });
+        const newCommit = parseApiJson(newCommitRaw, "POST git commit");
+        // 5. Update branch ref (fast-forward only; force is not needed since the
+        // fixup commit's parent is always the content commit we just created).
+        // Branch names with slashes (e.g. "chore/sync-config") are passed verbatim —
+        // the GitHub REST API accepts literal slashes in ref paths.
+        await client.call("PATCH", `${repoPath}/git/refs/heads/${branchName}`, {
+            payload: { sha: newCommit.sha },
+            options: apiOpts,
+        });
+        return {
+            sha: newCommit.sha,
+            verified: true,
+            pushed: true,
+        };
+    }
+}

package/dist/vcs/github-app-token-manager.d.ts

@@ -4,7 +4,7 @@ import type { GitHubRepoInfo } from "../shared/repo-detector.js";
  * Handles JWT generation, installation discovery, and token caching.
  */
 export declare class GitHubAppTokenManager {
-    private readonly appId;
+    private readonly clientId;
     private readonly privateKey;
     /** Map of "apiHost:owner" -> installation ID */
     private installations;
@@ -12,7 +12,7 @@ export declare class GitHubAppTokenManager {
     private discoveredHosts;
     /** Map of "apiHost:owner" -> cached token */
     private tokenCache;
-    constructor(appId: string, privateKey: string);
+    constructor(clientId: string, privateKey: string);
     /**
      * Generates a JWT for GitHub App authentication.
      * The JWT is signed with RS256 and valid for 10 minutes.

package/dist/vcs/github-app-token-manager.js

@@ -14,7 +14,7 @@ async function assertOkResponse(res, context) {
  * Handles JWT generation, installation discovery, and token caching.
  */
 export class GitHubAppTokenManager {
-    appId;
+    clientId;
     privateKey;
     /** Map of "apiHost:owner" -> installation ID */
     installations = new Map();
@@ -22,8 +22,8 @@ export class GitHubAppTokenManager {
     discoveredHosts = new Set();
     /** Map of "apiHost:owner" -> cached token */
     tokenCache = new Map();
-    constructor(appId, privateKey) {
-        this.appId = appId;
+    constructor(clientId, privateKey) {
+        this.clientId = clientId;
         this.privateKey = privateKey;
     }
     /**
@@ -39,7 +39,7 @@ export class GitHubAppTokenManager {
         const payload = {
             iat: now - 60, // Issued 60 seconds ago to account for clock drift
             exp: now + 600, // Expires in 10 minutes
-            iss: this.appId,
+            iss: this.clientId,
         };
         const encodedHeader = base64UrlEncode(JSON.stringify(header));
         const encodedPayload = base64UrlEncode(JSON.stringify(payload));

package/dist/vcs/index.d.ts

@@ -1,6 +1,7 @@
 export type { PRMergeConfig, FileChange, FileAction, IGitOps, ILocalGitOps, IPRStrategy, GitAuthOptions, PRResult, ICommitStrategy, } from "./types.js";
 export type { GitOpsOptions } from "./git-ops.js";
 export { createCommitStrategy, createTokenManager, } from "./commit-strategy-selector.js";
+export { FileModeFixupCommitStrategy } from "./file-mode-fixup-commit-strategy.js";
 export type { GitHubAppTokenManager } from "./github-app-token-manager.js";
 export { GitOps } from "./git-ops.js";
 export { AuthenticatedGitOps } from "./authenticated-git-ops.js";

package/dist/vcs/index.js

@@ -1,5 +1,6 @@
 // Commit strategies
 export { createCommitStrategy, createTokenManager, } from "./commit-strategy-selector.js";
+export { FileModeFixupCommitStrategy } from "./file-mode-fixup-commit-strategy.js";
 // Git operations
 export { GitOps } from "./git-ops.js";
 export { AuthenticatedGitOps } from "./authenticated-git-ops.js";

package/dist/vcs/types.d.ts

@@ -146,6 +146,9 @@ export interface FileAction {
 export interface FileChange {
     path: string;
     content: string | null;
+    /** Git file mode. Only set for executable files ("100755"). "100644" is included
+     *  in the union for type completeness — non-executable files omit this field. */
+    mode?: "100755" | "100644";
 }
 export interface CommitOptions {
     repoInfo: RepoInfo;

package/package.json

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