Feature: add vendure doctor diagnostics command

[dlhck]

Problem

Vendure projects can fail in ways that are common but time-consuming to identify: duplicate dependency versions, mismatched Vendure package versions, invalid config imports, plugin compatibility problems, GraphQL package duplication, database/schema drift, or production-unsafe settings.

These issues are especially costly during support and debugging because developers and agents often start by investigating application code before first excluding known environmental and dependency problems.

A vendure doctor command would give developers and AI agents a reliable first step in the debugging process: run a read-only diagnostic suite, rule out common project/setup issues, and produce actionable output that can be pasted into issues or support threads.

Proposal

Add a new CLI command:

vendure doctor
vendure doctor --config ./src/vendure-config.ts
vendure doctor --check dependencies --check config
vendure doctor --profile production
vendure doctor --format json
vendure doctor --strict

The command should be non-interactive and safe to run in CI, local terminals, and agent workflows. It should not mutate the project or database.

Example checks

Project and dependency checks

• Verify the current directory is a Vendure project.
• Verify there is exactly one resolvable Vendure config, or explain when --config is needed.
• Detect mismatched versions across installed @vendure/* packages.
• Detect duplicate installed versions of critical singleton-style dependencies, especially graphql.
• Detect multiple installed versions of TypeORM, NestJS, Apollo, or other dependencies where duplication can cause runtime/type identity bugs.
• Verify the configured database driver package is installed.
• Report package manager and lockfile inconsistencies.

Config checks

• Import the Vendure config using the same TypeScript/path-mapping behavior as other CLI commands.
• Run Vendure config preprocessing without starting the HTTP server.
• Validate custom fields, plugin entities, metadata modifiers, and plugin compatibility ranges.
• Verify GraphQL schemas can be built for Admin and Shop APIs.

Database checks

• Optionally verify DB connectivity.
• Detect pending migrations.
• Detect schema drift between the configured entities/custom fields and the current database schema.
• Warn about risky combinations such as synchronize: true with migrations.

Production profile checks

With --profile production, warn about settings commonly unsafe in production:

• authOptions.disableAuth enabled.
• Default superadmin credentials.
• Cookie auth without a stable cookie secret.
• GraphQL playground/debug/introspection enabled.
• Broad CORS with credentials.
• In-memory job queue/cache/session strategies.
• Missing asset storage/preview configuration.

Output

Default output should be concise and grouped:

Vendure Doctor

Project        pass  Vendure config found at src/vendure-config.ts
Dependencies  fail  Multiple graphql versions installed: 16.8.1, 16.11.0
Config         pass  Vendure config loaded and plugin configuration completed
Schema         pass  Admin and Shop schemas generated successfully
Database       warn  2 pending migrations found

Result: failed

--format json should emit structured output for agents and CI tooling.

Implementation notes

The CLI already has most of the needed building blocks:

• packages/cli/src/commands/command-declarations.ts for registering the command.
• VendureConfigRef and loadVendureConfigFile() for config discovery and loading.
• preBootstrapConfig() in core for validating runtime config without starting the server.
• Migration/schema-builder logic in packages/core/src/migrate.ts that could be refactored into reusable read-only helpers for drift and pending-migration checks.

A first version could focus on project detection, dependency duplication/version checks, config import, preBootstrapConfig() validation, and schema generation. DB connectivity and schema drift could be opt-in or a follow-up if needed.

Why this matters

This would improve the debugging workflow for both humans and agents. Before digging into application-specific code, they can run vendure doctor to exclude common Vendure environment problems and produce a compact diagnostic report. That should reduce issue back-and-forth, make support requests more actionable, and catch known dependency/setup problems such as duplicate graphql versions much earlier.

[Ryrahul]

Hi @dlhck , this is a great idea. Is anyone from the core team already working on this, or are external contributions welcome? I'd be happy to raise a PR and incorporate any feedback.

[dlhck]

@Ryrahul yes, if you want you can provide a PR for this!