[pull] main from fern-api:main

.claude/release-versioning.md

@@ -0,0 +1,49 @@
+# Changelog Infrastructure
+
+**Source of truth:** `release-config.json` (see `release-config.schema.json`). Each **`software`** entry defines:
+
+- **`softwareDirectory`**: repo paths under this tree are **that** product’s surface area.
+- **`changelogFolder`**: where changelog files for that product live.
+
+## What you should do
+
+When your change touches files **under** a given entry’s **`softwareDirectory`**, add or update an **unreleased** changelog file under:
+
+```text
+{changelogFolder}/unreleased/
+```
+
+Use the **`changelogFolder`** value from `release-config.json` for that software key. Do **not** hand-edit **`versions.yml`**; versioning and rolling releases are handled by **automation**, not by running local release commands.
+
+**Automation:** `.github/workflows/release-software.yml` drives the release pipeline (including when changes land on `main` under the configured changelog paths). Your job in a PR is to leave correct **`unreleased/`** entries so that workflow can run.
+
+## Mapping (from `release-config.json`)
+
+If a path falls under **`softwareDirectory`**, use the matching **`changelogFolder`/unreleased** column. **If anything here disagrees with `release-config.json`, follow the file on disk.**
+
+
+| Key | `softwareDirectory` | Add changelogs under |
+|-----|---------------------|----------------------|
+| `cli` | `packages/cli` | `packages/cli/cli/changes/unreleased/` |
+| `csharp` | `generators/csharp` | `generators/csharp/sdk/changes/unreleased/` |
+| `go` | `generators/go` | `generators/go/sdk/changes/unreleased/` |
+| `java` | `generators/java` | `generators/java/sdk/changes/unreleased/` |
+| `php` | `generators/php` | `generators/php/sdk/changes/unreleased/` |
+| `python` | `generators/python` | `generators/python/sdk/changes/unreleased/` |
+| `ruby` | `generators/ruby` | `generators/ruby/sdk/changes/unreleased/` |
+| `ruby-v2` | `generators/ruby-v2` | `generators/ruby-v2/sdk/changes/unreleased/` |
+| `rust` | `generators/rust` | `generators/rust/sdk/changes/unreleased/` |
+| `swift` | `generators/swift` | `generators/swift/sdk/changes/unreleased/` |
+| `typescript` | `generators/typescript` | `generators/typescript/sdk/changes/unreleased/` |
+
+Pick the narrowest matching **`softwareDirectory`** when several could apply (e.g. generator-only work under `generators/python/...` uses the Python generator row, not CLI). If a single PR spans multiple **`softwareDirectory`** trees, add a changelog file in **each** corresponding **`changelogFolder/unreleased/`**.
+
+## Changelog file format
+
+1. Copy **`.template.yml`** from that product’s `changes/unreleased/` if you need a starting point.
+2. Use a new filename that describes the change (e.g. `fix-streaming-timeout.yml`).
+3. Each file is a **YAML array** of objects. Only these fields are allowed (see **`fern-changes-yml.schema.json`**):
+   - **`summary`**: string (multi-line `|` allowed).
+   - **`type`**: `fix` | `chore` | `feat` | `internal` | `break`
+
+Those types drive semver bumps when releases run (`fix`/`chore` → patch, `feat`/`internal` → minor, `break` → major). You do not need to bump versions yourself.

.github/workflows/release-software.yml

@@ -0,0 +1,90 @@
+name: Release Software
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      # Auto-updated by scripts/release-setup.ts — do not edit manually
+      - "packages/cli/cli/changes/**"
+      - "generators/csharp/sdk/changes/**"
+      - "generators/go/sdk/changes/**"
+      - "generators/java/sdk/changes/**"
+      - "generators/php/sdk/changes/**"
+      - "generators/python/sdk/changes/**"
+      - "generators/ruby/sdk/changes/**"
+      - "generators/ruby-v2/sdk/changes/**"
+      - "generators/rust/sdk/changes/**"
+      - "generators/swift/sdk/changes/**"
+      - "generators/typescript/sdk/changes/**"
+  workflow_dispatch:
+    inputs:
+      software:
+        description: "Which software to release"
+        required: false
+        default: "all"
+        type: choice
+        options:
+          # Auto-updated by scripts/release-setup.ts — do not edit manually
+          - all
+          - cli
+          - csharp
+          - go
+          - java
+          - php
+          - python
+          - ruby
+          - ruby-v2
+          - rust
+          - swift
+          - typescript
+
+# Prevent concurrent release runs to avoid git conflicts
+concurrency:
+  group: release-software
+  cancel-in-progress: false
+
+# ACTIONS_PAT must belong to a user with bypass access for the main branch
+# protection rule, scoped only to allow changelog/versions file commits.
+permissions:
+  contents: write
+
+jobs:
+  release-software:
+    if: github.repository == 'fern-api/fern'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.ACTIONS_PAT }}
+          ref: main
+          fetch-depth: 0
+
+      - name: Skip if triggered by own release commit
+        id: skip-release-loop
+        run: |
+          SUBJECT=$(git log -1 --format='%s')
+          echo "Last commit subject: $SUBJECT"
+          if [[ "$SUBJECT" =~ ^chore\(.+\):\ release\ .+ ]]; then
+            echo "Triggered by automated release commit — skipping to avoid loop."
+            echo "skip=true" >> $GITHUB_OUTPUT
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Configure git
+        if: steps.skip-release-loop.outputs.skip != 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Install
+        if: steps.skip-release-loop.outputs.skip != 'true'
+        uses: ./.github/actions/install
+
+      - name: Run releases for all configured software
+        if: steps.skip-release-loop.outputs.skip != 'true'
+        env:
+          SOFTWARE: ${{ inputs.software || 'all' }}
+        run: npx tsx scripts/release-workflow.ts "$SOFTWARE"

fern-changes-yml.schema.json

@@ -0,0 +1,42 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+        "title": "Changelog Entry",
+        "description": "Schema for changelog entries in the unreleased directory",
+    "type": "array",
+    "items": {
+        "$ref": "#/definitions/ChangelogEntry"
+    },
+    "definitions": {
+        "ChangelogEntry": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "summary": {
+                    "type": "string",
+                    "description": "Description of the change. Use multi-line format for longer descriptions."
+                },
+                "type": {
+                    "$ref": "#/definitions/ChangelogType",
+                    "description": "Type of change determines version bump: fix/chore (patch), feat/internal (minor), break (major)"
+                }
+            },
+            "required": [
+                "summary",
+                "type"
+            ],
+            "title": "Changelog"
+        },
+        "ChangelogType": {
+            "type": "string",
+            "enum": [
+                "fix",
+                "chore",
+                "feat",
+                "internal",
+                "break"
+            ],
+            "title": "Changelog Type",
+            "description": "The type of change: fix/chore → patch, feat/internal → minor, break → major"
+        }
+    }
+}

generators/csharp/sdk/changes/unreleased/.template.yml

@@ -0,0 +1,8 @@
+# Template for changelog entries
+# Copy this file and rename it to describe your change (e.g., add-auth-feature.yml)
+# yaml-language-server: $schema=../../../../../fern-changes-yml.schema.json
+
+- summary: |
+    Brief description of your change.
+    You can use multiple lines for longer descriptions.
+  type: feat  # Options: fix/chore (patch), feat/internal (minor), break (major)

generators/go/sdk/changes/unreleased/.gitkeep

@@ -0,0 +1,2 @@
+# This directory contains unreleased changelog entries
+# Create files here following the format in fern-changes-yml.schema.json

generators/go/sdk/changes/unreleased/.template.yml

@@ -0,0 +1,8 @@
+# Template for changelog entries
+# Copy this file and rename it to describe your change (e.g., add-auth-feature.yml)
+# yaml-language-server: $schema=../../../../../fern-changes-yml.schema.json
+
+- summary: |
+    Brief description of your change.
+    You can use multiple lines for longer descriptions.
+  type: feat  # Options: fix/chore (patch), feat/internal (minor), break (major)

generators/java-v2/base/package.json

@@ -41,7 +41,7 @@
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/java-ast": "workspace:*",
     "@fern-api/logging-execa": "workspace:*",
-    "@fern-fern/ir-sdk": "^66.0.0",
+    "@fern-fern/ir-sdk": "^66.1.0",
     "@types/node": "catalog:",
     "typescript": "catalog:",
     "vitest": "catalog:"

generators/java-v2/sdk/package.json

@@ -49,7 +49,7 @@
     "@fern-api/logger": "workspace:*",
     "@fern-fern/generator-cli-sdk": "^0.1.8",
     "@fern-fern/generator-exec-sdk": "catalog:",
-    "@fern-fern/ir-sdk": "^66.0.0",
+    "@fern-fern/ir-sdk": "^66.1.0",
     "@types/lodash-es": "catalog:",
     "@types/node": "catalog:",
     "lodash-es": "catalog:",

generators/java/generator-utils/build.gradle

@@ -1,6 +1,6 @@
 dependencies {
     api 'com.squareup:javapoet'
-    api 'com.fern.fern:irV65'
+    api 'com.fern.fern:irV66'
     api 'com.fern.fern:generator-exec-client'
     api 'com.fasterxml.jackson.core:jackson-annotations'
     api 'com.fasterxml.jackson.core:jackson-databind'

generators/java/generator-utils/src/main/java/com/fern/java/AbstractGeneratorCli.java

@@ -24,7 +24,8 @@
 import com.fern.generator.exec.model.logging.SuccessfulStatusUpdate;
 import com.fern.ir.core.ObjectMappers;
 import com.fern.ir.model.commons.Name;
-import com.fern.ir.model.commons.NameAndWireValue;
+import com.fern.ir.model.commons.NameAndWireValueOrString;
+import com.fern.ir.model.commons.NameOrString;
 import com.fern.ir.model.ir.IntermediateRepresentation;
 import com.fern.ir.model.publish.DirectPublish;
 import com.fern.ir.model.publish.Filesystem;
@@ -127,14 +128,16 @@ private static IntermediateRepresentation getIr(GeneratorConfig generatorConfig)
             CasingConfiguration casingConfig = CasingConfiguration.fromIrJson(rootNode);
 
             SimpleModule nameModule = new SimpleModule("NameOrStringModule");
-            nameModule.addDeserializer(Name.class, new NameDeserializer(casingConfig));
-            nameModule.addDeserializer(NameAndWireValue.class, new NameAndWireValueDeserializer(casingConfig));
+            nameModule.addDeserializer(Name.class, new NameDeserializer.RawNameDeserializer(casingConfig));
+            nameModule.addDeserializer(NameOrString.class, new NameDeserializer(casingConfig));
+            nameModule.addDeserializer(NameAndWireValueOrString.class, new NameAndWireValueDeserializer(casingConfig));
 
             ObjectMapper irMapper = ObjectMappers.JSON_MAPPER.copy();
             // Mix-in annotations override class-level @JsonDeserialize(builder=...) annotations,
             // allowing the module-level custom deserializers to take effect.
             irMapper.addMixIn(Name.class, NameOrStringMixIn.class);
-            irMapper.addMixIn(NameAndWireValue.class, NameOrStringMixIn.class);
+            irMapper.addMixIn(NameOrString.class, NameOrStringMixIn.class);
+            irMapper.addMixIn(NameAndWireValueOrString.class, NameOrStringMixIn.class);
             irMapper.registerModule(nameModule);
 
             return irMapper.treeToValue(rootNode, IntermediateRepresentation.class);

generators/java/generator-utils/src/main/java/com/fern/java/AbstractModelPoetClassNameFactory.java

@@ -21,6 +21,7 @@
 import com.fern.ir.model.commons.SafeAndUnsafeString;
 import com.fern.ir.model.types.DeclaredTypeName;
 import com.fern.java.utils.KeyWordUtils;
+import com.fern.java.utils.NameUtils;
 import com.squareup.javapoet.ClassName;
 import java.util.ArrayList;
 import java.util.List;
@@ -37,14 +38,19 @@ public AbstractModelPoetClassNameFactory(
     public final ClassName getTypeClassName(DeclaredTypeName declaredTypeName) {
         String packageName = getTypesPackageName(declaredTypeName.getFernFilepath());
         return ClassName.get(
-                packageName, declaredTypeName.getName().getPascalCase().getSafeName());
+                packageName,
+                NameUtils.toName(declaredTypeName.getName()).getPascalCase().getSafeName());
     }
 
     @Override
     public final ClassName getInterfaceClassName(DeclaredTypeName declaredTypeName) {
         String packageName = getTypesPackageName(declaredTypeName.getFernFilepath());
         return ClassName.get(
-                packageName, "I" + declaredTypeName.getName().getPascalCase().getSafeName());
+                packageName,
+                "I"
+                        + NameUtils.toName(declaredTypeName.getName())
+                                .getPascalCase()
+                                .getSafeName());
     }
 
     protected final String getTypesPackageName(FernFilepath fernFilepath) {
@@ -54,6 +60,7 @@ protected final String getTypesPackageName(FernFilepath fernFilepath) {
                 // NOTE: We're making it camel-case here on purpose: snake-case is used in the NESTED case for
                 //  historical reasons, but we should unify on this method going forward.
                 tokens.addAll(fernFilepath.getPackagePath().stream()
+                        .map(NameUtils::toName)
                         .map(Name::getCamelCase)
                         .map(SafeAndUnsafeString::getSafeName)
                         .map(String::toLowerCase)
@@ -64,6 +71,7 @@ protected final String getTypesPackageName(FernFilepath fernFilepath) {
             default:
                 tokens.add("model");
                 tokens.addAll(fernFilepath.getAllParts().stream()
+                        .map(NameUtils::toName)
                         .map(Name::getSnakeCase)
                         .map(SafeAndUnsafeString::getSafeName)
                         .flatMap(snakeCase -> splitOnNonAlphaNumericChar(snakeCase).stream())

generators/java/generator-utils/src/main/java/com/fern/java/AbstractNonModelPoetClassNameFactory.java

@@ -21,6 +21,7 @@
 import com.fern.ir.model.commons.SafeAndUnsafeString;
 import com.fern.ir.model.types.DeclaredTypeName;
 import com.fern.java.utils.KeyWordUtils;
+import com.fern.java.utils.NameUtils;
 import com.squareup.javapoet.ClassName;
 import java.util.ArrayList;
 import java.util.List;
@@ -41,14 +42,19 @@ public AbstractNonModelPoetClassNameFactory(
     public final ClassName getTypeClassName(DeclaredTypeName declaredTypeName) {
         String packageName = getTypesPackageName(declaredTypeName.getFernFilepath());
         return ClassName.get(
-                packageName, declaredTypeName.getName().getPascalCase().getSafeName());
+                packageName,
+                NameUtils.toName(declaredTypeName.getName()).getPascalCase().getSafeName());
     }
 
     @Override
     public final ClassName getInterfaceClassName(DeclaredTypeName declaredTypeName) {
         String packageName = getTypesPackageName(declaredTypeName.getFernFilepath());
         return ClassName.get(
-                packageName, "I" + declaredTypeName.getName().getPascalCase().getSafeName());
+                packageName,
+                "I"
+                        + NameUtils.toName(declaredTypeName.getName())
+                                .getPascalCase()
+                                .getSafeName());
     }
 
     protected final String getTypesPackageName(FernFilepath fernFilepath) {
@@ -64,6 +70,7 @@ protected final String getResourcesPackage(Optional<FernFilepath> fernFilepath,
         switch (packageLayout) {
             case FLAT:
                 fernFilepath.ifPresent(filePath -> tokens.addAll(filePath.getPackagePath().stream()
+                        .map(NameUtils::toName)
                         .map(Name::getCamelCase)
                         .map(SafeAndUnsafeString::getSafeName)
                         .map(String::toLowerCase)
@@ -77,6 +84,7 @@ protected final String getResourcesPackage(Optional<FernFilepath> fernFilepath,
                     tokens.add("resources");
                 }
                 fernFilepath.ifPresent(filepath -> tokens.addAll(filepath.getAllParts().stream()
+                        .map(NameUtils::toName)
                         .map(Name::getCamelCase)
                         .map(SafeAndUnsafeString::getSafeName)
                         // names should be lower case

generators/java/generator-utils/src/main/java/com/fern/java/AbstractPoetClassNameFactory.java

@@ -3,6 +3,7 @@
 import com.fern.ir.model.ir.IntermediateRepresentation;
 import com.fern.ir.model.types.DeclaredTypeName;
 import com.fern.java.utils.KeyWordUtils;
+import com.fern.java.utils.NameUtils;
 import com.squareup.javapoet.ClassName;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -126,7 +127,7 @@ public static List<String> getPackagePrefixWithOrgAndApiName(IntermediateReprese
         prefix.add("com");
         prefix.addAll(splitOnNonAlphaNumericChar(KeyWordUtils.getKeyWordCompatibleName(organization)));
         prefix.addAll(splitOnNonAlphaNumericChar(KeyWordUtils.getKeyWordCompatibleName(
-                ir.getApiName().getCamelCase().getSafeName())));
+                NameUtils.toName(ir.getApiName()).getCamelCase().getSafeName())));
         return prefix;
     }
 }

generators/java/generator-utils/src/main/java/com/fern/java/FeatureResolver.java

@@ -8,6 +8,7 @@
 import com.fern.ir.model.auth.BearerAuthScheme;
 import com.fern.ir.model.auth.OAuthScheme;
 import com.fern.ir.model.commons.Name;
+import com.fern.ir.model.commons.NameOrString;
 import com.fern.ir.model.commons.SafeAndUnsafeString;
 import com.fern.ir.model.ir.IntermediateRepresentation;
 import java.util.List;
@@ -18,7 +19,7 @@ public class FeatureResolver {
 
     public static final AuthScheme DEFAULT_BEARER_AUTH = AuthScheme.bearer(BearerAuthScheme.builder()
             .key(AuthSchemeKey.of("bearer"))
-            .token(Name.builder()
+            .token(NameOrString.of(Name.builder()
                     .originalName("token")
                     .camelCase(SafeAndUnsafeString.builder()
                             .unsafeName("token")
@@ -36,7 +37,7 @@ public class FeatureResolver {
                             .unsafeName("TOKEN")
                             .safeName("TOKEN")
                             .build())
-                    .build())
+                    .build()))
             .build());
     private final IntermediateRepresentation ir;
     private final GeneratorConfig generatorConfig;