feat: Add unrag doctor command for installation validation and troubleshooting

[pingSubhajit]

Summary

This PR introduces the unrag doctor command, a comprehensive diagnostic tool for validating Unrag installations, detecting configuration issues, and troubleshooting common problems before they become production issues.

Motivation

Unrag is vendored source code, meaning users own and can modify it. This flexibility comes with a trade-off: there's no central registry tracking what's installed or whether it's configured correctly. Users might add an extractor but forget to register it, set up a database schema but miss an important index, or misconfigure environment variables.

The doctor command addresses this by providing automated validation that surfaces issues early.

Features

Static Checks (default)

• Installation integrity validation (unrag.json, config file, install directory structure)
• Environment variable verification based on detected embedding provider and store adapter
• Module presence checks for extractors and connectors
• Configuration coherence analysis (detects extractors installed but not registered/enabled)

Database Checks (--db flag)

• PostgreSQL connectivity verification
• pgvector extension validation
• Schema and table structure verification
• Index recommendations (btree on source_id, vector indexes for large datasets)
• Embedding dimension consistency detection

Setup Wizard (doctor setup subcommand)

• Interactive configuration generator
• Creates .unrag/doctor.json with project-specific settings
• Adds convenience scripts to package.json:
  • unrag:doctor - run static checks
  • unrag:doctor:db - run with database checks
  • unrag:doctor:ci - strict mode with JSON output for CI pipelines

CLI Options

unrag doctor [options]
  --config <path>         Load settings from a doctor config file
  --db                    Run database checks
  --json                  Output results as JSON (for CI)
  --strict                Treat warnings as failures
  --project-root <path>   Override project root directory
  --install-dir <path>    Override Unrag install directory
  --schema <name>         Database schema name (default: public)
  --scope <prefix>        Limit dimension checks to sourceId prefix
  --database-url <url>    Database connection string
  --database-url-env <name>  Env var name for database URL
  --env-file <path>       Load env vars from a specific .env file

Exit Codes

• 0: All checks passed (warnings allowed unless --strict)
• 1: One or more checks failed
• 2: Doctor could not run (internal error)

Files Changed

• Added cli/commands/doctor.ts - main doctor command implementation
• Added cli/commands/doctor-setup.ts - setup wizard implementation
• Added cli/lib/doctor/ - supporting modules:
  • types.ts - shared types and provider configurations
  • infer.ts - installation state inference
  • staticChecks.ts - static validation checks
  • configScan.ts - configuration coherence analysis
  • dbChecks.ts - database validation checks
  • doctorConfig.ts - config file handling
  • env.ts - environment file loading
  • output.ts - report formatting
• Updated cli/run.ts - registered doctor command
• Added comprehensive documentation in docs/guides/doctor.mdx
• Updated CLI reference documentation
• Added tests for doctor setup command

Testing

• Added test/doctor-setup.test.ts with comprehensive test coverage for the setup wizard
• Manual testing performed for all check categories

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
unrag-web	Ready	Preview, Comment	Jan 9, 2026 4:41am