@bushizhanghan/dsh-publish-gate 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.22.0
+
+- New tool `publish_gate_link` (the tenth): the local-development layer. It answers "is the code the
+  host loads the code I just edited?" from the profile's own files — `<profile>/node_modules`,
+  `<profile>/node_modules/.modules.yaml`, `<profile>/cordis.patch.yml` — with no network and no
+  package manager. Every failure on this path is silent: the plugin simply never appears.
+- `link-not-installed` (info): the profile has no entry for this package. Normal before the first
+  local install, so it does not raise the blocker count.
+- `link-target-missing` (error): the entry is a link whose target is gone, or whose target has no
+  parseable `package.json`. A dead junction makes the host resolve the package to nothing — this is
+  what broke this machine's Web UI once, with no error anywhere.
+- `link-stale-copy` (warn): the entry is a plain directory, not a link, and its version differs from
+  the checkout. Edits to `lib/` never reach the profile while the checkout's own tests stay green.
+- `pnpm-store-conflict` (warn): the profile's pnpm store major differs from the bundled pnpm's (11).
+  `dsh plugin add link:` then fails with `ERR_PNPM_UNEXPECTED_STORE` before installing anything, and
+  the message names neither the profile nor the major to match. Read from `storeDir` in
+  `.modules.yaml`; measured on this profile: `...\AppData\Local\pnpm\store\v11`, so v11 vs v11 is
+  clean and only a v10 store is flagged.
+- `patch-entry-top-level` (error): the package's row in the profile patch is a top-level `- id:`
+  entry. A top-level row overrides an entry that already exists; it does not add one, so the plugin
+  installs, loads, and never appears. This profile currently has **zero** `insert:` blocks and every
+  row is top-level — exactly the shape the rule exists to catch.
+- The link kind is reported as `junction` / `symlink` / `copy` / `missing`: Node reports a junction
+  and a directory symlink identically (`lstat().isSymbolicLink()`), so the junction is identified by
+  `realpathSync(p) !== p`, the check that distinguishes the form `mklink /J` creates without admin
+  rights from the one that needs them.
+- Tests: 131 engine tests (six new, one per rule, each against a temp profile — the real profile is
+  never read or written) and 32 integration assertions.
+
 ## 0.21.0
 
 - The runtime layer no longer assumes the entry is `lib/index.js`. It resolves `exports["."]` →
@@ -17,15 +46,15 @@
   dependencies, so the code is in the bundle and "lib/ never imports it" is true but not actionable.
 
 ## 0.20.0
-
+
 - `publish_gate_commands` now agrees with the rules: a prerelease version gets `npm publish --tag next`
   instead of a bare publish that would move `latest`.
 - New step `tag the shipped commit` (`git tag v<version> && git push origin v<version>`). The gate has
   warned about a missing tag since 0.5.0 and the command list never mentioned tagging — I wrote a
   separate script to do it because the instructions never said to.
-
+
 ## 0.19.0
-
+
 - `prerelease-published-as-latest` (warn): a `-beta` / `-rc` version with no `publishConfig.tag`.
   npm publishes to `latest` whatever the suffix says, so `npm i <name>` starts handing everyone an
   unfinished build and nothing warns.
@@ -33,17 +62,17 @@
   older one. That is what `--tag next` does when you meant to release: the release looks shipped and
   is not what anyone installs.
 - README: dropped a made-up `test/…` example path — `readme-path-missing` caught my own prose.
-
+
 ## 0.18.0
-
+
 - `readme-path-missing` (warn): a README that names `test/…`, `lib/…`, `scripts/…` files that no longer
   exist. Rename a file and the README keeps telling people to run something that returns ENOENT;
   nothing else in the repo notices. Only repo-relative paths under directories a plugin owns, so a
   tutorial example is not a finding.
 - Verified over all nine plugins in this workspace: no false positives, all nine still `e0 w0`.
-
+
 ## 0.17.0
-
+
 - `changelog-not-shipped` (warn): a CHANGELOG.md that exists on disk but is not in the tarball. npm
   force-includes README and LICENSE and nothing else, so the file you keep updating never reaches the
   registry page. Hit it the first time I added a changelog and had to add it to `files` by hand.
@@ -53,14 +82,14 @@
   was pushed through the API and local HEAD is not the shipped commit.
 - First end-to-end run of the gate with the test layer over all nine plugins in this workspace: every
   suite passed, and the tag rule was the only false positive.
-
+
 - `changelog-not-shipped` (warn): a CHANGELOG.md that exists on disk but is not in the tarball. npm
   force-includes README and LICENSE and nothing else, so the file you keep updating never reaches the
   registry page. Hit it the first time I added a changelog and had to add it to `files` by hand.
 - First end-to-end run of the gate with the test layer over all nine plugins in this workspace.
-
+
 ## 0.16.0
-
+
 - `market-release-behind` (warn): the newest GitHub release is older (or newer) than package.json. A
   catalogue entry may install `releases/latest/download/<asset>`, so a lagging release serves code the
   description no longer describes — a reviewer blocked a submission for exactly that.
@@ -70,9 +99,9 @@
 - The source scan added in 0.15.0 caught the same mistake again while building this version: a string
   replace aimed at RULE_ORDER matched an earlier `F(...)` call and wrote the new rule name into a severity
   slot. Fixed, and the fix now goes through the RULE_ORDER slice instead of a global replace.
-
+
 ## 0.15.0
-
+
 - Three rules shipped with a *rule name* in their severity slot: `market-repo-too-new`,
   `test-script-dir-arg` and `tool-missing-output-schema` were built as
   `F(rule, "some-other-rule", "a-third-rule", "warn", title, ...)`, because a string replace aimed at
@@ -81,45 +110,45 @@
   reaches the report, so the rules looked like they simply never fired. Fixed all three, added the six
   rule names that never made it into RULE_ORDER, and added a source scan that fails when any `F(...)`
   call passes something other than an error/warn/info literal (or a ternary of two of them).
-
+
 ## 0.14.0
-
+
 - New test layer: `checkTestRun` runs `node --test` in the plugin directory and reports `tests-fail`
   (error), `tests-timeout` (warn) and `tests-not-run` (warn). Every other layer reads the paperwork —
   the manifest, the tarball, the registry — while nine of my own plugins shipped
   `"test": "node --test test/"`, which throws MODULE_NOT_FOUND on Node 22+ and would have been caught
   by simply running it. The child drops the inherited NODE_TEST_CONTEXT, because a gate that runs
   inside `node --test` would otherwise start the suite in test-child mode and see no summary at all.
-
+
 ## 0.13.1
-
+
 - The tag check now asks `git ls-remote origin` instead of `git tag --points-at HEAD`. When the commit is pushed
   through the GitHub API the local HEAD is not the remote one, so the local form reported `git-tag-missing` on
   seven of my nine plugins whose tag existed all along. It now compares the tag against the shipped branch
   head and stays silent when the remote cannot be reached — a check that cannot see the truth must not claim
   a defect.
 ## 0.13.0
-
+
 - `market-fork-of-listed` / `market-fork-undisclosed` (warn): the repo is a GitHub fork whose parent is
   already in the catalogue, and nothing says so. A submission was blocked for exactly this: the entry
   described the fork as if it were original work, and both plugins claim the same provider id, so installing
   both silently shadows one of them. The check uses the `fork` and `parent.full_name` fields of the repo
   metadata the market layer already fetches.
 ## 0.12.0
-
+
 - `pack-ships-junk` (warn): the tarball carries `.bak-*`, `.orig`, `.swp`, `.log`, `~` or `.DS_Store` debris.
   Naming a directory in `files` takes everything inside it, so a `lib/client.js.bak-20261026` left behind
   during a fix ships to every consumer and stays on npm permanently. Both weapp-loop and page-monitor had
   exactly that file during this session; both were deleted by hand before this rule existed.
 ## 0.11.0
-
+
 - `tool-no-description` (error), `tool-description-thin` (warn), `tool-no-parameters` (error): the host
   renders name + description + parameters into the prompt and nothing else, so those three fields are the
   tool's entire specification. A tool with no description is a name in a list; a tool that reads args with no
   schema never receives them. All nine of my plugins were clean, so this guards the shape rather than a
   specific crash — the first two fixtures that had `description: 'd'` did fail, which is the point.
 ## 0.10.0
-
+
 - `client-double-load` (warn): the client probe now evaluates the bundle a second time against the same
   `window`, with a loader that throws on a repeated registration. A bundle inserted by two patches (its own,
   plus any sidebar plugin that injects `dsh-client-modules`) aborted web boot this way. A window-level guard

package/README.md

@@ -4,18 +4,18 @@
 >
 > 发布一个 DSH 插件有七步，每一步都有一个**直到你付出代价才说话的坑**：`files` 忘了 `lib/` 于是发出去一个空包、PowerShell 写下的 BOM 让 `JSON.parse` 报一个不提 BOM 的错、patch 的 insert 行缩进错了于是插件装上了但**永远不加载**、裸包名让 granular token 收到一个既不说 token 也不说 scope 的 403。这个插件把整条链路的每个静默坑变成一条确定性检查。
 
-八个 agent 工具：全量门禁、运行时注册检查、发后校验、patch 专项、市场条目校验、版本推进、多插件体检、发布命令清单。
+十个 agent 工具：全量门禁、运行时注册检查、发后校验、patch 专项、市场条目校验、版本推进、多插件体检、发布命令清单、本地开发链路诊断。
 
 门禁分三层：**清单层**看 package.json / patch / 入口源码，**产物层**真的跑一遍 `npm pack --dry-run` 看 npm 到底会发出什么，**运行时层**在独立子进程里 `import()` 入口并 `apply(ctx)` 一遍，看它到底注册了什么。
 
 ### 自检：看不见的 finding
-
+
 `severity` 不是 `error`/`warn`/`info` 的 finding 会被所有计数器忽略，等于规则从没触发过。`publish_gate` 现在会把这类 finding 提升成一条 `internal-bad-severity` 的 error，测试里还有一条源码扫描盯着 `F(...)` 的第二个参数。这条网加上当天就抓到了我自己的同一个错误。
-
+
 ### 测试层：门禁真的会跑一遍你的测试
-
+
 `tests-fail` / `tests-timeout` / `tests-not-run` 三条规则会以 `node --test` 在插件目录里真跑一次（不经过 `npm test`，因为脚本内容由作者决定、可能 shell 出去）。子进程会去掉继承来的 `NODE_TEST_CONTEXT`——否则当门禁本身跑在 `node --test` 里时，子进程进入 test-child 模式、一个摘要都不打印，看起来像"没有测试"。
-
+
 ## 典型用法（写完插件后）
 
 ```
@@ -45,6 +45,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `publish_gate_market` | 校验市场条目 YAML（url/name/category/description 双语）；传 `dir` 则改查只有线上才能回答的三件事：这个仓库**已经在目录里**（再开 PR 就是重复条目）、另一个条目也在发同一个 npm 包、仓库还**不满 24 小时**（提交门禁会失败并自己重跑） |
 | `publish_gate_next_version` | 当前版本、是否已被 registry 占用、建议 bump 到多少（本地比 npm 旧时从 npm 的 latest 往上加，不会推荐一个已被占用的版本） |
 | `publish_gate_doctor` | 扫整个目录，按 blocker 数排序，附带每个插件的真实包体积，看哪个还不能发 |
+| `publish_gate_link` | 本地开发链路：不联网、不调包管理器，只读 profile 自己的 `node_modules` / `.modules.yaml` / `cordis.patch.yml`，回答「宿主现在跑的到底是不是我刚改的这份代码」——链接的形态与目标、pnpm store 的 major、patch 行挂不挂载，一次报全。传 `profile` 可看别的 profile（默认 `~/.dsh/profiles/desktop`） |
 | `publish_gate_commands` | 按顺序列出发布命令，并标出这台机器已经走到哪一步。命令是**这台机器上真能跑的形式**：Windows 下 `npm publish` 走 `cmd /c`（PowerShell 的 `npm.ps1` 常被执行策略拦掉），`npm publish` 后面紧跟一条 `publish_gate_verify`；版本是预发版时命令自带 `--tag next`；最后一步是给发出去的 commit 打 tag |
 
 ## 检查清单
@@ -105,7 +106,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ### 运行时层：`apply` 之后到底注册了什么
 
 前两层都是读文件，读不出「装上能不能用」。这一层在独立子进程里 `import()` 入口、用假 ctx 调一次 `apply(ctx)`，把 `ctx.tools.register` 收到的每一条拿回来检查。20 秒超时，你的插件代码不在宿主进程里跑。
-
+
 入口按 `exports["."]` → `main` → `lib/index.js` 的顺序解析。**早先写死 `lib/index.js`，拿三十一个真实已装插件一测，二十个报"入口抛异常"——其中两个的入口是 `index.mjs`，根本没有 `lib/`。**误报比漏报更贵：一个满屏假错误的门禁，第二次就没人跑了。
 
 | 规则 | 抓什么 |
@@ -203,6 +204,37 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 
 都是 warn：本地试发、私有包、发完再补 tag 都合理。但「发完之后指不出是哪份代码」这件事，事后补不回来。
 
+## 本地开发：宿主跑的到底是不是你刚改的代码
+
+发布之前总有一段时间，插件只在你自己机器上跑。这段路比发布更容易踩空：宿主只加载 `<profile>/node_modules` 下的包，所以你改的是 `E:\...\dsh-x`，跑的是 profile 里那个入口——它可能是一个 junction、一份早就不再同步的拷贝，或者根本没有。这三种情况在宿主那边长得一模一样：插件不出现，没有报错，日志里也没有一行。
+
+`publish_gate_link` 只读 profile 自己的三个文件回答这件事，不联网、不调包管理器、不写任何东西。
+
+| 规则 | 严重度 | 抓什么 |
+|---|---|---|
+| `link-not-installed` | info | profile 的 `node_modules` 里没有这个包。新插件第一次接进宿主之前，这是正常状态 |
+| `link-target-missing` | error | 链接在、目标没了（或目标里没有能解析的 `package.json`）。死掉的 junction 让宿主把包解析成空，插件静默消失——这台机器的 Web UI 就这样坏过一次 |
+| `link-stale-copy` | warn | profile 里是**一份拷贝**而不是链接，且版本和工作区不同：改 `lib/` 永远不会到那边，而你在这边跑测试全绿 |
+| `pnpm-store-conflict` | warn | profile 的 pnpm store 是 v10、随包的 pnpm 是 v11（或反过来）。`dsh plugin add link:` 会在装任何东西之前以 `ERR_PNPM_UNEXPECTED_STORE` 失败，而那条错误既不说 profile、也不说要匹配哪个 major |
+| `patch-entry-top-level` | error | 这个包在 profile 的 `cordis.patch.yml` 里是一条顶层 `- id:` 行。顶层行覆盖树里已有的条目、不新增一条：装上了、加载了、永远不出现。这个坑藏了我两个插件两周 |
+
+链接的三种形态是分开报的：Node 对 junction 和目录符号链接都只说 `isSymbolicLink() === true`，只有 `realpathSync(p) !== p` 才说明它是 junction；普通目录则是拷贝。`mklink /J` 建 junction 不需要管理员权限，符号链接需要。
+
+工作流：
+
+```
+1. 改完 lib/，跑 publish_gate_link(dir)
+2. link-not-installed        → 建 junction（finding 的 fix 里就是能直接粘的命令）
+3. link-target-missing       → 删掉旧入口，重建 junction
+   link-stale-copy           → 同上；拷贝不会跟着工作区变
+4. patch-entry-top-level     → 把那一行挪进 "- insert:" 块
+5. pnpm-store-conflict       → 别用 pnpm，用 mklink
+```
+
+`profile` 参数可以看别的 profile（默认 `~/.dsh/profiles/desktop`）。测试永远用临时 profile，不碰真的那个。
+
+没有做的：它不替你建链接、不改 profile 的 patch——和门禁其余部分一样只读，每条 finding 都带 `fix` 文案，动手是你的决定。
+
 ## 一个真实的例子
 
 对一个刚从别人那儿接手、准备发布的插件跑 `publish_gate`：
@@ -239,8 +271,8 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test                      # 125 个引擎单测
-node test/integration.test.mjs   # 28 条集成断言（9 个真实插件作 fixture）
+node --test                      # 131 个引擎单测
+node test/integration.test.mjs   # 32 条集成断言（9 个真实插件作 fixture）
 ```
 
 ## License

package/lib/engine.js

@@ -6,7 +6,8 @@
 // unscoped npm name that returned E403, a git push that failed on the network
 // while the REST API worked. All of them are silent until the moment they cost
 // you a publish, so they are all checkable before you spend it.
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { existsSync, lstatSync, readFileSync, readlinkSync, readdirSync, realpathSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { join, relative } from 'node:path'
 import { builtinModules } from 'node:module'
 import { execFile } from 'node:child_process'
@@ -2661,6 +2662,213 @@ async function readRemoteRefs(dir) {
 // =====================================================================
 // Orchestration
 // =====================================================================
+// =====================================================================
+// Local development: is this checkout the code the host actually loads?
+// =====================================================================
+// An unpublished plugin reaches the host only through a link in the profile's
+// node_modules, and every failure looks the same from the outside: not
+// installed, linked to a target that moved, or a copy that stopped tracking
+// the checkout. `pnpm add link:` cannot help — the bundled pnpm and the
+// profile store are different majors. These checks read the profile's own
+// files, so they answer it with no network and no package manager.
+
+/** The desktop profile a plugin is installed into, unless the caller names one. */
+const profileDirOf = (opts = {}) => opts.profileDir || join(homedir(), '.dsh', 'profiles', 'desktop')
+
+export function checkLocalLink(dir, opts = {}) {
+  const findings = []
+  const name = readPkgJson(dir)?.name
+  const profileDir = profileDirOf(opts)
+  const path = name ? join(profileDir, 'node_modules', name) : null
+  const link = { kind: 'missing', target: null, resolves: false, path }
+  if (!name) return { ...link, findings } // a nameless package is checkPackageJson's finding
+
+  let entry = null
+  try {
+    entry = lstatSync(path)
+  } catch {
+    entry = null
+  }
+  if (!entry) {
+    findings.push(
+      F(
+        'link-not-installed',
+        'info',
+        `${name} is not installed in ${profileDir}`,
+        "The host only loads packages under the profile's node_modules, so this checkout is not what is running. Expected for a plugin nobody is testing in the host yet.",
+        `Link it: cmd /c mklink /J "${path}" "${dir}"`,
+      ),
+    )
+    return { ...link, findings }
+  }
+
+  if (!entry.isSymbolicLink()) {
+    // A plain directory is a copy, not a link: nothing written to lib/ here
+    // reaches the profile, so the host keeps running whatever was copied.
+    link.kind = 'copy'
+    link.target = path
+    link.resolves = true
+    const copied = readPkgJson(path)?.version ?? null
+    const local = readPkgJson(dir)?.version ?? null
+    if (copied !== local) {
+      findings.push(
+        F(
+          'link-stale-copy',
+          'warn',
+          `the profile holds a copy of ${name}@${copied ?? '?'} while this checkout is ${local ?? '?'}`,
+          'A copy is not a link: edits to lib/ never reach the profile, so the host runs the copied code while every test you run here passes against the checkout.',
+          `Delete "${path}", then: cmd /c mklink /J "${path}" "${dir}"`,
+        ),
+      )
+    }
+    return { ...link, findings }
+  }
+
+  // Node reports a junction and a directory symlink identically: both are
+  // symbolic links. The junction `mklink /J` creates without admin rights is
+  // the one whose realpath leaves the link path. A dead link no longer
+  // resolves, so it reads as 'symlink' here — `resolves: false` and the error
+  // finding below are the parts that matter. readlink still names the target.
+  let real = null
+  try {
+    real = realpathSync(path)
+  } catch {
+    real = null
+  }
+  let target = real
+  if (!target) {
+    try {
+      target = readlinkSync(path)
+    } catch {
+      target = null
+    }
+  }
+  link.kind = real && real !== path ? 'junction' : 'symlink'
+  link.target = target
+
+  const targetPkg = target ? safeText(join(target, 'package.json')) : null
+  let parsed = null
+  if (targetPkg !== null) {
+    try {
+      parsed = JSON.parse(targetPkg.replace(/^\uFEFF/, ''))
+    } catch {
+      parsed = null
+    }
+  }
+  link.resolves = real !== null && parsed !== null
+  if (!link.resolves) {
+    findings.push(
+      F(
+        'link-target-missing',
+        'error',
+        `the profile links ${name} to a target that is not a package`,
+        `The link at ${path} points at ${target ?? '(unreadable)'}, which ${real ? 'has no parseable package.json' : 'does not exist'}. A dead junction fails quietly: the host resolves the package to nothing and the plugin disappears with no error. This is what broke this machine's Web UI once.`,
+        `Delete the link, then: cmd /c mklink /J "${path}" "${dir}"`,
+      ),
+    )
+  }
+  return { ...link, findings }
+}
+
+export function checkStoreConflict(dir, opts = {}) {
+  const findings = []
+  const profileDir = profileDirOf(opts)
+  const bundledMajor = Number(opts.bundledPnpmMajor ?? 11)
+  const state = { profileMajor: null, bundledMajor, conflict: false, storeDir: null }
+  const text = safeText(join(profileDir, 'node_modules', '.modules.yaml'))
+  if (text === null) return { ...state, findings }
+
+  // pnpm writes this file as JSON despite the .yaml extension. The YAML shape
+  // is accepted too, so an older profile still gets an answer instead of silence.
+  let storeDir = null
+  try {
+    storeDir = JSON.parse(text.replace(/^\uFEFF/, ''))?.storeDir ?? null
+  } catch {
+    storeDir = null
+  }
+  if (!storeDir) {
+    const m = /^\s*"?storeDir"?\s*:\s*["']?([^"'\r\n]+?)["']?\s*$/m.exec(text)
+    storeDir = m ? m[1].trim() : null
+  }
+  state.storeDir = storeDir
+  if (!storeDir) return { ...state, findings }
+
+  const majors = [...String(storeDir).matchAll(/(?:^|[\\/])v(\d+)(?=[\\/]|$)/g)].map((m) => Number(m[1]))
+  const profileMajor = majors.length > 0 ? majors[majors.length - 1] : null
+  state.profileMajor = profileMajor
+  if (profileMajor === null) return { ...state, findings }
+
+  if (profileMajor !== bundledMajor) {
+    state.conflict = true
+    findings.push(
+      F(
+        'pnpm-store-conflict',
+        'warn',
+        `the profile store is pnpm v${profileMajor}, the bundled pnpm is v${bundledMajor}`,
+        `pnpm refuses a store written by another major, so \`dsh plugin add link:\` fails with ERR_PNPM_UNEXPECTED_STORE before it installs anything — and the message names neither the profile nor the version to match. The store is ${storeDir}.`,
+        `Skip pnpm: cmd /c mklink /J "${join(profileDir, 'node_modules', '<name>')}" "<checkout>"`,
+      ),
+    )
+  }
+  return { ...state, findings }
+}
+
+export function checkMountEntry(dir, opts = {}) {
+  const findings = []
+  const name = readPkgJson(dir)?.name
+  const profileDir = profileDirOf(opts)
+  const mount = { entryFound: false, shape: 'absent', line: null, id: null }
+  if (!name) return { ...mount, findings }
+
+  const patchPath = join(profileDir, 'cordis.patch.yml')
+  const text = safeText(patchPath)
+  // No profile patch at all: nothing to mount, and the plugin's own bundle
+  // patch is the supported channel, so absence is not a finding.
+  if (text === null) return { ...mount, findings }
+
+  const bare = name.replace(/^@[^/]+\//, '')
+  const lines = text.split('\n')
+  let inInsert = false
+  let insertIndent = 0
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const insert = /^(\s*)-?\s*insert:\s*$/.exec(line)
+    if (insert) {
+      inInsert = true
+      insertIndent = insert[1].length
+      continue
+    }
+    const row = /^(\s*)-\s*id:\s*(.+?)\s*$/.exec(line)
+    if (row) {
+      const indent = row[1].length
+      const id = row[2].replace(/^['"]|['"]$/g, '')
+      const mounted = (/^\s*name:\s*(.+?)\s*$/.exec(lines[i + 1] || '')?.[1] || '').replace(/^['"]|['"]$/g, '')
+      if (id === name || id === bare || mounted === name) {
+        mount.entryFound = true
+        mount.id = id
+        mount.line = i + 1
+        mount.shape = inInsert && indent > insertIndent ? 'insert' : 'top-level'
+        if (mount.shape === 'top-level') {
+          findings.push(
+            F(
+              'patch-entry-top-level',
+              'error',
+              `the profile patch row for ${name} is a top-level "- id:" entry, so it never mounts`,
+              `Line ${i + 1} of ${patchPath} sits outside any "- insert:" block. A top-level row overrides an entry that already exists in the tree; it does not add one, so the plugin installs, loads, and never appears. This hid two plugins for two weeks.`,
+              `Move it under "- insert:":\n- insert:\n    - id: ${bare}\n      name: "${name}"`,
+            ),
+          )
+        }
+        return { ...mount, findings }
+      }
+      continue
+    }
+    // a top-level key closes the insert sequence
+    if (/^\S/.test(line)) inInsert = false
+  }
+  return { ...mount, findings }
+}
+
 export function runStaticChecks(dir) {
   return [
     ...checkPackageJson(dir),
@@ -2706,6 +2914,7 @@ const RULE_ORDER = [
   'git-uncommitted', 'git-tag-missing', 'git-tag-unverified', 'git-tag-elsewhere',
   'readme-tool-undocumented', 'readme-test-count',
   'no-tests', 'no-test-files', 'no-test-script', 'no-engines', 'bad-repo-url', 'no-gitignore',
+  'link-not-installed', 'link-target-missing', 'link-stale-copy', 'pnpm-store-conflict', 'patch-entry-top-level',
 ]
 
 const MARK = { error: '✗', warn: '!', info: '·' }

package/lib/index.js

@@ -12,13 +12,16 @@ import {
   checkDocs,
   checkEntrySource,
   checkGitState,
+  checkLocalLink,
   checkMarketEntry,
   checkMarketReadiness,
+  checkMountEntry,
   checkNpmState,
   checkPackageJson,
   checkPack,
   checkPatchYml,
   checkPublishedMatches,
+  checkStoreConflict,
   checkTests,
   checkToolRegistrations,
   checkClientRuntime,
@@ -477,6 +480,36 @@ export function apply(ctx, config = {}) {
     },
   ]
 
+  tools.push({
+    name: 'publish_gate_link',
+    description:
+      'Answer "why is my local plugin not running?" from the profile\'s own files, with no network and no package manager. An unpublished plugin reaches the host only through a link in <profile>/node_modules plus a mount row in the profile\'s cordis.patch.yml, and every failure looks identical from the outside. Reports: link-not-installed (info) when the profile has no entry for this package; the link kind and its target — Node reports a junction and a directory symlink the same way, while a plain directory is a copy; link-target-missing (error) when the link points at a path with no parseable package.json, because a dead junction resolves the package to nothing and the plugin silently disappears; link-stale-copy (warn) when the profile holds a copy whose version differs from this checkout, so edits to lib/ never reach it; pnpm-store-conflict (warn) when the profile\'s pnpm store major differs from the bundled pnpm (v11) — that is the ERR_PNPM_UNEXPECTED_STORE that makes `dsh plugin add link:` fail before it installs; patch-entry-top-level (error) when this package\'s row in the profile patch sits outside an "- insert:" block, which installs and never mounts. Pass profile to inspect a temp profile; the default is ~/.dsh/profiles/desktop. Returns {ok, link:{kind,target,resolves}, store:{profileMajor,bundledMajor,conflict}, mount:{entryFound,shape}, findings, report}.',
+    parameters: {
+      type: 'object',
+      properties: {
+        dir: { type: 'string', description: 'Plugin checkout directory.' },
+        profile: { type: 'string', description: 'Profile directory to inspect (default ~/.dsh/profiles/desktop). Tests pass a temp profile instead of the real one.' },
+      },
+    },
+    async execute(args) {
+      const dir = resolveDir(args.dir)
+      if (!dir) return { ok: false, error: 'no plugin directory given (dir must be a string path)' }
+      const profileDir = typeof args.profile === 'string' && args.profile.trim() ? args.profile.trim() : undefined
+      const link = checkLocalLink(dir, { profileDir })
+      const store = checkStoreConflict(dir, { profileDir })
+      const mount = checkMountEntry(dir, { profileDir })
+      const findings = [...link.findings, ...store.findings, ...mount.findings]
+      return {
+        ok: true,
+        link: { kind: link.kind, target: link.target, resolves: link.resolves },
+        store: { profileMajor: store.profileMajor, bundledMajor: store.bundledMajor, conflict: store.conflict },
+        mount: { entryFound: mount.entryFound, shape: mount.shape },
+        findings,
+        report: renderReport(findings, { title: `local link · ${dir}` }),
+      }
+    },
+  })
+
   for (const t of tools) {
     try {
       ctx.tools.register({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bushizhanghan/dsh-publish-gate",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Pre-publish gate for DSH plugins: manifest, dependencies, artifact, runtime, browser half, traceability and market readiness — plus an input fuzzer that drives every declared parameter with the wrong type. 发布前的七层门禁 + 入参模糊测试。",
   "type": "module",
   "main": "lib/index.js",