feat(cli): Add 'workflow doctor' command for TypeScript plugin setup diagnostics#1314
Open
TooTallNate wants to merge 1 commit intomainfrom
Open
feat(cli): Add 'workflow doctor' command for TypeScript plugin setup diagnostics#1314TooTallNate wants to merge 1 commit intomainfrom
TooTallNate wants to merge 1 commit intomainfrom
Conversation
…n setup Add a diagnostic command that checks common setup issues preventing the Workflow TypeScript Language Service Plugin from loading correctly in editors. Checks tsconfig.json plugin config, workspace TypeScript installation, VS Code settings, and CoC/Vim configuration.
|
Contributor
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
Contributor
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests🐘 Local Postgres (2 failed)nextjs-webpack-canary (1 failed):
nitro-stable (1 failed):
🌍 Community Worlds (56 failed)mongodb (3 failed):
redis (2 failed):
turso (51 failed):
📋 Other (1 failed)e2e-local-postgres-nest-stable (1 failed):
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
❌ 🐘 Local Postgres
✅ 🪟 Windows
❌ 🌍 Community Worlds
❌ 📋 Other
❌ Some E2E test jobs failed:
Check the workflow run for details. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new workflow doctor CLI command to diagnose common TypeScript plugin + editor setup issues for Workflow DevKit, with PASS/WARN/FAIL output and suggested fixes.
Changes:
- Introduces
Doctoroclif command with checks for tsconfig plugin configuration, required packages, and editor (VS Code / CoC) setup. - Adds best-effort VS Code extension detection plus
.vscode/settings.jsonandcoc-settings.jsonheuristics.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
Comment on lines
+46
to
+52
| async function readJson<T>(path: string): Promise<T | null> { | ||
| try { | ||
| const content = await readFile(path, 'utf-8'); | ||
| return JSON.parse(content) as T; | ||
| } catch { | ||
| return null; | ||
| } |
There was a problem hiding this comment.
readJson() uses JSON.parse, but both tsconfig.json and VS Code settings.json are commonly JSONC (comments/trailing commas). This will frequently return null and cause false FAIL/WARN results. Consider parsing with a JSONC-capable parser (e.g., jsonc-parser) or TypeScript's config parsing utilities instead of JSON.parse.
Comment on lines
+99
to
+103
| const plugins = tsconfig.compilerOptions?.plugins ?? []; | ||
| const hasWorkflowPlugin = plugins.some( | ||
| (p) => | ||
| p.name === 'workflow' || p.name === '@workflow/typescript-plugin' | ||
| ); |
There was a problem hiding this comment.
The tsconfig plugin check only inspects tsconfig.json directly and ignores extends (even though the type includes it). If the plugin is configured in a base config (a common setup), this will incorrectly report FAIL. Consider resolving the extends chain (and/or using TypeScript's config loader) before checking compilerOptions.plugins.
Comment on lines
+225
to
+252
| const homeDir = process.env['HOME'] ?? process.env['USERPROFILE'] ?? ''; | ||
| if (homeDir) { | ||
| const cocSettingsPath = join(homeDir, '.vim', 'coc-settings.json'); | ||
| const hasCocSettings = await fileExists(cocSettingsPath); | ||
|
|
||
| if (hasCocSettings) { | ||
| const cocSettings = | ||
| await readJson<Record<string, unknown>>(cocSettingsPath); | ||
| const useLocal = cocSettings?.['tsserver.useLocalTsdk'] === true; | ||
|
|
||
| if (useLocal) { | ||
| results.push({ | ||
| name: 'CoC (Vim) config', | ||
| status: 'pass', | ||
| message: 'coc-settings.json has tsserver.useLocalTsdk enabled.', | ||
| }); | ||
| } else { | ||
| results.push({ | ||
| name: 'CoC (Vim) config', | ||
| status: 'warn', | ||
| message: | ||
| 'coc-settings.json exists but tsserver.useLocalTsdk is not enabled. The Workflow plugin may not load.', | ||
| fix: 'Add to ~/.vim/coc-settings.json:\n\n { "tsserver.useLocalTsdk": true }', | ||
| }); | ||
| } | ||
| } | ||
| // Don't warn if no CoC settings — user might not use Vim | ||
| } |
There was a problem hiding this comment.
The CoC/Vim check only adds a result if ~/.vim/coc-settings.json exists (and only if HOME/USERPROFILE is set). That means the command often prints only 4 checks, which conflicts with the PR description/examples that show 5 checks always running. Consider always emitting a CoC result (e.g., PASS/SKIP message) even when the file isn't found.
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
| async function readJson<T>(path: string): Promise<T | null> { | ||
| try { | ||
| const content = await readFile(path, 'utf-8'); | ||
| return JSON.parse(content) as T; |
Contributor
There was a problem hiding this comment.
readJson uses JSON.parse() which fails on JSONC files (tsconfig.json, settings.json, coc-settings.json), causing the doctor command to report false failures/warnings for valid configuration files.
VaguelySerious
approved these changes
Mar 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
workflow doctorcommand that diagnoses common setup issues preventing the Workflow TypeScript Language Service Plugin from loading correctly in editorsChecks performed
compilerOptions.pluginscontains"workflow"or"@workflow/typescript-plugin"workflowis installed innode_modulestypescriptis installed locally (shows version)typescript.tsdkis configuredtsserver.useLocalTsdkis enabled in coc-settings.jsonExample output
Usage
Background
The
workflowTypeScript plugin requires editors to use the workspace TypeScript version rather than their bundled copy. When misconfigured, the plugin silently fails to load — no errors, no warnings, just missing functionality. This command helps users identify and fix these issues.