@aspruyt/json-config-sync 3.2.0 → 3.4.0

package/README.md

@@ -3,8 +3,9 @@
 [![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-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.
+A CLI tool that syncs JSON, YAML, or text configuration files across multiple GitHub and Azure DevOps repositories by creating pull requests. Output format is automatically detected from the target filename extension (`.json` → JSON, `.yaml`/`.yml` → YAML, other → text).
 
 ## Table of Contents
 
@@ -60,7 +61,9 @@ 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
+- **Multi-Format Output** - JSON, YAML, or plain text based on filename extension
+- **Subdirectory Support** - Sync files to any path (e.g., `.github/workflows/ci.yml`)
+- **Text Files** - Sync `.gitignore`, `.markdownlintignore`, etc. with string or lines array
 - **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
@@ -167,13 +170,13 @@ repos: # List of repositories
 
 ### Per-File Fields
 
-| Field           | Description                                                | Required |
-| --------------- | ---------------------------------------------------------- | -------- |
-| `content`       | Base config inherited by all repos (omit for empty file)   | No       |
-| `mergeStrategy` | Array merge strategy: `replace`, `append`, `prepend`       | No       |
-| `createOnly`    | If `true`, only create file if it doesn't exist            | No       |
-| `header`        | Comment line(s) at top of YAML files (string or array)     | No       |
-| `schemaUrl`     | Adds `# yaml-language-server: $schema=<url>` to YAML files | No       |
+| Field           | Description                                                                                      | Required |
+| --------------- | ------------------------------------------------------------------------------------------------ | -------- |
+| `content`       | Base config: object for JSON/YAML files, string or string[] for text files (omit for empty file) | No       |
+| `mergeStrategy` | Merge strategy: `replace`, `append`, `prepend` (for arrays and text lines)                       | No       |
+| `createOnly`    | If `true`, only create file if it doesn't exist                                                  | No       |
+| `header`        | Comment line(s) at top of YAML files (string or array)                                           | No       |
+| `schemaUrl`     | Adds `# yaml-language-server: $schema=<url>` to YAML files                                       | No       |
 
 ### Per-Repo Fields
 
@@ -450,6 +453,72 @@ scan:
 
 **Note:** `header` and `schemaUrl` only apply to YAML output files (`.yaml`, `.yml`). They are ignored for JSON files.
 
+### Text Files
+
+Sync text files like `.gitignore`, `.markdownlintignore`, or `.env.example` using string or lines array content:
+
+```yaml
+files:
+  # String content (multiline text)
+  .markdownlintignore:
+    createOnly: true
+    content: |-
+      # Claude Code generated files
+      .claude/
+
+  # Lines array with merge strategy
+  .gitignore:
+    mergeStrategy: append
+    content:
+      - "node_modules/"
+      - "dist/"
+
+repos:
+  - git: git@github.com:org/repo.git
+    files:
+      .gitignore:
+        content:
+          - "coverage/" # Appended to base lines
+```
+
+**Content Types:**
+
+- **String content** (`content: |-`) - Direct text output with environment variable interpolation. Merging always replaces the base.
+- **Lines array** (`content: ['line1', 'line2']`) - Each line joined with newlines. Supports merge strategies (`append`, `prepend`, `replace`).
+
+**Validation:** JSON/YAML file extensions (`.json`, `.yaml`, `.yml`) require object content. Other extensions require string or string[] content.
+
+### Subdirectory Paths
+
+Sync files to any subdirectory path - parent directories are created automatically:
+
+```yaml
+files:
+  # GitHub Actions workflow
+  ".github/workflows/ci.yml":
+    content:
+      name: CI
+      on: [push, pull_request]
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+  # Nested config directory
+  "config/settings/app.json":
+    content:
+      environment: production
+      debug: false
+
+repos:
+  - git:
+      - git@github.com:org/frontend.git
+      - git@github.com:org/backend.git
+```
+
+**Note:** Quote file paths containing `/` in YAML keys. Parent directories are created if they don't exist.
+
 ## Supported Git URL Formats
 
 ### GitHub

package/dist/config-formatter.d.ts

@@ -11,7 +11,7 @@ export interface ConvertOptions {
  */
 export declare function detectOutputFormat(fileName: string): OutputFormat;
 /**
- * Converts content object to string in the appropriate format.
- * Handles null content (empty files) and comments (YAML only).
+ * Converts content to string in the appropriate format.
+ * Handles null content (empty files), text content (string/string[]), and object content (JSON/YAML).
  */
-export declare function convertContentToString(content: Record<string, unknown> | null, fileName: string, options?: ConvertOptions): string;
+export declare function convertContentToString(content: Record<string, unknown> | string | string[] | null, fileName: string, options?: ConvertOptions): string;

package/dist/config-formatter.js

@@ -47,13 +47,13 @@ function buildCommentOnlyYaml(header, schemaUrl) {
     return lines.join("\n") + "\n";
 }
 /**
- * Converts content object to string in the appropriate format.
- * Handles null content (empty files) and comments (YAML only).
+ * Converts content to string in the appropriate format.
+ * Handles null content (empty files), text content (string/string[]), and object content (JSON/YAML).
  */
 export function convertContentToString(content, fileName, options) {
-    const format = detectOutputFormat(fileName);
     // Handle empty file case
     if (content === null) {
+        const format = detectOutputFormat(fileName);
         if (format === "yaml" && options) {
             const commentOnly = buildCommentOnlyYaml(options.header, options.schemaUrl);
             if (commentOnly) {
@@ -62,6 +62,19 @@ export function convertContentToString(content, fileName, options) {
         }
         return "";
     }
+    // Handle string content (text file)
+    if (typeof content === "string") {
+        // Ensure trailing newline for text files
+        return content.endsWith("\n") ? content : content + "\n";
+    }
+    // Handle string[] content (text file with lines)
+    if (Array.isArray(content)) {
+        // Join lines with newlines and ensure trailing newline
+        const text = content.join("\n");
+        return text.length > 0 ? text + "\n" : "";
+    }
+    // Handle object content (JSON/YAML)
+    const format = detectOutputFormat(fileName);
     if (format === "yaml") {
         // Use Document API for YAML to support comments
         const doc = new Document(content);
@@ -75,5 +88,5 @@ export function convertContentToString(content, fileName, options) {
         return stringify(doc, { indent: 2 });
     }
     // JSON format - comments not supported, ignore header/schemaUrl
-    return JSON.stringify(content, null, 2);
+    return JSON.stringify(content, null, 2) + "\n";
 }

package/dist/config-normalizer.js

@@ -1,5 +1,5 @@
-import { deepMerge, stripMergeDirectives, createMergeContext, } from "./merge.js";
-import { interpolateEnvVars } from "./env.js";
+import { deepMerge, stripMergeDirectives, createMergeContext, isTextContent, mergeTextContent, } from "./merge.js";
+import { interpolateContent } from "./env.js";
 /**
  * Normalizes header to array format.
  */
@@ -38,6 +38,10 @@ export function normalizeConfig(raw) {
                     if (repoOverride.content === undefined) {
                         mergedContent = null;
                     }
+                    else if (isTextContent(repoOverride.content)) {
+                        // Text content: use as-is (no merge directives to strip)
+                        mergedContent = structuredClone(repoOverride.content);
+                    }
                     else {
                         mergedContent = stripMergeDirectives(structuredClone(repoOverride.content));
                     }
@@ -45,7 +49,12 @@ export function normalizeConfig(raw) {
                 else if (fileConfig.content === undefined) {
                     // Root file has no content = empty file (unless repo provides content)
                     if (repoOverride?.content) {
-                        mergedContent = stripMergeDirectives(structuredClone(repoOverride.content));
+                        if (isTextContent(repoOverride.content)) {
+                            mergedContent = structuredClone(repoOverride.content);
+                        }
+                        else {
+                            mergedContent = stripMergeDirectives(structuredClone(repoOverride.content));
+                        }
                     }
                     else {
                         mergedContent = null;
@@ -56,14 +65,21 @@ export function normalizeConfig(raw) {
                     mergedContent = structuredClone(fileConfig.content);
                 }
                 else {
-                    // Merge mode: deep merge file base + repo overlay
-                    const ctx = createMergeContext(fileStrategy);
-                    mergedContent = deepMerge(structuredClone(fileConfig.content), repoOverride.content, ctx);
-                    mergedContent = stripMergeDirectives(mergedContent);
+                    // Merge mode: handle text vs object content
+                    if (isTextContent(fileConfig.content)) {
+                        // Text content merging
+                        mergedContent = mergeTextContent(fileConfig.content, repoOverride.content, fileStrategy);
+                    }
+                    else {
+                        // Object content: deep merge file base + repo overlay
+                        const ctx = createMergeContext(fileStrategy);
+                        mergedContent = deepMerge(structuredClone(fileConfig.content), repoOverride.content, ctx);
+                        mergedContent = stripMergeDirectives(mergedContent);
+                    }
                 }
                 // Step 4: Interpolate env vars (only if content exists)
                 if (mergedContent !== null) {
-                    mergedContent = interpolateEnvVars(mergedContent, { strict: true });
+                    mergedContent = interpolateContent(mergedContent, { strict: true });
                 }
                 // Resolve fields: per-repo overrides root level
                 const createOnly = repoOverride?.createOnly ?? fileConfig.createOnly;

package/dist/config-validator.js

@@ -1,5 +1,26 @@
 import { isAbsolute } from "node:path";
 const VALID_STRATEGIES = ["replace", "append", "prepend"];
+/**
+ * Check if content is text type (string or string[]).
+ */
+function isTextContent(content) {
+    return (typeof content === "string" ||
+        (Array.isArray(content) &&
+            content.every((item) => typeof item === "string")));
+}
+/**
+ * Check if content is object type (for JSON/YAML output).
+ */
+function isObjectContent(content) {
+    return (typeof content === "object" && content !== null && !Array.isArray(content));
+}
+/**
+ * Check if file extension is for structured output (JSON/YAML).
+ */
+function isStructuredFileExtension(fileName) {
+    const ext = fileName.toLowerCase().split(".").pop();
+    return ext === "json" || ext === "yaml" || ext === "yml";
+}
 /**
  * Validates raw config structure before normalization.
  * @throws Error if validation fails
@@ -19,11 +40,21 @@ export function validateRawConfig(config) {
         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`);
+        // Validate content type
+        if (fileConfig.content !== undefined) {
+            const hasText = isTextContent(fileConfig.content);
+            const hasObject = isObjectContent(fileConfig.content);
+            if (!hasText && !hasObject) {
+                throw new Error(`File '${fileName}' content must be an object, string, or array of strings`);
+            }
+            // Validate content type matches file extension
+            const isStructured = isStructuredFileExtension(fileName);
+            if (isStructured && hasText) {
+                throw new Error(`File '${fileName}' has JSON/YAML extension but string content. Use object content for structured files.`);
+            }
+            if (!isStructured && hasObject) {
+                throw new Error(`File '${fileName}' has text extension but object content. Use string or string[] for text files, or use .json/.yaml/.yml extension.`);
+            }
         }
         if (fileConfig.mergeStrategy !== undefined &&
             !VALID_STRATEGIES.includes(fileConfig.mergeStrategy)) {
@@ -75,11 +106,21 @@ export function validateRawConfig(config) {
                 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`);
+                // Validate content type
+                if (fileOverride.content !== undefined) {
+                    const hasText = isTextContent(fileOverride.content);
+                    const hasObject = isObjectContent(fileOverride.content);
+                    if (!hasText && !hasObject) {
+                        throw new Error(`Repo at index ${i}: file '${fileName}' content must be an object, string, or array of strings`);
+                    }
+                    // Validate content type matches file extension
+                    const isStructured = isStructuredFileExtension(fileName);
+                    if (isStructured && hasText) {
+                        throw new Error(`Repo at index ${i}: file '${fileName}' has JSON/YAML extension but string content. Use object content for structured files.`);
+                    }
+                    if (!isStructured && hasObject) {
+                        throw new Error(`Repo at index ${i}: file '${fileName}' has text extension but object content. Use string or string[] for text files, or use .json/.yaml/.yml extension.`);
+                    }
                 }
                 if (fileOverride.createOnly !== undefined &&
                     typeof fileOverride.createOnly !== "boolean") {

package/dist/config.d.ts

@@ -1,14 +1,15 @@
 import type { ArrayMergeStrategy } from "./merge.js";
 export { convertContentToString } from "./config-formatter.js";
+export type ContentValue = Record<string, unknown> | string | string[];
 export interface RawFileConfig {
-    content?: Record<string, unknown>;
+    content?: ContentValue;
     mergeStrategy?: ArrayMergeStrategy;
     createOnly?: boolean;
     header?: string | string[];
     schemaUrl?: string;
 }
 export interface RawRepoFileOverride {
-    content?: Record<string, unknown>;
+    content?: ContentValue;
     override?: boolean;
     createOnly?: boolean;
     header?: string | string[];
@@ -24,7 +25,7 @@ export interface RawConfig {
 }
 export interface FileContent {
     fileName: string;
-    content: Record<string, unknown> | null;
+    content: ContentValue | null;
     createOnly?: boolean;
     header?: string[];
     schemaUrl?: string;

package/dist/env.d.ts

@@ -22,3 +22,16 @@ export interface EnvInterpolationOptions {
  * @returns A new object with interpolated values
  */
 export declare function interpolateEnvVars(json: Record<string, unknown>, options?: EnvInterpolationOptions): Record<string, unknown>;
+/**
+ * Interpolate environment variables in a string.
+ */
+export declare function interpolateEnvVarsInString(value: string, options?: EnvInterpolationOptions): string;
+/**
+ * Interpolate environment variables in an array of strings.
+ */
+export declare function interpolateEnvVarsInLines(lines: string[], options?: EnvInterpolationOptions): string[];
+/**
+ * Interpolate environment variables in content of any supported type.
+ * Handles objects, strings, and string arrays.
+ */
+export declare function interpolateContent(content: Record<string, unknown> | string | string[], options?: EnvInterpolationOptions): Record<string, unknown> | string | string[];

package/dist/env.js

@@ -86,3 +86,31 @@ function processValue(value, options) {
 export function interpolateEnvVars(json, options = DEFAULT_OPTIONS) {
     return processValue(json, options);
 }
+// =============================================================================
+// Text Content Interpolation
+// =============================================================================
+/**
+ * Interpolate environment variables in a string.
+ */
+export function interpolateEnvVarsInString(value, options = DEFAULT_OPTIONS) {
+    return processString(value, options);
+}
+/**
+ * Interpolate environment variables in an array of strings.
+ */
+export function interpolateEnvVarsInLines(lines, options = DEFAULT_OPTIONS) {
+    return lines.map((line) => processString(line, options));
+}
+/**
+ * Interpolate environment variables in content of any supported type.
+ * Handles objects, strings, and string arrays.
+ */
+export function interpolateContent(content, options = DEFAULT_OPTIONS) {
+    if (typeof content === "string") {
+        return interpolateEnvVarsInString(content, options);
+    }
+    if (Array.isArray(content)) {
+        return interpolateEnvVarsInLines(content, options);
+    }
+    return interpolateEnvVars(content, options);
+}

package/dist/git-ops.js

@@ -1,5 +1,5 @@
 import { rmSync, existsSync, mkdirSync, writeFileSync, readFileSync, } from "node:fs";
-import { join, resolve, relative, isAbsolute } from "node:path";
+import { join, resolve, relative, isAbsolute, dirname } from "node:path";
 import { escapeShellArg } from "./shell-utils.js";
 import { defaultExecutor } from "./command-executor.js";
 import { withRetry } from "./retry-utils.js";
@@ -97,6 +97,8 @@ export class GitOps {
             return;
         }
         const filePath = this.validatePath(fileName);
+        // Create parent directories if they don't exist
+        mkdirSync(dirname(filePath), { recursive: true });
         // Normalize trailing newline - ensure exactly one
         const normalized = content.endsWith("\n") ? content : content + "\n";
         writeFileSync(filePath, normalized, "utf-8");

package/dist/merge.d.ts

@@ -34,3 +34,14 @@ export declare function stripMergeDirectives(obj: Record<string, unknown>): Reco
  * Create a default merge context.
  */
 export declare function createMergeContext(defaultStrategy?: ArrayMergeStrategy): MergeContext;
+/**
+ * Check if content is text type (string or string[]).
+ */
+export declare function isTextContent(content: unknown): content is string | string[];
+/**
+ * Merge two text content values.
+ * For strings: overlay replaces base entirely.
+ * For string arrays: applies merge strategy.
+ * For mixed types: overlay replaces base.
+ */
+export declare function mergeTextContent(base: string | string[], overlay: string | string[], strategy?: ArrayMergeStrategy): string | string[];

package/dist/merge.js

@@ -152,3 +152,45 @@ export function createMergeContext(defaultStrategy = "replace") {
         defaultArrayStrategy: defaultStrategy,
     };
 }
+// =============================================================================
+// Text Content Utilities
+// =============================================================================
+/**
+ * Check if content is text type (string or string[]).
+ */
+export function isTextContent(content) {
+    return (typeof content === "string" ||
+        (Array.isArray(content) &&
+            content.every((item) => typeof item === "string")));
+}
+/**
+ * Merge two text content values.
+ * For strings: overlay replaces base entirely.
+ * For string arrays: applies merge strategy.
+ * For mixed types: overlay replaces base.
+ */
+export function mergeTextContent(base, overlay, strategy = "replace") {
+    // If overlay is a string, it always replaces
+    if (typeof overlay === "string") {
+        return overlay;
+    }
+    // If overlay is an array
+    if (Array.isArray(overlay)) {
+        // If base is also an array, apply merge strategy
+        if (Array.isArray(base)) {
+            switch (strategy) {
+                case "append":
+                    return [...base, ...overlay];
+                case "prepend":
+                    return [...overlay, ...base];
+                case "replace":
+                default:
+                    return overlay;
+            }
+        }
+        // Base is string, overlay is array - overlay replaces
+        return overlay;
+    }
+    // Fallback (shouldn't reach here with proper types)
+    return overlay;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/json-config-sync",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "CLI tool to sync JSON or YAML configuration files across multiple GitHub and Azure DevOps repositories",
   "type": "module",
   "main": "dist/index.js",