feat(cli): add fern docs link check command for live site link validation

[dsinghvi]

Description

Adds fern docs check --links (v2) / fern docs link check (v1) command that validates all links on a live Fern docs site via the dashboard's link-checker SSE endpoint.

Changes Made

• Link check command with real-time SSE streaming, progress bars, and categorized output (internal/external/blocked)
• Source file resolution: When sourcePageIds are available from the dashboard, resolves broken links to local file:line:column locations
• Multiple output formats: Human-readable (default), JSON, and CSV
• Runtime dashboard URL override: getDashboardBaseUrl() getter (deferred evaluation) ensures .env file overrides are respected after dotenv loading
• Shared constant: getDashboardBaseUrl exported from @fern-api/login, imported by both v1 and v2 CLI
• Updated README.md generator (if applicable) — N/A

Key Fixes from Code Review

• SSE robustness: WHATWG-compliant data: prefix handling (with/without space), decoder flush on EOF, null/type validation after JSON.parse
• Type safety: Runtime validation on error response body (no blind as casts), type-safe toBrokenLink helper, validated complete event array elements, narrowed type guard return types
• Output correctness: RFC 4180 CSV compliance (no comment lines, runStatus column), interrupted status in JSON/CSV, process.stderr.write bypass for text output
• Error handling: progress.finish() before error messages in catch, EPIPE-safe writeAndDrain, empty catch blocks documented
• Path handling: Segment-boundary check in stripBasePath, no double toRelativePath processing
• Logging: warn level for stream-interrupted messages, case-insensitive scheme regex
• UX parity: v1 CLI now mirrors v2 status message formatting (Icons + chalk styling)

Testing

• E2E tested against smoke-test-dev.docs.dev.buildwithfern.com
• Manual testing completed
• CI passing (42/42 on all pushes)

Link to Devin session: https://app.devin.ai/sessions/66d97c97cdbc4f6a9d8723b9d9641aac
Requested by: @Ryan-Amirthan

[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.}

[graphite-app]

The success message will never be displayed when there are broken links because the error is thrown first, making lines 71-73 unreachable. However, there's a more critical issue: when there are only blocked links (no broken links), the command exits successfully (exit code 0) without throwing an error, but also shows no success message. This creates inconsistent behavior.

if (result.brokenLinks.length > 0) {
    throw new CliError({ code: CliError.Code.ValidationError });
}

// This condition is unreachable when brokenLinks > 0
// But also won't show when blockedLinks > 0 and brokenLinks === 0
if (result.brokenLinks.length === 0 && result.blockedLinks.length === 0) {
    context.stderr.info(`${Icons.success} ${chalk.green("All links valid")}`);
}

Fix by restructuring:

if (result.brokenLinks.length > 0) {
    throw new CliError({ code: CliError.Code.ValidationError });
} else if (result.blockedLinks.length === 0) {
    context.stderr.info(`${Icons.success} ${chalk.green("All links valid")}`);
}

Spotted by Graphite



Is this helpful? React 👍 or 👎 to let us know.

[dsinghvi]

@devin fix

[devin-ai-integration]

Fixed — restructured to if/else if so the success message shows correctly when there are no broken links and no blocked links. Pushed in commit 58467c2.

[dsinghvi]

@claude review

[graphite-app]

Type guard isLinkCheckedData is incomplete and doesn't validate all required fields. It only checks url is a string and sourcePages is an array, but doesn't validate statusCode, isInternal, or that sourcePages contains strings. If the server sends invalid types (e.g., statusCode: "404" as a string instead of number), the type guard will pass but create a BrokenLink with the wrong types, violating the interface contract.

function isLinkCheckedData(
    data: Record<string, unknown>
): data is { url: string; statusCode: number | null; isInternal: boolean; sourcePages: string[]; error?: string } {
    return (
        typeof data.url === "string" &&
        (data.statusCode === null || data.statusCode === undefined || typeof data.statusCode === "number") &&
        (data.isInternal === undefined || typeof data.isInternal === "boolean") &&
        Array.isArray(data.sourcePages) &&
        data.sourcePages.every((page) => typeof page === "string") &&
        (data.error === undefined || typeof data.error === "string")
    );
}

Suggested change

	function isLinkCheckedData(
	data: Record<string, unknown>
	): data is { url: string; statusCode: number | null; isInternal: boolean; sourcePages: string[]; error?: string } {
	return typeof data.url === "string" && Array.isArray(data.sourcePages);
	}
	function isLinkCheckedData(
	data: Record<string, unknown>
	): data is { url: string; statusCode: number | null; isInternal: boolean; sourcePages: string[]; error?: string } {
	return (
	typeof data.url === "string" &&
	(data.statusCode === null || data.statusCode === undefined || typeof data.statusCode === "number") &&
	(data.isInternal === undefined || typeof data.isInternal === "boolean") &&
	Array.isArray(data.sourcePages) &&
	data.sourcePages.every((page) => typeof page === "string") &&
	(data.error === undefined || typeof data.error === "string")
	);
	}

Spotted by Graphite



Is this helpful? React 👍 or 👎 to let us know.

[devin-ai-integration]

Addressed in 03102c9: isLinkCheckedData now validates all fields — statusCode (number|null|undefined), isInternal (boolean|undefined), sourcePages (string[] with element check), and error (string|undefined).

[devin-ai-integration]

@claude review

[devin-ai-integration]

@claude review

[claude]

⚠️ Code review skipped — your organization's overage spend limit has been reached.

Code review is billed via overage credits. To resume reviews, an organization admin can raise the monthly limit at claude.ai/admin-settings/claude-code.

Once credits are available, reopen this pull request to trigger a review.