dsh-mini-utility-dock 0.1.8 → 0.3.0

package/CHANGELOG.en.md

@@ -3,6 +3,16 @@
 Release notes are generated from the matching version section; newest first.
 For Chinese, see [CHANGELOG.md](CHANGELOG.md).
 
+## 0.3.0 - 2026-09-22
+
+- New `dsh-plugin-docs`: a bilingual docs structure check, adopted from the `check-docs.mjs` copy each plugin repository carried. Same interface: no arguments checks the README and CHANGELOG pairs for structural alignment, `--base <revision>` requires bilingual pairs to change together. This package's own bilingual docs are now checked by it too.
+- README gains badges and a positioning statement; the two diagnostic bins (`dsh-plugin-parity`, `dsh-plugin-docs`) are documented with their purpose and opt-in mechanism; the package description states the "family shared assets" scope.
+
+## 0.2.0 - 2026-09-21
+
+- New `dsh-plugin-parity`: a cross-repository drift check, adopted from the copy each plugin repository carried. The member list is caller-supplied via `--member <repo>:<export>`; this package names no repository of its own. Without `--member` it runs the static checks only and discovers every repository that embeds the host-guard block.
+- The copy in each plugin repository is gone with it; the bilingual-structure half of `docs:check` stays with the repositories.
+
 ## 0.1.8 - 2026-09-21
 
 - The two host-side fragments no longer say "sibling": the three phrasings now state the design goal itself — a plugin ships standalone, with nothing else required. A fragment is embedded verbatim into each consumer, where the word had no referent.

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 Release Notes 由对应版本段生成；最新版本在前。
 英文版见 [CHANGELOG.en.md](CHANGELOG.en.md)。
 
+## 0.3.0 - 2026-09-22
+
+- 新增 `dsh-plugin-docs`：双语文档结构校验，收编自插件仓里各自维护的 `check-docs.mjs`。接口不变：无参数查 README 与 CHANGELOG 的中英结构对齐，`--base <revision>` 检查双语对同改。本包自身的双语文档也由此接入校验。
+- README 补上 badges 与包定位说明；两个诊断 bin（`dsh-plugin-parity`、`dsh-plugin-docs`）的用途与接入方式补进文档；包描述同步「族级共享资产」的定位。
+
+## 0.2.0 - 2026-09-21
+
+- 新增 `dsh-plugin-parity`：跨仓漂移诊断，收编自插件仓里各自维护的那份脚本。成员表由调用方通过 `--member <repo>:<export>` 提供，本包不点名任何仓；不带 `--member` 时只跑静态检查，自动发现所有嵌入了宿主守卫块的仓。
+- 插件仓里的该脚本由此删除；`docs:check` 的双语结构校验仍归各仓。
+
 ## 0.1.8 - 2026-09-21
 
 - 两个 host 侧片段的注释不再出现 `sibling`：三处改为陈述设计目标本身——插件独立运行，不依赖同级安装。片段会逐字嵌入消费仓，那个词在那里没有可指对象。

package/README.en.md

@@ -2,7 +2,14 @@
 
 [中文](./README.md) | [English](./README.en.md)
 
-Source fragments and an embedding CLI shared by the DSH plugins.
+[![ci](https://github.com/xswt442-cmd/dsh-mini-utility-dock/actions/workflows/ci.yml/badge.svg)](https://github.com/xswt442-cmd/dsh-mini-utility-dock/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-mini-utility-dock?label=npm&color=4d6bfe)](https://www.npmjs.com/package/dsh-mini-utility-dock)
+[![release](https://img.shields.io/github/v/release/xswt442-cmd/dsh-mini-utility-dock?label=release&color=16a3a3)](https://github.com/xswt442-cmd/dsh-mini-utility-dock/releases)
+[![node](https://img.shields.io/static/v1?label=node&message=%3E%3D20&color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
+[![downloads](https://img.shields.io/npm/d18m/dsh-mini-utility-dock?label=downloads&logo=npm&color=cb3837)](https://www.npmjs.com/package/dsh-mini-utility-dock)
+[![license](https://img.shields.io/badge/license-MIT-22c55e.svg)](./LICENSE)
+
+The DSH plugin family's shared assets: source fragments, an embedding CLI, and the cross-repo diagnostics and bilingual docs checks built around them.
 
 ## Fragments
 
@@ -44,4 +51,6 @@ Consumers invoke the same CLI as `loopback:sync` / `guard:sync`, with the target
 
 A consumer's `npm test` runs `loopback:check` / `guard:check`, comparing its two fragments byte for byte against the dock version it pins. A published version is immutable and consumers pin an exact version, so pin agreement implies fragment agreement.
 
-`scripts/guard-parity.mjs` (in each consumer) checks that cross-repo property directly, including pin agreement. It is a manual diagnostic and **does not run in CI**: the property cannot hold while peers sit on a different branch. Run it when all three checkouts share a branch.
+`dsh-plugin-parity` (a bin provided by this package) checks that cross-repo property directly, including pin agreement and a behavioral comparison. It is a manual diagnostic and **does not run in CI**: the property cannot hold while peers sit on a different branch. The member list is caller-supplied via `--member <repo>:<export>` — the guard factory's export name is per-repository by fragment design, so the tool presupposes no members; without `--member` it runs the static checks only and discovers every checkout that embeds the guard block.
+
+`dsh-plugin-docs` (another bin of this package) checks the documentation pairs for structural alignment: the two READMEs share heading levels and code-fence languages, the two CHANGELOGs expose the same releases, sections and item counts (section titles normalized through a bilingual category map); `--base <revision>` additionally requires both files of a pair to change together — a one-sided edit is a missing translation. Repositories opt in by pointing their own `docs:check` script at it; this package runs the same check on its own bilingual docs.

package/README.md

@@ -2,7 +2,14 @@
 
 [中文](./README.md) | [English](./README.en.md)
 
-DSH 插件共享的源码片段与嵌入 CLI。
+[![ci](https://github.com/xswt442-cmd/dsh-mini-utility-dock/actions/workflows/ci.yml/badge.svg)](https://github.com/xswt442-cmd/dsh-mini-utility-dock/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-mini-utility-dock?label=npm&color=4d6bfe)](https://www.npmjs.com/package/dsh-mini-utility-dock)
+[![release](https://img.shields.io/github/v/release/xswt442-cmd/dsh-mini-utility-dock?label=release&color=16a3a3)](https://github.com/xswt442-cmd/dsh-mini-utility-dock/releases)
+[![node](https://img.shields.io/static/v1?label=node&message=%3E%3D20&color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
+[![downloads](https://img.shields.io/npm/d18m/dsh-mini-utility-dock?label=downloads&logo=npm&color=cb3837)](https://www.npmjs.com/package/dsh-mini-utility-dock)
+[![license](https://img.shields.io/badge/license-MIT-22c55e.svg)](./LICENSE)
+
+DSH 插件族的共享资产：源码片段、嵌入 CLI，以及围绕它们的跨仓诊断与双语文档校验工具。
 
 ## 片段
 
@@ -44,4 +51,6 @@ npm run dock:embed -- sync path/to/client.js
 
 消费仓的 `npm test` 用 `loopback:check` / `guard:check` 把本仓两个片段与所 pin 的 dock 版本逐字节比对。dock 版本不可变且消费仓 pin 精确版本，故「pin 一致」即「片段一致」。
 
-`scripts/guard-parity.mjs`（位于各消费仓）直接检这条跨仓性质，含 pin 一致性断言。它是人工诊断工具，**不在 CI 中运行**：peer 处于不同分支时该性质本就不成立。请在三个检出同分支时运行。
+`dsh-plugin-parity`（本包提供的 bin）直接检这条跨仓性质，含 pin 一致性断言与行为级对比。它是人工诊断工具，**不在 CI 中运行**：peer 处于不同分支时该性质本就不成立。成员表由调用方经 `--member <repo>:<export>` 提供——守卫工厂的导出名按片段设计是各仓自定的，故本工具不预设任何成员；不带 `--member` 时只跑静态检查，自动发现所有嵌入了宿主守卫块的仓。
+
+`dsh-plugin-docs`（同样是本包的 bin）校验双语文档的结构对齐：README 中英标题层级与代码围栏一致，CHANGELOG 中英版本段、分类段与条目数一致（分类标题经双语映射归一）；`--base <revision>` 额外要求双语对同改，单边改动即缺翻译。接入方式是各仓自己的 `docs:check` script 指向它——本包自身的双语文档也由此校验。

package/bin/dsh-plugin-docs.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// Bilingual structure check for the documentation pairs the DSH plugins ship:
+// README.md against README.en.md, CHANGELOG.md against CHANGELOG.en.md.
+//
+// Verifies, naming no repository and taking no file arguments (the four names
+// are the family convention):
+//   * both READMEs share the same heading-level sequence and code-fence
+//     languages — content inside fences is exempt, since that is where
+//     language-specific examples live;
+//   * both CHANGELOGs expose the same releases: version, date, per-section
+//     item counts, with section titles normalized through a bilingual
+//     category map (新增/Added, 修复/Fixed, ...);
+//   * with `--base <revision>`, both files of each pair changed together
+//     since that revision — a one-sided edit is a missing translation.
+//
+// Repositories opt in through their own `docs:check` script; this package
+// runs the same check on its own bilingual docs.
+
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+
+const read = (file) => fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n')
+
+function markdownShape(file) {
+  let fenced = false
+  const headings = []
+  const fences = []
+
+  for (const line of read(file).split('\n')) {
+    const fence = line.match(/^\s*```\s*(\S*)/)
+    if (fence) {
+      if (!fenced) fences.push(fence[1])
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+    const heading = line.match(/^(#{1,3})\s+/)
+    if (heading) headings.push(heading[1].length)
+  }
+
+  if (fenced) throw new Error(`${file}: unclosed code fence`)
+  return { headings, fences }
+}
+
+function changelogShape(file) {
+  const releases = []
+  let release
+  let section
+
+  for (const line of read(file).split('\n')) {
+    const version = line.match(/^##\s+(\d+\.\d+\.\d+)(?:\s+-\s+(\d{4}-\d{2}-\d{2}))?\s*$/)
+    if (version) {
+      release = { version: version[1], date: version[2] ?? '', sections: [] }
+      releases.push(release)
+      section = undefined
+      continue
+    }
+    if (!release) continue
+
+    const heading = line.match(/^###\s+(.+?)\s*$/)
+    if (heading) {
+      section = { title: heading[1], items: 0 }
+      release.sections.push(section)
+      continue
+    }
+    if (section && /^\s*-\s+/.test(line)) section.items += 1
+  }
+
+  return releases
+}
+
+const category = new Map([
+  ['新增', 'added'], ['Added', 'added'],
+  ['修复', 'fixed'], ['Fixed', 'fixed'],
+  ['变更', 'changed'], ['Changed', 'changed'],
+  ['移除', 'removed'], ['Removed', 'removed'],
+  ['安全', 'security'], ['Security', 'security'],
+  ['性能', 'performance'], ['Performance', 'performance'],
+  ['兼容性', 'compatibility'], ['Compatibility', 'compatibility'],
+  ['维护', 'maintenance'], ['Maintenance', 'maintenance'],
+])
+
+function assertEqual(left, right, message) {
+  if (JSON.stringify(left) !== JSON.stringify(right)) {
+    throw new Error(`${message}\nleft:  ${JSON.stringify(left)}\nright: ${JSON.stringify(right)}`)
+  }
+}
+
+const zhReadme = markdownShape('README.md')
+const enReadme = markdownShape('README.en.md')
+assertEqual(zhReadme, enReadme, 'README structure differs between languages')
+
+const normalizeLog = (file) => changelogShape(file).map((release) => ({
+  version: release.version,
+  date: release.date,
+  sections: release.sections.map(({ title, items }) => ({
+    title: category.get(title) ?? title.toLowerCase(),
+    items,
+  })),
+}))
+assertEqual(normalizeLog('CHANGELOG.md'), normalizeLog('CHANGELOG.en.md'), 'CHANGELOG structure differs between languages')
+
+const baseIndex = process.argv.indexOf('--base')
+if (baseIndex !== -1) {
+  const base = process.argv[baseIndex + 1]
+  if (!base) throw new Error('--base requires a Git revision')
+
+  const changed = new Set(execFileSync('git', ['diff', '--name-only', base, 'HEAD'], { encoding: 'utf8' })
+    .split(/\r?\n/)
+    .filter(Boolean))
+
+  for (const [primary, translation] of [
+    ['README.md', 'README.en.md'],
+    ['CHANGELOG.md', 'CHANGELOG.en.md'],
+  ]) {
+    if (changed.has(primary) !== changed.has(translation)) {
+      throw new Error(`${primary} and ${translation} must change together`)
+    }
+  }
+}
+
+console.log('bilingual docs are structurally aligned')

package/bin/dsh-plugin-parity.js

@@ -0,0 +1,498 @@
+// Cross-repo drift check for the shared host fragments.
+//
+// Why this exists: each member repository ships its own copy of the loopback
+// predicates and the request guard, because each package has to stand alone.
+// Those copies drifted repeatedly, and every drift was security-relevant:
+//
+//   1. every copy rejected IPv6 loopback (`::1`) — a legitimate browser was
+//      locked out of its own API;
+//   2. the copies disagreed on which Host spellings count as loopback, leaving
+//      one of them with an allowlist entry its Origin path could never reach;
+//   3. a Host that parsed to no hostname silently skipped the allowlist in one
+//      copy and was denied in the others.
+//
+// The copies are no longer hand-written: they are two embedded blocks generated
+// from dsh-mini-utility-dock by the dock CLI — `dist/loopback.js` (the predicates)
+// and `dist/guard.js` (the enforcement policy). So this checker asserts three
+// things a generator alone cannot:
+//
+//   * both embedded blocks are byte-identical in every member (a hand edit to
+//     one copy, or a repo that never re-ran `loopback:sync` / `guard:sync`, fails
+//     here), and they appear in dependency order — the guard uses the predicates
+//     the loopback block declares in the same file;
+//   * no repo keeps a private copy of an enforcement decision beside them — that
+//     is how drifts 1-3 happened, and embedding the blocks is worthless if a repo
+//     also branches on its own version;
+//   * the members AGREE ON EVERY DECISION. Error codes and wording deliberately
+//     differ (each plugin's published API vocabulary), so the comparison is on
+//     the allow/deny outcome only. This is the assertion that survives a policy
+//     change: byte equality implies it, but only this proves each consumer
+//     actually routes through the blocks.
+//
+// Usage:
+//   dsh-plugin-parity --root <dir> --member <repo>:<export> [--member ...]
+//   dsh-plugin-parity --root <dir>       # static checks for every member found
+//   dsh-plugin-parity --self-test        # exercises the extractor alone
+//
+// `--member` names one participating repository and the guard factory it
+// exports. That name is per-repository by design — the shared block is not
+// exported under a plugin-facing name, so each repository publishes its own —
+// which is why the member list is caller-supplied: this tool names no
+// repository of its own.
+//
+// With no `--member`, every directory under `--root` that carries the guard
+// markers is checked statically, and the decision comparison is skipped.
+//
+// This is a LOCAL DIAGNOSTIC, deliberately not a CI gate. Per-repo CI already
+// proves the stronger local property — `loopback:check` / `guard:check` compare
+// each repo's embedded blocks against the `dist/` of the exact dock version it
+// pins, and that version is immutable on npm. Members pinning one version
+// therefore hold byte-identical blocks by construction, which is why this script
+// is redundant as a gate and was removed from the compat workflow.
+//
+// The property it asserts is inherently cross-repository and cannot hold at an
+// arbitrary moment: on a `dev` push the peer checkouts resolve to their default
+// branch, so a difference reported here may mean only that the peers are on
+// `main`. Run it when every checkout is on the same branch — before a
+// release, or after one — and read a failure as a real signal then.
+//
+// Exit code 0 = identical blocks, one shared dock pin, no private copies, and
+// every decision agrees.
+
+import { readFileSync, readdirSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import { join } from 'node:path'
+
+const argv = process.argv.slice(2)
+const flagOf = (name) => {
+  const at = argv.indexOf(name)
+  return at >= 0 ? argv[at + 1] : null
+}
+
+const root = flagOf('--root') || process.env.DSH_PLUGINS_ROOT || process.cwd()
+
+// `--member <repo>:<export>` names one participating repository and the guard
+// factory it exports. Repeated once per participant.
+const members = []
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] !== '--member') continue
+  const [repo, factory] = String(argv[i + 1] || '').split(':')
+  if (!repo || !factory) {
+    console.error('dsh-plugin-parity: --member expects <repo>:<export>')
+    process.exit(2)
+  }
+  members.push([repo, repo, factory])
+}
+
+// With no member list, take every directory under the root that embeds the guard
+// block. Those members take part in the static checks only, which is all a
+// discovered member can support: the decision comparison needs a factory name.
+const discovered = () => readdirSync(root, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+  .map((entry) => entry.name)
+  .filter((name) => {
+    try { return readFileSync(join(root, name, 'lib', 'shared.js'), 'utf8').includes('// <dsh-host-guard>') }
+    catch { return false }
+  })
+  .sort()
+
+const repos = members.length ? members : discovered().map((name) => [name, name, null])
+const tags = repos.map(([, tag]) => tag).join('/')
+
+// Dependency order: the guard block uses the predicates the loopback block
+// declares, so it must come second.
+const BLOCKS = [
+  { name: 'dsh-loopback-helpers', label: 'loopback predicates' },
+  { name: 'dsh-host-guard', label: 'host guard' }
+]
+
+const marks = (name) => ({ start: `// <${name}>`, end: `// </${name}>` })
+
+// Pull a generated block out of a consumer's lib/shared.js. Everything between
+// the markers is generator output, so it must match byte for byte; the consumer
+// indents it, which is stripped before comparing.
+const extractBlock = (src, name) => {
+  const { start, end } = marks(name)
+  const lines = src.split(/\r?\n/)
+  const starts = lines.reduce((hits, line, i) => line.trim() === start ? [...hits, i] : hits, [])
+  const ends = lines.reduce((hits, line, i) => line.trim() === end ? [...hits, i] : hits, [])
+  if (starts.length !== 1 || ends.length !== 1 || ends[0] <= starts[0]) return null
+  return lines.slice(starts[0] + 1, ends[0]).map((line) => line.replace(/^\s{2}/, '')).join('\n').trim()
+}
+
+const read = (repo) => readFileSync(join(root, repo, 'lib', 'shared.js'), 'utf8')
+
+const spanOf = (src, name) => {
+  const { start, end } = marks(name)
+  const lines = src.split(/\r?\n/)
+  const from = lines.findIndex((line) => line.trim() === start)
+  const to = lines.findIndex((line) => line.trim() === end)
+  return from >= 0 && to > from ? { from, to } : null
+}
+
+// Everything that is neither block: the plugin's own code, which is where a
+// private copy of an enforcement decision would hide.
+const dropBlocks = (src) => {
+  const spans = BLOCKS.map((b) => spanOf(src, b.name)).filter(Boolean).sort((a, b) => b.from - a.from)
+  const lines = src.split(/\r?\n/)
+  for (const { from, to } of spans) lines.splice(from, to - from + 1)
+  return lines.join('\n')
+}
+
+// The dock version a repo embeds its blocks from. This is the one fact that is
+// genuinely cross-repository: the blocks themselves are proven locally against
+// whatever version is pinned here, and a version is immutable on npm, so equal
+// pins are what make the blocks equal — not the other way round.
+const dockPinOf = (repo) => {
+  const pkg = JSON.parse(readFileSync(join(root, repo, 'package.json'), 'utf8'))
+  const dev = (pkg.devDependencies || {})['dsh-mini-utility-dock']
+  const any = (pkg.dependencies || {})['dsh-mini-utility-dock']
+  return dev || any || null
+}
+
+if (process.argv.includes('--self-test')) {
+  const good = [
+    marks('dsh-loopback-helpers').start, 'const a = 1', marks('dsh-loopback-helpers').end,
+    marks('dsh-host-guard').start, 'const b = 2', marks('dsh-host-guard').end
+  ].join('\n')
+  const cases = [
+    ['first block extracted', 'dsh-loopback-helpers', good, 'const a = 1'],
+    ['second block extracted', 'dsh-host-guard', good, 'const b = 2'],
+    ['indent is stripped', 'dsh-loopback-helpers', [marks('dsh-loopback-helpers').start, '  const a = 1', marks('dsh-loopback-helpers').end].join('\n'), 'const a = 1'],
+    ['missing end marker returns null', 'dsh-loopback-helpers', [marks('dsh-loopback-helpers').start, 'const a = 1'].join('\n'), null],
+    ['absent block returns null', 'dsh-host-guard', good.replace(/dsh-host-guard/g, 'other'), null]
+  ]
+  let bad = 0
+  for (const [label, name, src, expected] of cases) {
+    const got = extractBlock(src, name)
+    const ok = got === expected
+    if (!ok) console.log(`self-test FAIL ${label}\n  expected: ${JSON.stringify(expected)}\n  got:      ${JSON.stringify(got)}`)
+    else console.log(`self-test ok   ${label}`)
+    if (!ok) bad++
+  }
+  // Dropping both blocks must leave only the plugin's own code.
+  const residual = dropBlocks(good)
+  const dropOk = !/const a = 1|const b = 2/.test(residual)
+  console.log(dropOk ? 'self-test ok   both blocks dropped' : `self-test FAIL both blocks dropped: ${JSON.stringify(residual)}`)
+  if (!dropOk) bad++
+  process.exit(bad ? 1 : 0)
+}
+
+let failures = 0
+
+// 1. Both generated blocks must be present, byte-identical everywhere, and in
+//    dependency order.
+for (const block of BLOCKS) {
+  const copies = repos.map(([repo, tag]) => ({ repo, tag, body: extractBlock(read(repo), block.name) }))
+  const missing = copies.filter((c) => c.body === null)
+  if (missing.length) {
+    console.log(`FAIL ${block.label}: missing or malformed markers in ${missing.map((m) => m.tag).join(', ')}`)
+    failures++
+    continue
+  }
+  const base = copies[0]
+  const drifted = copies.slice(1).filter((c) => c.body !== base.body)
+  if (drifted.length) {
+    console.log(`FAIL ${block.label}: ${drifted.map((d) => d.tag).join(', ')} differ from ${base.tag}`)
+    for (const d of drifted) {
+      console.log(`\n--- ${base.tag} (${base.repo}/lib/shared.js) ---\n${base.body}`)
+      console.log(`\n--- ${d.tag} (${d.repo}/lib/shared.js) ---\n${d.body}`)
+    }
+    failures++
+  } else {
+    console.log(`ok   ${block.label}: identical across ${tags} (${base.body.length} chars)`)
+  }
+}
+
+// 2. Every repo must embed from the same dock version. A skew here is the one
+//    cross-repo cause of divergence that per-repo checks cannot see: each repo's
+//    own `guard:check` passes against whatever it pins, so a repo left on an older
+//    dock stays green while its blocks differ from its siblings'.
+{
+  const pins = repos.map(([repo, tag]) => ({ tag, pin: dockPinOf(repo) }))
+  const unset = pins.filter((p) => p.pin === null)
+  const distinct = [...new Set(pins.map((p) => p.pin).filter((p) => p !== null))]
+  if (unset.length) {
+    console.log(`FAIL dock pin: not declared by ${unset.map((u) => u.tag).join(', ')}`)
+    failures++
+  } else if (distinct.length !== 1) {
+    console.log(`FAIL dock pin: versions differ — ${pins.map((p) => `${p.tag}=${p.pin}`).join(' ')}`)
+    failures++
+  } else {
+    // An exact pin is what makes the sibling repos hold identical blocks: a range
+    // could resolve to different builds under one declared value.
+    const exact = /^\d+\.\d+\.\d+$/.test(distinct[0])
+    if (!exact) {
+      console.log(`FAIL dock pin: ${JSON.stringify(distinct[0])} is not an exact version, so one declared value can resolve to different blocks`)
+      failures++
+    } else {
+      console.log(`ok   dock pin: every member embeds dsh-mini-utility-dock ${distinct[0]}`)
+    }
+  }
+}
+
+// The guard block reads what the loopback block declares in the same file, so the
+// order is load-bearing, not cosmetic.
+{
+  let orderBad = 0
+  for (const [repo, tag] of repos) {
+    const src = read(repo)
+    const loop = spanOf(src, 'dsh-loopback-helpers')
+    const guard = spanOf(src, 'dsh-host-guard')
+    if (!loop || !guard) continue
+    if (loop.from > guard.from) {
+      console.log(`FAIL ${tag}: the host guard block precedes the loopback predicates`)
+      orderBad++
+    }
+  }
+  if (orderBad) failures += orderBad
+  else console.log('ok   block order: the loopback predicates precede the host guard everywhere')
+}
+
+// 3. Embedding the blocks is worthless if a repo also keeps its own enforcement
+//    beside them. Policy is expected outside the blocks; decisions are not.
+//
+//    `remoteAddress` is deliberately NOT listed on its own: a plugin may keep a
+//    second helper that applies the same criterion for a different gate
+//    (dsh-instance-manager's `requestNeedsBearer` does exactly that, so the API
+//    route and the guard cannot drift apart). A private criterion only matters
+//    when the repo also owns a private guard, which the factory check catches.
+const ENFORCEMENT = [
+  [/LOOPBACK_HOSTNAMES\s*=/, 'redefines LOOPBACK_HOSTNAMES'],
+  [/(?:const|function|let)\s+isLoopbackName\b/, 'defines a private isLoopbackName'],
+  [/(?:const|function|let)\s+isLoopbackAddress\b/, 'defines a private isLoopbackAddress'],
+  [/(?:const|function|let)\s+hostHostname\b/, 'defines a private hostHostname'],
+  [/(?:const|function|let)\s+bindGuard\b/, 'defines a private guard factory'],
+  [/sec-fetch-site/, 'branches on Fetch Metadata outside the blocks']
+]
+for (const [repo, tag] of repos) {
+  const outside = dropBlocks(read(repo))
+  const problems = ENFORCEMENT.filter(([re]) => re.test(outside)).map(([, why]) => why)
+  if (/remoteAddress/.test(outside) && /function\s+guard\s*\(|=>\s*\{\s*$/.test(outside)) {
+    problems.push('looks like a private guard reading the socket peer')
+  }
+  if (problems.length) {
+    console.log(`FAIL ${tag}: ${problems.join('; ')}`)
+    failures++
+  } else {
+    console.log(`ok   ${tag}: no enforcement outside the generated blocks`)
+  }
+}
+
+// Everything above is static, so it covers discovered members too. The decision
+// comparison needs a factory name per member, which only `--member` supplies.
+if (!members.length) {
+  console.log(failures
+    ? `\n${failures} drift problem(s)`
+    : '\nno drift (static checks only; pass --member <repo>:<export> to compare decisions)')
+  process.exit(failures ? 1 : 0)
+}
+
+// 4. Every decision must agree across the members. Codes differ by design, so
+//    only the verdict is compared.
+//
+//    First confirm each repo exports the guard it is expected to. A repo whose
+//    blocks failed to parse is already reported above; without this check the
+//    decision cases below would throw `mods[repo][factory] is not a function` and
+//    bury the real diagnosis under a stack trace.
+const makeRes = () => ({
+  statusCode: null,
+  body: null,
+  writeHead(code) { this.statusCode = code; return this },
+  setHeader() {},
+  end() {}
+})
+
+const mods = {}
+for (const [repo] of repos) {
+  mods[repo] = await import(pathToFileURL(join(root, repo, 'lib', 'shared.js')).href)
+}
+
+const unusable = repos.filter(([repo, , factory]) => typeof mods[repo][factory] !== 'function')
+if (unusable.length) {
+  for (const [repo, tag, factory] of unusable) {
+    console.log(`FAIL ${tag}: lib/shared.js does not export a usable ${factory}() — the embedded blocks are stale or absent`)
+  }
+  failures += unusable.length
+  console.log('\ncannot compare decisions while a repo exports no guard')
+  console.log(failures ? `\n${failures} drift problem(s)` : '\nno drift')
+  process.exit(1)
+}
+
+// Each plugin names its own guard, so resolve it per repo. The guard is built
+// with `allowRemoteHost` only when the case asks for fleet mode, because a plugin
+// that never opts in must behave strictly.
+const verdict = (repo, factory, { host, origin, peer = '127.0.0.1', site = 'same-origin', fleet = false }) => {
+  const req = {
+    method: 'GET',
+    headers: { ...(host === undefined ? {} : { host }), ...(origin ? { origin } : {}), ...(site === null ? {} : { 'sec-fetch-site': site }) },
+    socket: peer === null ? {} : { remoteAddress: peer }
+  }
+  const res = makeRes()
+  const guard = mods[repo][factory]({
+    currentPort: () => 3080,
+    // Every plugin routes rejections through its own sink; a fake one keeps the
+    // comparison independent of each plugin's response shape.
+    respond: (target, code, body) => { target.statusCode = code; target.body = body },
+    ...(fleet ? { allowRemoteHost: () => true } : {})
+  })
+  return guard(req, res) ? 'allow' : 'deny'
+}
+
+const cases = [
+  // Host allowlist, including both spellings of the mapped IPv6 loopback.
+  ['loopback ipv4 host', { host: '127.0.0.1:3080' }, 'allow'],
+  ['loopback name host', { host: 'localhost:3080' }, 'allow'],
+  ['loopback ipv6 host', { host: '[::1]:3080' }, 'allow'],
+  ['mapped loopback host (dotted)', { host: '[::ffff:127.0.0.1]:3080' }, 'allow'],
+  ['mapped loopback host (hex)', { host: '[::ffff:7f00:1]:3080' }, 'allow'],
+  ['case-insensitive name', { host: 'LOCALHOST:3080' }, 'allow'],
+  ['absent host (host-side caller)', { host: undefined }, 'allow'],
+  ['foreign host', { host: 'rebound.example' }, 'deny'],
+  ['localhost subdomain', { host: 'api.localhost' }, 'deny'],
+  ['evil localhost subdomain', { host: 'evil.localhost:3080' }, 'deny'],
+  ['rebinding suffix', { host: '127.0.0.1.evil.example:3080' }, 'deny'],
+  ['public ip host', { host: '203.0.113.5:3080' }, 'deny'],
+  // An unparseable Host must fail closed rather than skip the allowlist.
+  ['unbracketed ipv6 host', { host: '::1:3080' }, 'deny'],
+  ['unbracketed mapped host', { host: '::ffff:127.0.0.1:3080' }, 'deny'],
+  // Fetch Metadata.
+  ['cross-site metadata', { host: '127.0.0.1:3080', site: 'cross-site' }, 'deny'],
+  ['same-origin metadata', { host: '127.0.0.1:3080', site: 'same-origin' }, 'allow'],
+  ['no metadata (non-browser)', { host: '127.0.0.1:3080', site: null }, 'allow'],
+  // Origin.
+  ['matching origin', { host: '127.0.0.1:3080', origin: 'http://127.0.0.1:3080' }, 'allow'],
+  ['ipv6 origin', { host: '[::1]:3080', origin: 'http://[::1]:3080' }, 'allow'],
+  ['mapped origin (hex, as URL normalises)', { host: '127.0.0.1:3080', origin: 'http://[::ffff:7f00:1]:3080' }, 'allow'],
+  ['origin on another port', { host: '127.0.0.1:3080', origin: 'http://127.0.0.1:3081' }, 'deny'],
+  ['foreign origin', { host: '127.0.0.1:3080', origin: 'https://evil.example' }, 'deny'],
+  ['rebinding origin', { host: '127.0.0.1:3080', origin: 'http://127.0.0.1.evil.example:3080' }, 'deny'],
+  // Peer address.
+  ['ipv6 loopback peer', { host: '127.0.0.1:3080', peer: '::1' }, 'allow'],
+  ['mapped loopback peer', { host: '127.0.0.1:3080', peer: '::ffff:127.0.0.1' }, 'allow'],
+  ['remote peer', { host: '127.0.0.1:3080', peer: '203.0.113.7' }, 'deny'],
+  ['private-range peer', { host: '127.0.0.1:3080', peer: '10.0.0.5' }, 'deny'],
+  ['missing peer', { host: '127.0.0.1:3080', peer: null }, 'deny'],
+  ['blank peer', { host: '127.0.0.1:3080', peer: '' }, 'deny'],
+  // A remote caller that also spoofs a loopback Host is still remote.
+  ['remote peer, loopback host', { host: '127.0.0.1:3080', peer: '203.0.113.7' }, 'deny']
+]
+
+let bad = 0
+for (const [label, req, expected] of cases) {
+  const verdicts = repos.map(([repo, , factory]) => verdict(repo, factory, req))
+  const agrees = new Set(verdicts).size === 1
+  const got = verdicts[0]
+  if (!agrees) {
+    console.log(`FAIL ${label}: ${repos.map(([, tag], i) => `${tag}=${verdicts[i]}`).join(' ')}`)
+    bad++
+  } else if (got !== expected) {
+    console.log(`FAIL ${label}: every member answered ${got}, expected ${expected}`)
+    bad++
+  }
+}
+if (bad) failures += bad
+else console.log(`ok   decisions: ${cases.length} cases agree across ${tags}`)
+
+// 5. Fleet mode is the one place the guard deliberately relaxes, and only the
+//    member named by `--fleet` opts in. Assert the relaxation stays bounded: a
+//    fleet guard still rejects a cross-site request, a foreign Origin, and a
+//    missing peer.
+const fleetMember = members.find(([repo]) => repo === flagOf('--fleet')) || null
+const fleetCases = [
+  ['fleet admits a peer host', { host: 'box.lan:3080' }, 'allow'],
+  ['fleet admits a remote peer', { host: '127.0.0.1:3080', peer: '203.0.113.7' }, 'allow'],
+  ['fleet still rejects cross-site', { host: 'box.lan:3080', site: 'cross-site' }, 'deny'],
+  ['fleet still rejects foreign Origin', { host: 'box.lan:3080', origin: 'https://evil.example' }, 'deny'],
+  ['fleet still rejects a missing peer', { host: 'box.lan:3080', peer: null }, 'deny']
+]
+if (!fleetMember) {
+  console.log('ok   fleet bounds: skipped (pass --fleet <repo> to check the member that opts in)')
+} else {
+  const fleetVerdict = (req) => verdict(fleetMember[0], fleetMember[2], { ...req, fleet: true })
+  let fleetBad = 0
+  for (const [label, req, expected] of fleetCases) {
+    const got = fleetVerdict(req)
+    if (got !== expected) {
+      console.log(`FAIL ${label}: fleet guard answered ${got}, expected ${expected}`)
+      fleetBad++
+    }
+  }
+  if (fleetBad) failures += fleetBad
+  else console.log(`ok   fleet bounds: ${fleetCases.length} cases hold`)
+}
+
+// 6. The predicates themselves, called directly, across every repo.
+const predicateCases = [
+  ['isLoopbackName', ['127.0.0.1', true], ['localhost', true], ['::1', true],
+    ['LOCALHOST', true], ['[::1]', false], ['::ffff:127.0.0.1', true],
+    ['::ffff:7f00:1', true], ['::ffff:8.8.8.8', false], ['::ffff:127.0.0.2', false],
+    ['127.0.0.2', false], ['127.0.0.1.evil.example', false], ['api.localhost', false],
+    ['', false], [null, false]],
+  ['isLoopbackAddress', ['127.0.0.1', true], ['127.255.0.1', true], ['::1', true],
+    ['::ffff:127.0.0.1', true], ['::ffff:7f00:1', true], ['::ffff:127.0.0.2', true],
+    ['::ffff:8.8.8.8', false], ['10.0.0.1', false], ['::2', false], ['localhost', false],
+    ['127.0.0.1.evil.example', false], ['::ffff:999.1.1.1', false], ['', false],
+    [null, false], ['  ', false]],
+  ['hostHostname', ['127.0.0.1:3080', '127.0.0.1'], ['[::1]:3080', '::1'],
+    ['[::ffff:127.0.0.1]:80', '::ffff:127.0.0.1'], ['REBOUND.EXAMPLE', 'rebound.example'],
+    [undefined, ''], ['localhost', 'localhost']]
+]
+for (const [fn, ...fnCases] of predicateCases) {
+  let fnBad = 0
+  for (const [input, expected] of fnCases) {
+    const answers = repos.map(([repo]) => mods[repo][fn](input))
+    if (new Set(answers).size !== 1) {
+      console.log(`FAIL ${fn}(${JSON.stringify(input)}): ${repos.map(([, tag], i) => `${tag}=${JSON.stringify(answers[i])}`).join(' ')}`)
+      fnBad++
+    } else if (answers[0] !== expected) {
+      console.log(`FAIL ${fn}(${JSON.stringify(input)}): every member answered ${JSON.stringify(answers[0])}, expected ${JSON.stringify(expected)}`)
+      fnBad++
+    }
+  }
+  if (fnBad) failures += fnBad
+  else console.log(`ok   ${fn}: ${fnCases.length} cases agree across ${tags}`)
+}
+
+// 7. portOf normalises the default ports, which is what stopped a same-origin
+//    request on 80/443 from reading as a foreign Origin.
+{
+  let portBad = 0
+  const portCases = [
+    ['http://127.0.0.1', '80'], ['https://127.0.0.1', '443'],
+    ['http://127.0.0.1:3080', '3080'], ['https://[::1]:443', '443']
+  ]
+  for (const [url, expected] of portCases) {
+    const answers = repos.map(([repo]) => mods[repo].portOf(new URL(url)))
+    if (new Set(answers).size !== 1 || answers[0] !== expected) {
+      console.log(`FAIL portOf(${url}): ${repos.map(([, tag], i) => `${tag}=${JSON.stringify(answers[i])}`).join(' ')} (expected ${expected})`)
+      portBad++
+    }
+  }
+  if (portBad) failures += portBad
+  else console.log(`ok   portOf: ${portCases.length} cases agree across ${tags}`)
+}
+
+// 8. An unknown policy key is a typo, and a typo would silently leave the default
+//    in place, so the shared factory throws. A plugin that names its own policy
+//    must not swallow that — it should reach the caller.
+{
+  let policyBad = 0
+  for (const [repo, tag, factory] of repos) {
+    let threw = false
+    try {
+      mods[repo][factory]({ currentPort: () => 3080, respond: () => {}, policy: { not_a_reason: { code: 'x' } } })
+    } catch {
+      threw = true
+    }
+    if (!threw) {
+      console.log(`FAIL ${tag}: an unknown policy key was accepted instead of throwing`)
+      policyBad++
+    }
+  }
+  if (policyBad) failures += policyBad
+  else console.log('ok   policy validation: an unknown key is rejected by every plugin')
+}
+
+console.log(failures ? `\n${failures} drift problem(s)` : '\nno drift')
+process.exit(failures ? 1 : 0)

package/dist/loopback.js

@@ -12,7 +12,7 @@
 // Why it is shared at all: these predicates were copy-pasted per repo and
 // drifted twice. The first drift rejected IPv6 loopback everywhere; the second
 // is that consumers disagreed on which Host spellings count as loopback
-// (see scripts/guard-parity.mjs, which compares this block across repos).
+// (see the parity bin this package ships, which compares this block across repositories).
 //
 // "Loopback" is decided in exactly one place — LOOPBACK_HOSTNAMES plus the
 // IPv4-mapped IPv6 form of each entry — and both the name and the address

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "dsh-mini-utility-dock",
-  "version": "0.1.8",
-  "description": "Canonical fragments and a build-time embedding CLI shared by DSH plugins: the Mini Utility Dock bootstrap for client halves, and the loopback predicates plus the host request guard for host halves.",
+  "version": "0.3.0",
+  "description": "The DSH plugin family's shared assets: source fragments (the Mini Utility Dock bootstrap for client halves, the loopback predicates and host request guard for host halves), the embedding CLI, and the family diagnostics — cross-repo drift check and bilingual docs structure check.",
   "type": "module",
   "bin": {
-    "dsh-mini-utility-dock": "bin/dsh-mini-utility-dock.js"
+    "dsh-mini-utility-dock": "bin/dsh-mini-utility-dock.js",
+    "dsh-plugin-parity": "bin/dsh-plugin-parity.js",
+    "dsh-plugin-docs": "bin/dsh-plugin-docs.js"
   },
   "files": [
     "bin",
@@ -17,6 +19,7 @@
   ],
   "scripts": {
     "dock:embed": "node bin/dsh-mini-utility-dock.js",
+    "docs:check": "node bin/dsh-plugin-docs.js",
     "test": "node --test test/*.test.js"
   },
   "engines": {