@aspruyt/xfg 1.5.1 → 1.7.0

package/PR.md

@@ -1,10 +1,10 @@
 ## Summary
 
-Automated sync of configuration files.
+Automated sync of configuration files to ${xfg:repo.fullName}.
 
 ## Changes
 
-{{FILE_CHANGES}}
+${xfg:pr.fileChanges}
 
 ## Source
 

package/README.md

@@ -51,11 +51,12 @@ xfg --config ./config.yaml
 - **Content Inheritance** - Define base config once, override per-repo as needed
 - **Multi-Repo Targeting** - Apply same config to multiple repos with array syntax
 - **Environment Variables** - Use `${VAR}` syntax for dynamic values
+- **Templating** - Use `${xfg:repo.name}` syntax for dynamic repo-specific content
 - **Merge Strategies** - Control how arrays merge (replace, append, prepend)
 - **Override Mode** - Skip merging entirely for specific repos
 - **Empty Files** - Create files with no content (e.g., `.prettierignore`)
 - **YAML Comments** - Add header comments and schema directives to YAML files
-- **Multi-Platform** - Works with GitHub, Azure DevOps, and GitLab (including self-hosted)
+- **Multi-Platform** - Works with GitHub (including GitHub Enterprise Server), Azure DevOps, and GitLab (including self-hosted)
 - **Auto-Merge PRs** - Automatically merge PRs when checks pass, or force merge with admin privileges
 - **Dry-Run Mode** - Preview changes without creating PRs
 - **Error Resilience** - Continues processing if individual repos fail

package/dist/config-normalizer.js

@@ -115,6 +115,12 @@ export function normalizeConfig(raw) {
                 const executable = repoOverride?.executable ?? fileConfig.executable;
                 const header = normalizeHeader(repoOverride?.header ?? fileConfig.header);
                 const schemaUrl = repoOverride?.schemaUrl ?? fileConfig.schemaUrl;
+                // Template: per-repo overrides root level
+                const template = repoOverride?.template ?? fileConfig.template;
+                // Vars: merge root + per-repo (per-repo takes precedence)
+                const vars = fileConfig.vars || repoOverride?.vars
+                    ? { ...fileConfig.vars, ...repoOverride?.vars }
+                    : undefined;
                 files.push({
                     fileName,
                     content: mergedContent,
@@ -122,6 +128,8 @@ export function normalizeConfig(raw) {
                     executable,
                     header,
                     schemaUrl,
+                    template,
+                    vars,
                 });
             }
             // Merge PR options: per-repo overrides global
@@ -136,5 +144,6 @@ export function normalizeConfig(raw) {
     return {
         repos: expandedRepos,
         prTemplate: raw.prTemplate,
+        githubHosts: raw.githubHosts,
     };
 }

package/dist/config-validator.js

@@ -79,10 +79,44 @@ export function validateRawConfig(config) {
             typeof fileConfig.schemaUrl !== "string") {
             throw new Error(`File '${fileName}' schemaUrl must be a string`);
         }
+        if (fileConfig.template !== undefined &&
+            typeof fileConfig.template !== "boolean") {
+            throw new Error(`File '${fileName}' template must be a boolean`);
+        }
+        if (fileConfig.vars !== undefined) {
+            if (typeof fileConfig.vars !== "object" ||
+                fileConfig.vars === null ||
+                Array.isArray(fileConfig.vars)) {
+                throw new Error(`File '${fileName}' vars must be an object with string values`);
+            }
+            for (const [key, value] of Object.entries(fileConfig.vars)) {
+                if (typeof value !== "string") {
+                    throw new Error(`File '${fileName}' vars.${key} must be a string`);
+                }
+            }
+        }
     }
     if (!config.repos || !Array.isArray(config.repos)) {
         throw new Error("Config missing required field: repos (must be an array)");
     }
+    // Validate githubHosts if provided
+    if (config.githubHosts !== undefined) {
+        if (!Array.isArray(config.githubHosts) ||
+            !config.githubHosts.every((h) => typeof h === "string")) {
+            throw new Error("githubHosts must be an array of strings");
+        }
+        for (const host of config.githubHosts) {
+            if (!host) {
+                throw new Error("githubHosts entries must be non-empty hostnames");
+            }
+            if (host.includes("://")) {
+                throw new Error(`githubHosts entries must be hostnames only, not URLs. Got: ${host}`);
+            }
+            if (host.includes("/")) {
+                throw new Error(`githubHosts entries must be hostnames only, not paths. Got: ${host}`);
+            }
+        }
+    }
     // Validate each repo
     for (let i = 0; i < config.repos.length; i++) {
         const repo = config.repos[i];
@@ -146,6 +180,22 @@ export function validateRawConfig(config) {
                     typeof fileOverride.schemaUrl !== "string") {
                     throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' schemaUrl must be a string`);
                 }
+                if (fileOverride.template !== undefined &&
+                    typeof fileOverride.template !== "boolean") {
+                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' template must be a boolean`);
+                }
+                if (fileOverride.vars !== undefined) {
+                    if (typeof fileOverride.vars !== "object" ||
+                        fileOverride.vars === null ||
+                        Array.isArray(fileOverride.vars)) {
+                        throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' vars must be an object with string values`);
+                    }
+                    for (const [key, value] of Object.entries(fileOverride.vars)) {
+                        if (typeof value !== "string") {
+                            throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' vars.${key} must be a string`);
+                        }
+                    }
+                }
             }
         }
     }

package/dist/config.d.ts

@@ -16,6 +16,8 @@ export interface RawFileConfig {
     executable?: boolean;
     header?: string | string[];
     schemaUrl?: string;
+    template?: boolean;
+    vars?: Record<string, string>;
 }
 export interface RawRepoFileOverride {
     content?: ContentValue;
@@ -24,6 +26,8 @@ export interface RawRepoFileOverride {
     executable?: boolean;
     header?: string | string[];
     schemaUrl?: string;
+    template?: boolean;
+    vars?: Record<string, string>;
 }
 export interface RawRepoConfig {
     git: string | string[];
@@ -35,6 +39,7 @@ export interface RawConfig {
     repos: RawRepoConfig[];
     prOptions?: PRMergeOptions;
     prTemplate?: string;
+    githubHosts?: string[];
 }
 export interface FileContent {
     fileName: string;
@@ -43,6 +48,8 @@ export interface FileContent {
     executable?: boolean;
     header?: string[];
     schemaUrl?: string;
+    template?: boolean;
+    vars?: Record<string, string>;
 }
 export interface RepoConfig {
     git: string;
@@ -52,5 +59,6 @@ export interface RepoConfig {
 export interface Config {
     repos: RepoConfig[];
     prTemplate?: string;
+    githubHosts?: string[];
 }
 export declare function loadConfig(filePath: string): Config;

package/dist/env.js

@@ -23,8 +23,10 @@ const ENV_VAR_REGEX = /\$\{([^}:]+)(?::([?-])([^}]*))?\}/g;
  * Regex to match escaped environment variable placeholders.
  * $${...} outputs literal ${...} without interpolation.
  * Example: $${VAR} -> ${VAR}, $${VAR:-default} -> ${VAR:-default}
+ *
+ * Note: Does NOT match $${xfg:...} patterns - those are handled by xfg templating.
  */
-const ESCAPED_VAR_REGEX = /\$\$\{([^}]+)\}/g;
+const ESCAPED_VAR_REGEX = /\$\$\{((?!xfg:)[^}]+)\}/g;
 /**
  * Placeholder prefix for temporarily storing escaped sequences.
  * Uses null bytes which won't appear in normal content.

package/dist/index.js

@@ -115,7 +115,9 @@ async function main() {
         const current = i + 1;
         let repoInfo;
         try {
-            repoInfo = parseGitUrl(repoConfig.git);
+            repoInfo = parseGitUrl(repoConfig.git, {
+                githubHosts: config.githubHosts,
+            });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/dist/pr-creator.d.ts

@@ -23,9 +23,16 @@ export interface PRResult {
     message: string;
 }
 /**
- * Format PR body using template with {{FILE_CHANGES}} placeholder
+ * Format PR body using template with ${xfg:...} variables.
+ *
+ * Available PR-specific variables:
+ * - ${xfg:pr.fileChanges} - formatted list of changed files
+ * - ${xfg:pr.fileCount} - number of changed files
+ * - ${xfg:pr.title} - the PR title
+ *
+ * Plus all standard repo variables (repo.name, repo.owner, etc.)
  */
-export declare function formatPRBody(files: FileAction[], customTemplate?: string): string;
+export declare function formatPRBody(files: FileAction[], repoInfo: RepoInfo, customTemplate?: string): string;
 /**
  * Generate PR title based on files changed (excludes skipped files)
  */

package/dist/pr-creator.js

@@ -2,6 +2,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getPRStrategy, } from "./strategies/index.js";
+import { interpolateXfgContent } from "./xfg-template.js";
 // Re-export for backwards compatibility and testing
 export { escapeShellArg } from "./shell-utils.js";
 function loadDefaultTemplate() {
@@ -15,11 +16,11 @@ function loadDefaultTemplate() {
     // Fallback template
     return `## Summary
 
-Automated sync of configuration files.
+Automated sync of configuration files to \${xfg:repo.fullName}.
 
 ## Changes
 
-{{FILE_CHANGES}}
+\${xfg:pr.fileChanges}
 
 ## Source
 
@@ -42,12 +43,31 @@ function formatFileChanges(files) {
         .join("\n");
 }
 /**
- * Format PR body using template with {{FILE_CHANGES}} placeholder
+ * Format PR body using template with ${xfg:...} variables.
+ *
+ * Available PR-specific variables:
+ * - ${xfg:pr.fileChanges} - formatted list of changed files
+ * - ${xfg:pr.fileCount} - number of changed files
+ * - ${xfg:pr.title} - the PR title
+ *
+ * Plus all standard repo variables (repo.name, repo.owner, etc.)
  */
-export function formatPRBody(files, customTemplate) {
+export function formatPRBody(files, repoInfo, customTemplate) {
     const template = customTemplate ?? loadDefaultTemplate();
     const fileChanges = formatFileChanges(files);
-    return template.replace(/\{\{FILE_CHANGES\}\}/g, fileChanges);
+    const changedFiles = files.filter((f) => f.action !== "skip");
+    const title = formatPRTitle(files);
+    // Create context with PR-specific variables
+    const result = interpolateXfgContent(template, {
+        repoInfo,
+        fileName: "PR.md",
+        vars: {
+            "pr.fileChanges": fileChanges,
+            "pr.fileCount": String(changedFiles.length),
+            "pr.title": title,
+        },
+    });
+    return result;
 }
 /**
  * Generate PR title based on files changed (excludes skipped files)
@@ -66,7 +86,7 @@ export function formatPRTitle(files) {
 export async function createPR(options) {
     const { repoInfo, branchName, baseBranch, files, workDir, dryRun, retries, prTemplate, } = options;
     const title = formatPRTitle(files);
-    const body = formatPRBody(files, prTemplate);
+    const body = formatPRBody(files, repoInfo, prTemplate);
     if (dryRun) {
         return {
             success: true,

package/dist/repo-detector.d.ts

@@ -1,4 +1,7 @@
 export type RepoType = "github" | "azure-devops" | "gitlab";
+export interface RepoDetectorContext {
+    githubHosts?: string[];
+}
 interface BaseRepoInfo {
     gitUrl: string;
     repo: string;
@@ -6,6 +9,7 @@ interface BaseRepoInfo {
 export interface GitHubRepoInfo extends BaseRepoInfo {
     type: "github";
     owner: string;
+    host: string;
 }
 export interface AzureDevOpsRepoInfo extends BaseRepoInfo {
     type: "azure-devops";
@@ -23,7 +27,7 @@ export type RepoInfo = GitHubRepoInfo | AzureDevOpsRepoInfo | GitLabRepoInfo;
 export declare function isGitHubRepo(info: RepoInfo): info is GitHubRepoInfo;
 export declare function isAzureDevOpsRepo(info: RepoInfo): info is AzureDevOpsRepoInfo;
 export declare function isGitLabRepo(info: RepoInfo): info is GitLabRepoInfo;
-export declare function detectRepoType(gitUrl: string): RepoType;
-export declare function parseGitUrl(gitUrl: string): RepoInfo;
+export declare function detectRepoType(gitUrl: string, context?: RepoDetectorContext): RepoType;
+export declare function parseGitUrl(gitUrl: string, context?: RepoDetectorContext): RepoInfo;
 export declare function getRepoDisplayName(repoInfo: RepoInfo): string;
 export {};

package/dist/repo-detector.js

@@ -8,6 +8,22 @@ export function isAzureDevOpsRepo(info) {
 export function isGitLabRepo(info) {
     return info.type === "gitlab";
 }
+/**
+ * Extract hostname from a git URL.
+ */
+function extractHostFromUrl(gitUrl) {
+    // SSH: git@hostname:path
+    const sshMatch = gitUrl.match(/^git@([^:]+):/);
+    if (sshMatch) {
+        return sshMatch[1];
+    }
+    // HTTPS: https://hostname/path
+    const httpsMatch = gitUrl.match(/^https?:\/\/([^/]+)/);
+    if (httpsMatch) {
+        return httpsMatch[1];
+    }
+    return null;
+}
 /**
  * Valid URL patterns for supported repository types.
  */
@@ -41,8 +57,16 @@ function isGitLabStyleUrl(gitUrl) {
     }
     return false;
 }
-export function detectRepoType(gitUrl) {
-    // Check for Azure DevOps formats first (most specific patterns)
+export function detectRepoType(gitUrl, context) {
+    // Check for GitHub Enterprise hosts first (if configured)
+    if (context?.githubHosts?.length) {
+        const host = extractHostFromUrl(gitUrl)?.toLowerCase();
+        const normalizedHosts = context.githubHosts.map((h) => h.toLowerCase());
+        if (host && normalizedHosts.includes(host)) {
+            return "github";
+        }
+    }
+    // Check for Azure DevOps formats (most specific patterns)
     for (const pattern of AZURE_DEVOPS_URL_PATTERNS) {
         if (pattern.test(gitUrl)) {
             return "azure-devops";
@@ -67,37 +91,41 @@ export function detectRepoType(gitUrl) {
     // Throw for unrecognized URL formats
     throw new Error(`Unrecognized git URL format: ${gitUrl}. Supported formats: GitHub (git@github.com: or https://github.com/), Azure DevOps (git@ssh.dev.azure.com: or https://dev.azure.com/), and GitLab (git@gitlab.com: or https://gitlab.com/)`);
 }
-export function parseGitUrl(gitUrl) {
-    const type = detectRepoType(gitUrl);
+export function parseGitUrl(gitUrl, context) {
+    const type = detectRepoType(gitUrl, context);
     if (type === "azure-devops") {
         return parseAzureDevOpsUrl(gitUrl);
     }
     if (type === "gitlab") {
         return parseGitLabUrl(gitUrl);
     }
-    return parseGitHubUrl(gitUrl);
+    // For GitHub, extract the host from the URL
+    const host = extractHostFromUrl(gitUrl) ?? "github.com";
+    return parseGitHubUrl(gitUrl, host);
 }
-function parseGitHubUrl(gitUrl) {
-    // Handle SSH format: git@github.com:owner/repo.git
+function parseGitHubUrl(gitUrl, host) {
+    // Handle SSH format: git@hostname:owner/repo.git
     // Use (.+?) with end anchor to handle repo names with dots (e.g., my.repo.git)
-    const sshMatch = gitUrl.match(/git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/);
+    const sshMatch = gitUrl.match(/^git@[^:]+:([^/]+)\/(.+?)(?:\.git)?$/);
     if (sshMatch) {
         return {
             type: "github",
             gitUrl,
             owner: sshMatch[1],
             repo: sshMatch[2],
+            host,
         };
     }
-    // Handle HTTPS format: https://github.com/owner/repo.git
+    // Handle HTTPS format: https://hostname/owner/repo.git
     // Use (.+?) with end anchor to handle repo names with dots
-    const httpsMatch = gitUrl.match(/https?:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/);
+    const httpsMatch = gitUrl.match(/^https?:\/\/[^/]+\/([^/]+)\/(.+?)(?:\.git)?$/);
     if (httpsMatch) {
         return {
             type: "github",
             gitUrl,
             owner: httpsMatch[1],
             repo: httpsMatch[2],
+            host,
         };
     }
     throw new Error(`Unable to parse GitHub URL: ${gitUrl}`);

package/dist/repository-processor.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { convertContentToString, } from "./config.js";
 import { getRepoDisplayName } from "./repo-detector.js";
+import { interpolateXfgContent } from "./xfg-template.js";
 import { GitOps } from "./git-ops.js";
 import { createPR, mergePR } from "./pr-creator.js";
 import { logger } from "./logger.js";
@@ -97,7 +98,16 @@ export class RepositoryProcessor {
                     }
                 }
                 this.log.info(`Writing ${file.fileName}...`);
-                const fileContent = convertContentToString(file.content, file.fileName, {
+                // Apply xfg templating if enabled
+                let contentToWrite = file.content;
+                if (file.template && contentToWrite !== null) {
+                    contentToWrite = interpolateXfgContent(contentToWrite, {
+                        repoInfo,
+                        fileName: file.fileName,
+                        vars: file.vars,
+                    }, { strict: true });
+                }
+                const fileContent = convertContentToString(contentToWrite, file.fileName, {
                     header: file.header,
                     schemaUrl: file.schemaUrl,
                 });

package/dist/strategies/github-pr-strategy.js

@@ -5,13 +5,47 @@ import { isGitHubRepo } from "../repo-detector.js";
 import { BasePRStrategy, } from "./pr-strategy.js";
 import { logger } from "../logger.js";
 import { withRetry, isPermanentError } from "../retry-utils.js";
+/**
+ * Get the repo flag value for gh CLI commands.
+ * Returns HOST/OWNER/REPO for GHE, OWNER/REPO for github.com.
+ */
+function getRepoFlag(repoInfo) {
+    if (repoInfo.host && repoInfo.host !== "github.com") {
+        return `${repoInfo.host}/${repoInfo.owner}/${repoInfo.repo}`;
+    }
+    return `${repoInfo.owner}/${repoInfo.repo}`;
+}
+/**
+ * Get the hostname flag for gh api commands.
+ * Returns "--hostname HOST" for GHE, empty string for github.com.
+ */
+function getHostnameFlag(repoInfo) {
+    if (repoInfo.host && repoInfo.host !== "github.com") {
+        return `--hostname ${escapeShellArg(repoInfo.host)}`;
+    }
+    return "";
+}
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Build regex to match PR URLs for the given host.
+ */
+function buildPRUrlRegex(host) {
+    const escapedHost = escapeRegExp(host);
+    return new RegExp(`https://${escapedHost}/[\\w-]+/[\\w.-]+/pull/\\d+`);
+}
 export class GitHubPRStrategy extends BasePRStrategy {
     async checkExistingPR(options) {
         const { repoInfo, branchName, workDir, retries = 3 } = options;
         if (!isGitHubRepo(repoInfo)) {
             throw new Error("Expected GitHub repository");
         }
-        const command = `gh pr list --head ${escapeShellArg(branchName)} --json url --jq '.[0].url'`;
+        const repoFlag = getRepoFlag(repoInfo);
+        const command = `gh pr list --repo ${escapeShellArg(repoFlag)} --head ${escapeShellArg(branchName)} --json url --jq '.[0].url'`;
         try {
             const existingPR = await withRetry(() => this.executor.exec(command, workDir), { retries });
             return existingPR || null;
@@ -55,7 +89,8 @@ export class GitHubPRStrategy extends BasePRStrategy {
             throw new Error(`Could not extract PR number from URL: ${existingUrl}`);
         }
         // Close the PR and delete the branch
-        const command = `gh pr close ${escapeShellArg(prNumber)} --repo ${escapeShellArg(repoInfo.owner)}/${escapeShellArg(repoInfo.repo)} --delete-branch`;
+        const repoFlag = getRepoFlag(repoInfo);
+        const command = `gh pr close ${escapeShellArg(prNumber)} --repo ${escapeShellArg(repoFlag)} --delete-branch`;
         try {
             await withRetry(() => this.executor.exec(command, workDir), { retries });
             return true;
@@ -78,7 +113,9 @@ export class GitHubPRStrategy extends BasePRStrategy {
         try {
             const result = await withRetry(() => this.executor.exec(command, workDir), { retries });
             // Extract URL from output - use strict regex for valid PR URLs only
-            const urlMatch = result.match(/https:\/\/github\.com\/[\w-]+\/[\w.-]+\/pull\/\d+/);
+            const host = repoInfo.host || "github.com";
+            const urlRegex = buildPRUrlRegex(host);
+            const urlMatch = result.match(urlRegex);
             if (!urlMatch) {
                 throw new Error(`Could not parse PR URL from output: ${result}`);
             }
@@ -104,7 +141,9 @@ export class GitHubPRStrategy extends BasePRStrategy {
      * Check if auto-merge is enabled on the repository.
      */
     async checkAutoMergeEnabled(repoInfo, workDir, retries = 3) {
-        const command = `gh api repos/${escapeShellArg(repoInfo.owner)}/${escapeShellArg(repoInfo.repo)} --jq '.allow_auto_merge // false'`;
+        const hostnameFlag = getHostnameFlag(repoInfo);
+        const hostnamePart = hostnameFlag ? `${hostnameFlag} ` : "";
+        const command = `gh api ${hostnamePart}repos/${escapeShellArg(repoInfo.owner)}/${escapeShellArg(repoInfo.repo)} --jq '.allow_auto_merge // false'`;
         try {
             const result = await withRetry(() => this.executor.exec(command, workDir), { retries });
             return result.trim() === "true";
@@ -143,19 +182,20 @@ export class GitHubPRStrategy extends BasePRStrategy {
         const deleteBranchFlag = config.deleteBranch ? "--delete-branch" : "";
         if (config.mode === "auto") {
             // Check if auto-merge is enabled on the repo
-            // Extract owner/repo from PR URL
-            const match = prUrl.match(/github\.com\/([^/]+)\/([^/]+)/);
+            // Extract host/owner/repo from PR URL (supports both github.com and GHE)
+            const match = prUrl.match(/https:\/\/([^/]+)\/([^/]+)\/([^/]+)/);
             if (match) {
                 const repoInfo = {
                     type: "github",
                     gitUrl: prUrl,
-                    owner: match[1],
-                    repo: match[2],
+                    owner: match[2],
+                    repo: match[3],
+                    host: match[1],
                 };
                 const autoMergeEnabled = await this.checkAutoMergeEnabled(repoInfo, workDir, retries);
                 if (!autoMergeEnabled) {
                     logger.info(`Warning: Auto-merge not enabled for '${repoInfo.owner}/${repoInfo.repo}'. PR left open for manual review.`);
-                    logger.info(`To enable: gh repo edit ${repoInfo.owner}/${repoInfo.repo} --enable-auto-merge (requires admin)`);
+                    logger.info(`To enable: gh repo edit ${getRepoFlag(repoInfo)} --enable-auto-merge (requires admin)`);
                     return {
                         success: true,
                         message: `Auto-merge not enabled for repository. PR left open for manual review.`,

package/dist/xfg-template.d.ts

@@ -0,0 +1,43 @@
+/**
+ * XFG template variable interpolation utilities.
+ * Supports ${xfg:variable} syntax for repo-specific content.
+ * Use $${xfg:variable} to escape and output literal ${xfg:variable}.
+ */
+import type { RepoInfo } from "./repo-detector.js";
+import type { ContentValue } from "./config.js";
+export interface XfgTemplateContext {
+    /** Repository information from URL parsing */
+    repoInfo: RepoInfo;
+    /** Current file being processed */
+    fileName: string;
+    /** Custom variables defined in config */
+    vars?: Record<string, string>;
+}
+export interface XfgInterpolationOptions {
+    /**
+     * If true (default), throws an error when a variable is missing.
+     * If false, leaves the placeholder as-is.
+     */
+    strict: boolean;
+}
+/**
+ * Interpolate xfg template variables in content.
+ *
+ * Supports these syntaxes:
+ * - ${xfg:repo.name} - Repository name
+ * - ${xfg:repo.owner} - Repository owner
+ * - ${xfg:repo.fullName} - Full repository name (owner/repo)
+ * - ${xfg:repo.url} - Git URL
+ * - ${xfg:repo.platform} - Platform type (github, azure-devops, gitlab)
+ * - ${xfg:repo.host} - Host domain
+ * - ${xfg:file.name} - Current file name
+ * - ${xfg:date} - Current date (YYYY-MM-DD)
+ * - ${xfg:customVar} - Custom variable from vars config
+ * - $${xfg:var} - Escape: outputs literal ${xfg:var}
+ *
+ * @param content - The content to process (object, string, or string[])
+ * @param ctx - Template context with repo info and custom vars
+ * @param options - Interpolation options (default: strict mode)
+ * @returns Content with interpolated values
+ */
+export declare function interpolateXfgContent(content: ContentValue, ctx: XfgTemplateContext, options?: XfgInterpolationOptions): ContentValue;

package/dist/xfg-template.js

@@ -0,0 +1,158 @@
+/**
+ * XFG template variable interpolation utilities.
+ * Supports ${xfg:variable} syntax for repo-specific content.
+ * Use $${xfg:variable} to escape and output literal ${xfg:variable}.
+ */
+const DEFAULT_OPTIONS = {
+    strict: true,
+};
+/**
+ * Regex to match xfg template variable placeholders.
+ * Captures the variable name including dot notation.
+ * Variable names can only contain: a-z, A-Z, 0-9, dots, and underscores.
+ *
+ * Examples:
+ * - ${xfg:repo.name} -> varName=repo.name
+ * - ${xfg:myVar} -> varName=myVar
+ */
+const XFG_VAR_REGEX = /\$\{xfg:([a-zA-Z0-9._]+)\}/g;
+/**
+ * Regex to match escaped xfg template variable placeholders.
+ * $${xfg:...} outputs literal ${xfg:...} without interpolation.
+ * Variable names can only contain: a-z, A-Z, 0-9, dots, and underscores.
+ */
+const ESCAPED_XFG_VAR_REGEX = /\$\$\{xfg:([a-zA-Z0-9._]+)\}/g;
+/**
+ * Placeholder prefix for temporarily storing escaped sequences.
+ * Uses null bytes which won't appear in normal content.
+ */
+const ESCAPE_PLACEHOLDER = "\x00ESCAPED_XFG_VAR\x00";
+/**
+ * Get the value of a built-in xfg variable.
+ * Returns undefined if the variable is not recognized.
+ */
+function getBuiltinVar(varName, ctx) {
+    const { repoInfo, fileName } = ctx;
+    switch (varName) {
+        case "repo.name":
+            return repoInfo.repo;
+        case "repo.owner":
+            return repoInfo.owner;
+        case "repo.fullName":
+            if (repoInfo.type === "azure-devops") {
+                return `${repoInfo.organization}/${repoInfo.project}/${repoInfo.repo}`;
+            }
+            if (repoInfo.type === "gitlab") {
+                return `${repoInfo.namespace}/${repoInfo.repo}`;
+            }
+            return `${repoInfo.owner}/${repoInfo.repo}`;
+        case "repo.url":
+            return repoInfo.gitUrl;
+        case "repo.platform":
+            return repoInfo.type;
+        case "repo.host":
+            if (repoInfo.type === "github" || repoInfo.type === "gitlab") {
+                return repoInfo.host;
+            }
+            // Azure DevOps doesn't have a host field, use dev.azure.com
+            return "dev.azure.com";
+        case "file.name":
+            return fileName;
+        case "date":
+            return new Date().toISOString().split("T")[0];
+        default:
+            return undefined;
+    }
+}
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+function isPlainObject(val) {
+    return typeof val === "object" && val !== null && !Array.isArray(val);
+}
+/**
+ * Process a single string value, replacing xfg template variable placeholders.
+ * Supports escaping with $${xfg:var} syntax to output literal ${xfg:var}.
+ */
+function processString(value, ctx, options) {
+    // Phase 1: Replace escaped $${xfg:...} with placeholders
+    const escapedContent = [];
+    let processed = value.replace(ESCAPED_XFG_VAR_REGEX, (_match, content) => {
+        const index = escapedContent.length;
+        escapedContent.push(content);
+        return `${ESCAPE_PLACEHOLDER}${index}\x00`;
+    });
+    // Phase 2: Interpolate remaining ${xfg:...}
+    processed = processed.replace(XFG_VAR_REGEX, (match, varName) => {
+        // First check custom vars
+        if (ctx.vars && varName in ctx.vars) {
+            return ctx.vars[varName];
+        }
+        // Then check built-in vars
+        const builtinValue = getBuiltinVar(varName, ctx);
+        if (builtinValue !== undefined) {
+            return builtinValue;
+        }
+        // Unknown variable
+        if (options.strict) {
+            throw new Error(`Unknown xfg template variable: ${varName}`);
+        }
+        // Non-strict mode - leave placeholder as-is
+        return match;
+    });
+    // Phase 3: Restore escaped sequences as literal ${xfg:...}
+    processed = processed.replace(new RegExp(`${ESCAPE_PLACEHOLDER}(\\d+)\x00`, "g"), (_match, indexStr) => {
+        const index = parseInt(indexStr, 10);
+        return `\${xfg:${escapedContent[index]}}`;
+    });
+    return processed;
+}
+/**
+ * Recursively process a value, interpolating xfg template variables in strings.
+ */
+function processValue(value, ctx, options) {
+    if (typeof value === "string") {
+        return processString(value, ctx, options);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => processValue(item, ctx, options));
+    }
+    if (isPlainObject(value)) {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = processValue(val, ctx, options);
+        }
+        return result;
+    }
+    // For numbers, booleans, null - return as-is
+    return value;
+}
+/**
+ * Interpolate xfg template variables in content.
+ *
+ * Supports these syntaxes:
+ * - ${xfg:repo.name} - Repository name
+ * - ${xfg:repo.owner} - Repository owner
+ * - ${xfg:repo.fullName} - Full repository name (owner/repo)
+ * - ${xfg:repo.url} - Git URL
+ * - ${xfg:repo.platform} - Platform type (github, azure-devops, gitlab)
+ * - ${xfg:repo.host} - Host domain
+ * - ${xfg:file.name} - Current file name
+ * - ${xfg:date} - Current date (YYYY-MM-DD)
+ * - ${xfg:customVar} - Custom variable from vars config
+ * - $${xfg:var} - Escape: outputs literal ${xfg:var}
+ *
+ * @param content - The content to process (object, string, or string[])
+ * @param ctx - Template context with repo info and custom vars
+ * @param options - Interpolation options (default: strict mode)
+ * @returns Content with interpolated values
+ */
+export function interpolateXfgContent(content, ctx, options = DEFAULT_OPTIONS) {
+    if (typeof content === "string") {
+        return processString(content, ctx, options);
+    }
+    if (Array.isArray(content)) {
+        return content.map((line) => processString(line, ctx, options));
+    }
+    return processValue(content, ctx, options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "CLI tool to sync JSON, JSON5, YAML, or text configuration files across multiple Git repositories by creating pull requests",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "ts-node src/index.ts",
-    "test": "node --import tsx --test src/config.test.ts src/merge.test.ts src/env.test.ts src/repo-detector.test.ts src/pr-creator.test.ts src/git-ops.test.ts src/logger.test.ts src/workspace-utils.test.ts src/strategies/pr-strategy.test.ts src/strategies/github-pr-strategy.test.ts src/strategies/azure-pr-strategy.test.ts src/strategies/gitlab-pr-strategy.test.ts src/repository-processor.test.ts src/retry-utils.test.ts src/command-executor.test.ts src/shell-utils.test.ts src/index.test.ts src/config-formatter.test.ts src/config-validator.test.ts src/config-normalizer.test.ts src/diff-utils.test.ts",
+    "test": "node --import tsx --test src/config.test.ts src/merge.test.ts src/env.test.ts src/repo-detector.test.ts src/pr-creator.test.ts src/git-ops.test.ts src/logger.test.ts src/workspace-utils.test.ts src/strategies/pr-strategy.test.ts src/strategies/github-pr-strategy.test.ts src/strategies/azure-pr-strategy.test.ts src/strategies/gitlab-pr-strategy.test.ts src/repository-processor.test.ts src/retry-utils.test.ts src/command-executor.test.ts src/shell-utils.test.ts src/index.test.ts src/config-formatter.test.ts src/config-validator.test.ts src/config-normalizer.test.ts src/diff-utils.test.ts src/xfg-template.test.ts",
     "test:integration:github": "npm run build && node --import tsx --test src/integration-github.test.ts",
     "test:integration:ado": "npm run build && node --import tsx --test src/integration-ado.test.ts",
     "test:integration:gitlab": "npm run build && node --import tsx --test src/integration-gitlab.test.ts",