@aspruyt/xfg 5.1.5 → 5.2.0

package/dist/config/index.d.ts

@@ -1,4 +1,4 @@
-export type { MergeMode, MergeStrategy, BypassActor, StatusCheckConfig, CodeScanningTool, PullRequestRuleParameters, RulesetRule, Ruleset, GitHubRepoSettings, RepoVisibility, SquashMergeCommitTitle, SquashMergeCommitMessage, MergeCommitTitle, MergeCommitMessage, Label, RepoSettings, RawFileConfig, RawRepoFileOverride, RawRepoSettings, RawRepoConfig, RawConfig, RepoConfig, Config, FileContent, ContentValue, } from "./types.js";
+export type { MergeMode, MergeStrategy, BypassActor, StatusCheckConfig, CodeScanningTool, PullRequestRuleParameters, RulesetRule, Ruleset, GitHubRepoSettings, RepoVisibility, SquashMergeCommitTitle, SquashMergeCommitMessage, MergeCommitTitle, MergeCommitMessage, Label, RepoSettings, RawFileConfig, RawRepoFileOverride, RawRepoSettings, RawRepoConfig, RawConfig, RawConditionalGroupWhen, RawConditionalGroupConfig, RepoConfig, Config, FileContent, ContentValue, } from "./types.js";
 export { RULESET_COMPARABLE_FIELDS } from "./types.js";
 export { loadRawConfig, loadConfig, normalizeConfig } from "./loader.js";
 export { convertContentToString } from "./formatter.js";

package/dist/config/normalizer.js

@@ -358,6 +358,81 @@ function mergeGroupSettings(rootSettings, groupNames, groupDefs) {
     }
     return accumulated;
 }
+/**
+ * Evaluates a conditional group's `when` clause against a repo's effective groups.
+ * Both `allOf` (every listed group present) and `anyOf` (at least one present)
+ * must be satisfied. Absent conditions are treated as satisfied.
+ */
+function evaluateWhenClause(when, effectiveGroups) {
+    // Defensive: if neither condition is specified, don't match
+    if (!when.allOf && !when.anyOf)
+        return false;
+    const allOfSatisfied = !when.allOf || when.allOf.every((g) => effectiveGroups.has(g));
+    const anyOfSatisfied = !when.anyOf || when.anyOf.some((g) => effectiveGroups.has(g));
+    return allOfSatisfied && anyOfSatisfied;
+}
+/**
+ * Merges matching conditional groups into the accumulated files/prOptions/settings.
+ * Each matching conditional group is applied in array order, using the same
+ * merge semantics as regular group layers (inherit:false, file:false, override:true).
+ */
+function mergeConditionalGroups(accumulatedFiles, accumulatedPROptions, accumulatedSettings, effectiveGroups, conditionalGroups) {
+    let files = structuredClone(accumulatedFiles);
+    let prOptions = accumulatedPROptions
+        ? structuredClone(accumulatedPROptions)
+        : undefined;
+    let settings = accumulatedSettings;
+    for (const cg of conditionalGroups) {
+        if (!evaluateWhenClause(cg.when, effectiveGroups))
+            continue;
+        // Merge files using same logic as mergeGroupFiles inner loop
+        if (cg.files) {
+            const inheritFiles = shouldInherit(cg.files);
+            if (!inheritFiles) {
+                files = {};
+            }
+            for (const [fileName, fileConfig] of Object.entries(cg.files)) {
+                if (fileName === "inherit")
+                    continue;
+                if (fileConfig === false) {
+                    delete files[fileName];
+                    continue;
+                }
+                if (fileConfig === undefined)
+                    continue;
+                const existing = files[fileName];
+                if (existing) {
+                    const overlay = fileConfig;
+                    let mergedContent;
+                    if (overlay.override || !existing.content || !overlay.content) {
+                        mergedContent = overlay.content ?? existing.content;
+                    }
+                    else {
+                        mergedContent = mergeContentPair(existing.content, overlay.content, existing.mergeStrategy ?? "replace");
+                    }
+                    const { override: _override, ...restFileConfig } = fileConfig;
+                    files[fileName] = {
+                        ...existing,
+                        ...restFileConfig,
+                        content: mergedContent,
+                    };
+                }
+                else {
+                    files[fileName] = structuredClone(fileConfig);
+                }
+            }
+        }
+        // Merge prOptions
+        if (cg.prOptions) {
+            prOptions = mergePROptions(prOptions, cg.prOptions);
+        }
+        // Merge settings
+        if (cg.settings) {
+            settings = mergeRawSettings(settings, cg.settings);
+        }
+    }
+    return { files, prOptions, settings };
+}
 /**
  * Resolves a single file entry by merging root config with repo overrides.
  * Returns null if the file should be skipped.
@@ -396,16 +471,24 @@ export function normalizeConfig(raw, env) {
     const expandedRepos = [];
     for (const rawRepo of raw.repos) {
         const gitUrls = Array.isArray(rawRepo.git) ? rawRepo.git : [rawRepo.git];
-        // Resolve groups: build effective root files/prOptions/settings by merging group layers
-        const effectiveRootFiles = rawRepo.groups?.length
+        // Phase 1: Resolve groups - build effective root files/prOptions/settings by merging group layers
+        let effectiveRootFiles = rawRepo.groups?.length
             ? mergeGroupFiles(raw.files ?? {}, rawRepo.groups, raw.groups ?? {})
             : (raw.files ?? {});
-        const effectivePROptions = rawRepo.groups?.length
+        let effectivePROptions = rawRepo.groups?.length
             ? mergeGroupPROptions(raw.prOptions, rawRepo.groups, raw.groups ?? {})
             : raw.prOptions;
-        const effectiveSettings = rawRepo.groups?.length
+        let effectiveSettings = rawRepo.groups?.length
             ? mergeGroupSettings(raw.settings, rawRepo.groups, raw.groups ?? {})
             : raw.settings;
+        // Phase 2 + 3: Evaluate and merge conditional groups
+        if (raw.conditionalGroups?.length) {
+            const effectiveGroups = new Set(rawRepo.groups ?? []);
+            const merged = mergeConditionalGroups(effectiveRootFiles, effectivePROptions, effectiveSettings, effectiveGroups, raw.conditionalGroups);
+            effectiveRootFiles = merged.files;
+            effectivePROptions = merged.prOptions;
+            effectiveSettings = merged.settings;
+        }
         const fileNames = Object.keys(effectiveRootFiles);
         for (const gitUrl of gitUrls) {
             const files = [];

package/dist/config/types.d.ts

@@ -298,6 +298,26 @@ export interface RawGroupConfig {
     prOptions?: PRMergeOptions;
     settings?: RawRepoSettings;
 }
+/** Condition for conditional group activation */
+export interface RawConditionalGroupWhen {
+    /** All listed groups must be present in the repo's effective group set */
+    allOf?: string[];
+    /** At least one listed group must be present */
+    anyOf?: string[];
+}
+/** Conditional group: activates based on which groups a repo has */
+export interface RawConditionalGroupConfig {
+    /** Condition that determines when this group activates */
+    when: RawConditionalGroupWhen;
+    /** File definitions or overrides (same capabilities as regular groups) */
+    files?: Record<string, RawFileConfig | RawRepoFileOverride | false> & {
+        inherit?: boolean;
+    };
+    /** PR merge options */
+    prOptions?: PRMergeOptions;
+    /** Repository settings (rulesets, labels, repo settings) */
+    settings?: RawRepoSettings;
+}
 export interface RawRootSettings {
     rulesets?: Record<string, Ruleset | false>;
     repo?: GitHubRepoSettings | false;
@@ -331,6 +351,7 @@ export interface RawConfig {
     id: string;
     files?: Record<string, RawFileConfig>;
     groups?: Record<string, RawGroupConfig>;
+    conditionalGroups?: RawConditionalGroupConfig[];
     repos: RawRepoConfig[];
     prOptions?: PRMergeOptions;
     prTemplate?: string;

package/dist/config/validator.js

@@ -286,6 +286,79 @@ function validateGroups(config) {
         }
     }
 }
+function validateConditionalGroups(config) {
+    if (config.conditionalGroups === undefined)
+        return;
+    if (!Array.isArray(config.conditionalGroups)) {
+        throw new ValidationError("conditionalGroups must be an array");
+    }
+    const rootCtx = buildRootSettingsContext(config);
+    const groupNames = config.groups ? Object.keys(config.groups) : [];
+    for (let i = 0; i < config.conditionalGroups.length; i++) {
+        const entry = config.conditionalGroups[i];
+        const ctx = `conditionalGroups[${i}]`;
+        // Validate 'when' clause
+        if (!entry.when || !isPlainObject(entry.when)) {
+            throw new ValidationError(`${ctx}: 'when' is required and must be an object`);
+        }
+        const { allOf, anyOf } = entry.when;
+        if (!allOf && !anyOf) {
+            throw new ValidationError(`${ctx}: 'when' must have at least one of 'allOf' or 'anyOf'`);
+        }
+        if (allOf !== undefined) {
+            if (!Array.isArray(allOf) || allOf.length === 0) {
+                throw new ValidationError(`${ctx}: 'allOf' must be a non-empty array of strings`);
+            }
+            const seen = new Set();
+            for (const name of allOf) {
+                if (typeof name !== "string") {
+                    throw new ValidationError(`${ctx}: 'allOf' entries must be strings`);
+                }
+                if (!groupNames.includes(name)) {
+                    throw new ValidationError(`${ctx}: group '${name}' in allOf is not defined in root 'groups'`);
+                }
+                if (seen.has(name)) {
+                    throw new ValidationError(`${ctx}: duplicate group '${name}' in allOf`);
+                }
+                seen.add(name);
+            }
+        }
+        if (anyOf !== undefined) {
+            if (!Array.isArray(anyOf) || anyOf.length === 0) {
+                throw new ValidationError(`${ctx}: 'anyOf' must be a non-empty array of strings`);
+            }
+            const seen = new Set();
+            for (const name of anyOf) {
+                if (typeof name !== "string") {
+                    throw new ValidationError(`${ctx}: 'anyOf' entries must be strings`);
+                }
+                if (!groupNames.includes(name)) {
+                    throw new ValidationError(`${ctx}: group '${name}' in anyOf is not defined in root 'groups'`);
+                }
+                if (seen.has(name)) {
+                    throw new ValidationError(`${ctx}: duplicate group '${name}' in anyOf`);
+                }
+                seen.add(name);
+            }
+        }
+        // Validate files
+        if (entry.files) {
+            for (const [fileName, fileConfig] of Object.entries(entry.files)) {
+                if (fileName === "inherit")
+                    continue;
+                if (fileConfig === false)
+                    continue;
+                if (fileConfig === undefined)
+                    continue;
+                validateFileConfigFields(fileConfig, fileName, `${ctx}:`);
+            }
+        }
+        // Validate settings
+        if (entry.settings !== undefined) {
+            validateSettings(entry.settings, ctx, rootCtx);
+        }
+    }
+}
 function validateRepoGitField(repo, index) {
     if (!repo.git) {
         throw new ValidationError(`Repo at index ${index} missing required field: git`);
@@ -359,6 +432,16 @@ function validateRepoFiles(config, repo, index, repoLabel) {
             }
         }
     }
+    if (config.conditionalGroups) {
+        for (const cg of config.conditionalGroups) {
+            if (cg.files) {
+                for (const fn of Object.keys(cg.files)) {
+                    if (fn !== "inherit")
+                        knownFiles.add(fn);
+                }
+            }
+        }
+    }
     for (const fileName of Object.keys(repo.files)) {
         if (fileName === "inherit") {
             const inheritValue = repo.files.inherit;
@@ -400,6 +483,29 @@ function validateRepoSettingsEntry(config, repo, repoLabel) {
                         rootCtx.labelNames.push(name);
                 }
             }
+            if (group?.settings?.repo !== undefined &&
+                group.settings.repo !== false) {
+                rootCtx.hasRepoSettings = true;
+            }
+        }
+    }
+    if (config.conditionalGroups) {
+        for (const cg of config.conditionalGroups) {
+            if (cg.settings?.rulesets) {
+                for (const name of Object.keys(cg.settings.rulesets)) {
+                    if (name !== "inherit")
+                        rootCtx.rulesetNames.push(name);
+                }
+            }
+            if (cg.settings?.labels) {
+                for (const name of Object.keys(cg.settings.labels)) {
+                    if (name !== "inherit")
+                        rootCtx.labelNames.push(name);
+                }
+            }
+            if (cg.settings?.repo !== undefined && cg.settings.repo !== false) {
+                rootCtx.hasRepoSettings = true;
+            }
         }
     }
     validateSettings(repo.settings, `Repo ${repoLabel}`, rootCtx);
@@ -427,7 +533,20 @@ export function validateRawConfig(config) {
     const hasGrpFiles = hasGroupFiles(config);
     const hasGrpSettings = isPlainObject(config.groups) &&
         Object.values(config.groups).some((g) => g.settings && isPlainObject(g.settings));
-    if (!hasFiles && !hasSettings && !hasGrpFiles && !hasGrpSettings) {
+    const hasCondGrpFiles = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.files &&
+            Object.keys(cg.files).filter((k) => k !== "inherit" && cg.files[k] !== false).length > 0);
+    const hasCondGrpSettings = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.settings && isPlainObject(cg.settings));
+    const hasCondGrpPR = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.prOptions && isPlainObject(cg.prOptions));
+    if (!hasFiles &&
+        !hasSettings &&
+        !hasGrpFiles &&
+        !hasGrpSettings &&
+        !hasCondGrpFiles &&
+        !hasCondGrpSettings &&
+        !hasCondGrpPR) {
         throw new ValidationError("Config requires at least one of: 'files' or 'settings'. " +
             "Use 'files' to sync configuration files, or 'settings' to manage repository settings.");
     }
@@ -443,6 +562,7 @@ export function validateRawConfig(config) {
     validateGithubHosts(config);
     validatePrOptions(config);
     validateGroups(config);
+    validateConditionalGroups(config);
     for (let i = 0; i < config.repos.length; i++) {
         validateRepoEntry(config, config.repos[i], i);
     }
@@ -461,11 +581,21 @@ export function validateForSync(config) {
     const hasRepoSettings = config.repos.some((repo) => hasActionableSettings(repo.settings));
     const hasGroupSettings = isPlainObject(config.groups) &&
         Object.values(config.groups).some((g) => g.settings && hasActionableSettings(g.settings));
+    const hasCondGrpFiles = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.files &&
+            Object.keys(cg.files).filter((k) => k !== "inherit" && cg.files[k] !== false).length > 0);
+    const hasCondGrpSettings = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.settings && hasActionableSettings(cg.settings));
+    const hasCondGrpPR = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.prOptions && isPlainObject(cg.prOptions));
     if (!hasRootFiles &&
         !hasGrpFiles &&
         !hasSettings &&
         !hasRepoSettings &&
-        !hasGroupSettings) {
+        !hasGroupSettings &&
+        !hasCondGrpFiles &&
+        !hasCondGrpSettings &&
+        !hasCondGrpPR) {
         throw new ValidationError("Config requires at least one of: 'files' or 'settings'. " +
             "Use 'files' to sync configuration files, or 'settings' to manage repository settings.");
     }

package/dist/output/settings-report.js

@@ -147,6 +147,7 @@ function formatRulesetConfigPlain(config) {
  * Shared between formatSettingsReportMarkdown and unified-summary's renderSettingsLines.
  */
 export function renderRepoSettingsDiffLines(repo, diffLines) {
+    const startLength = diffLines.length;
     for (const setting of repo.settings) {
         if (setting.oldValue === undefined && setting.newValue === undefined) {
             continue;
@@ -158,7 +159,15 @@ export function renderRepoSettingsDiffLines(repo, diffLines) {
             diffLines.push(`! ${setting.name}: ${formatValuePlain(setting.oldValue)} → ${formatValuePlain(setting.newValue)}`);
         }
     }
-    for (const ruleset of repo.rulesets) {
+    // Blank line before rulesets if there was content above
+    if (repo.rulesets.length > 0 && diffLines.length > startLength) {
+        diffLines.push("");
+    }
+    for (let i = 0; i < repo.rulesets.length; i++) {
+        const ruleset = repo.rulesets[i];
+        // Blank line between rulesets
+        if (i > 0)
+            diffLines.push("");
         if (ruleset.action === "create") {
             diffLines.push(`+ ruleset "${ruleset.name}"`);
             if (ruleset.config) {
@@ -188,6 +197,10 @@ export function renderRepoSettingsDiffLines(repo, diffLines) {
             diffLines.push(`- ruleset "${ruleset.name}"`);
         }
     }
+    // Blank line before labels if there was content above
+    if (repo.labels.length > 0 && diffLines.length > startLength) {
+        diffLines.push("");
+    }
     for (const label of repo.labels) {
         if (label.action === "create") {
             diffLines.push(`+ label "${label.name}"`);
@@ -238,8 +251,7 @@ export function formatSettingsReportMarkdown(report, dryRun) {
         lines.push("> This was a dry run — no changes were applied");
         lines.push("");
     }
-    // Diff block
-    const diffLines = [];
+    // Per-repo sections: heading + diff block
     for (const repo of report.repos) {
         if (repo.settings.length === 0 &&
             repo.rulesets.length === 0 &&
@@ -247,14 +259,16 @@ export function formatSettingsReportMarkdown(report, dryRun) {
             !repo.error) {
             continue;
         }
-        diffLines.push(`@@ ${repo.repoName} @@`);
-        renderRepoSettingsDiffLines(repo, diffLines);
-    }
-    if (diffLines.length > 0) {
-        lines.push("```diff");
-        lines.push(...diffLines);
-        lines.push("```");
+        lines.push(`### ${repo.repoName}`);
         lines.push("");
+        const diffLines = [];
+        renderRepoSettingsDiffLines(repo, diffLines);
+        if (diffLines.length > 0) {
+            lines.push("```diff");
+            lines.push(...diffLines);
+            lines.push("```");
+            lines.push("");
+        }
     }
     // Summary
     lines.push(`**${formatSettingsSummary(report.totals)}**`);

package/dist/output/sync-report.js

@@ -58,27 +58,32 @@ export function formatSyncReportMarkdown(report, dryRun) {
         lines.push("> This was a dry run — no changes were applied");
         lines.push("");
     }
-    // Diff block
-    const diffLines = [];
+    // Per-repo sections: heading + diff block
     for (const repo of report.repos) {
         if (repo.files.length === 0 && !repo.error) {
             continue;
         }
-        diffLines.push(`@@ ${repo.repoName} @@`);
-        renderSyncLines(repo, diffLines);
-    }
-    if (diffLines.length > 0) {
-        lines.push("```diff");
-        lines.push(...diffLines);
-        lines.push("```");
+        lines.push(`### ${repo.repoName}`);
         lines.push("");
+        const diffLines = [];
+        renderSyncLines(repo, diffLines);
+        if (diffLines.length > 0) {
+            lines.push("```diff");
+            lines.push(...diffLines);
+            lines.push("```");
+            lines.push("");
+        }
     }
     // Summary
     lines.push(`**${formatSyncSummary(report.totals)}**`);
     return lines.join("\n");
 }
 export function renderSyncLines(syncRepo, diffLines) {
-    for (const file of syncRepo.files) {
+    for (let i = 0; i < syncRepo.files.length; i++) {
+        const file = syncRepo.files[i];
+        // Blank line between files for readability
+        if (i > 0)
+            diffLines.push("");
         if (file.action === "create") {
             diffLines.push(`+ ${file.path}`);
         }

package/dist/output/unified-summary.js

@@ -165,8 +165,7 @@ export function formatUnifiedSummaryMarkdown(input) {
         addRepo(r.repoName);
     for (const r of input.settings?.repos ?? [])
         addRepo(r.repoName);
-    // Diff block
-    const diffLines = [];
+    // Per-repo sections: heading + diff block
     for (const repoName of allRepos) {
         const lcAction = lifecycleByRepo.get(repoName);
         const syncRepo = syncByRepo.get(repoName);
@@ -180,19 +179,27 @@ export function formatUnifiedSummaryMarkdown(input) {
                 settingsRepo.error);
         if (!hasLcChange && !hasSyncChanges && !hasSettingsChanges)
             continue;
-        diffLines.push(`@@ ${repoName} @@`);
+        lines.push(`### ${repoName}`);
+        lines.push("");
+        const diffLines = [];
         if (lcAction)
             renderLifecycleLines(lcAction, diffLines);
+        // Blank line between lifecycle and sync sections
+        if (hasLcChange && hasSyncChanges)
+            diffLines.push("");
         if (syncRepo)
             renderSyncLines(syncRepo, diffLines);
+        // Blank line between files and settings sections
+        if (hasSyncChanges && hasSettingsChanges)
+            diffLines.push("");
         if (settingsRepo)
             renderRepoSettingsDiffLines(settingsRepo, diffLines);
-    }
-    if (diffLines.length > 0) {
-        lines.push("```diff");
-        lines.push(...diffLines);
-        lines.push("```");
-        lines.push("");
+        if (diffLines.length > 0) {
+            lines.push("```diff");
+            lines.push(...diffLines);
+            lines.push("```");
+            lines.push("");
+        }
     }
     // Combined summary
     lines.push(`**${formatCombinedSummary(input)}**`);

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

@@ -13,6 +13,8 @@ interface GhApiCallParams {
     payload?: unknown;
     options?: GhApiOptions;
     paginate?: boolean;
+    /** Override for delay function (test injection) */
+    _retryDelay?: (ms: number) => Promise<void>;
 }
 /**
  * Get the hostname flag for gh commands.
@@ -20,6 +22,20 @@ interface GhApiCallParams {
  */
 export declare function getHostnameFlag(repoInfo: GitHubRepoInfo): string;
 export declare function buildTokenEnv(token?: string): Record<string, string> | undefined;
+/**
+ * Strips HTTP response headers from `gh api --include` output.
+ * Splits on the first blank line (LF or CRLF) and returns everything after it.
+ * If no blank line is found, returns the full string (no headers present).
+ */
+export declare function parseResponseBody(raw: string): string;
+/**
+ * Parses Retry-After header from an exec error's stdout and attaches it
+ * as error.retryAfter (number of seconds). Only extracts the numeric value
+ * to avoid leaking tokens from other headers.
+ *
+ * No-op if stdout is absent or does not contain a numeric Retry-After header.
+ */
+export declare function attachRetryAfter(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

@@ -14,6 +14,40 @@ export function getHostnameFlag(repoInfo) {
 export function buildTokenEnv(token) {
     return token ? { GH_TOKEN: token } : undefined;
 }
+/**
+ * Strips HTTP response headers from `gh api --include` output.
+ * Splits on the first blank line (LF or CRLF) and returns everything after it.
+ * If no blank line is found, returns the full string (no headers present).
+ */
+export function parseResponseBody(raw) {
+    // Try CRLF first, then LF
+    const crlfIndex = raw.indexOf("\r\n\r\n");
+    if (crlfIndex !== -1) {
+        return raw.slice(crlfIndex + 4);
+    }
+    const lfIndex = raw.indexOf("\n\n");
+    if (lfIndex !== -1) {
+        return raw.slice(lfIndex + 2);
+    }
+    return raw;
+}
+/**
+ * Parses Retry-After header from an exec error's stdout and attaches it
+ * as error.retryAfter (number of seconds). Only extracts the numeric value
+ * to avoid leaking tokens from other headers.
+ *
+ * No-op if stdout is absent or does not contain a numeric Retry-After header.
+ */
+export function attachRetryAfter(error) {
+    const stdout = error.stdout;
+    if (!stdout)
+        return;
+    const stdoutStr = typeof stdout === "string" ? stdout : stdout.toString();
+    const match = stdoutStr.match(/^retry-after:\s*(\d+)\s*$/im);
+    if (match) {
+        error.retryAfter = parseInt(match[1], 10);
+    }
+}
 /**
  * Executes a GitHub API call using the gh CLI.
  * Shared by labels, rulesets, and repo-settings strategies.
@@ -30,23 +64,38 @@ async function ghApiCall(method, endpoint, opts) {
     if (paginate) {
         args.push("--paginate");
     }
+    else {
+        args.push("--include");
+    }
     if (apiOpts?.host && apiOpts.host !== "github.com") {
         args.push("--hostname", escapeShellArg(apiOpts.host));
     }
     args.push(escapeShellArg(endpoint));
     const baseCommand = args.join(" ");
     const env = buildTokenEnv(apiOpts?.token);
+    const execAndParse = async (command) => {
+        try {
+            const raw = await executor.exec(command, cwd, { env });
+            return paginate ? raw : parseResponseBody(raw);
+        }
+        catch (error) {
+            if (!paginate) {
+                attachRetryAfter(error);
+            }
+            throw error;
+        }
+    };
+    const retryOpts = {
+        retries,
+        ...(opts._retryDelay ? { _delay: opts._retryDelay } : {}),
+    };
     if (payload &&
         (method === "POST" || method === "PUT" || method === "PATCH")) {
         const payloadJson = JSON.stringify(payload);
         const command = `echo ${escapeShellArg(payloadJson)} | ${baseCommand} --input -`;
-        return await withRetry(() => executor.exec(command, cwd, { env }), {
-            retries,
-        });
+        return await withRetry(() => execAndParse(command), retryOpts);
     }
-    return await withRetry(() => executor.exec(baseCommand, cwd, { env }), {
-        retries,
-    });
+    return await withRetry(() => execAndParse(baseCommand), retryOpts);
 }
 /**
  * Encapsulates executor + retries for GitHub API calls.
@@ -69,6 +118,7 @@ export class GhApiClient {
             apiOpts: params?.options,
             payload: params?.payload,
             paginate: params?.paginate,
+            _retryDelay: params?._retryDelay,
         });
     }
 }

package/dist/shared/retry-utils.d.ts

@@ -8,6 +8,11 @@ export declare const CORE_PERMANENT_ERROR_PATTERNS: RegExp[];
  * Extends CORE_PERMANENT_ERROR_PATTERNS with git-CLI-specific patterns.
  */
 export declare const DEFAULT_PERMANENT_ERROR_PATTERNS: RegExp[];
+/**
+ * Checks if an error specifically indicates a rate limit (not just any transient error).
+ * Rate limit errors need longer backoff (60s+) compared to network errors (1-4s).
+ */
+export declare function isRateLimitError(error: unknown): boolean;
 interface RetryOptions {
     /** Maximum number of retries (default: 3) */
     retries?: number;
@@ -21,6 +26,8 @@ interface RetryOptions {
     log?: {
         info(msg: string): void;
     };
+    /** Override for delay function (test injection) */
+    _delay?: (ms: number) => Promise<void>;
 }
 /**
  * Classifies an error as permanent (should not retry) or transient (should retry).

package/dist/shared/retry-utils.js

@@ -65,6 +65,36 @@ const DEFAULT_TRANSIENT_ERROR_PATTERNS = [
     /could\s*not\s*resolve\s*host/i,
     /unable\s*to\s*access/i,
 ];
+/**
+ * Patterns that specifically indicate rate limiting (a subset of transient errors).
+ * Used to apply longer backoff delays -- connection resets and 5xx errors
+ * should NOT get 60-second waits.
+ */
+const RATE_LIMIT_PATTERNS = [
+    /rate\s*limit/i,
+    /too\s*many\s*requests/i,
+    /abuse\s*detection/i,
+];
+/**
+ * Checks if an error specifically indicates a rate limit (not just any transient error).
+ * Rate limit errors need longer backoff (60s+) compared to network errors (1-4s).
+ */
+export function isRateLimitError(error) {
+    const message = error instanceof Error ? error.message : String(error ?? "");
+    const stderr = error.stderr?.toString() ?? "";
+    const combined = `${message} ${stderr}`;
+    for (const pattern of RATE_LIMIT_PATTERNS) {
+        if (pattern.test(combined)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Default delay (seconds) for rate limit errors when no Retry-After header is available. */
+const RATE_LIMIT_FALLBACK_DELAY_SECONDS = 60;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
  * Classifies an error as permanent (should not retry) or transient (should retry).
  */
@@ -116,6 +146,7 @@ export async function withRetry(fn, options) {
         }
         catch (error) {
             if (error instanceof Error &&
+                !isTransientError(error, options?.transientErrorPatterns) &&
                 isPermanentError(error, permanentPatterns)) {
                 // Wrap in AbortError to stop retrying immediately
                 throw new AbortError(error);
@@ -124,8 +155,15 @@ export async function withRetry(fn, options) {
         }
     }, {
         retries,
-        onFailedAttempt: (context) => {
-            // Only log if this isn't the last attempt
+        onFailedAttempt: async (context) => {
+            // Apply rate-limit-specific delay before the next retry
+            if (context.retriesLeft > 0 && isRateLimitError(context.error)) {
+                const retryAfterSeconds = context.error.retryAfter ??
+                    RATE_LIMIT_FALLBACK_DELAY_SECONDS;
+                options?.log?.info(`Rate limited. Waiting ${retryAfterSeconds}s before retry...`);
+                await (options?._delay ?? delay)(retryAfterSeconds * 1000);
+            }
+            // Log the failure (existing behavior)
             if (context.retriesLeft > 0) {
                 const msg = sanitizeCredentials(context.error.message) || "Unknown error";
                 options?.log?.info(`Attempt ${context.attemptNumber}/${retries + 1} failed: ${msg}. Retrying...`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "5.1.5",
+  "version": "5.2.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",
@@ -78,6 +78,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "bottleneck": "^2.19.5",
     "c8": "^11.0.0",
     "tsx": "^4.15.0",
     "typescript": "^5.4.5"