Skip to content

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

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

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

Conversation

@nicknisi

@nicknisinicknisi commented Feb 18, 2026•
edited
Loading

Copy link
Copy Markdown
Member

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):

CodeDescriptionFrameworks
SIGNOUT_GET_HANDLERGET route handler at signout/logout path — should be POST/server actionNext.js
MISSING_MIDDLEWARENo middleware.ts/proxy.ts at project root — AuthKit sessions won't workNext.js
API_KEY_LEAKED_TO_CLIENTSecret API key in client-prefixed env var (NEXT_PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_)All
CALLBACK_ROUTE_MISSINGRedirect URI configured but no matching route file existsNext.js, React Router, TanStack Start

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

CodeDescriptionFrameworks
SIGNOUT_LINK_PREFETCH<Link>/<NextLink> pointing to signout/logout — triggers prefetch in productionNext.js
MIDDLEWARE_WRONG_LOCATIONmiddleware.ts found inside app/ instead of project rootNext.js
MISSING_AUTHKIT_PROVIDERAuthKitProvider not found in root layoutNext.js, React Router (declarative)
WRONG_CALLBACK_LOADERCallback route uses authkitLoader instead of authLoaderReact Router
MISSING_ROOT_AUTH_LOADERRoot route doesn't use authkitLoader for auth contextReact Router
MISSING_AUTHKIT_MIDDLEWAREstart.ts doesn't reference authkitMiddlewareTanStack Start
COOKIE_PASSWORD_TOO_SHORTWORKOS_COOKIE_PASSWORD set but < 32 charactersReact 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
nicknisiforce-pushed the nicknisi/doctor-improvements branch from 99ec24e to 47d4b07CompareFebruary 18, 2026 17:43
@nicknisinicknisi changed the title feat: add auth pattern analysis to workos doctorfeat: major workos doctor overhaul — visual refresh, multi-language, AI analysisFeb 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 mainFeb 18, 2026
5 checks passed
@nicknisi
nicknisi deleted the nicknisi/doctor-improvements branch February 18, 2026 19:59
@github-actionsgithub-actionsBot mentioned this pull request Feb 18, 2026
Merged
lucasmotta added a commit that referenced this pull request Feb 20, 2026
@lucasmotta
Merge remote-tracking branch 'origin/main' into feature/explore-widge…
843ef2b
…ts-skills
* origin/main: (21 commits)
chore(main): release 0.7.2 (#67)
fix: Correct issue submission links (#66)
chore(main): release 0.7.1 (#65)
fix: ground AI analysis in SDK documentation (#64)
chore(main): release 0.7.0 (#60)
fix: improve installer skill and remove shell: true from spawn calls (#63)
feat: major workos doctor overhaul — visual refresh, multi-language, AI analysis (#62)
fix: replace dotenv devDependency with inline env parser in doctor (#61)
feat: add environment, organization, and user management commands (#59)
chore(main): release 0.6.0 (#58)
feat: agent self-correction via validation feedback loop (#57)
chore(main): release 0.5.4 (#56)
fix: restore workflow_call and remove registry-url for OIDC
chore(main): release 0.5.3 (#55)
fix: trigger release.yml directly via release event for OIDC match
fix: remove registry-url from setup-node to unblock OIDC auth
chore(main): release 0.5.2 (#54)
fix: use npm publish for OIDC trusted publishing support
chore(main): release 0.5.1 (#53)
fix: remove duplicate release trigger causing publish race condition
...
# Conflicts:
#	src/lib/adapters/cli-adapter.ts
This was referenced Mar 26, 2026
Merged
Merged
Sign up for freeto 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