feat: add workos doctor command for diagnosing integration issues

[nicknisi]

Summary

Adds workos doctor — a diagnostic command that detects common WorkOS integration issues in one command. DSE team spends significant time in support conversations gathering basic diagnostic information ("What SDK?", "What version?", "Redirect URI?"). This command automates that info-gathering so customers can run a single command and share the output.

What it does

Runs a suite of diagnostic checks against the user's project:

• SDK detection — Finds installed WorkOS SDK (@workos/*, @workos-inc/*, workos), reports version, checks npm registry for latest
• Framework detection — Identifies Next.js (app/pages router variant), React Router, TanStack Start, Remix, Express
• Runtime info — Node.js version, package manager + version
• Environment config — Checks .env/.env.local for WORKOS_API_KEY, WORKOS_CLIENT_ID, WORKOS_REDIRECT_URI, WORKOS_COOKIE_DOMAIN, WORKOS_BASE_URL. Identifies staging vs production from key prefix
• API connectivity — Tests reachability + latency to api.workos.com
• Credential validation — Validates API key against WorkOS API (staging only, never production)
• Dashboard settings — Fetches auth methods, MFA policy, session timeout, org count (staging only)
• Redirect URI inference — Infers expected callback URI from framework detection when not explicitly configured
• Issue detection — Every detected issue includes specific remediation steps and docs links

CLI flags

Flag	Description
--json	Output report as JSON (machine-readable for future tooling)
--copy	Copy report to clipboard
--verbose	Include additional diagnostic details
--skip-api	Offline mode — skip all API calls
--install-dir	Target a specific project directory

Security

• API keys are never displayed — only status (configured / not set) and type (staging / production)
• Client IDs are truncated (client_01J...7KM)
• Production API keys are never sent to any API endpoint
• Raw credentials are kept in an internal-only type (EnvironmentRaw) and excluded from report output

Exit codes

• 0 — healthy, no errors
• 1 — critical issues found (or doctor itself failed)

Architecture

src/
├── commands/doctor.ts          # CLI handler (yargs → runDoctor → outputReport)
├── doctor/
│   ├── index.ts                # Orchestrator: runs checks, detects issues, outputs report
│   ├── types.ts                # All type definitions (DoctorReport, Issue, SdkInfo, etc.)
│   ├── issues.ts               # Issue detection rules + remediation definitions
│   ├── output.ts               # Terminal formatter (chalk, emoji indicators)
│   ├── json-output.ts          # JSON serializer
│   ├── clipboard.ts            # Cross-platform clipboard (pbcopy/xclip/clip.exe)
│   └── checks/
│       ├── sdk.ts              # SDK detection + npm registry latest version
│       ├── framework.ts        # Framework detection + Next.js variant
│       ├── runtime.ts          # Node.js + package manager detection
│       ├── environment.ts      # .env/.env.local parsing via dotenv
│       ├── connectivity.ts     # API health check + latency
│       └── dashboard.ts        # Dashboard API calls + credential validation
└── bin.ts                      # yargs command registration

Checks run concurrently via Promise.all where possible (SDK, framework, runtime, connectivity), then sequential for checks that depend on environment results (credential validation, dashboard settings).

Success criteria from contract

• Runs in any Node.js project with WorkOS SDK installed
• Detects SDK name, version, and latest available
• Detects Node.js runtime version
• Detects framework and version
• Detects package manager
• Reports environment configuration (API key status, Client ID, base URL)
• Identifies staging vs production from API key prefix
• Tests API connectivity and latency
• Fetches dashboard settings for staging environments
• Clean terminal output with indicators
• JSON output via --json
• --copy flag for clipboard
• Each issue includes remediation steps or docs links