@aspruyt/xfg 1.0.0

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,32 @@
+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();
+            }
+            // Include stderr in error message for better debugging
+            if (execError.stderr && execError.message) {
+                execError.message = `${execError.message}\n${execError.stderr}`;
+            }
+            throw error;
+        }
+    }
+}
+/**
+ * Default executor instance for production use.
+ */
+export const defaultExecutor = new ShellCommandExecutor();

package/dist/config-formatter.d.ts

@@ -0,0 +1,17 @@
+export type OutputFormat = "json" | "json5" | "yaml";
+/**
+ * Options for content conversion.
+ */
+export interface ConvertOptions {
+    header?: string[];
+    schemaUrl?: string;
+}
+/**
+ * Detects output format from file extension.
+ */
+export declare function detectOutputFormat(fileName: string): OutputFormat;
+/**
+ * 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> | string | string[] | null, fileName: string, options?: ConvertOptions): string;

package/dist/config-formatter.js

@@ -0,0 +1,100 @@
+import { Document, 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";
+    }
+    if (ext === "json5") {
+        return "json5";
+    }
+    return "json";
+}
+/**
+ * Builds header comment string from header lines and schemaUrl.
+ * Returns undefined if no comments to add.
+ * Each line gets a space prefix since yaml library adds # directly.
+ */
+function buildHeaderComment(header, schemaUrl) {
+    const lines = [];
+    // Add yaml-language-server schema directive first (if present)
+    if (schemaUrl) {
+        lines.push(` yaml-language-server: $schema=${schemaUrl}`);
+    }
+    // Add custom header lines (with space prefix for proper formatting)
+    if (header && header.length > 0) {
+        lines.push(...header.map((h) => ` ${h}`));
+    }
+    if (lines.length === 0)
+        return undefined;
+    // Join with newlines - the yaml library adds # prefix to each line
+    return lines.join("\n");
+}
+/**
+ * Builds comment-only output for empty YAML files with headers.
+ */
+function buildCommentOnlyYaml(header, schemaUrl) {
+    const lines = [];
+    // Add yaml-language-server schema directive first (if present)
+    if (schemaUrl) {
+        lines.push(`# yaml-language-server: $schema=${schemaUrl}`);
+    }
+    // Add custom header lines
+    if (header && header.length > 0) {
+        lines.push(...header.map((h) => `# ${h}`));
+    }
+    if (lines.length === 0)
+        return undefined;
+    return lines.join("\n") + "\n";
+}
+/**
+ * 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) {
+    // Handle empty file case
+    if (content === null) {
+        const format = detectOutputFormat(fileName);
+        if (format === "yaml" && options) {
+            const commentOnly = buildCommentOnlyYaml(options.header, options.schemaUrl);
+            if (commentOnly) {
+                return commentOnly;
+            }
+        }
+        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);
+        // Add header comment if present
+        if (options) {
+            const headerComment = buildHeaderComment(options.header, options.schemaUrl);
+            if (headerComment) {
+                doc.commentBefore = headerComment;
+            }
+        }
+        return stringify(doc, { indent: 2 });
+    }
+    if (format === "json5") {
+        // JSON5 format - output standard JSON (which is valid JSON5)
+        // Using JSON.stringify for standard JSON output that's compatible everywhere
+        return JSON.stringify(content, null, 2) + "\n";
+    }
+    // JSON format - comments not supported, ignore header/schemaUrl
+    return JSON.stringify(content, null, 2) + "\n";
+}

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,136 @@
+import { deepMerge, stripMergeDirectives, createMergeContext, isTextContent, mergeTextContent, } from "./merge.js";
+import { interpolateContent } from "./env.js";
+/**
+ * Normalizes header to array format.
+ */
+function normalizeHeader(header) {
+    if (header === undefined)
+        return undefined;
+    if (typeof header === "string")
+        return [header];
+    return header;
+}
+/**
+ * Merges PR options: per-repo overrides global defaults.
+ * Returns undefined if no options are set.
+ */
+function mergePROptions(global, perRepo) {
+    if (!global && !perRepo)
+        return undefined;
+    if (!global)
+        return perRepo;
+    if (!perRepo)
+        return global;
+    const result = {};
+    const merge = perRepo.merge ?? global.merge;
+    const mergeStrategy = perRepo.mergeStrategy ?? global.mergeStrategy;
+    const deleteBranch = perRepo.deleteBranch ?? global.deleteBranch;
+    const bypassReason = perRepo.bypassReason ?? global.bypassReason;
+    if (merge !== undefined)
+        result.merge = merge;
+    if (mergeStrategy !== undefined)
+        result.mergeStrategy = mergeStrategy;
+    if (deleteBranch !== undefined)
+        result.deleteBranch = deleteBranch;
+    if (bypassReason !== undefined)
+        result.bypassReason = bypassReason;
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/**
+ * Normalizes raw config into expanded, merged config.
+ * Pipeline: expand git arrays -> merge content -> interpolate env vars
+ */
+export function normalizeConfig(raw) {
+    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) {
+            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 fileStrategy = fileConfig.mergeStrategy ?? "replace";
+                // Step 3: Compute merged content for this file
+                let mergedContent;
+                if (repoOverride?.override) {
+                    // Override mode: use only repo file content (may be undefined for empty file)
+                    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));
+                    }
+                }
+                else if (fileConfig.content === undefined) {
+                    // Root file has no content = empty file (unless repo provides content)
+                    if (repoOverride?.content) {
+                        if (isTextContent(repoOverride.content)) {
+                            mergedContent = structuredClone(repoOverride.content);
+                        }
+                        else {
+                            mergedContent = stripMergeDirectives(structuredClone(repoOverride.content));
+                        }
+                    }
+                    else {
+                        mergedContent = null;
+                    }
+                }
+                else if (!repoOverride?.content) {
+                    // No repo override: use file base content as-is
+                    mergedContent = structuredClone(fileConfig.content);
+                }
+                else {
+                    // 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 = interpolateContent(mergedContent, { strict: true });
+                }
+                // Resolve fields: per-repo overrides root level
+                const createOnly = repoOverride?.createOnly ?? fileConfig.createOnly;
+                const executable = repoOverride?.executable ?? fileConfig.executable;
+                const header = normalizeHeader(repoOverride?.header ?? fileConfig.header);
+                const schemaUrl = repoOverride?.schemaUrl ?? fileConfig.schemaUrl;
+                files.push({
+                    fileName,
+                    content: mergedContent,
+                    createOnly,
+                    executable,
+                    header,
+                    schemaUrl,
+                });
+            }
+            // Merge PR options: per-repo overrides global
+            const prOptions = mergePROptions(raw.prOptions, rawRepo.prOptions);
+            expandedRepos.push({
+                git: gitUrl,
+                files,
+                prOptions,
+            });
+        }
+    }
+    return {
+        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,173 @@
+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 === "json5" || ext === "yaml" || ext === "yml";
+}
+/**
+ * Validates raw config structure before normalization.
+ * @throws Error if validation fails
+ */
+export function validateRawConfig(config) {
+    if (!config.files || typeof config.files !== "object") {
+        throw new Error("Config missing required field: files (must be an object)");
+    }
+    const fileNames = Object.keys(config.files);
+    if (fileNames.length === 0) {
+        throw new Error("Config files object cannot be empty");
+    }
+    // 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`);
+        }
+        // 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)) {
+            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 (fileConfig.executable !== undefined &&
+            typeof fileConfig.executable !== "boolean") {
+            throw new Error(`File '${fileName}' executable must be a boolean`);
+        }
+        if (fileConfig.header !== undefined) {
+            if (typeof fileConfig.header !== "string" &&
+                (!Array.isArray(fileConfig.header) ||
+                    !fileConfig.header.every((h) => typeof h === "string"))) {
+                throw new Error(`File '${fileName}' header must be a string or array of strings`);
+            }
+        }
+        if (fileConfig.schemaUrl !== undefined &&
+            typeof fileConfig.schemaUrl !== "string") {
+            throw new Error(`File '${fileName}' schemaUrl must be a string`);
+        }
+    }
+    if (!config.repos || !Array.isArray(config.repos)) {
+        throw new Error("Config missing required field: repos (must be an array)");
+    }
+    // Validate each repo
+    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`);
+        }
+        // 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`);
+                }
+                // 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") {
+                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' createOnly must be a boolean`);
+                }
+                if (fileOverride.executable !== undefined &&
+                    typeof fileOverride.executable !== "boolean") {
+                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' executable must be a boolean`);
+                }
+                if (fileOverride.header !== undefined) {
+                    if (typeof fileOverride.header !== "string" &&
+                        (!Array.isArray(fileOverride.header) ||
+                            !fileOverride.header.every((h) => typeof h === "string"))) {
+                        throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' header must be a string or array of strings`);
+                    }
+                }
+                if (fileOverride.schemaUrl !== undefined &&
+                    typeof fileOverride.schemaUrl !== "string") {
+                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' schemaUrl must be a string`);
+                }
+            }
+        }
+    }
+}
+/**
+ * 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";
+    }
+    return git;
+}

package/dist/config.d.ts

@@ -0,0 +1,54 @@
+import type { ArrayMergeStrategy } from "./merge.js";
+export { convertContentToString } from "./config-formatter.js";
+export type MergeMode = "manual" | "auto" | "force";
+export type MergeStrategy = "merge" | "squash" | "rebase";
+export interface PRMergeOptions {
+    merge?: MergeMode;
+    mergeStrategy?: MergeStrategy;
+    deleteBranch?: boolean;
+    bypassReason?: string;
+}
+export type ContentValue = Record<string, unknown> | string | string[];
+export interface RawFileConfig {
+    content?: ContentValue;
+    mergeStrategy?: ArrayMergeStrategy;
+    createOnly?: boolean;
+    executable?: boolean;
+    header?: string | string[];
+    schemaUrl?: string;
+}
+export interface RawRepoFileOverride {
+    content?: ContentValue;
+    override?: boolean;
+    createOnly?: boolean;
+    executable?: boolean;
+    header?: string | string[];
+    schemaUrl?: string;
+}
+export interface RawRepoConfig {
+    git: string | string[];
+    files?: Record<string, RawRepoFileOverride | false>;
+    prOptions?: PRMergeOptions;
+}
+export interface RawConfig {
+    files: Record<string, RawFileConfig>;
+    repos: RawRepoConfig[];
+    prOptions?: PRMergeOptions;
+}
+export interface FileContent {
+    fileName: string;
+    content: ContentValue | null;
+    createOnly?: boolean;
+    executable?: boolean;
+    header?: string[];
+    schemaUrl?: string;
+}
+export interface RepoConfig {
+    git: string;
+    files: FileContent[];
+    prOptions?: PRMergeOptions;
+}
+export interface Config {
+    repos: RepoConfig[];
+}
+export declare function loadConfig(filePath: string): Config;

package/dist/config.js

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parse } from "yaml";
+import { validateRawConfig } from "./config-validator.js";
+import { normalizeConfig } from "./config-normalizer.js";
+import { resolveFileReferencesInConfig } from "./file-reference-resolver.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 configDir = dirname(filePath);
+    let rawConfig;
+    try {
+        rawConfig = parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse YAML config at ${filePath}: ${message}`);
+    }
+    // Resolve file references before validation so content type checking works
+    rawConfig = resolveFileReferencesInConfig(rawConfig, { configDir });
+    validateRawConfig(rawConfig);
+    return normalizeConfig(rawConfig);
+}

package/dist/env.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Environment variable interpolation utilities.
+ * Supports ${VAR}, ${VAR:-default}, and ${VAR:?message} syntax.
+ * Use $${VAR} to escape and output literal ${VAR}.
+ */
+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 these 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
+ * - $${VAR} - Escape: outputs literal ${VAR} without interpolation
+ *
+ * @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>;
+/**
+ * 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[];