dsh-plugin-guide 0.4.3 → 0.4.5

package/docs/recipes.md

@@ -0,0 +1,251 @@
+# Recipes: copy these, then re-run the checker
+
+<a id="before-you-copy"></a>
+## Before you copy
+
+Every block below was run against `dsh-standards` `40-checker` (`0.1.0`,
+anchor `ce7073d51254`, default runtime `0.2.2-alpha.2`). The package name
+`@acme/dsh-hello` is a placeholder — replace it everywhere, including the patch
+row. The numbers in the verify sections are what the checker printed here; if
+your output differs, the diff line is your fix.
+
+<a id="minimal-packagejson"></a>
+## Minimal `package.json`
+
+A plugin that exports `apply`, registers one tool, and can also be composed as
+a bundle row.
+
+```json
+{
+  "name": "@acme/dsh-hello",
+  "version": "0.1.0",
+  "description": "Minimal DSH plugin that registers one tool.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": ["index.js", "cordis.patch.yml"],
+  "engines": {
+    "node": ">=24.9.0",
+    "dsh": ">=0.2.2-0 <0.3.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": ">=0.2.2-0 <0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh": { "optional": true }
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "kind": "plugin",
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "capabilities": ["tools:register"],
+    "labels": []
+  }
+}
+```
+
+| Field | What it buys | Check |
+|---|---|---|
+| `name` + exact `version` | a resolvable identity; a range or tag here is a FAIL | `C-1.1` |
+| `exports["."]` (or `main`) | the entry must resolve to a file inside the package | `C-1.2` |
+| `files` including the entry and patch | not checked, but `npm pack` can otherwise ship a manifest whose entry is absent | — |
+| `engines.dsh` | the only declaration that decides compatibility alone; `workspace:` is a FAIL | `C-2.1`/`C-2.3` |
+| `license` | avoids the `C-1.5` WARN; SPDX string | `C-1.5` |
+| `dsh.bundle.patch` | the file a bundle layer composes; in-package relative path | `C-1.4` |
+| `dsh.capabilities` | declares the host surfaces you touch; closed set of 15 | `C-11.1` |
+| `dsh.labels` | declares high-risk categories; closed set of 5; `[]` is allowed | `C-13.1` |
+| `dsh.kind` | `plugin` gets L1; `bundle` gets G0–G3; a client is static-only | `DSC-14` |
+
+Notes that come from the checker, not taste:
+
+- `dsh.capabilities` and `dsh.labels` are **standard extensions**: this host
+  does not read them. They are declarations, not enforcement. Declaring them
+  does not make the plugin safe, and omitting them is a WARN today.
+- `dsh.manifestVersion`, `dsh.bundle`, `dsh.client` are host fields; keep
+  `manifestVersion: 1`.
+- `engines.node` is **not** checked by the checker. Keep it for humans, but do
+  not expect a check to fail without it.
+
+<a id="entry-module"></a>
+## The entry module
+
+`C-1.2` resolves the entry, so the file must exist. `DSC-10` and `DSC-06` both
+look at what runs when and how it is cleaned up.
+
+```js
+export const name = 'dsh-hello'
+export const inject = []
+
+export function apply(ctx) {
+  ctx.effect(() => {
+    const timer = setInterval(() => {}, 60_000)
+    return () => clearInterval(timer)
+  }, 'dsh-hello.timer')
+
+  ctx.tools.register({
+    name: 'hello',
+    description: 'Say hello.',
+    async run() {
+      return 'hello'
+    },
+  })
+}
+```
+
+- `inject` lists only services you read; the runner stubs them for L1.
+- `ctx.effect(fn, 'label')` gives the disposer a label, so `dispose()` can go
+  back to zero (`C-6.2`, `C-7.1`).
+- `ctx.tools.register(...)` is the static trigger that requires
+  `capabilities: ["tools:register"]`.
+
+<a id="cordispatchyml-insert"></a>
+## `cordis.patch.yml`: the insert row
+
+```yaml
+- insert:
+    - id: dsh-hello
+      name: '@acme/dsh-hello'
+```
+
+Rules the checker and the host care about:
+
+- `id` is the stable row identifier later layers use to override this row. Keep
+  it short and unique.
+- `name` is the module the loader imports. For the **package-root row** it must
+  be the package name exactly (`@acme/dsh-hello`), because G4 looks for a
+  composed row whose `name` equals `manifest.name`. An `id` alone is not a row.
+- An insert is required. An `override`-only patch adds nothing to the profile;
+  the plugin is never loaded (G1 reports no target rows, G3 reports no active
+  rows).
+- The patch file stays inside the package and uses a relative path; `..`,
+  absolute paths, `~`, and `$VAR` are rejected (`C-1.4`).
+- Do not enable `@deepseek-ai/dsh-plugin-manager/tools` in a patch unless you
+  mean to hand every session the ability to install code (`C-11.3`).
+- G0 parses, G1 composes rows, G2 runs the compatibility gate, G3 boots the
+  target rows. Only G3 `verified` is a start; a `partial` result is
+  `ERROR`/`not-run`, not a pass.
+
+<a id="client-entry-and-root-row"></a>
+## Client entry and the package-root row
+
+A client is a dual-face package: a server/`dsh` half that is loaded as a row,
+and a prebuilt browser bundle at `exports["./client"]`.
+
+```json
+{
+  "name": "@acme/dsh-panel",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./lib/client.js"
+  },
+  "files": ["index.js", "lib", "cordis.patch.yml"],
+  "engines": { "dsh": ">=0.2.2-0 <0.3.0" },
+  "dsh": {
+    "manifestVersion": 1,
+    "kind": "client",
+    "client": { "platform": "web" },
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "capabilities": [],
+    "labels": []
+  }
+}
+```
+
+```yaml
+# cordis.patch.yml — the same package name as the manifest
+- insert:
+    - id: dsh-panel
+      name: '@acme/dsh-panel'
+```
+
+The server half only has to load as a row; the browser half is the built file:
+
+```js
+// index.js — the server half; lib/client.js is the browser half
+export const name = 'dsh-panel'
+export const inject = []
+
+export function apply() {}
+```
+
+What each piece is for:
+
+| Piece | Why it is required | Where it shows up |
+|---|---|---|
+| `dsh.client` (non-empty) | marks the package as having a browser face | `G4`, `C-1` |
+| `dsh.client.platform` | the host selects the Web consumer with `"web"`; the checker only requires `dsh.client` to be non-empty | host manifest type |
+| `exports["./client"]` | a string path, or an object with a string `default`; must point at a **built** file (the checker only fails when it is absent) | `G4` → `DSC-01` FAIL if missing |
+| root row (`name` = package name) | the client scanner reads the loader's rows; no active row means the bundle is never discovered | `G4` in the bundle smoke |
+| `dsh.client.inject` | informational package names, not Cordis injection | host only |
+| `dsh.client.external` | extra module-table requests; omit unless you need them | host build |
+
+`"capabilities": []` says the server half touches no host surface. The checker
+still WARNs (`C-11.1: dsh.capabilities is empty`) and the report's reason line
+says `advisory: DSC-11`; in ENTRY that WARN is advisory, so the status stays
+`pass`. If the server half does touch something, fill the array from the trigger
+table in [entry.md](entry.md#capability-triggers) — an empty array is not a
+substitute for the capabilities you actually use.
+
+Two failure shapes you will see, and how to tell them apart:
+
+```text
+G4: FAIL dsh.client exists but exports["./client"] is missing; a package-root row cannot resolve it
+```
+
+The message names both causes. Add `exports["./client"]` first; if the export
+already exists, the bundle smoke is telling you the composed root row is
+missing — check that the patch `name` equals `manifest.name` and that the row is
+`insert`ed.
+
+```text
+DSC-14  FAIL  C-14  L1  G4 failed: dsh.client has no package-root row or missing client export
+```
+
+That is the same condition on a runtime claim. Without `--host`, a client is
+`DSH-ENTRY recognized` at best, and `DSC-14` is `NA`: build-only is not runtime.
+
+<a id="verify"></a>
+## Verify what you copied
+
+```sh
+# recognition only (no runtime claim): expect status=pass, exit=0
+npx dsh-standards . --scope entry --entry-claim static
+
+# plugin runtime: expect DSC-14 PASS and level "DSH-ENTRY runtime"
+npx dsh-standards . --scope entry \
+  --runtime /path/to/cordis/lib/index.js
+
+# bundle: expect "G0-G3 verified; rows=1/1"
+npx dsh-standards . --scope entry \
+  --host /path/to/@deepseek-ai/dsh-app-boot/lib/index.js
+
+# machine-readable: read .conclusion.level and .g4
+npx dsh-standards . --format json
+```
+
+For the plugin recipe above, the static run prints:
+
+```text
+DSC-01  PASS  C-1    L0
+DSC-02  PASS  C-2    L0
+DSC-11  PASS  C-11   L0
+DSC-12  PASS  C-12   L0
+DSC-13  PASS  C-13   L0
+level: DSH-ENTRY recognized
+```
+
+For the client recipe, the same run ends `status=pass`, prints
+`level: DSH-ENTRY recognized`, and still shows
+`C-11.1: dsh.capabilities is empty` with `reason: advisory: DSC-11`. That is the
+transitional empty-array WARN, not a G4 failure. A `kind: client` package is
+static-only: `DSC-14` is `NA`, so `--host` cannot turn it into
+`DSH-ENTRY runtime`. Only a package installed as a bundle (`kind: bundle`)
+reaches runtime through G0–G3, and its G4 needs both the client export and the
+root row. If `G4` fails you get `exit=1` and no level — add the missing export
+or row, do not reword the report.

package/docs/rules.md

@@ -0,0 +1,99 @@
+# Rules: decode a check report in one table
+
+<a id="how-to-read"></a>
+## How to read one report line
+
+A DS-C report has one line per check: `id`, `result`, `clause`, `layer`,
+`reason`. The detail lines under it (`C-1.2`, `C-11.5`, `G4`) are what you
+actually fix.
+
+| Result | Meaning | What it does to the verdict |
+|---|---|---|
+| `PASS` | the check ran and found nothing | counts as pass |
+| `WARN` | ran, found something worth fixing | does not fail the run; `status` becomes `warn` (advisory checks excepted) |
+| `FAIL` | ran, found an attributable defect | `status=fail`, exit `1` |
+| `NA` | the check does not apply (wrong `dsh.kind`, no field, package profile) | allowed; not a pass |
+| `ERROR` | the check could not run (`coverage: not-run`, e.g. no `--runtime`/`--host`) | `status=incomplete`, exit `2` |
+
+Exit codes: `0` completed (pass or warn), `1` attributable FAIL, `2`
+incomplete/not-run, `3` usage error. `WARN` is not a clean pass and
+`incomplete` is not a pass — both are printed as such on purpose.
+
+The JSON report also carries a sibling `advice[]` array: one entry per live
+detail, with `title`, `why`, `fix`, `docsUrl`, `severity`, and `evidence`. It is
+additive and never changes the verdict (turn it off with `--no-advice`). The
+`docsUrl` follows the checker's `DOCS_BASE` (currently `v0.4.4`); if it points
+at an older page, this table is the current mapping.
+
+<a id="scope-matrix"></a>
+## Which checks run in which scope
+
+| Scope / profile | Mandatory checks | Notes |
+|---|---|---|
+| `--scope ds-c` (default), `package` | 01, 02, 04–09, 11, 12, 13 | 03 is `NA`, 10 is advisory, 14 is not run |
+| `--scope ds-c`, `listing` | + 03 | install spec / market index are now judged |
+| `--scope entry --entry-claim static` | 01, 02, 11, 12, 13 (+ 03 for listing) | 04–09 are attempted and printed (usually `ERROR`/`NA`), 14 is `NA`; a `DSC-11`/`DSC-12`/`DSC-13` FAIL is downgraded to `WARN` |
+| `--scope entry --entry-claim runtime` | + 14 | 14 carries the runtime verdict, not 04–09 |
+| `--scope mvp` | 01, 02, 04–09 | the MVP subset, labelled `MVP-13` |
+
+<a id="table"></a>
+## The check table
+
+| Check | Clause | Blocking or advice | One-line fix | Guide |
+|---|---|---|---|---|
+| **DSC-01** | C-1 manifest + entry | Blocking (ds-c, entry). C-1.3/C-1.5/C-1.6 are WARN/NA. A `G4` detail is reported here. | Exact `name`/`version`, `exports["."]` or `main` resolving to a file inside the package, in-package `dsh.bundle.patch` paths, and a `license`. | [entry.md § package shape](entry.md#package-shape) · [recipes](recipes.md#minimal-packagejson) |
+| **DSC-02** | C-2 version range | Blocking (ds-c). In ENTRY, a static claim downgrades the whole check to WARN; a runtime claim keeps `C-2.2`/`C-2.3` blocking. | Declare `engines.dsh` as a range that contains the host you target (`>=0.2.2-0 <0.3.0`); never publish `workspace:`. | [entry.md § package shape](entry.md#package-shape) |
+| **DSC-03** | C-3 install source | Blocking (listing only); `NA` in package profile. | Pin the source: exact version or verifiable tag, `#<40-hex>` for git, an in-package path, and a `format:1` market entry with pinned versions. | [entry.md § package shape](entry.md#package-shape) |
+| **DSC-04** | C-4 load to ACTIVE | Blocking (ds-c, when a runtime runs). | Make the entry import cleanly and reach `ACTIVE`: no throw at import, no module-scope work, declare `inject` or read `ctx.get()`, move work into `apply()`. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-05** | C-5 declared provide | Blocking (ds-c). | Every name in `export const provide` must be registered by this plugin's own fiber via `ctx.provide(name, impl)`. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-06** | C-6 effects | Blocking (ds-c); anonymous effects are WARN. | Wrap timers, watchers, sockets, and subprocesses in `ctx.effect(fn, 'label')`; never write `ctx.reflect.store` or `ctx.events._hooks`. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-07** | C-7 unload residue | Blocking (ds-c). | Return a disposer from every effect so `dispose()` leaves `getEffects()===0`, the service store at baseline, and `registry.size` unchanged. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-08** | C-8 restart idempotence | Blocking (ds-c). | Make `restart()` re-enter `ACTIVE`, keep the effect count, advance revision/epoch, and succeed from a fresh `Context`. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-09** | C-9 declared vs measured | Blocking (ds-c) for `C-9.1`; `C-9.2`/`C-9.3` are WARN. | Keep declarations equal to reality: provided ⊆ measured, measured ⊆ declared, and each declared `inject` is really read as `ctx.<service>`. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-10** | C-10 import-time work | Advice only; never changes the verdict. | Move module-scope `await`, timers, `process.on`, fs writes, and spawns into `apply()` and clean up with `ctx.effect()`. | [entry.md § import-time side effects](entry.md#import-time-side-effects) |
+| **DSC-11** | C-11 capabilities | Blocking (ds-c); `WARN` in ENTRY, and a `WARN` here is advisory even in ds-c. | Declare `dsh.capabilities` from the closed set, add one entry per static trigger, and never enable `@deepseek-ai/dsh-plugin-manager/tools` in a patch. | [entry.md § capability triggers](entry.md#capability-triggers) |
+| **DSC-12** | C-12 credentials + seams | Blocking (ds-c); `WARN` in ENTRY. | Read credentials through `ctx.credentials`, declare `credentials:list` for `listRecords()` and `credentials:provider` for a provider, and never read the backing file. | [entry.md § credentials and seams](entry.md#credentials-and-seams) |
+| **DSC-13** | C-13 labels + mirror | Blocking (ds-c); `WARN` in ENTRY, advisory as a WARN. | Use only the five labels, add the label each capability requires, point `dsh.upstream` at an https URL that is not this package **and** add `mirror`, and drop endorsement words. | [entry.md § labels and mirror](entry.md#labels-and-mirror) |
+| **DSC-14** | C-14 entry run | Blocking only for a runtime claim (`--scope entry`). | Supply the real host: `--host` for a bundle (G0–G3) or `--runtime` for a plugin (L1); a client or preset cannot claim runtime. | [entry.md § runtime surface](entry.md#runtime-surface) |
+
+`DSC-14` has no `C-14` in the clause text; it is the ENTRY run-set gate
+(`ENT-14` in 31-DSH-ENTRY). Treat it as "did the thing actually start".
+
+<a id="warn"></a>
+## Two things that look like passes but are not
+
+**Advisory WARN.** `DSC-10` is always advisory. `DSC-11` and `DSC-13` become
+advisory whenever the check itself returns `WARN`, because the host does not
+read those fields yet. The effect is visible: this guide's own report prints
+`DSC-11 WARN`, `DSC-13 WARN`, yet `coverage.warn=0` and
+`reason: advisory: DSC-11, DSC-13`. Read the reason line, not only the coverage
+counts. A `FAIL` that ENTRY downgrades to `WARN` is a plain WARN and does stay
+in the counts.
+
+**`incomplete`.** If a mandatory check has `coverage: not-run` (no runtime, no
+host, a killed child, a partial AST parse), the status is `incomplete` and the
+exit code is `2`. The report prints `NOT A DS-C PASS`. Do not paste a
+`not-run` row into a README as a pass; write `not-run` or run the check.
+
+<a id="not-checked"></a>
+## What the checker does not check
+
+These are good practice but **not** evidence of a pass, because no check reads
+them:
+
+- `engines.node` (the 24.9 line is a guide recommendation; `DSC-02` looks at
+  `engines.dsh` and `@deepseek-ai/dsh*` peers only)
+- README install instructions, display metadata, keywords, `icon`
+- endorsement words in prose, `description`, or README — `C-13.4` scans only
+  the `dsh.labels` array
+- whether a `red-team` label was actually used for red-team work (`C-13.5`
+  only asks for `dsh.usageScope`)
+- browser rendering of a client bundle (`G4` is a static shape check)
+
+The checker's default `--runtime-version` is `0.2.2-alpha.2`. Pass
+`--runtime-version <the host you target>` when that differs, or `DSC-02` will
+judge your range against the wrong version.
+
+If a report FAILs and you cannot find the ID here, open
+[`docs/recipes.md`](recipes.md) for the copy-paste shape, then re-run the same
+command and compare the detail lines.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-guide",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "A practical guide to DSH plugin quality: ENTRY checks, FLOW checks, and BOOST guidance. Community guide; not official, not a certification, not a ranking.",
   "type": "module",
   "main": "index.js",

package/README-zh.md

@@ -1,82 +0,0 @@
-<div align="center">
-
-# dsh-plugin-guide
-
-**DSH 插件质量指南：ENTRY、FLOW、BOOST。**
-
-社区指南，不是官方标准、不是认证、不是排名。
-
-[![npm](https://img.shields.io/npm/v/dsh-plugin-guide)](https://www.npmjs.com/package/dsh-plugin-guide)
-[![CI](https://github.com/PerryLink/dsh-plugin-guide/actions/workflows/verify.yml/badge.svg)](https://github.com/PerryLink/dsh-plugin-guide/actions/workflows/verify.yml)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
-
-[English](README.md) · [简体中文](README-zh.md)
-
-</div>
-
----
-
-## 这是什么
-
-`dsh-plugin-guide` 是 DSH 插件的**指南层**：解释要检查什么、为什么重要，以及
-判定应该由哪个工具负责。它不做认证、不打分、不排名。
-
-| 包 | 角色 |
-|---|---|
-| **`dsh-plugin-guide`** | 本包：文字指南、三层地图、agent skill |
-| **`dsh-standards`** | 执行总包：ENTRY/FLOW 检查、三层审计、规范文件 |
-| **`dsh-plugin-spec`** | 底层规则文本与条款来源 |
-| **`dsh-primer`** | 旧的构建/脚手架技能和 CLI（原 `dsh-plugin-guide` 0.3.x） |
-
-## 三层
-
-| 层 | 回答 | 能否判定 |
-|---|---|---|
-| **ENTRY** | 能不能被识别、安装、启动 | 能：recognized / runtime / failed / incomplete / unavailable |
-| **FLOW** | 用户能不能装、配、用、升级、卸载 | 有 runtime 证据时能；否则 `not-run` |
-| **BOOST** | 有没有用好 Cordis | 不给插件级判定；按实践登记证据 |
-
-三条轨道，不是三个等级；它们相加不等于分数或证书。
-
-先读一页地图：[docs/levels.md](docs/levels.md)。
-
-## 安装
-
-```sh
-dsh plugin --profile web add dsh-plugin-guide
-```
-
-然后在审查插件时让 agent 使用 `dsh-plugin-guide` 技能。它会将检查交给
-`dsh-standards`，将构建/脚手架工作指向 `dsh-primer`。
-
-## 检查插件
-
-```sh
-# 只做 ENTRY 识别（不声明 runtime）
-npx dsh-standards ./my-plugin --scope entry --entry-claim static
-
-# 三层审计；没跑的层保持 not-run / not-measured
-npx -p dsh-standards dsh-levels ./my-plugin --format json
-```
-
-`recognized` 不是通过，`static` 不是通过，`not-run` 也不是通过。
-
-## 0.4.0 改了什么
-
-- 旧的 agent skill 和 `dsh-plugin-dev` CLI 已迁到
-  [`dsh-primer`](https://github.com/PerryLink/dsh-primer)。
-- 本包现在是**指南层**：三层地图、检查路由、证据规则。
-- 旧 0.3.x npm 版本已标记 deprecated，已有安装仍可用；0.4.0 是产品切换，
-  锁在 `^0.3` 的用户不会自动升级。
-- 检查在 [`dsh-standards`](https://github.com/PerryLink/dsh-standards)，不在本包。
-
-## 边界
-
-- 不做官方背书、认证、认可或安全审计。
-- 不做评分、排名或市场门禁。
-- 不伪造 runtime 证据：`static` ≠ `runtime`，`not-run` ≠ `pass`。
-- BOOST 是建议和证据，不是插件等级。
-
-## 许可
-
-Apache-2.0。见 [LICENSE](LICENSE) 与 [NOTICE.md](NOTICE.md)。