feat(cli): add git-ref-based docs versioning

[devin-ai-integration]

Description

Adds v1 of git-ref-based docs versioning to the CLI. A version entry in docs.yml can name a single ref: (a git branch, tag, or commit SHA) instead of committing that version's content into the working tree. On publish, the CLI resolves the ref to a commit, materializes the repo at that commit, and composes the historical pages/nav/assets/API/libraries with the current branch's theme, shell, and versions: metadata. path:-only entries are byte-for-byte unchanged.

versions:
  - display-name: Latest
    path: ./versions/latest.yml   # working tree, unchanged behavior
  - display-name: "2.3"
    ref: release/2.3              # patchable (branch)
  - display-name: "2.2"
    ref: v2.2.0                   # frozen (tag)
    availability: deprecated

Changes Made

• docs.yml VersionConfig gains an optional ref: (schema + generated SDK/jsonschema regenerated). The field shape is isolated in getVersionContentRef so it can change in one spot.
• A version uses either ref: or path:, never both — declaring both is a config error surfaced by both fern check (the valid-version-ref rule) and the publish/build path with an actionable message.
• git-versions/: materializeGitRef (resolve <ref>^{commit}, backfill shallow/tagless CI history, git worktree materialize the whole repo, cache by SHA, prune + graceful temp cleanup) and resolveRefContentRoot (content-root precedence: ref versions[0].path → ref top-level navigation:, no recursion).
• DocsDefinitionResolver threads a VersionContentSource so historical pages/assets/snippets/API+OSS workspaces/libraries: output resolve from the ref.
• Version building: the publish path builds every version (no flag). fern docs dev previews only the working-tree version (git-ref-backed versions are materialized on publish); fern check never materializes refs.
• Library sections warn-and-skip when their output is missing (library absent from config, missing _navigation.yml, missing generated MDX) — a historical version can publish without its SDK reference. This matches pre-existing single-version behavior; unlike api: sections it is not a hard failure. (An earlier hard-fail proposal was intentionally not shipped; revisit in v2.)
• Moved/renamed fern folder at a ref → actionable CliError naming the ref, SHA, and expected path (instead of a raw ENOENT).
• Ref resolution: also tries origin/<ref> and resolves FETCH_HEAD after a targeted fetch (covers shallow/single-branch CI checkouts); --end-of-options hardens refs beginning with -.
• CI: added docs-preview-smoke-test/playwright/tsconfig.json so a newer Playwright doesn't walk up to the workspace-root tsconfig.json (unrelated harness fix that was blocking the smoke-test).

Scope deliberately left out (per prompt)

• No FDR/renderer changes (emits the same versioned bundle).
• No library-generation changes: no ref: on library inputs, no per-version library overrides, fern generate --docs does not invoke md generation. (v2.)

Testing

• Unit tests added/updated: getVersionContentRef, resolveRefContentRoot precedence + actionable error, refPathMutualExclusion, valid-version-ref, and a git-integration matrix for materializeGitRef (remote-tracking branch, tag, unresolvable ref, shallow/tagless fetch, leading-dash ref, mutability, same-SHA caching, offline fallback, fern-folder-moved).
• Manual testing completed: demo on fern-api/ryanstep-config (branch + tag) built with this CLI; publish composes all three versions and serves /welcome, /2-0/welcome, /1-0/welcome.

Link to Devin session: https://app.devin.ai/sessions/185c0e74b50b43f79023c793c814ac44

[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, CI, and merge conflict monitoring

[nitpickybot]

Reviewed the changes — everything looks good. No issues found.

[devin-ai-integration]

Devin Review found 2 potential issues.

View 3 additional findings in Devin Review.

[devin-ai-integration]

🔴 Documentation validation unexpectedly rebuilds historical versions and can fail

Historical git-ref-backed versions are built by materializing git checkouts during validation and definition-writing (because ref building is left on by default at packages/cli/docs-resolver/src/DocsDefinitionResolver.ts:221) rather than only at publish, so fern check and related commands perform git operations they were never meant to and can error out.

Impact: A project that declares a tag/branch-based docs version can no longer run fern check (or the write-definition/redirect-check flows) reliably — it triggers slow git worktree checkouts and hard-fails in common CI setups, and even the publish flow's validation step can abort before publishing.

Why buildRefVersions defaults on for validation call sites

The resolver defaults buildRefVersions = true (packages/cli/docs-resolver/src/DocsDefinitionResolver.ts:221), and it is threaded into parseDocsConfiguration (packages/cli/docs-resolver/src/DocsDefinitionResolver.ts:459) which then materializes each ref version via materializeGitRef (git rev-parse / fetch / git worktree add).

The publish path (packages/cli/generation/remote-generation/remote-workspace-runner/src/publishDocs.ts:544) and preview path (packages/cli/docs-preview/src/previewDocs.ts) were updated to pass cliVersion, but the validation/utility call sites were not and do not opt out of ref building:

• packages/cli/yaml/docs-validator/src/rules/valid-markdown-link/valid-markdown-link.ts:80
• packages/cli/yaml/docs-validator/src/rules/missing-redirects/missing-redirects.ts:127
• packages/cli/cli/src/commands/write-docs-definition/writeDocsDefinitionForProject.ts:35

Both rules are registered in getAllRules.ts, so fern check runs them. Each constructs DocsDefinitionResolver without buildRefVersions, so it defaults to true and materializes every ref version. Two concrete failures follow:

1. In shallow/tagless CI checkouts resolveRefToSha throws the actionable ConfigError — validation fails even though the PR's stated intent is that ref versions are validated at build time, not during current-tree validation.
2. If a ref version contains an api: section, resolveApiWorkspaces (packages/cli/docs-resolver/src/DocsDefinitionResolver.ts:1185-1192) throws an InternalError because cliVersion is undefined at these call sites.

The docs-validator AST change only skipped current-tree path validation for ref entries; it did not prevent the resolver-backed rules from fully building them.

Prompt for agents

The DocsDefinitionResolver constructor defaults buildRefVersions to true so the publish path (which passes cliVersion) builds git-ref-backed versions. However three other construction sites inherit this default and neither opt out nor pass cliVersion: the docs-validator rules valid-markdown-link.ts (line ~80) and missing-redirects.ts (line ~127), and writeDocsDefinitionForProject.ts (line ~35). Because these run during `fern check` and pre-publish validation, they now materialize git worktrees for every ref version and hard-fail in shallow/tagless CI, and additionally throw an InternalError from resolveApiWorkspaces when a ref version has an `api:` section (cliVersion is undefined there). The PR's design intent is that ref versions are validated at build/publish time, not during current-tree validation. Fix by making these validation/utility call sites explicitly pass buildRefVersions: false (matching the docs-validator AST change that already skips ref entries), so validation only exercises the working-tree versions. Confirm whether writeDocsDefinitionForProject should build refs (and if so thread cliVersion through it); otherwise set it false as well.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Good catch, fixed in 559ddf4. The three validation/utility construction sites (valid-markdown-link.ts, missing-redirects.ts, writeDocsDefinitionForProject.ts) now explicitly pass buildRefVersions: false, so fern check and write-definition only exercise working-tree versions and never materialize git worktrees or hit the cliVersion == null path. Ref versions are still built at publish (publishDocs.ts) and preview-with---versions all, matching the design intent that ref versions are validated at build time.

[devin-ai-integration]

🟨 Git ref from docs.yml passed to git without option terminator

The tag/branch value from docs.yml is passed directly as a positional argument to git subcommands (git rev-parse --verify --quiet ${ref}^{commit} at packages/cli/configuration-loader/src/docs-yml/git-versions/materializeGitRef.ts:100, and git fetch ... ${remote} ${ref} at packages/cli/configuration-loader/src/docs-yml/git-versions/materializeGitRef.ts:134) without a -- end-of-options separator. A ref value beginning with - (e.g. --upload-pack=...) could be interpreted by git as an option rather than a ref, enabling git option-injection. Commands are invoked via execa with an argv array (no shell), so classic shell command injection does not apply.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Hardened in 559ddf4 — added a -- end-of-options terminator before the ref in both git rev-parse --verify --quiet -- <ref>^{commit} and git fetch ... <remote> -- <ref>, so a ref value beginning with - can no longer be interpreted as a git flag. (As you note, execa uses an argv array with no shell, so there was never a shell-injection vector — this closes the git option-injection one.)

[github-actions]

Docs Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-08-05T05:01:21Z).

Fixture	main	PR	Delta
docs	252.7s (n=5)	250.4s (35 versions)	-2.3s (-0.9%)

Docs generation runs fern generate --docs --preview end-to-end against the benchmark fixture with 35 API versions (each version: markdown processing + OpenAPI-to-IR + FDR upload).
Delta is computed against the nightly baseline on main.
Baseline from nightly run(s) on main (latest: 2026-08-05T05:01:21Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-08-05 17:49 UTC

[github-actions]

SDK Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-08-05T05:01:21Z).

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
csharp-sdk	square	98s (n=5)	N/A	90s	-8s (-8.2%)
go-sdk	square	151s (n=5)	298s (n=5)	141s	-10s (-6.6%)
java-sdk	square	208s (n=5)	272s (n=5)	168s	-40s (-19.2%)
php-sdk	square	64s (n=5)	N/A	55s	-9s (-14.1%)
python-sdk	square	150s (n=5)	250s (n=5)	144s	-6s (-4.0%)
ruby-sdk-v2	square	110s (n=5)	146s (n=5)	106s	-4s (-3.6%)
rust-sdk	square	221s (n=5)	225s (n=5)	172s	-49s (-22.2%)
swift-sdk	square	80s (n=5)	448s (n=5)	56s	-24s (-30.0%)
ts-sdk	square	133s (n=5)	134s (n=5)	172s	+39s (+29.3%)

main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via fern generate). main (E2E): full customer-observable time including build/test scripts (nightly baseline, informational). Delta is computed against generator-only baseline.
⚠️ = generation exited with a non-zero exit code (timing may not reflect a successful run).
Baseline from nightly runs on main (latest: 2026-08-05T05:01:21Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-08-05 17:49 UTC

[aditya-arolkar-swe]

LGTM, but a small nit on the interface. It seems this is the current use case:
fern generate --docs --version all
and the docs dev version doesn't work yet (can be a follow up PR)

fern docs dev --version all
(flag is just not available yet)

However, @Ryan-Amirthan why have a version flag at all? If multiple versions are provided, isn't the default to assume we'd want all - then the flag can be used to narrow down specific versions for some deploys?

[Ryan-Amirthan]

LGTM, but a small nit on the interface. It seems this is the current use case: fern generate --docs --version all and the docs dev version doesn't work yet (can be a follow up PR)

fern docs dev --version all (flag is just not available yet)

However, @Ryan-Amirthan why have a version flag at all? If multiple versions are provided, isn't the default to assume we'd want all - then the flag can be used to narrow down specific versions for some deploys?

agreed @aditya-arolkar-swe , stale code that should have been removed when we changed the scope to remove version specific publishing.

[devin-ai-integration]

Re: @aditya-arolkar-swe's interface nit + @Ryan-Amirthan's reply — agreed, no version flag.

Correcting my earlier wording here: fern docs dev --versions current|all did exist (added in the initial feat commit 729b01a1c76). It was intentionally removed in c58c289acb3 — "scope git-ref docs versioning to publish only; drop fern docs dev --versions" — which also dropped the dev/preview plumbing. My later commit 4fabaddabe3 only cleaned up leftover docstrings that still referenced the flag. So it's not "never existed" — it was deliberately scoped out.

Current behavior:

• Publish (fern generate --docs) builds every version by default; no narrowing flag (--version is the SDK-package version flag, ignored for docs).
• fern docs dev previews the working-tree version only.

[aditya-arolkar-swe]

• Publish (fern generate --docs) already builds every version by default; there's no narrowing flag, and --version is ignored for docs (it's the SDK-package version flag).

Thanks - the usual fern generate --docs command now works for seeing all versions

• fern docs dev previews the working-tree version only (git-ref-backed versions are materialized on publish). Per Ryan's call this stays the fixed behavior rather than gaining a --versions flag.

@Ryan-Amirthan why would we not want them previewing this with fern docs dev? I was able to do this before the latest commit with fern docs dev --versions all and the recent commit removed that. Was there a use case they needed?

Regardless, looks good now. Can merge and address above in follow up PR.

[devin-ai-integration]

@aditya-arolkar-swe on the "why can't fern docs dev preview them" — that's @Ryan-Amirthan's scoping call (c58c289acb3), so I'll let him speak to the rationale. What I can add on the mechanics: dev preview of ref-backed versions is fully feasible — it worked in 729b01a1c76. Re-adding it means restoring the buildRefVersions/cliVersion plumbing through devDocsWorkspace → previewDocs → runAppPreviewServer and reintroducing the flag (or just always building all in dev). The one tradeoff is dev-loop speed: each reload would materialize a git worktree per ref, which is why it was scoped to publish for v1.

Agreed this is a clean follow-up. If Ryan wants it, I'm happy to open that PR (restore dev preview, default to all versions, no flag — matching the "default = all" idea from your earlier comment).

[Ryan-Amirthan]

• Publish (fern generate --docs) already builds every version by default; there's no narrowing flag, and --version is ignored for docs (it's the SDK-package version flag).

Thanks - the usual fern generate --docs command now works for seeing all versions

• fern docs dev previews the working-tree version only (git-ref-backed versions are materialized on publish). Per Ryan's call this stays the fixed behavior rather than gaining a --versions flag.

@Ryan-Amirthan why would we not want them previewing this with fern docs dev? I was able to do this before the latest commit with fern docs dev --versions all and the recent commit removed that. Was there a use case they needed?

Regardless, looks good now. Can merge and address above in follow up PR.

@aditya-arolkar-swe removed previewing from fern docs dev because I did not want fern docs dev to run slower due to it needing to create the git worktrees for each version and then render them. Since git ref based versioning is more of a snapshot in time I believe it will not be as necessary for fern docs dev. Checking out into the respective commit SHA would still allow someone to preview the version with fern docs dev.