@aspruyt/json-config-sync 1.0.0 → 2.0.0

package/README.md

@@ -5,16 +5,70 @@
 [![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)
 
-A CLI tool that syncs JSON configuration files across multiple Git repositories by creating pull requests.
+A CLI tool that syncs JSON or YAML configuration files across multiple GitHub and Azure DevOps repositories by creating pull requests. Output format is automatically detected from the target filename extension.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [How It Works](#how-it-works)
+- [Installation](#installation)
+- [Prerequisites](#prerequisites)
+- [Usage](#usage)
+- [Configuration Format](#configuration-format)
+- [Examples](#examples)
+- [Supported Git URL Formats](#supported-git-url-formats)
+- [CI/CD Integration](#cicd-integration)
+- [Output Examples](#output-examples)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [License](#license)
+
+## Quick Start
+
+```bash
+# Install
+npm install -g @aspruyt/json-config-sync
+
+# Authenticate (GitHub)
+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
+
+repos:
+  # Multiple repos can share the same config
+  - git:
+      - git@github.com:your-org/frontend-app.git
+      - git@github.com:your-org/backend-api.git
+      - git@github.com:your-org/shared-lib.git
+EOF
+
+# Run
+json-config-sync --config ./config.yaml
+```
+
+**Result:** PRs are created in all three repos with identical `.prettierrc.json` files.
 
 ## Features
 
-- Reads configuration from a YAML file
-- Supports both GitHub and Azure DevOps repositories
-- Creates PRs automatically using `gh` CLI (GitHub) or `az` CLI (Azure DevOps)
-- Continues processing if individual repos fail
-- Supports dry-run mode for testing
-- Progress logging with summary report
+- **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
+- **Environment Variables** - Use `${VAR}` syntax for dynamic values
+- **Merge Strategies** - Control how arrays merge (replace, append, prepend)
+- **Override Mode** - Skip merging entirely for specific repos
+- **GitHub & Azure DevOps** - Works with both platforms
+- **Dry-Run Mode** - Preview changes without creating PRs
+- **Error Resilience** - Continues processing if individual repos fail
 
 ## Installation
 
@@ -71,88 +125,384 @@ json-config-sync --config ./config.yaml --work-dir ./my-temp
 
 ### 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 |
+| 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       |
 
 ## Configuration Format
 
-Create a YAML file with the following structure:
+### 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
+
+repos:                        # List of repositories
+  - git: git@github.com:org/repo.git
+    content:                  # Per-repo overlay (optional if base content exists)
+      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      |
+
+\* Required if any repo entry omits the `content` field.
+
+### 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       |
+
+\* Required if no root-level `content` is defined.
+
+### 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
+```
+
+### Merge Directives
+
+Control array merging with the `$arrayMerge` directive:
+
+```yaml
+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]
+```
+
+## Examples
+
+### 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
+
+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
+
+  # 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
+
+  # Legacy service - completely different config
+  - git: git@github.com:org/legacy-api.git
+    override: true
+    content:
+      version: "1.0"
+      legacy: true
+```
+
+### Environment-Specific Values
+
+Use environment variables for secrets and environment-specific values:
 
 ```yaml
-fileName: my.config.json
+fileName: 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
+
 repos:
-  - git: git@github.com:example-org/repo1.git
-    json:
-      setting1: value1
-      nested:
-        setting2: value2
-  - git: git@ssh.dev.azure.com:v3/example-org/project/repo2
-    json:
-      setting1: differentValue
-      setting3: value
-```
-
-### Fields
-
-| Field | Description |
-|-------|-------------|
-| `fileName` | The name of the JSON file to create/update in each repo |
-| `repos` | Array of repository configurations |
-| `repos[].git` | Git URL of the repository (SSH or HTTPS) |
-| `repos[].json` | The JSON content to write to the file |
+  - git: git@github.com:org/backend.git
+```
+
+### Simple Multi-Repo Sync
+
+When all repos need identical config:
+
+```yaml
+fileName: .eslintrc.json
+
+content:
+  extends: ["@org/eslint-config"]
+  rules:
+    no-console: warn
+
+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
+```
 
 ## Supported Git URL Formats
 
 ### GitHub
+
 - SSH: `git@github.com:owner/repo.git`
 - HTTPS: `https://github.com/owner/repo.git`
 
 ### Azure DevOps
+
 - SSH: `git@ssh.dev.azure.com:v3/organization/project/repo`
 - HTTPS: `https://dev.azure.com/organization/project/_git/repo`
 
-## Workflow
+## How It Works
+
+```mermaid
+flowchart TB
+    subgraph Input
+        YAML[/"YAML Config File<br/>fileName + content + repos[]"/]
+    end
+
+    subgraph Normalization
+        EXPAND[Expand git arrays] --> MERGE[Merge base + overlay content]
+        MERGE --> ENV[Interpolate env vars]
+    end
+
+    subgraph Processing["For Each Repository"]
+        CLONE[Clone Repo] --> BRANCH[Create/Checkout Branch<br/>chore/sync-filename]
+        BRANCH --> WRITE[Write Config File<br/>JSON or YAML]
+        WRITE --> CHECK{Changes?}
+        CHECK -->|No| SKIP[Skip - No Changes]
+        CHECK -->|Yes| COMMIT[Commit Changes]
+        COMMIT --> PUSH[Push to Remote]
+    end
+
+    subgraph Platform["Platform Detection"]
+        PUSH --> DETECT{GitHub or<br/>Azure DevOps?}
+    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"/]
+    end
+
+    YAML --> EXPAND
+    ENV --> CLONE
+```
 
 For each repository in the config, the tool:
 
-1. Cleans the temporary workspace
-2. Detects if repo is GitHub or Azure DevOps
-3. Clones the repository
-4. Creates/checks out branch `chore/sync-{sanitized-filename}`
-5. Generates the JSON file from config
-6. Checks for changes (skips if no changes)
-7. Commits and pushes changes
-8. Creates a pull request
+1. Expands git URL arrays into individual entries
+2. 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 `chore/sync-{sanitized-filename}`
+7. Generates the config file (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
 
-## Example
+## CI/CD Integration
 
-Given this config file (`config.yaml`):
+### GitHub Actions
 
 ```yaml
-fileName: my.config.json
-repos:
-  - git: git@github.com:example-org/my-service.git
-    json:
-      environment: production
-      settings:
-        feature1: true
-        feature2: false
+name: Sync Configs
+on:
+  push:
+    branches: [main]
+    paths: ["config.yaml"]
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm install -g @aspruyt/json-config-sync
+      - run: json-config-sync --config ./config.yaml
+        env:
+          GH_TOKEN: ${{ secrets.GH_PAT }}
+```
+
+> **Note:** `GH_PAT` must be a Personal Access Token with `repo` scope to create PRs in target repositories.
+
+### Azure Pipelines
+
+```yaml
+trigger:
+  branches:
+    include: [main]
+  paths:
+    include: ["config.yaml"]
+
+pool:
+  vmImage: "ubuntu-latest"
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: "20.x"
+  - script: npm install -g @aspruyt/json-config-sync
+    displayName: "Install json-config-sync"
+  - script: json-config-sync --config ./config.yaml
+    displayName: "Sync configs"
+    env:
+      AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
+```
+
+> **Note:** Ensure the build service account has permission to create PRs in target repositories.
+
+## Output Examples
+
+### Console Output
+
 ```
+[1/3] Processing example-org/repo1...
+  ✓ Cloned repository
+  ✓ Created branch chore/sync-my-config
+  ✓ Wrote my.config.json
+  ✓ 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
+  ⊘ No changes detected, skipping
+
+[3/3] Processing example-org/repo3...
+  ✓ Cloned repository
+  ✓ Created branch chore/sync-my-config
+  ✓ Wrote my.config.json
+  ✓ Committed changes
+  ✓ Pushed to remote
+  ✓ PR already exists: https://github.com/example-org/repo3/pull/15
+
+Summary: 2 succeeded, 1 skipped, 0 failed
+```
+
+### Created PR
+
+The tool creates PRs with:
+
+- **Title:** `chore: sync {fileName}`
+- **Branch:** `chore/sync-{sanitized-filename}`
+- **Body:** Describes the sync action and links to documentation
+
+## Troubleshooting
+
+### Authentication Errors
 
-Running:
+**GitHub:**
 
 ```bash
+# Check authentication status
+gh auth status
+
+# Re-authenticate if needed
+gh auth login
+```
+
+**Azure DevOps:**
+
+```bash
+# Check authentication status
+az account show
+
+# Re-authenticate if needed
+az login
+az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG
+```
+
+### 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
+
+### Branch Already Exists
+
+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
+```
+
+### Missing Environment Variables
+
+If you see "Missing required environment variable" errors:
+
+```bash
+# Set the variable before running
+export MY_VAR=value
 json-config-sync --config ./config.yaml
+
+# Or use default values in config
+# ${MY_VAR:-default-value}
 ```
 
-Will:
-1. Clone `example-org/my-service`
-2. Create branch `chore/sync-my-config`
-3. Write `my.config.json` with the specified content
-4. Create a PR titled "chore: sync my.config.json"
+### Network/Proxy Issues
+
+If cloning fails behind a corporate proxy:
+
+```bash
+# Configure git proxy
+git config --global http.proxy http://proxy.example.com:8080
+git config --global https.proxy http://proxy.example.com:8080
+```
 
 ## Development
 

package/dist/config.d.ts

@@ -1,10 +1,22 @@
+import { type ArrayMergeStrategy } from './merge.js';
+export interface RawRepoConfig {
+    git: string | string[];
+    content?: Record<string, unknown>;
+    override?: boolean;
+}
+export interface RawConfig {
+    fileName: string;
+    content?: Record<string, unknown>;
+    mergeStrategy?: ArrayMergeStrategy;
+    repos: RawRepoConfig[];
+}
 export interface RepoConfig {
     git: string;
-    json: Record<string, unknown>;
+    content: Record<string, unknown>;
 }
 export interface Config {
     fileName: string;
     repos: RepoConfig[];
 }
 export declare function loadConfig(filePath: string): Config;
-export declare function convertJsonToString(json: Record<string, unknown>): string;
+export declare function convertContentToString(content: Record<string, unknown>, fileName: string): string;

package/dist/config.js

@@ -1,25 +1,97 @@
 import { readFileSync } from 'node:fs';
-import { parse } from 'yaml';
-export function loadConfig(filePath) {
-    const content = readFileSync(filePath, 'utf-8');
-    const config = parse(content);
+import { parse, stringify } from 'yaml';
+import { deepMerge, stripMergeDirectives, createMergeContext, } from './merge.js';
+import { interpolateEnvVars } from './env.js';
+// =============================================================================
+// Validation
+// =============================================================================
+function validateRawConfig(config) {
     if (!config.fileName) {
         throw new Error('Config missing required field: fileName');
     }
     if (!config.repos || !Array.isArray(config.repos)) {
         throw new Error('Config missing required field: repos (must be an array)');
     }
+    const hasRootContent = config.content !== undefined;
     for (let i = 0; i < config.repos.length; i++) {
         const repo = config.repos[i];
         if (!repo.git) {
             throw new Error(`Repo at index ${i} missing required field: git`);
         }
-        if (!repo.json) {
-            throw new Error(`Repo at index ${i} missing required field: json`);
+        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`);
+        }
+    }
+}
+function getGitDisplayName(git) {
+    if (Array.isArray(git)) {
+        return git[0] || 'unknown';
+    }
+    return git;
+}
+// =============================================================================
+// Normalization Pipeline
+// =============================================================================
+function normalizeConfig(raw) {
+    const baseContent = raw.content ?? {};
+    const defaultStrategy = raw.mergeStrategy ?? 'replace';
+    const expandedRepos = [];
+    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));
+            }
+            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,
+            });
         }
     }
-    return config;
+    return {
+        fileName: raw.fileName,
+        repos: expandedRepos,
+    };
+}
+// =============================================================================
+// Public API
+// =============================================================================
+export function loadConfig(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    const rawConfig = parse(content);
+    validateRawConfig(rawConfig);
+    return normalizeConfig(rawConfig);
 }
-export function convertJsonToString(json) {
-    return JSON.stringify(json, null, 2);
+function detectOutputFormat(fileName) {
+    const ext = fileName.toLowerCase().split('.').pop();
+    if (ext === 'yaml' || ext === 'yml') {
+        return 'yaml';
+    }
+    return 'json';
+}
+export function convertContentToString(content, fileName) {
+    const format = detectOutputFormat(fileName);
+    if (format === 'yaml') {
+        return stringify(content, { indent: 2 });
+    }
+    return JSON.stringify(content, null, 2);
 }

package/dist/env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Environment variable interpolation utilities.
+ * Supports ${VAR}, ${VAR:-default}, and ${VAR:?message} syntax.
+ */
+export interface EnvInterpolationOptions {
+    /**
+     * If true (default), throws an error when a variable is missing
+     * and has no default value. If false, leaves the placeholder as-is.
+     */
+    strict: boolean;
+}
+/**
+ * Interpolate environment variables in a JSON object.
+ *
+ * Supports three syntaxes:
+ * - ${VAR} - Replace with env value, error if missing (in strict mode)
+ * - ${VAR:-default} - Replace with env value, or use default if missing
+ * - ${VAR:?message} - Replace with env value, or throw error with message if missing
+ *
+ * @param json - The JSON object to process
+ * @param options - Interpolation options (default: strict mode)
+ * @returns A new object with interpolated values
+ */
+export declare function interpolateEnvVars(json: Record<string, unknown>, options?: EnvInterpolationOptions): Record<string, unknown>;

package/dist/env.js

@@ -0,0 +1,88 @@
+/**
+ * Environment variable interpolation utilities.
+ * Supports ${VAR}, ${VAR:-default}, and ${VAR:?message} syntax.
+ */
+const DEFAULT_OPTIONS = {
+    strict: true,
+};
+/**
+ * Regex to match environment variable placeholders.
+ * Captures:
+ * - Group 1: Variable name
+ * - Group 2: Modifier (- for default, ? for required with message)
+ * - Group 3: Default value or error message
+ *
+ * Examples:
+ * - ${VAR} -> varName=VAR, modifier=undefined, value=undefined
+ * - ${VAR:-default} -> varName=VAR, modifier=-, value=default
+ * - ${VAR:?message} -> varName=VAR, modifier=?, value=message
+ */
+const ENV_VAR_REGEX = /\$\{([^}:]+)(?::([?-])([^}]*))?\}/g;
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+function isPlainObject(val) {
+    return typeof val === 'object' && val !== null && !Array.isArray(val);
+}
+/**
+ * Process a single string value, replacing environment variable placeholders.
+ */
+function processString(value, options) {
+    return value.replace(ENV_VAR_REGEX, (match, varName, modifier, defaultOrMsg) => {
+        const envValue = process.env[varName];
+        // Variable exists - use its value
+        if (envValue !== undefined) {
+            return envValue;
+        }
+        // Has default value (:-default)
+        if (modifier === '-') {
+            return defaultOrMsg ?? '';
+        }
+        // Required with message (:?message)
+        if (modifier === '?') {
+            const message = defaultOrMsg || `is required`;
+            throw new Error(`${varName}: ${message}`);
+        }
+        // No modifier - check strictness
+        if (options.strict) {
+            throw new Error(`Missing required environment variable: ${varName}`);
+        }
+        // Non-strict mode - leave placeholder as-is
+        return match;
+    });
+}
+/**
+ * Recursively process a value, interpolating environment variables in strings.
+ */
+function processValue(value, options) {
+    if (typeof value === 'string') {
+        return processString(value, options);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => processValue(item, options));
+    }
+    if (isPlainObject(value)) {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = processValue(val, options);
+        }
+        return result;
+    }
+    // For numbers, booleans, null - return as-is
+    return value;
+}
+/**
+ * Interpolate environment variables in a JSON object.
+ *
+ * Supports three syntaxes:
+ * - ${VAR} - Replace with env value, error if missing (in strict mode)
+ * - ${VAR:-default} - Replace with env value, or use default if missing
+ * - ${VAR:?message} - Replace with env value, or throw error with message if missing
+ *
+ * @param json - The JSON object to process
+ * @param options - Interpolation options (default: strict mode)
+ * @returns A new object with interpolated values
+ */
+export function interpolateEnvVars(json, options = DEFAULT_OPTIONS) {
+    return processValue(json, options);
+}

package/dist/index.js

@@ -2,7 +2,7 @@
 import { program } from 'commander';
 import { resolve, join } from 'node:path';
 import { existsSync } from 'node:fs';
-import { loadConfig, convertJsonToString } from './config.js';
+import { loadConfig, convertContentToString } from './config.js';
 import { parseGitUrl, getRepoDisplayName } from './repo-detector.js';
 import { GitOps, sanitizeBranchName } from './git-ops.js';
 import { createPR } from './pr-creator.js';
@@ -61,10 +61,10 @@ async function main() {
             // Step 4: Create/checkout branch
             logger.info(`Switching to branch: ${branchName}`);
             gitOps.createBranch(branchName);
-            // Step 5: Write JSON file
+            // Step 5: Write config file
             logger.info(`Writing ${config.fileName}...`);
-            const jsonContent = convertJsonToString(repoConfig.json);
-            gitOps.writeFile(config.fileName, jsonContent);
+            const fileContent = convertContentToString(repoConfig.content, config.fileName);
+            gitOps.writeFile(config.fileName, fileContent);
             // Step 6: Check for changes
             if (!gitOps.hasChanges()) {
                 logger.skip(current, repoName, 'No changes detected');

package/dist/merge.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Deep merge utilities for JSON configuration objects.
+ * Supports configurable array merge strategies via $arrayMerge directive.
+ */
+export type ArrayMergeStrategy = 'replace' | 'append' | 'prepend';
+export interface MergeContext {
+    arrayStrategies: Map<string, ArrayMergeStrategy>;
+    defaultArrayStrategy: ArrayMergeStrategy;
+}
+/**
+ * Deep merge two objects with configurable array handling.
+ *
+ * @param base - The base object
+ * @param overlay - The overlay object (values override base)
+ * @param ctx - Merge context with array strategies
+ * @param path - Current path for strategy lookup (internal)
+ */
+export declare function deepMerge(base: Record<string, unknown>, overlay: Record<string, unknown>, ctx: MergeContext, path?: string): Record<string, unknown>;
+/**
+ * Strip merge directive keys ($arrayMerge, $override, etc.) from an object.
+ * Works recursively on nested objects and arrays.
+ */
+export declare function stripMergeDirectives(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Create a default merge context.
+ */
+export declare function createMergeContext(defaultStrategy?: ArrayMergeStrategy): MergeContext;

package/dist/merge.js

@@ -0,0 +1,147 @@
+/**
+ * Deep merge utilities for JSON configuration objects.
+ * Supports configurable array merge strategies via $arrayMerge directive.
+ */
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+function isPlainObject(val) {
+    return typeof val === 'object' && val !== null && !Array.isArray(val);
+}
+/**
+ * Merge two arrays based on the specified strategy.
+ */
+function mergeArrays(base, overlay, strategy) {
+    switch (strategy) {
+        case 'replace':
+            return overlay;
+        case 'append':
+            return [...base, ...overlay];
+        case 'prepend':
+            return [...overlay, ...base];
+        default:
+            return overlay;
+    }
+}
+/**
+ * Extract array values from an overlay object that uses the directive syntax:
+ * { $arrayMerge: 'append', values: [1, 2, 3] }
+ *
+ * Or just return the array if it's already an array.
+ */
+function extractArrayFromOverlay(overlay) {
+    if (Array.isArray(overlay)) {
+        return overlay;
+    }
+    if (isPlainObject(overlay) && 'values' in overlay) {
+        const values = overlay.values;
+        if (Array.isArray(values)) {
+            return values;
+        }
+    }
+    return null;
+}
+/**
+ * Get merge strategy from an overlay object's $arrayMerge directive.
+ */
+function getStrategyFromOverlay(overlay) {
+    if (isPlainObject(overlay) && '$arrayMerge' in overlay) {
+        const strategy = overlay.$arrayMerge;
+        if (strategy === 'replace' ||
+            strategy === 'append' ||
+            strategy === 'prepend') {
+            return strategy;
+        }
+    }
+    return null;
+}
+/**
+ * Deep merge two objects with configurable array handling.
+ *
+ * @param base - The base object
+ * @param overlay - The overlay object (values override base)
+ * @param ctx - Merge context with array strategies
+ * @param path - Current path for strategy lookup (internal)
+ */
+export function deepMerge(base, overlay, ctx, path = '') {
+    const result = { ...base };
+    // Check for $arrayMerge directive at this level (applies to child arrays)
+    const levelStrategy = getStrategyFromOverlay(overlay);
+    for (const [key, overlayValue] of Object.entries(overlay)) {
+        // Skip directive keys in output
+        if (key.startsWith('$'))
+            continue;
+        const currentPath = path ? `${path}.${key}` : key;
+        const baseValue = base[key];
+        // If overlay is an object with $arrayMerge directive for an array field
+        if (isPlainObject(overlayValue) && '$arrayMerge' in overlayValue) {
+            const strategy = getStrategyFromOverlay(overlayValue);
+            const overlayArray = extractArrayFromOverlay(overlayValue);
+            if (strategy && overlayArray && Array.isArray(baseValue)) {
+                result[key] = mergeArrays(baseValue, overlayArray, strategy);
+                continue;
+            }
+        }
+        // Both are arrays - apply strategy
+        if (Array.isArray(baseValue) && Array.isArray(overlayValue)) {
+            // Check for level-specific strategy, then path-specific, then default
+            const strategy = levelStrategy ??
+                ctx.arrayStrategies.get(currentPath) ??
+                ctx.defaultArrayStrategy;
+            result[key] = mergeArrays(baseValue, overlayValue, strategy);
+            continue;
+        }
+        // Both are plain objects - recurse
+        if (isPlainObject(baseValue) && isPlainObject(overlayValue)) {
+            // Extract $arrayMerge for child paths if present
+            if ('$arrayMerge' in overlayValue) {
+                const childStrategy = getStrategyFromOverlay(overlayValue);
+                if (childStrategy) {
+                    // Apply to all immediate child arrays
+                    for (const childKey of Object.keys(overlayValue)) {
+                        if (!childKey.startsWith('$')) {
+                            const childPath = currentPath ? `${currentPath}.${childKey}` : childKey;
+                            ctx.arrayStrategies.set(childPath, childStrategy);
+                        }
+                    }
+                }
+            }
+            result[key] = deepMerge(baseValue, overlayValue, ctx, currentPath);
+            continue;
+        }
+        // Otherwise, overlay wins (including null values)
+        result[key] = overlayValue;
+    }
+    return result;
+}
+/**
+ * Strip merge directive keys ($arrayMerge, $override, etc.) from an object.
+ * Works recursively on nested objects and arrays.
+ */
+export function stripMergeDirectives(obj) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        // Skip all $-prefixed keys (reserved for directives)
+        if (key.startsWith('$'))
+            continue;
+        if (isPlainObject(value)) {
+            result[key] = stripMergeDirectives(value);
+        }
+        else if (Array.isArray(value)) {
+            result[key] = value.map((item) => isPlainObject(item) ? stripMergeDirectives(item) : item);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Create a default merge context.
+ */
+export function createMergeContext(defaultStrategy = 'replace') {
+    return {
+        arrayStrategies: new Map(),
+        defaultArrayStrategy: defaultStrategy,
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aspruyt/json-config-sync",
-  "version": "1.0.0",
-  "description": "CLI tool to sync JSON configuration files across multiple repositories",
+  "version": "2.0.0",
+  "description": "CLI tool to sync JSON configuration files across multiple GitHub and Azure DevOps repositories",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -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",
+    "test": "node --import tsx --test src/config.test.ts src/merge.test.ts src/env.test.ts",
     "test:integration": "npm run build && node --import tsx --test src/integration.test.ts",
     "prepublishOnly": "npm run build",
     "release:patch": "npm version patch && git push --follow-tags",