Merge pull request #23 from stack-wuh/fix/20260918-fix-installer-ci-cmd-assert

fix(installer): .cmd 断言补平台门，恢复 linux/macos CI 门禁

Author: stack-wuh

shadow-docs/changes/20260918-fix-installer-ci-cmd-assert/brief.md

@@ -0,0 +1,76 @@
+---
+{
+  "schema": "shadow-dev/v1",
+  "name": "20260918-fix-installer-ci-cmd-assert",
+  "type": "fix",
+  "scope": null,
+  "status": "branched",
+  "baseBranch": "main",
+  "branch": "fix/20260918-fix-installer-ci-cmd-assert",
+  "files": [],
+  "github": {
+    "repository": "stack-wuh/shadow-dev-cli",
+    "issue": 22,
+    "issueUrl": "https://github.com/stack-wuh/shadow-dev-cli/issues/22",
+    "pullRequest": null,
+    "pullRequestUrl": null
+  },
+  "review": {
+    "conclusion": "pending",
+    "verifiedCommit": null,
+    "verifiedAt": null
+  },
+  "workflow": {
+    "operation": null,
+    "checkpoint": "issue:22",
+    "planHash": "de68a5b25e152b369e06ce10b5bedfa40cf9888b26eaacb1bacbef49b7e7af05",
+    "updatedAt": null,
+    "lastError": null,
+    "issuePlan": {
+      "title": "[fix] 安装器契约测试 Linux/macOS 恒红：.cmd 断言补平台门",
+      "titleRaw": null,
+      "supplement": "",
+      "body": "## 动机\n`test/install.test.mjs` 用例 53 无条件断言 `$BIN/shadow-dev.cmd` 存在，但 `.cmd` 按设计只在 MINGW/MSYS/CYGWIN 下生成（`gen_shims` 的 uname 分支）。结果 ubuntu/macos 矩阵自 38b1364（安装器引入）起 **main 分支 CI 持续红色**——红 CI 掩盖真实回归、让后续所有 PR 在坏门禁下合并（#18/#21 均如此）。本变更修复断言本身，恢复 CI 门禁价值。\n\n## 引用规范\n- shadow-docs/knowledge/install-distribution.md\n  - 当前结论: 托管 shim 为 `.sh` 全平台 + `.cmd` 仅 Windows；验证方式登记 8 用例\n  - 适用 scope: scripts/install-cli.sh, test/install.test.mjs\n- norms/tdd-verification.md\n  - 当前结论: 完成前必须有可查验证；本变更的\"红\"在 CI 非 Windows 矩阵（本地 win 恒真无法复现），PR 上 CI 矩阵转绿即验证\n\n## 决策\n- **选型:** 平台门：`platform() === 'win32'` 时才断言 `.cmd` 存在（单行修复，非 win 环境断言 `.cmd` 不存在反而更贴合设计——顺带钉住\"不越平台生成\"）。\n- **对比方案:** 让 `gen_shims` 在 unix 也生成 `.cmd` 被否——unix 下 `.cmd` 无运行语义，为迁就错误断言改正确行为是反模式。\n- **理由:** 断言错、行为对；测试向契约对齐，不是相反。\n\n## 任务\n- [ ] task-1 — `test/install.test.mjs` — 用例 53 的 `.cmd` 断言加平台门（win32 存在 / 其他平台不存在）\n- [ ] task-2 — `scripts/install-cli.sh` 无改动（确认边界）；`shadow-docs/knowledge/install-distribution.md` — 验证方式登记平台分支语义，source 追加本 brief\n\n完整 brief：shadow-docs/changes/20260918-fix-installer-ci-cmd-assert/brief.md\n\n<!-- shadow-dev:issue-metadata {\"name\":\"20260918-fix-installer-ci-cmd-assert\",\"type\":\"fix\",\"scope\":null,\"status\":\"proposed\",\"branch\":null,\"baseBranch\":\"main\",\"briefPath\":\"shadow-docs/changes/20260918-fix-installer-ci-cmd-assert/brief.md\",\"cliVersion\":\"1.2.0\",\"prUrl\":null,\"issueNumber\":null} -->\n",
+      "labels": [
+        "fix"
+      ]
+    }
+  }
+}
+---
+
+# 安装器契约测试 Linux/macOS 恒红：.cmd 断言补平台门
+
+## 动机
+
+`test/install.test.mjs` 用例 53 无条件断言 `$BIN/shadow-dev.cmd` 存在，但 `.cmd` 按设计只在 MINGW/MSYS/CYGWIN 下生成（`gen_shims` 的 uname 分支）。结果 ubuntu/macos 矩阵自 38b1364（安装器引入）起 **main 分支 CI 持续红色**——红 CI 掩盖真实回归、让后续所有 PR 在坏门禁下合并（#18/#21 均如此）。本变更修复断言本身，恢复 CI 门禁价值。
+
+## 引用规范
+
+- shadow-docs/knowledge/install-distribution.md
+  - 当前结论: 托管 shim 为 `.sh` 全平台 + `.cmd` 仅 Windows；验证方式登记 8 用例
+  - 适用 scope: scripts/install-cli.sh, test/install.test.mjs
+- norms/tdd-verification.md
+  - 当前结论: 完成前必须有可查验证；本变更的"红"在 CI 非 Windows 矩阵（本地 win 恒真无法复现），PR 上 CI 矩阵转绿即验证
+
+## 决策
+
+- **选型:** 平台门：`platform() === 'win32'` 时才断言 `.cmd` 存在（单行修复，非 win 环境断言 `.cmd` 不存在反而更贴合设计——顺带钉住"不越平台生成"）。
+- **对比方案:** 让 `gen_shims` 在 unix 也生成 `.cmd` 被否——unix 下 `.cmd` 无运行语义，为迁就错误断言改正确行为是反模式。
+- **理由:** 断言错、行为对；测试向契约对齐，不是相反。
+
+## 任务
+
+- [x] task-1 — `test/install.test.mjs` — 用例 53 的 `.cmd` 断言加平台门（win32 存在 / 其他平台不存在）
+- [x] task-2 — `scripts/install-cli.sh` 无改动（确认边界）；`shadow-docs/knowledge/install-distribution.md` — 验证方式登记平台分支语义，source 追加本 brief
+
+## 结果
+
+- 实际耗时: —
+- 验证: —
+
+## 知识评估
+
+- **预期影响:** 更新
+- **候选卡片:** shadow-docs/knowledge/install-distribution.md
+- **理由:** 卡片验证方式需钉住 `.cmd` 平台分支语义，防再次写出跨平台恒假断言

shadow-docs/knowledge/install-distribution.md

@@ -8,7 +8,8 @@ source:
   - changes/20260917-feature-install-cli-script/brief.md
   - changes/20260917-fix-installer-url-taint/brief.md
   - changes/20260917-feature-install-link-mode/brief.md
-verified: 2026-09-17
+  - changes/20260918-fix-installer-ci-cmd-assert/brief.md
+verified: 2026-09-18
 ---
 
 # shadow-dev CLI 安装与分发模型
@@ -32,7 +33,7 @@ verified: 2026-09-17
 
 ## 验证方式
 
-`node --test test/install.test.mjs` 全绿即契约成立（8 用例：离线物化+shim 运行、幂等/--force、非托管 shim 保护、回滚往返、坏产物、link 映射/优先/回退、link 校验与 guard、dry-run+status+参数拒绝）。手工复验：`bash scripts/install-cli.sh link <本仓库>` 后 `shadow-dev change list --archived` 立即可用且 `install --json` 后仍走 link（LINK 优先）；`unlink` 后回物化版本；`status --json` 的 `linked`/`current` 如实反映。
+`node --test test/install.test.mjs` 全绿即契约成立（8 用例：离线物化+shim 运行、幂等/--force、非托管 shim 保护、回滚往返、坏产物、link 映射/优先/回退、link 校验与 guard、dry-run+status+参数拒绝）。shim 面是**平台分支**的：`.sh` 全平台生成，`.cmd` 仅 MINGW/MSYS/CYGWIN——测试断言 `.cmd` 必须带 `platform() === 'win32'` 平台门，恒真/恒假的跨平台断言会让 CI 门禁失真（历史上 main 因此连红一天）。手工复验：`bash scripts/install-cli.sh link <本仓库>` 后 `shadow-dev change list --archived` 立即可用且 `install --json` 后仍走 link（LINK 优先）；`unlink` 后回物化版本；`status --json` 的 `linked`/`current` 如实反映。
 
 ## 关联知识
 

test/install.test.mjs

@@ -53,7 +53,7 @@ test('offline install: pointer, managed shims, installed shim runs', skip, () =>
   assert.equal(readFileSync(join(prefix, 'CURRENT'), 'utf8').trim(), '9.9.9')
   const shim = readFileSync(join(bin, 'shadow-dev'), 'utf8')
   assert.match(shim, /managed-by: shadow-dev-cli-installer/)
-  assert.ok(existsSync(join(bin, 'shadow-dev.cmd')))
+  assert.equal(existsSync(join(bin, 'shadow-dev.cmd')), platform() === 'win32', '.cmd shim is generated on Windows only')
   const viaShim = spawnSync('bash', [toUnix(join(bin, 'shadow-dev')), 'help'], { encoding: 'utf8' })
   assert.equal(viaShim.status, 0, viaShim.stderr)
   assert.match(viaShim.stdout, /"ok":true/)