RFC: Community plugin registry contract + first-class plugin checks (registry v2 ? dsh plugin check ? dsh doctor)

[zoahdev]

RFC: Community plugin registry contract + first-class plugin checks

English below · 中文摘要见后

Summary

Three small, upstream-able pieces that make the plugin ecosystem safer to
use and easier to build on:

1. Community Plugin Registry Contract v2 — one shared JSON schema for
   plugin catalogs, so a single entry drives web storefronts, CLI sync tools,
   and in-harness agent tools identically.
2. dsh plugin check <dir|tarball> — a pre-publish gate with stable exit
   codes (0 pass / 1 fixable / 2 not a plugin).
3. dsh doctor [--profile P] — runtime diagnostics for a broken profile,
   with machine-readable JSON output.

All three have running, CI-green reference implementations and are verified
against the current release train (0.1.0-rc.6).

Problem

• The ecosystem has multiple marketplaces that each re-invent how a plugin
  entry is described (dsh-market, dsh-subscribe, DSH-Plugins-Marketplace,
  PR-based registries). Interop is impossible without a shared contract.
• Broken plugins (missing manifest, missing build artifact, wrong peer
  ranges) reach users because authors have no standard pre-publish gate.
• Support threads start from "plugin won't load" with no standard way to
  collect diagnostics.

Proposal

1. Community Plugin Registry Contract v2

registry.json v2 (schema in dsh-docs):

• id unique and stable (owner-suffix disambiguation for duplicate names)
• install.spec is the authoritative pnpm spec (github:owner/repo[#path:/sub] or npm name) — never guessed from homepage
• verified: true is a narrow claim (curator exercised CI + release + install + runtime smoke), never a security audit
• verified entries must declare a version
• source preserves provenance for mirrored entries
• count === plugins.length as a cheap structural invariant

Validation exists today: scripts/check-registry.mjs in
dsh-subscribe.

2. dsh plugin check

Exit codes: 0 pass, 1 fixable issues, 2 not a plugin. Checks that exist
in reference implementations today:

• cordis.patch.yml exists and inserts the declared id
• peer ranges match the tested release train
• build artifact exists and matches main
• tool schemas compile under the real runtime
• packed tarball loads and registers tools through apply()/ctx.tools.register

3. dsh doctor

• exit 0 healthy / 1 warnings / 2 broken
• --json output with check groups (env / profile / session)
• shadow-profile detection, module-drift detection, allowBuilds hints

Reference: dsh-plugin-doctor.

Reference implementations & evidence

Piece	Reference	Status
Registry contract v2 + validator	dsh-subscribe	536 plugins, 20 verified, validator CI-green
In-harness marketplace consuming the contract	dsh-subscribe v0.3	real one-click install via HTTP verified in CI
dsh plugin check equivalent	dsh-plugin-doctor preflight	CI-green
dsh doctor equivalent	dsh-plugin-doctor --profile --env --port	CI-green
Template with runtime peer guard	dsh-plugin-template	CI-green

Verification runs (all executed, not claimed):

node scripts/check-registry.mjs           → registry OK: 536 plugins, 20 verified
node --test tests/cli.test.mjs            → 4/4 pass
node --test test/plugin.test.mjs test/market-server.test.mjs → 9/9 pass
pnpm pack + runtime-smoke                → packed tarball loads, tools + 12 routes execute
fresh DSH profile → dsh web boot → POST /dsh-subscribe/install → real dsh CLI exit 0

Maintenance commitment

If upstream adopts any piece, zoahdev commits to: keeping the reference
implementations aligned with each release train, running compatibility
reports after every official release, and handing over clean patches the
moment the PR channel opens.

Adoption path

1. Discussion feedback on this RFC (now).
2. Clean patches submitted when upstream reopens PRs, or earlier if
   maintainers prefer discussion-first contributions.
3. dsh-docs keeps PR-ready documents mirrored to the official docs structure:
   zoahdev/dsh-docs.

Related: #1629 (plugin scaffolding RFC), #1719 (doctor spec), #1814
(adoption proposal), #1828 (dsh-subscribe showcase).

---

中文摘要

向官方提三件可采纳的小事：插件注册表契约 v2（一个 JSON schema 同时
驱动网页商店、CLI 同步和 agent 工具）、dsh plugin check（发布前检查，
退出码 0/1/2）、dsh doctor（运行时诊断，JSON 输出）。三个都有可运行、
CI 全绿的参考实现，并在 0.1.0-rc.6 上真机验证过。若官方采纳，zoahdev
承诺跟随每个 release train 维护、发版后出兼容性报告、PR 通道一开即交
干净补丁。欢迎官方与社区反馈。

[zoahdev]

Implementation-status update for this RFC (everything below is runnable and CI-green):

1. Registry contract v2 ? validator in dsh-subscribe (scripts/check-registry.mjs): 536 plugins / 20 verified, unique ids/specs enforced.
2. dsh plugin check surface ? dsh-plugin-doctor check <dir> (v1.7+): manifest ? patch ? entry ? files ? build ? pack ? fresh-profile install ? config; exit 0/1/2, --json.
3. dsh doctor diagnostics ? --profile (profile-shadow Bug: installing any plugin that depends on @deepseek-ai/dsh-tools breaks every tool call (Cannot read properties of undefined (reading 'prepare')) #1697, manifest-bom Bug: profile package.json with UTF-8 BOM crashes dsh web (Unexpected token ... is not valid JSON) #1842, large-files Bug: session search crashes with `RangeError: Invalid string length` on large sessions (root cause + fix) #1859), --env (win-bash 【Bug】Windows 上官方 minimal（极简模式）预设的 bash 无法启动：默认 shellPath /bin/bash 不可解析（实测+修复建议） #1856), --json with the dsh-doctor/v1 envelope; cross-implementation acceptance harness (doctor-contract-check.mjs) runs clean/BOM/shadow fixtures.
4. Consuming marketplace ? dsh-subscribe v0.3.1: in-harness storefront at /dsh-subscribe/ with one-click install/uninstall/update + allowBuilds approval, real HTTP install verified in CI.

All links and evidence are in the body. Happy to adjust naming/shape based on maintainer feedback ? the cheapest moment to change is now.

[zoahdev]

cc @imccyu @tianyicui ? this RFC is explicitly seeking maintainer feedback, so flagging it directly. Summary of what exists today (all runnable, all CI-green):

1. Registry contract v2 ? validator ships in dsh-subscribe (536 plugins / 20 verified).
2. dsh plugin check ? dsh-plugin-doctor check <dir> implements the proposed surface (exit 0/1/2, --json). Neutral demo on a third-party plugin (dsh-market@1.3.0, source tarball):

{ "ok": true, "checks": [
  { "name": "manifest", "status": "PASS", "detail": "dshmarket@1.3.0 bundle manifest ok" },
  { "name": "patch", "status": "PASS", "detail": "1 plugin row(s): dsh-market" },
  { "name": "entry", "status": "WARN", "detail": "entry lib/index.js not built yet ?" },
  { "name": "files", "status": "PASS" },
  { "name": "pre-execute-side-effects", "status": "PASS" } ] }

3. dsh doctor ? --profile (profile-shadow/manifest-bom/large-files), --env (win-bash), dsh-doctor/v1 envelope, cross-implementation acceptance harness.
4. Consuming marketplace ? in-harness storefront with one-click install (verified over HTTP in CI).

Five cherry-pick-ready patches are staged on the fork (see upstream-patches.md): #1697, #1842, #1856, #1861, #1869.

The cheapest moment to adjust naming/shape is now ? any maintainer feedback is welcome.

[moonquake2004]

Comprehensive RFC — all three pieces are the right call, and the reference implementations are genuinely CI-green on the current train. Three contributions from our side:

1. Pin the envelope as the dsh doctor --json contract. The doctor spec in #1719 has already converged on the dsh-doctor/v1 envelope ({ schema, exitCode, summary{pass,warn,fail}, ok, checks:[{name,status,detail}] }, lowercase status, exit 0/1/2) — emitted by both dsh-plugin-doctor (v1.6.0) and our dsh-doctor (0.2.5, --json --envelope). If the RFC adopts that shape, every consumer (CI, marketplace, support threads) gets interchangeable output from day one.

2. Add session-integrity depth to the dsh doctor session group. env/profile are well covered; the session group is our strong suit and the least specified here. We maintain 8 fixture-verified session checks, each mapped to a community report: seq == index continuity (chunk rows expanded like the harness's expandRow), post-end-seed replay, zstd single-frame containers (session.list 500), orphan tool calls, sourceEventSeqs drift, unknown event types, unclosed turns, and oversized-session heap estimation (corrupt → quarantine, oversized → cold-start stall risk). Happy to contribute these as the session group of the official doctor.

3. Reuse the fixture corpus. Our regression suite (54 tests: 20 built-in + 5 catalog checks, synthetic good/bad fixtures — including the #1724 patch-lint and #1697 host-shadowing cases) is a ready-made verification bed for whichever checks land. Offer it as the test corpus for dsh plugin check / dsh doctor.

Also: registry v2's install.spec matches how dshmarket already consumes awesome-dsh-plugin's plugins.json (npm name as the authoritative spec) — our entry there resolves via npm, so the contract is compatible with what's live today. Happy to align our check-ids and the envelope with whatever the official command settles on.

[moonquake2004]

One deeper layer worth adding to the RFC — not a competing proposal, but the ground underneath #2 and #3 that isn't specced anywhere yet: the lifecycle of the checks themselves.

The RFC standardizes the tools (registry contract, publish gate, doctor command). What it doesn't cover is how a check is born, proven correct, distributed, and kept honest over time. That's a real gap, because checks rot: every check encodes assumptions about harness internals (event-type tables, seq semantics, patch grammar, file layout), and every dsh release can silently invalidate them. Two data points from our side: our E6 check exists precisely because of this (it re-verifies at runtime that the contracts S6/S7/S10 rely on still exist in the installed dsh-session), and #1697/#1415 were both contract-drift crashes that no static list could have caught early. Even our own P3 shipped silently dead for months — a wrong regex matched nothing, so it always "passed" — until fixture testing found it.

Four properties would close this:

1. Checks are data, not code. Each check = a read-only probe definition + its target contract anchor + a good/bad fixture pair + the release train it was certified on. Distributed through a check registry (not a plugin registry) with TTL cache + offline fallback — our Layer-A catalog already does this live (5 catalog checks, shipped without any release).

2. Introspection instead of hardcoding. Read the installed harness's contracts (event-type table, module symbols, patch grammar) to derive or validate expectations, rather than baking them in. Upgrade → either the anchor passes (check still valid) or the tripwire fails loudly (no silent rot). Our S8 (parses the installed KNOWN_SESSION_EVENT_TYPES with a fallback) and E6 are the working seeds of this.

3. Certification gate. A check enters the ecosystem only if its fixture pair proves "good doesn't false-positive, bad gets caught" on the declared train. That's an upgrade of the doctor-contract-check idea: from certifying output shape to certifying check correctness. Our 54-test corpus (incl. the #1724 patch-lint and #1697 shadowing fixtures) is a ready-made harness for this.

4. Evolution loop. Community report → candidate check → fixture certification → catalog distribution → auto-update. The diagnostic layer itself "evolves on the fly" — the paper's theme, applied to the diagnostics.

If the RFC keeps the check inventory as a plain list, each of these stays unsolved and every future check re-invents them. If it adopts "checks as data + fixture certification + anchor introspection" as the foundation, #2 and #3 become instances of one mechanism. Happy to contribute the Layer-A catalog, the fixture corpus, and the E6/S8 introspection machinery as the reference implementation for this layer.