@aspruyt/xfg 4.0.2 → 4.0.4

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

@@ -1,9 +1,8 @@
 import { escapeShellArg } from "../shared/shell-utils.js";
-import { defaultExecutor, } from "../shared/command-executor.js";
-import { withRetry, DEFAULT_PERMANENT_ERROR_PATTERNS, } from "../shared/retry-utils.js";
+import { withRetry, isPermanentError, DEFAULT_PERMANENT_ERROR_PATTERNS, } from "../shared/retry-utils.js";
 import { assertGitHubRepo, } from "../shared/repo-detector.js";
-import { logger } from "../shared/logger.js";
 import { toErrorMessage } from "../shared/type-guards.js";
+import { LifecycleError } from "../shared/errors.js";
 import { buildTokenEnv, getHostnameFlag } from "../shared/gh-api-utils.js";
 /**
  * Error messages that indicate "repo not found" vs actual errors.
@@ -43,13 +42,16 @@ export class GitHubLifecycleProvider {
     cwd;
     forkReadyTimeoutMs;
     forkPollIntervalMs;
+    log;
     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;
+        this.executor = options.executor;
+        this.retries = options.retries ?? 3;
+        this.cwd = options.cwd;
+        this.forkReadyTimeoutMs =
+            options.forkReadyTimeoutMs ?? FORK_READY_TIMEOUT_MS;
+        this.forkPollIntervalMs =
+            options.forkPollIntervalMs ?? FORK_POLL_INTERVAL_MS;
+        this.log = options.log;
     }
     /**
      * Check if a GitHub owner is an organization (vs user).
@@ -64,11 +66,19 @@ export class GitHubLifecycleProvider {
             return data.type === "Organization";
         }
         catch (error) {
-            // If we can't determine, assume it's an org (safer - uses --org flag).
+            // Two-tier error handling:
+            // 1. Permanent errors (auth failures, 403/401) are rethrown — retrying
+            //    or falling through would mask a real credentials problem.
+            // 2. Transient errors (network timeouts, 5xx) fall through to assume
+            //    the owner is an organization, which is the safer default because
+            //    --org is required for org forks but harmless if wrong.
+            if (isPermanentError(error)) {
+                throw error;
+            }
             // This may cause fork to fail with a misleading error for personal accounts.
             const errMsg = toErrorMessage(error);
-            logger.debug(`Could not determine if '${owner}' is an organization, defaulting to org behavior: ${errMsg}`);
-            logger.warn(`Could not verify if '${owner}' is an organization or user account. ` +
+            this.log?.debug(`Could not determine if '${owner}' is an organization, defaulting to org behavior: ${errMsg}`);
+            this.log?.warn(`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;
@@ -170,7 +180,7 @@ export class GitHubLifecycleProvider {
         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}'. ` +
+            throw new LifecycleError(`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
@@ -219,14 +229,14 @@ export class GitHubLifecycleProvider {
                 }
             }
             catch (error) {
-                logger.debug(`Polling fork readiness: ${toErrorMessage(error)}`);
+                this.log?.debug(`Polling fork readiness: ${toErrorMessage(error)}`);
             }
             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 ` +
+        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.`);
     }
     /**
@@ -258,7 +268,7 @@ export class GitHubLifecycleProvider {
             await this.executor.exec(`git -C ${escapeShellArg(sourceDir)} remote remove origin`, this.cwd);
         }
         catch (error) {
-            logger.debug(`Cleanup: remote remove origin skipped - ${toErrorMessage(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
@@ -276,14 +286,14 @@ export class GitHubLifecycleProvider {
             }
         }
         catch (error) {
-            logger.debug(`Cleanup: ref cleanup skipped - ${toErrorMessage(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 Error(`Mirror clone HEAD symbolic-ref is '${headRef}', expected to start with '${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);
@@ -360,7 +370,7 @@ export class GitHubLifecycleProvider {
                 }
             }
             catch (error) {
-                logger.debug(`Polling default branch: ${toErrorMessage(error)}`);
+                this.log?.debug(`Polling default branch: ${toErrorMessage(error)}`);
             }
             await new Promise((resolve) => setTimeout(resolve, pollMs));
         }

package/dist/lifecycle/lifecycle-formatter.js

@@ -1,5 +1,6 @@
 import chalk from "chalk";
 import { getRepoDisplayName } from "../shared/repo-detector.js";
+import { SyncError } from "../shared/errors.js";
 /**
  * Format lifecycle action for output (used in both dry-run and real execution).
  * Returns empty array if action is "existed" (no output needed).
@@ -22,7 +23,7 @@ export function formatLifecycleAction(result, options) {
             break;
         default: {
             const _exhaustive = result.action;
-            throw new Error(`Unknown lifecycle action: ${_exhaustive}`);
+            throw new SyncError(`Unknown lifecycle action: ${_exhaustive}`);
         }
     }
     // Add settings details if provided

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

@@ -10,6 +10,10 @@ interface LifecycleCheckOptions {
     resolvedWorkDir?: string;
     /** Auth token (GitHub App installation token or PAT) for gh CLI commands */
     token?: string;
+    /** Index used to generate workspace directory name when resolvedWorkDir is not provided. */
+    repoIndex: number;
+    lifecycleManager: IRepoLifecycleManager;
+    repoSettings?: GitHubRepoSettings;
 }
 /**
  * Build CreateRepoSettings from GitHubRepoSettings.
@@ -24,5 +28,5 @@ interface LifecycleCheckResult {
  * 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>;
+export declare function runLifecycleCheck(repoConfig: RepoConfig, repoInfo: RepoInfo, options: LifecycleCheckOptions): Promise<LifecycleCheckResult>;
 export {};

package/dist/lifecycle/lifecycle-helpers.js

@@ -25,11 +25,11 @@ export function toCreateRepoSettings(repo) {
  * 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) {
+export async function runLifecycleCheck(repoConfig, repoInfo, options) {
     const workDir = options.resolvedWorkDir ??
-        resolve(join(options.workDir ?? "./tmp", generateWorkspaceName(repoIndex)));
-    const createSettings = toCreateRepoSettings(repoSettings);
-    const lifecycleResult = await lifecycleManager.ensureRepo(repoConfig, repoInfo, {
+        resolve(join(options.workDir ?? "./tmp", generateWorkspaceName(options.repoIndex)));
+    const createSettings = toCreateRepoSettings(options.repoSettings);
+    const lifecycleResult = await options.lifecycleManager.ensureRepo(repoConfig, repoInfo, {
         dryRun: options.dryRun,
         workDir,
         githubHosts: options.githubHosts,

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

@@ -1,14 +1,14 @@
 import { ICommandExecutor } from "../shared/command-executor.js";
+import type { DebugWarnLog } from "../shared/logger.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);
+    private readonly cwd;
+    private readonly log?;
+    constructor(executor: ICommandExecutor, retries: number | undefined, cwd: string, log?: DebugWarnLog);
     getProvider(platform: LifecyclePlatform): IRepoLifecycleProvider;
     getMigrationSource(platform: LifecyclePlatform): IMigrationSource;
 }

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

@@ -1,17 +1,18 @@
-import { defaultExecutor, } from "../shared/command-executor.js";
+import { LifecycleError } from "../shared/errors.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;
+    cwd;
+    log;
+    constructor(executor, retries, cwd, log) {
+        this.executor = executor;
         this.retries = retries ?? 3;
+        this.cwd = cwd;
+        this.log = log;
     }
     getProvider(platform) {
         // Check cache first
@@ -26,10 +27,12 @@ export class RepoLifecycleFactory {
                 provider = new GitHubLifecycleProvider({
                     executor: this.executor,
                     retries: this.retries,
+                    cwd: this.cwd,
+                    log: this.log,
                 });
                 break;
             default:
-                throw new Error(`Platform '${platform}' not supported as target for lifecycle operations. ` +
+                throw new LifecycleError(`Platform '${platform}' not supported as target for lifecycle operations. ` +
                     `Currently supported: github`);
         }
         this.providers.set(platform, provider);
@@ -45,10 +48,10 @@ export class RepoLifecycleFactory {
         let source;
         switch (platform) {
             case "azure-devops":
-                source = new AdoMigrationSource(this.executor, this.retries);
+                source = new AdoMigrationSource(this.executor, this.retries, this.cwd);
                 break;
             default:
-                throw new Error(`Platform '${platform}' not supported as migration source. ` +
+                throw new LifecycleError(`Platform '${platform}' not supported as migration source. ` +
                     `Currently supported: azure-devops`);
         }
         this.sources.set(platform, source);

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

@@ -1,4 +1,6 @@
 import { type RepoInfo } from "../shared/repo-detector.js";
+import { type DebugInfoWarnLog } from "../shared/logger.js";
+import type { ICommandExecutor } from "../shared/command-executor.js";
 import type { RepoConfig } from "../config/types.js";
 import type { IRepoLifecycleManager, IRepoLifecycleFactory, LifecycleResult, LifecycleOptions, CreateRepoSettings } from "./types.js";
 /**
@@ -6,7 +8,8 @@ import type { IRepoLifecycleManager, IRepoLifecycleFactory, LifecycleResult, Lif
  */
 export declare class RepoLifecycleManager implements IRepoLifecycleManager {
     private readonly factory;
-    constructor(factory?: IRepoLifecycleFactory, retries?: number);
+    private readonly log?;
+    constructor(factory: IRepoLifecycleFactory | undefined, executor: ICommandExecutor, retries: number | undefined, cwd: string, log?: DebugInfoWarnLog);
     ensureRepo(repoConfig: RepoConfig, repoInfo: RepoInfo, options: LifecycleOptions, settings?: CreateRepoSettings): Promise<LifecycleResult>;
     private create;
     private fork;

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

@@ -1,16 +1,20 @@
 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 { safeCleanup } from "../shared/type-guards.js";
+import { LifecycleError } from "../shared/errors.js";
+import { NO_OP_DEBUG_LOG } 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);
+    log;
+    constructor(factory, executor, retries, cwd, log) {
+        this.factory =
+            factory ?? new RepoLifecycleFactory(executor, retries, cwd, log);
+        this.log = log;
     }
     async ensureRepo(repoConfig, repoInfo, options, settings) {
         let provider;
@@ -23,7 +27,7 @@ export class RepoLifecycleManager {
                 throw error;
             }
             // Platform doesn't support lifecycle operations yet - log and skip
-            logger.debug(`Lifecycle: skipping unsupported platform "${repoInfo.type}"`);
+            this.log?.debug(`Lifecycle: skipping unsupported platform "${repoInfo.type}"`);
             return { repoInfo, action: "existed" };
         }
         const { token } = options;
@@ -71,7 +75,7 @@ export class RepoLifecycleManager {
             };
         }
         if (!provider.fork) {
-            throw new Error(`Platform '${repoInfo.type}' does not support forking`);
+            throw new LifecycleError(`Platform '${repoInfo.type}' does not support forking`);
         }
         const upstreamInfo = parseGitUrl(repoConfig.upstream, {
             githubHosts: options.githubHosts,
@@ -110,7 +114,7 @@ export class RepoLifecycleManager {
             };
         }
         finally {
-            await safeCleanup(() => rm(sourceDir, { recursive: true, force: true }), `failed to remove ${sourceDir}`, logger);
+            await safeCleanup(() => rm(sourceDir, { recursive: true, force: true }), `failed to remove ${sourceDir}`, this.log ?? NO_OP_DEBUG_LOG);
         }
     }
     /**
@@ -127,6 +131,6 @@ export class RepoLifecycleManager {
             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`);
+        this.log?.info(`Repo ${repoInfo.owner}/${repoInfo.repo} not yet visible after ${timeoutMs}ms, proceeding`);
     }
 }

package/dist/lifecycle/types.d.ts

@@ -1,20 +1,11 @@
 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 {
     repoInfo: RepoInfo;
     action: "existed" | "created" | "forked" | "migrated";
     skipped?: boolean;
 }
-/**
- * Options for lifecycle operations.
- */
 export interface LifecycleOptions {
     dryRun: boolean;
     workDir: string;
@@ -70,9 +61,6 @@ export interface IMigrationSource {
      */
     cloneForMigration(repoInfo: RepoInfo, workDir: string): Promise<void>;
 }
-/**
- * Factory for getting providers by platform.
- */
 export interface IRepoLifecycleFactory {
     /**
      * Get lifecycle provider for a platform.
@@ -85,9 +73,6 @@ export interface IRepoLifecycleFactory {
      */
     getMigrationSource(platform: LifecyclePlatform): IMigrationSource;
 }
-/**
- * Manager that orchestrates lifecycle operations before sync.
- */
 export interface IRepoLifecycleManager {
     /**
      * Ensure repository exists, creating/forking/migrating if needed.

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

@@ -1,3 +1,4 @@
+import type { DebugLog } from "../shared/logger.js";
 export type MergeOutcome = "manual" | "auto" | "force" | "direct";
 export interface FileChanges {
     added: number;
@@ -17,7 +18,7 @@ export interface RulesetPlanDetail {
 }
 export interface RepoSettingsPlanDetail {
     property: string;
-    action: "add" | "change";
+    action: "create" | "update";
 }
 export interface LabelsPlanDetail {
     name: string;
@@ -45,10 +46,10 @@ export interface SummaryData {
     results: RepoResult[];
 }
 export declare function formatSummary(data: SummaryData): string;
-export declare function isGitHubActions(): boolean;
+export declare function shouldWriteSummary(summaryPath: string | undefined): boolean;
 /**
  * Append markdown content to GITHUB_STEP_SUMMARY.
- * No-op outside GitHub Actions.
+ * No-op if summaryPath is not provided.
  */
-export declare function writeGitHubStepSummary(markdown: string): void;
-export declare function writeSummary(data: SummaryData): void;
+export declare function writeGitHubStepSummary(markdown: string, summaryPath: string | undefined, log?: DebugLog): void;
+export declare function writeSummary(data: SummaryData, summaryPath: string | undefined): void;

package/dist/output/github-summary.js

@@ -1,4 +1,5 @@
 import { appendFileSync } from "node:fs";
+import { toErrorMessage } from "../shared/type-guards.js";
 function escapeMarkdown(text) {
     // Escape backslashes first, then pipes (order matters to prevent double-escaping)
     return text.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
@@ -15,14 +16,14 @@ function formatChangesColumn(result) {
     // For settings results, derive changes from plan details
     const parts = [];
     if (result.rulesetPlanDetails && result.rulesetPlanDetails.length > 0) {
-        parts.push(formatRulesetPlanSummary(result.rulesetPlanDetails));
+        parts.push(formatPlanSummary(result.rulesetPlanDetails));
     }
     if (result.repoSettingsPlanDetails &&
         result.repoSettingsPlanDetails.length > 0) {
-        parts.push(formatSettingsPlanSummary(result.repoSettingsPlanDetails));
+        parts.push(formatPlanSummary(result.repoSettingsPlanDetails));
     }
     if (result.labelsPlanDetails && result.labelsPlanDetails.length > 0) {
-        parts.push(formatLabelsPlanSummary(result.labelsPlanDetails));
+        parts.push(formatPlanSummary(result.labelsPlanDetails));
     }
     return parts.length > 0 ? parts.join("; ") : "-";
 }
@@ -80,52 +81,30 @@ function formatRulesetProperties(detail) {
     }
     return "-";
 }
-function formatRulesetPlanSummary(details) {
-    const creates = details.filter((d) => d.action === "create").length;
-    const updates = details.filter((d) => d.action === "update").length;
-    const deletes = details.filter((d) => d.action === "delete").length;
+function formatPlanSummary(details) {
+    const counts = {};
+    for (const d of details) {
+        counts[d.action] = (counts[d.action] ?? 0) + 1;
+    }
     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`);
+    if (counts.create)
+        parts.push(`${counts.create} to create`);
+    if (counts.update)
+        parts.push(`${counts.update} to update`);
+    if (counts.delete)
+        parts.push(`${counts.delete} to delete`);
     return parts.join(", ") || "no changes";
 }
 function formatSettingsAction(action) {
     switch (action) {
-        case "add":
-            return "+ Add";
-        case "change":
-            return "~ Change";
+        case "create":
+            return "+ Create";
+        case "update":
+            return "~ Update";
         default:
             return action;
     }
 }
-function formatSettingsPlanSummary(details) {
-    const adds = details.filter((d) => d.action === "add").length;
-    const changes = details.filter((d) => d.action === "change").length;
-    const parts = [];
-    if (adds > 0)
-        parts.push(`${adds} to add`);
-    if (changes > 0)
-        parts.push(`${changes} to change`);
-    return parts.join(", ") || "no changes";
-}
-function formatLabelsPlanSummary(details) {
-    const creates = details.filter((d) => d.action === "create").length;
-    const updates = details.filter((d) => d.action === "update").length;
-    const deletes = details.filter((d) => d.action === "delete").length;
-    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`);
-    return parts.join(", ") || "no changes";
-}
 export function formatSummary(data) {
     const lines = [];
     // Header
@@ -168,7 +147,7 @@ export function formatSummary(data) {
             if (result.rulesetPlanDetails && result.rulesetPlanDetails.length > 0) {
                 lines.push("");
                 lines.push("<details>");
-                lines.push(`<summary>${result.repoName} — Rulesets: ${formatRulesetPlanSummary(result.rulesetPlanDetails)}</summary>`);
+                lines.push(`<summary>${result.repoName} — Rulesets: ${formatPlanSummary(result.rulesetPlanDetails)}</summary>`);
                 lines.push("");
                 lines.push("| Ruleset | Action | Properties |");
                 lines.push("|---------|--------|------------|");
@@ -182,7 +161,7 @@ export function formatSummary(data) {
                 result.repoSettingsPlanDetails.length > 0) {
                 lines.push("");
                 lines.push("<details>");
-                lines.push(`<summary>${result.repoName} — Repo Settings: ${formatSettingsPlanSummary(result.repoSettingsPlanDetails)}</summary>`);
+                lines.push(`<summary>${result.repoName} — Repo Settings: ${formatPlanSummary(result.repoSettingsPlanDetails)}</summary>`);
                 lines.push("");
                 lines.push("| Setting | Action |");
                 lines.push("|---------|--------|");
@@ -195,7 +174,7 @@ export function formatSummary(data) {
             if (result.labelsPlanDetails && result.labelsPlanDetails.length > 0) {
                 lines.push("");
                 lines.push("<details>");
-                lines.push(`<summary>${result.repoName} — Labels: ${formatLabelsPlanSummary(result.labelsPlanDetails)}</summary>`);
+                lines.push(`<summary>${result.repoName} — Labels: ${formatPlanSummary(result.labelsPlanDetails)}</summary>`);
                 lines.push("");
                 lines.push("| Label | Action |");
                 lines.push("|-------|--------|");
@@ -221,20 +200,25 @@ export function formatSummary(data) {
     }
     return lines.join("\n");
 }
-export function isGitHubActions() {
-    return !!process.env.GITHUB_STEP_SUMMARY;
+export function shouldWriteSummary(summaryPath) {
+    return !!summaryPath;
 }
 /**
  * Append markdown content to GITHUB_STEP_SUMMARY.
- * No-op outside GitHub Actions.
+ * No-op if summaryPath is not provided.
  */
-export function writeGitHubStepSummary(markdown) {
-    const summaryPath = process.env.GITHUB_STEP_SUMMARY;
-    if (!summaryPath)
+export function writeGitHubStepSummary(markdown, summaryPath, log) {
+    const path = summaryPath;
+    if (!path)
         return;
-    appendFileSync(summaryPath, "\n" + markdown + "\n");
+    try {
+        appendFileSync(path, "\n" + markdown + "\n");
+    }
+    catch (error) {
+        log?.debug(`Failed to write GitHub step summary: ${toErrorMessage(error)}`);
+    }
 }
-export function writeSummary(data) {
+export function writeSummary(data, summaryPath) {
     const markdown = formatSummary(data);
-    writeGitHubStepSummary(markdown);
+    writeGitHubStepSummary(markdown, summaryPath);
 }

package/dist/output/index.d.ts

@@ -1,5 +1,5 @@
-export { formatSyncReportCLI, formatSyncReportMarkdown, writeSyncReportSummary, type SyncReport, type RepoFileChanges, type FileChange, } from "./sync-report.js";
+export { formatSyncReportCLI, formatSyncReportMarkdown, writeSyncReportSummary, type SyncReport, type RepoFileChanges, type ReportFileChange, } from "./sync-report.js";
 export { formatSettingsReportCLI, formatSettingsReportMarkdown, writeSettingsReportSummary, type SettingsReport, type RepoChanges, type RulesetChange, type SettingChange, } from "./settings-report.js";
 export { formatUnifiedSummaryMarkdown, writeUnifiedSummary, } from "./unified-summary.js";
-export { formatSummary, isGitHubActions, writeSummary, type MergeOutcome, type FileChanges, type RulesetPlanDetail, type RepoSettingsPlanDetail, type RepoResult, type SummaryData, } from "./github-summary.js";
+export { formatSummary, shouldWriteSummary, writeSummary, type MergeOutcome, type FileChanges, type RulesetPlanDetail, type RepoSettingsPlanDetail, type RepoResult, type SummaryData, } from "./github-summary.js";
 export { getMergeOutcome, toFileChanges, buildRepoResult, buildErrorResult, } from "./summary-utils.js";

package/dist/output/index.js

@@ -5,6 +5,6 @@ export { formatSettingsReportCLI, formatSettingsReportMarkdown, writeSettingsRep
 // Unified summary (lifecycle + sync + settings in one diff block)
 export { formatUnifiedSummaryMarkdown, writeUnifiedSummary, } from "./unified-summary.js";
 // GitHub Actions summary
-export { formatSummary, isGitHubActions, writeSummary, } from "./github-summary.js";
+export { formatSummary, shouldWriteSummary, writeSummary, } from "./github-summary.js";
 // Summary utilities
 export { getMergeOutcome, toFileChanges, buildRepoResult, buildErrorResult, } from "./summary-utils.js";

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

@@ -17,21 +17,11 @@ export interface LifecycleAction {
         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;
+export declare function buildLifecycleReport(results: LifecycleAction[]): 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;
+export declare function writeLifecycleReportSummary(report: LifecycleReport, dryRun: boolean, summaryPath: string | undefined): void;