dsh-gitbash-shell 0.40.3 → 0.40.4

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 > 倒序排列,新版本条目在最上面。条目格式:`## vX.Y.Z — YYYY-MM-DD` + 类型(feat / fix / docs / chore)+ 要点 + 相关链接。
 > 纪律见 AGENTS.md「变更记录纪律」:发版前先更新本文件并随版本提交;事故复盘、复现与真机验证记录也记在这里。
 
+## v0.40.4 — 2026-10-17
+
+### 终端工具扫描只认可执行条目：手册页/文档/同名目录不再冒充命令（fix）
+
+- `scanCommands`（`src/toolchain.js`）原先用 `entry.replace(/\.[^./\\]+$/, '')` 剥掉**任意**扩展名，于是 PATH 目录里任何与工具同名的条目都算命中：
+  - **真实案例**：winget 便携包目录中 `just.1`（手册页）在字典序上排在 `just.exe` 之前，而扫描是「首个命中者胜出」⇒ 卡片「完整路径 / 由谁提供」列把手册页当成了 `just` 的可执行文件（实测 `commandPath` = `…\Casey.Just_Microsoft.Winget.Source_8wekyb3d8bbwe\just.1`）。
+  - **判定层影响**：`classifyToolState` 在 `wingetOwned === false` 时只看 `hasCommand`，所以一台**确实没装**该命令、而 PATH 里恰好有同名文档 / 手册页 / 目录的机器，该行会被判成 `external`（`isActionable` 为 false）——**安装入口永不出现**。本机 `just` 之所以未暴露，只是 winget 清单命中在前把它掩盖了。
+- 修法（**纯函数改动、零 io 变更**）：新增扩展名白名单 `EXEC_EXTS = {.exe,.cmd,.bat,.com}`，扩展名不在白名单的条目直接跳过；**无扩展名照旧命中**——Git for Windows 自带 `/usr/bin/make` 这类无扩展名可执行文件（`fzf` 同理），这条不能丢。未加 `.` / `..` 防御分支：`readdirSync` 本就不返回这两项。
+- 回归用例（`tests/smoke.mjs`「only executable extensions resolve」）锁三层：手册页 / 文档 / 目录不命中；无扩展名真可执行仍命中；`just.1` 排在 `just.exe` 之前时**首个可执行命中者**路径正确（另覆盖 `.EXE` 大小写）。判定层补一条联动断言：扫不到 ⇒ `missing` ⇒ `isActionable` 为真。**该用例已在未修复的源码上验证会失败**（`actual: 'C:/pkg\just.1'`），修复后通过。
+- 目录区分（无扩展名目录 vs 无扩展名 MSYS 可执行文件）**留作后续**：需要给 `io.readdir` 增加 `stat`/`Dirent` 能力并牵动调用方，本版不动 io 契约。
+- 验证：Windows 10.0.26200 / Node 24.19.0，`npm test` 通过（当时基线计数把 skip 计入记作 237；维护者复核：基线 235 pass + 1 skip，合并分支 236 pass + 1 skip，本用例恰好多 1）。维护者另在 macOS / Node 24 复跑全量同绿，CI ubuntu+windows × Node 22/24 四矩阵绿。
+- 相关：[issue #31](https://github.com/KannaKuron/dsh-gitbash-shell/issues/31)。
+
 ## v0.40.3 — 2026-10-17
 
 ### gitBash 能力服务新增 `pwshToolEnabled`(feat,additive——配对 dsh-ptc-cordis-preset v0.20.1)

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-gitbash-shell",
-  "version": "0.40.3",
+  "version": "0.40.4",
   "main": "./src/index.js",
   "description": "Windows 全模式 Git Bash:自带 bash 工具(私有 Git Bash 执行器实例,官方 PowerShell 执行器原样保留),官方四个模式经行内工具补位直接获得 Git Bash(v0.35.0 起;v0.39.0 起不再替换宿主执行器),四个 *·Git Bash 变体 preset 可开关;官方 pwsh 工具默认隐藏、开关可见(真 PowerShell);附带 gb_* FastCtx 文件工具,检测到 dsh-ops 自动让位。联动:dsh-ptc-cordis-preset(PTC 创造模式带 Git Bash 行且可去重)+ dsh-better-sidebar(终端标签自动切 Git Bash)。",
   "engines": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gitbash-shell",
-  "version": "0.40.3",
+  "version": "0.40.4",
   "description": "Windows 上给 agent 一个真正的 Git Bash 命令工具:私有 Git Bash 执行器实例(官方 PowerShell 执行器原样保留),统一 MSYS 盘根路径方言,官方 pwsh 工具默认隐藏可开关,物化四个内置预设的 Git Bash 变体,侧栏终端接管可开关。· Give agents a real Git Bash tool on Windows: a private Git Bash executor instance (the official PowerShell executor stays untouched), a unified MSYS drive-root path dialect, an opt-in official pwsh tool, and four Git Bash preset variants.",
   "type": "module",
   "repository": {

package/src/toolchain.js

@@ -213,18 +213,30 @@ export function parseExportJson(text, tools) {
   return found
 }
 
+/**
+ * The extensions a PATH entry must carry to BE the command. Anything else in a
+ * PATH directory — a man page, a README, a directory — merely shares the stem
+ * and must never resolve. An entry with NO extension still does: Git for
+ * Windows ships its own executables that way (`/usr/bin/make`).
+ */
+const EXEC_EXTS = new Set(['.exe', '.cmd', '.bat', '.com'])
+
 /**
  * Which catalog commands the machine already has, and WHERE they came from.
  * One `readdir` per PATH directory (not one `exists` per tool × directory ×
  * extension), and every unreadable directory is skipped rather than fatal.
  * First PATH hit wins, which is the same precedence the shell itself applies.
+ * Only EXECUTABLE entries resolve (see EXEC_EXTS): a man page (`just.1`) or a
+ * document (`jq.md`) shares the stem without being the command, and issue #31
+ * measured a man page winning the first-hit race over the `just.exe` beside it.
  * @param {{pathDirs: () => string[], readdir: (dir: string) => string[]}} io
  * @param {Array} tools - catalog entries to look for.
  * @returns {Map<string, string>} cmd → the first resolving full path.
  */
 export function scanCommands(io, tools) {
   const list = Array.isArray(tools) ? tools : TOOLCHAIN
-  // "make.exe" / "make.cmd" / "make" all resolve the command `make`.
+  // "make.exe" / "make.cmd" / "make" all resolve the command `make`; "make.1"
+  // (the man page) and "make.txt" do not — see EXEC_EXTS.
   const wanted = new Map(list.map((tool) => [String(tool.cmd).toLowerCase(), tool.cmd]))
   const found = new Map()
   let dirs
@@ -236,7 +248,12 @@ export function scanCommands(io, tools) {
     if (!Array.isArray(entries)) continue
     for (const entry of entries) {
       if (typeof entry !== 'string') continue
-      const base = entry.replace(/\.[^./\\]+$/, '').toLowerCase()
+      // The LAST extension decides, exactly as before — but it now has to be
+      // an executable one, so a man page/doc/directory is skipped instead of
+      // resolving to a command it merely shares a stem with.
+      const suffix = /(\.[^./\\]+)$/.exec(entry)
+      if (suffix !== null && !EXEC_EXTS.has(suffix[1].toLowerCase())) continue
+      const base = (suffix === null ? entry : entry.slice(0, suffix.index)).toLowerCase()
       const cmd = wanted.get(base)
       if (cmd !== undefined && !found.has(cmd)) {
         found.set(cmd, dir.replace(/[\\/]+$/, '') + '\\' + entry)