@aspruyt/xfg 1.0.0

package/dist/env.js

@@ -0,0 +1,144 @@
+/**
+ * Environment variable interpolation utilities.
+ * Supports ${VAR}, ${VAR:-default}, and ${VAR:?message} syntax.
+ * Use $${VAR} to escape and output literal ${VAR}.
+ */
+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;
+/**
+ * Regex to match escaped environment variable placeholders.
+ * $${...} outputs literal ${...} without interpolation.
+ * Example: $${VAR} -> ${VAR}, $${VAR:-default} -> ${VAR:-default}
+ */
+const ESCAPED_VAR_REGEX = /\$\$\{([^}]+)\}/g;
+/**
+ * Placeholder prefix for temporarily storing escaped sequences.
+ * Uses null bytes which won't appear in normal content.
+ */
+const ESCAPE_PLACEHOLDER = "\x00ESCAPED_VAR\x00";
+/**
+ * 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.
+ * Supports escaping with $${VAR} syntax to output literal ${VAR}.
+ */
+function processString(value, options) {
+    // Phase 1: Replace escaped $${...} with placeholders
+    const escapedContent = [];
+    let processed = value.replace(ESCAPED_VAR_REGEX, (_match, content) => {
+        const index = escapedContent.length;
+        escapedContent.push(content);
+        return `${ESCAPE_PLACEHOLDER}${index}\x00`;
+    });
+    // Phase 2: Interpolate remaining ${...}
+    processed = processed.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;
+    });
+    // Phase 3: Restore escaped sequences as literal ${...}
+    processed = processed.replace(new RegExp(`${ESCAPE_PLACEHOLDER}(\\d+)\x00`, "g"), (_match, indexStr) => {
+        const index = parseInt(indexStr, 10);
+        return `\${${escapedContent[index]}}`;
+    });
+    return processed;
+}
+/**
+ * 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 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 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/file-reference-resolver.d.ts

@@ -0,0 +1,20 @@
+import type { ContentValue, RawConfig } from "./config.js";
+export interface FileReferenceOptions {
+    configDir: string;
+}
+/**
+ * Check if a value is a file reference (string starting with @)
+ */
+export declare function isFileReference(value: unknown): value is string;
+/**
+ * Resolve a file reference to its content.
+ * - JSON files are parsed as objects
+ * - YAML files are parsed as objects
+ * - Other files are returned as strings
+ */
+export declare function resolveFileReference(reference: string, configDir: string): ContentValue;
+/**
+ * Resolve all file references in a raw config.
+ * Walks through files at root level and per-repo level.
+ */
+export declare function resolveFileReferencesInConfig(raw: RawConfig, options: FileReferenceOptions): RawConfig;

package/dist/file-reference-resolver.js

@@ -0,0 +1,135 @@
+import { readFileSync } from "node:fs";
+import { resolve, isAbsolute, normalize, extname } from "node:path";
+import JSON5 from "json5";
+import { parse as parseYaml } from "yaml";
+/**
+ * Check if a value is a file reference (string starting with @)
+ */
+export function isFileReference(value) {
+    return typeof value === "string" && value.startsWith("@");
+}
+/**
+ * Resolve a file reference to its content.
+ * - JSON files are parsed as objects
+ * - YAML files are parsed as objects
+ * - Other files are returned as strings
+ */
+export function resolveFileReference(reference, configDir) {
+    const relativePath = reference.slice(1); // Remove @ prefix
+    if (relativePath.length === 0) {
+        throw new Error(`Invalid file reference "${reference}": path is empty`);
+    }
+    // Security: block absolute paths
+    if (isAbsolute(relativePath)) {
+        throw new Error(`File reference "${reference}" uses absolute path. Use relative paths only.`);
+    }
+    const resolvedPath = resolve(configDir, relativePath);
+    const normalizedResolved = normalize(resolvedPath);
+    const normalizedConfigDir = normalize(configDir);
+    // Security: ensure path stays within config directory tree
+    // Use path separator to ensure we're checking directory boundaries
+    if (!normalizedResolved.startsWith(normalizedConfigDir + "/") &&
+        normalizedResolved !== normalizedConfigDir) {
+        throw new Error(`File reference "${reference}" escapes config directory. ` +
+            `References must be within "${configDir}".`);
+    }
+    // Load file
+    let content;
+    try {
+        content = readFileSync(resolvedPath, "utf-8");
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to load file reference "${reference}": ${msg}`);
+    }
+    // Parse based on extension
+    const ext = extname(relativePath).toLowerCase();
+    if (ext === ".json") {
+        try {
+            return JSON.parse(content);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid JSON in "${reference}": ${msg}`);
+        }
+    }
+    if (ext === ".json5") {
+        try {
+            return JSON5.parse(content);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid JSON5 in "${reference}": ${msg}`);
+        }
+    }
+    if (ext === ".yaml" || ext === ".yml") {
+        try {
+            return parseYaml(content);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid YAML in "${reference}": ${msg}`);
+        }
+    }
+    // Text file - return as string
+    return content;
+}
+/**
+ * Recursively resolve file references in a content value.
+ * Only string values starting with @ are resolved.
+ */
+function resolveContentValue(value, configDir) {
+    if (value === undefined) {
+        return undefined;
+    }
+    // If it's a file reference, resolve it
+    if (isFileReference(value)) {
+        return resolveFileReference(value, configDir);
+    }
+    // Otherwise return as-is (objects, arrays, plain strings)
+    return value;
+}
+/**
+ * Resolve all file references in a raw config.
+ * Walks through files at root level and per-repo level.
+ */
+export function resolveFileReferencesInConfig(raw, options) {
+    const { configDir } = options;
+    // Deep clone to avoid mutating input
+    const result = JSON.parse(JSON.stringify(raw));
+    // Resolve root-level file content
+    if (result.files) {
+        for (const [fileName, fileConfig] of Object.entries(result.files)) {
+            if (fileConfig &&
+                typeof fileConfig === "object" &&
+                "content" in fileConfig) {
+                const resolved = resolveContentValue(fileConfig.content, configDir);
+                if (resolved !== undefined) {
+                    result.files[fileName] = { ...fileConfig, content: resolved };
+                }
+            }
+        }
+    }
+    // Resolve per-repo file content
+    if (result.repos) {
+        for (const repo of result.repos) {
+            if (repo.files) {
+                for (const [fileName, fileOverride] of Object.entries(repo.files)) {
+                    // Skip false (exclusion) entries
+                    if (fileOverride === false) {
+                        continue;
+                    }
+                    if (fileOverride &&
+                        typeof fileOverride === "object" &&
+                        "content" in fileOverride) {
+                        const resolved = resolveContentValue(fileOverride.content, configDir);
+                        if (resolved !== undefined) {
+                            repo.files[fileName] = { ...fileOverride, content: resolved };
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return result;
+}

package/dist/git-ops.d.ts

@@ -0,0 +1,75 @@
+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): Promise<void>;
+    /**
+     * Create a new branch from the current HEAD.
+     * Always creates fresh - existing branches should be cleaned up beforehand
+     * by closing any existing PRs (which deletes the remote branch).
+     */
+    createBranch(branchName: string): Promise<void>;
+    writeFile(fileName: string, content: string): void;
+    /**
+     * Marks a file as executable in git using update-index --chmod=+x.
+     * This modifies the file mode in git's index, not the filesystem.
+     * @param fileName - The file path relative to the work directory
+     */
+    setExecutable(fileName: string): Promise<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(): Promise<boolean>;
+    /**
+     * Check if there are staged changes ready to commit.
+     * Uses `git diff --cached --quiet` which exits with 1 if there are staged changes.
+     */
+    hasStagedChanges(): Promise<boolean>;
+    /**
+     * Check if a file exists on a specific branch.
+     * Used for createOnly checks against the base branch (not the working directory).
+     */
+    fileExistsOnBranch(fileName: string, branch: string): Promise<boolean>;
+    /**
+     * Stage all changes and commit with the given message.
+     * Uses --no-verify to skip pre-commit hooks (config sync should always succeed).
+     * @returns true if a commit was made, false if there were no staged changes
+     */
+    commit(message: string): Promise<boolean>;
+    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;

package/dist/git-ops.js

@@ -0,0 +1,229 @@
+import { rmSync, existsSync, mkdirSync, writeFileSync, readFileSync, } from "node:fs";
+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";
+import { logger } from "./logger.js";
+export class GitOps {
+    workDir;
+    dryRun;
+    executor;
+    retries;
+    constructor(options) {
+        this.workDir = options.workDir;
+        this.dryRun = options.dryRun ?? false;
+        this.executor = options.executor ?? defaultExecutor;
+        this.retries = options.retries ?? 3;
+    }
+    async exec(command, cwd) {
+        return this.executor.exec(command, cwd ?? this.workDir);
+    }
+    /**
+     * Run a command with retry logic for transient failures.
+     * Used for network operations like clone, fetch, push.
+     */
+    async execWithRetry(command, cwd) {
+        return withRetry(() => this.exec(command, cwd), {
+            retries: this.retries,
+        });
+    }
+    /**
+     * Validates that a file path doesn't escape the workspace directory.
+     * @returns The resolved absolute file path
+     * @throws Error if path traversal is detected
+     */
+    validatePath(fileName) {
+        const filePath = join(this.workDir, fileName);
+        const resolvedPath = resolve(filePath);
+        const resolvedWorkDir = resolve(this.workDir);
+        const relativePath = relative(resolvedWorkDir, resolvedPath);
+        if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+            throw new Error(`Path traversal detected: ${fileName}`);
+        }
+        return filePath;
+    }
+    cleanWorkspace() {
+        if (existsSync(this.workDir)) {
+            rmSync(this.workDir, { recursive: true, force: true });
+        }
+        mkdirSync(this.workDir, { recursive: true });
+    }
+    async clone(gitUrl) {
+        await this.execWithRetry(`git clone ${escapeShellArg(gitUrl)} .`, this.workDir);
+    }
+    /**
+     * Create a new branch from the current HEAD.
+     * Always creates fresh - existing branches should be cleaned up beforehand
+     * by closing any existing PRs (which deletes the remote branch).
+     */
+    async createBranch(branchName) {
+        try {
+            await this.exec(`git checkout -b ${escapeShellArg(branchName)}`, this.workDir);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to create branch '${branchName}': ${message}`);
+        }
+    }
+    writeFile(fileName, content) {
+        if (this.dryRun) {
+            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");
+    }
+    /**
+     * Marks a file as executable in git using update-index --chmod=+x.
+     * This modifies the file mode in git's index, not the filesystem.
+     * @param fileName - The file path relative to the work directory
+     */
+    async setExecutable(fileName) {
+        if (this.dryRun) {
+            return;
+        }
+        const filePath = this.validatePath(fileName);
+        // Use relative path from workDir for git command
+        const relativePath = relative(this.workDir, filePath);
+        await this.exec(`git update-index --add --chmod=+x ${escapeShellArg(relativePath)}`, this.workDir);
+    }
+    /**
+     * Checks if writing the given content would result in changes.
+     * Works in both normal and dry-run modes by comparing content directly.
+     */
+    wouldChange(fileName, content) {
+        const filePath = this.validatePath(fileName);
+        // Normalize trailing newline - ensure exactly one
+        const newContent = content.endsWith("\n") ? content : content + "\n";
+        if (!existsSync(filePath)) {
+            // File doesn't exist, so writing it would be a change
+            return true;
+        }
+        try {
+            const existingContent = readFileSync(filePath, "utf-8");
+            return existingContent !== newContent;
+        }
+        catch {
+            // If we can't read the file, assume it would change
+            return true;
+        }
+    }
+    async hasChanges() {
+        const status = await this.exec("git status --porcelain", this.workDir);
+        return status.length > 0;
+    }
+    /**
+     * Check if there are staged changes ready to commit.
+     * Uses `git diff --cached --quiet` which exits with 1 if there are staged changes.
+     */
+    async hasStagedChanges() {
+        try {
+            await this.exec("git diff --cached --quiet", this.workDir);
+            return false; // Exit code 0 = no staged changes
+        }
+        catch {
+            return true; // Exit code 1 = there are staged changes
+        }
+    }
+    /**
+     * Check if a file exists on a specific branch.
+     * Used for createOnly checks against the base branch (not the working directory).
+     */
+    async fileExistsOnBranch(fileName, branch) {
+        try {
+            await this.exec(`git show ${escapeShellArg(branch)}:${escapeShellArg(fileName)}`, this.workDir);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Stage all changes and commit with the given message.
+     * Uses --no-verify to skip pre-commit hooks (config sync should always succeed).
+     * @returns true if a commit was made, false if there were no staged changes
+     */
+    async commit(message) {
+        if (this.dryRun) {
+            return true;
+        }
+        await this.exec("git add -A", this.workDir);
+        // Check if there are actually staged changes after git add
+        if (!(await this.hasStagedChanges())) {
+            return false; // No changes to commit
+        }
+        // Use --no-verify to skip pre-commit hooks
+        await this.exec(`git commit --no-verify -m ${escapeShellArg(message)}`, this.workDir);
+        return true;
+    }
+    async push(branchName) {
+        if (this.dryRun) {
+            return;
+        }
+        await this.execWithRetry(`git push -u origin ${escapeShellArg(branchName)}`, this.workDir);
+    }
+    async getDefaultBranch() {
+        try {
+            // Try to get the default branch from remote (network operation with retry)
+            const remoteInfo = await this.execWithRetry("git remote show origin", this.workDir);
+            const match = remoteInfo.match(/HEAD branch: (\S+)/);
+            if (match) {
+                return { branch: match[1], method: "remote HEAD" };
+            }
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            logger.info(`Debug: git remote show origin failed - ${msg}`);
+        }
+        // Try common default branch names (local operations, no retry needed)
+        try {
+            await this.exec("git rev-parse --verify origin/main", this.workDir);
+            return { branch: "main", method: "origin/main exists" };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            logger.info(`Debug: origin/main check failed - ${msg}`);
+        }
+        try {
+            await this.exec("git rev-parse --verify origin/master", this.workDir);
+            return { branch: "master", method: "origin/master exists" };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            logger.info(`Debug: origin/master check failed - ${msg}`);
+        }
+        return { branch: "main", method: "fallback default" };
+    }
+}
+export function sanitizeBranchName(fileName) {
+    return fileName
+        .toLowerCase()
+        .replace(/\.[^.]+$/, "") // Remove extension
+        .replace(/[^a-z0-9-]/g, "-") // Replace non-alphanumeric with dashes
+        .replace(/-+/g, "-") // Collapse multiple dashes
+        .replace(/^-|-$/g, ""); // Remove leading/trailing dashes
+}
+/**
+ * Validates a user-provided branch name against git's naming rules.
+ * @throws Error if the branch name is invalid
+ */
+export function validateBranchName(branchName) {
+    if (!branchName || branchName.trim() === "") {
+        throw new Error("Branch name cannot be empty");
+    }
+    if (branchName.startsWith(".") || branchName.startsWith("-")) {
+        throw new Error('Branch name cannot start with "." or "-"');
+    }
+    // Git disallows: space, ~, ^, :, ?, *, [, \, and consecutive dots (..)
+    if (/[\s~^:?*\[\\]/.test(branchName) || branchName.includes("..")) {
+        throw new Error("Branch name contains invalid characters");
+    }
+    if (branchName.endsWith("/") ||
+        branchName.endsWith(".lock") ||
+        branchName.endsWith(".")) {
+        throw new Error("Branch name has invalid ending");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { ProcessorResult } from "./repository-processor.js";
+import { RepoConfig } from "./config.js";
+import { RepoInfo } from "./repo-detector.js";
+import { ProcessorOptions } from "./repository-processor.js";
+/**
+ * Processor interface for dependency injection in tests.
+ */
+export interface IRepositoryProcessor {
+    process(repoConfig: RepoConfig, repoInfo: RepoInfo, options: ProcessorOptions): Promise<ProcessorResult>;
+}
+/**
+ * Factory function type for creating processors.
+ * Allows dependency injection for testing.
+ */
+export type ProcessorFactory = () => IRepositoryProcessor;
+/**
+ * Default factory that creates a real RepositoryProcessor.
+ */
+export declare const defaultProcessorFactory: ProcessorFactory;