@aspruyt/xfg 3.9.12 → 3.9.14

package/dist/settings/labels/diff.js

@@ -0,0 +1,156 @@
+import { normalizeColor } from "./converter.js";
+/**
+ * Compares current labels (from GitHub) with desired labels (from config).
+ *
+ * Matching is case-insensitive by name (GitHub label names are case-insensitive).
+ * Color comparison is case-insensitive bare hex (strip #, lowercase both sides).
+ * Description: undefined in config means "do not compare" (leave current value).
+ * An explicit empty string "" means "set to empty."
+ * GitHub API returns null for labels without descriptions — treat null and
+ * undefined as equivalent when comparing (neither triggers an update).
+ *
+ * @param current - Current labels from GitHub API
+ * @param desired - Desired labels from config (name -> label)
+ * @param managedLabels - Names of labels managed by xfg (from manifest)
+ * @param noDelete - If true, skip delete operations
+ * @returns Array of changes to apply
+ * @throws Error if rename collisions are detected
+ */
+export function diffLabels(current, desired, managedLabels, noDelete) {
+    const changes = [];
+    // Build case-insensitive lookup of current labels
+    const currentByName = new Map();
+    for (const label of current) {
+        currentByName.set(label.name.toLowerCase(), label);
+    }
+    const managedSet = new Set(managedLabels.map((n) => n.toLowerCase()));
+    // Collect rename targets for collision detection
+    const renameTargets = new Map(); // lowercase target -> source name
+    for (const [name, label] of Object.entries(desired)) {
+        if (label.new_name) {
+            const targetLower = label.new_name.toLowerCase();
+            if (renameTargets.has(targetLower)) {
+                throw new Error(`Rename collision: both '${renameTargets.get(targetLower)}' and '${name}' rename to '${label.new_name}'`);
+            }
+            renameTargets.set(targetLower, name);
+        }
+    }
+    // Determine which labels will be deleted (for collision checking)
+    const desiredLower = new Set(Object.keys(desired).map((n) => n.toLowerCase()));
+    const deletedNames = new Set();
+    if (!noDelete) {
+        for (const name of managedSet) {
+            if (!desiredLower.has(name) && currentByName.has(name)) {
+                deletedNames.add(name);
+            }
+        }
+    }
+    // Check rename targets for collisions with existing labels.
+    // Note: Chain renames (A->B and B->C) are allowed when the target label is
+    // itself being renamed away. This is safe because the apply ordering
+    // (deletes -> updates -> creates) ensures both renames execute in the same batch.
+    // This deviates from the original design plan which called for flagging chains
+    // as errors, but the permissive behavior is correct and more user-friendly.
+    for (const [name, label] of Object.entries(desired)) {
+        if (!label.new_name)
+            continue;
+        const targetLower = label.new_name.toLowerCase();
+        const nameLower = name.toLowerCase();
+        // Check if target collides with an existing label that is NOT:
+        // 1. The source label itself
+        // 2. Being deleted in this diff
+        // 3. Being renamed away in this diff
+        if (currentByName.has(targetLower) &&
+            targetLower !== nameLower &&
+            !deletedNames.has(targetLower)) {
+            const collidingDesired = Object.entries(desired).find(([n]) => n.toLowerCase() === targetLower);
+            if (!collidingDesired || !collidingDesired[1].new_name) {
+                throw new Error(`Rename collision: '${name}' would rename to '${label.new_name}', but that label already exists`);
+            }
+        }
+    }
+    // Check each desired label
+    for (const [name, desiredLabel] of Object.entries(desired)) {
+        const nameLower = name.toLowerCase();
+        const currentLabel = currentByName.get(nameLower);
+        if (!currentLabel) {
+            changes.push({
+                action: "create",
+                name,
+                desired: desiredLabel,
+            });
+        }
+        else {
+            const propChanges = [];
+            const desiredColor = normalizeColor(desiredLabel.color);
+            const currentColor = currentLabel.color.toLowerCase();
+            if (desiredColor !== currentColor) {
+                propChanges.push({
+                    property: "color",
+                    oldValue: currentLabel.color,
+                    newValue: desiredColor,
+                });
+            }
+            // Description: undefined = don't compare, explicit value = compare
+            if (desiredLabel.description !== undefined) {
+                const currentDesc = currentLabel.description ?? "";
+                if (desiredLabel.description !== currentDesc) {
+                    propChanges.push({
+                        property: "description",
+                        oldValue: currentLabel.description ?? undefined,
+                        newValue: desiredLabel.description,
+                    });
+                }
+            }
+            // new_name always triggers an update
+            if (desiredLabel.new_name) {
+                propChanges.push({
+                    property: "new_name",
+                    oldValue: name,
+                    newValue: desiredLabel.new_name,
+                });
+            }
+            if (propChanges.length > 0) {
+                changes.push({
+                    action: "update",
+                    name,
+                    newName: desiredLabel.new_name,
+                    current: currentLabel,
+                    desired: desiredLabel,
+                    propertyChanges: propChanges,
+                });
+            }
+            else {
+                changes.push({
+                    action: "unchanged",
+                    name,
+                    current: currentLabel,
+                    desired: desiredLabel,
+                });
+            }
+        }
+    }
+    // Check for orphaned labels (in manifest but not in desired config)
+    if (!noDelete) {
+        for (const name of managedSet) {
+            if (!desiredLower.has(name)) {
+                const currentLabel = currentByName.get(name);
+                if (currentLabel) {
+                    changes.push({
+                        action: "delete",
+                        name: currentLabel.name,
+                        current: currentLabel,
+                    });
+                }
+            }
+        }
+    }
+    // Sort: delete first, then update, then create, then unchanged
+    const actionOrder = {
+        delete: 0,
+        update: 1,
+        create: 2,
+        unchanged: 3,
+    };
+    return changes.sort((a, b) => actionOrder[a.action] - actionOrder[b.action]);
+}

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

@@ -0,0 +1,25 @@
+import type { LabelChange, LabelAction } from "./diff.js";
+import type { Label } from "../../config/types.js";
+export interface LabelsPlanEntry {
+    name: string;
+    action: LabelAction;
+    newName?: string;
+    propertyChanges?: {
+        property: string;
+        oldValue?: string;
+        newValue?: string;
+    }[];
+    config?: Label;
+}
+export interface LabelsPlanResult {
+    lines: string[];
+    creates: number;
+    updates: number;
+    deletes: number;
+    unchanged: number;
+    entries: LabelsPlanEntry[];
+}
+/**
+ * Format label changes as a Terraform-style plan.
+ */
+export declare function formatLabelsPlan(changes: LabelChange[]): LabelsPlanResult;

package/dist/settings/labels/formatter.js

@@ -0,0 +1,92 @@
+import chalk from "chalk";
+/**
+ * Format label changes as a Terraform-style plan.
+ */
+export function formatLabelsPlan(changes) {
+    const lines = [];
+    const entries = [];
+    const createChanges = changes.filter((c) => c.action === "create");
+    const updateChanges = changes.filter((c) => c.action === "update");
+    const deleteChanges = changes.filter((c) => c.action === "delete");
+    const unchangedChanges = changes.filter((c) => c.action === "unchanged");
+    const creates = createChanges.length;
+    const updates = updateChanges.length;
+    const deletes = deleteChanges.length;
+    const unchanged = unchangedChanges.length;
+    // Format creates
+    if (createChanges.length > 0) {
+        lines.push(chalk.bold("  Create:"));
+        for (const change of createChanges) {
+            lines.push(chalk.green(`    + label "${change.name}"`));
+            if (change.desired) {
+                lines.push(chalk.green(`        color: "${change.desired.color}"`));
+                if (change.desired.description !== undefined) {
+                    lines.push(chalk.green(`        description: "${change.desired.description}"`));
+                }
+            }
+            entries.push({
+                name: change.name,
+                action: "create",
+                config: change.desired,
+            });
+            lines.push("");
+        }
+    }
+    // Format updates
+    if (updateChanges.length > 0) {
+        lines.push(chalk.bold("  Update:"));
+        for (const change of updateChanges) {
+            if (change.newName) {
+                lines.push(chalk.yellow(`    ~ label "${change.name}" \u2192 "${change.newName}"`));
+            }
+            else {
+                lines.push(chalk.yellow(`    ~ label "${change.name}"`));
+            }
+            if (change.propertyChanges) {
+                for (const prop of change.propertyChanges) {
+                    if (prop.property === "new_name")
+                        continue; // shown in header
+                    if (prop.oldValue !== undefined) {
+                        lines.push(chalk.yellow(`        ${prop.property}: "${prop.oldValue}" \u2192 "${prop.newValue}"`));
+                    }
+                    else {
+                        lines.push(chalk.yellow(`        ${prop.property}: "${prop.newValue}"`));
+                    }
+                }
+            }
+            entries.push({
+                name: change.name,
+                action: "update",
+                newName: change.newName,
+                propertyChanges: change.propertyChanges,
+            });
+            lines.push("");
+        }
+    }
+    // Format deletes
+    if (deleteChanges.length > 0) {
+        lines.push(chalk.bold("  Delete:"));
+        for (const change of deleteChanges) {
+            lines.push(chalk.red(`    - label "${change.name}"`));
+            entries.push({ name: change.name, action: "delete" });
+        }
+        lines.push("");
+    }
+    // Unchanged (entries only, no output lines)
+    for (const change of unchangedChanges) {
+        entries.push({ name: change.name, action: "unchanged" });
+    }
+    // Summary line
+    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} labels (${parts.join(", ")})`);
+    }
+    return { lines, creates, updates, deletes, unchanged, entries };
+}

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

@@ -0,0 +1,51 @@
+import { ICommandExecutor } from "../../shared/command-executor.js";
+import { RepoInfo } from "../../shared/repo-detector.js";
+import type { ILabelsStrategy, GitHubLabel, LabelsStrategyOptions } from "./types.js";
+/**
+ * GitHub Labels Strategy for managing repository labels via GitHub REST API.
+ * Uses `gh api` CLI for authentication and API calls.
+ *
+ * Note: Uses ICommandExecutor (the project's safe executor pattern) with
+ * escapeShellArg for input sanitization, matching the rulesets strategy pattern.
+ */
+export declare class GitHubLabelsStrategy implements ILabelsStrategy {
+    private executor;
+    constructor(executor?: ICommandExecutor);
+    /**
+     * Lists all labels for a repository.
+     * Uses --paginate to retrieve all labels.
+     */
+    list(repoInfo: RepoInfo, options?: LabelsStrategyOptions): Promise<GitHubLabel[]>;
+    /**
+     * Creates a new label.
+     */
+    create(repoInfo: RepoInfo, label: {
+        name: string;
+        color: string;
+        description?: string;
+    }, options?: LabelsStrategyOptions): Promise<void>;
+    /**
+     * Updates an existing label.
+     * Uses encodeURIComponent for label name in URL path.
+     */
+    update(repoInfo: RepoInfo, currentName: string, label: {
+        new_name?: string;
+        color?: string;
+        description?: string;
+    }, options?: LabelsStrategyOptions): Promise<void>;
+    /**
+     * Deletes a label.
+     * Uses encodeURIComponent for label name in URL path.
+     */
+    delete(repoInfo: RepoInfo, name: string, options?: LabelsStrategyOptions): Promise<void>;
+    /**
+     * Validates that the repo is a GitHub repository.
+     */
+    private validateGitHub;
+    /**
+     * Executes a GitHub API call using the gh CLI.
+     * Uses the project's ICommandExecutor + escapeShellArg pattern
+     * (matching github-ruleset-strategy.ts).
+     */
+    private ghApi;
+}

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

@@ -0,0 +1,102 @@
+import { defaultExecutor, } from "../../shared/command-executor.js";
+import { isGitHubRepo, } from "../../shared/repo-detector.js";
+import { escapeShellArg } from "../../shared/shell-utils.js";
+import { withRetry } from "../../shared/retry-utils.js";
+/**
+ * GitHub Labels Strategy for managing repository labels via GitHub REST API.
+ * Uses `gh api` CLI for authentication and API calls.
+ *
+ * Note: Uses ICommandExecutor (the project's safe executor pattern) with
+ * escapeShellArg for input sanitization, matching the rulesets strategy pattern.
+ */
+export class GitHubLabelsStrategy {
+    executor;
+    constructor(executor) {
+        this.executor = executor ?? defaultExecutor;
+    }
+    /**
+     * Lists all labels for a repository.
+     * Uses --paginate to retrieve all labels.
+     */
+    async list(repoInfo, options) {
+        this.validateGitHub(repoInfo);
+        const github = repoInfo;
+        const endpoint = `/repos/${github.owner}/${github.repo}/labels`;
+        const result = await this.ghApi("GET", endpoint, undefined, options, true);
+        return JSON.parse(result);
+    }
+    /**
+     * Creates a new label.
+     */
+    async create(repoInfo, label, options) {
+        this.validateGitHub(repoInfo);
+        const github = repoInfo;
+        const endpoint = `/repos/${github.owner}/${github.repo}/labels`;
+        await this.ghApi("POST", endpoint, label, options);
+    }
+    /**
+     * Updates an existing label.
+     * Uses encodeURIComponent for label name in URL path.
+     */
+    async update(repoInfo, currentName, label, options) {
+        this.validateGitHub(repoInfo);
+        const github = repoInfo;
+        const endpoint = `/repos/${github.owner}/${github.repo}/labels/${encodeURIComponent(currentName)}`;
+        await this.ghApi("PATCH", endpoint, label, options);
+    }
+    /**
+     * Deletes a label.
+     * Uses encodeURIComponent for label name in URL path.
+     */
+    async delete(repoInfo, name, options) {
+        this.validateGitHub(repoInfo);
+        const github = repoInfo;
+        const endpoint = `/repos/${github.owner}/${github.repo}/labels/${encodeURIComponent(name)}`;
+        await this.ghApi("DELETE", endpoint, undefined, options);
+    }
+    /**
+     * Validates that the repo is a GitHub repository.
+     */
+    validateGitHub(repoInfo) {
+        if (!isGitHubRepo(repoInfo)) {
+            throw new Error(`GitHub Labels strategy requires GitHub repositories. Got: ${repoInfo.type}`);
+        }
+    }
+    /**
+     * Executes a GitHub API call using the gh CLI.
+     * Uses the project's ICommandExecutor + escapeShellArg pattern
+     * (matching github-ruleset-strategy.ts).
+     */
+    async ghApi(method, endpoint, payload, options, paginate) {
+        const args = ["gh", "api"];
+        // Add method flag
+        if (method !== "GET") {
+            args.push("-X", method);
+        }
+        // Add pagination for list endpoint
+        if (paginate) {
+            args.push("--paginate");
+        }
+        // Add host flag for GitHub Enterprise
+        if (options?.host && options.host !== "github.com") {
+            args.push("--hostname", escapeShellArg(options.host));
+        }
+        // Add endpoint
+        args.push(escapeShellArg(endpoint));
+        // Build base command
+        const baseCommand = args.join(" ");
+        // Add GH_TOKEN environment variable prefix if token provided
+        const tokenPrefix = options?.token
+            ? `GH_TOKEN=${escapeShellArg(options.token)} `
+            : "";
+        // For POST/PATCH with payload, use echo pipe pattern
+        if (payload && (method === "POST" || method === "PATCH")) {
+            const payloadJson = JSON.stringify(payload);
+            const command = `echo ${escapeShellArg(payloadJson)} | ${tokenPrefix}${baseCommand} --input -`;
+            return await withRetry(() => this.executor.exec(command, process.cwd()));
+        }
+        // For GET/DELETE, run command directly
+        const command = `${tokenPrefix}${baseCommand}`;
+        return await withRetry(() => this.executor.exec(command, process.cwd()));
+    }
+}

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

@@ -0,0 +1,6 @@
+export type { ILabelsStrategy, GitHubLabel, LabelsStrategyOptions, } from "./types.js";
+export { normalizeColor, labelConfigToPayload, type GitHubLabelPayload, } from "./converter.js";
+export { diffLabels, type LabelChange, type LabelAction } from "./diff.js";
+export { formatLabelsPlan, type LabelsPlanResult, type LabelsPlanEntry, } from "./formatter.js";
+export { LabelsProcessor, type ILabelsProcessor, type LabelsProcessorOptions, type LabelsProcessorResult, } from "./processor.js";
+export { GitHubLabelsStrategy } from "./github-labels-strategy.js";

package/dist/settings/labels/index.js

@@ -0,0 +1,10 @@
+// Converter
+export { normalizeColor, labelConfigToPayload, } from "./converter.js";
+// Diff
+export { diffLabels } from "./diff.js";
+// Formatter
+export { formatLabelsPlan, } from "./formatter.js";
+// Processor
+export { LabelsProcessor, } from "./processor.js";
+// Strategy
+export { GitHubLabelsStrategy } from "./github-labels-strategy.js";

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

@@ -0,0 +1,57 @@
+import type { RepoConfig } from "../../config/index.js";
+import type { RepoInfo } from "../../shared/repo-detector.js";
+import { type LabelsPlanResult } from "./formatter.js";
+import type { ILabelsStrategy } from "./types.js";
+export interface ILabelsProcessor {
+    process(repoConfig: RepoConfig, repoInfo: RepoInfo, options: LabelsProcessorOptions): Promise<LabelsProcessorResult>;
+}
+export interface LabelsProcessorOptions {
+    configId: string;
+    dryRun?: boolean;
+    managedLabels: string[];
+    noDelete?: boolean;
+    token?: string;
+}
+export interface LabelsProcessorResult {
+    success: boolean;
+    repoName: string;
+    message: string;
+    skipped?: boolean;
+    dryRun?: boolean;
+    changes?: {
+        create: number;
+        update: number;
+        delete: number;
+        unchanged: number;
+    };
+    manifestUpdate?: {
+        labels: string[];
+    };
+    planOutput?: LabelsPlanResult;
+}
+/**
+ * Processes label configuration for a repository.
+ * Handles create/update/delete operations via GitHub Labels API.
+ */
+export declare class LabelsProcessor implements ILabelsProcessor {
+    private readonly strategy;
+    private readonly tokenManager;
+    constructor(strategy?: ILabelsStrategy);
+    /**
+     * Process labels for a single repository.
+     */
+    process(repoConfig: RepoConfig, repoInfo: RepoInfo, options: LabelsProcessorOptions): Promise<LabelsProcessorResult>;
+    /**
+     * Format change counts into a summary string.
+     */
+    private formatChangeSummary;
+    /**
+     * Compute manifest update based on current config.
+     * Only labels with deleteOrphaned enabled should be tracked.
+     */
+    private computeManifestUpdate;
+    /**
+     * Resolves a GitHub App installation token for the given repo.
+     */
+    private getInstallationToken;
+}