@aspruyt/json-config-sync 2.0.3 → 2.1.1

package/README.md

@@ -1,7 +1,7 @@
 # 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.yml/badge.svg)](https://github.com/anthony-spruyt/json-config-sync/actions/workflows/integration.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)
 [![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)
 
@@ -70,6 +70,7 @@ json-config-sync --config ./config.yaml
 - **GitHub & Azure DevOps** - Works with both platforms
 - **Dry-Run Mode** - Preview changes without creating PRs
 - **Error Resilience** - Continues processing if individual repos fail
+- **Automatic Retries** - Retries transient network errors with exponential backoff
 
 ## Installation
 
@@ -122,15 +123,20 @@ json-config-sync --config ./config.yaml --dry-run
 
 # Custom work directory
 json-config-sync --config ./config.yaml --work-dir ./my-temp
+
+# Custom branch name
+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       |
+| 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       |
 
 ## Configuration Format
 
@@ -315,7 +321,7 @@ flowchart TB
     end
 
     subgraph Processing["For Each Repository"]
-        CLONE[Clone Repo] --> BRANCH[Create/Checkout Branch<br/>chore/sync-filename]
+        CLONE[Clone Repo] --> BRANCH[Create/Checkout Branch<br/>--branch or chore/sync-filename]
         BRANCH --> WRITE[Write Config File<br/>JSON or YAML]
         WRITE --> CHECK{Changes?}
         CHECK -->|No| SKIP[Skip - No Changes]
@@ -345,7 +351,7 @@ 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 `chore/sync-{sanitized-filename}`
+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)
 8. Checks for changes (skips if no changes)
 9. Commits and pushes changes
@@ -505,6 +511,20 @@ git config --global http.proxy http://proxy.example.com:8080
 git config --global https.proxy http://proxy.example.com:8080
 ```
 
+### Transient Network Errors
+
+The tool automatically retries transient errors (timeouts, connection resets, rate limits) with exponential backoff. By default, it retries 3 times before failing.
+
+```bash
+# Increase retries for unreliable networks
+json-config-sync --config ./config.yaml --retries 5
+
+# Disable retries
+json-config-sync --config ./config.yaml --retries 0
+```
+
+Permanent errors (authentication failures, permission denied, repository not found) are not retried.
+
 ## IDE Integration
 
 ### VS Code YAML Schema Support

package/dist/command-executor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Interface for executing shell commands.
+ * Enables dependency injection for testing and alternative implementations.
+ */
+export interface CommandExecutor {
+    /**
+     * Execute a shell command and return the output.
+     * @param command The command to execute
+     * @param cwd The working directory for the command
+     * @returns Promise resolving to the trimmed stdout output
+     * @throws Error if the command fails
+     */
+    exec(command: string, cwd: string): Promise<string>;
+}
+/**
+ * Default implementation that uses Node.js child_process.execSync.
+ * Note: Commands are escaped using escapeShellArg before being passed here.
+ */
+export declare class ShellCommandExecutor implements CommandExecutor {
+    exec(command: string, cwd: string): Promise<string>;
+}
+/**
+ * Default executor instance for production use.
+ */
+export declare const defaultExecutor: CommandExecutor;

package/dist/command-executor.js

@@ -0,0 +1,28 @@
+import { execSync } from "node:child_process";
+/**
+ * Default implementation that uses Node.js child_process.execSync.
+ * Note: Commands are escaped using escapeShellArg before being passed here.
+ */
+export class ShellCommandExecutor {
+    async exec(command, cwd) {
+        try {
+            return execSync(command, {
+                cwd,
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+            }).trim();
+        }
+        catch (error) {
+            // Ensure stderr is always a string for consistent error handling
+            const execError = error;
+            if (execError.stderr && typeof execError.stderr !== "string") {
+                execError.stderr = execError.stderr.toString();
+            }
+            throw error;
+        }
+    }
+}
+/**
+ * Default executor instance for production use.
+ */
+export const defaultExecutor = new ShellCommandExecutor();

package/dist/config-formatter.d.ts

@@ -0,0 +1,9 @@
+export type OutputFormat = "json" | "yaml";
+/**
+ * Detects output format from file extension.
+ */
+export declare function detectOutputFormat(fileName: string): OutputFormat;
+/**
+ * Converts content object to string in the appropriate format.
+ */
+export declare function convertContentToString(content: Record<string, unknown>, fileName: string): string;

package/dist/config-formatter.js

@@ -0,0 +1,21 @@
+import { stringify } from "yaml";
+/**
+ * Detects output format from file extension.
+ */
+export function detectOutputFormat(fileName) {
+    const ext = fileName.toLowerCase().split(".").pop();
+    if (ext === "yaml" || ext === "yml") {
+        return "yaml";
+    }
+    return "json";
+}
+/**
+ * Converts content object to string in the appropriate format.
+ */
+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/config-normalizer.d.ts

@@ -0,0 +1,6 @@
+import type { RawConfig, Config } from "./config.js";
+/**
+ * Normalizes raw config into expanded, merged config.
+ * Pipeline: expand git arrays -> merge content -> interpolate env vars
+ */
+export declare function normalizeConfig(raw: RawConfig): Config;

package/dist/config-normalizer.js

@@ -0,0 +1,43 @@
+import { deepMerge, stripMergeDirectives, createMergeContext, } from "./merge.js";
+import { interpolateEnvVars } from "./env.js";
+/**
+ * Normalizes raw config into expanded, merged config.
+ * Pipeline: expand git arrays -> merge content -> interpolate env vars
+ */
+export 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 {
+        fileName: raw.fileName,
+        repos: expandedRepos,
+    };
+}

package/dist/config-validator.d.ts

@@ -0,0 +1,6 @@
+import type { RawConfig } from "./config.js";
+/**
+ * Validates raw config structure before normalization.
+ * @throws Error if validation fails
+ */
+export declare function validateRawConfig(config: RawConfig): void;

package/dist/config-validator.js

@@ -0,0 +1,54 @@
+import { isAbsolute } from "node:path";
+/**
+ * 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");
+    }
+    // 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`);
+    }
+    // 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`);
+    }
+    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;
+    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 (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`);
+        }
+    }
+}
+function getGitDisplayName(git) {
+    if (Array.isArray(git)) {
+        return git[0] || "unknown";
+    }
+    return git;
+}

package/dist/config.d.ts

@@ -1,4 +1,5 @@
-import { type ArrayMergeStrategy } from "./merge.js";
+import type { ArrayMergeStrategy } from "./merge.js";
+export { convertContentToString } from "./config-formatter.js";
 export interface RawRepoConfig {
     git: string | string[];
     content?: Record<string, unknown>;
@@ -19,4 +20,3 @@ export interface Config {
     repos: RepoConfig[];
 }
 export declare function loadConfig(filePath: string): Config;
-export declare function convertContentToString(content: Record<string, unknown>, fileName: string): string;

package/dist/config.js

@@ -1,97 +1,22 @@
 import { readFileSync } from "node:fs";
-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 (!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 {
-        fileName: raw.fileName,
-        repos: expandedRepos,
-    };
-}
+import { parse } from "yaml";
+import { validateRawConfig } from "./config-validator.js";
+import { normalizeConfig } from "./config-normalizer.js";
+// Re-export formatter functions for backwards compatibility
+export { convertContentToString } from "./config-formatter.js";
 // =============================================================================
 // Public API
 // =============================================================================
 export function loadConfig(filePath) {
     const content = readFileSync(filePath, "utf-8");
-    const rawConfig = parse(content);
-    validateRawConfig(rawConfig);
-    return normalizeConfig(rawConfig);
-}
-function detectOutputFormat(fileName) {
-    const ext = fileName.toLowerCase().split(".").pop();
-    if (ext === "yaml" || ext === "yml") {
-        return "yaml";
+    let rawConfig;
+    try {
+        rawConfig = parse(content);
     }
-    return "json";
-}
-export function convertContentToString(content, fileName) {
-    const format = detectOutputFormat(fileName);
-    if (format === "yaml") {
-        return stringify(content, { indent: 2 });
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse YAML config at ${filePath}: ${message}`);
     }
-    return JSON.stringify(content, null, 2);
+    validateRawConfig(rawConfig);
+    return normalizeConfig(rawConfig);
 }

package/dist/git-ops.d.ts

@@ -1,27 +1,49 @@
+import { CommandExecutor } from "./command-executor.js";
 export interface GitOpsOptions {
     workDir: string;
     dryRun?: boolean;
+    executor?: CommandExecutor;
+    /** Number of retries for network operations (default: 3) */
+    retries?: number;
 }
 export declare class GitOps {
     private workDir;
     private dryRun;
+    private executor;
+    private retries;
     constructor(options: GitOpsOptions);
     private exec;
+    /**
+     * Run a command with retry logic for transient failures.
+     * Used for network operations like clone, fetch, push.
+     */
+    private execWithRetry;
+    /**
+     * Validates that a file path doesn't escape the workspace directory.
+     * @returns The resolved absolute file path
+     * @throws Error if path traversal is detected
+     */
+    private validatePath;
     cleanWorkspace(): void;
-    clone(gitUrl: string): void;
-    createBranch(branchName: string): void;
+    clone(gitUrl: string): Promise<void>;
+    createBranch(branchName: string): Promise<void>;
     writeFile(fileName: string, content: string): void;
     /**
      * 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(): boolean;
-    commit(message: string): void;
-    push(branchName: string): void;
-    getDefaultBranch(): {
+    hasChanges(): Promise<boolean>;
+    commit(message: string): Promise<void>;
+    push(branchName: string): Promise<void>;
+    getDefaultBranch(): Promise<{
         branch: string;
         method: string;
-    };
+    }>;
 }
 export declare function sanitizeBranchName(fileName: string): string;
+/**
+ * Validates a user-provided branch name against git's naming rules.
+ * @throws Error if the branch name is invalid
+ */
+export declare function validateBranchName(branchName: string): void;