@aspruyt/xfg 3.8.2 → 3.9.0

package/dist/lifecycle/github-lifecycle-provider.js

@@ -0,0 +1,314 @@
+import { escapeShellArg } from "../shared/shell-utils.js";
+import { defaultExecutor, } from "../shared/command-executor.js";
+import { withRetry } from "../shared/retry-utils.js";
+import { isGitHubRepo, } from "../shared/repo-detector.js";
+import { logger } from "../shared/logger.js";
+/**
+ * Error messages that indicate "repo not found" vs actual errors.
+ */
+const REPO_NOT_FOUND_PATTERNS = [
+    "Could not resolve to a Repository",
+    "Not Found",
+    "404",
+];
+/**
+ * Check if an error indicates repo not found (vs network/auth error).
+ */
+function isRepoNotFoundError(error) {
+    const message = error instanceof Error
+        ? error.message + (error.stderr ?? "")
+        : String(error);
+    return REPO_NOT_FOUND_PATTERNS.some((pattern) => message.includes(pattern));
+}
+/**
+ * Get the hostname flag for gh commands.
+ * Returns "--hostname HOST" for GHE, empty string for github.com.
+ */
+function getHostnameFlag(repoInfo) {
+    if (repoInfo.host && repoInfo.host !== "github.com") {
+        return `--hostname ${escapeShellArg(repoInfo.host)}`;
+    }
+    return "";
+}
+/**
+ * Default timeout for waiting for fork readiness (60 seconds).
+ */
+const FORK_READY_TIMEOUT_MS = 60_000;
+/**
+ * Interval between fork readiness checks (2 seconds).
+ */
+const FORK_POLL_INTERVAL_MS = 2_000;
+export class GitHubLifecycleProvider {
+    platform = "github";
+    executor;
+    retries;
+    cwd;
+    forkReadyTimeoutMs;
+    forkPollIntervalMs;
+    constructor(options) {
+        const opts = options ?? {};
+        this.executor = opts.executor ?? defaultExecutor;
+        this.retries = opts.retries ?? 3;
+        this.cwd = opts.cwd ?? process.cwd();
+        this.forkReadyTimeoutMs = opts.forkReadyTimeoutMs ?? FORK_READY_TIMEOUT_MS;
+        this.forkPollIntervalMs = opts.forkPollIntervalMs ?? FORK_POLL_INTERVAL_MS;
+    }
+    /**
+     * Check if a GitHub owner is an organization (vs user).
+     * Uses gh api to query the user/org endpoint.
+     */
+    async isOrganization(owner, repoInfo, token) {
+        const tokenPrefix = this.buildTokenPrefix(token);
+        const hostnameFlag = getHostnameFlag(repoInfo);
+        const hostnamePart = hostnameFlag ? `${hostnameFlag} ` : "";
+        const command = `${tokenPrefix}gh api ${hostnamePart}users/${escapeShellArg(owner)}`;
+        try {
+            const stdout = await withRetry(() => this.executor.exec(command, this.cwd), { retries: this.retries });
+            const data = JSON.parse(stdout);
+            return data.type === "Organization";
+        }
+        catch (error) {
+            // If we can't determine, assume it's an org (safer - uses --org flag).
+            // This may cause fork to fail with a misleading error for personal accounts.
+            const errMsg = error instanceof Error ? error.message : String(error);
+            logger.debug(`Could not determine if '${owner}' is an organization, defaulting to org behavior: ${errMsg}`);
+            logger.info(`Warning: Could not verify if '${owner}' is an organization or user account. ` +
+                `If fork fails, check your authentication (gh auth status) and ensure the ` +
+                `target owner is correct.`);
+            return true;
+        }
+    }
+    assertGitHub(repoInfo) {
+        if (!isGitHubRepo(repoInfo)) {
+            throw new Error(`GitHubLifecycleProvider requires GitHub repo, got: ${repoInfo.type}`);
+        }
+    }
+    /**
+     * Build GH_TOKEN prefix for gh CLI commands.
+     * Returns "GH_TOKEN=<escaped_token> " when token is provided, "" otherwise.
+     * Token is escaped via escapeShellArg to prevent injection.
+     */
+    buildTokenPrefix(token) {
+        return token ? `GH_TOKEN=${escapeShellArg(token)} ` : "";
+    }
+    async exists(repoInfo, token) {
+        this.assertGitHub(repoInfo);
+        const tokenPrefix = this.buildTokenPrefix(token);
+        const hostnameFlag = getHostnameFlag(repoInfo);
+        const hostnamePart = hostnameFlag ? `${hostnameFlag} ` : "";
+        const command = `${tokenPrefix}gh api ${hostnamePart}repos/${escapeShellArg(repoInfo.owner)}/${escapeShellArg(repoInfo.repo)}`;
+        try {
+            // Note: withRetry already classifies 404/not-found as permanent errors,
+            // so retries are aborted immediately for non-existent repos.
+            await withRetry(() => this.executor.exec(command, this.cwd), {
+                retries: this.retries,
+            });
+            return true;
+        }
+        catch (error) {
+            // Distinguish "repo not found" from actual errors
+            if (isRepoNotFoundError(error)) {
+                return false;
+            }
+            // Re-throw network/auth errors
+            throw error;
+        }
+    }
+    async create(repoInfo, settings, token) {
+        this.assertGitHub(repoInfo);
+        const tokenPrefix = this.buildTokenPrefix(token);
+        const parts = [
+            `${tokenPrefix}gh repo create`,
+            escapeShellArg(`${repoInfo.owner}/${repoInfo.repo}`),
+        ];
+        // Visibility flag (default to private for safety)
+        if (settings?.visibility === "public") {
+            parts.push("--public");
+        }
+        else if (settings?.visibility === "internal") {
+            parts.push("--internal");
+        }
+        else {
+            parts.push("--private");
+        }
+        // Description
+        if (settings?.description) {
+            parts.push("--description", escapeShellArg(settings.description));
+        }
+        // Disable features if specified
+        if (settings?.hasIssues === false) {
+            parts.push("--disable-issues");
+        }
+        if (settings?.hasWiki === false) {
+            parts.push("--disable-wiki");
+        }
+        // Add --add-readme to establish the default branch via an initial commit.
+        // This avoids empty repos where HEAD doesn't resolve.
+        parts.push("--add-readme");
+        const command = parts.join(" ");
+        await withRetry(() => this.executor.exec(command, this.cwd), {
+            retries: this.retries,
+        });
+        // Delete the README so xfg sync starts from a clean state.
+        await this.deleteReadme(repoInfo, token);
+    }
+    async fork(upstream, target, settings, token) {
+        this.assertGitHub(upstream);
+        this.assertGitHub(target);
+        // Guard: cannot fork a repo to the same owner
+        if (upstream.owner.toLowerCase() === target.owner.toLowerCase()) {
+            throw new Error(`Cannot fork ${upstream.owner}/${upstream.repo} to the same owner '${target.owner}'. ` +
+                `The upstream and target owners must be different.`);
+        }
+        // Determine if target owner is an organization or user
+        const isOrg = await this.isOrganization(target.owner, target, token);
+        const tokenPrefix = this.buildTokenPrefix(token);
+        // Build fork command
+        // For orgs: gh repo fork <upstream> --org <target-org> --fork-name <name> --clone=false
+        // For users: gh repo fork <upstream> --fork-name <name> --clone=false
+        const parts = [
+            `${tokenPrefix}gh repo fork`,
+            escapeShellArg(`${upstream.owner}/${upstream.repo}`),
+        ];
+        if (isOrg) {
+            parts.push("--org", escapeShellArg(target.owner));
+        }
+        parts.push("--fork-name", escapeShellArg(target.repo), "--clone=false");
+        const forkCommand = parts.join(" ");
+        await withRetry(() => this.executor.exec(forkCommand, this.cwd), {
+            retries: this.retries,
+        });
+        // GitHub forks are async - wait for the fork to be ready for git operations
+        await this.waitForForkReady(target, this.forkReadyTimeoutMs, this.forkPollIntervalMs, token);
+        // Apply settings after fork (visibility, description, etc.)
+        if (settings?.visibility || settings?.description) {
+            await this.applyRepoSettings(target, settings, token);
+        }
+    }
+    /**
+     * Wait for a forked repo to become available via the GitHub API.
+     * GitHub forks are created asynchronously; polls exists() with a timeout.
+     */
+    async waitForForkReady(repoInfo, timeoutMs = FORK_READY_TIMEOUT_MS, intervalMs = FORK_POLL_INTERVAL_MS, token) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            try {
+                const ready = await this.exists(repoInfo, token);
+                if (ready) {
+                    return;
+                }
+            }
+            catch {
+                // Ignore transient errors during polling
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                break;
+            await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, remaining)));
+        }
+        throw new Error(`Timed out waiting for fork ${repoInfo.owner}/${repoInfo.repo} to become available ` +
+            `after ${timeoutMs / 1000}s. The fork may still be processing on GitHub.`);
+    }
+    /**
+     * Apply settings to an existing repo using gh repo edit.
+     */
+    async applyRepoSettings(repoInfo, settings, token) {
+        const tokenPrefix = this.buildTokenPrefix(token);
+        const parts = [
+            `${tokenPrefix}gh repo edit`,
+            escapeShellArg(`${repoInfo.owner}/${repoInfo.repo}`),
+        ];
+        if (settings.visibility) {
+            parts.push("--visibility", settings.visibility, "--accept-visibility-change-consequences");
+        }
+        if (settings.description) {
+            parts.push("--description", escapeShellArg(settings.description));
+        }
+        const command = parts.join(" ");
+        await withRetry(() => this.executor.exec(command, this.cwd), {
+            retries: this.retries,
+        });
+    }
+    async receiveMigration(repoInfo, sourceDir, settings, token) {
+        this.assertGitHub(repoInfo);
+        const tokenPrefix = this.buildTokenPrefix(token);
+        // Remove existing "origin" remote if present (e.g., from git clone --mirror).
+        // gh repo create --source --push needs to set its own origin remote.
+        try {
+            await this.executor.exec(`git -C ${escapeShellArg(sourceDir)} remote remove origin`, this.cwd);
+        }
+        catch {
+            // No origin remote — nothing to remove
+        }
+        // Remove all non-standard refs that GitHub rejects on push.
+        // Mirror clones include ALL refs from the source, but GitHub only
+        // accepts branches (refs/heads/*) and tags (refs/tags/*).
+        // Other refs like refs/pull/* (GitHub), refs/merge-requests/* (GitLab),
+        // refs/keep-around/* etc. must be removed.
+        try {
+            const allRefs = await this.executor.exec(`git -C ${escapeShellArg(sourceDir)} for-each-ref --format='%(refname)'`, this.cwd);
+            for (const ref of allRefs.split("\n").filter((r) => r.trim())) {
+                const trimmed = ref.trim();
+                if (!trimmed.startsWith("refs/heads/") &&
+                    !trimmed.startsWith("refs/tags/")) {
+                    await this.executor.exec(`git -C ${escapeShellArg(sourceDir)} update-ref -d ${escapeShellArg(trimmed)}`, this.cwd);
+                }
+            }
+        }
+        catch {
+            // No refs to remove — ignore
+        }
+        // Use gh repo create --source --push to create and mirror in one step.
+        // For bare repos (from git clone --mirror), --push mirrors all refs.
+        // This uses gh CLI authentication, avoiding raw git auth issues with GHE.
+        const parts = [
+            `${tokenPrefix}gh repo create`,
+            escapeShellArg(`${repoInfo.owner}/${repoInfo.repo}`),
+            "--source",
+            escapeShellArg(sourceDir),
+            "--push",
+        ];
+        // Visibility flag (default to private for safety)
+        if (settings?.visibility === "public") {
+            parts.push("--public");
+        }
+        else if (settings?.visibility === "internal") {
+            parts.push("--internal");
+        }
+        else {
+            parts.push("--private");
+        }
+        // Description
+        if (settings?.description) {
+            parts.push("--description", escapeShellArg(settings.description));
+        }
+        // Disable features if specified
+        if (settings?.hasIssues === false) {
+            parts.push("--disable-issues");
+        }
+        if (settings?.hasWiki === false) {
+            parts.push("--disable-wiki");
+        }
+        const command = parts.join(" ");
+        await withRetry(() => this.executor.exec(command, this.cwd), {
+            retries: this.retries,
+        });
+    }
+    /**
+     * Delete the README.md that --add-readme creates.
+     * This leaves the repo with a default branch established (from the initial
+     * commit) but no files, so xfg sync starts from a clean state.
+     */
+    async deleteReadme(repoInfo, token) {
+        const tokenPrefix = this.buildTokenPrefix(token);
+        const hostnameFlag = getHostnameFlag(repoInfo);
+        const hostnamePart = hostnameFlag ? `${hostnameFlag} ` : "";
+        const apiPath = `repos/${escapeShellArg(repoInfo.owner)}/${escapeShellArg(repoInfo.repo)}`;
+        // Get the SHA of the README.md created by --add-readme
+        const fileInfo = await withRetry(() => this.executor.exec(`${tokenPrefix}gh api ${hostnamePart}${apiPath}/contents/README.md --jq '.sha'`, this.cwd), { retries: this.retries });
+        const sha = fileInfo.trim();
+        // Delete the README.md to leave the repo clean
+        await withRetry(() => this.executor.exec(`${tokenPrefix}gh api ${hostnamePart}${apiPath}/contents/README.md ` +
+            `--method DELETE -f message='Remove initialization file' -f sha=${escapeShellArg(sha)}`, this.cwd), { retries: this.retries });
+    }
+}

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,7 @@
+export type { LifecyclePlatform, LifecycleResult, LifecycleOptions, CreateRepoSettings, IRepoLifecycleProvider, IMigrationSource, IRepoLifecycleFactory, IRepoLifecycleManager, } from "./types.js";
+export { GitHubLifecycleProvider, type GitHubLifecycleProviderOptions, } from "./github-lifecycle-provider.js";
+export { AdoMigrationSource } from "./ado-migration-source.js";
+export { RepoLifecycleFactory } from "./repo-lifecycle-factory.js";
+export { RepoLifecycleManager } from "./repo-lifecycle-manager.js";
+export { formatLifecycleAction, type FormatOptions, } from "./lifecycle-formatter.js";
+export { runLifecycleCheck, toCreateRepoSettings, type LifecycleCheckOptions, type LifecycleCheckResult, } from "./lifecycle-helpers.js";

package/dist/lifecycle/index.js

@@ -0,0 +1,6 @@
+export { GitHubLifecycleProvider, } from "./github-lifecycle-provider.js";
+export { AdoMigrationSource } from "./ado-migration-source.js";
+export { RepoLifecycleFactory } from "./repo-lifecycle-factory.js";
+export { RepoLifecycleManager } from "./repo-lifecycle-manager.js";
+export { formatLifecycleAction, } from "./lifecycle-formatter.js";
+export { runLifecycleCheck, toCreateRepoSettings, } from "./lifecycle-helpers.js";

package/dist/lifecycle/lifecycle-formatter.d.ts

@@ -0,0 +1,14 @@
+import type { LifecycleResult } from "./types.js";
+export interface FormatOptions {
+    upstream?: string;
+    source?: string;
+    settings?: {
+        visibility?: string;
+        description?: string;
+    };
+}
+/**
+ * Format lifecycle action for output (used in both dry-run and real execution).
+ * Returns empty array if action is "existed" (no output needed).
+ */
+export declare function formatLifecycleAction(result: LifecycleResult, options?: FormatOptions): string[];

package/dist/lifecycle/lifecycle-formatter.js

@@ -0,0 +1,34 @@
+import chalk from "chalk";
+import { getRepoDisplayName } from "../shared/repo-detector.js";
+/**
+ * Format lifecycle action for output (used in both dry-run and real execution).
+ * Returns empty array if action is "existed" (no output needed).
+ */
+export function formatLifecycleAction(result, options) {
+    if (result.action === "existed") {
+        return [];
+    }
+    const lines = [];
+    const repoDisplay = getRepoDisplayName(result.repoInfo);
+    switch (result.action) {
+        case "created":
+            lines.push(chalk.green(`+ CREATE ${repoDisplay}`));
+            break;
+        case "forked":
+            lines.push(chalk.green(`+ FORK ${options?.upstream ?? "upstream"} -> ${repoDisplay}`));
+            break;
+        case "migrated":
+            lines.push(chalk.green(`+ MIGRATE ${options?.source ?? "source"} -> ${repoDisplay}`));
+            break;
+    }
+    // Add settings details if provided
+    if (options?.settings) {
+        if (options.settings.visibility) {
+            lines.push(`    visibility: ${options.settings.visibility}`);
+        }
+        if (options.settings.description) {
+            lines.push(`    description: "${options.settings.description}"`);
+        }
+    }
+    return lines;
+}

package/dist/lifecycle/lifecycle-helpers.d.ts

@@ -0,0 +1,27 @@
+import type { RepoConfig, GitHubRepoSettings } from "../config/types.js";
+import type { RepoInfo } from "../shared/repo-detector.js";
+import type { IRepoLifecycleManager, CreateRepoSettings, LifecycleResult } from "./types.js";
+export interface LifecycleCheckOptions {
+    dryRun: boolean;
+    /** Base work directory (combined with repoIndex to compute full path). */
+    workDir?: string;
+    githubHosts?: string[];
+    /** Pre-resolved work directory. If provided, used directly instead of computing from workDir + repoIndex. */
+    resolvedWorkDir?: string;
+    /** Auth token (GitHub App installation token or PAT) for gh CLI commands */
+    token?: string;
+}
+/**
+ * Build CreateRepoSettings from GitHubRepoSettings.
+ * Extracts only the fields relevant for repo creation.
+ */
+export declare function toCreateRepoSettings(repo: GitHubRepoSettings | undefined): CreateRepoSettings | undefined;
+export interface LifecycleCheckResult {
+    lifecycleResult: LifecycleResult;
+    outputLines: string[];
+}
+/**
+ * Run lifecycle check for a single repo.
+ * Returns the lifecycle result and formatted output lines.
+ */
+export declare function runLifecycleCheck(repoConfig: RepoConfig, repoInfo: RepoInfo, repoIndex: number, options: LifecycleCheckOptions, lifecycleManager: IRepoLifecycleManager, repoSettings?: GitHubRepoSettings): Promise<LifecycleCheckResult>;

package/dist/lifecycle/lifecycle-helpers.js

@@ -0,0 +1,47 @@
+import { resolve, join } from "node:path";
+import { generateWorkspaceName } from "../shared/workspace-utils.js";
+import { formatLifecycleAction } from "./lifecycle-formatter.js";
+/**
+ * Build CreateRepoSettings from GitHubRepoSettings.
+ * Extracts only the fields relevant for repo creation.
+ */
+export function toCreateRepoSettings(repo) {
+    if (!repo)
+        return undefined;
+    const result = {};
+    if (repo.visibility !== undefined)
+        result.visibility = repo.visibility;
+    if (repo.description !== undefined)
+        result.description = repo.description;
+    if (repo.hasIssues !== undefined)
+        result.hasIssues = repo.hasIssues;
+    if (repo.hasWiki !== undefined)
+        result.hasWiki = repo.hasWiki;
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/**
+ * Run lifecycle check for a single repo.
+ * Returns the lifecycle result and formatted output lines.
+ */
+export async function runLifecycleCheck(repoConfig, repoInfo, repoIndex, options, lifecycleManager, repoSettings) {
+    const workDir = options.resolvedWorkDir ??
+        resolve(join(options.workDir ?? "./tmp", generateWorkspaceName(repoIndex)));
+    const createSettings = toCreateRepoSettings(repoSettings);
+    const lifecycleResult = await lifecycleManager.ensureRepo(repoConfig, repoInfo, {
+        dryRun: options.dryRun,
+        workDir,
+        githubHosts: options.githubHosts,
+        token: options.token,
+    }, createSettings);
+    const outputLines = formatLifecycleAction(lifecycleResult, {
+        upstream: repoConfig.upstream,
+        source: repoConfig.source,
+        settings: createSettings
+            ? {
+                visibility: createSettings.visibility,
+                description: createSettings.description,
+            }
+            : undefined,
+    });
+    return { lifecycleResult, outputLines };
+}

package/dist/lifecycle/repo-lifecycle-factory.d.ts

@@ -0,0 +1,14 @@
+import { ICommandExecutor } from "../shared/command-executor.js";
+import type { IRepoLifecycleFactory, IRepoLifecycleProvider, IMigrationSource, LifecyclePlatform } from "./types.js";
+/**
+ * Factory for creating lifecycle providers and migration sources.
+ */
+export declare class RepoLifecycleFactory implements IRepoLifecycleFactory {
+    private readonly providers;
+    private readonly sources;
+    private readonly executor;
+    private readonly retries;
+    constructor(executor?: ICommandExecutor, retries?: number);
+    getProvider(platform: LifecyclePlatform): IRepoLifecycleProvider;
+    getMigrationSource(platform: LifecyclePlatform): IMigrationSource;
+}

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

@@ -0,0 +1,57 @@
+import { defaultExecutor, } from "../shared/command-executor.js";
+import { GitHubLifecycleProvider } from "./github-lifecycle-provider.js";
+import { AdoMigrationSource } from "./ado-migration-source.js";
+/**
+ * Factory for creating lifecycle providers and migration sources.
+ */
+export class RepoLifecycleFactory {
+    providers = new Map();
+    sources = new Map();
+    executor;
+    retries;
+    constructor(executor, retries) {
+        this.executor = executor ?? defaultExecutor;
+        this.retries = retries ?? 3;
+    }
+    getProvider(platform) {
+        // Check cache first
+        const cached = this.providers.get(platform);
+        if (cached) {
+            return cached;
+        }
+        // Create provider
+        let provider;
+        switch (platform) {
+            case "github":
+                provider = new GitHubLifecycleProvider({
+                    executor: this.executor,
+                    retries: this.retries,
+                });
+                break;
+            default:
+                throw new Error(`Platform '${platform}' not supported as target for lifecycle operations. ` +
+                    `Currently supported: github`);
+        }
+        this.providers.set(platform, provider);
+        return provider;
+    }
+    getMigrationSource(platform) {
+        // Check cache first
+        const cached = this.sources.get(platform);
+        if (cached) {
+            return cached;
+        }
+        // Create source
+        let source;
+        switch (platform) {
+            case "azure-devops":
+                source = new AdoMigrationSource(this.executor, this.retries);
+                break;
+            default:
+                throw new Error(`Platform '${platform}' not supported as migration source. ` +
+                    `Currently supported: azure-devops`);
+        }
+        this.sources.set(platform, source);
+        return source;
+    }
+}

package/dist/lifecycle/repo-lifecycle-manager.d.ts

@@ -0,0 +1,20 @@
+import { type RepoInfo } from "../shared/repo-detector.js";
+import type { RepoConfig } from "../config/types.js";
+import type { IRepoLifecycleManager, IRepoLifecycleFactory, LifecycleResult, LifecycleOptions, CreateRepoSettings } from "./types.js";
+/**
+ * Orchestrates repo lifecycle operations before sync.
+ */
+export declare class RepoLifecycleManager implements IRepoLifecycleManager {
+    private readonly factory;
+    constructor(factory?: IRepoLifecycleFactory, retries?: number);
+    ensureRepo(repoConfig: RepoConfig, repoInfo: RepoInfo, options: LifecycleOptions, settings?: CreateRepoSettings): Promise<LifecycleResult>;
+    private create;
+    private fork;
+    private migrate;
+    /**
+     * 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.
+     */
+    private waitForRepoReady;
+}