@aspruyt/xfg 1.3.1 → 1.4.0

package/PR.md

@@ -1,10 +1,10 @@
 ## Summary
 
-Automated sync of `{{FILE_NAME}}` configuration file.
+Automated sync of configuration files.
 
 ## Changes
 
-- {{ACTION}} `{{FILE_NAME}}` in repository root
+{{FILE_CHANGES}}
 
 ## Source
 

package/README.md

@@ -182,11 +182,12 @@ repos: # List of repositories
 
 ### Root-Level Fields
 
-| Field       | Description                                          | Required |
-| ----------- | ---------------------------------------------------- | -------- |
-| `files`     | Map of target filenames to configs                   | Yes      |
-| `repos`     | Array of repository configurations                   | Yes      |
-| `prOptions` | Global PR merge options (can be overridden per-repo) | No       |
+| Field        | Description                                                   | Required |
+| ------------ | ------------------------------------------------------------- | -------- |
+| `files`      | Map of target filenames to configs                            | Yes      |
+| `repos`      | Array of repository configurations                            | Yes      |
+| `prOptions`  | Global PR merge options (can be overridden per-repo)          | No       |
+| `prTemplate` | Custom PR body template (inline or `@path/to/file` reference) | No       |
 
 ### Per-File Fields
 
@@ -216,6 +217,33 @@ repos: # List of repositories
 | `deleteBranch`  | Delete source branch after merge                                            | `true`   |
 | `bypassReason`  | Reason for bypassing policies (Azure DevOps only, required for `force`)     | -        |
 
+### PR Template Customization
+
+Customize the PR body with a template. Use the `{{FILE_CHANGES}}` placeholder for the list of changed files:
+
+```yaml
+# Inline template
+prTemplate: |
+  ## Configuration Update
+
+  This PR synchronizes the following files:
+
+  {{FILE_CHANGES}}
+
+  Please review and merge.
+
+# Or reference an external file
+prTemplate: "@templates/pr-body.md"
+```
+
+**Available Placeholders:**
+
+| Placeholder        | Description                         | Example Output                                           |
+| ------------------ | ----------------------------------- | -------------------------------------------------------- |
+| `{{FILE_CHANGES}}` | Bulleted list of files with actions | `- Created \`config.json\`\n- Updated \`settings.yaml\`` |
+
+**Default Template:** If not specified, uses the built-in template with Summary, Changes, and Source sections.
+
 ### Per-Repo File Override Fields
 
 | Field        | Description                                             | Required |

package/dist/config-normalizer.js

@@ -135,5 +135,6 @@ export function normalizeConfig(raw) {
     }
     return {
         repos: expandedRepos,
+        prTemplate: raw.prTemplate,
     };
 }

package/dist/config-validator.js

@@ -108,7 +108,8 @@ export function validateRawConfig(config) {
                     continue;
                 }
                 if (fileOverride.override && !fileOverride.content) {
-                    throw new Error(`Repo ${getGitDisplayName(repo.git)} has override: true for file '${fileName}' but no content defined`);
+                    throw new Error(`Repo ${getGitDisplayName(repo.git)} has override: true for file '${fileName}' but no content defined. ` +
+                        `Use content: "" for an empty text file override, or content: {} for an empty JSON/YAML override.`);
                 }
                 // Validate content type
                 if (fileOverride.content !== undefined) {

package/dist/config.d.ts

@@ -34,6 +34,7 @@ export interface RawConfig {
     files: Record<string, RawFileConfig>;
     repos: RawRepoConfig[];
     prOptions?: PRMergeOptions;
+    prTemplate?: string;
 }
 export interface FileContent {
     fileName: string;
@@ -50,5 +51,6 @@ export interface RepoConfig {
 }
 export interface Config {
     repos: RepoConfig[];
+    prTemplate?: string;
 }
 export declare function loadConfig(filePath: string): Config;

package/dist/file-reference-resolver.js

@@ -99,6 +99,14 @@ export function resolveFileReferencesInConfig(raw, options) {
     const { configDir } = options;
     // Deep clone to avoid mutating input
     const result = JSON.parse(JSON.stringify(raw));
+    // Resolve prTemplate file reference
+    if (result.prTemplate && isFileReference(result.prTemplate)) {
+        const resolved = resolveFileReference(result.prTemplate, configDir);
+        if (typeof resolved !== "string") {
+            throw new Error(`prTemplate file reference "${result.prTemplate}" must resolve to a text file, not JSON/YAML`);
+        }
+        result.prTemplate = resolved;
+    }
     // Resolve root-level file content
     if (result.files) {
         for (const [fileName, fileConfig] of Object.entries(result.files)) {

package/dist/index.js

@@ -131,6 +131,7 @@ async function main() {
                 workDir,
                 dryRun: options.dryRun,
                 retries: options.retries,
+                prTemplate: config.prTemplate,
             });
             if (result.skipped) {
                 logger.skip(current, repoName, result.message);

package/dist/pr-creator.d.ts

@@ -14,6 +14,8 @@ export interface PROptions {
     dryRun?: boolean;
     /** Number of retries for API operations (default: 3) */
     retries?: number;
+    /** Custom PR body template */
+    prTemplate?: string;
 }
 export interface PRResult {
     url?: string;
@@ -21,9 +23,9 @@ export interface PRResult {
     message: string;
 }
 /**
- * Format PR body for multiple files
+ * Format PR body using template with {{FILE_CHANGES}} placeholder
  */
-export declare function formatPRBody(files: FileAction[]): string;
+export declare function formatPRBody(files: FileAction[], customTemplate?: string): string;
 /**
  * Generate PR title based on files changed (excludes skipped files)
  */

package/dist/pr-creator.js

@@ -4,7 +4,7 @@ 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() {
+function loadDefaultTemplate() {
     // Try to find PR.md in the project root
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = dirname(__filename);
@@ -12,17 +12,21 @@ function loadPRTemplate() {
     if (existsSync(templatePath)) {
         return readFileSync(templatePath, "utf-8");
     }
-    // Fallback template for multi-file support
+    // Fallback template
     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)_`;
 }
 /**
@@ -38,35 +42,12 @@ function formatFileChanges(files) {
         .join("\n");
 }
 /**
- * Format PR body for multiple files
+ * Format PR body using template with {{FILE_CHANGES}} placeholder
  */
-export function formatPRBody(files) {
-    const template = loadPRTemplate();
+export function formatPRBody(files, customTemplate) {
+    const template = customTemplate ?? loadDefaultTemplate();
     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)_`;
+    return template.replace(/\{\{FILE_CHANGES\}\}/g, fileChanges);
 }
 /**
  * Generate PR title based on files changed (excludes skipped files)
@@ -83,9 +64,9 @@ export function formatPRTitle(files) {
     return `chore: sync ${changedFiles.length} config files`;
 }
 export async function createPR(options) {
-    const { repoInfo, branchName, baseBranch, files, workDir, dryRun, retries } = options;
+    const { repoInfo, branchName, baseBranch, files, workDir, dryRun, retries, prTemplate, } = options;
     const title = formatPRTitle(files);
-    const body = formatPRBody(files);
+    const body = formatPRBody(files, prTemplate);
     if (dryRun) {
         return {
             success: true,

package/dist/repository-processor.d.ts

@@ -11,6 +11,8 @@ export interface ProcessorOptions {
     retries?: number;
     /** Command executor for shell commands (for testing) */
     executor?: CommandExecutor;
+    /** Custom PR body template */
+    prTemplate?: string;
 }
 /**
  * Factory function type for creating GitOps instances.

package/dist/repository-processor.js

@@ -37,7 +37,7 @@ export class RepositoryProcessor {
     }
     async process(repoConfig, repoInfo, options) {
         const repoName = getRepoDisplayName(repoInfo);
-        const { branchName, workDir, dryRun, retries } = options;
+        const { branchName, workDir, dryRun, retries, prTemplate } = options;
         const executor = options.executor ?? defaultExecutor;
         this.gitOps = this.gitOpsFactory({ workDir, dryRun, retries });
         try {
@@ -207,6 +207,7 @@ export class RepositoryProcessor {
                 workDir,
                 dryRun,
                 retries,
+                prTemplate,
             });
             // Step 10: Handle merge options if configured
             const mergeMode = repoConfig.prOptions?.merge ?? "auto";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "CLI tool to sync JSON or YAML configuration files across multiple GitHub, Azure DevOps, and GitLab repositories",
   "type": "module",
   "main": "dist/index.js",