@aspruyt/xfg 6.2.0 → 6.4.0

package/dist/secrets/processor.js

@@ -0,0 +1,115 @@
+import { isGitHubRepo, getRepoDisplayName, } from "../repo/index.js";
+export class SecretsProcessor {
+    strategy;
+    encryptor;
+    envResolver;
+    constructor(strategy, encryptor, envResolver) {
+        this.strategy = strategy;
+        this.encryptor = encryptor;
+        this.envResolver = envResolver;
+    }
+    async process(secretsConfig, repoInfo, options) {
+        const repoName = getRepoDisplayName(repoInfo);
+        if (!isGitHubRepo(repoInfo)) {
+            return {
+                success: true,
+                repoName,
+                message: "Skipped: not a GitHub repository",
+                skipped: true,
+                created: 0,
+                updated: 0,
+                deleted: 0,
+            };
+        }
+        const githubRepo = repoInfo;
+        const { deleteOrphaned: configDeleteOrphaned = false, ...rawEntries } = secretsConfig;
+        const { dryRun, token, noDelete } = options;
+        const deleteOrphaned = configDeleteOrphaned && !(noDelete ?? false);
+        const strategyOptions = { token, host: githubRepo.host };
+        const secretEntries = Object.entries(rawEntries).filter((entry) => typeof entry[1] !== "boolean");
+        let resolvedValues;
+        if (!dryRun && secretEntries.length > 0) {
+            resolvedValues = this.envResolver.resolveAll(secretEntries.map(([name, config]) => ({
+                name,
+                envVar: config.env,
+            })));
+        }
+        else {
+            resolvedValues = new Map();
+        }
+        const currentSecrets = await this.strategy.list(githubRepo, strategyOptions);
+        const currentByName = new Set(currentSecrets.map((s) => s.name.toUpperCase()));
+        const desiredNames = new Set(secretEntries.map(([name]) => name.toUpperCase()));
+        let created = 0;
+        let updated = 0;
+        let deleted = 0;
+        if (!dryRun) {
+            if (secretEntries.length > 0) {
+                const publicKey = await this.strategy.getPublicKey(githubRepo, strategyOptions);
+                for (const [name] of secretEntries) {
+                    const value = resolvedValues.get(name);
+                    const encrypted = await this.encryptor.encrypt(value, publicKey.key);
+                    await this.strategy.upsert(githubRepo, name, encrypted, publicKey.key_id, strategyOptions);
+                    if (currentByName.has(name.toUpperCase())) {
+                        updated++;
+                    }
+                    else {
+                        created++;
+                    }
+                }
+            }
+            if (deleteOrphaned) {
+                for (const current of currentSecrets) {
+                    if (!desiredNames.has(current.name.toUpperCase())) {
+                        await this.strategy.delete(githubRepo, current.name, strategyOptions);
+                        deleted++;
+                    }
+                }
+            }
+        }
+        else {
+            for (const [name] of secretEntries) {
+                if (currentByName.has(name.toUpperCase())) {
+                    updated++;
+                }
+                else {
+                    created++;
+                }
+            }
+            if (deleteOrphaned) {
+                for (const current of currentSecrets) {
+                    if (!desiredNames.has(current.name.toUpperCase())) {
+                        deleted++;
+                    }
+                }
+            }
+        }
+        const parts = [];
+        if (created > 0)
+            parts.push(`${created} created`);
+        if (updated > 0)
+            parts.push(`${updated} updated`);
+        if (deleted > 0)
+            parts.push(`${deleted} deleted`);
+        const summary = parts.length > 0 ? parts.join(", ") : "no changes";
+        if (dryRun) {
+            return {
+                success: true,
+                repoName,
+                message: `[DRY RUN] ${summary}`,
+                dryRun: true,
+                created,
+                updated,
+                deleted,
+            };
+        }
+        return {
+            success: true,
+            repoName,
+            message: summary,
+            created,
+            updated,
+            deleted,
+        };
+    }
+}

package/dist/secrets/types.d.ts

@@ -0,0 +1,21 @@
+import type { RepoInfo } from "../repo/index.js";
+import type { GhApiOptions } from "../shared/gh-api-utils.js";
+export interface GitHubSecret {
+    name: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface GitHubSecretsListResponse {
+    total_count: number;
+    secrets: GitHubSecret[];
+}
+export interface GitHubPublicKey {
+    key_id: string;
+    key: string;
+}
+export interface ISecretsStrategy {
+    list(repoInfo: RepoInfo, options?: GhApiOptions): Promise<GitHubSecret[]>;
+    getPublicKey(repoInfo: RepoInfo, options?: GhApiOptions): Promise<GitHubPublicKey>;
+    upsert(repoInfo: RepoInfo, name: string, encryptedValue: string, keyId: string, options?: GhApiOptions): Promise<void>;
+    delete(repoInfo: RepoInfo, name: string, options?: GhApiOptions): Promise<void>;
+}

package/dist/secrets/types.js

@@ -0,0 +1 @@
+export {};

package/dist/settings/index.d.ts

@@ -3,3 +3,4 @@ export { type PropertyDiff, type RulesetPlanEntry, RulesetProcessor, type IRules
 export { RepoSettingsProcessor, type IRepoSettingsProcessor, type RepoSettingsPlanEntry, GitHubRepoSettingsStrategy, } from "./repo-settings/index.js";
 export { type LabelsPlanEntry, LabelsProcessor, type ILabelsProcessor, GitHubLabelsStrategy, } from "./labels/index.js";
 export { type CodeScanningPlanEntry, CodeScanningProcessor, type ICodeScanningProcessor, GitHubCodeScanningStrategy, } from "./code-scanning/index.js";
+export { type VariablesPlanEntry, VariablesProcessor, type IVariablesProcessor, GitHubVariablesStrategy, } from "./variables/index.js";

package/dist/settings/index.js

@@ -8,3 +8,5 @@ export { RepoSettingsProcessor, GitHubRepoSettingsStrategy, } from "./repo-setti
 export { LabelsProcessor, GitHubLabelsStrategy, } from "./labels/index.js";
 // Code scanning
 export { CodeScanningProcessor, GitHubCodeScanningStrategy, } from "./code-scanning/index.js";
+// Variables
+export { VariablesProcessor, GitHubVariablesStrategy, } from "./variables/index.js";

package/dist/settings/variables/diff.d.ts

@@ -0,0 +1,10 @@
+import type { GitHubVariable } from "./types.js";
+import type { SettingsAction } from "../base-processor.js";
+export type VariableAction = SettingsAction;
+export interface VariableChange {
+    action: VariableAction;
+    name: string;
+    oldValue?: string;
+    newValue?: string;
+}
+export declare function diffVariables(current: GitHubVariable[], desired: Record<string, string>, deleteOrphaned: boolean): VariableChange[];

package/dist/settings/variables/diff.js

@@ -0,0 +1,39 @@
+export function diffVariables(current, desired, deleteOrphaned) {
+    const changes = [];
+    const currentByName = new Map();
+    for (const v of current) {
+        currentByName.set(v.name.toUpperCase(), v);
+    }
+    const desiredUpper = new Set(Object.keys(desired).map((n) => n.toUpperCase()));
+    for (const [name, desiredValue] of Object.entries(desired)) {
+        const currentVar = currentByName.get(name.toUpperCase());
+        if (!currentVar) {
+            changes.push({ action: "create", name, newValue: desiredValue });
+        }
+        else if (currentVar.value !== desiredValue) {
+            changes.push({
+                action: "update",
+                name: currentVar.name,
+                oldValue: currentVar.value,
+                newValue: desiredValue,
+            });
+        }
+        else {
+            changes.push({ action: "unchanged", name: currentVar.name });
+        }
+    }
+    if (deleteOrphaned) {
+        for (const [nameUpper, currentVar] of currentByName) {
+            if (!desiredUpper.has(nameUpper)) {
+                changes.push({ action: "delete", name: currentVar.name });
+            }
+        }
+    }
+    const actionOrder = {
+        delete: 0,
+        update: 1,
+        create: 2,
+        unchanged: 3,
+    };
+    return changes.sort((a, b) => actionOrder[a.action] - actionOrder[b.action]);
+}

package/dist/settings/variables/formatter.d.ts

@@ -0,0 +1,16 @@
+import type { VariableChange, VariableAction } from "./diff.js";
+export interface VariablesPlanEntry {
+    name: string;
+    action: VariableAction;
+    oldValue?: string;
+    newValue?: string;
+}
+export interface VariablesPlanResult {
+    lines: string[];
+    creates: number;
+    updates: number;
+    deletes: number;
+    unchanged: number;
+    entries: VariablesPlanEntry[];
+}
+export declare function formatVariablesPlan(changes: VariableChange[]): VariablesPlanResult;

package/dist/settings/variables/formatter.js

@@ -0,0 +1,70 @@
+import chalk from "chalk";
+import { countActions } from "../base-processor.js";
+export function formatVariablesPlan(changes) {
+    const lines = [];
+    const entries = [];
+    const { create: creates, update: updates, delete: deletes, unchanged, } = countActions(changes);
+    const grouped = {
+        create: [],
+        update: [],
+        delete: [],
+        unchanged: [],
+    };
+    for (const c of changes) {
+        grouped[c.action].push(c);
+    }
+    if (grouped.create.length > 0) {
+        lines.push(chalk.bold("  Create:"));
+        for (const change of grouped.create) {
+            lines.push(chalk.green(`    + variable "${change.name}"`));
+            if (change.newValue !== undefined) {
+                lines.push(chalk.green(`        value: "${change.newValue}"`));
+            }
+            entries.push({
+                name: change.name,
+                action: "create",
+                newValue: change.newValue,
+            });
+            lines.push("");
+        }
+    }
+    if (grouped.update.length > 0) {
+        lines.push(chalk.bold("  Update:"));
+        for (const change of grouped.update) {
+            lines.push(chalk.yellow(`    ~ variable "${change.name}"`));
+            if (change.oldValue !== undefined && change.newValue !== undefined) {
+                lines.push(chalk.yellow(`        value: "${change.oldValue}" → "${change.newValue}"`));
+            }
+            entries.push({
+                name: change.name,
+                action: "update",
+                oldValue: change.oldValue,
+                newValue: change.newValue,
+            });
+            lines.push("");
+        }
+    }
+    if (grouped.delete.length > 0) {
+        lines.push(chalk.bold("  Delete:"));
+        for (const change of grouped.delete) {
+            lines.push(chalk.red(`    - variable "${change.name}"`));
+            entries.push({ name: change.name, action: "delete" });
+        }
+        lines.push("");
+    }
+    for (const change of grouped.unchanged) {
+        entries.push({ name: change.name, action: "unchanged" });
+    }
+    const total = creates + updates + deletes;
+    if (total > 0) {
+        const parts = [];
+        if (creates > 0)
+            parts.push(`${creates} to create`);
+        if (updates > 0)
+            parts.push(`${updates} to update`);
+        if (deletes > 0)
+            parts.push(`${deletes} to delete`);
+        lines.push(`  Plan: ${total} variables (${parts.join(", ")})`);
+    }
+    return { lines, creates, updates, deletes, unchanged, entries };
+}

package/dist/settings/variables/github-variables-strategy.d.ts

@@ -0,0 +1,17 @@
+import type { ICommandExecutor } from "../../shared/command-executor.js";
+import { type RepoInfo } from "../../repo/index.js";
+import { type GhApiOptions } from "../../shared/gh-api-utils.js";
+import type { IVariablesStrategy, GitHubVariable } from "./types.js";
+interface GitHubVariablesStrategyOptions {
+    retries?: number;
+    cwd: string;
+}
+export declare class GitHubVariablesStrategy implements IVariablesStrategy {
+    private api;
+    constructor(executor: ICommandExecutor, options: GitHubVariablesStrategyOptions);
+    list(repoInfo: RepoInfo, options?: GhApiOptions): Promise<GitHubVariable[]>;
+    create(repoInfo: RepoInfo, name: string, value: string, options?: GhApiOptions): Promise<void>;
+    update(repoInfo: RepoInfo, name: string, value: string, options?: GhApiOptions): Promise<void>;
+    delete(repoInfo: RepoInfo, name: string, options?: GhApiOptions): Promise<void>;
+}
+export {};

package/dist/settings/variables/github-variables-strategy.js

@@ -0,0 +1,40 @@
+import { assertGitHubRepo } from "../../repo/index.js";
+import { GhApiClient } from "../../shared/gh-api-utils.js";
+import { parseApiJson } from "../../shared/json-utils.js";
+export class GitHubVariablesStrategy {
+    api;
+    constructor(executor, options) {
+        this.api = new GhApiClient(executor, options.retries ?? 3, options.cwd);
+    }
+    async list(repoInfo, options) {
+        assertGitHubRepo(repoInfo, "GitHub Variables strategy");
+        const endpoint = `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/variables`;
+        const result = await this.api.call("GET", endpoint, {
+            options,
+            paginate: true,
+        });
+        const response = parseApiJson(result, "variables response");
+        return response.variables ?? [];
+    }
+    async create(repoInfo, name, value, options) {
+        assertGitHubRepo(repoInfo, "GitHub Variables strategy");
+        const endpoint = `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/variables`;
+        await this.api.call("POST", endpoint, {
+            payload: { name, value },
+            options,
+        });
+    }
+    async update(repoInfo, name, value, options) {
+        assertGitHubRepo(repoInfo, "GitHub Variables strategy");
+        const endpoint = `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/variables/${encodeURIComponent(name)}`;
+        await this.api.call("PATCH", endpoint, {
+            payload: { value },
+            options,
+        });
+    }
+    async delete(repoInfo, name, options) {
+        assertGitHubRepo(repoInfo, "GitHub Variables strategy");
+        const endpoint = `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/variables/${encodeURIComponent(name)}`;
+        await this.api.call("DELETE", endpoint, { options });
+    }
+}

package/dist/settings/variables/index.d.ts

@@ -0,0 +1,4 @@
+export { type VariableChange, type VariableAction } from "./diff.js";
+export { type VariablesPlanEntry } from "./formatter.js";
+export { VariablesProcessor, type IVariablesProcessor } from "./processor.js";
+export { GitHubVariablesStrategy } from "./github-variables-strategy.js";

package/dist/settings/variables/index.js

@@ -0,0 +1,2 @@
+export { VariablesProcessor } from "./processor.js";
+export { GitHubVariablesStrategy } from "./github-variables-strategy.js";

package/dist/settings/variables/processor.d.ts

@@ -0,0 +1,19 @@
+import type { RepoConfig } from "../../config/index.js";
+import type { RepoInfo } from "../../repo/index.js";
+import { type VariablesPlanResult } from "./formatter.js";
+import type { IVariablesStrategy } from "./types.js";
+import { type BaseProcessorOptions, type BaseProcessorResult, type ISettingsProcessor, type ChangeCounts } from "../base-processor.js";
+export type IVariablesProcessor = ISettingsProcessor<VariablesProcessorOptions, VariablesProcessorResult>;
+export interface VariablesProcessorOptions extends BaseProcessorOptions {
+    noDelete?: boolean;
+}
+export interface VariablesProcessorResult extends BaseProcessorResult {
+    changes?: ChangeCounts;
+    planOutput?: VariablesPlanResult;
+}
+export declare class VariablesProcessor implements IVariablesProcessor {
+    private readonly strategy;
+    constructor(strategy: IVariablesStrategy);
+    process(repoConfig: RepoConfig, repoInfo: RepoInfo, options: VariablesProcessorOptions): Promise<VariablesProcessorResult>;
+    private applySettings;
+}

package/dist/settings/variables/processor.js

@@ -0,0 +1,60 @@
+import { diffVariables } from "./diff.js";
+import { formatVariablesPlan } from "./formatter.js";
+import { withGitHubGuards, countActions, buildDryRunResult, buildApplyResult, } from "../base-processor.js";
+export class VariablesProcessor {
+    strategy;
+    constructor(strategy) {
+        this.strategy = strategy;
+    }
+    async process(repoConfig, repoInfo, options) {
+        return withGitHubGuards(repoConfig, repoInfo, options, {
+            hasDesiredSettings: (rc) => {
+                const vars = rc.settings?.variables ?? {};
+                const { deleteOrphaned, ...entries } = vars;
+                return Object.keys(entries).length > 0 || deleteOrphaned === true;
+            },
+            emptySettingsMessage: "No variables configured",
+            applySettings: (githubRepo, rc, opts, token, repoName) => this.applySettings(githubRepo, rc, opts, token, repoName),
+        });
+    }
+    async applySettings(githubRepo, repoConfig, options, effectiveToken, repoName) {
+        const { dryRun, noDelete } = options;
+        const settings = repoConfig.settings;
+        const { deleteOrphaned: varDeleteOrphaned = false, ...desiredVariables } = (settings?.variables ?? {});
+        const deleteOrphaned = varDeleteOrphaned && !(noDelete ?? false);
+        const strategyOptions = { token: effectiveToken, host: githubRepo.host };
+        const currentVariables = await this.strategy.list(githubRepo, strategyOptions);
+        const changes = diffVariables(currentVariables, desiredVariables, deleteOrphaned);
+        const changeCounts = countActions(changes);
+        const planOutput = formatVariablesPlan(changes);
+        if (dryRun) {
+            return buildDryRunResult(repoName, changeCounts, { planOutput });
+        }
+        let appliedCount = 0;
+        for (const change of changes) {
+            switch (change.action) {
+                case "create":
+                    if (change.newValue !== undefined) {
+                        await this.strategy.create(githubRepo, change.name, change.newValue, strategyOptions);
+                        appliedCount++;
+                    }
+                    break;
+                case "update":
+                    if (change.newValue !== undefined) {
+                        await this.strategy.update(githubRepo, change.name, change.newValue, strategyOptions);
+                        appliedCount++;
+                    }
+                    break;
+                case "delete":
+                    await this.strategy.delete(githubRepo, change.name, strategyOptions);
+                    appliedCount++;
+                    break;
+                case "unchanged":
+                    break;
+            }
+        }
+        return buildApplyResult(repoName, changeCounts, appliedCount, {
+            planOutput,
+        });
+    }
+}

package/dist/settings/variables/types.d.ts

@@ -0,0 +1,18 @@
+import type { RepoInfo } from "../../repo/index.js";
+import type { GhApiOptions } from "../../shared/gh-api-utils.js";
+export interface GitHubVariable {
+    name: string;
+    value: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface GitHubVariablesListResponse {
+    total_count: number;
+    variables: GitHubVariable[];
+}
+export interface IVariablesStrategy {
+    list(repoInfo: RepoInfo, options?: GhApiOptions): Promise<GitHubVariable[]>;
+    create(repoInfo: RepoInfo, name: string, value: string, options?: GhApiOptions): Promise<void>;
+    update(repoInfo: RepoInfo, name: string, value: string, options?: GhApiOptions): Promise<void>;
+    delete(repoInfo: RepoInfo, name: string, options?: GhApiOptions): Promise<void>;
+}

package/dist/settings/variables/types.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/branch-validation.d.ts

@@ -0,0 +1,2 @@
+/** Validates a user-provided branch name against git's naming rules. @throws ValidationError if the branch name is invalid */
+export declare function validateBranchName(branchName: string): void;

package/dist/shared/branch-validation.js

@@ -0,0 +1,19 @@
+import { ValidationError } from "./errors.js";
+/** Validates a user-provided branch name against git's naming rules. @throws ValidationError if the branch name is invalid */
+export function validateBranchName(branchName) {
+    if (!branchName || branchName.trim() === "") {
+        throw new ValidationError("Branch name cannot be empty");
+    }
+    if (branchName.startsWith(".") || branchName.startsWith("-")) {
+        throw new ValidationError('Branch name cannot start with "." or "-"');
+    }
+    // Git disallows: space, ~, ^, :, ?, *, [, \, and consecutive dots (..)
+    if (/[\s~^:?*[\\]/.test(branchName) || branchName.includes("..")) {
+        throw new ValidationError("Branch name contains invalid characters");
+    }
+    if (branchName.endsWith("/") ||
+        branchName.endsWith(".lock") ||
+        branchName.endsWith(".")) {
+        throw new ValidationError("Branch name has invalid ending");
+    }
+}

package/dist/shared/env-resolver.d.ts

@@ -0,0 +1,16 @@
+export interface IEnvResolver {
+    resolve(envName: string): string;
+    resolveAll(entries: {
+        name: string;
+        envVar: string;
+    }[]): Map<string, string>;
+}
+export declare class EnvResolver implements IEnvResolver {
+    private readonly env;
+    constructor(env: Record<string, string | undefined>);
+    resolve(envName: string): string;
+    resolveAll(entries: {
+        name: string;
+        envVar: string;
+    }[]): Map<string, string>;
+}

package/dist/shared/env-resolver.js

@@ -0,0 +1,33 @@
+export class EnvResolver {
+    env;
+    constructor(env) {
+        this.env = env;
+    }
+    resolve(envName) {
+        const value = this.env[envName];
+        if (value === undefined) {
+            throw new Error(`Environment variable '${envName}' is not set.`);
+        }
+        if (value === "") {
+            throw new Error(`Environment variable '${envName}' is empty.`);
+        }
+        return value;
+    }
+    resolveAll(entries) {
+        const missing = new Set();
+        const result = new Map();
+        for (const { name, envVar } of entries) {
+            const value = this.env[envVar];
+            if (value === undefined || value === "") {
+                missing.add(envVar);
+            }
+            else {
+                result.set(name, value);
+            }
+        }
+        if (missing.size > 0) {
+            throw new Error(`Missing environment variables: ${[...missing].join(", ")}`);
+        }
+        return result;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "6.2.0",
+  "version": "6.4.0",
   "description": "Manage files, settings, and repositories across GitHub, Azure DevOps, and GitLab — declaratively, from a single YAML config",
   "type": "module",
   "main": "dist/index.js",
@@ -74,10 +74,12 @@
     "chalk": "^5.3.0",
     "commander": "^14.0.2",
     "json5": "^2.2.3",
+    "libsodium-wrappers": "^0.8.4",
     "p-retry": "^8.0.0",
     "yaml": "^2.4.5"
   },
   "devDependencies": {
+    "@types/libsodium-wrappers": "^0.8.0",
     "@types/node": "^24.12.2",
     "bottleneck": "^2.19.5",
     "c8": "^11.0.0",