@aspruyt/xfg 6.0.3 → 6.2.0

package/dist/lifecycle/ado-migration-source.js

@@ -1,4 +1,3 @@
-import { escapeShellArg } from "../shared/shell-utils.js";
 import { withRetry } from "../shared/retry-utils.js";
 import { toErrorMessage } from "../shared/type-guards.js";
 import { LifecycleError } from "../shared/errors.js";
@@ -24,9 +23,8 @@ export class AdoMigrationSource {
     }
     async cloneForMigration(repoInfo, workDir) {
         this.assertAdo(repoInfo);
-        const command = `git clone --mirror ${escapeShellArg(repoInfo.gitUrl)} ${escapeShellArg(workDir)}`;
         try {
-            await withRetry(() => this.executor.exec(command, this.cwd), {
+            await withRetry(() => this.executor.exec("git", ["clone", "--mirror", "--", repoInfo.gitUrl, workDir], this.cwd), {
                 retries: this.retries,
             });
         }
@@ -34,7 +32,7 @@ export class AdoMigrationSource {
             const msg = toErrorMessage(error);
             throw new LifecycleError(`Failed to clone migration source ${repoInfo.gitUrl}: ${msg}. ` +
                 `Ensure you have authentication configured for Azure DevOps ` +
-                `(e.g., AZURE_DEVOPS_EXT_PAT or git credential helper).`);
+                `(e.g., AZURE_DEVOPS_EXT_PAT or git credential helper).`, { cause: error });
         }
     }
 }

package/dist/lifecycle/github-lifecycle-provider.d.ts

@@ -1,5 +1,5 @@
 import type { ICommandExecutor } from "../shared/command-executor.js";
-import type { DebugWarnLog } from "../shared/logger.js";
+import type { DebugInfoWarnLog } from "../shared/logger.js";
 import type { IRepoLifecycleProvider, LifecyclePlatform, LifecycleExistsParams, LifecycleCreateParams, LifecycleForkParams, LifecycleReceiveMigrationParams } from "./types.js";
 /**
  * GitHub implementation of IRepoLifecycleProvider.
@@ -13,7 +13,7 @@ interface GitHubLifecycleProviderOptions {
     forkReadyTimeoutMs?: number;
     /** Poll interval in ms for fork readiness checks (default: 2000) */
     forkPollIntervalMs?: number;
-    log?: DebugWarnLog;
+    log?: DebugInfoWarnLog;
 }
 export declare class GitHubLifecycleProvider implements IRepoLifecycleProvider {
     readonly platform: LifecyclePlatform;
@@ -30,15 +30,11 @@ export declare class GitHubLifecycleProvider implements IRepoLifecycleProvider {
      */
     private isOrganization;
     private assertGitHub;
-    /**
-     * Builds the common gh API command prefix parts for a given repo.
-     * Returns tokenEnv for exec options, and the command prefix string
-     * (e.g., "gh api --hostname host repos/owner/repo").
-     */
     private buildGhApiPrefix;
     exists(params: LifecycleExistsParams): Promise<boolean>;
     create(params: LifecycleCreateParams): Promise<void>;
     fork(params: LifecycleForkParams): Promise<void>;
+    private pollWithDeadline;
     /**
      * Wait for a forked repo to become available via the GitHub API.
      * GitHub forks are created asynchronously; polls exists() with a timeout.
@@ -49,6 +45,10 @@ export declare class GitHubLifecycleProvider implements IRepoLifecycleProvider {
      */
     private applyRepoSettings;
     receiveMigration(params: LifecycleReceiveMigrationParams): Promise<void>;
+    private removeOriginRemote;
+    private cleanNonStandardRefs;
+    private renameMirrorDefaultBranch;
+    private createRepoAndPushMirror;
     /**
      * Rename a branch via the GitHub branch rename API.
      * GitHub automatically updates the default branch pointer.
@@ -57,10 +57,6 @@ export declare class GitHubLifecycleProvider implements IRepoLifecycleProvider {
     /**
      * Poll until the GitHub API reports the expected default branch.
      * After a branch rename, the API may lag for a few seconds.
-     *
-     * Note: Uses the same executor.exec pattern as the rest of this class.
-     * The command arguments are constructed from trusted RepoInfo values
-     * (validated during config parsing), not user input.
      */
     private waitForDefaultBranch;
     /**

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

@@ -1,9 +1,8 @@
-import { escapeShellArg } from "../shared/shell-utils.js";
 import { withRetry, isPermanentError, DEFAULT_PERMANENT_ERROR_PATTERNS, } from "../shared/retry-utils.js";
 import { assertGitHubRepo, } from "../repo/index.js";
 import { toErrorMessage } from "../shared/type-guards.js";
 import { LifecycleError } from "../shared/errors.js";
-import { buildTokenEnv, getHostnameFlag } from "../shared/gh-api-utils.js";
+import { buildTokenEnv, buildHostnameArgs } from "../shared/gh-api-utils.js";
 /**
  * Error messages that indicate "repo not found" vs actual errors.
  */
@@ -42,24 +41,24 @@ const POST_CREATE_PERMANENT_PATTERNS = [
  * Interval between fork readiness checks (2 seconds).
  */
 const FORK_POLL_INTERVAL_MS = 2_000;
-function buildRepoCreateFlags(parts, settings) {
+function buildRepoCreateArgs(args, settings) {
     if (settings?.visibility === "public") {
-        parts.push("--public");
+        args.push("--public");
     }
     else if (settings?.visibility === "internal") {
-        parts.push("--internal");
+        args.push("--internal");
     }
     else {
-        parts.push("--private");
+        args.push("--private");
     }
     if (settings?.description) {
-        parts.push("--description", escapeShellArg(settings.description));
+        args.push("--description", settings.description);
     }
     if (settings?.hasIssues === false) {
-        parts.push("--disable-issues");
+        args.push("--disable-issues");
     }
     if (settings?.hasWiki === false) {
-        parts.push("--disable-wiki");
+        args.push("--disable-wiki");
     }
 }
 export class GitHubLifecycleProvider {
@@ -85,10 +84,11 @@ export class GitHubLifecycleProvider {
      * Uses gh api to query the user/org endpoint.
      */
     async isOrganization(owner, repoInfo, token) {
-        const { tokenEnv, prefix } = this.buildGhApiPrefix(repoInfo, token);
-        const command = `${prefix}users/${escapeShellArg(owner)}`;
+        const { tokenEnv, baseArgs } = this.buildGhApiPrefix(repoInfo, token);
         try {
-            const stdout = await withRetry(() => this.executor.exec(command, this.cwd, { env: tokenEnv }), { retries: this.retries });
+            const stdout = await withRetry(() => this.executor.exec("gh", [...baseArgs, `users/${owner}`], this.cwd, {
+                env: tokenEnv,
+            }), { retries: this.retries });
             const data = JSON.parse(stdout);
             return data.type === "Organization";
         }
@@ -114,27 +114,22 @@ export class GitHubLifecycleProvider {
     assertGitHub(repoInfo) {
         assertGitHubRepo(repoInfo, "GitHubLifecycleProvider");
     }
-    /**
-     * Builds the common gh API command prefix parts for a given repo.
-     * Returns tokenEnv for exec options, and the command prefix string
-     * (e.g., "gh api --hostname host repos/owner/repo").
-     */
     buildGhApiPrefix(repoInfo, token) {
         const tokenEnv = buildTokenEnv(token);
-        const hostnameFlag = getHostnameFlag(repoInfo);
-        const hostnamePart = hostnameFlag ? `${hostnameFlag} ` : "";
-        const apiPath = `repos/${escapeShellArg(repoInfo.owner)}/${escapeShellArg(repoInfo.repo)}`;
-        return { tokenEnv, prefix: `gh api ${hostnamePart}`, apiPath };
+        const hostnameArgs = buildHostnameArgs(repoInfo);
+        const apiPath = `repos/${repoInfo.owner}/${repoInfo.repo}`;
+        return { tokenEnv, baseArgs: ["api", ...hostnameArgs], apiPath };
     }
     async exists(params) {
         const { repo: repoInfo, token } = params;
         this.assertGitHub(repoInfo);
-        const { tokenEnv, prefix, apiPath } = this.buildGhApiPrefix(repoInfo, token);
-        const command = `${prefix}${apiPath}`;
+        const { tokenEnv, baseArgs, apiPath } = this.buildGhApiPrefix(repoInfo, token);
         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, { env: tokenEnv }), {
+            await withRetry(() => this.executor.exec("gh", [...baseArgs, apiPath], this.cwd, {
+                env: tokenEnv,
+            }), {
                 retries: this.retries,
             });
             return true;
@@ -152,23 +147,23 @@ export class GitHubLifecycleProvider {
         const { repo: repoInfo, settings, token } = params;
         this.assertGitHub(repoInfo);
         const tokenEnv = buildTokenEnv(token);
-        const parts = [
-            "gh repo create",
-            escapeShellArg(`${repoInfo.owner}/${repoInfo.repo}`),
+        const args = [
+            "repo",
+            "create",
+            `${repoInfo.owner}/${repoInfo.repo}`,
         ];
-        buildRepoCreateFlags(parts, settings);
+        buildRepoCreateArgs(args, settings);
         // 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, { env: tokenEnv }), {
+        args.push("--add-readme");
+        await withRetry(() => this.executor.exec("gh", args, this.cwd, { env: tokenEnv }), {
             retries: this.retries,
         });
         // Rename default branch if requested and it differs from what GitHub created.
         if (settings?.defaultBranch) {
-            const { tokenEnv: branchTokenEnv, prefix, apiPath, } = this.buildGhApiPrefix(repoInfo, token);
+            const { tokenEnv: branchTokenEnv, baseArgs, apiPath, } = this.buildGhApiPrefix(repoInfo, token);
             // Detect the actual default branch name
-            const actualBranch = (await withRetry(() => this.executor.exec(`${prefix}${apiPath} --jq '.default_branch'`, this.cwd, { env: branchTokenEnv }), {
+            const actualBranch = (await withRetry(() => this.executor.exec("gh", [...baseArgs, apiPath, "--jq", ".default_branch"], this.cwd, { env: branchTokenEnv }), {
                 retries: this.retries,
                 permanentErrorPatterns: POST_CREATE_PERMANENT_PATTERNS,
             })).trim();
@@ -199,16 +194,12 @@ export class GitHubLifecycleProvider {
         // 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 = [
-            "gh repo fork",
-            escapeShellArg(`${upstream.owner}/${upstream.repo}`),
-        ];
+        const forkArgs = ["repo", "fork", `${upstream.owner}/${upstream.repo}`];
         if (isOrg) {
-            parts.push("--org", escapeShellArg(target.owner));
+            forkArgs.push("--org", target.owner);
         }
-        parts.push("--fork-name", escapeShellArg(target.repo), "--clone=false");
-        const forkCommand = parts.join(" ");
-        await withRetry(() => this.executor.exec(forkCommand, this.cwd, { env: tokenEnv }), {
+        forkArgs.push("--fork-name", target.repo, "--clone=false");
+        await withRetry(() => this.executor.exec("gh", forkArgs, this.cwd, { env: tokenEnv }), {
             retries: this.retries,
         });
         // GitHub forks are async - wait for the fork to be ready for git operations
@@ -222,131 +213,131 @@ export class GitHubLifecycleProvider {
             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, options) {
-        const timeoutMs = options?.timeoutMs ?? FORK_READY_TIMEOUT_MS;
-        const intervalMs = options?.pollMs ?? FORK_POLL_INTERVAL_MS;
-        const token = options?.token;
-        const deadline = Date.now() + timeoutMs;
+    async pollWithDeadline(check, opts) {
+        const deadline = Date.now() + opts.timeoutMs;
         while (Date.now() < deadline) {
             try {
-                const ready = await this.exists({ repo: repoInfo, token });
-                if (ready) {
-                    return;
-                }
+                if (await check())
+                    return true;
             }
             catch (error) {
-                this.log?.debug(`Polling fork readiness: ${toErrorMessage(error)}`);
+                this.log?.debug(`Polling ${opts.debugLabel}: ${toErrorMessage(error)}`);
             }
             const remaining = deadline - Date.now();
             if (remaining <= 0)
                 break;
-            await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, remaining)));
+            await new Promise((resolve) => setTimeout(resolve, Math.min(opts.pollMs, remaining)));
+        }
+        return false;
+    }
+    /**
+     * 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, options) {
+        const timeoutMs = options?.timeoutMs ?? FORK_READY_TIMEOUT_MS;
+        const pollMs = options?.pollMs ?? FORK_POLL_INTERVAL_MS;
+        const token = options?.token;
+        const ready = await this.pollWithDeadline(() => this.exists({ repo: repoInfo, token }), { timeoutMs, pollMs, debugLabel: "fork readiness" });
+        if (!ready) {
+            throw new LifecycleError(`Timed out waiting for fork ${repoInfo.owner}/${repoInfo.repo} to become available ` +
+                `after ${timeoutMs / 1000}s. The fork may still be processing on GitHub.`);
         }
-        throw new LifecycleError(`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 tokenEnv = buildTokenEnv(token);
-        const parts = [
-            "gh repo edit",
-            escapeShellArg(`${repoInfo.owner}/${repoInfo.repo}`),
-        ];
+        const args = ["repo", "edit", `${repoInfo.owner}/${repoInfo.repo}`];
         if (settings.visibility) {
-            parts.push("--visibility", settings.visibility, "--accept-visibility-change-consequences");
+            args.push("--visibility", settings.visibility, "--accept-visibility-change-consequences");
         }
         if (settings.description) {
-            parts.push("--description", escapeShellArg(settings.description));
+            args.push("--description", settings.description);
         }
-        const command = parts.join(" ");
-        await withRetry(() => this.executor.exec(command, this.cwd, { env: tokenEnv }), {
+        await withRetry(() => this.executor.exec("gh", args, this.cwd, { env: tokenEnv }), {
             retries: this.retries,
         });
     }
     async receiveMigration(params) {
         const { repo: repoInfo, sourceDir, settings, token } = params;
         this.assertGitHub(repoInfo);
-        const tokenEnv = buildTokenEnv(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.
+        await this.removeOriginRemote(sourceDir);
+        await this.cleanNonStandardRefs(sourceDir);
+        await this.renameMirrorDefaultBranch(sourceDir, settings?.defaultBranch);
+        await this.createRepoAndPushMirror(repoInfo, sourceDir, settings, token);
+    }
+    async removeOriginRemote(sourceDir) {
         try {
-            await this.executor.exec(`git -C ${escapeShellArg(sourceDir)} remote remove origin`, this.cwd);
+            await this.executor.exec("git", ["-C", sourceDir, "remote", "remove", "origin"], this.cwd);
         }
         catch (error) {
             this.log?.debug(`Cleanup: remote remove origin skipped - ${toErrorMessage(error)}`);
         }
-        // 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.
+    }
+    // Mirror clones include ALL refs from the source, but GitHub only
+    // accepts branches (refs/heads/*) and tags (refs/tags/*).
+    async cleanNonStandardRefs(sourceDir) {
         try {
-            const allRefs = await this.executor.exec(`git -C ${escapeShellArg(sourceDir)} for-each-ref --format='%(refname)'`, this.cwd);
+            const allRefs = await this.executor.exec("git", ["-C", 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);
+                    await this.executor.exec("git", ["-C", sourceDir, "update-ref", "-d", trimmed], this.cwd);
                 }
             }
         }
         catch (error) {
             this.log?.debug(`Cleanup: ref cleanup skipped - ${toErrorMessage(error)}`);
         }
-        // Rename default branch in mirror clone if requested.
-        if (settings?.defaultBranch) {
-            const headRef = (await this.executor.exec(`git -C ${escapeShellArg(sourceDir)} symbolic-ref HEAD`, this.cwd)).trim();
-            const prefix = "refs/heads/";
-            if (!headRef.startsWith(prefix)) {
-                throw new LifecycleError(`Mirror clone HEAD symbolic-ref is '${headRef}', expected to start with '${prefix}'. ` +
-                    `Cannot rename default branch.`);
-            }
-            const sourceBranch = headRef.slice(prefix.length);
-            if (sourceBranch !== settings.defaultBranch) {
-                await this.executor.exec(`git -C ${escapeShellArg(sourceDir)} branch -m ${escapeShellArg(sourceBranch)} ${escapeShellArg(settings.defaultBranch)}`, this.cwd);
-                await this.executor.exec(`git -C ${escapeShellArg(sourceDir)} symbolic-ref HEAD refs/heads/${escapeShellArg(settings.defaultBranch)}`, this.cwd);
-            }
+    }
+    async renameMirrorDefaultBranch(sourceDir, targetBranch) {
+        if (!targetBranch)
+            return;
+        const headRef = (await this.executor.exec("git", ["-C", sourceDir, "symbolic-ref", "HEAD"], this.cwd)).trim();
+        const prefix = "refs/heads/";
+        if (!headRef.startsWith(prefix)) {
+            throw new LifecycleError(`Mirror clone HEAD symbolic-ref is '${headRef}', expected to start with '${prefix}'. ` +
+                `Cannot rename default branch.`);
+        }
+        const sourceBranch = headRef.slice(prefix.length);
+        if (sourceBranch !== targetBranch) {
+            await this.executor.exec("git", ["-C", sourceDir, "branch", "-m", sourceBranch, targetBranch], this.cwd);
+            await this.executor.exec("git", ["-C", sourceDir, "symbolic-ref", "HEAD", `refs/heads/${targetBranch}`], this.cwd);
         }
-        // Split create and push into two steps. gh repo create --source --push
-        // does both atomically, but if the git backend hasn't propagated after
-        // the GraphQL create, the push fails with "Repository not found". A
-        // retry then hits "Name already exists" on the create step.
+    }
+    async createRepoAndPushMirror(repoInfo, sourceDir, settings, token) {
+        // Split create and push: gh repo create --source --push does both
+        // atomically, but if the git backend hasn't propagated after the
+        // GraphQL create, the push fails with "Repository not found".
         const repoSlug = `${repoInfo.owner}/${repoInfo.repo}`;
-        const createParts = ["gh repo create", escapeShellArg(repoSlug)];
-        buildRepoCreateFlags(createParts, settings);
+        const tokenEnv = buildTokenEnv(token);
+        const createArgs = ["repo", "create", repoSlug];
+        buildRepoCreateArgs(createArgs, settings);
         try {
-            await withRetry(() => this.executor.exec(createParts.join(" "), this.cwd, {
-                env: tokenEnv,
-            }), {
+            await withRetry(() => this.executor.exec("gh", createArgs, this.cwd, { env: tokenEnv }), {
                 retries: this.retries,
                 permanentErrorPatterns: POST_CREATE_PERMANENT_PATTERNS,
                 log: this.log
-                    ? { info: (m) => this.log.warn(m) }
+                    ? { info: (m) => this.log.info(m) }
                     : undefined,
             });
         }
         catch (error) {
-            if (!/already\s*exists/i.test(toErrorMessage(error))) {
+            if (!isPermanentError(error, [/already\s*exists/i])) {
                 throw error;
             }
         }
-        // Push mirror content via authenticated URL. Retries handle the git
-        // backend propagation delay (POST_CREATE_PERMANENT_PATTERNS allows
-        // retry on 404/not-found).
         const remoteUrl = token
             ? `https://x-access-token:${token}@${repoInfo.host}/${repoSlug}.git`
             : `https://${repoInfo.host}/${repoSlug}.git`;
-        await this.executor.exec(`git -C ${escapeShellArg(sourceDir)} remote add origin ${escapeShellArg(remoteUrl)}`, this.cwd);
-        await withRetry(() => this.executor.exec(`git -C ${escapeShellArg(sourceDir)} push --mirror origin`, this.cwd, { env: tokenEnv }), {
+        await this.executor.exec("git", ["-C", sourceDir, "remote", "add", "origin", remoteUrl], this.cwd);
+        await withRetry(() => this.executor.exec("git", ["-C", sourceDir, "push", "--mirror", "origin"], this.cwd, { env: tokenEnv }), {
             retries: this.retries,
             permanentErrorPatterns: POST_CREATE_PERMANENT_PATTERNS,
-            log: this.log ? { info: (m) => this.log.warn(m) } : undefined,
+            log: this.log ? { info: (m) => this.log.info(m) } : undefined,
         });
     }
     /**
@@ -354,41 +345,31 @@ export class GitHubLifecycleProvider {
      * GitHub automatically updates the default branch pointer.
      */
     async renameBranch(repoInfo, current, desired, token) {
-        const { tokenEnv, prefix, apiPath } = this.buildGhApiPrefix(repoInfo, token);
-        await withRetry(() => this.executor.exec(`${prefix}${apiPath}/branches/${escapeShellArg(current)}/rename ` +
-            `--method POST -f new_name=${escapeShellArg(desired)}`, this.cwd, { env: tokenEnv }), {
+        const { tokenEnv, baseArgs, apiPath } = this.buildGhApiPrefix(repoInfo, token);
+        await withRetry(() => this.executor.exec("gh", [
+            ...baseArgs,
+            `${apiPath}/branches/${current}/rename`,
+            "--method",
+            "POST",
+            "-f",
+            `new_name=${desired}`,
+        ], this.cwd, { env: tokenEnv }), {
             retries: this.retries,
         });
     }
     /**
      * Poll until the GitHub API reports the expected default branch.
      * After a branch rename, the API may lag for a few seconds.
-     *
-     * Note: Uses the same executor.exec pattern as the rest of this class.
-     * The command arguments are constructed from trusted RepoInfo values
-     * (validated during config parsing), not user input.
      */
     async waitForDefaultBranch(repoInfo, expectedBranch, options) {
         const timeoutMs = options?.timeoutMs ?? 15000;
         const pollMs = options?.pollMs ?? 1000;
-        const { tokenEnv, prefix, apiPath } = this.buildGhApiPrefix(repoInfo, options?.token);
-        const deadline = Date.now() + timeoutMs;
-        while (Date.now() < deadline) {
-            try {
-                const branch = (await this.executor.exec(`${prefix}${apiPath} --jq '.default_branch'`, this.cwd, { env: tokenEnv })).trim();
-                if (branch === expectedBranch) {
-                    return;
-                }
-            }
-            catch (error) {
-                this.log?.debug(`Polling default branch: ${toErrorMessage(error)}`);
-            }
-            const remaining = deadline - Date.now();
-            if (remaining <= 0)
-                break;
-            await new Promise((resolve) => setTimeout(resolve, Math.min(pollMs, remaining)));
-        }
-        // Don't throw — rename succeeded, this is just a best-effort wait
+        const { tokenEnv, baseArgs, apiPath } = this.buildGhApiPrefix(repoInfo, options?.token);
+        // Best-effort wait — don't throw on timeout since rename already succeeded
+        await this.pollWithDeadline(async () => {
+            const branch = (await this.executor.exec("gh", [...baseArgs, apiPath, "--jq", ".default_branch"], this.cwd, { env: tokenEnv })).trim();
+            return branch === expectedBranch;
+        }, { timeoutMs, pollMs, debugLabel: "default branch" });
     }
     /**
      * Delete the README.md that --add-readme creates.
@@ -396,16 +377,24 @@ export class GitHubLifecycleProvider {
      * commit) but no files, so xfg sync starts from a clean state.
      */
     async deleteReadme(repoInfo, token) {
-        const { tokenEnv, prefix, apiPath } = this.buildGhApiPrefix(repoInfo, token);
+        const { tokenEnv, baseArgs, apiPath } = this.buildGhApiPrefix(repoInfo, token);
         // Get the SHA of the README.md created by --add-readme
-        const fileInfo = await withRetry(() => this.executor.exec(`${prefix}${apiPath}/contents/README.md --jq '.sha'`, this.cwd, { env: tokenEnv }), {
+        const fileInfo = await withRetry(() => this.executor.exec("gh", [...baseArgs, `${apiPath}/contents/README.md`, "--jq", ".sha"], this.cwd, { env: tokenEnv }), {
             retries: this.retries,
             permanentErrorPatterns: POST_CREATE_PERMANENT_PATTERNS,
         });
         const sha = fileInfo.trim();
         // Delete the README.md to leave the repo clean
-        await withRetry(() => this.executor.exec(`${prefix}${apiPath}/contents/README.md ` +
-            `--method DELETE -f message='Remove initialization file' -f sha=${escapeShellArg(sha)}`, this.cwd, { env: tokenEnv }), {
+        await withRetry(() => this.executor.exec("gh", [
+            ...baseArgs,
+            `${apiPath}/contents/README.md`,
+            "--method",
+            "DELETE",
+            "-f",
+            "message=Remove initialization file",
+            "-f",
+            `sha=${sha}`,
+        ], this.cwd, { env: tokenEnv }), {
             retries: this.retries,
             permanentErrorPatterns: POST_CREATE_PERMANENT_PATTERNS,
         });

package/dist/lifecycle/{lifecycle-helpers.d.ts → helpers.d.ts}

@@ -20,10 +20,14 @@ interface LifecycleCheckOptions {
  * Extracts only the fields relevant for repo creation.
  */
 export declare function toCreateRepoSettings(repo: GitHubRepoSettings | undefined): CreateRepoSettings | undefined;
+export interface LifecycleReportSettings {
+    visibility?: CreateRepoSettings["visibility"];
+    description?: CreateRepoSettings["description"];
+}
 export interface LifecycleCheckResult {
     lifecycleResult: LifecycleResult;
     outputLines: string[];
-    createSettings: CreateRepoSettings | undefined;
+    reportSettings: LifecycleReportSettings | undefined;
 }
 /**
  * Run lifecycle check for a single repo.

package/dist/lifecycle/{lifecycle-helpers.js → helpers.js}

@@ -1,6 +1,6 @@
 import { resolve, join } from "node:path";
 import { generateWorkspaceName } from "../shared/workspace-utils.js";
-import { formatLifecycleAction } from "./lifecycle-formatter.js";
+import { formatLifecycleAction } from "./formatter.js";
 /**
  * Build CreateRepoSettings from GitHubRepoSettings.
  * Extracts only the fields relevant for repo creation.
@@ -35,15 +35,16 @@ export async function runLifecycleCheck(repoConfig, repoInfo, options) {
         githubHosts: options.githubHosts,
         token: options.token,
     }, createSettings);
+    const reportSettings = createSettings
+        ? {
+            visibility: createSettings.visibility,
+            description: createSettings.description,
+        }
+        : undefined;
     const outputLines = formatLifecycleAction(lifecycleResult, {
         upstream: repoConfig.upstream,
         source: repoConfig.source,
-        settings: createSettings
-            ? {
-                visibility: createSettings.visibility,
-                description: createSettings.description,
-            }
-            : undefined,
+        settings: reportSettings,
     });
-    return { lifecycleResult, outputLines, createSettings };
+    return { lifecycleResult, outputLines, reportSettings };
 }

package/dist/lifecycle/index.d.ts

@@ -1,3 +1,3 @@
-export type { IRepoLifecycleManager } from "./types.js";
+export type { IRepoLifecycleManager, LifecycleActionKind } from "./types.js";
 export { RepoLifecycleManager } from "./repo-lifecycle-manager.js";
-export { runLifecycleCheck, toCreateRepoSettings, type LifecycleCheckResult, } from "./lifecycle-helpers.js";
+export { runLifecycleCheck, toCreateRepoSettings, type LifecycleCheckResult, } from "./helpers.js";

package/dist/lifecycle/index.js

@@ -1,2 +1,2 @@
 export { RepoLifecycleManager } from "./repo-lifecycle-manager.js";
-export { runLifecycleCheck, toCreateRepoSettings, } from "./lifecycle-helpers.js";
+export { runLifecycleCheck, toCreateRepoSettings, } from "./helpers.js";

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

@@ -1,5 +1,5 @@
 import type { ICommandExecutor } from "../shared/command-executor.js";
-import type { DebugWarnLog } from "../shared/logger.js";
+import type { DebugInfoWarnLog } from "../shared/logger.js";
 import type { IRepoLifecycleFactory, IRepoLifecycleProvider, IMigrationSource, LifecyclePlatform } from "./types.js";
 export declare class RepoLifecycleFactory implements IRepoLifecycleFactory {
     private readonly providers;
@@ -8,7 +8,7 @@ export declare class RepoLifecycleFactory implements IRepoLifecycleFactory {
     private readonly retries;
     private readonly cwd;
     private readonly log?;
-    constructor(executor: ICommandExecutor, retries: number | undefined, cwd: string, log?: DebugWarnLog);
+    constructor(executor: ICommandExecutor, retries: number | undefined, cwd: string, log?: DebugInfoWarnLog);
     getProvider(platform: LifecyclePlatform): IRepoLifecycleProvider;
     getMigrationSource(platform: LifecyclePlatform): IMigrationSource;
 }

package/dist/output/github-summary.js

@@ -5,11 +5,10 @@ import { toErrorMessage } from "../shared/type-guards.js";
  * No-op if summaryPath is not provided.
  */
 export function writeGitHubStepSummary(markdown, summaryPath, log) {
-    const path = summaryPath;
-    if (!path)
+    if (!summaryPath)
         return;
     try {
-        appendFileSync(path, "\n" + markdown + "\n");
+        appendFileSync(summaryPath, "\n" + markdown + "\n");
     }
     catch (error) {
         log?.debug(`Failed to write GitHub step summary: ${toErrorMessage(error)}`);

package/dist/output/index.d.ts

@@ -0,0 +1,4 @@
+export { writeGitHubStepSummary } from "./github-summary.js";
+export { hasLifecycleChanges, formatLifecycleReportCLI, formatLifecycleReportMarkdown, writeLifecycleReportSummary, type LifecycleReport, type LifecycleAction, } from "./lifecycle-report.js";
+export { formatCountEntry, formatSettingsReportCLI, renderRepoSettingsDiffLines, formatSettingsReportMarkdown, writeSettingsReportSummary, type SettingsReport, type RepoChanges, type SettingChange, type RulesetChange, type LabelChange, } from "./settings-report.js";
+export { formatSyncReportCLI, formatSyncReportMarkdown, renderSyncLines, writeSyncReportSummary, type SyncReport, type RepoFileChanges, type ReportFileChange, } from "./sync-report.js";

package/dist/output/index.js

@@ -0,0 +1,4 @@
+export { writeGitHubStepSummary } from "./github-summary.js";
+export { hasLifecycleChanges, formatLifecycleReportCLI, formatLifecycleReportMarkdown, writeLifecycleReportSummary, } from "./lifecycle-report.js";
+export { formatCountEntry, formatSettingsReportCLI, renderRepoSettingsDiffLines, formatSettingsReportMarkdown, writeSettingsReportSummary, } from "./settings-report.js";
+export { formatSyncReportCLI, formatSyncReportMarkdown, renderSyncLines, writeSyncReportSummary, } from "./sync-report.js";

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

@@ -1,4 +1,4 @@
-import type { LifecycleActionKind } from "../lifecycle/types.js";
+import type { LifecycleActionKind } from "../lifecycle/index.js";
 import type { RepoVisibility } from "../config/index.js";
 export interface LifecycleReport {
     actions: LifecycleAction[];

package/dist/output/lifecycle-report.js

@@ -33,6 +33,11 @@ function renderActionDiffLines(actions) {
             case "migrated":
                 lines.push(`+ MIGRATE ${action.source ?? "source"} -> ${action.repoName}`);
                 break;
+            /* c8 ignore next 4 */
+            default: {
+                const _exhaustive = action.action;
+                throw new Error(`Unexpected lifecycle action: ${_exhaustive}`);
+            }
         }
         if (action.settings) {
             if (action.settings.visibility) {