@aspruyt/xfg 1.0.3 → 1.2.0

package/README.md

@@ -5,7 +5,7 @@
 [![npm downloads](https://img.shields.io/npm/dw/@aspruyt/xfg.svg)](https://www.npmjs.com/package/@aspruyt/xfg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-A CLI tool that syncs JSON, JSON5, YAML, or text configuration files across multiple GitHub and Azure DevOps repositories by creating pull requests. Output format is automatically detected from the target filename extension (`.json` → JSON, `.json5` → JSON5, `.yaml`/`.yml` → YAML, other → text).
+A CLI tool that syncs JSON, JSON5, YAML, or text configuration files across multiple GitHub, Azure DevOps, and GitLab repositories by creating pull requests (or merge requests for GitLab). Output format is automatically detected from the target filename extension (`.json` → JSON, `.json5` → JSON5, `.yaml`/`.yml` → YAML, other → text).
 
 ## Table of Contents
 
@@ -72,7 +72,7 @@ xfg --config ./config.yaml
 - **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
-- **GitHub & Azure DevOps** - Works with both platforms
+- **Multi-Platform** - Works with GitHub, 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
@@ -118,6 +118,20 @@ az login
 az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT
 ```
 
+### GitLab Authentication
+
+Before using with GitLab repositories, authenticate with the GitLab CLI:
+
+```bash
+glab auth login
+```
+
+For self-hosted GitLab instances:
+
+```bash
+glab auth login --hostname gitlab.example.com
+```
+
 ## Usage
 
 ```bash
@@ -136,16 +150,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 +211,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 +663,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 +672,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 +693,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                  | GitLab Behavior                            |
+| -------- | ---------------------------------------------------- | -------------------------------------- | ------------------------------------------ |
+| `manual` | Leave PR open for review                             | Leave PR open for review               | Leave MR open for review                   |
+| `auto`   | Enable auto-merge (requires repo setup, **default**) | Enable auto-complete (**default**)     | Merge when pipeline succeeds (**default**) |
+| `force`  | Merge with `--admin` (bypass checks)                 | Bypass policies with `--bypass-policy` | Merge immediately                          |
 
 **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 +708,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
@@ -713,6 +727,14 @@ xfg --config ./config.yaml --merge auto --merge-strategy squash --delete-branch
 - SSH: `git@ssh.dev.azure.com:v3/organization/project/repo`
 - HTTPS: `https://dev.azure.com/organization/project/_git/repo`
 
+### GitLab
+
+- SSH: `git@gitlab.com:owner/repo.git`
+- HTTPS: `https://gitlab.com/owner/repo.git`
+- Nested groups: `git@gitlab.com:org/group/subgroup/repo.git`
+- Self-hosted SSH: `git@gitlab.example.com:owner/repo.git`
+- Self-hosted HTTPS: `https://gitlab.example.com/owner/repo.git`
+
 ## How It Works
 
 ```mermaid
@@ -727,23 +749,30 @@ 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{Platform?}
+        PR_DETECT -->|GitHub| GH_PR[Create PR via gh CLI]
+        PR_DETECT -->|Azure DevOps| AZ_PR[Create PR via az CLI]
+        PR_DETECT -->|GitLab| GL_PR[Create MR via glab CLI]
+        GH_PR --> PR_CREATED[PR/MR Created]
+        AZ_PR --> PR_CREATED
+        GL_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 +786,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
 
@@ -882,18 +914,34 @@ az login
 az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG
 ```
 
+**GitLab:**
+
+```bash
+# Check authentication status
+glab auth status
+
+# Re-authenticate if needed
+glab auth login
+
+# For self-hosted instances
+glab auth login --hostname gitlab.example.com
+```
+
 ### Permission Denied
 
 - Ensure your token has write access to the target repositories
 - For GitHub, the token needs `repo` scope
 - For Azure DevOps, ensure the user/service account has "Contribute to pull requests" permission
+- For GitLab, ensure the user has at least "Developer" role on the project
 
 ### 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 +1033,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

@@ -40,12 +40,23 @@ export declare class GitOps {
      * @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

@@ -93,6 +93,22 @@ export class GitOps {
         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.
@@ -118,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;
 }