@aspruyt/xfg 5.2.0 → 5.3.1

package/dist/cli/types.d.ts

@@ -44,7 +44,7 @@ export interface SyncResultEntry {
     mergeOutcome?: "manual" | "auto" | "force" | "direct";
     error?: string;
 }
-export interface SettingsResult extends Pick<BaseProcessorResult, "success" | "message" | "skipped"> {
+export interface SettingsResult extends BaseProcessorResult {
     planOutput?: {
         lines?: string[];
     };

package/dist/config/extends-resolver.d.ts

@@ -0,0 +1,13 @@
+import type { RawGroupConfig } from "./types.js";
+/**
+ * Resolves a single group's extends chain into an ordered list of group names.
+ * Parents appear before children (topological order). Detects circular extends
+ * and missing group references.
+ */
+export declare function resolveExtendsChain(groupName: string, groupDefs: Record<string, RawGroupConfig>): string[];
+/**
+ * Expands a repo's group list by resolving extends chains for each group.
+ * Returns the full ordered list with transitive parents, deduplicated.
+ * First occurrence wins for deduplication (preserves topological order).
+ */
+export declare function expandRepoGroups(repoGroups: string[], groupDefs: Record<string, RawGroupConfig>): string[];

package/dist/config/extends-resolver.js

@@ -0,0 +1,63 @@
+const MAX_EXTENDS_DEPTH = 100;
+/**
+ * Resolves a single group's extends chain into an ordered list of group names.
+ * Parents appear before children (topological order). Detects circular extends
+ * and missing group references.
+ */
+export function resolveExtendsChain(groupName, groupDefs) {
+    function walk(name, visited, depth) {
+        if (depth > MAX_EXTENDS_DEPTH) {
+            throw new Error(`Extends chain exceeds maximum depth of ${MAX_EXTENDS_DEPTH} — likely misconfigured`);
+        }
+        if (visited.has(name)) {
+            const cycle = [...visited, name].join(" -> ");
+            throw new Error(`Circular extends detected: ${cycle}`);
+        }
+        visited.add(name);
+        const group = groupDefs[name];
+        if (!group) {
+            throw new Error(`Group '${name}' referenced in extends chain does not exist`);
+        }
+        if (!group.extends) {
+            return [name];
+        }
+        const parents = Array.isArray(group.extends)
+            ? group.extends
+            : [group.extends];
+        const result = [];
+        const seen = new Set();
+        for (const parent of parents) {
+            const chain = walk(parent, new Set(visited), depth + 1);
+            for (const n of chain) {
+                if (!seen.has(n)) {
+                    seen.add(n);
+                    result.push(n);
+                }
+            }
+        }
+        if (!seen.has(name)) {
+            result.push(name);
+        }
+        return result;
+    }
+    return walk(groupName, new Set(), 0);
+}
+/**
+ * Expands a repo's group list by resolving extends chains for each group.
+ * Returns the full ordered list with transitive parents, deduplicated.
+ * First occurrence wins for deduplication (preserves topological order).
+ */
+export function expandRepoGroups(repoGroups, groupDefs) {
+    const result = [];
+    const seen = new Set();
+    for (const groupName of repoGroups) {
+        const chain = resolveExtendsChain(groupName, groupDefs);
+        for (const name of chain) {
+            if (!seen.has(name)) {
+                seen.add(name);
+                result.push(name);
+            }
+        }
+    }
+    return result;
+}

package/dist/config/file-reference-resolver.js

@@ -132,6 +132,23 @@ export function resolveFileReferencesInConfig(raw, options) {
             }
         }
     }
+    // Resolve conditional group file content
+    if (result.conditionalGroups) {
+        for (const cg of result.conditionalGroups) {
+            if (cg.files) {
+                for (const [fileName, fileConfig] of Object.entries(cg.files)) {
+                    if (fileConfig &&
+                        typeof fileConfig === "object" &&
+                        "content" in fileConfig) {
+                        const resolved = resolveContentValue(fileConfig.content, configDir);
+                        if (resolved !== undefined) {
+                            cg.files[fileName] = { ...fileConfig, content: resolved };
+                        }
+                    }
+                }
+            }
+        }
+    }
     // Resolve per-repo file content
     if (result.repos) {
         for (const repo of result.repos) {

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, RawConditionalGroupWhen, RawConditionalGroupConfig, 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, RawGroupConfig, 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

@@ -1,5 +1,6 @@
 import { deepMerge, stripMergeDirectives, createMergeContext, isTextContent, mergeTextContent, } from "./merge.js";
 import { interpolateContent } from "../shared/env.js";
+import { expandRepoGroups } from "./extends-resolver.js";
 /**
  * Clone content, stripping merge directives from object content.
  * Text content is cloned as-is since it has no merge directives.
@@ -203,6 +204,47 @@ export function mergeSettings(root, perRepo) {
     }
     return Object.keys(result).length > 0 ? result : undefined;
 }
+/**
+ * Applies a single file-layer onto an accumulated file map: inherit:false clears,
+ * file:false removes entries, otherwise deep-merges content.
+ */
+function applyFileLayer(accumulated, layerFiles) {
+    const inheritFiles = shouldInherit(layerFiles);
+    if (!inheritFiles) {
+        accumulated = {};
+    }
+    for (const [fileName, fileConfig] of Object.entries(layerFiles)) {
+        if (fileName === "inherit")
+            continue;
+        if (fileConfig === false) {
+            delete accumulated[fileName];
+            continue;
+        }
+        if (fileConfig === undefined)
+            continue;
+        const existing = accumulated[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;
+            accumulated[fileName] = {
+                ...existing,
+                ...restFileConfig,
+                content: mergedContent,
+            };
+        }
+        else {
+            accumulated[fileName] = structuredClone(fileConfig);
+        }
+    }
+    return accumulated;
+}
 /**
  * Merges group file layers onto root files, producing an effective root file map.
  * Each group layer is processed in order: inherit:false clears accumulated,
@@ -214,45 +256,7 @@ function mergeGroupFiles(rootFiles, groupNames, groupDefs) {
         const group = groupDefs[groupName];
         if (!group?.files)
             continue;
-        const inheritFiles = shouldInherit(group.files);
-        if (!inheritFiles) {
-            // Intentionally clear: "discard everything above me"
-            accumulated = {};
-        }
-        for (const [fileName, fileConfig] of Object.entries(group.files)) {
-            if (fileName === "inherit")
-                continue;
-            // file: false removes from accumulated set
-            if (fileConfig === false) {
-                delete accumulated[fileName];
-                continue;
-            }
-            if (fileConfig === undefined)
-                continue;
-            const existing = accumulated[fileName];
-            if (existing) {
-                // Deep-merge content if both sides have object content
-                const overlay = fileConfig;
-                let mergedContent;
-                if (overlay.override || !existing.content || !overlay.content) {
-                    // override:true or one side missing content — use overlay content
-                    mergedContent = overlay.content ?? existing.content;
-                }
-                else {
-                    mergedContent = mergeContentPair(existing.content, overlay.content, existing.mergeStrategy ?? "replace");
-                }
-                const { override: _override, ...restFileConfig } = fileConfig;
-                accumulated[fileName] = {
-                    ...existing,
-                    ...restFileConfig,
-                    content: mergedContent,
-                };
-            }
-            else {
-                // New file introduced by group
-                accumulated[fileName] = structuredClone(fileConfig);
-            }
-        }
+        accumulated = applyFileLayer(accumulated, group.files);
     }
     return accumulated;
 }
@@ -385,42 +389,8 @@ function mergeConditionalGroups(accumulatedFiles, accumulatedPROptions, accumula
     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);
-                }
-            }
+            files = applyFileLayer(files, cg.files);
         }
         // Merge prOptions
         if (cg.prOptions) {
@@ -471,19 +441,23 @@ export function normalizeConfig(raw, env) {
     const expandedRepos = [];
     for (const rawRepo of raw.repos) {
         const gitUrls = Array.isArray(rawRepo.git) ? rawRepo.git : [rawRepo.git];
+        // Phase 0: Expand extends chains
+        const expandedGroups = rawRepo.groups?.length
+            ? expandRepoGroups(rawRepo.groups, raw.groups ?? {})
+            : [];
         // 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 ?? {})
+        let effectiveRootFiles = expandedGroups.length
+            ? mergeGroupFiles(raw.files ?? {}, expandedGroups, raw.groups ?? {})
             : (raw.files ?? {});
-        let effectivePROptions = rawRepo.groups?.length
-            ? mergeGroupPROptions(raw.prOptions, rawRepo.groups, raw.groups ?? {})
+        let effectivePROptions = expandedGroups.length
+            ? mergeGroupPROptions(raw.prOptions, expandedGroups, raw.groups ?? {})
             : raw.prOptions;
-        let effectiveSettings = rawRepo.groups?.length
-            ? mergeGroupSettings(raw.settings, rawRepo.groups, raw.groups ?? {})
+        let effectiveSettings = expandedGroups.length
+            ? mergeGroupSettings(raw.settings, expandedGroups, raw.groups ?? {})
             : raw.settings;
         // Phase 2 + 3: Evaluate and merge conditional groups
         if (raw.conditionalGroups?.length) {
-            const effectiveGroups = new Set(rawRepo.groups ?? []);
+            const effectiveGroups = new Set(expandedGroups);
             const merged = mergeConditionalGroups(effectiveRootFiles, effectivePROptions, effectiveSettings, effectiveGroups, raw.conditionalGroups);
             effectiveRootFiles = merged.files;
             effectivePROptions = merged.prOptions;

package/dist/config/types.d.ts

@@ -292,6 +292,7 @@ export interface RawRepoFileOverride {
     deleteOrphaned?: boolean;
 }
 export interface RawGroupConfig {
+    extends?: string | string[];
     files?: Record<string, RawFileConfig | RawRepoFileOverride | false> & {
         inherit?: boolean;
     };

package/dist/config/validator.js

@@ -1,3 +1,4 @@
+import { resolveExtendsChain, expandRepoGroups } from "./extends-resolver.js";
 import { isTextContent, isObjectContent, isStructuredFileExtension, validateFileName, VALID_STRATEGIES, } from "./validators/file-validator.js";
 import { validateRepoSettings } from "./validators/repo-settings-validator.js";
 import { validateRuleset } from "./validators/ruleset-validator.js";
@@ -259,6 +260,71 @@ function validatePrOptions(config) {
         }
     }
 }
+/**
+ * Validates the extends field on a single group definition.
+ * Checks type, self-reference, and that all referenced groups exist.
+ */
+function validateGroupExtends(groupName, extends_, groupNames) {
+    // Type check
+    if (typeof extends_ === "string") {
+        if (extends_.length === 0) {
+            throw new ValidationError(`groups.${groupName}: 'extends' must be a non-empty string or array of strings`);
+        }
+        // Self-reference
+        if (extends_ === groupName) {
+            throw new ValidationError(`groups.${groupName}: extends cannot reference itself`);
+        }
+        // Existence
+        if (!groupNames.has(extends_)) {
+            throw new ValidationError(`groups.${groupName}: extends references undefined group '${extends_}'`);
+        }
+    }
+    else if (Array.isArray(extends_)) {
+        if (extends_.length === 0) {
+            throw new ValidationError(`groups.${groupName}: 'extends' must be a non-empty string or array of strings`);
+        }
+        const seen = new Set();
+        for (const entry of extends_) {
+            if (typeof entry !== "string") {
+                throw new ValidationError(`groups.${groupName}: 'extends' array entries must be strings`);
+            }
+            if (entry.length === 0) {
+                throw new ValidationError(`groups.${groupName}: 'extends' array entries must be non-empty strings`);
+            }
+            if (entry === groupName) {
+                throw new ValidationError(`groups.${groupName}: extends cannot reference itself`);
+            }
+            if (!groupNames.has(entry)) {
+                throw new ValidationError(`groups.${groupName}: extends references undefined group '${entry}'`);
+            }
+            if (seen.has(entry)) {
+                throw new ValidationError(`groups.${groupName}: duplicate '${entry}' in extends`);
+            }
+            seen.add(entry);
+        }
+    }
+    else {
+        throw new ValidationError(`groups.${groupName}: 'extends' must be a non-empty string or array of strings`);
+    }
+}
+/**
+ * Detects circular extends chains across all groups.
+ * Reuses resolveExtendsChain from extends-resolver.ts to avoid
+ * duplicating the chain-walking logic. Converts thrown errors
+ * to ValidationError.
+ */
+function validateNoCircularExtends(groups) {
+    for (const name of Object.keys(groups)) {
+        if (!groups[name].extends)
+            continue;
+        try {
+            resolveExtendsChain(name, groups);
+        }
+        catch (error) {
+            throw new ValidationError(error instanceof Error ? error.message : String(error));
+        }
+    }
+}
 function validateGroups(config) {
     if (config.groups === undefined)
         return;
@@ -266,10 +332,18 @@ function validateGroups(config) {
         throw new ValidationError("groups must be an object");
     }
     const rootCtx = buildRootSettingsContext(config);
+    const groupNames = new Set(Object.keys(config.groups));
     for (const [groupName, group] of Object.entries(config.groups)) {
         if (groupName === "inherit") {
             throw new ValidationError("'inherit' is a reserved key and cannot be used as a group name");
         }
+        if (groupName === "extends") {
+            throw new ValidationError("'extends' is a reserved key and cannot be used as a group name");
+        }
+        // Validate extends field
+        if (group.extends !== undefined) {
+            validateGroupExtends(groupName, group.extends, groupNames);
+        }
         if (group.files) {
             for (const [fileName, fileConfig] of Object.entries(group.files)) {
                 if (fileName === "inherit")
@@ -285,6 +359,8 @@ function validateGroups(config) {
             validateSettings(group.settings, `groups.${groupName}`, rootCtx);
         }
     }
+    // Validate no circular extends after individual validation
+    validateNoCircularExtends(config.groups);
 }
 function validateConditionalGroups(config) {
     if (config.conditionalGroups === undefined)
@@ -422,7 +498,8 @@ function validateRepoFiles(config, repo, index, repoLabel) {
     }
     const knownFiles = new Set(config.files ? Object.keys(config.files) : []);
     if (repo.groups && config.groups) {
-        for (const groupName of repo.groups) {
+        const expandedGroups = expandRepoGroups(repo.groups, config.groups);
+        for (const groupName of expandedGroups) {
             const group = config.groups[groupName];
             if (group?.files) {
                 for (const fn of Object.keys(group.files)) {
@@ -469,7 +546,8 @@ function validateRepoSettingsEntry(config, repo, repoLabel) {
         return;
     const rootCtx = buildRootSettingsContext(config);
     if (repo.groups && config.groups) {
-        for (const groupName of repo.groups) {
+        const expandedGroups = expandRepoGroups(repo.groups, config.groups);
+        for (const groupName of expandedGroups) {
             const group = config.groups[groupName];
             if (group?.settings?.rulesets) {
                 for (const name of Object.keys(group.settings.rulesets)) {

package/dist/output/settings-report.js

@@ -1,5 +1,6 @@
 import chalk from "chalk";
 import { writeGitHubStepSummary } from "./github-summary.js";
+import { formatScalarValue } from "../shared/string-utils.js";
 /**
  * Shared recursive renderer for ruleset config objects.
  * The formatLine callback controls indentation style and coloring:
@@ -127,14 +128,9 @@ export function formatSettingsReportCLI(report) {
     return lines;
 }
 function formatValuePlain(val) {
-    if (val === null)
-        return "null";
-    if (val === undefined)
-        return "undefined";
-    if (typeof val === "string")
-        return `"${val}"`;
-    if (typeof val === "boolean")
-        return val ? "true" : "false";
+    const scalar = formatScalarValue(val);
+    if (scalar !== undefined)
+        return scalar;
     if (typeof val === "object")
         return JSON.stringify(val);
     return String(val);

package/dist/settings/base-processor.js

@@ -1,40 +1,46 @@
 import { isGitHubRepo, getRepoDisplayName } from "../shared/repo-detector.js";
 import { toErrorMessage } from "../shared/type-guards.js";
+/**
+ * Build a base result that satisfies TResult for guard early-returns.
+ * All TResult subtypes only extend BaseProcessorResult with optional fields,
+ * so a base-only object is structurally valid. If adding a new processor
+ * result type, ensure all extension fields are optional.
+ */
+function baseResult(result) {
+    return result;
+}
 /**
  * Common boilerplate for GitHub settings processors: GitHub-only gating,
  * empty settings check, token resolution, and error wrapping.
  */
 export async function withGitHubGuards(repoConfig, repoInfo, options, guards) {
     const repoName = getRepoDisplayName(repoInfo);
-    // Safe cast: all TResult subtypes (RulesetProcessorResult, LabelsProcessorResult,
-    // RepoSettingsProcessorResult) only extend BaseProcessorResult with optional fields.
-    // If adding a new processor result type, ensure all extension fields are optional.
     if (!isGitHubRepo(repoInfo)) {
-        return {
+        return baseResult({
             success: true,
             repoName,
             message: `Skipped: ${repoName} is not a GitHub repository`,
             skipped: true,
-        };
+        });
     }
     if (!guards.hasDesiredSettings(repoConfig)) {
-        return {
+        return baseResult({
             success: true,
             repoName,
             message: guards.emptySettingsMessage,
             skipped: true,
-        };
+        });
     }
     try {
         return await guards.applySettings(repoInfo, repoConfig, options, options.token, repoName);
     }
     catch (error) {
         const message = toErrorMessage(error);
-        return {
+        return baseResult({
             success: false,
             repoName,
             message: `Failed: ${message}`,
-        };
+        });
     }
 }
 /** Type predicate that narrows entries with an active (non-"unchanged") action. */

package/dist/settings/labels/diff.d.ts

@@ -29,6 +29,6 @@ export interface LabelChange {
  * @param deleteOrphaned - If true, delete current labels not in desired config
  * @param noDelete - If true, skip delete operations
  * @returns Array of changes to apply
- * @throws Error if rename collisions are detected
+ * @throws ValidationError if rename collisions are detected
  */
 export declare function diffLabels(current: GitHubLabel[], desired: Record<string, Label>, deleteOrphaned: boolean, noDelete: boolean): LabelChange[];

package/dist/settings/labels/diff.js

@@ -15,7 +15,7 @@ import { ValidationError } from "../../shared/errors.js";
  * @param deleteOrphaned - If true, delete current labels not in desired config
  * @param noDelete - If true, skip delete operations
  * @returns Array of changes to apply
- * @throws Error if rename collisions are detected
+ * @throws ValidationError if rename collisions are detected
  */
 export function diffLabels(current, desired, deleteOrphaned, noDelete) {
     const changes = [];

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

@@ -1,17 +1,10 @@
 import chalk from "chalk";
+import { formatScalarValue } from "../../shared/string-utils.js";
 /**
  * Format a value for display.
  */
 function formatValue(val) {
-    if (val === null)
-        return "null";
-    if (val === undefined)
-        return "undefined";
-    if (typeof val === "string")
-        return `"${val}"`;
-    if (typeof val === "boolean")
-        return val ? "true" : "false";
-    return String(val);
+    return formatScalarValue(val) ?? String(val);
 }
 /**
  * Get warning message for a property change.

package/dist/settings/rulesets/formatter.js

@@ -1,5 +1,6 @@
 import chalk from "chalk";
 import { projectToDesiredShape, normalizeRuleset, } from "./diff.js";
+import { formatScalarValue } from "../../shared/string-utils.js";
 import { computePropertyDiffs, } from "./diff-algorithm.js";
 import { isPlainObject } from "../../shared/type-guards.js";
 /**
@@ -39,12 +40,9 @@ function buildTree(diffs) {
  * Format a value for inline display (scalars and simple arrays only).
  */
 function formatValue(val) {
-    if (val === null)
-        return "null";
-    if (val === undefined)
-        return "undefined";
-    if (typeof val === "string")
-        return `"${val}"`;
+    const scalar = formatScalarValue(val);
+    if (scalar !== undefined)
+        return scalar;
     if (Array.isArray(val)) {
         if (val.every((v) => typeof v !== "object" || v === null)) {
             return `[${val.map(formatValue).join(", ")}]`;
@@ -224,10 +222,10 @@ export function formatRulesetPlan(changes) {
     for (const c of changes) {
         grouped[c.action].push(c);
     }
+    if (grouped.create.length > 0) {
+        lines.push(chalk.bold("  Create:"));
+    }
     for (const change of grouped.create) {
-        if (grouped.create.indexOf(change) === 0) {
-            lines.push(chalk.bold("  Create:"));
-        }
         lines.push(chalk.green(`    + ruleset "${change.name}"`));
         if (change.desired) {
             lines.push(...formatFullConfig(change.desired, 2));
@@ -243,10 +241,10 @@ export function formatRulesetPlan(changes) {
         });
         lines.push("");
     }
+    if (grouped.update.length > 0) {
+        lines.push(chalk.bold("  Update:"));
+    }
     for (const change of grouped.update) {
-        if (grouped.update.indexOf(change) === 0) {
-            lines.push(chalk.bold("  Update:"));
-        }
         lines.push(chalk.yellow(`    ~ ruleset "${change.name}"`));
         if (change.current && change.desired) {
             const currentNorm = normalizeRuleset(change.current);

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

@@ -1,6 +1,6 @@
 export declare function sanitizeBranchName(fileName: string): string;
 /**
  * Validates a user-provided branch name against git's naming rules.
- * @throws Error if the branch name is invalid
+ * @throws ValidationError if the branch name is invalid
  */
 export declare function validateBranchName(branchName: string): void;

package/dist/shared/branch-utils.js

@@ -9,7 +9,7 @@ export function sanitizeBranchName(fileName) {
 }
 /**
  * Validates a user-provided branch name against git's naming rules.
- * @throws Error if the branch name is invalid
+ * @throws ValidationError if the branch name is invalid
  */
 export function validateBranchName(branchName) {
     if (!branchName || branchName.trim() === "") {

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

@@ -110,7 +110,7 @@ export class GhApiClient {
         this.retries = retries;
         this.cwd = cwd;
     }
-    async call(method, endpoint, params) {
+    call(method, endpoint, params) {
         return ghApiCall(method, endpoint, {
             executor: this.executor,
             retries: this.retries,

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

@@ -2,3 +2,9 @@
  * Convert a camelCase string to snake_case.
  */
 export declare function camelToSnake(str: string): string;
+/**
+ * Format a scalar value for display: null, undefined, string, boolean.
+ * Returns undefined for non-scalar types (arrays, objects) so callers
+ * can apply domain-specific formatting.
+ */
+export declare function formatScalarValue(val: unknown): string | undefined;

package/dist/shared/string-utils.js

@@ -4,3 +4,19 @@
 export function camelToSnake(str) {
     return str.replace(/([A-Z])/g, "_$1").toLowerCase();
 }
+/**
+ * Format a scalar value for display: null, undefined, string, boolean.
+ * Returns undefined for non-scalar types (arrays, objects) so callers
+ * can apply domain-specific formatting.
+ */
+export function formatScalarValue(val) {
+    if (val === null)
+        return "null";
+    if (val === undefined)
+        return "undefined";
+    if (typeof val === "string")
+        return `"${val}"`;
+    if (typeof val === "boolean")
+        return val ? "true" : "false";
+    return undefined;
+}

package/dist/sync/auth-options-builder.d.ts

@@ -1,5 +1,5 @@
 import { RepoInfo } from "../shared/repo-detector.js";
-import { GitHubAppTokenManager } from "../vcs/github-app-token-manager.js";
+import type { GitHubAppTokenManager } from "../vcs/index.js";
 import type { AuthResult, IAuthOptionsBuilder } from "./types.js";
 import type { ILogger } from "../shared/logger.js";
 export declare class AuthOptionsBuilder implements IAuthOptionsBuilder {

package/dist/sync/repository-processor.d.ts

@@ -1,7 +1,7 @@
 import type { RepoConfig } from "../config/index.js";
 import type { RepoInfo } from "../shared/repo-detector.js";
 import type { ILogger } from "../shared/logger.js";
-import type { GitHubAppTokenManager } from "../vcs/github-app-token-manager.js";
+import type { GitHubAppTokenManager } from "../vcs/index.js";
 import type { IFileWriter, IManifestManager, IBranchManager, IAuthOptionsBuilder, IRepositorySession, ICommitPushManager, IFileSyncOrchestrator, IPRMergeHandler, ISyncWorkflow, IRepositoryProcessor, GitOpsFactory, ProcessorOptions, ProcessorResult } from "./types.js";
 /**
  * Thin facade that delegates to SyncWorkflow with FileSyncStrategy.

package/dist/vcs/git-ops.d.ts

@@ -18,7 +18,7 @@ export declare class GitOps implements ILocalGitOps {
     /**
      * Validates that a file path doesn't escape the workspace directory.
      * @returns The resolved absolute file path
-     * @throws Error if path traversal is detected
+     * @throws ValidationError if path traversal is detected
      */
     private validatePath;
     cleanWorkspace(): void;
@@ -70,7 +70,7 @@ export declare class GitOps implements ILocalGitOps {
     /**
      * Stage all changes and commit with the given message.
      * Uses --no-verify to skip pre-commit hooks (config sync should always succeed).
-     * @returns true if a commit was made, false if there were no staged changes
+     * @returns true if a commit was made (or would be made in dry-run mode), false if there were no staged changes
      */
     commit(message: string): Promise<boolean>;
     /**

package/dist/vcs/git-ops.js

@@ -20,7 +20,7 @@ export class GitOps {
     /**
      * Validates that a file path doesn't escape the workspace directory.
      * @returns The resolved absolute file path
-     * @throws Error if path traversal is detected
+     * @throws ValidationError if path traversal is detected
      */
     validatePath(fileName) {
         const filePath = join(this._workDir, fileName);
@@ -209,7 +209,7 @@ export class GitOps {
     /**
      * Stage all changes and commit with the given message.
      * Uses --no-verify to skip pre-commit hooks (config sync should always succeed).
-     * @returns true if a commit was made, false if there were no staged changes
+     * @returns true if a commit was made (or would be made in dry-run mode), false if there were no staged changes
      */
     async commit(message) {
         if (this.dryRun) {

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

@@ -43,7 +43,8 @@ export declare class GraphQLCommitStrategy implements ICommitStrategy {
      * 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
+     * @throws ValidationError if repo is not GitHub or payload exceeds 50MB
+     * @throws GraphQLApiError if the API call fails
      */
     commit(options: CommitOptions): Promise<CommitResult>;
     /**

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

@@ -70,7 +70,8 @@ export class GraphQLCommitStrategy {
      * 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
+     * @throws ValidationError if repo is not GitHub or payload exceeds 50MB
+     * @throws GraphQLApiError if the API call fails
      */
     async commit(options) {
         const { repoInfo, branchName, message, fileChanges, workDir, retries = 3, token, } = options;

package/dist/vcs/index.d.ts

@@ -1,5 +1,6 @@
 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 type { GitHubAppTokenManager } from "./github-app-token-manager.js";
 export { createPRStrategy } from "./pr-strategy-factory.js";
 export { createPR, mergePR } from "./pr-creator.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "5.2.0",
+  "version": "5.3.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",