@aspruyt/xfg 3.8.2 → 3.9.1

package/dist/lifecycle/repo-lifecycle-manager.js

@@ -0,0 +1,139 @@
+import { join } from "node:path";
+import { rm } from "node:fs/promises";
+import { parseGitUrl } from "../shared/repo-detector.js";
+import { logger } from "../shared/logger.js";
+import { RepoLifecycleFactory } from "./repo-lifecycle-factory.js";
+/**
+ * Orchestrates repo lifecycle operations before sync.
+ */
+export class RepoLifecycleManager {
+    factory;
+    constructor(factory, retries) {
+        this.factory = factory ?? new RepoLifecycleFactory(undefined, retries);
+    }
+    async ensureRepo(repoConfig, repoInfo, options, settings) {
+        let provider;
+        try {
+            provider = this.factory.getProvider(repoInfo.type);
+        }
+        catch (error) {
+            // If user explicitly configured lifecycle (upstream/source), propagate the error
+            if (repoConfig.upstream || repoConfig.source) {
+                throw error;
+            }
+            // Platform doesn't support lifecycle operations yet - skip silently
+            return { repoInfo, action: "existed" };
+        }
+        const { token } = options;
+        // Check if repo exists
+        const exists = await provider.exists(repoInfo, token);
+        if (exists) {
+            // Repo exists - nothing to do (ignore upstream/source)
+            return {
+                repoInfo,
+                action: "existed",
+            };
+        }
+        // Repo doesn't exist - determine what action to take
+        if (repoConfig.source) {
+            // Migration mode
+            return this.migrate(repoConfig, repoInfo, options, settings);
+        }
+        if (repoConfig.upstream) {
+            // Fork mode
+            return this.fork(repoConfig, repoInfo, provider, options, settings);
+        }
+        // Create mode (no upstream or source)
+        return this.create(repoInfo, provider, options, settings);
+    }
+    async create(repoInfo, provider, options, settings) {
+        if (options.dryRun) {
+            return {
+                repoInfo,
+                action: "created",
+                skipped: true,
+            };
+        }
+        await provider.create(repoInfo, settings, options.token);
+        await this.waitForRepoReady(provider, repoInfo, options.token);
+        return {
+            repoInfo,
+            action: "created",
+        };
+    }
+    async fork(repoConfig, repoInfo, provider, options, settings) {
+        if (options.dryRun) {
+            return {
+                repoInfo,
+                action: "forked",
+                skipped: true,
+            };
+        }
+        if (!provider.fork) {
+            throw new Error(`Platform '${repoInfo.type}' does not support forking`);
+        }
+        // Parse upstream URL to get repo info
+        const upstreamInfo = parseGitUrl(repoConfig.upstream, {
+            githubHosts: options.githubHosts,
+        });
+        await provider.fork(upstreamInfo, repoInfo, settings, options.token);
+        await this.waitForRepoReady(provider, repoInfo, options.token);
+        return {
+            repoInfo,
+            action: "forked",
+        };
+    }
+    async migrate(repoConfig, repoInfo, options, settings) {
+        if (options.dryRun) {
+            return {
+                repoInfo,
+                action: "migrated",
+                skipped: true,
+            };
+        }
+        // Parse source URL to get platform and repo info
+        const sourceInfo = parseGitUrl(repoConfig.source, {
+            githubHosts: options.githubHosts,
+        });
+        const source = this.factory.getMigrationSource(sourceInfo.type);
+        // Clone source repo to temp directory
+        const sourceDir = join(options.workDir, "migration-source");
+        try {
+            await source.cloneForMigration(sourceInfo, sourceDir);
+            // Create target and push content
+            const provider = this.factory.getProvider(repoInfo.type);
+            await provider.receiveMigration(repoInfo, sourceDir, settings, options.token);
+            await this.waitForRepoReady(provider, repoInfo, options.token);
+            return {
+                repoInfo,
+                action: "migrated",
+            };
+        }
+        finally {
+            // Clean up migration source directory
+            try {
+                await rm(sourceDir, { recursive: true, force: true });
+            }
+            catch (cleanupError) {
+                // Log cleanup errors at debug level for troubleshooting
+                logger.debug(`Failed to clean up migration source directory ${sourceDir}: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+            }
+        }
+    }
+    /**
+     * Polls provider.exists() until the repo is visible, with timeout.
+     * GitHub's API may return success from create/fork before the git
+     * backend has fully propagated, causing subsequent clone to 403.
+     */
+    async waitForRepoReady(provider, repoInfo, token, timeoutMs = 15000, pollMs = 1000) {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            if (await provider.exists(repoInfo, token)) {
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+        // Timed out — proceed anyway and let downstream operations handle it
+        logger.info(`Repo ${repoInfo.owner}/${repoInfo.repo} not yet visible after ${timeoutMs}ms, proceeding`);
+    }
+}

package/dist/lifecycle/types.d.ts

@@ -0,0 +1,104 @@
+import type { RepoInfo } from "../shared/repo-detector.js";
+import type { RepoConfig } from "../config/types.js";
+/**
+ * Supported platforms for lifecycle operations.
+ */
+export type LifecyclePlatform = "github" | "azure-devops" | "gitlab";
+/**
+ * Result of a lifecycle operation.
+ */
+export interface LifecycleResult {
+    /** The repo info (may be updated) */
+    repoInfo: RepoInfo;
+    /** What action was taken */
+    action: "existed" | "created" | "forked" | "migrated";
+    /** True if skipped due to dry-run */
+    skipped?: boolean;
+}
+/**
+ * Options for lifecycle operations.
+ */
+export interface LifecycleOptions {
+    /** Dry-run mode - don't make changes */
+    dryRun: boolean;
+    /** Working directory for git operations */
+    workDir: string;
+    /** GitHub Enterprise hostnames for URL detection */
+    githubHosts?: string[];
+    /** Auth token (GitHub App installation token or PAT) for gh CLI commands */
+    token?: string;
+}
+/**
+ * Repo settings to apply when creating a new repo.
+ * Subset of GitHubRepoSettings that makes sense for creation.
+ */
+export interface CreateRepoSettings {
+    visibility?: "public" | "private" | "internal";
+    description?: string;
+    hasIssues?: boolean;
+    hasWiki?: boolean;
+}
+/**
+ * Provider for platform-specific lifecycle operations.
+ * Implementations handle create/fork/receive for a specific platform.
+ */
+export interface IRepoLifecycleProvider {
+    /** Platform this provider handles */
+    readonly platform: LifecyclePlatform;
+    /**
+     * Check if a repository exists on this platform.
+     * @throws Error on network/auth failures (NOT for "repo not found")
+     */
+    exists(repoInfo: RepoInfo, token?: string): Promise<boolean>;
+    /**
+     * Create an empty repository.
+     */
+    create(repoInfo: RepoInfo, settings?: CreateRepoSettings, token?: string): Promise<void>;
+    /**
+     * Fork from an upstream repository.
+     * Optional - not all platforms support forking.
+     */
+    fork?(upstream: RepoInfo, target: RepoInfo, settings?: CreateRepoSettings, token?: string): Promise<void>;
+    /**
+     * Receive migrated content (repo already created, push content).
+     */
+    receiveMigration(repoInfo: RepoInfo, sourceDir: string, settings?: CreateRepoSettings, token?: string): Promise<void>;
+}
+/**
+ * Source for migration operations.
+ * Implementations handle cloning from a source platform.
+ */
+export interface IMigrationSource {
+    /** Platform this source handles */
+    readonly platform: LifecyclePlatform;
+    /**
+     * Clone repository with all refs for migration.
+     * Uses --mirror to get all branches/tags.
+     */
+    cloneForMigration(repoInfo: RepoInfo, workDir: string): Promise<void>;
+}
+/**
+ * Factory for getting providers by platform.
+ */
+export interface IRepoLifecycleFactory {
+    /**
+     * Get lifecycle provider for a platform.
+     * @throws Error if platform not supported as target
+     */
+    getProvider(platform: LifecyclePlatform): IRepoLifecycleProvider;
+    /**
+     * Get migration source for a platform.
+     * @throws Error if platform not supported as source
+     */
+    getMigrationSource(platform: LifecyclePlatform): IMigrationSource;
+}
+/**
+ * Manager that orchestrates lifecycle operations before sync.
+ */
+export interface IRepoLifecycleManager {
+    /**
+     * Ensure repository exists, creating/forking/migrating if needed.
+     * Call this before sync/settings operations.
+     */
+    ensureRepo(repoConfig: RepoConfig, repoInfo: RepoInfo, options: LifecycleOptions, settings?: CreateRepoSettings): Promise<LifecycleResult>;
+}

package/dist/lifecycle/types.js

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

package/dist/output/lifecycle-report.d.ts

@@ -0,0 +1,37 @@
+export interface LifecycleReport {
+    actions: LifecycleAction[];
+    totals: {
+        created: number;
+        forked: number;
+        migrated: number;
+        existed: number;
+    };
+}
+export interface LifecycleAction {
+    repoName: string;
+    action: "existed" | "created" | "forked" | "migrated";
+    upstream?: string;
+    source?: string;
+    settings?: {
+        visibility?: string;
+        description?: string;
+    };
+}
+export interface LifecycleReportInput {
+    repoName: string;
+    action: "existed" | "created" | "forked" | "migrated";
+    upstream?: string;
+    source?: string;
+    settings?: {
+        visibility?: string;
+        description?: string;
+    };
+}
+export declare function buildLifecycleReport(results: LifecycleReportInput[]): LifecycleReport;
+/**
+ * Returns true if the report has any non-"existed" actions worth displaying.
+ */
+export declare function hasLifecycleChanges(report: LifecycleReport): boolean;
+export declare function formatLifecycleReportCLI(report: LifecycleReport): string[];
+export declare function formatLifecycleReportMarkdown(report: LifecycleReport, dryRun: boolean): string;
+export declare function writeLifecycleReportSummary(report: LifecycleReport, dryRun: boolean): void;

package/dist/output/lifecycle-report.js

@@ -0,0 +1,146 @@
+// src/output/lifecycle-report.ts
+import { appendFileSync } from "node:fs";
+import chalk from "chalk";
+// =============================================================================
+// Builder
+// =============================================================================
+export function buildLifecycleReport(results) {
+    const actions = [];
+    const totals = { created: 0, forked: 0, migrated: 0, existed: 0 };
+    for (const result of results) {
+        actions.push({
+            repoName: result.repoName,
+            action: result.action,
+            upstream: result.upstream,
+            source: result.source,
+            settings: result.settings,
+        });
+        totals[result.action]++;
+    }
+    return { actions, totals };
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function formatSummary(totals) {
+    const total = totals.created + totals.forked + totals.migrated;
+    if (total === 0) {
+        return "No changes";
+    }
+    const parts = [];
+    if (totals.created > 0)
+        parts.push(`${totals.created} to create`);
+    if (totals.forked > 0)
+        parts.push(`${totals.forked} to fork`);
+    if (totals.migrated > 0)
+        parts.push(`${totals.migrated} to migrate`);
+    const repoWord = total === 1 ? "repo" : "repos";
+    return `Plan: ${total} ${repoWord} (${parts.join(", ")})`;
+}
+/**
+ * Returns true if the report has any non-"existed" actions worth displaying.
+ */
+export function hasLifecycleChanges(report) {
+    return report.actions.some((a) => a.action !== "existed");
+}
+// =============================================================================
+// CLI Formatter
+// =============================================================================
+export function formatLifecycleReportCLI(report) {
+    if (!hasLifecycleChanges(report)) {
+        return [];
+    }
+    const lines = [];
+    for (const action of report.actions) {
+        if (action.action === "existed")
+            continue;
+        switch (action.action) {
+            case "created":
+                lines.push(chalk.green(`+ CREATE ${action.repoName}`));
+                break;
+            case "forked":
+                lines.push(chalk.green(`+ FORK ${action.upstream ?? "upstream"} -> ${action.repoName}`));
+                break;
+            case "migrated":
+                lines.push(chalk.green(`+ MIGRATE ${action.source ?? "source"} -> ${action.repoName}`));
+                break;
+        }
+        if (action.settings) {
+            if (action.settings.visibility) {
+                lines.push(`    visibility: ${action.settings.visibility}`);
+            }
+            if (action.settings.description) {
+                lines.push(`    description: "${action.settings.description}"`);
+            }
+        }
+    }
+    lines.push("");
+    // Summary
+    lines.push(formatSummary(report.totals));
+    return lines;
+}
+// =============================================================================
+// Markdown Formatter
+// =============================================================================
+export function formatLifecycleReportMarkdown(report, dryRun) {
+    if (!hasLifecycleChanges(report)) {
+        return "";
+    }
+    const lines = [];
+    // Title
+    const titleSuffix = dryRun ? " (Dry Run)" : "";
+    lines.push(`## Lifecycle Summary${titleSuffix}`);
+    lines.push("");
+    // Dry-run warning
+    if (dryRun) {
+        lines.push("> [!WARNING]");
+        lines.push("> This was a dry run — no changes were applied");
+        lines.push("");
+    }
+    // Diff block
+    const diffLines = [];
+    for (const action of report.actions) {
+        if (action.action === "existed")
+            continue;
+        switch (action.action) {
+            case "created":
+                diffLines.push(`+ CREATE ${action.repoName}`);
+                break;
+            case "forked":
+                diffLines.push(`+ FORK ${action.upstream ?? "upstream"} -> ${action.repoName}`);
+                break;
+            case "migrated":
+                diffLines.push(`+ MIGRATE ${action.source ?? "source"} -> ${action.repoName}`);
+                break;
+        }
+        if (action.settings) {
+            if (action.settings.visibility) {
+                diffLines.push(`    visibility: ${action.settings.visibility}`);
+            }
+            if (action.settings.description) {
+                diffLines.push(`    description: "${action.settings.description}"`);
+            }
+        }
+    }
+    if (diffLines.length > 0) {
+        lines.push("```diff");
+        lines.push(...diffLines);
+        lines.push("```");
+        lines.push("");
+    }
+    // Summary
+    lines.push(`**${formatSummary(report.totals)}**`);
+    return lines.join("\n");
+}
+// =============================================================================
+// File Writer
+// =============================================================================
+export function writeLifecycleReportSummary(report, dryRun) {
+    const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+    if (!summaryPath)
+        return;
+    const markdown = formatLifecycleReportMarkdown(report, dryRun);
+    if (!markdown)
+        return;
+    appendFileSync(summaryPath, "\n" + markdown + "\n");
+}

package/dist/output/settings-report.js

@@ -164,52 +164,52 @@ function formatValuePlain(val) {
         return val ? "true" : "false";
     return String(val);
 }
-function formatRulesetConfigPlain(config, indent) {
+function formatRulesetConfigPlain(config) {
     const lines = [];
-    function renderObject(obj, currentIndent) {
+    function renderObject(obj, depth) {
         for (const [k, v] of Object.entries(obj)) {
-            renderValue(k, v, currentIndent);
+            renderValue(k, v, depth);
         }
     }
-    function renderValue(key, value, currentIndent) {
-        const pad = "    ".repeat(currentIndent);
+    function renderValue(key, value, depth) {
+        const indent = "  ".repeat(depth);
         if (value === null || value === undefined)
             return;
         if (Array.isArray(value)) {
             if (value.length === 0) {
-                lines.push(`${pad}+ ${key}: []`);
+                lines.push(`+${indent} ${key}: []`);
             }
             else if (value.every((v) => typeof v !== "object")) {
-                lines.push(`${pad}+ ${key}: [${value.map((v) => (typeof v === "string" ? `"${v}"` : String(v))).join(", ")}]`);
+                lines.push(`+${indent} ${key}: [${value.map((v) => (typeof v === "string" ? `"${v}"` : String(v))).join(", ")}]`);
             }
             else {
-                lines.push(`${pad}+ ${key}:`);
+                lines.push(`+${indent} ${key}:`);
                 for (let i = 0; i < value.length; i++) {
                     const item = value[i];
                     if (typeof item === "object" && item !== null) {
                         const obj = item;
                         const typeLabel = "type" in obj ? ` (${obj.type})` : "";
-                        lines.push(`${pad}    + [${i}]${typeLabel}:`);
-                        renderObject(obj, currentIndent + 2);
+                        lines.push(`+${indent}   [${i}]${typeLabel}:`);
+                        renderObject(obj, depth + 2);
                     }
                     else {
-                        lines.push(`${pad}    + ${formatValuePlain(item)}`);
+                        lines.push(`+${indent}   ${formatValuePlain(item)}`);
                     }
                 }
             }
         }
         else if (typeof value === "object") {
-            lines.push(`${pad}+ ${key}:`);
-            renderObject(value, currentIndent + 1);
+            lines.push(`+${indent} ${key}:`);
+            renderObject(value, depth + 1);
         }
         else {
-            lines.push(`${pad}+ ${key}: ${formatValuePlain(value)}`);
+            lines.push(`+${indent} ${key}: ${formatValuePlain(value)}`);
         }
     }
     for (const [key, value] of Object.entries(config)) {
         if (key === "name")
             continue;
-        renderValue(key, value, indent);
+        renderValue(key, value, 1);
     }
     return lines;
 }
@@ -233,49 +233,49 @@ export function formatSettingsReportMarkdown(report, dryRun) {
             !repo.error) {
             continue;
         }
-        diffLines.push(`~ ${repo.repoName}`);
+        diffLines.push(`@@ ${repo.repoName} @@`);
         for (const setting of repo.settings) {
             // Skip settings where both values are undefined
             if (setting.oldValue === undefined && setting.newValue === undefined) {
                 continue;
             }
             if (setting.action === "add") {
-                diffLines.push(`    + ${setting.name}: ${formatValuePlain(setting.newValue)}`);
+                diffLines.push(`+ ${setting.name}: ${formatValuePlain(setting.newValue)}`);
             }
             else {
-                diffLines.push(`    ~ ${setting.name}: ${formatValuePlain(setting.oldValue)} → ${formatValuePlain(setting.newValue)}`);
+                diffLines.push(`! ${setting.name}: ${formatValuePlain(setting.oldValue)} → ${formatValuePlain(setting.newValue)}`);
             }
         }
         for (const ruleset of repo.rulesets) {
             if (ruleset.action === "create") {
-                diffLines.push(`    + ruleset "${ruleset.name}"`);
+                diffLines.push(`+ ruleset "${ruleset.name}"`);
                 if (ruleset.config) {
-                    diffLines.push(...formatRulesetConfigPlain(ruleset.config, 2));
+                    diffLines.push(...formatRulesetConfigPlain(ruleset.config));
                 }
             }
             else if (ruleset.action === "update") {
-                diffLines.push(`    ~ ruleset "${ruleset.name}"`);
+                diffLines.push(`! ruleset "${ruleset.name}"`);
                 if (ruleset.propertyDiffs && ruleset.propertyDiffs.length > 0) {
                     for (const diff of ruleset.propertyDiffs) {
                         const path = diff.path.join(".");
                         if (diff.action === "add") {
-                            diffLines.push(`        + ${path}: ${formatValuePlain(diff.newValue)}`);
+                            diffLines.push(`+   ${path}: ${formatValuePlain(diff.newValue)}`);
                         }
                         else if (diff.action === "change") {
-                            diffLines.push(`        ~ ${path}: ${formatValuePlain(diff.oldValue)} → ${formatValuePlain(diff.newValue)}`);
+                            diffLines.push(`!   ${path}: ${formatValuePlain(diff.oldValue)} → ${formatValuePlain(diff.newValue)}`);
                         }
                         else if (diff.action === "remove") {
-                            diffLines.push(`        - ${path}`);
+                            diffLines.push(`-   ${path}`);
                         }
                     }
                 }
             }
             else if (ruleset.action === "delete") {
-                diffLines.push(`    - ruleset "${ruleset.name}"`);
+                diffLines.push(`- ruleset "${ruleset.name}"`);
             }
         }
         if (repo.error) {
-            diffLines.push(`    ! Error: ${repo.error}`);
+            diffLines.push(`- Error: ${repo.error}`);
         }
     }
     if (diffLines.length > 0) {

package/dist/output/sync-report.js

@@ -64,20 +64,20 @@ export function formatSyncReportMarkdown(report, dryRun) {
         if (repo.files.length === 0 && !repo.error) {
             continue;
         }
-        diffLines.push(`~ ${repo.repoName}`);
+        diffLines.push(`@@ ${repo.repoName} @@`);
         for (const file of repo.files) {
             if (file.action === "create") {
-                diffLines.push(`    + ${file.path}`);
+                diffLines.push(`+ ${file.path}`);
             }
             else if (file.action === "update") {
-                diffLines.push(`    ~ ${file.path}`);
+                diffLines.push(`! ${file.path}`);
             }
             else if (file.action === "delete") {
-                diffLines.push(`    - ${file.path}`);
+                diffLines.push(`- ${file.path}`);
             }
         }
         if (repo.error) {
-            diffLines.push(`    ! Error: ${repo.error}`);
+            diffLines.push(`- Error: ${repo.error}`);
         }
     }
     if (diffLines.length > 0) {

package/dist/output/unified-summary.d.ts

@@ -0,0 +1,4 @@
+import type { LifecycleReport } from "./lifecycle-report.js";
+import type { SyncReport } from "./sync-report.js";
+export declare function formatUnifiedSummaryMarkdown(lifecycle: LifecycleReport, sync: SyncReport, dryRun: boolean): string;
+export declare function writeUnifiedSummary(lifecycle: LifecycleReport, sync: SyncReport, dryRun: boolean): void;