@fern-api/generator-cli 0.9.11 → 0.9.14

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import { ForgetOptions, ForgetResult, BootstrapResult, ResolveResult, ReplayReport, StatusResult } from '@fern-api/replay';
+import { ReplayService, ReplayPreparation, ReplayReport, ForgetOptions, ForgetResult, BootstrapResult, ResolveResult, StatusResult } from '@fern-api/replay';
 export { ConflictDetail, DiffStat, ForgetOptions, ForgetResult, MatchedPatch, ReplayReport, ResolveResult, StatusGeneration, StatusPatch, StatusResult } from '@fern-api/replay';
 import fs from 'fs';
 
@@ -496,6 +496,65 @@ interface PipelineLogger {
  */
 declare const consolePipelineLogger: PipelineLogger;
 
+interface ReplayRunParams {
+    outputDir: string;
+    cliVersion?: string;
+    generatorVersions?: Record<string, string>;
+    /** Don't commit, just stage changes. Default: false */
+    stageOnly?: boolean;
+    /** Generator name for namespaced tag lookup (e.g. "fernapi/fern-typescript-node-sdk") */
+    generatorName?: string;
+    /** Commit generation + update lockfile, skip patch detection/application */
+    skipApplication?: boolean;
+    /** Optional logger for diagnostic output */
+    logger?: PipelineLogger;
+}
+interface ReplayRunResult {
+    /** null if replay wasn't initialized (no lockfile) */
+    report: ReplayReport | null;
+    /** Whether .fernignore was updated */
+    fernignoreUpdated: boolean;
+    /** SHA of the [fern-generated] commit before this replay run (null if first generation or unreadable) */
+    previousGenerationSha: string | null;
+    /** SHA of the [fern-generated] commit created by this replay run (null if replay didn't run or unreadable) */
+    currentGenerationSha: string | null;
+    /** SHA of main's HEAD before replay ran. Always on main's lineage, stable after squash merges. */
+    baseBranchHead: string | null;
+}
+/**
+ * Opaque handle returned by `replayPrepare()` and consumed by `replayApply()`.
+ *
+ * Between prepare and apply, HEAD is at the new `[fern-generated]` commit (or unchanged
+ * for dry-run / skip-application terminals). Consumers MAY land additional commits on
+ * HEAD (e.g. `[fern-autoversion]`) — apply will run patches on top of current HEAD at
+ * call time while rebasing stored patches against the pure `[fern-generated]` tree.
+ *
+ * If apply is never reached, the working tree has the new `[fern-generated]` commit
+ * but the lockfile is stale. Callers MUST either call apply (which advances the
+ * lockfile) or reset HEAD to `previousGenerationSha`.
+ */
+interface PreparedReplay {
+    /** @internal Service instance carrying in-memory state across phases. */
+    _service: ReplayService;
+    /** @internal Preparation state handed to the service's apply phase. */
+    _preparation: ReplayPreparation;
+    /** Working tree / git repo the replay operates on. */
+    outputDir: string;
+    /** Flow selected by the service during prepare. */
+    flow: ReplayPreparation["flow"];
+    /** SHA of the `[fern-generated]` commit before this run; null if no prior generation. */
+    previousGenerationSha: string | null;
+    /** SHA of the new `[fern-generated]` commit created by prepare (or prior HEAD for dry-run terminals). */
+    currentGenerationSha: string;
+    /** SHA of main's HEAD captured before prepare mutated anything. */
+    baseBranchHead: string | null;
+}
+/**
+ * Backwards-compatible atomic entry point. Composes `replayPrepare` +
+ * `replayApply` with byte-identical behavior for existing callers.
+ */
+declare function replayRun(params: ReplayRunParams): Promise<ReplayRunResult>;
+
 interface PipelineConfig {
     outputDir: string;
     replay?: ReplayStepConfig;
@@ -508,11 +567,29 @@ interface PipelineConfig {
 }
 interface PipelineContext {
     previousStepResults: {
+        generationCommit?: GenerationCommitStepResult;
         replay?: ReplayStepResult;
         autoVersion?: AutoVersionStepResult;
         fernignore?: FernignoreStepResult;
     };
 }
+/**
+ * Result of running replayPrepare(). Holds the opaque PreparedReplay handle that
+ * downstream steps (AutoVersionStep, ReplayStep) consume.
+ *
+ * `preparedReplay` is null when replay isn't initialized for this repo (no
+ * lockfile) or when prepare failed — the pipeline proceeds without replay in
+ * both cases.
+ */
+interface GenerationCommitStepResult extends StepResult {
+    /** Opaque handle consumed by ReplayStep's apply phase. Imported at the import site to avoid circular deps. */
+    preparedReplay?: PreparedReplay | null;
+    previousGenerationSha?: string;
+    currentGenerationSha?: string;
+    baseBranchHead?: string;
+    /** Flow selected by the replay service during prepare. */
+    flow?: "first-generation" | "no-patches" | "normal-regeneration" | "skip-application";
+}
 interface ReplayStepConfig {
     enabled: boolean;
     stageOnly?: boolean;
@@ -524,10 +601,29 @@ interface AutoVersionStepConfig {
     language: string;
     /** Existing changelog content passed to the AI for context. */
     priorChangelog?: string;
-    /** Fallback version when no prior generation exists (first run). */
+    /** Fallback version when no prior generation exists (first run). Defaults to "0.0.1" (or "v0.0.1" for Go). */
     baseVersion?: string;
-    /** Fern token used to authorize the FAI (AnalyzeSdkDiff) call. */
-    fernToken: string;
+    /**
+     * BAML AI service configuration (provider + model). Required when `enabled: true` — without it,
+     * AnalyzeSdkDiff calls will fail and the step will fall back to a PATCH bump.
+     * Shape matches `generatorsYml.AiServicesSchema` from @fern-api/configuration; typed structurally
+     * to avoid pulling the configuration package into generator-cli's dep graph.
+     */
+    ai?: AutoVersionAiConfig;
+    /** Optional Fern API token passed through to BAML client configuration if needed by the provider. */
+    fernToken?: string;
+    /** Spec repository commit message included as additional AI context. */
+    specCommitMessage?: string;
+    /** When true, strips "🌿 Generated with Fern" trailers from commit messages (whitelabel customers). */
+    isWhitelabel?: boolean;
+}
+/**
+ * Minimal shape for the BAML AI service configuration. Structural equivalent of
+ * `generatorsYml.AiServicesSchema` from @fern-api/configuration.
+ */
+interface AutoVersionAiConfig {
+    provider: string;
+    model: string;
 }
 interface FernignoreStepConfig {
     enabled: boolean;
@@ -584,6 +680,7 @@ interface GithubStepConfig {
 interface PipelineResult {
     success: boolean;
     steps: {
+        generationCommit?: GenerationCommitStepResult;
         replay?: ReplayStepResult;
         autoVersion?: AutoVersionStepResult;
         fernignore?: FernignoreStepResult;
@@ -734,33 +831,6 @@ interface ReplayResolveParams {
 }
 declare function replayResolve(params: ReplayResolveParams): Promise<ResolveResult>;
 
-interface ReplayRunParams {
-    outputDir: string;
-    cliVersion?: string;
-    generatorVersions?: Record<string, string>;
-    /** Don't commit, just stage changes. Default: false */
-    stageOnly?: boolean;
-    /** Generator name for namespaced tag lookup (e.g. "fernapi/fern-typescript-node-sdk") */
-    generatorName?: string;
-    /** Commit generation + update lockfile, skip patch detection/application */
-    skipApplication?: boolean;
-    /** Optional logger for diagnostic output */
-    logger?: PipelineLogger;
-}
-interface ReplayRunResult {
-    /** null if replay wasn't initialized (no lockfile) */
-    report: ReplayReport | null;
-    /** Whether .fernignore was updated */
-    fernignoreUpdated: boolean;
-    /** SHA of the [fern-generated] commit before this replay run (null if first generation or unreadable) */
-    previousGenerationSha: string | null;
-    /** SHA of the [fern-generated] commit created by this replay run (null if replay didn't run or unreadable) */
-    currentGenerationSha: string | null;
-    /** SHA of main's HEAD before replay ran. Always on main's lineage, stable after squash merges. */
-    baseBranchHead: string | null;
-}
-declare function replayRun(params: ReplayRunParams): Promise<ReplayRunResult>;
-
 interface ReplayStatusParams {
     /** Directory containing the SDK (where .fern/replay.lock lives) */
     outputDir: string;