@aspruyt/xfg 1.0.0

package/dist/index.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+import { program } from "commander";
+import { resolve, join, dirname } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "./config.js";
+// Get version from package.json
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+import { parseGitUrl, getRepoDisplayName } from "./repo-detector.js";
+import { sanitizeBranchName, validateBranchName } from "./git-ops.js";
+import { logger } from "./logger.js";
+import { generateWorkspaceName } from "./workspace-utils.js";
+import { RepositoryProcessor, } from "./repository-processor.js";
+/**
+ * Default factory that creates a real RepositoryProcessor.
+ */
+export const defaultProcessorFactory = () => new RepositoryProcessor();
+program
+    .name("xfg")
+    .description("Sync JSON configuration files across multiple repositories")
+    .version(packageJson.version)
+    .requiredOption("-c, --config <path>", "Path to YAML config file")
+    .option("-d, --dry-run", "Show what would be done without making changes")
+    .option("-w, --work-dir <path>", "Temporary directory for cloning", "./tmp")
+    .option("-r, --retries <number>", "Number of retries for network operations (0 to disable)", (v) => parseInt(v, 10), 3)
+    .option("-b, --branch <name>", "Override the branch name (default: chore/sync-{filename} or chore/sync-config)")
+    .option("-m, --merge <mode>", "PR merge mode: manual, auto (default, merge when checks pass), force (bypass requirements)", (value) => {
+    const valid = ["manual", "auto", "force"];
+    if (!valid.includes(value)) {
+        throw new Error(`Invalid merge mode: ${value}. Valid: ${valid.join(", ")}`);
+    }
+    return value;
+})
+    .option("--merge-strategy <strategy>", "Merge strategy: merge, squash (default), rebase", (value) => {
+    const valid = ["merge", "squash", "rebase"];
+    if (!valid.includes(value)) {
+        throw new Error(`Invalid merge strategy: ${value}. Valid: ${valid.join(", ")}`);
+    }
+    return value;
+})
+    .option("--delete-branch", "Delete source branch after merge")
+    .parse();
+const options = program.opts();
+/**
+ * Get unique file names from all repos in the config
+ */
+function getUniqueFileNames(config) {
+    const fileNames = new Set();
+    for (const repo of config.repos) {
+        for (const file of repo.files) {
+            fileNames.add(file.fileName);
+        }
+    }
+    return Array.from(fileNames);
+}
+/**
+ * Generate default branch name based on files being synced
+ */
+function generateBranchName(fileNames) {
+    if (fileNames.length === 1) {
+        return `chore/sync-${sanitizeBranchName(fileNames[0])}`;
+    }
+    return "chore/sync-config";
+}
+/**
+ * Format file names for display
+ */
+function formatFileNames(fileNames) {
+    if (fileNames.length === 1) {
+        return fileNames[0];
+    }
+    if (fileNames.length <= 3) {
+        return fileNames.join(", ");
+    }
+    return `${fileNames.length} files`;
+}
+async function main() {
+    const configPath = resolve(options.config);
+    if (!existsSync(configPath)) {
+        console.error(`Config file not found: ${configPath}`);
+        process.exit(1);
+    }
+    console.log(`Loading config from: ${configPath}`);
+    if (options.dryRun) {
+        console.log("Running in DRY RUN mode - no changes will be made\n");
+    }
+    const config = loadConfig(configPath);
+    const fileNames = getUniqueFileNames(config);
+    let branchName;
+    if (options.branch) {
+        validateBranchName(options.branch);
+        branchName = options.branch;
+    }
+    else {
+        branchName = generateBranchName(fileNames);
+    }
+    logger.setTotal(config.repos.length);
+    console.log(`Found ${config.repos.length} repositories to process`);
+    console.log(`Target files: ${formatFileNames(fileNames)}`);
+    console.log(`Branch: ${branchName}\n`);
+    const processor = defaultProcessorFactory();
+    for (let i = 0; i < config.repos.length; i++) {
+        const repoConfig = config.repos[i];
+        // Apply CLI merge overrides to repo config
+        if (options.merge || options.mergeStrategy || options.deleteBranch) {
+            repoConfig.prOptions = {
+                ...repoConfig.prOptions,
+                merge: options.merge ?? repoConfig.prOptions?.merge,
+                mergeStrategy: options.mergeStrategy ?? repoConfig.prOptions?.mergeStrategy,
+                deleteBranch: options.deleteBranch ?? repoConfig.prOptions?.deleteBranch,
+            };
+        }
+        const current = i + 1;
+        let repoInfo;
+        try {
+            repoInfo = parseGitUrl(repoConfig.git);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error(current, repoConfig.git, message);
+            continue;
+        }
+        const repoName = getRepoDisplayName(repoInfo);
+        const workDir = resolve(join(options.workDir ?? "./tmp", generateWorkspaceName(i)));
+        try {
+            logger.progress(current, repoName, "Processing...");
+            const result = await processor.process(repoConfig, repoInfo, {
+                branchName,
+                workDir,
+                dryRun: options.dryRun,
+                retries: options.retries,
+            });
+            if (result.skipped) {
+                logger.skip(current, repoName, result.message);
+            }
+            else if (result.success) {
+                let message = result.prUrl ? `PR: ${result.prUrl}` : result.message;
+                if (result.mergeResult) {
+                    if (result.mergeResult.merged) {
+                        message += " (merged)";
+                    }
+                    else if (result.mergeResult.autoMergeEnabled) {
+                        message += " (auto-merge enabled)";
+                    }
+                }
+                logger.success(current, repoName, message);
+            }
+            else {
+                logger.error(current, repoName, result.message);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error(current, repoName, message);
+        }
+    }
+    logger.summary();
+    if (logger.hasFailures()) {
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/logger.d.ts

@@ -0,0 +1,21 @@
+export interface ILogger {
+    info(message: string): void;
+}
+export interface LoggerStats {
+    total: number;
+    succeeded: number;
+    failed: number;
+    skipped: number;
+}
+export declare class Logger {
+    private stats;
+    setTotal(total: number): void;
+    progress(current: number, repoName: string, message: string): void;
+    info(message: string): void;
+    success(current: number, repoName: string, message: string): void;
+    skip(current: number, repoName: string, reason: string): void;
+    error(current: number, repoName: string, error: string): void;
+    summary(): void;
+    hasFailures(): boolean;
+}
+export declare const logger: Logger;

package/dist/logger.js

@@ -0,0 +1,46 @@
+import chalk from "chalk";
+export class Logger {
+    stats = {
+        total: 0,
+        succeeded: 0,
+        failed: 0,
+        skipped: 0,
+    };
+    setTotal(total) {
+        this.stats.total = total;
+    }
+    progress(current, repoName, message) {
+        console.log(chalk.blue(`[${current}/${this.stats.total}]`) +
+            ` ${repoName}: ${message}`);
+    }
+    info(message) {
+        console.log(chalk.gray(`    ${message}`));
+    }
+    success(current, repoName, message) {
+        this.stats.succeeded++;
+        console.log(chalk.green(`[${current}/${this.stats.total}] ✓`) +
+            ` ${repoName}: ${message}`);
+    }
+    skip(current, repoName, reason) {
+        this.stats.skipped++;
+        console.log(chalk.yellow(`[${current}/${this.stats.total}] ⊘`) +
+            ` ${repoName}: Skipped - ${reason}`);
+    }
+    error(current, repoName, error) {
+        this.stats.failed++;
+        console.log(chalk.red(`[${current}/${this.stats.total}] ✗`) +
+            ` ${repoName}: ${error}`);
+    }
+    summary() {
+        console.log("");
+        console.log(chalk.bold("Summary:"));
+        console.log(`  Total:     ${this.stats.total}`);
+        console.log(chalk.green(`  Succeeded: ${this.stats.succeeded}`));
+        console.log(chalk.yellow(`  Skipped:   ${this.stats.skipped}`));
+        console.log(chalk.red(`  Failed:    ${this.stats.failed}`));
+    }
+    hasFailures() {
+        return this.stats.failed > 0;
+    }
+}
+export const logger = new Logger();

package/dist/merge.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Deep merge utilities for JSON configuration objects.
+ * Supports configurable array merge strategies via $arrayMerge directive.
+ */
+export type ArrayMergeStrategy = "replace" | "append" | "prepend";
+/**
+ * Handler function type for array merge strategies.
+ */
+export type ArrayMergeHandler = (base: unknown[], overlay: unknown[]) => unknown[];
+/**
+ * Strategy map for array merge operations.
+ * Extensible: add new strategies by adding to this map.
+ */
+export declare const arrayMergeStrategies: Map<ArrayMergeStrategy, ArrayMergeHandler>;
+export interface MergeContext {
+    arrayStrategies: Map<string, ArrayMergeStrategy>;
+    defaultArrayStrategy: ArrayMergeStrategy;
+}
+/**
+ * Deep merge two objects with configurable array handling.
+ *
+ * @param base - The base object
+ * @param overlay - The overlay object (values override base)
+ * @param ctx - Merge context with array strategies
+ * @param path - Current path for strategy lookup (internal)
+ */
+export declare function deepMerge(base: Record<string, unknown>, overlay: Record<string, unknown>, ctx: MergeContext, path?: string): Record<string, unknown>;
+/**
+ * Strip merge directive keys ($arrayMerge, $override, etc.) from an object.
+ * Works recursively on nested objects and arrays.
+ */
+export declare function stripMergeDirectives(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Create a default merge context.
+ */
+export declare function createMergeContext(defaultStrategy?: ArrayMergeStrategy): MergeContext;
+/**
+ * Check if content is text type (string or string[]).
+ */
+export declare function isTextContent(content: unknown): content is string | string[];
+/**
+ * Merge two text content values.
+ * For strings: overlay replaces base entirely.
+ * For string arrays: applies merge strategy.
+ * For mixed types: overlay replaces base.
+ */
+export declare function mergeTextContent(base: string | string[], overlay: string | string[], strategy?: ArrayMergeStrategy): string | string[];

package/dist/merge.js

@@ -0,0 +1,196 @@
+/**
+ * Deep merge utilities for JSON configuration objects.
+ * Supports configurable array merge strategies via $arrayMerge directive.
+ */
+/**
+ * Strategy map for array merge operations.
+ * Extensible: add new strategies by adding to this map.
+ */
+export const arrayMergeStrategies = new Map([
+    ["replace", (_base, overlay) => overlay],
+    ["append", (base, overlay) => [...base, ...overlay]],
+    ["prepend", (base, overlay) => [...overlay, ...base]],
+]);
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+function isPlainObject(val) {
+    return typeof val === "object" && val !== null && !Array.isArray(val);
+}
+/**
+ * Merge two arrays based on the specified strategy.
+ */
+function mergeArrays(base, overlay, strategy) {
+    const handler = arrayMergeStrategies.get(strategy);
+    if (handler) {
+        return handler(base, overlay);
+    }
+    // Fallback to replace for unknown strategies
+    return overlay;
+}
+/**
+ * Extract array values from an overlay object that uses the directive syntax:
+ * { $arrayMerge: 'append', values: [1, 2, 3] }
+ *
+ * Or just return the array if it's already an array.
+ */
+function extractArrayFromOverlay(overlay) {
+    if (Array.isArray(overlay)) {
+        return overlay;
+    }
+    if (isPlainObject(overlay) && "values" in overlay) {
+        const values = overlay.values;
+        if (Array.isArray(values)) {
+            return values;
+        }
+    }
+    return null;
+}
+/**
+ * Get merge strategy from an overlay object's $arrayMerge directive.
+ */
+function getStrategyFromOverlay(overlay) {
+    if (isPlainObject(overlay) && "$arrayMerge" in overlay) {
+        const strategy = overlay.$arrayMerge;
+        if (strategy === "replace" ||
+            strategy === "append" ||
+            strategy === "prepend") {
+            return strategy;
+        }
+    }
+    return null;
+}
+/**
+ * Deep merge two objects with configurable array handling.
+ *
+ * @param base - The base object
+ * @param overlay - The overlay object (values override base)
+ * @param ctx - Merge context with array strategies
+ * @param path - Current path for strategy lookup (internal)
+ */
+export function deepMerge(base, overlay, ctx, path = "") {
+    const result = { ...base };
+    // Check for $arrayMerge directive at this level (applies to child arrays)
+    const levelStrategy = getStrategyFromOverlay(overlay);
+    for (const [key, overlayValue] of Object.entries(overlay)) {
+        // Skip directive keys in output
+        if (key.startsWith("$"))
+            continue;
+        const currentPath = path ? `${path}.${key}` : key;
+        const baseValue = base[key];
+        // If overlay is an object with $arrayMerge directive for an array field
+        if (isPlainObject(overlayValue) && "$arrayMerge" in overlayValue) {
+            const strategy = getStrategyFromOverlay(overlayValue);
+            const overlayArray = extractArrayFromOverlay(overlayValue);
+            if (strategy && overlayArray && Array.isArray(baseValue)) {
+                result[key] = mergeArrays(baseValue, overlayArray, strategy);
+                continue;
+            }
+        }
+        // Both are arrays - apply strategy
+        if (Array.isArray(baseValue) && Array.isArray(overlayValue)) {
+            // Check for level-specific strategy, then path-specific, then default
+            const strategy = levelStrategy ??
+                ctx.arrayStrategies.get(currentPath) ??
+                ctx.defaultArrayStrategy;
+            result[key] = mergeArrays(baseValue, overlayValue, strategy);
+            continue;
+        }
+        // Both are plain objects - recurse
+        if (isPlainObject(baseValue) && isPlainObject(overlayValue)) {
+            // Extract $arrayMerge for child paths if present
+            if ("$arrayMerge" in overlayValue) {
+                const childStrategy = getStrategyFromOverlay(overlayValue);
+                if (childStrategy) {
+                    // Apply to all immediate child arrays
+                    for (const childKey of Object.keys(overlayValue)) {
+                        if (!childKey.startsWith("$")) {
+                            const childPath = currentPath
+                                ? `${currentPath}.${childKey}`
+                                : childKey;
+                            ctx.arrayStrategies.set(childPath, childStrategy);
+                        }
+                    }
+                }
+            }
+            result[key] = deepMerge(baseValue, overlayValue, ctx, currentPath);
+            continue;
+        }
+        // Otherwise, overlay wins (including null values)
+        result[key] = overlayValue;
+    }
+    return result;
+}
+/**
+ * Strip merge directive keys ($arrayMerge, $override, etc.) from an object.
+ * Works recursively on nested objects and arrays.
+ */
+export function stripMergeDirectives(obj) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        // Skip all $-prefixed keys (reserved for directives)
+        if (key.startsWith("$"))
+            continue;
+        if (isPlainObject(value)) {
+            result[key] = stripMergeDirectives(value);
+        }
+        else if (Array.isArray(value)) {
+            result[key] = value.map((item) => isPlainObject(item) ? stripMergeDirectives(item) : item);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Create a default merge context.
+ */
+export function createMergeContext(defaultStrategy = "replace") {
+    return {
+        arrayStrategies: new Map(),
+        defaultArrayStrategy: defaultStrategy,
+    };
+}
+// =============================================================================
+// Text Content Utilities
+// =============================================================================
+/**
+ * Check if content is text type (string or string[]).
+ */
+export function isTextContent(content) {
+    return (typeof content === "string" ||
+        (Array.isArray(content) &&
+            content.every((item) => typeof item === "string")));
+}
+/**
+ * Merge two text content values.
+ * For strings: overlay replaces base entirely.
+ * For string arrays: applies merge strategy.
+ * For mixed types: overlay replaces base.
+ */
+export function mergeTextContent(base, overlay, strategy = "replace") {
+    // If overlay is a string, it always replaces
+    if (typeof overlay === "string") {
+        return overlay;
+    }
+    // If overlay is an array
+    if (Array.isArray(overlay)) {
+        // If base is also an array, apply merge strategy
+        if (Array.isArray(base)) {
+            switch (strategy) {
+                case "append":
+                    return [...base, ...overlay];
+                case "prepend":
+                    return [...overlay, ...base];
+                case "replace":
+                default:
+                    return overlay;
+            }
+        }
+        // Base is string, overlay is array - overlay replaces
+        return overlay;
+    }
+    // Fallback (shouldn't reach here with proper types)
+    return overlay;
+}

package/dist/pr-creator.d.ts

@@ -0,0 +1,40 @@
+import { RepoInfo } from "./repo-detector.js";
+import { MergeResult, PRMergeConfig } from "./strategies/index.js";
+export { escapeShellArg } from "./shell-utils.js";
+export interface FileAction {
+    fileName: string;
+    action: "create" | "update" | "skip";
+}
+export interface PROptions {
+    repoInfo: RepoInfo;
+    branchName: string;
+    baseBranch: string;
+    files: FileAction[];
+    workDir: string;
+    dryRun?: boolean;
+    /** Number of retries for API operations (default: 3) */
+    retries?: number;
+}
+export interface PRResult {
+    url?: string;
+    success: boolean;
+    message: string;
+}
+/**
+ * Format PR body for multiple files
+ */
+export declare function formatPRBody(files: FileAction[]): string;
+/**
+ * Generate PR title based on files changed (excludes skipped files)
+ */
+export declare function formatPRTitle(files: FileAction[]): string;
+export declare function createPR(options: PROptions): Promise<PRResult>;
+export interface MergePROptions {
+    repoInfo: RepoInfo;
+    prUrl: string;
+    mergeConfig: PRMergeConfig;
+    workDir: string;
+    dryRun?: boolean;
+    retries?: number;
+}
+export declare function mergePR(options: MergePROptions): Promise<MergeResult>;

package/dist/pr-creator.js

@@ -0,0 +1,129 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getPRStrategy, } from "./strategies/index.js";
+// Re-export for backwards compatibility and testing
+export { escapeShellArg } from "./shell-utils.js";
+function loadPRTemplate() {
+    // Try to find PR.md in the project root
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    const templatePath = join(__dirname, "..", "PR.md");
+    if (existsSync(templatePath)) {
+        return readFileSync(templatePath, "utf-8");
+    }
+    // Fallback template for multi-file support
+    return `## Summary
+Automated sync of configuration files.
+
+## Changes
+{{FILE_CHANGES}}
+
+## Source
+Configuration synced using [xfg](https://github.com/anthony-spruyt/xfg).
+
+---
+_This PR was automatically generated by [xfg](https://github.com/anthony-spruyt/xfg)_`;
+}
+/**
+ * Format file changes list, excluding skipped files
+ */
+function formatFileChanges(files) {
+    const changedFiles = files.filter((f) => f.action !== "skip");
+    return changedFiles
+        .map((f) => {
+        const actionText = f.action === "create" ? "Created" : "Updated";
+        return `- ${actionText} \`${f.fileName}\``;
+    })
+        .join("\n");
+}
+/**
+ * Format PR body for multiple files
+ */
+export function formatPRBody(files) {
+    const template = loadPRTemplate();
+    const fileChanges = formatFileChanges(files);
+    // Check if template supports multi-file format
+    if (template.includes("{{FILE_CHANGES}}")) {
+        return template.replace(/\{\{FILE_CHANGES\}\}/g, fileChanges);
+    }
+    // Legacy single-file template - adapt it for multiple files
+    const changedFiles = files.filter((f) => f.action !== "skip");
+    if (changedFiles.length === 1) {
+        const actionText = changedFiles[0].action === "create" ? "Created" : "Updated";
+        return template
+            .replace(/\{\{FILE_NAME\}\}/g, changedFiles[0].fileName)
+            .replace(/\{\{ACTION\}\}/g, actionText);
+    }
+    // Multiple files with legacy template - generate custom body
+    return `## Summary
+Automated sync of configuration files.
+
+## Changes
+${fileChanges}
+
+## Source
+Configuration synced using [xfg](https://github.com/anthony-spruyt/xfg).
+
+---
+_This PR was automatically generated by [xfg](https://github.com/anthony-spruyt/xfg)_`;
+}
+/**
+ * Generate PR title based on files changed (excludes skipped files)
+ */
+export function formatPRTitle(files) {
+    const changedFiles = files.filter((f) => f.action !== "skip");
+    if (changedFiles.length === 1) {
+        return `chore: sync ${changedFiles[0].fileName}`;
+    }
+    if (changedFiles.length <= 3) {
+        const fileNames = changedFiles.map((f) => f.fileName).join(", ");
+        return `chore: sync ${fileNames}`;
+    }
+    return `chore: sync ${changedFiles.length} config files`;
+}
+export async function createPR(options) {
+    const { repoInfo, branchName, baseBranch, files, workDir, dryRun, retries } = options;
+    const title = formatPRTitle(files);
+    const body = formatPRBody(files);
+    if (dryRun) {
+        return {
+            success: true,
+            message: `[DRY RUN] Would create PR: "${title}"`,
+        };
+    }
+    // Get the appropriate strategy and execute
+    const strategy = getPRStrategy(repoInfo);
+    return strategy.execute({
+        repoInfo,
+        title,
+        body,
+        branchName,
+        baseBranch,
+        workDir,
+        retries,
+    });
+}
+export async function mergePR(options) {
+    const { repoInfo, prUrl, mergeConfig, workDir, dryRun, retries } = options;
+    if (dryRun) {
+        const modeText = mergeConfig.mode === "force"
+            ? "force merge"
+            : mergeConfig.mode === "auto"
+                ? "enable auto-merge"
+                : "leave open for manual review";
+        return {
+            success: true,
+            message: `[DRY RUN] Would ${modeText}`,
+            merged: false,
+        };
+    }
+    // Get the appropriate strategy and execute merge
+    const strategy = getPRStrategy(repoInfo);
+    return strategy.merge({
+        prUrl,
+        config: mergeConfig,
+        workDir,
+        retries,
+    });
+}

package/dist/repo-detector.d.ts

@@ -0,0 +1,22 @@
+export type RepoType = "github" | "azure-devops";
+interface BaseRepoInfo {
+    gitUrl: string;
+    repo: string;
+}
+export interface GitHubRepoInfo extends BaseRepoInfo {
+    type: "github";
+    owner: string;
+}
+export interface AzureDevOpsRepoInfo extends BaseRepoInfo {
+    type: "azure-devops";
+    owner: string;
+    organization: string;
+    project: string;
+}
+export type RepoInfo = GitHubRepoInfo | AzureDevOpsRepoInfo;
+export declare function isGitHubRepo(info: RepoInfo): info is GitHubRepoInfo;
+export declare function isAzureDevOpsRepo(info: RepoInfo): info is AzureDevOpsRepoInfo;
+export declare function detectRepoType(gitUrl: string): RepoType;
+export declare function parseGitUrl(gitUrl: string): RepoInfo;
+export declare function getRepoDisplayName(repoInfo: RepoInfo): string;
+export {};