dsh-tower 2.4.0 → 2.4.1

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 ## 未发布（Unreleased）
 
+## 2.4.1（2026-10-24）
+
+### 修复
+
+- **可选组件行在 Plugins 页面只显示模块名**：每个可选能力导出现在提供
+  `<specifier>/locale/{en,zh}.json`（`meta.title` / `meta.description`），由
+  `locale/<lang>.json` 的 `components` 块经 `npm run docs:generate:locale` 生成，并由
+  `docs:check:generated:locale` + CI 步骤防漂移；描述同时说明能力用途与关闭后移除的内容，
+  开关无需离开页面即可判断。
+
 ## 2.4.0（2026-10-24）
 
 ### 新增

package/COMPATIBILITY.md

@@ -5,6 +5,7 @@ is shipped in the npm package; doctor reads it locally and never contacts a regi
 
 | dsh version | tag / commit | verified on | what was run |
 |---|---|---|---|
+| 0.2.1-rc.2 | v2.4.1 | 2026-10-24 | mount smoke (28/28 default tools, 3 skills, 2 presets, 1 bundle row), `npm test` (620), `types:coverage` 146/146, docs + seven generated checks incl capability-row locales, components + philosophy + surface gates |
 | 0.2.1-rc.2 | v2.4.0 | 2026-10-24 | mount smoke (28/28 default tools, 3 skills, 2 presets, 1 bundle row), `npm test` (612), `types:coverage` 146/146, strict ratchet 10, docs + six generated checks, components + philosophy + surface gates |
 | 0.2.1-rc.2 | v2.3.0 | 2026-10-23 | mount smoke (29 tower tools, `/tower`, 3 skills, 2 presets, single bundle row), `npm test` (573), `npm run docs:check`, four generated docs checks, philosophy + surface gates, live `--check` |
 | 0.2.1-rc.2 | v2.2.0 | 2026-10-23 | mount smoke (29 tower tools, `/tower`, 3 skills, 2 presets, single bundle row), `npm test` (536), `npm run docs:check`, four generated docs checks |

package/CONTRIBUTING.md

@@ -122,7 +122,7 @@ the push gates; CI schedules it nightly.
 
 ## Pull request checklist
 
-1. `npm test` passes locally (612 tests today, including protocol end-to-end against a real temporary Git repository and mock spawn coverage) and `npm run docs:check` passes.
+1. `npm test` passes locally (620 tests today, including protocol end-to-end against a real temporary Git repository and mock spawn coverage) and `npm run docs:check` passes.
 2. New behavior has a test. Bug fixes should add a test that fails before the fix.
 3. No secrets, tokens, personal paths, session logs, or generated artifacts are added. `.gitignore` covers local acceptance output; do not force-add it.
 4. Keep the public API and state-file formats compatible; if a change is breaking, call it out in `CHANGELOG.md` and bump the version.
@@ -137,7 +137,10 @@ the push gates; CI schedules it nightly.
    same PR, and `npm run surface:check` passes. A visible component change also updates
    `scripts/surface-baseline.json` (`components`), `scripts/component-surface.json` and
    `docs/reference/component-surface.md` (`npm run docs:generate:components`), and must pass
-   `npm run docs:check:components`.
+   `npm run docs:check:components`. A new visible capability row also ships its own
+   `<specifier>/locale/*.json` row label via `npm run docs:generate:locale` and passes
+   `npm run docs:check:generated:locale` (see
+   [architecture/overview.md](docs/architecture/overview.md#row-display-metadata-121)).
 
 ## Mount smoke
 

package/docs/architecture/overview.md

@@ -21,6 +21,50 @@ allowed to be switches is a table lookup in
 to a tool that is not on the recorded allowlist (empty since #122) and any
 `cordis.patch.yml` row that defaults a forbidden key off.
 
+### Row display metadata (#121)
+
+The Plugins page renders an optional row as `row.meta.title ?? row.moduleName`
+plus `row.meta.description`. The Host fills `row.meta` by resolving
+`<specifier>/locale/en.json` and then every sibling `<lang>.json` in that
+directory, reading `meta.title` / `meta.description`; title falls back to the full
+module specifier and description to empty when no resource resolves. That is why
+the mandatory `tower` card explains itself (the package root ships
+`locale/*.json`) while a bare subpath row would show only `dsh-tower/batch`.
+
+Each optional capability therefore ships its own resolvable subpath resource:
+`dsh-tower/skills/locale/{en,zh}.json` and the same for `batch`, `import`,
+`leases`, `tests` and `hmr`. `package.json` `exports` maps every
+`./<capability>/locale/*.json` to `./locale/<capability>/*.json`, and
+`files: ["locale/"]` ships the nested tree, so the lookup matches the installed
+package. The root `./locale/*.json` export stays so the Tower group keeps its own
+`meta`.
+
+The capability files are generated, never hand-written. `npm run
+docs:generate:locale` renders them from the `components` block of
+`locale/en.json` and `locale/zh.json` (the same source `docs:check:components`
+audits): `meta.title` is the component `title`, and `meta.description` joins the
+component `summary` (what the capability enables) with its `disables` text (what
+turning it off removes) behind a per-language "When off / 关闭后" label. The
+row is therefore decidable from the page alone. `npm run
+docs:check:generated:locale` fails on drift, runs in `npm run check`, and is its
+own step in the `test` CI job (`.github/workflows/test.yml`).
+
+To label a new capability row:
+
+1. Classify it in `scripts/component-surface.json`, ship it in
+   `cordis.patch.yml`, and add `title` / `summary` / `disables` to the
+   `components` block of both `locale/en.json` and `locale/zh.json`.
+2. Add `{ specifier, component }` to `CAPABILITY_LOCALES` in
+   `scripts/generate-capability-locale.mjs`, the matching
+   `./<specifier>/locale/*.json` export in `package.json`, and the row to the
+   coverage map in `tests/capability-locales.test.mjs`.
+3. Run `npm run docs:generate:locale`, then regenerate
+   `scripts/pack-manifest.txt` with `npm run pack:check -- --write`.
+
+The reviewer preset row is the one visible component that is not a package
+specifier: its label comes from the `cordis.patch.yml` preset `config.name` /
+`description`. The generated capability files never touch the root locale `meta`.
+
 ```
 Host plugin (index.js)
  ├─ /tower command + Tower mode (guard, prompt section, tower_mode/tower_control)

package/locale/batch/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Evidence batches",
+    "description": "Group missions into finite evidence batches and close them against required checks and receipts. When off: tower_batch is not registered; missions, gates and merges are unaffected."
+  }
+}

package/locale/batch/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "证据批次",
+    "description": "把 mission 归入有限证据批次，并按必需检查与回执关闭批次。关闭后：不再注册 tower_batch；mission、门禁与合并不受影响。"
+  }
+}

package/locale/hmr/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Dev hot reload",
+    "description": "Register tower_reload and /tower reload for linked-profile development. When off: tower_reload and /tower reload are unavailable; a non-HMR profile behaves exactly as before. Shipped off."
+  }
+}

package/locale/hmr/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "开发热重载",
+    "description": "为联动开发 profile 注册 tower_reload 与 /tower reload。关闭后：tower_reload 与 /tower reload 不可用；非 HMR profile 的行为与之前完全相同。随包默认关闭。"
+  }
+}

package/locale/import/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Legacy import",
+    "description": "Import a Tower Codex legacy state file and audit its snapshot-to-mission mapping. When off: tower_import_legacy and tower_legacy_map are not registered; new state is unaffected."
+  }
+}

package/locale/import/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "旧版导入",
+    "description": "导入 Tower Codex 旧状态文件，并审计快照到 mission 的映射。关闭后：不再注册 tower_import_legacy 与 tower_legacy_map；新状态不受影响。"
+  }
+}

package/locale/leases/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Advisory leases",
+    "description": "Coordinate heavy per-repository work with advisory resource leases. When off: tower_resource is not registered; nothing else depends on a lease."
+  }
+}

package/locale/leases/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "咨询式租约",
+    "description": "用咨询式资源租约协调每个仓库中的重型工作。关闭后：不再注册 tower_resource；其他能力不依赖租约。"
+  }
+}

package/locale/skills/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Tower skills",
+    "description": "Playbooks for worker/reviewer agents and recovery after a blocked merge. When off: The three Tower skills leave the catalog; the worker/reviewer protocol sections and every mission tool keep working."
+  }
+}

package/locale/skills/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Tower 技能包",
+    "description": "执行与审查代理的操作手册，以及失败后的恢复指南。关闭后：三个 Tower 技能从目录中移除；执行/审查协议段落与所有 mission 工具继续工作。"
+  }
+}

package/locale/tests/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Test discovery",
+    "description": "Run the worktree's declared test discovery and record a receipt for the mission tip. When off: tower_test is not registered and no receipt can be recorded; with gates.requireTests:true planning/mode entry is rejected with an explanation."
+  }
+}

package/locale/tests/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "测试发现",
+    "description": "运行 worktree 声明的测试发现，并为 mission tip 记录回执。关闭后：不再注册 tower_test，也无法记录回执；若 gates.requireTests:true，规划/进入模式会以解释性错误拒绝。"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tower",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "type": "module",
   "description": "DSH-native Tower: mission planning, worktree isolation, review-gated merges, and a human-owned Tower mode.",
   "license": "MIT",
@@ -36,6 +36,12 @@
     "./leases": "./host/capability-leases.js",
     "./tests": "./host/capability-tests.js",
     "./hmr": "./host/capability-hmr.js",
+    "./skills/locale/*.json": "./locale/skills/*.json",
+    "./batch/locale/*.json": "./locale/batch/*.json",
+    "./import/locale/*.json": "./locale/import/*.json",
+    "./leases/locale/*.json": "./locale/leases/*.json",
+    "./tests/locale/*.json": "./locale/tests/*.json",
+    "./hmr/locale/*.json": "./locale/hmr/*.json",
     "./locale/*.json": "./locale/*.json",
     "./icon": "./icon.svg",
     "./package.json": "./package.json"
@@ -54,7 +60,7 @@
     "types/",
     "cordis.patch.yml",
     "scripts/",
-    "locale/*.json",
+    "locale/",
     "icon.svg",
     "README.md",
     "README.en.md",
@@ -99,6 +105,8 @@
     "docs:check:generated:types": "node scripts/generate-types.mjs --check",
     "docs:generate:components": "node scripts/generate-component-surface.mjs",
     "docs:check:generated:components": "node scripts/generate-component-surface.mjs --check",
+    "docs:generate:locale": "node scripts/generate-capability-locale.mjs",
+    "docs:check:generated:locale": "node scripts/generate-capability-locale.mjs --check",
     "docs:check:components": "node scripts/check-components.mjs",
     "pack:check": "node scripts/check-pack.mjs",
     "architecture:check": "node scripts/architecture.mjs",
@@ -106,7 +114,7 @@
     "types:coverage": "node scripts/types-coverage.mjs",
     "types:strict:check": "node scripts/types-strict.mjs",
     "types:strict:write": "node scripts/types-strict.mjs --write",
-    "check": "npm test && npm run docs:check && npm run docs:check:philosophy && npm run docs:check:generated && npm run docs:check:generated:tools && npm run docs:check:generated:config && npm run docs:check:generated:events && npm run docs:check:generated:types && npm run docs:check:generated:components && npm run docs:check:components && npm run surface:check && npm run pack:check && npm run architecture:check && npm run types:coverage && npm run types:strict:check && npm run types:check && npm run domain:check",
+    "check": "npm test && npm run docs:check && npm run docs:check:philosophy && npm run docs:check:generated && npm run docs:check:generated:tools && npm run docs:check:generated:config && npm run docs:check:generated:events && npm run docs:check:generated:types && npm run docs:check:generated:components && npm run docs:check:generated:locale && npm run docs:check:components && npm run surface:check && npm run pack:check && npm run architecture:check && npm run types:coverage && npm run types:strict:check && npm run types:check && npm run domain:check",
     "domain:metrics": "node scripts/domain-metrics.mjs",
     "domain:check": "node scripts/domain-metrics.mjs --check"
   },

package/scripts/check-pack.mjs

@@ -10,6 +10,7 @@ import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { capabilityLocalePaths } from './generate-capability-locale.mjs'
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const REQUIRED_FILES = [
@@ -17,6 +18,9 @@ const REQUIRED_FILES = [
   'index.js',
   'locale/en.json',
   'locale/zh.json',
+  // #121: every optional capability row explains itself on the Plugins page
+  // through a subpath locale resource, so those generated files are required.
+  ...capabilityLocalePaths(),
   'ui-bundle/index.js',
   'ui-bundle/package.json',
   'ui-bundle/cordis.patch.yml',

package/scripts/generate-capability-locale.mjs

@@ -0,0 +1,148 @@
+// Generate the per-capability row locale files (#121).
+//
+// The DSH Plugins page renders an optional row as
+// `row.meta.title ?? row.moduleName` plus `row.meta.description`, and the Host
+// fills `row.meta` by resolving `<specifier>/locale/en.json` and then every
+// sibling `<lang>.json` in that directory. A subpath row without such a resource
+// therefore shows only `dsh-tower/batch`, and the switch is not decidable from
+// the page.
+//
+// Those files are generated, not hand-written: the single source of truth is the
+// `components` block of `locale/<lang>.json` that `npm run docs:check:components`
+// already audits. `meta.title` is the component `title`; `meta.description`
+// composes that component's `summary` (what the capability enables) with its
+// `disables` text (what turning it off removes), so the row explains the switch
+// in both directions.
+//
+// Usage:
+//   node scripts/generate-capability-locale.mjs [--root <dir>] [--check]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs, runMain } from './lib/cli.mjs'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const LANGUAGE_FILES = { en: 'locale/en.json', zh: 'locale/zh.json' }
+const LANGUAGES = Object.keys(LANGUAGE_FILES)
+// The off-effect marker is generated, not recovered from the hand-written
+// `disables` prose, so the check can prove every description names what the
+// switch removes without depending on one English or Chinese phrasing.
+const OFF_EFFECT_LABEL = { en: 'When off:', zh: '关闭后：' }
+
+/**
+ * The optional capability rows that need their own subpath locale resource, in
+ * the row order of `cordis.patch.yml`. The specifier is the module subpath the
+ * row mounts; the component id is the key in the locale `components` block.
+ */
+export const CAPABILITY_LOCALES = [
+  { specifier: 'skills', component: 'tower-skills' },
+  { specifier: 'batch', component: 'tower-batch' },
+  { specifier: 'import', component: 'tower-import' },
+  { specifier: 'leases', component: 'tower-leases' },
+  { specifier: 'tests', component: 'tower-tests' },
+  { specifier: 'hmr', component: 'tower-hmr' },
+]
+
+export const CAPABILITY_LOCALE_LANGUAGES = LANGUAGES
+
+/** Repo-relative paths of every generated capability locale file. */
+export function capabilityLocalePaths() {
+  return CAPABILITY_LOCALES.flatMap(({ specifier }) =>
+    LANGUAGES.map((lang) => `locale/${specifier}/${lang}.json`),
+  )
+}
+
+/** The `package.json` exports entry that exposes one capability's locale files. */
+export function capabilityLocaleExport(specifier) {
+  return { key: `./${specifier}/locale/*.json`, target: `./locale/${specifier}/*.json` }
+}
+
+function requireText(value, label) {
+  const text = typeof value === 'string' ? value.trim() : ''
+  if (!text) throw new Error(`${label} must be a non-empty string`)
+  return text
+}
+
+/**
+ * Compose the display metadata for one capability row in one language.
+ * @param {{ title: string, summary: string, disables: string }} entry
+ * @param {'en' | 'zh'} lang
+ */
+export function renderCapabilityMeta(entry, lang) {
+  const title = requireText(entry?.title, `${lang} capability title`)
+  const summary = requireText(entry?.summary, `${lang} capability summary`).replace(/\s+/g, ' ')
+  const disables = requireText(entry?.disables, `${lang} capability disables`).replace(/\s+/g, ' ')
+  // Chinese prose does not space CJK punctuation, so the label joins directly.
+  const space = lang === 'zh' ? '' : ' '
+  return {
+    meta: { title, description: `${summary}${space}${OFF_EFFECT_LABEL[lang]}${space}${disables}` },
+  }
+}
+
+/**
+ * Render every generated file for one repository root.
+ * @param {string} root
+ * @returns {Map<string, string>} repo-relative path -> file text
+ */
+export function renderCapabilityLocaleFiles(root) {
+  const locales = {}
+  for (const lang of LANGUAGES) {
+    const file = path.join(root, LANGUAGE_FILES[lang])
+    if (!fs.existsSync(file)) throw new Error(`${LANGUAGE_FILES[lang]} is missing under ${root}`)
+    locales[lang] = JSON.parse(fs.readFileSync(file, 'utf8'))
+  }
+  const files = new Map()
+  for (const { specifier, component } of CAPABILITY_LOCALES) {
+    for (const lang of LANGUAGES) {
+      const entry = locales[lang]?.components?.[component]
+      if (!entry) throw new Error(`${LANGUAGE_FILES[lang]} has no components.${component} entry`)
+      files.set(`locale/${specifier}/${lang}.json`, `${JSON.stringify(renderCapabilityMeta(entry, lang), null, 2)}\n`)
+    }
+  }
+  return files
+}
+
+function main(argv) {
+  const options = parseArgs(argv, {
+    initial: { root: PACKAGE_ROOT, check: false, help: false },
+    values: { '--root': { key: 'root', parse: path.resolve } },
+    flags: { '--check': 'check', '--help': 'help', '-h': 'help' },
+  })
+  if (options.help) {
+    console.log(`usage: node scripts/generate-capability-locale.mjs [--root <dir>] [--check]
+
+  --root   repository root to read and write (default: this package)
+  --check  fail when a committed file differs instead of writing it
+  --help   print this text
+
+The files are generated from the components block of locale/en.json and
+locale/zh.json; do not edit locale/<capability>/<lang>.json by hand.`)
+    return 0
+  }
+  const root = path.resolve(options.root)
+  const files = renderCapabilityLocaleFiles(root)
+  if (options.check) {
+    const stale = []
+    for (const [relative, expected] of files) {
+      const target = path.join(root, relative)
+      const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
+      if (actual !== expected) stale.push(relative)
+    }
+    if (stale.length > 0) {
+      console.error('capability locale files are stale; run npm run docs:generate:locale')
+      for (const relative of stale) console.error(`  ${relative}`)
+      return 1
+    }
+    console.log(`capability row locales: ${files.size} files in sync (${CAPABILITY_LOCALES.length} specifiers, en/zh)`)
+    return 0
+  }
+  for (const [relative, text] of files) {
+    const target = path.join(root, relative)
+    fs.mkdirSync(path.dirname(target), { recursive: true })
+    fs.writeFileSync(target, text)
+  }
+  console.log(`wrote ${files.size} capability row locale files (${CAPABILITY_LOCALES.length} specifiers, en/zh)`)
+  return 0
+}
+
+await runMain(import.meta.url, () => main(process.argv.slice(2)), { errorPrefix: 'capability-locales' })

package/scripts/pack-manifest.txt

@@ -162,7 +162,19 @@ host/tool-registry.js
 host/tower.js
 icon.svg
 index.js
+locale/batch/en.json
+locale/batch/zh.json
 locale/en.json
+locale/hmr/en.json
+locale/hmr/zh.json
+locale/import/en.json
+locale/import/zh.json
+locale/leases/en.json
+locale/leases/zh.json
+locale/skills/en.json
+locale/skills/zh.json
+locale/tests/en.json
+locale/tests/zh.json
 locale/zh.json
 package.json
 ports/archive.js
@@ -187,6 +199,7 @@ scripts/check-philosophy.mjs
 scripts/component-surface.json
 scripts/domain-metrics.mjs
 scripts/enable-dev-hmr.mjs
+scripts/generate-capability-locale.mjs
 scripts/generate-component-surface.mjs
 scripts/generate-config-reference.mjs
 scripts/generate-error-reference.mjs