@fern-api/replay 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -434,6 +434,72 @@ interface ReplayOptions {
     /** SHA of the base branch HEAD before replay runs. Stored in lockfile for squash merge recovery. */
     baseBranchHead?: string;
 }
+/**
+ * Options honored by `applyPreparedReplay()`. `cliVersion`, `generatorVersions`,
+ * `baseBranchHead`, `dryRun`, and `skipApplication` were all captured in phase 1
+ * and re-supplying them here is meaningless.
+ */
+interface ApplyOptions {
+    /** Write files and stage changes, but don't commit */
+    stageOnly?: boolean;
+}
+/**
+ * Opaque handle returned by `prepareReplay()`. Consumed by `applyPreparedReplay()`
+ * to complete the run.
+ *
+ * Contract for consumers (e.g., generator-cli pipeline inserting AutoVersionStep):
+ *
+ * - Between `prepareReplay` and `applyPreparedReplay`, HEAD is at the new
+ *   `[fern-generated]` commit (unless `_prepared.terminal === true`, e.g. dry-run).
+ * - Consumers MAY land additional commits on HEAD between phases. `applyPatches`
+ *   runs against current HEAD at phase-2 call time, so mid-phase commits are
+ *   respected. `rebasePatches` uses `currentGenerationSha` (the pure `[fern-generated]`
+ *   SHA), NOT HEAD — mid-phase commits do not retarget patches' `base_generation`.
+ * - The service instance is single-use across the phase boundary: do not call
+ *   other service methods (`syncFromDivergentMerge`, another `prepareReplay`, etc.)
+ *   between phases. In-memory lockfile and warning state would be corrupted.
+ * - If the caller's mid-phase work throws or `applyPreparedReplay` is never called,
+ *   the repo is left with the new `[fern-generated]` commit but a stale lockfile.
+ *   Consumers MUST either (a) still call `applyPreparedReplay` so the lockfile
+ *   advances, or (b) reset HEAD to `previousGenerationSha` and surface the failure.
+ *
+ * To decide whether to run autoversion between phases, use:
+ *     prep.previousGenerationSha != null && prep.flow !== "skip-application"
+ */
+interface ReplayPreparation {
+    flow: "first-generation" | "no-patches" | "normal-regeneration" | "skip-application";
+    /** lockfile.current_generation from BEFORE this run; null iff no prior generation exists */
+    previousGenerationSha: string | null;
+    /** SHA of the new [fern-generated] commit created by prepareReplay (or HEAD for dry-run terminals) */
+    currentGenerationSha: string;
+    /** options.baseBranchHead passed through */
+    baseBranchHead: string | null;
+    /** @internal Opaque state consumed by applyPreparedReplay */
+    readonly _prepared: InternalPreparationState;
+}
+/** @internal */
+interface InternalPreparationState {
+    flow: "first-generation" | "no-patches" | "normal-regeneration" | "skip-application";
+    /** true → applyPreparedReplay returns preparedReport without disk/git work (dry-run path) */
+    terminal: boolean;
+    preparedReport?: ReplayReport;
+    /** post-preGenRebase, post-detection, post-absorption (references, not copies) */
+    patchesToApply: StoredPatch[];
+    /** subset of patchesToApply that were freshly detected this cycle (vs already in the lockfile) */
+    newPatchIds: Set<string>;
+    preRebaseCounts?: {
+        conflictResolved: number;
+        conflictAbsorbed: number;
+        contentRefreshed: number;
+    };
+    /** detector warnings snapshotted at end of phase 1 */
+    detectorWarnings: string[];
+    revertedCount: number;
+    /** [fern-generated] SHA; passed to rebasePatches as currentGenSha */
+    genSha: string;
+    /** cached phase-1 options for constructing the final ReplayReport in phase 2 */
+    optionsSnapshot?: ReplayOptions;
+}
 declare class ReplayService {
     private git;
     private detector;
@@ -465,6 +531,33 @@ declare class ReplayService {
      */
     getLastResults(): ReadonlyArray<ReplayResult>;
     constructor(outputDir: string, _config: ReplayConfig);
+    /**
+     * Phase 1 of the two-phase replay flow. Runs preGenerationRebase (when applicable),
+     * detects new patches, and creates the `[fern-generated]` commit. Leaves HEAD at
+     * the generation commit (or unchanged for dry-run).
+     *
+     * Does NOT apply patches — the returned handle must be passed to
+     * `applyPreparedReplay()` to complete the run. No disk writes to the lockfile
+     * happen here; lockfile persistence is deferred to phase 2.
+     *
+     * Callers may land additional commits on HEAD between `prepareReplay` and
+     * `applyPreparedReplay` (e.g., `[fern-autoversion]`).
+     */
+    prepareReplay(options?: ReplayOptions): Promise<ReplayPreparation>;
+    /**
+     * Phase 2 of the two-phase replay flow. Applies patches, rebases them against
+     * the generation, saves the lockfile, and commits `[fern-replay]` (or stages
+     * under `stageOnly`). Operates on HEAD at call time — mid-phase commits are
+     * respected.
+     *
+     * For terminal handles (dry-run, first-gen has no patch work, skip-app does
+     * its own post-commit logic), this returns the precomputed report.
+     */
+    applyPreparedReplay(prep: ReplayPreparation, options?: ApplyOptions): Promise<ReplayReport>;
+    /**
+     * Backwards-compatible atomic entry point. Composes `prepareReplay` + `applyPreparedReplay`.
+     * Behavior is byte-identical to the pre-split implementation for all existing callers.
+     */
     runReplay(options?: ReplayOptions): Promise<ReplayReport>;
     /**
      * Sync the lockfile after a divergent PR was squash-merged.
@@ -482,15 +575,22 @@ declare class ReplayService {
         baseBranchHead?: string;
     }): Promise<void>;
     private determineFlow;
-    private handleFirstGeneration;
+    private firstGenerationReport;
+    private _prepareFirstGeneration;
+    private _applyFirstGeneration;
     /**
-     * Skip-application mode: commit the generation and update the lockfile
-     * but don't detect or apply patches. Sets a marker so the next normal
-     * run skips revert detection in preGenerationRebase().
+     * Skip-application mode phase 1: commit the generation and update the
+     * in-memory lockfile, but don't detect or apply patches. Sets a marker
+     * so the next normal run skips revert detection in preGenerationRebase().
+     *
+     * Disk save is deferred to `_applySkipApplication`.
      */
-    private handleSkipApplication;
-    private handleNoPatchesRegeneration;
-    private handleNormalRegeneration;
+    private _prepareSkipApplication;
+    private _applySkipApplication;
+    private _prepareNoPatchesRegeneration;
+    private _applyNoPatchesRegeneration;
+    private _prepareNormalRegeneration;
+    private _applyNormalRegeneration;
     /**
      * Rebase cleanly applied patches so they are relative to the current generation.
      * This prevents recurring conflicts on subsequent regenerations.
@@ -761,4 +861,4 @@ interface StatusGeneration {
 }
 declare function status(outputDir: string): StatusResult;
 
-export { type BootstrapOptions, type BootstrapResult, CREDENTIAL_PATTERNS, type CommitInfo, type CommitOptions, type ConflictDetail, type ConflictMetadata, type ConflictReason, type ConflictRegion, type CredentialPattern, type CustomizationsConfig, type DetectionResult, type DiffStat, FERN_BOT_EMAIL, FERN_BOT_LOGIN, FERN_BOT_NAME, FernignoreMigrator, type FileResult, type ForgetOptions, type ForgetResult, type GenerationLock, type GenerationRecord, GitClient, LockfileManager, LockfileNotFoundError, type MatchedPatch, type MergeResult, type MigrationAnalysis, type MigrationResult, type MoveDeclaration, ReplayApplicator, ReplayCommitter, type ReplayConfig, ReplayDetector, type ReplayOptions, type ReplayReport, type ReplayResult, ReplayService, type ResetOptions, type ResetResult, type ResolveOptions, type ResolveResult, SENSITIVE_FILE_PATTERNS, type StatusGeneration, type StatusPatch, type StatusResult, type StoredPatch, type UnresolvedPatchInfo, bootstrap, forget, isGenerationCommit, isReplayCommit, isRevertCommit, isSensitiveFile, parseRevertedMessage, parseRevertedSha, reset, resolve, scanForCredentials, status, threeWayMerge };
+export { type ApplyOptions, type BootstrapOptions, type BootstrapResult, CREDENTIAL_PATTERNS, type CommitInfo, type CommitOptions, type ConflictDetail, type ConflictMetadata, type ConflictReason, type ConflictRegion, type CredentialPattern, type CustomizationsConfig, type DetectionResult, type DiffStat, FERN_BOT_EMAIL, FERN_BOT_LOGIN, FERN_BOT_NAME, FernignoreMigrator, type FileResult, type ForgetOptions, type ForgetResult, type GenerationLock, type GenerationRecord, GitClient, LockfileManager, LockfileNotFoundError, type MatchedPatch, type MergeResult, type MigrationAnalysis, type MigrationResult, type MoveDeclaration, ReplayApplicator, ReplayCommitter, type ReplayConfig, ReplayDetector, type ReplayOptions, type ReplayPreparation, type ReplayReport, type ReplayResult, ReplayService, type ResetOptions, type ResetResult, type ResolveOptions, type ResolveResult, SENSITIVE_FILE_PATTERNS, type StatusGeneration, type StatusPatch, type StatusResult, type StoredPatch, type UnresolvedPatchInfo, bootstrap, forget, isGenerationCommit, isReplayCommit, isRevertCommit, isSensitiveFile, parseRevertedMessage, parseRevertedSha, reset, resolve, scanForCredentials, status, threeWayMerge };

package/dist/index.d.ts

@@ -434,6 +434,72 @@ interface ReplayOptions {
     /** SHA of the base branch HEAD before replay runs. Stored in lockfile for squash merge recovery. */
     baseBranchHead?: string;
 }
+/**
+ * Options honored by `applyPreparedReplay()`. `cliVersion`, `generatorVersions`,
+ * `baseBranchHead`, `dryRun`, and `skipApplication` were all captured in phase 1
+ * and re-supplying them here is meaningless.
+ */
+interface ApplyOptions {
+    /** Write files and stage changes, but don't commit */
+    stageOnly?: boolean;
+}
+/**
+ * Opaque handle returned by `prepareReplay()`. Consumed by `applyPreparedReplay()`
+ * to complete the run.
+ *
+ * Contract for consumers (e.g., generator-cli pipeline inserting AutoVersionStep):
+ *
+ * - Between `prepareReplay` and `applyPreparedReplay`, HEAD is at the new
+ *   `[fern-generated]` commit (unless `_prepared.terminal === true`, e.g. dry-run).
+ * - Consumers MAY land additional commits on HEAD between phases. `applyPatches`
+ *   runs against current HEAD at phase-2 call time, so mid-phase commits are
+ *   respected. `rebasePatches` uses `currentGenerationSha` (the pure `[fern-generated]`
+ *   SHA), NOT HEAD — mid-phase commits do not retarget patches' `base_generation`.
+ * - The service instance is single-use across the phase boundary: do not call
+ *   other service methods (`syncFromDivergentMerge`, another `prepareReplay`, etc.)
+ *   between phases. In-memory lockfile and warning state would be corrupted.
+ * - If the caller's mid-phase work throws or `applyPreparedReplay` is never called,
+ *   the repo is left with the new `[fern-generated]` commit but a stale lockfile.
+ *   Consumers MUST either (a) still call `applyPreparedReplay` so the lockfile
+ *   advances, or (b) reset HEAD to `previousGenerationSha` and surface the failure.
+ *
+ * To decide whether to run autoversion between phases, use:
+ *     prep.previousGenerationSha != null && prep.flow !== "skip-application"
+ */
+interface ReplayPreparation {
+    flow: "first-generation" | "no-patches" | "normal-regeneration" | "skip-application";
+    /** lockfile.current_generation from BEFORE this run; null iff no prior generation exists */
+    previousGenerationSha: string | null;
+    /** SHA of the new [fern-generated] commit created by prepareReplay (or HEAD for dry-run terminals) */
+    currentGenerationSha: string;
+    /** options.baseBranchHead passed through */
+    baseBranchHead: string | null;
+    /** @internal Opaque state consumed by applyPreparedReplay */
+    readonly _prepared: InternalPreparationState;
+}
+/** @internal */
+interface InternalPreparationState {
+    flow: "first-generation" | "no-patches" | "normal-regeneration" | "skip-application";
+    /** true → applyPreparedReplay returns preparedReport without disk/git work (dry-run path) */
+    terminal: boolean;
+    preparedReport?: ReplayReport;
+    /** post-preGenRebase, post-detection, post-absorption (references, not copies) */
+    patchesToApply: StoredPatch[];
+    /** subset of patchesToApply that were freshly detected this cycle (vs already in the lockfile) */
+    newPatchIds: Set<string>;
+    preRebaseCounts?: {
+        conflictResolved: number;
+        conflictAbsorbed: number;
+        contentRefreshed: number;
+    };
+    /** detector warnings snapshotted at end of phase 1 */
+    detectorWarnings: string[];
+    revertedCount: number;
+    /** [fern-generated] SHA; passed to rebasePatches as currentGenSha */
+    genSha: string;
+    /** cached phase-1 options for constructing the final ReplayReport in phase 2 */
+    optionsSnapshot?: ReplayOptions;
+}
 declare class ReplayService {
     private git;
     private detector;
@@ -465,6 +531,33 @@ declare class ReplayService {
      */
     getLastResults(): ReadonlyArray<ReplayResult>;
     constructor(outputDir: string, _config: ReplayConfig);
+    /**
+     * Phase 1 of the two-phase replay flow. Runs preGenerationRebase (when applicable),
+     * detects new patches, and creates the `[fern-generated]` commit. Leaves HEAD at
+     * the generation commit (or unchanged for dry-run).
+     *
+     * Does NOT apply patches — the returned handle must be passed to
+     * `applyPreparedReplay()` to complete the run. No disk writes to the lockfile
+     * happen here; lockfile persistence is deferred to phase 2.
+     *
+     * Callers may land additional commits on HEAD between `prepareReplay` and
+     * `applyPreparedReplay` (e.g., `[fern-autoversion]`).
+     */
+    prepareReplay(options?: ReplayOptions): Promise<ReplayPreparation>;
+    /**
+     * Phase 2 of the two-phase replay flow. Applies patches, rebases them against
+     * the generation, saves the lockfile, and commits `[fern-replay]` (or stages
+     * under `stageOnly`). Operates on HEAD at call time — mid-phase commits are
+     * respected.
+     *
+     * For terminal handles (dry-run, first-gen has no patch work, skip-app does
+     * its own post-commit logic), this returns the precomputed report.
+     */
+    applyPreparedReplay(prep: ReplayPreparation, options?: ApplyOptions): Promise<ReplayReport>;
+    /**
+     * Backwards-compatible atomic entry point. Composes `prepareReplay` + `applyPreparedReplay`.
+     * Behavior is byte-identical to the pre-split implementation for all existing callers.
+     */
     runReplay(options?: ReplayOptions): Promise<ReplayReport>;
     /**
      * Sync the lockfile after a divergent PR was squash-merged.
@@ -482,15 +575,22 @@ declare class ReplayService {
         baseBranchHead?: string;
     }): Promise<void>;
     private determineFlow;
-    private handleFirstGeneration;
+    private firstGenerationReport;
+    private _prepareFirstGeneration;
+    private _applyFirstGeneration;
     /**
-     * Skip-application mode: commit the generation and update the lockfile
-     * but don't detect or apply patches. Sets a marker so the next normal
-     * run skips revert detection in preGenerationRebase().
+     * Skip-application mode phase 1: commit the generation and update the
+     * in-memory lockfile, but don't detect or apply patches. Sets a marker
+     * so the next normal run skips revert detection in preGenerationRebase().
+     *
+     * Disk save is deferred to `_applySkipApplication`.
      */
-    private handleSkipApplication;
-    private handleNoPatchesRegeneration;
-    private handleNormalRegeneration;
+    private _prepareSkipApplication;
+    private _applySkipApplication;
+    private _prepareNoPatchesRegeneration;
+    private _applyNoPatchesRegeneration;
+    private _prepareNormalRegeneration;
+    private _applyNormalRegeneration;
     /**
      * Rebase cleanly applied patches so they are relative to the current generation.
      * This prevents recurring conflicts on subsequent regenerations.
@@ -761,4 +861,4 @@ interface StatusGeneration {
 }
 declare function status(outputDir: string): StatusResult;
 
-export { type BootstrapOptions, type BootstrapResult, CREDENTIAL_PATTERNS, type CommitInfo, type CommitOptions, type ConflictDetail, type ConflictMetadata, type ConflictReason, type ConflictRegion, type CredentialPattern, type CustomizationsConfig, type DetectionResult, type DiffStat, FERN_BOT_EMAIL, FERN_BOT_LOGIN, FERN_BOT_NAME, FernignoreMigrator, type FileResult, type ForgetOptions, type ForgetResult, type GenerationLock, type GenerationRecord, GitClient, LockfileManager, LockfileNotFoundError, type MatchedPatch, type MergeResult, type MigrationAnalysis, type MigrationResult, type MoveDeclaration, ReplayApplicator, ReplayCommitter, type ReplayConfig, ReplayDetector, type ReplayOptions, type ReplayReport, type ReplayResult, ReplayService, type ResetOptions, type ResetResult, type ResolveOptions, type ResolveResult, SENSITIVE_FILE_PATTERNS, type StatusGeneration, type StatusPatch, type StatusResult, type StoredPatch, type UnresolvedPatchInfo, bootstrap, forget, isGenerationCommit, isReplayCommit, isRevertCommit, isSensitiveFile, parseRevertedMessage, parseRevertedSha, reset, resolve, scanForCredentials, status, threeWayMerge };
+export { type ApplyOptions, type BootstrapOptions, type BootstrapResult, CREDENTIAL_PATTERNS, type CommitInfo, type CommitOptions, type ConflictDetail, type ConflictMetadata, type ConflictReason, type ConflictRegion, type CredentialPattern, type CustomizationsConfig, type DetectionResult, type DiffStat, FERN_BOT_EMAIL, FERN_BOT_LOGIN, FERN_BOT_NAME, FernignoreMigrator, type FileResult, type ForgetOptions, type ForgetResult, type GenerationLock, type GenerationRecord, GitClient, LockfileManager, LockfileNotFoundError, type MatchedPatch, type MergeResult, type MigrationAnalysis, type MigrationResult, type MoveDeclaration, ReplayApplicator, ReplayCommitter, type ReplayConfig, ReplayDetector, type ReplayOptions, type ReplayPreparation, type ReplayReport, type ReplayResult, ReplayService, type ResetOptions, type ResetResult, type ResolveOptions, type ResolveResult, SENSITIVE_FILE_PATTERNS, type StatusGeneration, type StatusPatch, type StatusResult, type StoredPatch, type UnresolvedPatchInfo, bootstrap, forget, isGenerationCommit, isReplayCommit, isRevertCommit, isSensitiveFile, parseRevertedMessage, parseRevertedSha, reset, resolve, scanForCredentials, status, threeWayMerge };