@aspruyt/json-config-sync 2.1.1 → 3.1.0

package/README.md

@@ -1,7 +1,6 @@
 # json-config-sync
 
-[![CI](https://github.com/anthony-spruyt/json-config-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/anthony-spruyt/json-config-sync/actions/workflows/ci.yml)
-[![Integration Test](https://github.com/anthony-spruyt/json-config-sync/actions/workflows/integration-test.yml/badge.svg?branch=main)](https://github.com/anthony-spruyt/json-config-sync/actions/workflows/integration-test.yml)
+[![CI](https://github.com/anthony-spruyt/json-config-sync/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/anthony-spruyt/json-config-sync/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@aspruyt/json-config-sync.svg)](https://www.npmjs.com/package/@aspruyt/json-config-sync)
 [![npm downloads](https://img.shields.io/npm/dw/@aspruyt/json-config-sync.svg)](https://www.npmjs.com/package/@aspruyt/json-config-sync)
 
@@ -36,14 +35,13 @@ gh auth login
 
 # Create config.yaml
 cat > config.yaml << 'EOF'
-fileName: .prettierrc.json
-
-# Base configuration inherited by all repos
-content:
-  semi: false
-  singleQuote: true
-  tabWidth: 2
-  trailingComma: es5
+files:
+  .prettierrc.json:
+    content:
+      semi: false
+      singleQuote: true
+      tabWidth: 2
+      trailingComma: es5
 
 repos:
   # Multiple repos can share the same config
@@ -61,6 +59,7 @@ json-config-sync --config ./config.yaml
 
 ## Features
 
+- **Multi-File Sync** - Sync multiple config files in a single run
 - **JSON/YAML Output** - Automatically outputs JSON or YAML based on filename extension
 - **Content Inheritance** - Define base config once, override per-repo as needed
 - **Multi-Repo Targeting** - Apply same config to multiple repos with array syntax
@@ -130,61 +129,86 @@ json-config-sync --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-{filename}`) | 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-config`)   | No       |
 
 ## Configuration Format
 
 ### Basic Structure
 
 ```yaml
-fileName: my.config.json # Target file (.json outputs JSON, .yaml/.yml outputs YAML)
-mergeStrategy: replace # Default array merge strategy (optional)
-
-content: # Base config content (optional)
-  key: value
+files:
+  my.config.json: # Target file (.json outputs JSON, .yaml/.yml outputs YAML)
+    mergeStrategy: replace # Array merge strategy for this file (optional)
+    content: # Base config content
+      key: value
 
 repos: # List of repositories
   - git: git@github.com:org/repo.git
-    content: # Per-repo overlay (optional if base content exists)
-      key: override
+    files: # Per-repo file overrides (optional)
+      my.config.json:
+        content:
+          key: override
 ```
 
 ### Root-Level Fields
 
-| Field           | Description                                                            | Required |
-| --------------- | ---------------------------------------------------------------------- | -------- |
-| `fileName`      | Target file name (`.json` → JSON output, `.yaml`/`.yml` → YAML output) | Yes      |
-| `content`       | Base config inherited by all repos                                     | No\*     |
-| `mergeStrategy` | Default array merge strategy: `replace`, `append`, `prepend`           | No       |
-| `repos`         | Array of repository configurations                                     | Yes      |
+| Field   | Description                        | Required |
+| ------- | ---------------------------------- | -------- |
+| `files` | Map of target filenames to configs | Yes      |
+| `repos` | Array of repository configurations | Yes      |
 
-\* Required if any repo entry omits the `content` field.
+### Per-File Fields
+
+| Field           | Description                                          | Required |
+| --------------- | ---------------------------------------------------- | -------- |
+| `content`       | Base config inherited by all repos                   | Yes      |
+| `mergeStrategy` | Array merge strategy: `replace`, `append`, `prepend` | No       |
+| `createOnly`    | If `true`, only create file if it doesn't exist      | No       |
 
 ### Per-Repo Fields
 
-| Field      | Description                                                | Required |
-| ---------- | ---------------------------------------------------------- | -------- |
-| `git`      | Git URL (string) or array of URLs                          | Yes      |
-| `content`  | Content overlay merged onto base (optional if base exists) | No\*     |
-| `override` | If `true`, ignore base content and use only this repo's    | No       |
+| Field   | Description                        | Required |
+| ------- | ---------------------------------- | -------- |
+| `git`   | Git URL (string) or array of URLs  | Yes      |
+| `files` | Per-repo file overrides (optional) | No       |
+
+### Per-Repo File Override Fields
 
-\* Required if no root-level `content` is defined.
+| Field        | Description                                             | Required |
+| ------------ | ------------------------------------------------------- | -------- |
+| `content`    | Content overlay merged onto file's base content         | No       |
+| `override`   | If `true`, ignore base content and use only this repo's | No       |
+| `createOnly` | Override root-level `createOnly` for this repo          | No       |
+
+**File Exclusion:** Set a file to `false` to exclude it from a specific repo:
+
+```yaml
+repos:
+  - git: git@github.com:org/repo.git
+    files:
+      eslint.json: false # This repo won't receive eslint.json
+```
 
 ### Environment Variables
 
 Use `${VAR}` syntax in string values:
 
 ```yaml
-content:
-  apiUrl: ${API_URL} # Required - errors if not set
-  environment: ${ENV:-development} # With default value
-  secretKey: ${SECRET:?Secret required} # Required with custom error message
+files:
+  app.config.json:
+    content:
+      apiUrl: ${API_URL} # Required - errors if not set
+      environment: ${ENV:-development} # With default value
+      secretKey: ${SECRET:?Secret required} # Required with custom error message
+
+repos:
+  - git: git@github.com:org/backend.git
 ```
 
 ### Merge Directives
@@ -192,66 +216,106 @@ content:
 Control array merging with the `$arrayMerge` directive:
 
 ```yaml
-content:
-  features:
-    - core
-    - monitoring
+files:
+  config.json:
+    content:
+      features:
+        - core
+        - monitoring
 
 repos:
   - git: git@github.com:org/repo.git
-    content:
-      features:
-        $arrayMerge: append # append | prepend | replace
-        values:
-          - custom-feature # Results in: [core, monitoring, custom-feature]
+    files:
+      config.json:
+        content:
+          features:
+            $arrayMerge: append # append | prepend | replace
+            values:
+              - custom-feature # Results in: [core, monitoring, custom-feature]
 ```
 
 ## Examples
 
+### Multi-File Sync
+
+Sync multiple configuration files to all repos:
+
+```yaml
+files:
+  .eslintrc.json:
+    content:
+      extends: ["@org/eslint-config"]
+      rules:
+        no-console: warn
+
+  .prettierrc.yaml:
+    content:
+      semi: false
+      singleQuote: true
+
+  tsconfig.json:
+    content:
+      compilerOptions:
+        strict: true
+        target: ES2022
+
+repos:
+  - git:
+      - git@github.com:org/frontend.git
+      - git@github.com:org/backend.git
+      - git@github.com:org/shared-lib.git
+```
+
 ### Shared Config Across Teams
 
 Define common settings once, customize per team:
 
 ```yaml
-fileName: service.config.json
-
-content:
-  version: "2.0"
-  logging:
-    level: info
-    format: json
-  features:
-    - health-check
-    - metrics
+files:
+  service.config.json:
+    content:
+      version: "2.0"
+      logging:
+        level: info
+        format: json
+      features:
+        - health-check
+        - metrics
 
 repos:
   # Platform team repos - add extra features
   - git:
       - git@github.com:org/api-gateway.git
       - git@github.com:org/auth-service.git
-    content:
-      team: platform
-      features:
-        $arrayMerge: append
-        values:
-          - tracing
-          - rate-limiting
+    files:
+      service.config.json:
+        content:
+          team: platform
+          features:
+            $arrayMerge: append
+            values:
+              - tracing
+              - rate-limiting
 
   # Data team repos - different logging
   - git:
       - git@github.com:org/data-pipeline.git
       - git@github.com:org/analytics.git
-    content:
-      team: data
-      logging:
-        level: debug
+    files:
+      service.config.json:
+        content:
+          team: data
+          logging:
+            level: debug
 
   # Legacy service - completely different config
   - git: git@github.com:org/legacy-api.git
-    override: true
-    content:
-      version: "1.0"
-      legacy: true
+    files:
+      service.config.json:
+        override: true
+        content:
+          version: "1.0"
+          legacy: true
 ```
 
 ### Environment-Specific Values
@@ -259,40 +323,79 @@ repos:
 Use environment variables for secrets and environment-specific values:
 
 ```yaml
-fileName: app.config.json
-
-content:
-  database:
-    host: ${DB_HOST:-localhost}
-    port: ${DB_PORT:-5432}
-    password: ${DB_PASSWORD:?Database password required}
+files:
+  app.config.json:
+    content:
+      database:
+        host: ${DB_HOST:-localhost}
+        port: ${DB_PORT:-5432}
+        password: ${DB_PASSWORD:?Database password required}
 
-  api:
-    baseUrl: ${API_BASE_URL}
-    timeout: 30000
+      api:
+        baseUrl: ${API_BASE_URL}
+        timeout: 30000
 
 repos:
   - git: git@github.com:org/backend.git
 ```
 
-### Simple Multi-Repo Sync
+### Per-File Merge Strategies
 
-When all repos need identical config:
+Different files can use different array merge strategies:
 
 ```yaml
-fileName: .eslintrc.json
+files:
+  eslint.config.json:
+    mergeStrategy: append # Extends will append
+    content:
+      extends: ["@company/base"]
 
-content:
-  extends: ["@org/eslint-config"]
-  rules:
-    no-console: warn
+  tsconfig.json:
+    mergeStrategy: replace # Lib will replace entirely
+    content:
+      compilerOptions:
+        lib: ["ES2022"]
 
 repos:
-  - git:
-      - git@github.com:org/frontend.git
-      - git@github.com:org/backend.git
-      - git@github.com:org/shared-lib.git
-      - git@github.com:org/cli-tool.git
+  - git: git@github.com:org/frontend.git
+    files:
+      eslint.config.json:
+        content:
+          extends: ["plugin:react/recommended"]
+      # Results in extends: ["@company/base", "plugin:react/recommended"]
+```
+
+### Create-Only Files (Defaults That Can Be Customized)
+
+Some files should only be created once as defaults, allowing repos to maintain their own versions:
+
+```yaml
+files:
+  .trivyignore.yaml:
+    createOnly: true # Only create if doesn't exist
+    content:
+      vulnerabilities: []
+
+  .prettierignore:
+    createOnly: true
+    content:
+      patterns:
+        - "dist/"
+        - "node_modules/"
+
+  eslint.config.json:
+    content: # Always synced (no createOnly)
+      extends: ["@company/base"]
+
+repos:
+  - git: git@github.com:org/repo.git
+    # .trivyignore.yaml and .prettierignore only created if missing
+    # eslint.config.json always updated
+
+  - git: git@github.com:org/special-repo.git
+    files:
+      .trivyignore.yaml:
+        createOnly: false # Override: always sync this file
 ```
 
 ## Supported Git URL Formats
@@ -312,17 +415,17 @@ repos:
 ```mermaid
 flowchart TB
     subgraph Input
-        YAML[/"YAML Config File<br/>fileName + content + repos[]"/]
+        YAML[/"YAML Config File<br/>files{} + repos[]"/]
     end
 
     subgraph Normalization
-        EXPAND[Expand git arrays] --> MERGE[Merge base + overlay content]
+        EXPAND[Expand git arrays] --> MERGE[Merge base + overlay content<br/>for each file]
         MERGE --> ENV[Interpolate env vars]
     end
 
     subgraph Processing["For Each Repository"]
-        CLONE[Clone Repo] --> BRANCH[Create/Checkout Branch<br/>--branch or chore/sync-filename]
-        BRANCH --> WRITE[Write Config File<br/>JSON or YAML]
+        CLONE[Clone Repo] --> BRANCH[Create/Checkout Branch<br/>--branch or chore/sync-config]
+        BRANCH --> WRITE[Write All Config Files<br/>JSON or YAML]
         WRITE --> CHECK{Changes?}
         CHECK -->|No| SKIP[Skip - No Changes]
         CHECK -->|Yes| COMMIT[Commit Changes]
@@ -347,12 +450,12 @@ flowchart TB
 For each repository in the config, the tool:
 
 1. Expands git URL arrays into individual entries
-2. Merges base content with per-repo overlay
+2. For each file, merges base content with per-repo overlay
 3. Interpolates environment variables
 4. Cleans the temporary workspace
 5. Clones the repository
-6. Creates/checks out branch (custom `--branch` or default `chore/sync-{sanitized-filename}`)
-7. Generates the config file (JSON or YAML based on filename extension)
+6. Creates/checks out branch (custom `--branch` or default `chore/sync-config`)
+7. Writes all config files (JSON or YAML based on filename extension)
 8. Checks for changes (skips if no changes)
 9. Commits and pushes changes
 10. Creates a pull request
@@ -417,22 +520,25 @@ steps:
 ```
 [1/3] Processing example-org/repo1...
   ✓ Cloned repository
-  ✓ Created branch chore/sync-my-config
-  ✓ Wrote my.config.json
+  ✓ Created branch chore/sync-config
+  ✓ Wrote .eslintrc.json
+  ✓ Wrote .prettierrc.yaml
   ✓ Committed changes
   ✓ Pushed to remote
   ✓ Created PR: https://github.com/example-org/repo1/pull/42
 
 [2/3] Processing example-org/repo2...
   ✓ Cloned repository
-  ✓ Checked out existing branch chore/sync-my-config
-  ✓ Wrote my.config.json
+  ✓ Checked out existing branch chore/sync-config
+  ✓ Wrote .eslintrc.json
+  ✓ Wrote .prettierrc.yaml
   ⊘ No changes detected, skipping
 
 [3/3] Processing example-org/repo3...
   ✓ Cloned repository
-  ✓ Created branch chore/sync-my-config
-  ✓ Wrote my.config.json
+  ✓ Created branch chore/sync-config
+  ✓ Wrote .eslintrc.json
+  ✓ Wrote .prettierrc.yaml
   ✓ Committed changes
   ✓ Pushed to remote
   ✓ PR already exists: https://github.com/example-org/repo3/pull/15
@@ -444,9 +550,9 @@ Summary: 2 succeeded, 1 skipped, 0 failed
 
 The tool creates PRs with:
 
-- **Title:** `chore: sync {fileName}`
-- **Branch:** `chore/sync-{sanitized-filename}`
-- **Body:** Describes the sync action and links to documentation
+- **Title:** `chore: sync config files` (or lists files if ≤3)
+- **Branch:** `chore/sync-config` (or custom `--branch`)
+- **Body:** Describes the sync action and lists changed files
 
 ## Troubleshooting
 
@@ -485,7 +591,7 @@ The tool automatically reuses existing branches. If you see unexpected behavior:
 
 ```bash
 # Delete the remote branch to start fresh
-git push origin --delete chore/sync-my-config
+git push origin --delete chore/sync-config
 ```
 
 ### Missing Environment Variables
@@ -535,9 +641,11 @@ For autocomplete and validation in VS Code, install the [YAML extension](https:/
 
 ```yaml
 # yaml-language-server: $schema=https://raw.githubusercontent.com/anthony-spruyt/json-config-sync/main/config-schema.json
-fileName: my.config.json
-content:
-  key: value
+files:
+  my.config.json:
+    content:
+      key: value
+
 repos:
   - git: git@github.com:org/repo.git
 ```
@@ -557,7 +665,7 @@ repos:
 
 This enables:
 
-- Autocomplete for `fileName`, `mergeStrategy`, `repos`, `content`, `git`, `override`
+- Autocomplete for `files`, `repos`, `content`, `mergeStrategy`, `git`, `override`
 - Enum suggestions for `mergeStrategy` values (`replace`, `append`, `prepend`)
 - Validation of required fields
 - Hover documentation for each field

package/dist/config-normalizer.js

@@ -5,39 +5,56 @@ import { interpolateEnvVars } from "./env.js";
  * Pipeline: expand git arrays -> merge content -> interpolate env vars
  */
 export function normalizeConfig(raw) {
-    const baseContent = raw.content ?? {};
-    const defaultStrategy = raw.mergeStrategy ?? "replace";
     const expandedRepos = [];
+    const fileNames = Object.keys(raw.files);
     for (const rawRepo of raw.repos) {
         // Step 1: Expand git arrays
         const gitUrls = Array.isArray(rawRepo.git) ? rawRepo.git : [rawRepo.git];
         for (const gitUrl of gitUrls) {
-            // Step 2: Compute merged content
-            let mergedContent;
-            if (rawRepo.override) {
-                // Override mode: use only repo content
-                mergedContent = stripMergeDirectives(structuredClone(rawRepo.content));
+            const files = [];
+            // Step 2: Process each file definition
+            for (const fileName of fileNames) {
+                const repoOverride = rawRepo.files?.[fileName];
+                // Skip excluded files (set to false)
+                if (repoOverride === false) {
+                    continue;
+                }
+                const fileConfig = raw.files[fileName];
+                const baseContent = fileConfig.content ?? {};
+                const fileStrategy = fileConfig.mergeStrategy ?? "replace";
+                // Step 3: Compute merged content for this file
+                let mergedContent;
+                if (repoOverride?.override) {
+                    // Override mode: use only repo file content
+                    mergedContent = stripMergeDirectives(structuredClone(repoOverride.content));
+                }
+                else if (!repoOverride?.content) {
+                    // No repo override: use file base content as-is
+                    mergedContent = structuredClone(baseContent);
+                }
+                else {
+                    // Merge mode: deep merge file base + repo overlay
+                    const ctx = createMergeContext(fileStrategy);
+                    mergedContent = deepMerge(structuredClone(baseContent), repoOverride.content, ctx);
+                    mergedContent = stripMergeDirectives(mergedContent);
+                }
+                // Step 4: Interpolate env vars
+                mergedContent = interpolateEnvVars(mergedContent, { strict: true });
+                // Resolve createOnly: per-repo overrides root level
+                const createOnly = repoOverride?.createOnly ?? fileConfig.createOnly;
+                files.push({
+                    fileName,
+                    content: mergedContent,
+                    createOnly,
+                });
             }
-            else if (!rawRepo.content) {
-                // No repo content: use root content as-is
-                mergedContent = structuredClone(baseContent);
-            }
-            else {
-                // Merge mode: deep merge base + overlay
-                const ctx = createMergeContext(defaultStrategy);
-                mergedContent = deepMerge(structuredClone(baseContent), rawRepo.content, ctx);
-                mergedContent = stripMergeDirectives(mergedContent);
-            }
-            // Step 3: Interpolate env vars
-            mergedContent = interpolateEnvVars(mergedContent, { strict: true });
             expandedRepos.push({
                 git: gitUrl,
-                content: mergedContent,
+                files,
             });
         }
     }
     return {
-        fileName: raw.fileName,
         repos: expandedRepos,
     };
 }

package/dist/config-validator.js

@@ -1,35 +1,43 @@
 import { isAbsolute } from "node:path";
+const VALID_STRATEGIES = ["replace", "append", "prepend"];
 /**
  * Validates raw config structure before normalization.
  * @throws Error if validation fails
  */
 export function validateRawConfig(config) {
-    if (!config.fileName) {
-        throw new Error("Config missing required field: fileName");
+    if (!config.files || typeof config.files !== "object") {
+        throw new Error("Config missing required field: files (must be an object)");
     }
-    // Validate fileName doesn't allow path traversal
-    if (config.fileName.includes("..") || isAbsolute(config.fileName)) {
-        throw new Error(`Invalid fileName: must be a relative path without '..' components`);
+    const fileNames = Object.keys(config.files);
+    if (fileNames.length === 0) {
+        throw new Error("Config files object cannot be empty");
     }
-    // Validate fileName doesn't contain control characters that could bypass shell escaping
-    if (/[\n\r\0]/.test(config.fileName)) {
-        throw new Error(`Invalid fileName: cannot contain newlines or null bytes`);
+    // Validate each file definition
+    for (const fileName of fileNames) {
+        validateFileName(fileName);
+        const fileConfig = config.files[fileName];
+        if (!fileConfig || typeof fileConfig !== "object") {
+            throw new Error(`File '${fileName}' must have a configuration object`);
+        }
+        if (fileConfig.content !== undefined &&
+            (typeof fileConfig.content !== "object" ||
+                fileConfig.content === null ||
+                Array.isArray(fileConfig.content))) {
+            throw new Error(`File '${fileName}' content must be an object`);
+        }
+        if (fileConfig.mergeStrategy !== undefined &&
+            !VALID_STRATEGIES.includes(fileConfig.mergeStrategy)) {
+            throw new Error(`File '${fileName}' has invalid mergeStrategy: ${fileConfig.mergeStrategy}. Must be one of: ${VALID_STRATEGIES.join(", ")}`);
+        }
+        if (fileConfig.createOnly !== undefined &&
+            typeof fileConfig.createOnly !== "boolean") {
+            throw new Error(`File '${fileName}' createOnly must be a boolean`);
+        }
     }
     if (!config.repos || !Array.isArray(config.repos)) {
         throw new Error("Config missing required field: repos (must be an array)");
     }
-    const validStrategies = ["replace", "append", "prepend"];
-    if (config.mergeStrategy !== undefined &&
-        !validStrategies.includes(config.mergeStrategy)) {
-        throw new Error(`Invalid mergeStrategy: ${config.mergeStrategy}. Must be one of: ${validStrategies.join(", ")}`);
-    }
-    if (config.content !== undefined &&
-        (typeof config.content !== "object" ||
-            config.content === null ||
-            Array.isArray(config.content))) {
-        throw new Error("Root content must be an object");
-    }
-    const hasRootContent = config.content !== undefined;
+    // Validate each repo
     for (let i = 0; i < config.repos.length; i++) {
         const repo = config.repos[i];
         if (!repo.git) {
@@ -38,14 +46,54 @@ export function validateRawConfig(config) {
         if (Array.isArray(repo.git) && repo.git.length === 0) {
             throw new Error(`Repo at index ${i} has empty git array`);
         }
-        if (!hasRootContent && !repo.content) {
-            throw new Error(`Repo at index ${i} missing required field: content (no root-level content defined)`);
-        }
-        if (repo.override && !repo.content) {
-            throw new Error(`Repo ${getGitDisplayName(repo.git)} has override: true but no content defined`);
+        // Validate per-repo file overrides
+        if (repo.files) {
+            if (typeof repo.files !== "object" || Array.isArray(repo.files)) {
+                throw new Error(`Repo at index ${i}: files must be an object`);
+            }
+            for (const fileName of Object.keys(repo.files)) {
+                // Ensure the file is defined at root level
+                if (!config.files[fileName]) {
+                    throw new Error(`Repo at index ${i} references undefined file '${fileName}'. File must be defined in root 'files' object.`);
+                }
+                const fileOverride = repo.files[fileName];
+                // false means exclude this file for this repo - no further validation needed
+                if (fileOverride === false) {
+                    continue;
+                }
+                if (fileOverride.override && !fileOverride.content) {
+                    throw new Error(`Repo ${getGitDisplayName(repo.git)} has override: true for file '${fileName}' but no content defined`);
+                }
+                if (fileOverride.content !== undefined &&
+                    (typeof fileOverride.content !== "object" ||
+                        fileOverride.content === null ||
+                        Array.isArray(fileOverride.content))) {
+                    throw new Error(`Repo at index ${i}: file '${fileName}' content must be an object`);
+                }
+                if (fileOverride.createOnly !== undefined &&
+                    typeof fileOverride.createOnly !== "boolean") {
+                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' createOnly must be a boolean`);
+                }
+            }
         }
     }
 }
+/**
+ * Validates a file name for security issues
+ */
+function validateFileName(fileName) {
+    if (!fileName || typeof fileName !== "string") {
+        throw new Error("File name must be a non-empty string");
+    }
+    // Validate fileName doesn't allow path traversal
+    if (fileName.includes("..") || isAbsolute(fileName)) {
+        throw new Error(`Invalid fileName '${fileName}': must be a relative path without '..' components`);
+    }
+    // Validate fileName doesn't contain control characters that could bypass shell escaping
+    if (/[\n\r\0]/.test(fileName)) {
+        throw new Error(`Invalid fileName '${fileName}': cannot contain newlines or null bytes`);
+    }
+}
 function getGitDisplayName(git) {
     if (Array.isArray(git)) {
         return git[0] || "unknown";

package/dist/config.d.ts

@@ -1,22 +1,33 @@
 import type { ArrayMergeStrategy } from "./merge.js";
 export { convertContentToString } from "./config-formatter.js";
-export interface RawRepoConfig {
-    git: string | string[];
+export interface RawFileConfig {
+    content: Record<string, unknown>;
+    mergeStrategy?: ArrayMergeStrategy;
+    createOnly?: boolean;
+}
+export interface RawRepoFileOverride {
     content?: Record<string, unknown>;
     override?: boolean;
+    createOnly?: boolean;
+}
+export interface RawRepoConfig {
+    git: string | string[];
+    files?: Record<string, RawRepoFileOverride | false>;
 }
 export interface RawConfig {
-    fileName: string;
-    content?: Record<string, unknown>;
-    mergeStrategy?: ArrayMergeStrategy;
+    files: Record<string, RawFileConfig>;
     repos: RawRepoConfig[];
 }
+export interface FileContent {
+    fileName: string;
+    content: Record<string, unknown>;
+    createOnly?: boolean;
+}
 export interface RepoConfig {
     git: string;
-    content: Record<string, unknown>;
+    files: FileContent[];
 }
 export interface Config {
-    fileName: string;
     repos: RepoConfig[];
 }
 export declare function loadConfig(filePath: string): Config;

package/dist/index.js

@@ -25,9 +25,42 @@ program
     .option("-d, --dry-run", "Show what would be done without making changes")
     .option("-w, --work-dir <path>", "Temporary directory for cloning", "./tmp")
     .option("-r, --retries <number>", "Number of retries for network operations (0 to disable)", (v) => parseInt(v, 10), 3)
-    .option("-b, --branch <name>", "Override the branch name (default: chore/sync-{filename})")
+    .option("-b, --branch <name>", "Override the branch name (default: chore/sync-{filename} or chore/sync-config)")
     .parse();
 const options = program.opts();
+/**
+ * Get unique file names from all repos in the config
+ */
+function getUniqueFileNames(config) {
+    const fileNames = new Set();
+    for (const repo of config.repos) {
+        for (const file of repo.files) {
+            fileNames.add(file.fileName);
+        }
+    }
+    return Array.from(fileNames);
+}
+/**
+ * Generate default branch name based on files being synced
+ */
+function generateBranchName(fileNames) {
+    if (fileNames.length === 1) {
+        return `chore/sync-${sanitizeBranchName(fileNames[0])}`;
+    }
+    return "chore/sync-config";
+}
+/**
+ * Format file names for display
+ */
+function formatFileNames(fileNames) {
+    if (fileNames.length === 1) {
+        return fileNames[0];
+    }
+    if (fileNames.length <= 3) {
+        return fileNames.join(", ");
+    }
+    return `${fileNames.length} files`;
+}
 async function main() {
     const configPath = resolve(options.config);
     if (!existsSync(configPath)) {
@@ -39,17 +72,18 @@ async function main() {
         console.log("Running in DRY RUN mode - no changes will be made\n");
     }
     const config = loadConfig(configPath);
+    const fileNames = getUniqueFileNames(config);
     let branchName;
     if (options.branch) {
         validateBranchName(options.branch);
         branchName = options.branch;
     }
     else {
-        branchName = `chore/sync-${sanitizeBranchName(config.fileName)}`;
+        branchName = generateBranchName(fileNames);
     }
     logger.setTotal(config.repos.length);
     console.log(`Found ${config.repos.length} repositories to process`);
-    console.log(`Target file: ${config.fileName}`);
+    console.log(`Target files: ${formatFileNames(fileNames)}`);
     console.log(`Branch: ${branchName}\n`);
     const processor = defaultProcessorFactory();
     for (let i = 0; i < config.repos.length; i++) {
@@ -69,7 +103,6 @@ async function main() {
         try {
             logger.progress(current, repoName, "Processing...");
             const result = await processor.process(repoConfig, repoInfo, {
-                fileName: config.fileName,
                 branchName,
                 workDir,
                 dryRun: options.dryRun,

package/dist/pr-creator.d.ts

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

package/dist/pr-creator.js

@@ -12,27 +12,80 @@ function loadPRTemplate() {
     if (existsSync(templatePath)) {
         return readFileSync(templatePath, "utf-8");
     }
-    // Fallback template
+    // Fallback template for multi-file support
     return `## Summary
-Automated sync of \`{{FILE_NAME}}\` configuration file.
+Automated sync of configuration files.
 
 ## Changes
-- {{ACTION}} \`{{FILE_NAME}}\` in repository root
+{{FILE_CHANGES}}
+
+## Source
+Configuration synced using [json-config-sync](https://github.com/anthony-spruyt/json-config-sync).
 
 ---
-*This PR was automatically generated by json-config-sync*`;
+_This PR was automatically generated by [json-config-sync](https://github.com/anthony-spruyt/json-config-sync)_`;
+}
+/**
+ * Format file changes list, excluding skipped files
+ */
+function formatFileChanges(files) {
+    const changedFiles = files.filter((f) => f.action !== "skip");
+    return changedFiles
+        .map((f) => {
+        const actionText = f.action === "create" ? "Created" : "Updated";
+        return `- ${actionText} \`${f.fileName}\``;
+    })
+        .join("\n");
 }
-export function formatPRBody(fileName, action) {
+/**
+ * Format PR body for multiple files
+ */
+export function formatPRBody(files) {
     const template = loadPRTemplate();
-    const actionText = action === "create" ? "Created" : "Updated";
-    return template
-        .replace(/\{\{FILE_NAME\}\}/g, fileName)
-        .replace(/\{\{ACTION\}\}/g, actionText);
+    const fileChanges = formatFileChanges(files);
+    // Check if template supports multi-file format
+    if (template.includes("{{FILE_CHANGES}}")) {
+        return template.replace(/\{\{FILE_CHANGES\}\}/g, fileChanges);
+    }
+    // Legacy single-file template - adapt it for multiple files
+    const changedFiles = files.filter((f) => f.action !== "skip");
+    if (changedFiles.length === 1) {
+        const actionText = changedFiles[0].action === "create" ? "Created" : "Updated";
+        return template
+            .replace(/\{\{FILE_NAME\}\}/g, changedFiles[0].fileName)
+            .replace(/\{\{ACTION\}\}/g, actionText);
+    }
+    // Multiple files with legacy template - generate custom body
+    return `## Summary
+Automated sync of configuration files.
+
+## Changes
+${fileChanges}
+
+## Source
+Configuration synced using [json-config-sync](https://github.com/anthony-spruyt/json-config-sync).
+
+---
+_This PR was automatically generated by [json-config-sync](https://github.com/anthony-spruyt/json-config-sync)_`;
+}
+/**
+ * Generate PR title based on files changed (excludes skipped files)
+ */
+export function formatPRTitle(files) {
+    const changedFiles = files.filter((f) => f.action !== "skip");
+    if (changedFiles.length === 1) {
+        return `chore: sync ${changedFiles[0].fileName}`;
+    }
+    if (changedFiles.length <= 3) {
+        const fileNames = changedFiles.map((f) => f.fileName).join(", ");
+        return `chore: sync ${fileNames}`;
+    }
+    return `chore: sync ${changedFiles.length} config files`;
 }
 export async function createPR(options) {
-    const { repoInfo, branchName, baseBranch, fileName, action, workDir, dryRun, retries, } = options;
-    const title = `chore: sync ${fileName}`;
-    const body = formatPRBody(fileName, action);
+    const { repoInfo, branchName, baseBranch, files, workDir, dryRun, retries } = options;
+    const title = formatPRTitle(files);
+    const body = formatPRBody(files);
     if (dryRun) {
         return {
             success: true,

package/dist/repository-processor.d.ts

@@ -3,7 +3,6 @@ import { RepoInfo } from "./repo-detector.js";
 import { GitOps, GitOpsOptions } from "./git-ops.js";
 import { ILogger } from "./logger.js";
 export interface ProcessorOptions {
-    fileName: string;
     branchName: string;
     workDir: string;
     dryRun?: boolean;
@@ -33,4 +32,8 @@ export declare class RepositoryProcessor {
      */
     constructor(gitOpsFactory?: GitOpsFactory, log?: ILogger);
     process(repoConfig: RepoConfig, repoInfo: RepoInfo, options: ProcessorOptions): Promise<ProcessorResult>;
+    /**
+     * Format commit message based on files changed (excludes skipped files)
+     */
+    private formatCommitMessage;
 }

package/dist/repository-processor.js

@@ -20,7 +20,7 @@ export class RepositoryProcessor {
     }
     async process(repoConfig, repoInfo, options) {
         const repoName = getRepoDisplayName(repoInfo);
-        const { fileName, branchName, workDir, dryRun, retries } = options;
+        const { branchName, workDir, dryRun, retries } = options;
         this.gitOps = this.gitOpsFactory({ workDir, dryRun, retries });
         try {
             // Step 1: Clean workspace
@@ -35,30 +35,59 @@ export class RepositoryProcessor {
             // Step 4: Create/checkout branch
             this.log.info(`Switching to branch: ${branchName}`);
             await this.gitOps.createBranch(branchName);
-            // Step 5: Write config file
-            this.log.info(`Writing ${fileName}...`);
-            const fileContent = convertContentToString(repoConfig.content, fileName);
-            // Step 6: Check for changes and determine action
-            // NOTE: This is NOT a race condition. We intentionally:
-            // 1. Capture action type (create/update) BEFORE writing - for PR title
-            // 2. Check git status AFTER writing - to detect actual content changes
-            // The action type is cosmetic for the PR; hasChanges() determines whether to proceed.
-            // If file exists with identical content: action="update", hasChanges=false -> skip (correct)
-            // If file doesn't exist: action="create", hasChanges=true -> proceed (correct)
-            const filePath = join(workDir, fileName);
-            let action;
-            let wouldHaveChanges;
+            // Step 5: Write all config files and track changes
+            const changedFiles = [];
+            for (const file of repoConfig.files) {
+                const filePath = join(workDir, file.fileName);
+                const fileExists = existsSync(filePath);
+                // Handle createOnly - skip if file already exists
+                if (file.createOnly && fileExists) {
+                    this.log.info(`Skipping ${file.fileName} (createOnly: already exists)`);
+                    changedFiles.push({ fileName: file.fileName, action: "skip" });
+                    continue;
+                }
+                this.log.info(`Writing ${file.fileName}...`);
+                const fileContent = convertContentToString(file.content, file.fileName);
+                // Determine action type (create vs update)
+                const action = fileExists ? "update" : "create";
+                if (dryRun) {
+                    // In dry-run, check if file would change without writing
+                    if (this.gitOps.wouldChange(file.fileName, fileContent)) {
+                        changedFiles.push({ fileName: file.fileName, action });
+                    }
+                }
+                else {
+                    // Write the file
+                    this.gitOps.writeFile(file.fileName, fileContent);
+                }
+            }
+            // Step 6: Check for changes (exclude skipped files)
+            let hasChanges;
             if (dryRun) {
-                action = existsSync(filePath) ? "update" : "create";
-                wouldHaveChanges = this.gitOps.wouldChange(fileName, fileContent);
+                hasChanges = changedFiles.filter((f) => f.action !== "skip").length > 0;
             }
             else {
-                // Capture action and write atomically (in same sync block)
-                action = existsSync(filePath) ? "update" : "create";
-                this.gitOps.writeFile(fileName, fileContent);
-                wouldHaveChanges = await this.gitOps.hasChanges();
+                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)
+                    const skippedFiles = new Set(changedFiles
+                        .filter((f) => f.action === "skip")
+                        .map((f) => f.fileName));
+                    for (const file of repoConfig.files) {
+                        if (skippedFiles.has(file.fileName)) {
+                            continue; // Already tracked as skipped
+                        }
+                        const filePath = join(workDir, file.fileName);
+                        const action = existsSync(filePath)
+                            ? "update"
+                            : "create";
+                        changedFiles.push({ fileName: file.fileName, action });
+                    }
+                }
             }
-            if (!wouldHaveChanges) {
+            if (!hasChanges) {
                 return {
                     success: true,
                     repoName,
@@ -68,7 +97,8 @@ export class RepositoryProcessor {
             }
             // Step 7: Commit
             this.log.info("Committing changes...");
-            await this.gitOps.commit(`chore: sync ${fileName}`);
+            const commitMessage = this.formatCommitMessage(changedFiles);
+            await this.gitOps.commit(commitMessage);
             // Step 8: Push
             this.log.info("Pushing to remote...");
             await this.gitOps.push(branchName);
@@ -78,8 +108,7 @@ export class RepositoryProcessor {
                 repoInfo,
                 branchName,
                 baseBranch,
-                fileName,
-                action,
+                files: changedFiles,
                 workDir,
                 dryRun,
                 retries,
@@ -92,7 +121,7 @@ export class RepositoryProcessor {
             };
         }
         finally {
-            // Always cleanup workspace on completion or failure (Improvement 3)
+            // Always cleanup workspace on completion or failure
             if (this.gitOps) {
                 try {
                     this.gitOps.cleanWorkspace();
@@ -103,4 +132,18 @@ export class RepositoryProcessor {
             }
         }
     }
+    /**
+     * Format commit message based on files changed (excludes skipped files)
+     */
+    formatCommitMessage(files) {
+        const changedFiles = files.filter((f) => f.action !== "skip");
+        if (changedFiles.length === 1) {
+            return `chore: sync ${changedFiles[0].fileName}`;
+        }
+        if (changedFiles.length <= 3) {
+            const fileNames = changedFiles.map((f) => f.fileName).join(", ");
+            return `chore: sync ${fileNames}`;
+        }
+        return `chore: sync ${changedFiles.length} config files`;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/json-config-sync",
-  "version": "2.1.1",
+  "version": "3.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",