@aspruyt/xfg 3.0.0 → 3.1.0

package/README.md

@@ -8,7 +8,7 @@
 [![docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://anthony-spruyt.github.io/xfg/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-A CLI tool that syncs JSON, JSON5, YAML, or text configuration files across multiple GitHub, Azure DevOps, and GitLab repositories. By default, changes are made via pull requests, but you can also push directly to the default branch.
+A CLI tool for repository-as-code. Sync files and manage settings across GitHub, Azure DevOps, and GitLab.
 
 **[Full Documentation](https://anthony-spruyt.github.io/xfg/)**
 
@@ -29,8 +29,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: anthony-spruyt/xfg@v1
+      - uses: anthony-spruyt/xfg@v3
         with:
+          command: sync
           config: ./sync-config.yaml
           github-token: ${{ secrets.GH_PAT }} # PAT with repo scope for cross-repo access
 ```
@@ -44,31 +45,46 @@ npm install -g @aspruyt/xfg
 # Authenticate (GitHub)
 gh auth login
 
-# Run
-xfg --config ./config.yaml
+# Sync files across repos
+xfg sync --config ./config.yaml
+
+# Apply repository settings
+xfg settings --config ./config.yaml
 ```
 
 ### Example Config
 
 ```yaml
 # sync-config.yaml
-id: my-org-prettier-config
+id: my-org-config
 files:
   .prettierrc.json:
     content:
       semi: false
       singleQuote: true
       tabWidth: 2
-      trailingComma: es5
+
+settings:
+  rulesets:
+    main-protection:
+      target: branch
+      enforcement: active
+      conditions:
+        refName:
+          include: ["refs/heads/main"]
+          exclude: []
+      rules:
+        - type: pull_request
+          parameters:
+            requiredApprovingReviewCount: 1
 
 repos:
   - git:
       - git@github.com:your-org/frontend-app.git
       - git@github.com:your-org/backend-api.git
-      - git@github.com:your-org/shared-lib.git
 ```
 
-**Result:** PRs are created in all three repos with identical `.prettierrc.json` files.
+**Result:** PRs are created with `.prettierrc.json` files, and repos get branch protection rules.
 
 ## Documentation
 

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { program } from "./index.js";
+// Handle backwards compatibility: if no subcommand is provided, default to sync
+// This maintains compatibility with existing usage like `xfg -c config.yaml`
+const args = process.argv.slice(2);
+const subcommands = ["sync", "settings", "help"];
+const versionFlags = ["-V", "--version"];
+// Check if the first argument is a subcommand or version flag
+const firstArg = args[0];
+const isSubcommand = firstArg && subcommands.includes(firstArg);
+const isVersionFlag = firstArg && versionFlags.includes(firstArg);
+if (isSubcommand || isVersionFlag) {
+    // Explicit subcommand or version flag - parse normally
+    program.parse();
+}
+else {
+    // No subcommand - prepend 'sync' for backwards compatibility
+    // This handles: `xfg -c config.yaml`, `xfg --help`, `xfg` (no args)
+    program.parse(["node", "xfg", "sync", ...args]);
+}

package/dist/config-normalizer.d.ts

@@ -1,4 +1,9 @@
-import type { RawConfig, Config } from "./config.js";
+import type { RawConfig, Config, RepoSettings, RawRepoSettings } from "./config.js";
+/**
+ * Merges settings: per-repo settings deep merge with root settings.
+ * Returns undefined if no settings are defined.
+ */
+export declare function mergeSettings(root: RawRepoSettings | undefined, perRepo: RawRepoSettings | undefined): RepoSettings | undefined;
 /**
  * Normalizes raw config into expanded, merged config.
  * Pipeline: expand git arrays -> merge content -> interpolate env vars

package/dist/config-normalizer.js

@@ -36,13 +36,54 @@ function mergePROptions(global, perRepo) {
         result.bypassReason = bypassReason;
     return Object.keys(result).length > 0 ? result : undefined;
 }
+/**
+ * Deep merges two rulesets: per-repo values override root values.
+ */
+function mergeRuleset(root, perRepo) {
+    if (!root)
+        return structuredClone(perRepo ?? {});
+    if (!perRepo)
+        return structuredClone(root);
+    // Deep merge using the existing merge utility with replace strategy
+    const ctx = createMergeContext("replace");
+    const merged = deepMerge(structuredClone(root), perRepo, ctx);
+    return merged;
+}
+/**
+ * Merges settings: per-repo settings deep merge with root settings.
+ * Returns undefined if no settings are defined.
+ */
+export function mergeSettings(root, perRepo) {
+    if (!root && !perRepo)
+        return undefined;
+    const result = {};
+    // Merge rulesets by name - each ruleset is deep merged
+    const rootRulesets = root?.rulesets ?? {};
+    const repoRulesets = perRepo?.rulesets ?? {};
+    const allRulesetNames = new Set([
+        ...Object.keys(rootRulesets),
+        ...Object.keys(repoRulesets),
+    ]);
+    if (allRulesetNames.size > 0) {
+        result.rulesets = {};
+        for (const name of allRulesetNames) {
+            result.rulesets[name] = mergeRuleset(rootRulesets[name], repoRulesets[name]);
+        }
+    }
+    // deleteOrphaned: per-repo overrides root
+    const deleteOrphaned = perRepo?.deleteOrphaned ?? root?.deleteOrphaned;
+    if (deleteOrphaned !== undefined) {
+        result.deleteOrphaned = deleteOrphaned;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
 /**
  * Normalizes raw config into expanded, merged config.
  * Pipeline: expand git arrays -> merge content -> interpolate env vars
  */
 export function normalizeConfig(raw) {
     const expandedRepos = [];
-    const fileNames = Object.keys(raw.files);
+    const fileNames = raw.files ? Object.keys(raw.files) : [];
     for (const rawRepo of raw.repos) {
         // Step 1: Expand git arrays
         const gitUrls = Array.isArray(rawRepo.git) ? rawRepo.git : [rawRepo.git];
@@ -139,10 +180,13 @@ export function normalizeConfig(raw) {
             }
             // Merge PR options: per-repo overrides global
             const prOptions = mergePROptions(raw.prOptions, rawRepo.prOptions);
+            // Merge settings: per-repo deep merges with root settings
+            const settings = mergeSettings(raw.settings, rawRepo.settings);
             expandedRepos.push({
                 git: gitUrl,
                 files,
                 prOptions,
+                settings,
             });
         }
     }
@@ -152,5 +196,6 @@ export function normalizeConfig(raw) {
         prTemplate: raw.prTemplate,
         githubHosts: raw.githubHosts,
         deleteOrphaned: raw.deleteOrphaned,
+        settings: raw.settings,
     };
 }

package/dist/config-validator.d.ts

@@ -1,6 +1,25 @@
-import type { RawConfig } from "./config.js";
+import type { RawConfig, RawRepoSettings } from "./config.js";
 /**
  * Validates raw config structure before normalization.
  * @throws Error if validation fails
  */
 export declare function validateRawConfig(config: RawConfig): void;
+/**
+ * Validates settings object containing rulesets.
+ */
+export declare function validateSettings(settings: unknown, context: string): void;
+/**
+ * Validates that config is suitable for the sync command.
+ * @throws Error if files section is missing or empty
+ */
+export declare function validateForSync(config: RawConfig): void;
+/**
+ * Checks if settings contain actionable configuration.
+ * Currently only rulesets, but extensible for future settings features.
+ */
+export declare function hasActionableSettings(settings: RawRepoSettings | undefined): boolean;
+/**
+ * Validates that config is suitable for the settings command.
+ * @throws Error if no settings are defined or no actionable settings exist
+ */
+export declare function validateForSettings(config: RawConfig): void;

package/dist/config-validator.js

@@ -39,13 +39,16 @@ export function validateRawConfig(config) {
     if (config.id.length > CONFIG_ID_MAX_LENGTH) {
         throw new Error(`Config 'id' exceeds maximum length of ${CONFIG_ID_MAX_LENGTH} characters`);
     }
-    if (!config.files || typeof config.files !== "object") {
-        throw new Error("Config missing required field: files (must be an object)");
-    }
-    const fileNames = Object.keys(config.files);
-    if (fileNames.length === 0) {
-        throw new Error("Config files object cannot be empty");
+    // Validate at least one of files or settings exists
+    const hasFiles = config.files &&
+        typeof config.files === "object" &&
+        Object.keys(config.files).length > 0;
+    const hasSettings = config.settings && typeof config.settings === "object";
+    if (!hasFiles && !hasSettings) {
+        throw new Error("Config requires at least one of: 'files' or 'settings'. " +
+            "Use 'files' to sync configuration files, or 'settings' to manage repository settings.");
     }
+    const fileNames = hasFiles ? Object.keys(config.files) : [];
     // Validate each file definition
     for (const fileName of fileNames) {
         validateFileName(fileName);
@@ -121,6 +124,10 @@ export function validateRawConfig(config) {
     if (!config.repos || !Array.isArray(config.repos)) {
         throw new Error("Config missing required field: repos (must be an array)");
     }
+    // Validate root settings
+    if (config.settings !== undefined) {
+        validateSettings(config.settings, "Root");
+    }
     // Validate githubHosts if provided
     if (config.githubHosts !== undefined) {
         if (!Array.isArray(config.githubHosts) ||
@@ -155,7 +162,7 @@ export function validateRawConfig(config) {
             }
             for (const fileName of Object.keys(repo.files)) {
                 // Ensure the file is defined at root level
-                if (!config.files[fileName]) {
+                if (!config.files || !config.files[fileName]) {
                     throw new Error(`Repo at index ${i} references undefined file '${fileName}'. File must be defined in root 'files' object.`);
                 }
                 const fileOverride = repo.files[fileName];
@@ -224,6 +231,10 @@ export function validateRawConfig(config) {
                 }
             }
         }
+        // Validate per-repo settings
+        if (repo.settings !== undefined) {
+            validateSettings(repo.settings, `Repo ${getGitDisplayName(repo.git)}`);
+        }
     }
 }
 /**
@@ -248,3 +259,285 @@ function getGitDisplayName(git) {
     }
     return git;
 }
+// =============================================================================
+// Ruleset Validation
+// =============================================================================
+const VALID_RULESET_TARGETS = ["branch", "tag"];
+const VALID_ENFORCEMENT_LEVELS = ["active", "disabled", "evaluate"];
+const VALID_ACTOR_TYPES = ["Team", "User", "Integration"];
+const VALID_BYPASS_MODES = ["always", "pull_request"];
+const VALID_PATTERN_OPERATORS = [
+    "starts_with",
+    "ends_with",
+    "contains",
+    "regex",
+];
+const VALID_MERGE_METHODS = ["merge", "squash", "rebase"];
+const VALID_ALERTS_THRESHOLDS = [
+    "none",
+    "errors",
+    "errors_and_warnings",
+    "all",
+];
+const VALID_SECURITY_THRESHOLDS = [
+    "none",
+    "critical",
+    "high_or_higher",
+    "medium_or_higher",
+    "all",
+];
+const VALID_RULE_TYPES = [
+    "pull_request",
+    "required_status_checks",
+    "required_signatures",
+    "required_linear_history",
+    "non_fast_forward",
+    "creation",
+    "update",
+    "deletion",
+    "required_deployments",
+    "code_scanning",
+    "code_quality",
+    "workflows",
+    "commit_author_email_pattern",
+    "commit_message_pattern",
+    "committer_email_pattern",
+    "branch_name_pattern",
+    "tag_name_pattern",
+    "file_path_restriction",
+    "file_extension_restriction",
+    "max_file_path_length",
+    "max_file_size",
+];
+/**
+ * Validates a single ruleset rule.
+ */
+function validateRule(rule, context) {
+    if (typeof rule !== "object" || rule === null || Array.isArray(rule)) {
+        throw new Error(`${context}: rule must be an object`);
+    }
+    const r = rule;
+    if (!r.type || typeof r.type !== "string") {
+        throw new Error(`${context}: rule must have a 'type' string field`);
+    }
+    if (!VALID_RULE_TYPES.includes(r.type)) {
+        throw new Error(`${context}: invalid rule type '${r.type}'. Must be one of: ${VALID_RULE_TYPES.join(", ")}`);
+    }
+    // Validate parameters based on rule type
+    if (r.parameters !== undefined) {
+        if (typeof r.parameters !== "object" ||
+            r.parameters === null ||
+            Array.isArray(r.parameters)) {
+            throw new Error(`${context}: rule parameters must be an object`);
+        }
+        const params = r.parameters;
+        // Validate pattern rule parameters
+        if (r.type.toString().endsWith("_pattern")) {
+            if (params.operator !== undefined &&
+                !VALID_PATTERN_OPERATORS.includes(params.operator)) {
+                throw new Error(`${context}: pattern rule operator must be one of: ${VALID_PATTERN_OPERATORS.join(", ")}`);
+            }
+            if (params.pattern !== undefined && typeof params.pattern !== "string") {
+                throw new Error(`${context}: pattern rule pattern must be a string`);
+            }
+        }
+        // Validate pull_request parameters
+        if (r.type === "pull_request") {
+            if (params.requiredApprovingReviewCount !== undefined) {
+                const count = params.requiredApprovingReviewCount;
+                if (typeof count !== "number" ||
+                    !Number.isInteger(count) ||
+                    count < 0 ||
+                    count > 10) {
+                    throw new Error(`${context}: requiredApprovingReviewCount must be an integer between 0 and 10`);
+                }
+            }
+            if (params.allowedMergeMethods !== undefined) {
+                if (!Array.isArray(params.allowedMergeMethods)) {
+                    throw new Error(`${context}: allowedMergeMethods must be an array`);
+                }
+                for (const method of params.allowedMergeMethods) {
+                    if (!VALID_MERGE_METHODS.includes(method)) {
+                        throw new Error(`${context}: allowedMergeMethods values must be one of: ${VALID_MERGE_METHODS.join(", ")}`);
+                    }
+                }
+            }
+        }
+        // Validate code_scanning parameters
+        if (r.type === "code_scanning" && params.codeScanningTools !== undefined) {
+            if (!Array.isArray(params.codeScanningTools)) {
+                throw new Error(`${context}: codeScanningTools must be an array`);
+            }
+            for (const tool of params.codeScanningTools) {
+                if (typeof tool !== "object" || tool === null) {
+                    throw new Error(`${context}: each codeScanningTool must be an object`);
+                }
+                const t = tool;
+                if (t.alertsThreshold !== undefined &&
+                    !VALID_ALERTS_THRESHOLDS.includes(t.alertsThreshold)) {
+                    throw new Error(`${context}: alertsThreshold must be one of: ${VALID_ALERTS_THRESHOLDS.join(", ")}`);
+                }
+                if (t.securityAlertsThreshold !== undefined &&
+                    !VALID_SECURITY_THRESHOLDS.includes(t.securityAlertsThreshold)) {
+                    throw new Error(`${context}: securityAlertsThreshold must be one of: ${VALID_SECURITY_THRESHOLDS.join(", ")}`);
+                }
+            }
+        }
+    }
+}
+/**
+ * Validates a single ruleset.
+ */
+function validateRuleset(ruleset, name, context) {
+    if (typeof ruleset !== "object" ||
+        ruleset === null ||
+        Array.isArray(ruleset)) {
+        throw new Error(`${context}: ruleset '${name}' must be an object`);
+    }
+    const rs = ruleset;
+    if (rs.target !== undefined &&
+        !VALID_RULESET_TARGETS.includes(rs.target)) {
+        throw new Error(`${context}: ruleset '${name}' target must be one of: ${VALID_RULESET_TARGETS.join(", ")}`);
+    }
+    if (rs.enforcement !== undefined &&
+        !VALID_ENFORCEMENT_LEVELS.includes(rs.enforcement)) {
+        throw new Error(`${context}: ruleset '${name}' enforcement must be one of: ${VALID_ENFORCEMENT_LEVELS.join(", ")}`);
+    }
+    // Validate bypassActors
+    if (rs.bypassActors !== undefined) {
+        if (!Array.isArray(rs.bypassActors)) {
+            throw new Error(`${context}: ruleset '${name}' bypassActors must be an array`);
+        }
+        for (let i = 0; i < rs.bypassActors.length; i++) {
+            const actor = rs.bypassActors[i];
+            if (typeof actor !== "object" || actor === null) {
+                throw new Error(`${context}: ruleset '${name}' bypassActors[${i}] must be an object`);
+            }
+            if (typeof actor.actorId !== "number") {
+                throw new Error(`${context}: ruleset '${name}' bypassActors[${i}].actorId must be a number`);
+            }
+            if (!VALID_ACTOR_TYPES.includes(actor.actorType)) {
+                throw new Error(`${context}: ruleset '${name}' bypassActors[${i}].actorType must be one of: ${VALID_ACTOR_TYPES.join(", ")}`);
+            }
+            if (actor.bypassMode !== undefined &&
+                !VALID_BYPASS_MODES.includes(actor.bypassMode)) {
+                throw new Error(`${context}: ruleset '${name}' bypassActors[${i}].bypassMode must be one of: ${VALID_BYPASS_MODES.join(", ")}`);
+            }
+        }
+    }
+    // Validate conditions
+    if (rs.conditions !== undefined) {
+        if (typeof rs.conditions !== "object" ||
+            rs.conditions === null ||
+            Array.isArray(rs.conditions)) {
+            throw new Error(`${context}: ruleset '${name}' conditions must be an object`);
+        }
+        const conditions = rs.conditions;
+        if (conditions.refName !== undefined) {
+            const refName = conditions.refName;
+            if (typeof refName !== "object" ||
+                refName === null ||
+                Array.isArray(refName)) {
+                throw new Error(`${context}: ruleset '${name}' conditions.refName must be an object`);
+            }
+            if (refName.include !== undefined &&
+                (!Array.isArray(refName.include) ||
+                    !refName.include.every((s) => typeof s === "string"))) {
+                throw new Error(`${context}: ruleset '${name}' conditions.refName.include must be an array of strings`);
+            }
+            if (refName.exclude !== undefined &&
+                (!Array.isArray(refName.exclude) ||
+                    !refName.exclude.every((s) => typeof s === "string"))) {
+                throw new Error(`${context}: ruleset '${name}' conditions.refName.exclude must be an array of strings`);
+            }
+        }
+    }
+    // Validate rules array
+    if (rs.rules !== undefined) {
+        if (!Array.isArray(rs.rules)) {
+            throw new Error(`${context}: ruleset '${name}' rules must be an array`);
+        }
+        for (let i = 0; i < rs.rules.length; i++) {
+            validateRule(rs.rules[i], `${context}: ruleset '${name}' rules[${i}]`);
+        }
+    }
+}
+/**
+ * Validates settings object containing rulesets.
+ */
+export function validateSettings(settings, context) {
+    if (typeof settings !== "object" ||
+        settings === null ||
+        Array.isArray(settings)) {
+        throw new Error(`${context}: settings must be an object`);
+    }
+    const s = settings;
+    if (s.rulesets !== undefined) {
+        if (typeof s.rulesets !== "object" ||
+            s.rulesets === null ||
+            Array.isArray(s.rulesets)) {
+            throw new Error(`${context}: rulesets must be an object`);
+        }
+        const rulesets = s.rulesets;
+        for (const [name, ruleset] of Object.entries(rulesets)) {
+            validateRuleset(ruleset, name, context);
+        }
+    }
+    if (s.deleteOrphaned !== undefined && typeof s.deleteOrphaned !== "boolean") {
+        throw new Error(`${context}: settings.deleteOrphaned must be a boolean`);
+    }
+}
+// =============================================================================
+// Command-Specific Validators
+// =============================================================================
+/**
+ * Validates that config is suitable for the sync command.
+ * @throws Error if files section is missing or empty
+ */
+export function validateForSync(config) {
+    if (!config.files) {
+        throw new Error("The 'sync' command requires a 'files' section with at least one file defined. " +
+            "To manage repository settings instead, use 'xfg settings'.");
+    }
+    const fileNames = Object.keys(config.files);
+    if (fileNames.length === 0) {
+        throw new Error("The 'sync' command requires a 'files' section with at least one file defined. " +
+            "To manage repository settings instead, use 'xfg settings'.");
+    }
+}
+/**
+ * Checks if settings contain actionable configuration.
+ * Currently only rulesets, but extensible for future settings features.
+ */
+export function hasActionableSettings(settings) {
+    if (!settings)
+        return false;
+    // Check for rulesets
+    if (settings.rulesets && Object.keys(settings.rulesets).length > 0) {
+        return true;
+    }
+    // Future: check for repoConfig, creation, etc.
+    // if (settings.repoConfig) return true;
+    return false;
+}
+/**
+ * Validates that config is suitable for the settings command.
+ * @throws Error if no settings are defined or no actionable settings exist
+ */
+export function validateForSettings(config) {
+    // Check if settings exist at root or in any repo
+    const hasRootSettings = config.settings !== undefined;
+    const hasRepoSettings = config.repos.some((repo) => repo.settings !== undefined);
+    if (!hasRootSettings && !hasRepoSettings) {
+        throw new Error("The 'settings' command requires a 'settings' section at root level or " +
+            "in at least one repo. To sync files instead, use 'xfg sync'.");
+    }
+    // Check if there's at least one actionable setting
+    const rootActionable = hasActionableSettings(config.settings);
+    const repoActionable = config.repos.some((repo) => hasActionableSettings(repo.settings));
+    if (!rootActionable && !repoActionable) {
+        throw new Error("No actionable settings configured. Currently supported: rulesets. " +
+            "To sync files instead, use 'xfg sync'. " +
+            "See docs: https://anthony-spruyt.github.io/xfg/settings");
+    }
+}