Skip to content

feat: major workos doctor overhaul — visual refresh, multi-language, AI analysis#62

Merged
nicknisi merged 12 commits intomainfrom
nicknisi/doctor-improvements
Feb 18, 2026
Merged

feat: major workos doctor overhaul — visual refresh, multi-language, AI analysis#62
nicknisi merged 12 commits intomainfrom
nicknisi/doctor-improvements

Conversation

@nicknisi
Copy link
Member

@nicknisi nicknisi commented Feb 18, 2026 •
edited
Loading

Summary

Major overhaul of workos doctor across four areas: visual identity, multi-language support, AI-powered analysis, and auth pattern detection.

Visual refresh

  • Branded lock character with expressions: success (◠ ◠), warning (• •), error (× ×)
  • Lock appears in doctor summary, installer completion, and TUI dashboard
  • Summary box with dynamic width and word-wrapping for narrow terminals
  • Unicode + ASCII fallback for all art

Multi-language detection

  • Detects project language from manifest files: Go, Ruby, Python, Java, PHP, .NET, JS/TS
  • Expanded framework detection: Expo (managed/bare), React Native, SvelteKit, Nuxt (2/3), Vue.js, Astro, Svelte
  • Non-JS SDK detection from requirements.txt, Gemfile, go.mod, pom.xml, build.gradle, composer.json, *.csproj
  • Language-aware install hints in issue remediation

AI-powered analysis

  • One-shot API call to LLM gateway using Haiku for fast, low-cost diagnostics
  • SDK knowledge injected into prompt to prevent false positives (e.g. @workos-inc/node flagged as incompatible with Expo)
  • Deduplicates against static checks — AI only reports issues the deterministic checks missed
  • Graceful degradation: skips when unauthenticated, surfaces credential diagnostics on failure
  • Configurable model via doctorModel in cli config

Auth pattern detection

  • 11 framework-specific anti-pattern checks (Next.js, React Router, TanStack Start)
  • Catches P0-class bugs like GET signout routes + <Link> prefetching
  • Detection via file existence + regex — no AST parsing, no new dependencies

Check Catalog

Errors (high-confidence — almost certainly wrong):

Code Description Frameworks
SIGNOUT_GET_HANDLER GET route handler at signout/logout path — should be POST/server action Next.js
MISSING_MIDDLEWARE No middleware.ts/proxy.ts at project root — AuthKit sessions won't work Next.js
API_KEY_LEAKED_TO_CLIENT Secret API key in client-prefixed env var (NEXT_PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_) All
CALLBACK_ROUTE_MISSING Redirect URI configured but no matching route file exists Next.js, React Router, TanStack Start

Warnings (lower-confidence — suspicious but may be intentional):

Code Description Frameworks
SIGNOUT_LINK_PREFETCH <Link>/<NextLink> pointing to signout/logout — triggers prefetch in production Next.js
MIDDLEWARE_WRONG_LOCATION middleware.ts found inside app/ instead of project root Next.js
MISSING_AUTHKIT_PROVIDER AuthKitProvider not found in root layout Next.js, React Router (declarative)
WRONG_CALLBACK_LOADER Callback route uses authkitLoader instead of authLoader React Router
MISSING_ROOT_AUTH_LOADER Root route doesn't use authkitLoader for auth context React Router
MISSING_AUTHKIT_MIDDLEWARE start.ts doesn't reference authkitMiddleware TanStack Start
COOKIE_PASSWORD_TOO_SHORT WORKOS_COOKIE_PASSWORD set but < 32 characters React Router, TanStack Start

Credential storage fix

  • saveCredentials now writes to both keyring AND file — file persists across binary rebuilds where macOS invalidates keyring access due to code signature changes
  • Added diagnoseCredentials() for debugging auth failures

Files Changed

  • New: src/utils/lock-art.ts, src/utils/summary-box.ts — branded visual components
  • New: src/doctor/checks/language.ts — multi-language detection
  • New: src/doctor/checks/ai-analysis.ts, src/doctor/agent-prompt.ts — AI analysis
  • New: src/doctor/checks/auth-patterns.ts — anti-pattern detection (11 checks)
  • Modified: src/doctor/checks/framework.ts — 7 new frameworks
  • Modified: src/doctor/checks/sdk.ts — non-JS SDK detection
  • Modified: src/lib/credential-store.ts — dual-write + diagnostics
  • Modified: src/doctor/output.ts, src/doctor/index.ts, src/doctor/types.ts — wiring
  • Tests: 8 new/modified spec files, 536 total tests passing

@nicknisi
feat: add auth pattern analysis to workos doctor
9ceaa89 
Detect AuthKit-specific integration anti-patterns by scanning project
code via file existence checks and regex matching (no AST parsing).

Checks (11 total):
- SIGNOUT_GET_HANDLER: GET route at signout/logout path (error)
- SIGNOUT_LINK_PREFETCH: <Link>/<NextLink> to signout path (warning)
- MISSING_MIDDLEWARE: No middleware.ts/proxy.ts for Next.js (error)
- MIDDLEWARE_WRONG_LOCATION: middleware inside app/ dir (warning)
- MISSING_AUTHKIT_PROVIDER: No AuthKitProvider in root layout (warning)
- CALLBACK_ROUTE_MISSING: No route at redirect URI path (error)
- API_KEY_LEAKED_TO_CLIENT: Secret key in NEXT_PUBLIC_/VITE_/etc (error)
- WRONG_CALLBACK_LOADER: authkitLoader on callback route (warning)
- MISSING_ROOT_AUTH_LOADER: Root route missing authkitLoader (warning)
- MISSING_AUTHKIT_MIDDLEWARE: TanStack start.ts missing middleware (warning)
- COOKIE_PASSWORD_TOO_SHORT: Password < 32 chars (warning)

Framework-aware for Next.js, React Router, and TanStack Start.
Resolves callback path from NEXT_PUBLIC_WORKOS_REDIRECT_URI when set.
@nicknisi
chore: formatting
bc964b2
@nicknisi
feat: add branded lock character and summary box to doctor and installer
49eb74a 
Add a WorkOS lock ASCII art character with expressions (success/warning/error)
and a summary box renderer used by both doctor output and installer completion
screens. The lock shackle opens on error state. Box width adapts to terminal
size with word-wrapping for narrow terminals.
@nicknisi
feat: add multi-language detection and expanded framework support to …
827b3ab 
…doctor

Add language detection (Python, Ruby, Go, Java, PHP, .NET, JS/TS) from
manifest files. Expand framework detection with Expo, React Native,
SvelteKit, Vue/Nuxt, Astro, and Svelte. Detect non-JS WorkOS SDKs from
requirements.txt, Gemfile, go.mod, pom.xml, composer.json, and .csproj.
Language-aware install hints in issue remediation.
@nicknisi
feat: add AI-powered project analysis to workos doctor
2fb2937 
Add Claude Agent SDK (Sonnet) integration for doctor that analyzes the
project with read-only tools and provides tailored, framework-specific
recommendations. Runs through LLM gateway with credential proxy auth.
Includes --skip-ai flag for offline use, 60s timeout, graceful
degradation on auth/parse failures, and structured JSON response parsing.
@nicknisi
fix: rewrite AI analysis as direct API call with one-shot token refresh
133f18e 
Replace Claude Agent SDK subprocess with a single Anthropic SDK API call
to the LLM gateway. No credential proxy — reads access token directly,
refreshes once if expired. Adds configurable doctorModel (default Haiku)
and a spinner during analysis. Fixes credential corruption caused by
proxy token rotation during short-lived doctor runs.
@nicknisi
fix: improve AI prompt accuracy, credential resilience, and lock art
c2b205d 
- Add WorkOS SDK knowledge to AI prompt to prevent false positives
  (e.g. flagging @workos-inc/node as incompatible with Expo/RN)
- Tighten AI analysis rules: fewer speculative findings, no contradicting
  SDK knowledge section
- Fix credential storage: always write file fallback alongside keyring
  to survive binary rebuilds (macOS code signature invalidation)
- Add credential diagnostics for debugging auth failures
- Fix error lock art: shackle present but not connected to body
- Formatting pass
@nicknisi
fix: improve look of lock guy
47d4b07
@nicknisi nicknisi force-pushed the nicknisi/doctor-improvements branch from 99ec24e to 47d4b07 Compare February 18, 2026 17:43
@nicknisi nicknisi changed the title feat: add auth pattern analysis to workos doctor feat: major workos doctor overhaul — visual refresh, multi-language, AI analysis Feb 18, 2026
@nicknisi
feat: add cross-language checks and fix non-JS project support
93de578 
- Add 3 cross-language auth pattern checks that run for all projects:
  API_KEY_IN_SOURCE, ENV_FILE_NOT_GITIGNORED, MIXED_ENVIRONMENT
- Remove isAuthKit gate so auth patterns run for non-JS projects too
- Fix process.exit crash when running doctor in projects without
  package.json (replaced getPackageDotJson with direct file reads)
- Hide Node.js runtime line for non-JS projects
@nicknisi
chore: remove verbose logging and redundant comments
3f38947
@nicknisi
refactor: simplify doctor code and reduce duplication
2384c60 
- Extract shared readPackageJson into package-json.ts
- Extract renderCompletionSummary to dedupe adapter code
- Inline single-use callApi into callModel
- Consolidate token expiration branches
- Replace dotenv with inline parseEnvFile in auth-patterns
- Remove dynamic imports, unused params, and no-op ternary
@nicknisi
chore: formatting
c185da6
@nicknisi nicknisi merged commit 014fbbc into main Feb 18, 2026
5 checks passed
@nicknisi nicknisi deleted the nicknisi/doctor-improvements branch February 18, 2026 19:59
@github-actions github-actions bot mentioned this pull request Feb 18, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@nicknisi

Comments