@fern-api/generator-cli 0.9.10 → 0.9.13

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,9 +496,69 @@ 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;
+    autoVersion?: AutoVersionStepConfig;
     fernignore?: FernignoreStepConfig;
     github?: GithubStepConfig;
     cliVersion?: string;
@@ -507,15 +567,64 @@ 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;
     skipApplication?: boolean;
 }
+interface AutoVersionStepConfig {
+    enabled: boolean;
+    /** Generator language: typescript | python | java | go | ruby | csharp | php | swift | rust | kotlin */
+    language: string;
+    /** Existing changelog content passed to the AI for context. */
+    priorChangelog?: string;
+    /** Fallback version when no prior generation exists (first run). Defaults to "0.0.1" (or "v0.0.1" for Go). */
+    baseVersion?: 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;
     customContents?: string;
@@ -555,8 +664,10 @@ interface GithubStepConfig {
         previousGenerationSha: string;
         currentGenerationSha: string;
     };
-    /** When true: separate PRs per generation, no-diff skip, automerge support, run_id in body */
+    /** When true: separate PRs per generation, automerge support, run_id in body */
     automationMode?: boolean;
+    /** When true: skip opening a PR / pushing when the generated output has no diff from the base branch. */
+    skipIfNoDiff?: boolean;
     /** Enable GitHub automerge on the PR (only effective when automationMode && !hasBreakingChanges) */
     autoMerge?: boolean;
     /** Pre-computed: version bump is MAJOR (from --version AUTO AI analysis) */
@@ -569,7 +680,9 @@ interface GithubStepConfig {
 interface PipelineResult {
     success: boolean;
     steps: {
+        generationCommit?: GenerationCommitStepResult;
         replay?: ReplayStepResult;
+        autoVersion?: AutoVersionStepResult;
         fernignore?: FernignoreStepResult;
         github?: GithubStepResult;
     };
@@ -602,6 +715,24 @@ interface ReplayStepResult extends StepResult {
 interface FernignoreStepResult extends StepResult {
     pathsPreserved?: string[];
 }
+interface AutoVersionStepResult extends StepResult {
+    /** The new version to use (e.g. "1.2.3"). Field name matches fiddle's Java AutoVersionResult DTO. */
+    version?: string;
+    /** Commit subject for the `[fern-autoversion]` commit. */
+    commitMessage?: string;
+    /** User-facing changelog entry appended to changelog.md. */
+    changelogEntry?: string;
+    /** Prior SDK version before this change (e.g. "1.2.2"). */
+    previousVersion?: string;
+    /** The version bump level determined by FAI. */
+    versionBump?: "MAJOR" | "MINOR" | "PATCH" | "NO_CHANGE";
+    /** Structured PR description with Before/After code fences for breaking changes. */
+    prDescription?: string;
+    /** One-sentence justification for WHY the version bump was chosen. */
+    versionBumpReason?: string;
+    /** SHA of the `[fern-autoversion]` commit once it's been made. TS-only; no fiddle counterpart. */
+    commitSha?: string;
+}
 interface GithubStepResult extends StepResult {
     commitSha?: string;
     branchUrl?: string;
@@ -700,37 +831,54 @@ 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;
 }
 declare function replayStatus(params: ReplayStatusParams): StatusResult;
 
-export { type BootstrapLogEntry, type GenerateReadmeParams, type GenerateReadmeToStreamParams, type GenerateReferenceParams, type GenerateReferenceToStreamParams, type GithubPrParams, type GithubPushParams, type GithubReleaseParams, type GithubStepConfig, type GithubStepResult, type PipelineConfig, type PipelineContext, type PipelineLogger, type PipelineResult, PostGenerationPipeline, type ReplayForgetParams, type ReplayInitParams, type ReplayInitResult, type ReplayResolveParams, type ReplayRunParams, type ReplayRunResult, type ReplayStatusParams, type ReplayStepResult, consolePipelineLogger, formatBootstrapSummary, formatReplayPrBody, generateReadme, generateReadmeToStream, generateReference, generateReferenceToStream, githubPr, githubPush, githubRelease, logReplaySummary, replayForget, replayInit, replayResolve, replayRun, replayStatus };
+interface SubmitReplayInitParams {
+    /** Fiddle API origin (e.g. "https://fiddle.buildwithfern.com") */
+    fiddleOrigin: string;
+    /** Fern auth token */
+    fernToken: string;
+    /** GitHub repository (e.g. "owner/repo" or full URL) */
+    githubRepo: string;
+    /** Result from replayInit() */
+    initResult: ReplayInitResult;
+}
+interface SubmitReplayInitResult {
+    /** URL of the PR created by Fiddle */
+    prUrl: string;
+}
+/**
+ * Submits a Replay init lockfile to the Fiddle API for server-side PR creation.
+ *
+ * Extracts owner/repo from the GitHub repository string, posts the lockfile
+ * and related metadata to the Fiddle remote-gen endpoint, and returns the
+ * resulting PR URL.
+ *
+ * This function is shared between CLI v1 and CLI v2 to avoid duplicating
+ * the Fiddle submission logic.
+ */
+declare function submitReplayInit(params: SubmitReplayInitParams): Promise<SubmitReplayInitResult>;
+/**
+ * Parses a GitHub repository string into owner and repo components.
+ * Accepts formats: "owner/repo", "github.com/owner/repo",
+ * "https://github.com/owner/repo", "https://github.com/owner/repo.git"
+ */
+declare function parseOwnerRepo(githubRepo: string): {
+    owner: string;
+    repo: string;
+};
+/**
+ * Error thrown when submitting a Replay init to Fiddle fails.
+ * Consumers can inspect `statusCode` to distinguish between
+ * different failure modes (e.g. 404 = GitHub App not installed).
+ */
+declare class ReplaySubmitError extends Error {
+    readonly statusCode: number | undefined;
+    constructor(message: string, statusCode?: number);
+}
+
+export { type BootstrapLogEntry, type GenerateReadmeParams, type GenerateReadmeToStreamParams, type GenerateReferenceParams, type GenerateReferenceToStreamParams, type GithubPrParams, type GithubPushParams, type GithubReleaseParams, type GithubStepConfig, type GithubStepResult, type PipelineConfig, type PipelineContext, type PipelineLogger, type PipelineResult, PostGenerationPipeline, type ReplayForgetParams, type ReplayInitParams, type ReplayInitResult, type ReplayResolveParams, type ReplayRunParams, type ReplayRunResult, type ReplayStatusParams, type ReplayStepResult, ReplaySubmitError, type SubmitReplayInitParams, type SubmitReplayInitResult, consolePipelineLogger, formatBootstrapSummary, formatReplayPrBody, generateReadme, generateReadmeToStream, generateReference, generateReferenceToStream, githubPr, githubPush, githubRelease, logReplaySummary, parseOwnerRepo, replayForget, replayInit, replayResolve, replayRun, replayStatus, submitReplayInit };