@fern-api/generator-cli 0.9.17 → 0.9.19

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import { ReplayService, ReplayPreparation, ReplayReport, ForgetOptions, ForgetResult, BootstrapResult, ResolveResult, StatusResult } from '@fern-api/replay';
+import { ForgetOptions, ForgetResult, BootstrapResult, ResolveResult, ReplayReport, StatusResult } from '@fern-api/replay';
 export { ConflictDetail, DiffStat, ForgetOptions, ForgetResult, MatchedPatch, ReplayReport, ResolveResult, StatusGeneration, StatusPatch, StatusResult } from '@fern-api/replay';
 import fs from 'fs';
 
@@ -480,291 +480,6 @@ interface GithubReleaseParams {
 }
 declare function githubRelease(params: GithubReleaseParams): Promise<void>;
 
-/**
- * Logger interface for pipeline steps.
- * Abstracts away the logging implementation so steps work with both
- * the CLI's TaskContext and the standalone CLI subprocess (console).
- */
-interface PipelineLogger {
-    debug(message: string): void;
-    info(message: string): void;
-    warn(message: string): void;
-    error(message: string): void;
-}
-/**
- * Default logger implementation using stderr (to avoid mixing with JSON result output on stdout).
- */
-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;
-    generatorVersions?: Record<string, string>;
-    generatorName?: string;
-}
-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;
-}
-interface GithubStepConfig {
-    enabled: boolean;
-    /** GitHub repository URI (e.g. "owner/repo") */
-    uri: string;
-    /** GitHub auth token */
-    token: string;
-    /** Output mode */
-    mode: "push" | "pull-request";
-    /** Target branch (base branch for PRs, push target for push mode) */
-    branch?: string;
-    /** Commit message for the generation */
-    commitMessage?: string;
-    /** User-facing changelog entry for PR body. When present, used instead of commit message body. */
-    changelogEntry?: string;
-    /** Structured PR description with Before/After code fences for breaking changes. Takes priority over changelogEntry for PR body. */
-    prDescription?: string;
-    /** One-sentence justification for WHY the version bump was chosen. Shown only for breaking changes. */
-    versionBumpReason?: string;
-    /** The previous SDK version before this change (e.g. "1.2.3"). Used for version header in PR body. */
-    previousVersion?: string;
-    /** The new SDK version after this change (e.g. "1.3.0"). Used for version header in PR body. */
-    newVersion?: string;
-    /** The version bump level: MAJOR, MINOR, or PATCH. Used for version header formatting. */
-    versionBump?: string;
-    /** Skip push/PR creation, just prepare branches locally */
-    previewMode?: boolean;
-    /** Generator name for namespaced fern-generation-base tag */
-    generatorName?: string;
-    /** Explicit override: whether replay already created commits (derived from replay context if omitted) */
-    skipCommit?: boolean;
-    /** Explicit override: replay conflict info (derived from replay context if omitted) */
-    replayConflictInfo?: {
-        previousGenerationSha: string;
-        currentGenerationSha: string;
-    };
-    /** 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) */
-    hasBreakingChanges?: boolean;
-    /** Human-readable breaking changes summary for PR body (from autoVersioningPrDescription on MAJOR) */
-    breakingChangesSummary?: string;
-    /** FERN_RUN_ID for cross-repo correlation (set by GitHub Action) */
-    runId?: string;
-}
-interface PipelineResult {
-    success: boolean;
-    steps: {
-        generationCommit?: GenerationCommitStepResult;
-        replay?: ReplayStepResult;
-        autoVersion?: AutoVersionStepResult;
-        fernignore?: FernignoreStepResult;
-        github?: GithubStepResult;
-    };
-    errors?: string[];
-    warnings?: string[];
-}
-interface ReplayStepResult extends StepResult {
-    flow?: "first-generation" | "no-patches" | "normal-regeneration" | "skip-application";
-    patchesDetected?: number;
-    patchesApplied?: number;
-    patchesWithConflicts?: number;
-    patchesAbsorbed?: number;
-    patchesRepointed?: number;
-    patchesContentRebased?: number;
-    patchesKeptAsUserOwned?: number;
-    previousGenerationSha?: string;
-    currentGenerationSha?: string;
-    baseBranchHead?: string;
-    unresolvedPatches?: Array<{
-        patchId: string;
-        patchMessage: string;
-        files: string[];
-        conflictDetails: Array<{
-            file: string;
-            conflictReason?: string;
-        }>;
-    }>;
-    warnings?: string[];
-}
-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;
-    prUrl?: string;
-    prNumber?: number;
-    updatedExistingPr?: boolean;
-    generationBaseTagSha?: string;
-    /** True when generation produced no changes vs base branch — PR skipped */
-    skippedNoDiff?: boolean;
-    /** True when automerge was enabled on the PR */
-    autoMergeEnabled?: boolean;
-}
-interface StepResult {
-    executed: boolean;
-    success: boolean;
-    errorMessage?: string;
-}
-
-declare class PostGenerationPipeline {
-    private readonly config;
-    private readonly logger;
-    private steps;
-    constructor(config: PipelineConfig, logger?: PipelineLogger);
-    run(): Promise<PipelineResult>;
-}
-
-declare function logReplaySummary(result: ReplayStepResult, logger: PipelineLogger): void;
-declare function formatReplayPrBody(result: ReplayStepResult | undefined, options?: {
-    branchName?: string;
-    repoUri?: string;
-}): string | undefined;
-
 interface ReplayForgetParams {
     /** Directory containing the SDK (where .fern/replay.lock lives) */
     outputDir: string;
@@ -792,10 +507,10 @@ interface ReplayInitResult {
     bootstrap: BootstrapResult;
     /** Raw lockfile YAML content, present when bootstrap succeeded and not dry-run */
     lockfileContent?: string;
-    /** Raw replay.yml content, present only when fernignore migration created it */
-    replayYmlContent?: string;
     /** Fernignore entries that the server should ensure exist */
     fernignoreEntries: string[];
+    /** Gitattributes entries the server should ensure exist (e.g. linguist-generated markers) */
+    gitattributesEntries: string[];
     /** Generated PR body markdown for the server to use */
     prBody?: string;
 }
@@ -808,8 +523,8 @@ interface ReplayInitResult {
  * Flow:
  * 1. Clone the SDK repo (read-only)
  * 2. Run bootstrap() to scan history and create lockfile
- * 3. Ensure .fernignore has replay entries
- * 4. Read lockfile content from disk and return it
+ * 3. Read lockfile content from disk
+ * 4. Return lockfile + fernignore/gitattributes entries for Fiddle to apply server-side
  */
 declare function replayInit(params: ReplayInitParams): Promise<ReplayInitResult>;
 interface BootstrapLogEntry {
@@ -831,6 +546,49 @@ interface ReplayResolveParams {
 }
 declare function replayResolve(params: ReplayResolveParams): Promise<ResolveResult>;
 
+/**
+ * Logger interface for pipeline steps.
+ * Abstracts away the logging implementation so steps work with both
+ * the CLI's TaskContext and the standalone CLI subprocess (console).
+ */
+interface PipelineLogger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+
+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;
+}
+/**
+ * Backwards-compatible atomic entry point. Composes `replayPrepare` +
+ * `replayApply` with byte-identical behavior for existing callers.
+ */
+declare function replayRun(params: ReplayRunParams): Promise<ReplayRunResult>;
+
 interface ReplayStatusParams {
     /** Directory containing the SDK (where .fern/replay.lock lives) */
     outputDir: string;
@@ -881,4 +639,4 @@ declare class ReplaySubmitError extends Error {
     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 };
+export { type BootstrapLogEntry, type GenerateReadmeParams, type GenerateReadmeToStreamParams, type GenerateReferenceParams, type GenerateReferenceToStreamParams, type GithubPrParams, type GithubPushParams, type GithubReleaseParams, type ReplayForgetParams, type ReplayInitParams, type ReplayInitResult, type ReplayResolveParams, type ReplayRunParams, type ReplayRunResult, type ReplayStatusParams, ReplaySubmitError, type SubmitReplayInitParams, type SubmitReplayInitResult, formatBootstrapSummary, generateReadme, generateReadmeToStream, generateReference, generateReferenceToStream, githubPr, githubPush, githubRelease, parseOwnerRepo, replayForget, replayInit, replayResolve, replayRun, replayStatus, submitReplayInit };