@aspruyt/xfg 1.0.2 → 1.1.0

package/README.md

@@ -136,16 +136,16 @@ xfg --config ./config.yaml --branch feature/update-eslint
 
 ### Options
 
-| Option             | Alias | Description                                                                          | Required |
-| ------------------ | ----- | ------------------------------------------------------------------------------------ | -------- |
-| `--config`         | `-c`  | Path to YAML config file                                                             | Yes      |
-| `--dry-run`        | `-d`  | Show what would be done without making changes                                       | No       |
-| `--work-dir`       | `-w`  | Temporary directory for cloning (default: `./tmp`)                                   | No       |
-| `--retries`        | `-r`  | Number of retries for network operations (default: 3)                                | No       |
-| `--branch`         | `-b`  | Override branch name (default: `chore/sync-config`)                                  | No       |
-| `--merge`          | `-m`  | PR merge mode: `manual` (default), `auto` (merge when checks pass), `force` (bypass) | No       |
-| `--merge-strategy` |       | Merge strategy: `merge` (default), `squash`, `rebase`                                | No       |
-| `--delete-branch`  |       | Delete source branch after merge                                                     | No       |
+| Option             | Alias | Description                                                                    | Required |
+| ------------------ | ----- | ------------------------------------------------------------------------------ | -------- |
+| `--config`         | `-c`  | Path to YAML config file                                                       | Yes      |
+| `--dry-run`        | `-d`  | Show what would be done without making changes                                 | No       |
+| `--work-dir`       | `-w`  | Temporary directory for cloning (default: `./tmp`)                             | No       |
+| `--retries`        | `-r`  | Number of retries for network operations (default: 3)                          | No       |
+| `--branch`         | `-b`  | Override branch name (default: `chore/sync-{filename}` or `chore/sync-config`) | No       |
+| `--merge`          | `-m`  | PR merge mode: `manual`, `auto` (default), `force` (bypass checks)             | No       |
+| `--merge-strategy` |       | Merge strategy: `merge`, `squash` (default), `rebase`                          | No       |
+| `--delete-branch`  |       | Delete source branch after merge                                               | No       |
 
 ## Configuration Format
 
@@ -197,9 +197,9 @@ repos: # List of repositories
 
 | Field           | Description                                                                 | Default  |
 | --------------- | --------------------------------------------------------------------------- | -------- |
-| `merge`         | Merge mode: `manual` (leave open), `auto` (merge when checks pass), `force` | `manual` |
-| `mergeStrategy` | How to merge: `merge`, `squash`, `rebase`                                   | `merge`  |
-| `deleteBranch`  | Delete source branch after merge                                            | `false`  |
+| `merge`         | Merge mode: `manual` (leave open), `auto` (merge when checks pass), `force` | `auto`   |
+| `mergeStrategy` | How to merge: `merge`, `squash`, `rebase`                                   | `squash` |
+| `deleteBranch`  | Delete source branch after merge                                            | `true`   |
 | `bypassReason`  | Reason for bypassing policies (Azure DevOps only, required for `force`)     | -        |
 
 ### Per-Repo File Override Fields
@@ -649,7 +649,7 @@ config/
 
 ### Auto-Merge PRs
 
-Configure PRs to merge automatically when checks pass, or force merge using admin privileges:
+By default, xfg enables auto-merge on PRs when checks pass. You can override this behavior per-repo or via CLI flags:
 
 ```yaml
 files:
@@ -658,18 +658,18 @@ files:
       semi: false
       singleQuote: true
 
-# Global PR options - apply to all repos
-prOptions:
-  merge: auto # auto-merge when checks pass
-  mergeStrategy: squash # squash commits
-  deleteBranch: true # cleanup after merge
-
+# Default behavior (auto-merge with squash, delete branch) - no prOptions needed
 repos:
-  # These repos use global prOptions (auto-merge)
+  # These repos use defaults (auto-merge with squash, delete branch)
   - git:
       - git@github.com:org/frontend.git
       - git@github.com:org/backend.git
 
+  # This repo overrides to manual (leave PR open for review)
+  - git: git@github.com:org/needs-review.git
+    prOptions:
+      merge: manual
+
   # This repo overrides to force merge (bypass required reviews)
   - git: git@github.com:org/internal-tool.git
     prOptions:
@@ -679,11 +679,11 @@ repos:
 
 **Merge Modes:**
 
-| Mode     | GitHub Behavior                         | Azure DevOps Behavior                  |
-| -------- | --------------------------------------- | -------------------------------------- |
-| `manual` | Leave PR open for review (default)      | Leave PR open for review               |
-| `auto`   | Enable auto-merge (requires repo setup) | Enable auto-complete                   |
-| `force`  | Merge with `--admin` (bypass checks)    | Bypass policies with `--bypass-policy` |
+| Mode     | GitHub Behavior                                      | Azure DevOps Behavior                  |
+| -------- | ---------------------------------------------------- | -------------------------------------- |
+| `manual` | Leave PR open for review                             | Leave PR open for review               |
+| `auto`   | Enable auto-merge (requires repo setup, **default**) | Enable auto-complete (**default**)     |
+| `force`  | Merge with `--admin` (bypass checks)                 | Bypass policies with `--bypass-policy` |
 
 **GitHub Auto-Merge Note:** The `auto` mode requires auto-merge to be enabled in the repository settings. If not enabled, the tool will warn and leave the PR open for manual review. Enable it with:
 
@@ -694,11 +694,11 @@ gh repo edit org/repo --enable-auto-merge
 **CLI Override:** You can override config file settings with CLI flags:
 
 ```bash
+# Disable auto-merge, leave PRs open for review
+xfg --config ./config.yaml --merge manual
+
 # Force merge all PRs (useful for urgent updates)
 xfg --config ./config.yaml --merge force
-
-# Enable auto-merge with squash
-xfg --config ./config.yaml --merge auto --merge-strategy squash --delete-branch
 ```
 
 ## Supported Git URL Formats
@@ -727,23 +727,28 @@ flowchart TB
     end
 
     subgraph Processing["For Each Repository"]
-        CLONE[Clone Repo] --> BRANCH[Create/Checkout Branch<br/>--branch or chore/sync-config]
-        BRANCH --> WRITE[Write All Config Files<br/>JSON, JSON5, or YAML]
+        CLONE[Clone Repo] --> DETECT_BRANCH[Detect Default Branch]
+        DETECT_BRANCH --> CLOSE_PR[Close Existing PR<br/>if exists]
+        CLOSE_PR --> BRANCH[Create Fresh Branch]
+        BRANCH --> WRITE[Write Config Files]
         WRITE --> CHECK{Changes?}
         CHECK -->|No| SKIP[Skip - No Changes]
-        CHECK -->|Yes| COMMIT[Commit Changes]
-        COMMIT --> PUSH[Push to Remote]
+        CHECK -->|Yes| COMMIT[Commit & Push]
     end
 
-    subgraph Platform["Platform Detection"]
-        PUSH --> DETECT{GitHub or<br/>Azure DevOps?}
+    subgraph Platform["PR Creation"]
+        COMMIT --> PR_DETECT{GitHub or<br/>Azure DevOps?}
+        PR_DETECT -->|GitHub| GH_PR[Create PR via gh CLI]
+        PR_DETECT -->|Azure DevOps| AZ_PR[Create PR via az CLI]
+        GH_PR --> PR_CREATED[PR Created]
+        AZ_PR --> PR_CREATED
     end
 
-    subgraph Output
-        DETECT -->|GitHub| GH_PR[Create PR via gh CLI]
-        DETECT -->|Azure DevOps| AZ_PR[Create PR via az CLI]
-        GH_PR --> GH_URL[/"GitHub PR URL"/]
-        AZ_PR --> AZ_URL[/"Azure DevOps PR URL"/]
+    subgraph AutoMerge["Auto-Merge (default)"]
+        PR_CREATED --> MERGE_MODE{Merge Mode?}
+        MERGE_MODE -->|manual| OPEN[Leave PR Open]
+        MERGE_MODE -->|auto| AUTO[Enable Auto-Merge]
+        MERGE_MODE -->|force| FORCE[Bypass & Merge]
     end
 
     YAML --> EXPAND
@@ -757,11 +762,14 @@ For each repository in the config, the tool:
 3. Interpolates environment variables
 4. Cleans the temporary workspace
 5. Clones the repository
-6. Creates/checks out branch (custom `--branch` or default `chore/sync-config`)
-7. Writes all config files (JSON, JSON5, or YAML based on filename extension)
-8. Checks for changes (skips if no changes)
-9. Commits and pushes changes
-10. Creates a pull request
+6. Detects the default branch (main/master)
+7. Closes any existing PR on the branch and deletes the remote branch (fresh start)
+8. Creates a fresh branch from the default branch
+9. Writes all config files (JSON, JSON5, YAML, or text based on filename extension)
+10. Checks for changes (skips if no changes)
+11. Commits and pushes changes
+12. Creates a pull request
+13. Handles auto-merge based on configuration (auto by default)
 
 ## CI/CD Integration
 
@@ -890,10 +898,12 @@ az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG
 
 ### Branch Already Exists
 
-The tool automatically reuses existing branches. If you see unexpected behavior:
+The tool uses a fresh-start approach: it closes any existing PR on the branch and deletes the branch before creating a new one. This ensures each sync attempt is isolated and avoids merge conflicts from stale branches.
+
+If you see issues with stale branches:
 
 ```bash
-# Delete the remote branch to start fresh
+# Manually delete the remote branch if needed
 git push origin --delete chore/sync-config
 ```
 
@@ -985,7 +995,3 @@ npm test
 # Build
 npm run build
 ```
-
-## License
-
-MIT

package/dist/config-normalizer.js

@@ -93,7 +93,10 @@ export function normalizeConfig(raw) {
                 else {
                     // Merge mode: handle text vs object content
                     if (isTextContent(fileConfig.content)) {
-                        // Text content merging
+                        // Text content merging - validate overlay is also text
+                        if (!isTextContent(repoOverride.content)) {
+                            throw new Error(`Expected text content for ${fileName}, got object`);
+                        }
                         mergedContent = mergeTextContent(fileConfig.content, repoOverride.content, fileStrategy);
                     }
                     else {

package/dist/config-validator.js

@@ -1,4 +1,4 @@
-import { isAbsolute } from "node:path";
+import { extname, isAbsolute } from "node:path";
 const VALID_STRATEGIES = ["replace", "append", "prepend"];
 /**
  * Check if content is text type (string or string[]).
@@ -18,8 +18,8 @@ function isObjectContent(content) {
  * Check if file extension is for structured output (JSON/YAML).
  */
 function isStructuredFileExtension(fileName) {
-    const ext = fileName.toLowerCase().split(".").pop();
-    return ext === "json" || ext === "json5" || ext === "yaml" || ext === "yml";
+    const ext = extname(fileName).toLowerCase();
+    return (ext === ".json" || ext === ".json5" || ext === ".yaml" || ext === ".yml");
 }
 /**
  * Validates raw config structure before normalization.

package/dist/diff-utils.d.ts

@@ -0,0 +1,31 @@
+export type FileStatus = "NEW" | "MODIFIED" | "UNCHANGED";
+/**
+ * Determines file status based on existence and change detection.
+ */
+export declare function getFileStatus(exists: boolean, changed: boolean): FileStatus;
+/**
+ * Format a status badge with appropriate color.
+ */
+export declare function formatStatusBadge(status: FileStatus): string;
+/**
+ * Format a single diff line with appropriate color.
+ */
+export declare function formatDiffLine(line: string): string;
+/**
+ * Generate a unified diff between old and new content.
+ * Returns an array of formatted diff lines.
+ */
+export declare function generateDiff(oldContent: string | null, newContent: string, fileName: string, contextLines?: number): string[];
+export interface DiffStats {
+    newCount: number;
+    modifiedCount: number;
+    unchangedCount: number;
+}
+/**
+ * Create an empty diff stats object.
+ */
+export declare function createDiffStats(): DiffStats;
+/**
+ * Increment the appropriate counter in diff stats.
+ */
+export declare function incrementDiffStats(stats: DiffStats, status: FileStatus): void;

package/dist/diff-utils.js

@@ -0,0 +1,223 @@
+import chalk from "chalk";
+/**
+ * Determines file status based on existence and change detection.
+ */
+export function getFileStatus(exists, changed) {
+    if (!exists)
+        return "NEW";
+    return changed ? "MODIFIED" : "UNCHANGED";
+}
+/**
+ * Format a status badge with appropriate color.
+ */
+export function formatStatusBadge(status) {
+    switch (status) {
+        case "NEW":
+            return chalk.green("[NEW]");
+        case "MODIFIED":
+            return chalk.yellow("[MODIFIED]");
+        case "UNCHANGED":
+            return chalk.gray("[UNCHANGED]");
+    }
+}
+/**
+ * Format a single diff line with appropriate color.
+ */
+export function formatDiffLine(line) {
+    if (line.startsWith("+"))
+        return chalk.green(line);
+    if (line.startsWith("-"))
+        return chalk.red(line);
+    if (line.startsWith("@@"))
+        return chalk.cyan(line);
+    return line;
+}
+/**
+ * Generate a unified diff between old and new content.
+ * Returns an array of formatted diff lines.
+ */
+export function generateDiff(oldContent, newContent, fileName, contextLines = 3) {
+    const oldLines = oldContent ? oldContent.split("\n") : [];
+    const newLines = newContent.split("\n");
+    // For new files, show all lines as additions
+    if (oldContent === null) {
+        const result = [];
+        for (const line of newLines) {
+            result.push(formatDiffLine(`+${line}`));
+        }
+        return result;
+    }
+    // Simple LCS-based diff algorithm
+    const hunks = computeDiffHunks(oldLines, newLines, contextLines);
+    if (hunks.length === 0) {
+        return [];
+    }
+    const result = [];
+    for (const hunk of hunks) {
+        result.push(formatDiffLine(`@@ -${hunk.oldStart},${hunk.oldCount} +${hunk.newStart},${hunk.newCount} @@`));
+        for (const line of hunk.lines) {
+            result.push(formatDiffLine(line));
+        }
+    }
+    return result;
+}
+/**
+ * Compute diff hunks using a simple line-by-line comparison.
+ * This is a simplified diff that shows changed regions with context.
+ */
+function computeDiffHunks(oldLines, newLines, contextLines) {
+    // Compute edit script using LCS
+    const editScript = computeEditScript(oldLines, newLines);
+    if (editScript.length === 0) {
+        return [];
+    }
+    // Group edits into hunks with context
+    return groupIntoHunks(editScript, oldLines, newLines, contextLines);
+}
+/**
+ * Compute an edit script using a simple O(mn) LCS algorithm.
+ */
+function computeEditScript(oldLines, newLines) {
+    const m = oldLines.length;
+    const n = newLines.length;
+    // Build LCS table
+    const lcs = Array(m + 1)
+        .fill(null)
+        .map(() => Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (oldLines[i - 1] === newLines[j - 1]) {
+                lcs[i][j] = lcs[i - 1][j - 1] + 1;
+            }
+            else {
+                lcs[i][j] = Math.max(lcs[i - 1][j], lcs[i][j - 1]);
+            }
+        }
+    }
+    // Backtrack to find edit script
+    const ops = [];
+    let i = m;
+    let j = n;
+    while (i > 0 || j > 0) {
+        if (i > 0 && j > 0 && oldLines[i - 1] === newLines[j - 1]) {
+            ops.unshift({ type: "keep", oldIdx: i - 1, newIdx: j - 1 });
+            i--;
+            j--;
+        }
+        else if (j > 0 && (i === 0 || lcs[i][j - 1] >= lcs[i - 1][j])) {
+            ops.unshift({ type: "insert", newIdx: j - 1 });
+            j--;
+        }
+        else {
+            ops.unshift({ type: "delete", oldIdx: i - 1 });
+            i--;
+        }
+    }
+    return ops;
+}
+/**
+ * Group edit operations into hunks with context lines.
+ */
+function groupIntoHunks(ops, oldLines, newLines, contextLines) {
+    // Find ranges of changes
+    const changeRanges = [];
+    let inChange = false;
+    let changeStart = 0;
+    for (let i = 0; i < ops.length; i++) {
+        const op = ops[i];
+        if (op.type !== "keep") {
+            if (!inChange) {
+                inChange = true;
+                changeStart = i;
+            }
+        }
+        else if (inChange) {
+            changeRanges.push({ start: changeStart, end: i });
+            inChange = false;
+        }
+    }
+    if (inChange) {
+        changeRanges.push({ start: changeStart, end: ops.length });
+    }
+    if (changeRanges.length === 0) {
+        return [];
+    }
+    // Merge ranges that are close together (within 2*contextLines)
+    const mergedRanges = [];
+    let currentRange = { ...changeRanges[0] };
+    for (let i = 1; i < changeRanges.length; i++) {
+        const range = changeRanges[i];
+        if (range.start - currentRange.end <= contextLines * 2) {
+            currentRange.end = range.end;
+        }
+        else {
+            mergedRanges.push(currentRange);
+            currentRange = { ...range };
+        }
+    }
+    mergedRanges.push(currentRange);
+    // Build hunks with context
+    const hunks = [];
+    for (const range of mergedRanges) {
+        const contextStart = Math.max(0, range.start - contextLines);
+        const contextEnd = Math.min(ops.length, range.end + contextLines);
+        const hunkOps = ops.slice(contextStart, contextEnd);
+        const lines = [];
+        let oldStart = 1;
+        let newStart = 1;
+        let oldCount = 0;
+        let newCount = 0;
+        // Calculate starting positions
+        for (let i = 0; i < contextStart; i++) {
+            const op = ops[i];
+            if (op.type === "keep" || op.type === "delete") {
+                oldStart++;
+            }
+            if (op.type === "keep" || op.type === "insert") {
+                newStart++;
+            }
+        }
+        // Build hunk lines
+        for (const op of hunkOps) {
+            switch (op.type) {
+                case "keep":
+                    lines.push(` ${oldLines[op.oldIdx]}`);
+                    oldCount++;
+                    newCount++;
+                    break;
+                case "delete":
+                    lines.push(`-${oldLines[op.oldIdx]}`);
+                    oldCount++;
+                    break;
+                case "insert":
+                    lines.push(`+${newLines[op.newIdx]}`);
+                    newCount++;
+                    break;
+            }
+        }
+        hunks.push({ oldStart, oldCount, newStart, newCount, lines });
+    }
+    return hunks;
+}
+/**
+ * Create an empty diff stats object.
+ */
+export function createDiffStats() {
+    return { newCount: 0, modifiedCount: 0, unchangedCount: 0 };
+}
+/**
+ * Increment the appropriate counter in diff stats.
+ */
+export function incrementDiffStats(stats, status) {
+    switch (status) {
+        case "NEW":
+            stats.newCount++;
+            break;
+        case "MODIFIED":
+            stats.modifiedCount++;
+            break;
+        case "UNCHANGED":
+            stats.unchangedCount++;
+            break;
+    }
+}

package/dist/file-reference-resolver.js

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { resolve, isAbsolute, normalize, extname } from "node:path";
+import { resolve, isAbsolute, normalize, extname, relative } from "node:path";
 import JSON5 from "json5";
 import { parse as parseYaml } from "yaml";
 /**
@@ -27,9 +27,11 @@ export function resolveFileReference(reference, configDir) {
     const normalizedResolved = normalize(resolvedPath);
     const normalizedConfigDir = normalize(configDir);
     // Security: ensure path stays within config directory tree
-    // Use path separator to ensure we're checking directory boundaries
-    if (!normalizedResolved.startsWith(normalizedConfigDir + "/") &&
-        normalizedResolved !== normalizedConfigDir) {
+    // Fix for issue #89: Use path.relative() instead of hardcoded "/" separator
+    // The old approach (!path.startsWith(configDir + "/")) fails on Windows
+    // where normalize() returns paths with backslash separators.
+    const pathFromConfig = relative(normalizedConfigDir, normalizedResolved);
+    if (pathFromConfig.startsWith("..") || isAbsolute(pathFromConfig)) {
         throw new Error(`File reference "${reference}" escapes config directory. ` +
             `References must be within "${configDir}".`);
     }

package/dist/git-ops.d.ts

@@ -34,17 +34,29 @@ export declare class GitOps {
     createBranch(branchName: string): Promise<void>;
     writeFile(fileName: string, content: string): void;
     /**
-     * Marks a file as executable in git using update-index --chmod=+x.
-     * This modifies the file mode in git's index, not the filesystem.
+     * Marks a file as executable both on the filesystem and in git's index.
+     * - Filesystem: Uses chmod to set 755 permissions (rwxr-xr-x)
+     * - Git index: Uses update-index --chmod=+x so the mode is committed
      * @param fileName - The file path relative to the work directory
      */
     setExecutable(fileName: string): Promise<void>;
+    /**
+     * Get the content of a file in the workspace.
+     * Returns null if the file doesn't exist.
+     */
+    getFileContent(fileName: string): string | null;
     /**
      * Checks if writing the given content would result in changes.
      * Works in both normal and dry-run modes by comparing content directly.
      */
     wouldChange(fileName: string, content: string): boolean;
     hasChanges(): Promise<boolean>;
+    /**
+     * Get list of files that have changes according to git status.
+     * Returns relative file paths for files that are modified, added, or untracked.
+     * Uses the same this.exec() pattern as other methods in this class.
+     */
+    getChangedFiles(): Promise<string[]>;
     /**
      * Check if there are staged changes ready to commit.
      * Uses `git diff --cached --quiet` which exits with 1 if there are staged changes.

package/dist/git-ops.js

@@ -1,4 +1,4 @@
-import { rmSync, existsSync, mkdirSync, writeFileSync, readFileSync, } from "node:fs";
+import { rmSync, existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, } from "node:fs";
 import { join, resolve, relative, isAbsolute, dirname } from "node:path";
 import { escapeShellArg } from "./shell-utils.js";
 import { defaultExecutor } from "./command-executor.js";
@@ -77,8 +77,9 @@ export class GitOps {
         writeFileSync(filePath, normalized, "utf-8");
     }
     /**
-     * Marks a file as executable in git using update-index --chmod=+x.
-     * This modifies the file mode in git's index, not the filesystem.
+     * Marks a file as executable both on the filesystem and in git's index.
+     * - Filesystem: Uses chmod to set 755 permissions (rwxr-xr-x)
+     * - Git index: Uses update-index --chmod=+x so the mode is committed
      * @param fileName - The file path relative to the work directory
      */
     async setExecutable(fileName) {
@@ -86,10 +87,28 @@ export class GitOps {
             return;
         }
         const filePath = this.validatePath(fileName);
-        // Use relative path from workDir for git command
+        // Set filesystem permissions (755 = rwxr-xr-x)
+        chmodSync(filePath, 0o755);
+        // Also update git's index so the executable bit is committed
         const relativePath = relative(this.workDir, filePath);
         await this.exec(`git update-index --add --chmod=+x ${escapeShellArg(relativePath)}`, this.workDir);
     }
+    /**
+     * Get the content of a file in the workspace.
+     * Returns null if the file doesn't exist.
+     */
+    getFileContent(fileName) {
+        const filePath = this.validatePath(fileName);
+        if (!existsSync(filePath)) {
+            return null;
+        }
+        try {
+            return readFileSync(filePath, "utf-8");
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Checks if writing the given content would result in changes.
      * Works in both normal and dry-run modes by comparing content directly.
@@ -115,6 +134,20 @@ export class GitOps {
         const status = await this.exec("git status --porcelain", this.workDir);
         return status.length > 0;
     }
+    /**
+     * Get list of files that have changes according to git status.
+     * Returns relative file paths for files that are modified, added, or untracked.
+     * Uses the same this.exec() pattern as other methods in this class.
+     */
+    async getChangedFiles() {
+        const status = await this.exec("git status --porcelain", this.workDir);
+        if (!status)
+            return [];
+        return status
+            .split("\n")
+            .filter((line) => line.length > 0)
+            .map((line) => line.slice(3)); // Remove status prefix (e.g., " M ", "?? ", "A  ")
+    }
     /**
      * Check if there are staged changes ready to commit.
      * Uses `git diff --cached --quiet` which exits with 1 if there are staged changes.

package/dist/logger.d.ts

@@ -1,5 +1,8 @@
+import { FileStatus } from "./diff-utils.js";
 export interface ILogger {
     info(message: string): void;
+    fileDiff(fileName: string, status: FileStatus, diffLines: string[]): void;
+    diffSummary(newCount: number, modifiedCount: number, unchangedCount: number): void;
 }
 export interface LoggerStats {
     total: number;
@@ -15,6 +18,15 @@ export declare class Logger {
     success(current: number, repoName: string, message: string): void;
     skip(current: number, repoName: string, reason: string): void;
     error(current: number, repoName: string, error: string): void;
+    /**
+     * Display a file diff with status badge.
+     * Used in dry-run mode to show what would change.
+     */
+    fileDiff(fileName: string, status: FileStatus, diffLines: string[]): void;
+    /**
+     * Display summary statistics for dry-run diff.
+     */
+    diffSummary(newCount: number, modifiedCount: number, unchangedCount: number): void;
     summary(): void;
     hasFailures(): boolean;
 }

package/dist/logger.js

@@ -1,4 +1,5 @@
 import chalk from "chalk";
+import { formatStatusBadge } from "./diff-utils.js";
 export class Logger {
     stats = {
         total: 0,
@@ -31,6 +32,35 @@ export class Logger {
         console.log(chalk.red(`[${current}/${this.stats.total}] ✗`) +
             ` ${repoName}: ${error}`);
     }
+    /**
+     * Display a file diff with status badge.
+     * Used in dry-run mode to show what would change.
+     */
+    fileDiff(fileName, status, diffLines) {
+        const badge = formatStatusBadge(status);
+        console.log(`    ${badge} ${fileName}`);
+        // Only show diff lines for NEW or MODIFIED files
+        if (status !== "UNCHANGED" && diffLines.length > 0) {
+            for (const line of diffLines) {
+                console.log(`      ${line}`);
+            }
+        }
+    }
+    /**
+     * Display summary statistics for dry-run diff.
+     */
+    diffSummary(newCount, modifiedCount, unchangedCount) {
+        const parts = [];
+        if (newCount > 0)
+            parts.push(chalk.green(`${newCount} new`));
+        if (modifiedCount > 0)
+            parts.push(chalk.yellow(`${modifiedCount} modified`));
+        if (unchangedCount > 0)
+            parts.push(chalk.gray(`${unchangedCount} unchanged`));
+        if (parts.length > 0) {
+            console.log(chalk.gray(`    Summary: ${parts.join(", ")}`));
+        }
+    }
     summary() {
         console.log("");
         console.log(chalk.bold("Summary:"));

package/dist/repository-processor.js

@@ -7,6 +7,7 @@ import { createPR, mergePR } from "./pr-creator.js";
 import { logger } from "./logger.js";
 import { getPRStrategy } from "./strategies/index.js";
 import { defaultExecutor } from "./command-executor.js";
+import { getFileStatus, generateDiff, createDiffStats, incrementDiffStats, } from "./diff-utils.js";
 /**
  * Determines if a file should be marked as executable.
  * .sh files are auto-executable unless explicit executable: false is set.
@@ -69,7 +70,19 @@ export class RepositoryProcessor {
             this.log.info(`Creating branch: ${branchName}`);
             await this.gitOps.createBranch(branchName);
             // Step 5: Write all config files and track changes
+            //
+            // DESIGN NOTE: Change detection differs between dry-run and normal mode:
+            // - Dry-run: Uses wouldChange() for read-only content comparison (no side effects)
+            // - Normal: Uses git status after writing (source of truth for what git will commit)
+            //
+            // This is intentional. git status is more accurate because it respects .gitattributes
+            // (line ending normalization, filters) and detects executable bit changes. However,
+            // it requires actually writing files, which defeats dry-run's purpose.
+            //
+            // For config files (JSON/YAML), these approaches produce identical results in practice.
+            // Edge cases (repos with unusual git attributes on config files) are essentially nonexistent.
             const changedFiles = [];
+            const diffStats = createDiffStats();
             for (const file of repoConfig.files) {
                 const filePath = join(workDir, file.fileName);
                 const fileExistsLocal = existsSync(filePath);
@@ -93,10 +106,18 @@ export class RepositoryProcessor {
                     ? "update"
                     : "create";
                 if (dryRun) {
-                    // In dry-run, check if file would change without writing
-                    if (this.gitOps.wouldChange(file.fileName, fileContent)) {
+                    // In dry-run, check if file would change and show diff
+                    const existingContent = this.gitOps.getFileContent(file.fileName);
+                    const changed = this.gitOps.wouldChange(file.fileName, fileContent);
+                    const status = getFileStatus(existingContent !== null, changed);
+                    // Track stats
+                    incrementDiffStats(diffStats, status);
+                    if (changed) {
                         changedFiles.push({ fileName: file.fileName, action });
                     }
+                    // Generate and display diff
+                    const diffLines = generateDiff(existingContent, fileContent, file.fileName);
+                    this.log.fileDiff(file.fileName, status, diffLines);
                 }
                 else {
                     // Write the file
@@ -115,6 +136,10 @@ export class RepositoryProcessor {
                     await this.gitOps.setExecutable(file.fileName);
                 }
             }
+            // Show diff summary in dry-run mode
+            if (dryRun) {
+                this.log.diffSummary(diffStats.newCount, diffStats.modifiedCount, diffStats.unchangedCount);
+            }
             // Step 6: Check for changes (exclude skipped files)
             let hasChanges;
             if (dryRun) {
@@ -124,15 +149,21 @@ export class RepositoryProcessor {
                 hasChanges = await this.gitOps.hasChanges();
                 // If there are changes, determine which files changed
                 if (hasChanges) {
-                    // Rebuild the changed files list by checking git status
-                    // Skip files that were already marked as skipped (createOnly)
+                    // Get the actual list of changed files from git status
+                    const gitChangedFiles = new Set(await this.gitOps.getChangedFiles());
+                    // Preserve skipped files (createOnly)
                     const skippedFiles = new Set(changedFiles
                         .filter((f) => f.action === "skip")
                         .map((f) => f.fileName));
+                    // Only add files that actually changed according to git
                     for (const file of repoConfig.files) {
                         if (skippedFiles.has(file.fileName)) {
                             continue; // Already tracked as skipped
                         }
+                        // Only include files that git reports as changed
+                        if (!gitChangedFiles.has(file.fileName)) {
+                            continue; // File didn't actually change
+                        }
                         const filePath = join(workDir, file.fileName);
                         const action = existsSync(filePath)
                             ? "update"

package/dist/shell-utils.js

@@ -6,6 +6,10 @@
  * @returns The escaped string wrapped in single quotes
  */
 export function escapeShellArg(arg) {
+    // Defense-in-depth: reject null bytes even if upstream validation should catch them
+    if (arg.includes("\0")) {
+        throw new Error("Shell argument contains null byte");
+    }
     // Use single quotes and escape any single quotes within
     // 'string' -> quote ends, escaped quote, quote starts again
     return `'${arg.replace(/'/g, "'\\''")}'`;

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

@@ -52,8 +52,7 @@ export class GitHubPRStrategy extends BasePRStrategy {
         // Extract PR number from URL
         const prNumber = existingUrl.match(/\/pull\/(\d+)/)?.[1];
         if (!prNumber) {
-            logger.info(`Warning: Could not extract PR number from URL: ${existingUrl}`);
-            return false;
+            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`;
@@ -78,10 +77,13 @@ export class GitHubPRStrategy extends BasePRStrategy {
         const command = `gh pr create --title ${escapeShellArg(title)} --body-file ${escapeShellArg(bodyFile)} --base ${escapeShellArg(baseBranch)} --head ${escapeShellArg(branchName)}`;
         try {
             const result = await withRetry(() => this.executor.exec(command, workDir), { retries });
-            // Extract URL from output
-            const urlMatch = result.match(/https:\/\/github\.com\/[^\s]+/);
+            // Extract URL from output - use strict regex for valid PR URLs only
+            const urlMatch = result.match(/https:\/\/github\.com\/[\w-]+\/[\w.-]+\/pull\/\d+/);
+            if (!urlMatch) {
+                throw new Error(`Could not parse PR URL from output: ${result}`);
+            }
             return {
-                url: urlMatch?.[0] ?? result,
+                url: urlMatch[0],
                 success: true,
                 message: "PR created successfully",
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "CLI tool to sync JSON or YAML configuration files across multiple GitHub and Azure DevOps repositories",
   "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/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",
+    "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/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:integration": "npm run build && node --import tsx --test src/integration.test.ts",
     "prepublishOnly": "npm run build"
   },