dsh-mini-utility-dock 0.5.1 → 0.7.0

package/README.en.md

@@ -17,6 +17,7 @@ The DSH plugin family's shared assets: source fragments, an embedding CLI, and t
 | --- | --- | --- | --- |
 | loopback predicates | `dsh-loopback-helpers` | `lib/shared.js` | `LOOPBACK_HOSTNAMES`, `normalizeHostValue`, `hostHostname`, `isLoopbackName`, `isLoopbackAddress` |
 | host request guard | `dsh-host-guard` | `lib/shared.js` | `portOf`, `GUARD_REASONS`, `DEFAULT_GUARD_POLICY` |
+| host HTTP glue | `dsh-host-http` | `lib/shared.js` | `sendJson`, `CONNECTION_UNAVAILABLE`, `connectionUnavailable`, `REQUIRE_POST_REASONS`, `DEFAULT_REQUIRE_POST_POLICY`, `createRequirePost`, `createBrowserAuthorizer`, `optionalSessionId` |
 | utility launcher | `dsh-utility-launcher` | `lib/client.js` | `registerUtilityLauncher`, `UTILITY_ITEM_SLOT` |
 
 ## Usage
@@ -37,19 +38,34 @@ npm run dock:embed -- check path/to/shared.js
 npm run dock:embed -- sync path/to/shared.js
 ```
 
-Consumers invoke the same CLI as `loopback:sync` / `guard:sync` with the target fixed to their own `lib/shared.js`, and as `launcher:sync` for the `dsh-utility-launcher` block in their own `lib/client.js`.
+Consumers invoke the same CLI as `loopback:sync` / `guard:sync` / `http:sync` with the target fixed to their own `lib/shared.js`, and as `launcher:sync` for the `dsh-utility-launcher` block in their own `lib/client.js`. One command handles the three host-half blocks together: a block is selected by the marker that exists in the file, so `http:sync` and `loopback:sync` write different blocks of the same file.
 
 ## Constraints
 
-- `dist/` is the single source. Run `npm test` after a change, and re-`sync` consumers.
-- The two fragments in `lib/shared.js` have a fixed order, `dsh-loopback-helpers` first: `dsh-host-guard` uses the module-scope names the preceding fragment exports, and neither redeclares nor imports them.
+- `dist/` is the single source. After changing a fragment, run the whole set below under "Development and verification", and have consumers re-`sync`.
+- The three fragments in `lib/shared.js` have fixed positions: `dsh-loopback-helpers` → `dsh-host-guard` → `dsh-host-http`. The guard uses the module-scope names the preceding fragment exports, and neither redeclares nor imports them; `dsh-host-http` reads nothing from the two blocks above it and declares none of their names, so it can be embedded alone. Those positions are the `FRAGMENTS` order, and `sync` replaces blocks from the bottom of the file up; a file whose marker ranges overlap is rejected outright and left unwritten.
+- `dsh-utility-launcher` lands in the client half: exactly one copy of the assembly runs per page (the first to load wins the `window` mutex and declares the menu seat), and every other copy contributes one row to that seat. That is a runtime fact, not a styling choice.
 - A fragment must not contain `import` or `require`; a consumer must publish standalone.
 - `bindGuard` is not exported — a consumer declares its own guard export in the same file. Each plugin passes its own error codes and wording through `policy`; the enforcement is shared.
+- `createRequirePost({ respond, policy })` works the same way: the default code is `method`, and a repository's published vocabulary — `need_post`, Chinese wording, the `action` echoed back — is an override of `policy.method_not_allowed`, not a behavior difference. An unknown key throws.
+- `createBrowserAuthorizer({ getConnection, getConnectionSeen, guard, respond })` takes accessors, not values: a host half's Connection is reassigned to `null` by a service reload, and the value-shaped version would keep admitting requests through a destroyed Connection. The semantics are fixed: a Connection that throws answers 503 `connection_unavailable`; a rejection is answered with its own code (401 → `unauthorized`, anything else → `forbidden`); a Connection that was seen but is absent now answers 503 and never falls back to the weaker guard; a host that never had one is decided by `guard`.
 
 ## Cross-repo consistency
 
-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.
+A consumer's `npm test` runs `loopback:check` / `guard:check` / `http:check`, comparing the three blocks in its own `lib/shared.js` 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. The converse does not hold: `check` selects blocks by the markers it recognizes, so a consumer that has not raised its pin never looks at a block the older CLI does not know and that one check passes vacuously. After a fragment is added, a consumer re-runs all four `sync` scripts and raises its pin to the released version in the same commit.
 
-`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-parity` (a bin provided by this package) checks that cross-repo property directly: every host block compared in isolation after stripping the block's common indentation (the three, `dsh-host-http` included), pin agreement, block position, 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; `--fleet <repo>` names the single member that opts into fleet mode, and only its guard is checked for "the relaxation stays bounded", while naming a repository that is not a member fails with a non-zero exit; without `--member` it runs the static checks only and discovers every checkout that embeds the guard block. `--self-test` needs no checkout at all: it exercises the block extractor and the block-dropping step against inline samples, so run it first whenever either changes.
 
-`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.
+`dsh-plugin-docs` (another bin of this package) checks the bilingual documentation pairs for structural alignment. It names no document of its own: which pairs to check, which directory holds them, and how each is compared come from an array of `{ name, zh, en, shape? }` that the calling repository supplies through `--config <module>`; this package declares its own pairs in `docs.config.mjs` the same way. Two shapes exist. The default, `markdown`, compares the heading-level sequence and the code-fence languages on both sides; content inside a fence is exempt because that is where language-specific examples live. `changelog` compares the releases on both sides, the `Unreleased` section included, together with their sections and item counts, with section titles normalized through a bilingual category map. `--base <revision>` additionally requires both files of each declared pair to have changed since that revision: a one-sided edit is a missing translation. When that revision is the all-zero null OID, which is what `github.event.before` carries for a newly created or force-pushed branch, there is no previous state to compare, so that one requirement is skipped with a note while the structural checks still run. Repositories call it from their own `docs:check` script.
+
+## Development and verification
+
+`dist/` is the source, so one change has to pass three layers: fragment behavior, the CLI, and the documentation pair. This is the full check of this repository (identical to the Verify block in `AGENTS.md`; the release procedure is in `docs/RELEASING.md`):
+
+```sh
+npm test
+node bin/dsh-plugin-docs.js
+for f in bin/*.js dist/*.js; do node --check "$f"; done
+node bin/dsh-plugin-parity.js --self-test
+npm pack --dry-run
+```

package/README.md

@@ -17,6 +17,7 @@ DSH 插件族的共享资产：源码片段、嵌入 CLI，以及围绕它们的
 | --- | --- | --- | --- |
 | loopback 判定 | `dsh-loopback-helpers` | `lib/shared.js` | `LOOPBACK_HOSTNAMES`、`normalizeHostValue`、`hostHostname`、`isLoopbackName`、`isLoopbackAddress` |
 | host 请求守卫 | `dsh-host-guard` | `lib/shared.js` | `portOf`、`GUARD_REASONS`、`DEFAULT_GUARD_POLICY` |
+| host HTTP 胶水 | `dsh-host-http` | `lib/shared.js` | `sendJson`、`CONNECTION_UNAVAILABLE`、`connectionUnavailable`、`REQUIRE_POST_REASONS`、`DEFAULT_REQUIRE_POST_POLICY`、`createRequirePost`、`createBrowserAuthorizer`、`optionalSessionId` |
 | utility 入口 | `dsh-utility-launcher` | `lib/client.js` | `registerUtilityLauncher`、`UTILITY_ITEM_SLOT` |
 
 ## 使用
@@ -37,19 +38,34 @@ npm run dock:embed -- check path/to/shared.js
 npm run dock:embed -- sync path/to/shared.js
 ```
 
-消费插件以 `loopback:sync` / `guard:sync` 调用同一 CLI，目标固定为自身 `lib/shared.js`；client 半以 `launcher:sync` 维护 `dsh-utility-launcher` 块，目标固定为自身 `lib/client.js`。
+消费插件以 `loopback:sync` / `guard:sync` / `http:sync` 调用同一 CLI，目标固定为自身 `lib/shared.js`；client 半以 `launcher:sync` 维护 `dsh-utility-launcher` 块，目标固定为自身 `lib/client.js`。宿主半的三个块由一条命令一并处理：标记存在即被选中，因此 `http:sync` 与 `loopback:sync` 写的是同一个文件里的不同块。
 
 ## 约束
 
-- `dist/` 是唯一来源。改片段后运行 `npm test`，并让消费插件重新 `sync`。
-- `lib/shared.js` 中两个片段顺序固定，`dsh-loopback-helpers` 在前：`dsh-host-guard` 直接使用前一片段导出的模块级名字，既不重新声明也不 import。
+- `dist/` 是唯一来源。修改片段后执行下面「开发与验证」列出的命令，并让消费插件重新 `sync`。
+- `lib/shared.js` 中三个片段的落点固定：`dsh-loopback-helpers` → `dsh-host-guard` → `dsh-host-http`。守卫直接使用前一块声明的模块级名字，既不重新声明也不 import；`dsh-host-http` 不读上面两块、也不声明它们的名字，故可单独嵌入。落点顺序即 `FRAGMENTS` 顺序；`sync` 自下而上替换块，标记区间彼此交叠的文件会被直接拒绝、不写出任何内容。
+- `dsh-utility-launcher` 落在 client 半：每页只运行一份该装配（先加载的一方赢得 `window` 互斥并声明菜单座位），其余副本只往座位里投一行。这是运行时事实，不是样式选择。
 - 片段不得包含 `import` 或 `require`；消费插件必须能独立发布。
 - `bindGuard` 不从片段导出——消费插件在同一文件中声明自己的 guard 导出。各插件通过 `policy` 传入自身错误码与文案，判定逻辑共用。
+- `createRequirePost({ respond, policy })` 同上：默认 code 是 `method`，一个仓已发布的词汇（例如 `need_post`、中文文案、回带 `action`）由 `policy.method_not_allowed` 覆盖，行为不变；未知 key 抛错。
+- `createBrowserAuthorizer({ getConnection, getConnectionSeen, guard, respond })` 收的是访问器而非值：宿主半的 Connection 会被服务重载置空，捕获值的那一版会一直放行给一个已销毁的 Connection。语义固定：Connection 抛异常 → 503 `connection_unavailable`；给出 rejection → 以该码回绝（401 → `unauthorized`，其余 → `forbidden`）；见过 Connection 而当下没有 → 503，且绝不退回更弱的 guard；从未见过 → 交给 `guard`。
 
 ## 跨仓一致性
 
-消费仓的 `npm test` 用 `loopback:check` / `guard:check` 把本仓两个片段与所 pin 的 dock 版本逐字节比对。dock 版本不可变且消费仓 pin 精确版本，故「pin 一致」即「片段一致」。
+消费插件的 `npm test` 用 `loopback:check` / `guard:check` / `http:check` 把自己 `lib/shared.js` 里的三个块与所 pin 的 dock 版本逐字节比对。dock 版本不可变且消费方 pin 精确版本，故「pin 一致」即「片段一致」。反向不成立：`check` 只按它能识别的标记选块，一个还没抬 pin 的消费方根本不比对新增的那个块，对它这一项是空过的。所以新增片段后，消费方要重跑四个 `sync`，并把 pin 一起抬到发布版本。
 
-`dsh-plugin-parity`（本包提供的 bin）直接检这条跨仓性质，含 pin 一致性断言与行为级对比。它是人工诊断工具，**不在 CI 中运行**：peer 处于不同分支时该性质本就不成立。成员表由调用方经 `--member <repo>:<export>` 提供——守卫工厂的导出名按片段设计是各仓自定的，故本工具不预设任何成员；不带 `--member` 时只跑静态检查，自动发现所有嵌入了宿主守卫块的仓。
+`dsh-plugin-parity`（本包提供的 bin）直接检这条跨仓性质：逐块（剥离块的公共缩进后）比对三个 host 块（含 `dsh-host-http`）、pin 一致性断言、块落点顺序断言与行为级对比。它是人工诊断工具，**不在 CI 中运行**：peer 处于不同分支时该性质本就不成立。成员表由调用方经 `--member <repo>:<export>` 提供——守卫工厂的导出名按片段设计是各仓自定的，故本工具不预设任何成员；`--fleet <repo>` 点名唯一启用 fleet 模式的成员，只对它检查「放宽有边界」，点名不在成员表中的仓即判 FAIL 并非零退出；不带 `--member` 时只跑静态检查，自动发现所有嵌入了宿主守卫块的仓。`--self-test` 不需要任何 checkout：它用内联样例检验块提取与「丢块」两步，改动这两个函数后先跑它。
 
-`dsh-plugin-docs`（同样是本包的 bin）校验双语文档的结构对齐：README 中英标题层级与代码围栏一致，CHANGELOG 中英版本段、分类段与条目数一致（分类标题经双语映射归一）；`--base <revision>` 额外要求双语对同改，单边改动即缺翻译。接入方式是各仓自己的 `docs:check` script 指向它——本包自身的双语文档也由此校验。
+`dsh-plugin-docs`（同样是本包的 bin）校验双语文档的结构对齐。它不预设文档名：检查哪些文档对、文件位于哪个目录、按什么形状比较，都由调用仓通过 `--config <module>` 提供一个 `{ name, zh, en, shape? }` 数组决定；本包用同一种方式声明自己的 `docs.config.mjs`。形状有两种。默认的 `markdown` 比较中英两侧的标题层级序列与代码围栏语言，围栏内的内容豁免，因为语言相关的示例写在那里。`changelog` 比较中英两侧的版本段（含 `Unreleased` 段）、分类段与小节条目数，分类标题经双语映射归一。`--base <revision>` 额外要求声明的每一对文件在该 revision 之后一起改动，单边改动即缺翻译；revision 为全 0 的 null OID（新建分支或强推时 `github.event.before` 即为此值）时没有可比的前态，这一项跳过并给出提示，其余结构校验照常。各仓的 `docs:check` script 调用它。
+
+## 开发与验证
+
+片段是唯一来源，所以一次改动要同时过片段行为、CLI 与文档这三层；下面是本仓的完整校验（与 `AGENTS.md` 的 Verify 块一致，发布步骤见 `docs/RELEASING.md`）：
+
+```sh
+npm test
+node bin/dsh-plugin-docs.js
+for f in bin/*.js dist/*.js; do node --check "$f"; done
+node bin/dsh-plugin-parity.js --self-test
+npm pack --dry-run
+```

package/bin/dsh-mini-utility-dock.js

@@ -1,42 +1,59 @@
 #!/usr/bin/env node
 // Embed a canonical fragment from this package into a consumer file.
 //
-// Three fragments are maintained the same way, because all three have the same
+// Every fragment is maintained the same way, because all of them have the same
 // shape of problem: the consumer must ship the code standalone (a browser classic
-// script cannot `import`, and a host half must not depend on the dock being
+// script cannot `import`, and a host half must not depend on this package being
 // installed), so the code is embedded at build time and drift is a build error.
 //
-//   dsh-utility-launcher   -> <dsh-utility-launcher> ... </dsh-utility-launcher>
-//     the family launcher (one icon plus the menu of family panels it opens),
-//     embedded into a plugin's lib/client.js
-//
 //   dsh-loopback-helpers   -> <dsh-loopback-helpers> ... </dsh-loopback-helpers>
 //     the loopback predicates, embedded into a plugin's lib/shared.js
 //
 //   dsh-host-guard         -> <dsh-host-guard> ... </dsh-host-guard>
 //     the same-origin request guard, embedded into the same file
 //
-// The host half of a plugin embeds BOTH shared.js fragments, in the order above,
-// because the guard imports the predicates. Each is an independent block with its
-// own markers and its own check, so a plugin that only needs the predicates can
-// embed just those.
+//   dsh-host-http          -> <dsh-host-http> ... </dsh-host-http>
+//     the host response glue: JSON replies, the POST gate, the browser
+//     authorizer, embedded into the same file below the guard block
+//
+//   dsh-utility-launcher   -> <dsh-utility-launcher> ... </dsh-utility-launcher>
+//     the shared launcher assembly: one icon plus the menu of utility panels it
+//     opens, embedded into a plugin's lib/client.js
+//
+// The host half of a plugin embeds ALL THREE shared.js fragments, in the order
+// above, because its guard reads the predicates the block above it declares. Each
+// is an independent block with its own markers and its own check, so a plugin that
+// only needs the predicates can embed just those.
 //
 // The fragment is selected by the marker already present in the target file, so
 // one command serves every target and only a named block is ever touched. A
 // consumer calls this through its own `launcher:sync` / `guard:sync` /
-// `loopback:sync` script; the paired `check` mode is what CI runs.
+// `loopback:sync` / `http:sync` script; the paired `check` mode is what CI runs.
 
 import { readFile, writeFile, stat } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-// Listed in dependency order: the guard fragment reads the predicates the
-// loopback fragment declares, so a consumer that wants the guard syncs both, in
-// this order, into the same file. The launcher is independent of both and lands
-// in the client half instead, so it sits last.
+// Listed in the order the blocks sit in a consumer's file. That order is
+// load-bearing for the consumer, not for this tool:
+//
+//   1. the guard fragment reads the predicates the loopback fragment declares, so
+//      a consumer that wants the guard syncs both, loopback first;
+//   2. the host-http fragment lands below the guard block, where a consumer's own
+//      `lib/shared.js` glue has always lived. It depends on neither block above
+//      it and declares nothing they declare, so the three coexist in one file;
+//   3. the launcher is independent of all of them and lands in the client half
+//      instead, so it sits last.
+//
+// `main()` replaces each block working from the bottom of the file upward, and it
+// orders that pass by the line numbers it found rather than by this list, so
+// adding a row here states where a block sits and cannot shift another block's
+// splice. Registering a fragment whose markers sit in a different order is still
+// worth catching — `dsh-plugin-parity` checks it across repositories.
 const FRAGMENTS = [
   { name: 'dsh-loopback-helpers', source: 'loopback.js' },
   { name: 'dsh-host-guard', source: 'guard.js' },
+  { name: 'dsh-host-http', source: 'host-http.js' },
   { name: 'dsh-utility-launcher', source: 'launcher.js' }
 ]
 
@@ -44,12 +61,19 @@ const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url)))
 const marker = (name, edge) => `// <${edge}${name}>`
 
 function usage() {
-  const fragments = FRAGMENTS.map((f) => `  ${marker(f.name, '')} -> dist/${f.source}`).join('\n')
+  const fragments = FRAGMENTS.map((f) => `  ${marker(f.name, '')} ... ${marker(f.name, '/')}  ->  dist/${f.source}`).join('\n')
   return [
     'Usage: dsh-mini-utility-dock <sync|check> <consumer-file>',
     '',
-    'The fragment is chosen by the marker already present in <consumer-file>:',
-    fragments
+    'The blocks to maintain are the ones whose markers are present in <consumer-file>;',
+    'one command handles every block in that file:',
+    fragments,
+    '',
+    'A plugin host half embeds the three lib/shared.js blocks: the loopback',
+    'predicates, the same-origin guard that reads them, and the host HTTP glue',
+    '(JSON replies, the POST gate, the browser authorizer) below the guard. The',
+    'launcher block belongs to the client half in lib/client.js.',
+    '`sync` writes them, `check` exits non-zero on drift.'
   ].join('\n')
 }
 
@@ -72,9 +96,10 @@ function indentation(line) {
 }
 
 // Locate every marked block in the file, in fragment order. A host half embeds
-// both shared.js fragments, so one command must maintain both; processing them in
-// FRAGMENTS order also keeps the dependency order (the guard reads the predicates
-// declared by the loopback block above it).
+// all three shared.js fragments, so one command must maintain all of them;
+// processing them in FRAGMENTS order also keeps the dependency order (the guard
+// reads the predicates declared by the loopback block above it, and the HTTP glue
+// sits below both without reading either).
 function locate(source) {
   const lines = source.split(/\r?\n/)
   const candidates = FRAGMENTS.map((fragment) => {
@@ -91,7 +116,20 @@ function locate(source) {
       throw new Error(`expected exactly one marked block for ${fragment.name} (${marker(fragment.name, '')} ... ${marker(fragment.name, '/')})`)
     }
   }
-  return { lines, blocks: candidates.map(({ fragment, start, end }) => ({ fragment, start: start[0], end: end[0] })) }
+  const blocks = candidates.map(({ fragment, start, end }) => ({ fragment, start: start[0], end: end[0] }))
+  // Each block is replaced by splicing its own line range, so two different
+  // fragments' ranges must not overlap. Interleaved markers (`<A> <B> </A> </B>`)
+  // would make one pass write into the range another pass had just rewritten, so
+  // the result would be corrupted rather than merely stale; the uniqueness of each
+  // marker pair is enforced above, and this closes the case a single pair cannot.
+  for (let i = 0; i < blocks.length; i++) {
+    for (let j = i + 1; j < blocks.length; j++) {
+      if (blocks[i].start <= blocks[j].end && blocks[j].start <= blocks[i].end) {
+        throw new Error(`marked blocks for ${blocks[i].fragment.name} and ${blocks[j].fragment.name} overlap; each marker pair must enclose its own lines`)
+      }
+    }
+  }
+  return { lines, blocks }
 }
 
 function rendered(lines, fragmentSource, block) {
@@ -101,9 +139,9 @@ function rendered(lines, fragmentSource, block) {
   return [...lines.slice(0, block.start + 1), ...body, ...lines.slice(block.end)]
 }
 
-// Applied from the LAST block to the first. Each pass replaces a line range, so
-// doing it bottom-up leaves every earlier block's line indices valid; going
-// top-down would shift them and a later pass would splice the wrong lines.
+// One pass over the target file maintains EVERY marked block it carries, applied
+// from the bottom of the file upward so each block's line indices are still valid
+// when its turn comes. See the loop below for why that order is the whole trick.
 async function main() {
   const [command, fileName, ...rest] = process.argv.slice(2)
   if (!['sync', 'check'].includes(command) || !fileName || rest.length) throw new Error(usage())
@@ -112,7 +150,14 @@ async function main() {
 
   let lines = located.lines
   const applied = []
-  for (const block of [...located.blocks].reverse()) {
+  // Walk by line position, the block nearest the end of the file first. Each pass
+  // replaces a line range, so every block above it must keep valid indices; going
+  // top-down would shift them and a later pass would splice the wrong lines.
+  // `locate()` has already rejected any file whose marker ranges overlap, so these
+  // blocks are disjoint: the pass can be ordered by the lines themselves rather
+  // than by the table, and a table/file order disagreement then only rewrites
+  // blocks in a different sequence, corrupting nothing.
+  for (const block of [...located.blocks].sort((a, b) => b.start - a.start)) {
     const fragmentSource = await readFile(resolve(packageRoot, 'dist', block.fragment.source), 'utf8')
     lines = rendered(lines, fragmentSource, block)
     applied.unshift(block.fragment.name)

package/bin/dsh-plugin-docs.js

@@ -1,23 +1,31 @@
 #!/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.
+// Bilingual structure check for the documentation pairs a repository ships.
 //
-// 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
+// The pairs are the repository's own declaration — `--config <module>` points at
+// a module exporting `{ name, zh, en, shape? }` entries, so which documents
+// exist, where they live, and how each is compared is decided there, never here.
+// Two shapes are provided:
+//   * `markdown` (the default): both files share the same heading-level sequence
+//     and code-fence languages — content inside fences is exempt, since that is
+//     where language-specific examples live;
+//   * `changelog`: both files expose the same releases — the `Unreleased` section
+//     included, since that is where the newest edits land — with version, date,
+//     per-section item counts, 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.
+//   * with `--base <revision>`, both files of every declared pair changed
+//     together since that revision — a one-sided edit is a missing translation.
+//     An all-zero revision is the null OID, which is what `github.event.before`
+//     carries for a branch that was just created or force-pushed: there is no
+//     previous revision to diff against, so that one requirement is skipped with
+//     a note instead of dying inside `git diff`.
 //
 // Repositories opt in through their own `docs:check` script; this package
-// runs the same check on its own bilingual docs.
+// declares its pairs the same way.
 
 import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 const read = (file) => fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n')
 
@@ -47,12 +55,26 @@ function changelogShape(file) {
   let release
   let section
 
+  // A `## ...` heading opens a release and clears the current section, so bullets
+  // that follow it before any `###` still count — into an anonymous leading
+  // section — instead of being silently dropped.
+  const openRelease = (version, date) => {
+    release = { version, date, sections: [] }
+    releases.push(release)
+    section = undefined
+  }
+
   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
+      openRelease(version[1], version[2] ?? '')
+      continue
+    }
+    // `Unreleased` is the version-less top release and usually the most-edited
+    // section, so it is compared with the same shape as a numbered one. Both
+    // languages keep the literal heading, so the labels match directly.
+    if (/^##\s+Unreleased\s*$/i.test(line)) {
+      openRelease('Unreleased', '')
       continue
     }
     if (!release) continue
@@ -63,7 +85,13 @@ function changelogShape(file) {
       release.sections.push(section)
       continue
     }
-    if (section && /^\s*-\s+/.test(line)) section.items += 1
+    if (/^\s*-\s+/.test(line)) {
+      if (!section) {
+        section = { title: '', items: 0 }
+        release.sections.push(section)
+      }
+      section.items += 1
+    }
   }
 
   return releases
@@ -80,16 +108,6 @@ const category = new Map([
   ['维护', '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,
@@ -98,23 +116,69 @@ const normalizeLog = (file) => changelogShape(file).map((release) => ({
     items,
   })),
 }))
-assertEqual(normalizeLog('CHANGELOG.md'), normalizeLog('CHANGELOG.en.md'), 'CHANGELOG structure differs between languages')
+
+function assertEqual(left, right, message) {
+  if (JSON.stringify(left) !== JSON.stringify(right)) {
+    throw new Error(`${message}\nleft:  ${JSON.stringify(left)}\nright: ${JSON.stringify(right)}`)
+  }
+}
+
+// The repository declares its own pairs; this tool names none of them. Paths are
+// read from the current directory, so run it from the repository root — `--base`
+// compares against paths as Git reports them.
+async function loadPairs(argv) {
+  const index = argv.indexOf('--config')
+  const file = argv[index + 1]
+  if (index === -1 || !file) {
+    throw new Error('--config <module> is required: the module exports the bilingual pairs this repository ships')
+  }
+  if (!fs.existsSync(file)) throw new Error(`${file} not found — declare the repository's pairs there`)
+
+  const loaded = await import(pathToFileURL(path.resolve(file)).href)
+  const pairs = loaded.pairs ?? loaded.default
+
+  if (!Array.isArray(pairs) || pairs.length === 0) {
+    throw new Error(`${file}: export a non-empty array of pairs`)
+  }
+  for (const pair of pairs) {
+    for (const field of ['name', 'zh', 'en']) {
+      if (typeof pair?.[field] !== 'string' || !pair[field]) throw new Error(`${file}: every pair needs name, zh and en`)
+    }
+    if (pair.shape !== undefined && !shapes[pair.shape]) throw new Error(`${file}: ${pair.name}: unknown shape '${pair.shape}'`)
+  }
+  return pairs
+}
+
+const shapes = { markdown: markdownShape, changelog: normalizeLog }
+
+const pairs = await loadPairs(process.argv)
+
+for (const pair of pairs) {
+  const shape = shapes[pair.shape ?? 'markdown']
+  assertEqual(shape(pair.zh), shape(pair.en), `${pair.name} 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`)
+  // The null OID, in either hash length. A workflow that passes
+  // `github.event.before` here gets it whenever a branch is created or
+  // force-pushed, and `git diff 000... HEAD` is not a comparison with no base —
+  // it is an error. So the honest reading is the one the push event states: there
+  // is nothing before this push, and the pair test cannot run.
+  if (/^0+$/.test(base)) {
+    console.log(`note: --base ${base} is the null OID (new branch or force-push) — pair-change check skipped`)
+  } else {
+    const changed = new Set(execFileSync('git', ['diff', '--name-only', base, 'HEAD'], { encoding: 'utf8' })
+      .split(/\r?\n/)
+      .filter(Boolean))
+
+    for (const pair of pairs) {
+      if (changed.has(pair.zh) !== changed.has(pair.en)) {
+        throw new Error(`${pair.zh} and ${pair.en} must change together`)
+      }
     }
   }
 }