dsh-plugin-doctor

dsh-plugin-doctor

A DeepSeek Harness host plugin and CLI that audits a repository against the mechanical rules the dsh-plugin directory enforces on a submission — the rules that a repository can satisfy silently, or fail silently, long before a maintainer reads it.

It registers one model-facing tool, plugin_doctor, and ships the same engine as a CLI. Both are read-only: nothing is written to the audited repository, and no network request is made unless network is true.

What it checks

Up to fifteen checks run. Which ones depends on what the repository declares — a repository with no parseable manifest runs fewer — and two run only when their condition exists (a patch outside the package directory, a peer range this checker cannot model).

Every failure names the concrete fix. The CLI exits 0 when no check fails (and, under --strict, no warning fails), 1 when one does, and 2 on a usage error.

Install

Into a profile, once published to npm:

dsh plugin --profile web add dsh-plugin-doctor

From this repository, before any npm release:

dsh plugin --profile web add github:Tim-ReJet/dsh-plugin-doctor

Both append the bundle layer to that profile's dsh.profile.bundles; the layer inserts one host row named plugin-doctor. Confirm the layer composed:

dsh --profile web --dump-config | grep -A 3 plugin-doctor

For local development against a source checkout, skip the install and load the entry point with a patch overlay:

# doctor.overlay.yml
- insert:
    - id: plugin-doctor
      name: '/absolute/path/to/dsh-plugin-doctor/src/index.js'
      config:
        path: '/absolute/path/to/the/repository/you/are/auditing'

dsh --profile web --patch ./doctor.overlay.yml

Use

The tool, from any session where the plugin is composed:

Run plugin_doctor on this repository and fix what it reports.

It returns ok, errors, warnings, and a report. Its path, strict, and network parameters default to the row configuration in cordis.patch.yml.

The CLI, from a checkout — no install required:

node bin/dsh-plugin-doctor.mjs [path]

--emit-entry always single-quotes and escapes the description, because a bare scalar breaks on a colon, on # (silently truncating it) and on a leading YAML indicator such as @. In a monorepo it points the entry at the subpackage that declares dsh.bundle.

The prerelease trap this exists for

An installable plugin peers on the harness packages. Almost every range that looks right is wrong for a prerelease harness, because node-semver admits a prerelease version only when some comparator in the matching branch carries a prerelease tag on the same major.minor.patch tuple:

// looks broad, silently excludes every 0.1.1-* and 0.2.0-* build
"@deepseek-ai/dsh-tools": ">=0.1.0-rc.1 <0.3.0-0"
"@deepseek-ai/dsh-tools": "*"

// admitted: the branch names the tuple with a prerelease tag
"@deepseek-ai/dsh-tools": ">=0.1.1-rc.1 <0.1.2-0 || >=0.2.0-rc.1 <0.2.1-0"

manifest.peer-prerelease reports which of the two failures applies. The checker is not a semver implementation: it models caret, tilde, hyphen, x-ranges, and comparison operators, and its expected answers are pinned to what node-semver itself answered for 450 recorded (range, version) pairs in tests/fixtures/node-semver-table.json. Anything it cannot parse is reported as manifest.peer-range-parsed instead of being guessed at.

What it cannot check

• Whether the plugin does what its description says. That is what a maintainer reads the source for, and no checker replaces it. Do not treat a clean run as that review.
• Security. Being listed is not a security review, and neither is this. The audit reads manifests and structure, not behaviour.
• The rest of the submission surface: the entry file beyond what --emit-entry prints, screenshots.json rules, tarball hosting rules, and whether a bundle's dependencies point at the original author's repository rather than a re-upload.
• Whether the code is real rather than a stub. A file that exports nothing still counts as an implementation file here.
• Whether the category fits, or whether the plugin duplicates an existing entry.
• Whether the project is actively maintained. The directory's periodic scan flags repositories that are gone, archived, or long dormant; this audit reads one moment in time.
• npm publication and download counts. Listing does not depend on them.

Verification

• npm test runs 40 tests on node:test with no network: fixtures are throwaway repositories in the temp directory, and the prerelease gate is checked against the recorded node-semver table. The package declares no dependencies — the audit engine and CLI need none; the host plugin needs its declared peers, and the four host-plugin tests skip when those peers are not resolvable.
• The repository audits itself to zero errors apart from repo.age, which fails until the repository is a day old — the directory's own rule. npm run doctor therefore exits 1 today and 0 tomorrow; a test covers the same run with the clock moved past the gate.
• End to end, in a real harness with the plugin composed and a model calling the tool: verified on harness 0.1.1-rc.2 and 0.2.0-rc.2, the two lines its peer range names.
• The install path was walked by hand on 2026-10-04 and is reproducible with npm run verify:install (network required): it installs github:Tim-ReJet/dsh-plugin-doctor into a throwaway profile, checks the bundle layer composed, and removes the profile. No automated test covers it.

Peer dependencies

@deepseek-ai/dsh-tools and @deepseek-ai/schemastery are peerDependencies, so the profile supplies one copy each; @deepseek-ai/cordis is a stable 4.x line and is declared ^4.0.1. The harness range names an explicit prerelease branch per tuple, as the directory requires.

Getting listed

The directory is awesome-dsh-plugin/awesome-dsh-plugin; contributing.md is the contract this plugin checks. Listing takes one file in a pull request — data/plugins/<owner>__<repo>.yml, which --emit-entry prints — plus the dsh-plugin topic on the repository and a repository at least a day old.

dshmarket installs only sources named in that curated registry, so carrying the topic alone makes a repository discoverable under the topic, not installable from the market.

License

MIT