Preface

DSH uses an “everything is a plugin” architecture. When developing or maintaining DSH instances, startup failures after installing or upgrading plugins are a common issue. When the Web UI cannot open, identifying the root cause (such as duplicate loader IDs, missing patches, or configuration conflicts) is usually difficult.

dsh-composition-doctor is designed to solve this problem. It links known failure modes to the Bundle, Patch, or Profile layer and tells you which source to inspect next without starting a DSH instance.

What Is It?

dsh-composition-doctor is a client diagnostic tool maintained by lemonxiny55. It explains DSH plugin failures by analyzing static metadata, including duplicate insertions, missing patches, and peer dependency mismatches. The current version is 0.4.0.

Installation

Install the global CLI using npm (note: ignore build scripts):

npm install -g dsh-composition-doctor@0.4.0 --ignore-scripts

After installation, verify the version:

dsh-doctor --version

Prerequisite: The runtime environment must support Node.js >= 20.

Core Features

  1. Read-only and offline: Diagnostics are offline by default, without auto-fixing configuration, accessing the network, or starting DSH processes.
  2. Failure detection: It can detect the following issues:
    • Duplicate loader IDs.
    • Bundles unavailable.
    • Missing or invalid bundle patches.
    • Missing target declarations.
    • Peer version/dependency mismatches.
    • Configuration replacement or override.
  3. Output support: Supports piping and structured output (such as JSON or Markdown).
  4. Web explorer: Provides an optional web interface for viewing reports.

Usage Examples

Basic Check

Check the static metadata of a specified profile:

dsh-doctor check --profile "$HOME/.dsh/profiles/web"

Diagnostic Log

Diagnose using an error log:

dsh-doctor diagnose --profile "$HOME/.dsh/profiles/web" --log ./minimal-error.log

Structured Output

Output structured results in JSON format:

dsh-doctor diagnose --profile "$HOME/.dsh/profiles/web" --format json

Inspect Sources and Impact

Inspect the source chain for a specific row, or inspect the impact scope of a specific Bundle:

dsh-doctor why row tool-bash --profile C:\path\to\profile
dsh-doctor impact bundle @example/dsh-bundle --profile C:\path\to\profile

How It Works and Caveats

  • Static analysis: The check and diagnose commands only inspect static metadata; they do not import plugin code, run lifecycle scripts, or access the network.
  • Misjudged health status: If the output is unknown, no-match, or the exit code is 0, this does not mean the configuration is healthy. It may mean that the plugin cannot detect known failure modes.
  • No automatic repair: This tool only provides diagnostic information and does not automatically modify your Profile configuration.

Summary

dsh-composition-doctor is a practical CLI tool for troubleshooting DSH plugin failures. It helps you quickly identify the root cause when DSH cannot start by analyzing static metadata.