feat(cli): polish fern config migrate with docs.yml $ref pointer, drop group/defaultGroup, and workflow migration

[iamnamananand996]

Description

Closes FER-8911

Polishes the fern config migrate command with several improvements to handle real-world migration edge cases.

Changes Made

1. Drop defaultGroup and group from migration output

• Removed defaultGroup propagation in Migrator.ts (multi-API path) and both convertSdkTargets / convertSdkTargetsFromRaw in convertSdkTargets.ts
• Removed target.group = [groupName] assignment from convertGeneratorToTarget and convertRawGeneratorToTarget
• Schemas (SdksSchema, SdkTargetSchema) are left unchanged for backward-compat reading

2. docs.yml $ref pointer

• New migrateDocsYml function checks if docs.yml exists in the fern/ directory and, if so, returns a { $ref: "./docs.yml" } pointer
• The migrated fern.yml simply points its docs key at the existing docs.yml file via $ref syntax — no inlining or recursive resolution
• docs.yml is not added to migratedFiles (it must remain on disk since fern.yml now references it)

3. GitHub Actions workflow migration

• New migrateGithubWorkflows function scans .github/workflows/*.yml and .yaml files
• Transforms fern generate → fern sdk generate
• Transforms --group → --target (only on lines containing fern generate)

4. Generator metadata and smart-casing migration

• Migrates generator-level metadata fields: package-description → description, author/email → authors, license → output.git.license
• Emits unsupported warning for metadata.reference-url (no fern.yml equivalent)
• Emits unsupported warning for smart-casing (not supported in fern.yml)

5. Settings key alias

• Added title-as-schema-name as an alias for titleAsSchemaName in the settings migration key map

6. Changelog entry (unreleased versioning system)

• Added packages/cli/cli/changes/unreleased/polish-fern-config-migrate.yml using the new unreleased changelog system (no direct versions.yml entry)

7. Comprehensive test suite

• migrateDocsYml.test.ts — 5 tests: missing file, $ref pointer creation, empty file, complex content, no inlining
• migrateGithubWorkflows.test.ts — 9 tests: missing dir, empty dir, command rewriting, --group → --target, fern-api variant, no-op, multiple files, non-yaml ignored, multi-command
• convertSdkTargets.test.ts — 13 tests: empty groups, basic conversion, group/defaultGroup exclusion, multi-group, deduplication, unknown generators, config preservation, npm publish, apiName, raw format, image field, missing name, git output
• FernConfigJsonMigrator.test.ts — 9 tests: detect/migrate for fern.config.json
• GeneratorsYmlMigrator.test.ts — real-world xai REST/gRPC configs, metadata migration, smart-casing warnings, multi-group, openapi settings, auth
• Migrator.test.ts — end-to-end integration tests for single-API and multi-API workspaces
• convertApiSpecs.test.ts — API spec conversion edge cases
• convertGitOutput.test.ts — git output configuration conversion
• convertSettings.test.ts — settings key mapping including title-as-schema-name alias

Human review checklist

• docs field type cast — docsRef is cast via as unknown as schemas.FernYmlSchema["docs"] since { $ref: string } doesn't match the DocsSchema zod type. This works at runtime (YAML serializer sees a plain object) but bypasses compile-time type checking.
• Metadata migration type casts — generator.metadata and smart-casing are accessed via as casts (e.g. (generator as { "smart-casing"?: boolean })). These bypass compile-time checks; verify the underlying types actually carry these fields at runtime.
• Duplicated metadata migration logic — The metadata → target.metadata / license → output.git.license block is duplicated between convertGeneratorToTarget and convertRawGeneratorToTarget. Consider extracting a shared helper if this grows.
• Workflow regex scope — --group → --target replacement is scoped to lines matching fern generate, but could still transform echo/comment lines that happen to contain that pattern.

Testing

• Unit tests added (50+ tests across 9 test files)
• Lint (pnpm run check) passes
• Format (pnpm format) passes
• Manual testing completed

Link to Devin session: https://app.devin.ai/sessions/9a72485c90c3405a98a3885f0fb90ebb
Requested by: @iamnamananand996

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[iamnamananand996]

We should use the new unreleased versioning system

[devin-ai-integration]

Done — removed the 4.65.0 entry from versions.yml and created packages/cli/cli/changes/unreleased/polish-fern-config-migrate.yml instead, using the new unreleased versioning system. This should also eliminate the recurring merge conflicts on this file.