dsh-mini-utility-dock 0.1.3 → 0.1.5

package/CHANGELOG.en.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.5 - 2026-09-17
+
+- Documentation maintenance: README and CHANGELOG cleanup. Fragments and command behavior are unchanged, so consumer pins need no update.
+
+## 0.1.4 - 2026-09-16
+
+- Add a cross-repo consistency section to the READMEs, separating two different properties: **local** -- a consumer's `npm test` runs `loopback:check` / `guard:check` to compare both fragments byte-for-byte against the version of this package it pins, covering both "edited a block by hand" and "forgot to re-`sync`"; and **cross-repo** -- this package's published versions are immutable and consumers pin an exact version, so "all three pin the same version" already implies "all three hold byte-identical blocks".
+- That section also records that a consumer's `scripts/guard-parity.mjs` is a **manual diagnostic, not a CI gate**, because the property it asserts cannot hold while a peer checkout resolves to a different branch, which would make it report false failures.
+- The LICENSE copyright holder is now `xswt442-cmd`.
+
 ## 0.1.3 - 2026-09-14
 
 - Add two host-side fragments. `dist/loopback.js` (`dsh-loopback-helpers`) exports `LOOPBACK_HOSTNAMES`, `normalizeHostValue`, `hostHostname`, `isLoopbackName` and `isLoopbackAddress`. `dist/guard.js` (`dsh-host-guard`) exports `portOf`, `GUARD_REASONS`, `DEFAULT_GUARD_POLICY` and an internal `bindGuard()` factory; a consumer passes its own error codes and wording as `policy`, so the enforcement does not fork per plugin.

package/CHANGELOG.md

@@ -1,11 +1,21 @@
 # Changelog
 
+## 0.1.5 - 2026-09-17
+
+- 文档维护：README 与 CHANGELOG 的整理，片段与命令行为不变，故无需改动消费仓的 pin。
+
+## 0.1.4 - 2026-09-16
+
+- README 新增「跨仓一致性」一节：本地由消费仓 `npm test` 的 `loopback:check` / `guard:check` 逐字节比对，跨仓由消费仓 pin 精确版本保证。
+- 该节记录 `scripts/guard-parity.mjs` 是人工诊断工具而非 CI 门禁。
+- LICENSE 版权署名统一为 `xswt442-cmd`。
+
 ## 0.1.3 - 2026-09-14
 
-- 新增两个 host 侧片段：`dist/loopback.js`（`dsh-loopback-helpers`）导出 `LOOPBACK_HOSTNAMES`、`normalizeHostValue`、`hostHostname`、`isLoopbackName`、`isLoopbackAddress`；`dist/guard.js`（`dsh-host-guard`）导出 `portOf`、`GUARD_REASONS`、`DEFAULT_GUARD_POLICY` 与内部的 `bindGuard()` 工厂。调用方以 `policy` 传入自己的错误码与文案，判定逻辑不随之分叉。
-- `sync` / `check` 改为处理目标文件中**所有**已标记的片段，按 `FRAGMENTS` 顺序自下而上应用，不再要求恰好一个块。单块调用方的行为不变。
-- 修正 README 与包描述：说明 host 侧两个片段各自的职责、固定顺序，以及 `bindGuard` 不导出的原因。
-- 新增测试：多块同步与幂等 `check`、块顺序、两个片段均不引入 `import`/`require`、`bindGuard` 不导出且判据不被重复声明。
+- 新增两个 host 侧片段：`dist/loopback.js`（`dsh-loopback-helpers`）导出回环判定谓词；`dist/guard.js`（`dsh-host-guard`）导出 `portOf`、`GUARD_REASONS`、`DEFAULT_GUARD_POLICY` 与内部的 `bindGuard()` 工厂，调用方以 `policy` 传入自己的错误码与文案。
+- `sync` / `check` 处理目标文件中所有已标记的片段，按 `FRAGMENTS` 顺序自下而上应用。
+- 修正 README 与包描述：说明两个 host 侧片段的职责、固定顺序与 `bindGuard` 不导出的原因。
+- 新增测试：多块同步与幂等 `check`、块顺序、片段不引入 `import`/`require`、判据不被重复声明。
 
 ## 0.1.2 - 2026-09-06
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 PracticalIssue
+Copyright (c) 2026 xswt442-cmd
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.en.md

@@ -1,53 +1,45 @@
 # dsh-mini-utility-dock
 
-Source fragments and an embedding CLI shared by the DSH plugins. Fragments are written into a consumer at build time, so a plugin publishes standalone with no dependency on this package.
+Source fragments and an embedding CLI shared by the DSH plugins.
 
 ## Fragments
 
-Three fragments, each delimited by markers.
-
 | Fragment | Marker | Target file | Exports |
 | --- | --- | --- | --- |
 | dock bootstrap | `dsh-mini-utility-dock` | `lib/client.js` | — |
 | 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` |
 
-`dsh-loopback-helpers` decides address locality; the Host-header path and the TCP-peer path share one decision. `dsh-host-guard` decides admission, and provides a `bindGuard()` factory internally.
-
 ## Usage
 
 Write the markers into the target file, then run the CLI.
 
 ```sh
-npx dsh-mini-utility-dock sync path/to/client.js
-npx dsh-mini-utility-dock check path/to/client.js
+npx dsh-mini-utility-dock sync path/to/shared.js
+npx dsh-mini-utility-dock check path/to/shared.js
 ```
 
-`sync` preserves the markers and their indentation and writes the fragment; `check` exits non-zero when the content no longer matches it. The CLI maintains every marked fragment in the target file, applied bottom-up in `FRAGMENTS` order. A file containing a single fragment is unaffected.
+The CLI maintains every marked fragment in the file, applied bottom-up in `FRAGMENTS` order. `sync` preserves marker indentation; `check` exits non-zero on drift.
 
-This repository also exposes an equivalent entry point, with the target path passed by the caller:
+Equivalent entry point from this repository (target passed by the caller):
 
 ```sh
-npm run dock:embed -- check path/to/client.js  # verify only, non-zero on drift
-npm run dock:embed -- sync path/to/client.js   # write between the markers
+npm run dock:embed -- check path/to/client.js
+npm run dock:embed -- sync path/to/client.js
 ```
 
-Consumers invoke the same CLI as `loopback:sync` / `guard:sync`, with the target fixed to their own `lib/shared.js`; either command maintains both fragments in that file.
-
-## The two host-side fragments
-
-The two fragments in `lib/shared.js` have a fixed order, `dsh-loopback-helpers` first.
-
-The order is a functional requirement, not a style choice. Both fragments occupy one file, and `dsh-host-guard` uses the module-scope names the preceding fragment exports. It therefore neither redeclares those predicates nor imports a sibling module: redeclaring collides with the declaration in the same file, and importing would break the standalone-publication constraint. The `guard-parity` check fails when the order is reversed.
-
-`bindGuard` is not exported from the fragment. A consumer declares its own guard export in the same file (typically reusing an existing name such as `createGuard`), and exporting the same identifier would collide. Each plugin calls `bindGuard()` and passes its own error codes and wording through `policy`: the enforcement is shared, the error vocabulary stays with each plugin.
+Consumers invoke the same CLI as `loopback:sync` / `guard:sync`, with the target fixed to their own `lib/shared.js`.
 
-## Development
+## Constraints
 
-`dist/` is the single source for each fragment. Run `npm test` after a change; consumers that have already embedded a fragment must re-run the matching `sync` command.
+- `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.
+- 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.
+- A missing, blank, or non-string `label` falls back to `id`.
 
-A fragment must not contain `import` or `require`: it shares a file with the consumer's own code, and the consumer must publish standalone. Tests assert this constraint.
+## Cross-repo consistency
 
-## Registration
+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 missing, blank, or non-string `label` falls back to `id`, so no item renders `aria-label="undefined"`.
+`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.

package/README.md

@@ -1,53 +1,45 @@
 # dsh-mini-utility-dock
 
-DSH 插件共享的源码片段与嵌入 CLI。片段在构建时写入消费插件，使插件无需依赖本包即可独立发布。
+DSH 插件共享的源码片段与嵌入 CLI。
 
 ## 片段
 
-三个片段，均由标记界定。
-
 | 片段 | 标记 | 目标文件 | 导出 |
 | --- | --- | --- | --- |
 | dock 引导 | `dsh-mini-utility-dock` | `lib/client.js` | — |
 | 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` |
 
-`dsh-loopback-helpers` 定义地址的归属：Host 头与 TCP 对端两条路径共用同一判定。`dsh-host-guard` 定义准入策略，并在内部提供 `bindGuard()` 工厂。
-
 ## 使用
 
 在目标文件中写入标记，然后运行 CLI。
 
 ```sh
-npx dsh-mini-utility-dock sync path/to/client.js
-npx dsh-mini-utility-dock check path/to/client.js
+npx dsh-mini-utility-dock sync path/to/shared.js
+npx dsh-mini-utility-dock check path/to/shared.js
 ```
 
-`sync` 保留标记及其缩进并写入片段；`check` 在内容与片段不一致时以非零状态退出。CLI 处理目标文件中所有已标记的片段，按 `FRAGMENTS` 顺序自下而上应用。仅含单个片段的文件行为不变。
+CLI 处理文件中所有已标记的片段，按 `FRAGMENTS` 顺序自下而上应用；`sync` 保留标记缩进，`check` 在漂移时非零退出。
 
-本仓库另提供等价入口，目标路径由调用方传入：
+本仓库等价入口（目标由调用方传入）：
 
 ```sh
-npm run dock:embed -- check path/to/client.js  # 仅校验，漂移时非零退出
-npm run dock:embed -- sync path/to/client.js   # 写入标记之间
+npm run dock:embed -- check path/to/client.js
+npm run dock:embed -- sync path/to/client.js
 ```
 
-消费插件以 `loopback:sync` / `guard:sync` 调用同一 CLI，目标固定为自身的 `lib/shared.js`；任一命令都会同步该文件中的两个片段。
-
-## host 侧两个片段的约定
-
-`lib/shared.js` 中的两个片段顺序固定，`dsh-loopback-helpers` 在前。
-
-顺序是功能要求，不是风格约定。两者位于同一文件，`dsh-host-guard` 直接使用前一片段导出的模块级名字，因此它既不重新声明这些判据，也不 import 兄弟模块：重新声明与 import 都会与同文件内的声明冲突，且 import 会破坏插件独立发布的约束。`guard-parity` 检查在该顺序被颠倒时失败。
-
-`bindGuard` 不从片段导出。消费插件在同一文件中声明自己的 guard 导出（通常沿用 `createGuard` 等既有名字），导出同名标识符会冲突。每个插件调用 `bindGuard()`，通过 `policy` 传入自身的错误码与文案；判定逻辑共用，错误词汇由各插件持有。
+消费插件以 `loopback:sync` / `guard:sync` 调用同一 CLI，目标固定为自身 `lib/shared.js`。
 
-## 开发
+## 约束
 
-片段的唯一来源是 `dist/`。修改后运行 `npm test`；已嵌入片段的消费插件需重新运行对应的 `sync` 命令。
+- `dist/` 是唯一来源。改片段后运行 `npm test`，并让消费插件重新 `sync`。
+- `lib/shared.js` 中两个片段顺序固定，`dsh-loopback-helpers` 在前：`dsh-host-guard` 直接使用前一片段导出的模块级名字，既不重新声明也不 import。
+- 片段不得包含 `import` 或 `require`；消费插件必须能独立发布。
+- `bindGuard` 不从片段导出——消费插件在同一文件中声明自己的 guard 导出。各插件通过 `policy` 传入自身错误码与文案，判定逻辑共用。
+- `label` 缺省、空白或非字符串时回退为 `id`。
 
-片段不得包含 `import` 或 `require`：它们与消费插件自身的代码位于同一文件，且消费插件必须独立发布。测试对此约束进行断言。
+## 跨仓一致性
 
-## 注册
+消费仓的 `npm test` 用 `loopback:check` / `guard:check` 把本仓两个片段与所 pin 的 dock 版本逐字节比对。dock 版本不可变且消费仓 pin 精确版本，故「pin 一致」即「片段一致」。
 
-`label` 缺省、空白或非字符串时回退为 `id`，避免渲染出 `aria-label="undefined"`。
+`scripts/guard-parity.mjs`（位于各消费仓）直接检这条跨仓性质，含 pin 一致性断言。它是人工诊断工具，**不在 CI 中运行**：peer 处于不同分支时该性质本就不成立。请在三个检出同分支时运行。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mini-utility-dock",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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.",
   "type": "module",
   "bin": {