@aspruyt/json-config-sync 3.0.0 → 3.1.0

package/README.md

@@ -169,6 +169,7 @@ repos: # List of repositories
 | --------------- | ---------------------------------------------------- | -------- |
 | `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
 
@@ -179,10 +180,11 @@ repos: # List of repositories
 
 ### Per-Repo File Override Fields
 
-| 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       |
+| 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:
 
@@ -363,6 +365,39 @@ repos:
       # 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
 
 ### GitHub

package/dist/config-normalizer.js

@@ -40,9 +40,12 @@ export function normalizeConfig(raw) {
                 }
                 // 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,
                 });
             }
             expandedRepos.push({

package/dist/config-validator.js

@@ -29,6 +29,10 @@ export function validateRawConfig(config) {
             !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)");
@@ -66,6 +70,10 @@ export function validateRawConfig(config) {
                         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`);
+                }
             }
         }
     }

package/dist/config.d.ts

@@ -3,10 +3,12 @@ export { convertContentToString } from "./config-formatter.js";
 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[];
@@ -19,6 +21,7 @@ export interface RawConfig {
 export interface FileContent {
     fileName: string;
     content: Record<string, unknown>;
+    createOnly?: boolean;
 }
 export interface RepoConfig {
     git: string;

package/dist/pr-creator.d.ts

@@ -2,7 +2,7 @@ import { RepoInfo } from "./repo-detector.js";
 export { escapeShellArg } from "./shell-utils.js";
 export interface FileAction {
     fileName: string;
-    action: "create" | "update";
+    action: "create" | "update" | "skip";
 }
 export interface PROptions {
     repoInfo: RepoInfo;
@@ -24,7 +24,7 @@ export interface PRResult {
  */
 export declare function formatPRBody(files: FileAction[]): string;
 /**
- * Generate PR title based on files changed
+ * 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

@@ -25,36 +25,37 @@ Configuration synced using [json-config-sync](https://github.com/anthony-spruyt/
 ---
 _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");
+}
 /**
  * Format PR body for multiple files
  */
 export function formatPRBody(files) {
     const template = loadPRTemplate();
+    const fileChanges = formatFileChanges(files);
     // Check if template supports multi-file format
     if (template.includes("{{FILE_CHANGES}}")) {
-        // Multi-file template
-        const fileChanges = files
-            .map((f) => {
-            const actionText = f.action === "create" ? "Created" : "Updated";
-            return `- ${actionText} \`${f.fileName}\``;
-        })
-            .join("\n");
         return template.replace(/\{\{FILE_CHANGES\}\}/g, fileChanges);
     }
     // Legacy single-file template - adapt it for multiple files
-    if (files.length === 1) {
-        const actionText = files[0].action === "create" ? "Created" : "Updated";
+    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, files[0].fileName)
+            .replace(/\{\{FILE_NAME\}\}/g, changedFiles[0].fileName)
             .replace(/\{\{ACTION\}\}/g, actionText);
     }
     // Multiple files with legacy template - generate custom body
-    const fileChanges = files
-        .map((f) => {
-        const actionText = f.action === "create" ? "Created" : "Updated";
-        return `- ${actionText} \`${f.fileName}\``;
-    })
-        .join("\n");
     return `## Summary
 Automated sync of configuration files.
 
@@ -68,17 +69,18 @@ Configuration synced using [json-config-sync](https://github.com/anthony-spruyt/
 _This PR was automatically generated by [json-config-sync](https://github.com/anthony-spruyt/json-config-sync)_`;
 }
 /**
- * Generate PR title based on files changed
+ * Generate PR title based on files changed (excludes skipped files)
  */
 export function formatPRTitle(files) {
-    if (files.length === 1) {
-        return `chore: sync ${files[0].fileName}`;
+    const changedFiles = files.filter((f) => f.action !== "skip");
+    if (changedFiles.length === 1) {
+        return `chore: sync ${changedFiles[0].fileName}`;
     }
-    if (files.length <= 3) {
-        const fileNames = files.map((f) => f.fileName).join(", ");
+    if (changedFiles.length <= 3) {
+        const fileNames = changedFiles.map((f) => f.fileName).join(", ");
         return `chore: sync ${fileNames}`;
     }
-    return `chore: sync ${files.length} config files`;
+    return `chore: sync ${changedFiles.length} config files`;
 }
 export async function createPR(options) {
     const { repoInfo, branchName, baseBranch, files, workDir, dryRun, retries } = options;

package/dist/repository-processor.d.ts

@@ -33,7 +33,7 @@ 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
+     * Format commit message based on files changed (excludes skipped files)
      */
     private formatCommitMessage;
 }

package/dist/repository-processor.js

@@ -38,13 +38,18 @@ export class RepositoryProcessor {
             // 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);
-                const filePath = join(workDir, file.fileName);
                 // Determine action type (create vs update)
-                const action = existsSync(filePath)
-                    ? "update"
-                    : "create";
+                const action = fileExists ? "update" : "create";
                 if (dryRun) {
                     // In dry-run, check if file would change without writing
                     if (this.gitOps.wouldChange(file.fileName, fileContent)) {
@@ -56,23 +61,25 @@ export class RepositoryProcessor {
                     this.gitOps.writeFile(file.fileName, fileContent);
                 }
             }
-            // Step 6: Check for changes
+            // Step 6: Check for changes (exclude skipped files)
             let hasChanges;
             if (dryRun) {
-                hasChanges = changedFiles.length > 0;
+                hasChanges = changedFiles.filter((f) => f.action !== "skip").length > 0;
             }
             else {
                 hasChanges = await this.gitOps.hasChanges();
                 // If there are changes, determine which files changed
                 if (hasChanges) {
                     // Rebuild the changed files list by checking git status
-                    // For simplicity, we include all files with their detected actions
+                    // 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);
-                        // We check if file existed before writing (action was determined above)
-                        // Since we don't have pre-write state, we'll mark all files that are in the commit
-                        // A more accurate approach would track this before writing, but for now
-                        // we'll assume all files are being synced and include them all
                         const action = existsSync(filePath)
                             ? "update"
                             : "create";
@@ -126,16 +133,17 @@ export class RepositoryProcessor {
         }
     }
     /**
-     * Format commit message based on files changed
+     * Format commit message based on files changed (excludes skipped files)
      */
     formatCommitMessage(files) {
-        if (files.length === 1) {
-            return `chore: sync ${files[0].fileName}`;
+        const changedFiles = files.filter((f) => f.action !== "skip");
+        if (changedFiles.length === 1) {
+            return `chore: sync ${changedFiles[0].fileName}`;
         }
-        if (files.length <= 3) {
-            const fileNames = files.map((f) => f.fileName).join(", ");
+        if (changedFiles.length <= 3) {
+            const fileNames = changedFiles.map((f) => f.fileName).join(", ");
             return `chore: sync ${fileNames}`;
         }
-        return `chore: sync ${files.length} config files`;
+        return `chore: sync ${changedFiles.length} config files`;
     }
 }

package/package.json

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