dsh-git-bash 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## 0.1.1 (2026-09-13)
+
+- Documentation only: the English and Chinese READMEs now link to each other
+  from their first line, so the language switch is discoverable.
+- Added this changelog (the package had none).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VviLliAm-qwq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# dsh-git-bash
+
+**English** · [中文](README.zh.md)
+
+Make a **Git for Windows** installation resolvable as `bash` inside the dsh
+host process, so the official bash shell stack can run on Windows.
+
+## The problem it solves
+
+dsh ships two shell stacks and gates them by platform: on Windows
+`@deepseek-ai/dsh-base` mounts `pwsh-sandbox` + `tool-pwsh` and disables
+`bash-sandbox` + `tool-bash`. The bash stack is not disabled for lack of
+support — it is disabled because it spawns the **bare name** `bash`:
+
+- the executor runs `["bash", "-c", command]`, and
+- the sandbox layer builds its own `["bash", "-c", command]` for the confined
+  runner.
+
+Neither place accepts a configurable executable path. A stock Windows PATH does
+not resolve `bash`: Git for Windows puts `cmd\git.exe` on PATH, but not
+`bin\bash.exe`. So the only seam that reaches both spawn sites is the process
+PATH — which is what this plugin edits.
+
+## What it does
+
+On `win32` only, during `apply()`:
+
+1. detects a Git installation (`%ProgramFiles%\Git\bin`,
+   `%ProgramFiles(x86)%\Git\bin`, `%LOCALAPPDATA%\Programs\Git\bin`, then
+   `C:\Program Files\Git\bin`) and checks that it really holds `bash.exe`;
+2. prepends that directory to `process.env.PATH` — but only when `bash` is not
+   resolvable already, and never reordering an existing entry;
+3. records what it decided in `~/.dsh-tui/dsh-git-bash.log` (bounded: past
+   128 KiB the older half is dropped, and `node --test` runs never write it);
+4. restores the previous PATH on unload — but only while the value is still its
+   own, so a PATH someone else edited afterwards is left alone.
+
+On other platforms it logs `skipped: not win32` and does nothing.
+
+It never throws: a missing installation, an unreadable log or a hostile config
+leaves the host exactly as it was.
+
+## Enabling the bash stack: the bundle patch does both halves
+
+A plugin cannot register a tool; it can only make the environment the official
+tools need. So this package's own bundle patch does both halves, and installing
+the package IS the installation:
+
+```yaml
+- insert:
+    - id: dsh-git-bash
+      name: 'dsh-git-bash'
+- id: bash-sandbox      # enabled (config restated: a patch replaces it whole)
+  disabled: false
+- id: pwsh-sandbox      # disabled
+  disabled: true
+- id: tool-bash         # enabled -> the `bash` tool appears
+  disabled: false
+- id: tool-pwsh         # disabled
+  disabled: true
+```
+
+Both stacks provide `ctx.shell`, so exactly one may mount: this is a swap, not
+an addition. `pwsh` remains reachable from bash (`powershell -Command '…'`) if
+you need it.
+
+**Reverting is removing the bundle** (`dsh plugin --profile <p> remove
+dsh-git-bash`): every override above disappears with it and the platform gating
+in `@deepseek-ai/dsh-base` applies again.
+
+> **Do not put this swap in a LIVE profile's own `cordis.patch.yml` instead.**
+> That file is watched by `patchReload: live`, so editing it re-configures
+> running sessions immediately — before this plugin's row is loaded, which
+> leaves them with a shell stack that cannot spawn `bash`. A bundle patch is
+> read at boot, which is the order this needs.
+
+## Install
+
+```sh
+dsh plugin --profile dsh-tui add file:/absolute/path/to/dsh-git-bash
+```
+
+Then restart the TUI (`/restart`) and confirm the composition before trusting
+it:
+
+```sh
+dsh --profile dsh-tui --dump-config    # composes the tree without starting the UI
+```
+
+## Configuration
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `gitBinDir` | string | `""` | Directory holding `bash.exe`. Empty = auto-detect. When set, it is the only candidate — a typo is reported instead of being papered over. |
+
+Set it on the plugin's row when detection cannot find your installation:
+
+```yaml
+- id: dsh-git-bash
+  config:
+    gitBinDir: 'D:\PortableGit\bin'
+```
+
+## Known limitations
+
+- **This enables a platform-gated stack.** dsh disables the bash rows on Windows
+  by design; this plugin removes the reason it cannot work, but that composition
+  is not one upstream tests. Keep the `.bak` of your `cordis.patch.yml`: rolling
+  back is deleting the four override lines above.
+- **Sandbox modes are the untested part.** With `danger-full-access` the
+  executor skips the confinement wrapper entirely, which is what has been
+  exercised here. Under `workspace-write` the sandbox layer wraps the command in
+  the Windows ACL restricted-token runner — a path built for POSIX. Treat
+  confined modes as unverified.
+- A plugin cannot add tools; it can only make the environment the official tools
+  need. If the bash rows are not enabled, this plugin changes nothing visible.
+- The PATH edit is process-wide inside the host process, which is exactly the
+  point: every consumer resolving `bash` (the agent's own commands included)
+  benefits.
+
+## Development
+
+```sh
+pnpm install
+pnpm test              # node:test unit tests (pure discovery/PATH rules)
+pnpm check:encoding    # no UTF-8 BOM / damaged sequences / tab indentation
+pnpm verify            # both, in order
+```
+
+The tests are pure and injectable: `resolveBinDir` takes its environment and its
+existence probe as arguments, so the discovery rules are pinned without touching
+the machine. The win32 cases exercise the real installation when one is present
+and skip otherwise.
+
+## Diagnostics
+
+`~/.dsh-tui/dsh-git-bash.log` holds one line per decision: the detected
+directory, `already resolvable`, `PATH left unchanged`, the unload restore (or
+`PATH left alone: it changed after this plugin`). Every message is also sent to
+the host logger.
+
+## Publishing
+
+- **Repository**: <https://github.com/VviLliAm-qwq/dsh-git-bash> (public)
+
+## License
+
+MIT.

package/README.zh.md

@@ -0,0 +1,107 @@
+# dsh-git-bash
+
+**中文** · [English](README.md)
+
+让 **Git for Windows** 的 `bash` 在 dsh 宿主进程里能被解析到，从而让官方 bash shell 工具栈在 Windows 上跑起来。
+
+## 它解决什么问题
+
+dsh 带两套 shell 栈，并按平台互相门控：Windows 下 `@deepseek-ai/dsh-base` 挂 `pwsh-sandbox` + `tool-pwsh`，同时把 `bash-sandbox` + `tool-bash` 关掉。关掉 bash 栈**不是因为不支持**，而是因为它 spawn 的是**裸名字 `bash`**：
+
+- 执行器跑的是 `["bash", "-c", command]`；
+- 沙箱层为受限运行器**自己又拼了一份** `["bash", "-c", command]`。
+
+这两处都不接受"可配置的可执行文件路径"。而 Windows 默认 PATH 里没有 `bash`：Git for Windows 只把 `cmd\git.exe` 放进 PATH，不含 `bin\bash.exe`。所以能同时覆盖这两个 spawn 点的唯一接缝就是**进程 PATH**——本插件改的就是它。
+
+## 它做什么
+
+只在 `win32` 上，在 `apply()` 期间：
+
+1. 探测 Git 安装位置（`%ProgramFiles%\Git\bin`、`%ProgramFiles(x86)%\Git\bin`、`%LOCALAPPDATA%\Programs\Git\bin`，最后 `C:\Program Files\Git\bin`），并确认里面**真的有** `bash.exe`；
+2. 把该目录**前置**进 `process.env.PATH`——仅在 `bash` 尚不可解析时动手，且从不重排已有条目；
+3. 把决定写进 `~/.dsh-tui/dsh-git-bash.log`（有上限：超过 128 KiB 丢旧的一半；`node --test` 下不写文件）；
+4. 卸载时还原原 PATH——但只在**该值仍是自己设的那个**时才还原，别人之后改过的 PATH 一律不动。
+
+其他平台只记一行 `skipped: not win32`，什么都不做。
+
+它永不抛异常：没装 Git、日志写不了、配置是垃圾——宿主都保持原样。
+
+## 启用 bash 栈：插件自带的 bundle patch 两件一起做
+
+插件本身不能注册工具，只能把官方工具需要的环境准备好。所以**本包自己的 bundle patch 把两件事一起做了**——装上这个包就是全部安装步骤：
+
+```yaml
+- insert:
+    - id: dsh-git-bash
+      name: 'dsh-git-bash'
+- id: bash-sandbox      # 开（config 原样回填：patch 会整体替换它）
+  disabled: false
+- id: pwsh-sandbox      # 关
+  disabled: true
+- id: tool-bash         # 开 → 出现 `bash` 工具
+  disabled: false
+- id: tool-pwsh         # 关
+  disabled: true
+```
+
+两套栈都提供 `ctx.shell`，所以只能挂一个：这是**换栈**不是叠加。需要 PowerShell 时仍可从 bash 里调（`powershell -Command '…'`）。
+
+**回滚 = 卸载这个包**（`dsh plugin --profile <p> remove dsh-git-bash`）：上面所有覆盖随包一起消失，`@deepseek-ai/dsh-base` 的平台门控重新生效。
+
+> **不要把这段换栈放进"活着的" profile 自己的 `cordis.patch.yml`。** 那个文件被 `patchReload: live` 监视，一改就**立刻重配运行中的会话**——而那时本插件的行还没加载，于是那些会话的 shell 栈连 `bash` 都 spawn 不到。bundle patch 是启动时读取的，顺序才是对的。
+
+## 安装
+
+```sh
+dsh plugin --profile dsh-tui add file:/到本仓库的绝对路径/dsh-git-bash
+```
+
+之后在 TUI 内 `/restart`，并在信任它之前先验证组合：
+
+```sh
+dsh --profile dsh-tui --dump-config    # 只组合插件树，不启动界面
+```
+
+## 配置
+
+| 键 | 类型 | 默认 | 含义 |
+| --- | --- | --- | --- |
+| `gitBinDir` | string | `""` | 存放 `bash.exe` 的目录。留空 = 自动探测。一旦设置它就是**唯一**候选——写错会如实报告，而不是被"兜住"。 |
+
+探测不到时可以在这行上指定：
+
+```yaml
+- id: dsh-git-bash
+  config:
+    gitBinDir: 'D:\PortableGit\bin'
+```
+
+## 已知限制
+
+- **这等于启用了官方按平台关掉的栈。** dsh 有意在 Windows 上禁用 bash 行；本插件去掉了它跑不起来的原因，但这条组合并非上游测试覆盖的路径。请保留 `cordis.patch.yml` 的 `.bak`：回滚就是删掉上面那四行覆盖。
+- **沙箱模式是未验证的部分。** `danger-full-access` 下执行器完全跳过受限包装，这是实测过的路径；`workspace-write` 下沙箱层会把命令交给 Windows ACL 受限令牌运行器——那条路是为 POSIX 写的。请把受限模式当作未经验证。
+- 插件不能新增工具，只能把官方工具需要的环境准备好。若没有启用 bash 行，本插件不会带来任何可见变化。
+- 它改的是宿主进程内**进程级**的 PATH，这正是目的：所有解析 `bash` 的消费者（包括代理自己的命令）都受益。
+
+## 开发与验证
+
+```sh
+pnpm install
+pnpm test              # node:test 单测（纯探测 / PATH 规则）
+pnpm check:encoding    # 无 UTF-8 BOM / 编码损坏 / tab 缩进
+pnpm verify            # 以上两项依次执行
+```
+
+测试全是纯函数且可注入：`resolveBinDir` 的环境与"存在性探针"都从参数传入，所以探测规则能在不碰本机的前提下钉死。win32 的用例在有真实安装时跑真机、没有则跳过。
+
+## 诊断
+
+`~/.dsh-tui/dsh-git-bash.log` 每个决定一行：探测到的目录、`already resolvable`、`PATH left unchanged`、卸载时的还原（或 `PATH left alone: it changed after this plugin`）。每条消息同时送宿主 logger。
+
+## 发布
+
+- **仓库**：<https://github.com/VviLliAm-qwq/dsh-git-bash>（公开）
+
+## 许可
+
+MIT。

package/cordis.patch.yml

@@ -0,0 +1,47 @@
+# Your patch layer for this dsh profile, applied after every bundle layer:
+# a top-level YAML array of loader patch entries (id-targeted config
+# overrides, disables, and insert lists; `!!js` expressions allowed).
+#
+# dsh-git-bash does two things, and the second one is why this patch is not
+# just an insert:
+#
+#   1. inserts the dsh-git-bash row, which prepends a Git for Windows `bin`
+#      directory to the host process PATH so the bare name `bash` resolves;
+#   2. swaps the two platform-gated shell stacks. `@deepseek-ai/dsh-base`
+#      disables the bash rows on win32 (`disabled: !!js process.platform ===
+#      'win32'`) because their executor and sandbox layer both spawn `bash`.
+#      Both stacks provide `ctx.shell`, so exactly one may mount: this is a
+#      swap, not an addition. PowerShell stays reachable from bash
+#      (`powershell -Command '…'`).
+#
+# Revert by removing the bundle (`dsh plugin --profile <p> remove dsh-git-bash`):
+# every override below disappears with it. `bash-sandbox`'s config is restated
+# because a patch replaces the row's whole config object.
+#
+# The row is inserted last, after the stack rows it enables. That order is
+# harmless: nothing spawns `bash` while the tree loads, and this plugin has
+# already fixed PATH by the time any tool call runs. Keep a LIVE profile's own
+# `cordis.patch.yml` out of this swap — that file is watched by
+# `patchReload: live`, so editing it swaps the stack of running sessions
+# instantly, before this row is loaded.
+- insert:
+    - id: dsh-git-bash
+      name: 'dsh-git-bash'
+
+- id: bash-sandbox
+  name: '@deepseek-ai/dsh-bash-sandbox'
+  disabled: false
+  config:
+    timeoutMs: 60000
+
+- id: pwsh-sandbox
+  name: '@deepseek-ai/dsh-pwsh-sandbox'
+  disabled: true
+
+- id: tool-bash
+  name: '@deepseek-ai/dsh-tool-bash'
+  disabled: false
+
+- id: tool-pwsh
+  name: '@deepseek-ai/dsh-tool-pwsh'
+  disabled: true

package/lib/git-path.js

@@ -0,0 +1,129 @@
+/**
+ * Pure helpers for making a Git for Windows installation resolvable as `bash`.
+ *
+ * WHY THIS EXISTS
+ *
+ * The official bash shell stack (`@deepseek-ai/dsh-bash-sandbox` +
+ * `@deepseek-ai/dsh-tool-bash`) spawns the *bare name* `bash` in two places:
+ * the local executor's `run()`/`start()` argv (`["bash", "-c", command]`) and,
+ * crucially, the sandbox layer's `confine()`, which builds its own
+ * `["bash", "-c", command]` for the confined runner. Neither goes through a
+ * configurable executable path, so the only place a Windows installation can
+ * be injected is the process PATH that resolves that name.
+ *
+ * Everything here is pure and injectable: no `process.env` reads, no
+ * filesystem calls, so the discovery rules are unit-testable at fixed inputs.
+ *
+ * @module dsh-git-bash/git-path
+ */
+
+import { statSync } from 'node:fs'
+import { delimiter as pathDelimiter, join } from 'node:path'
+
+/** Executable the shell stack ultimately spawns. */
+export const BASH_EXECUTABLE = 'bash.exe'
+
+/**
+ * Installation roots probed when the config names none, most common first.
+ *
+ * `ProgramFiles(x86)` is read through a lookup function because its name is not
+ * a valid identifier for dot access on some engines, and an unset variable must
+ * simply drop the candidate rather than produce a path relative to the cwd.
+ *
+ * @param env - environment to read.
+ * @returns Candidate `bin` directories, de-duplicated, in probe order.
+ */
+export function candidateBinDirs(env = {}) {
+  const read = name => {
+    const value = env[name]
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+  }
+  const roots = [
+    read('ProgramFiles'),
+    read('ProgramW6432'),
+    read('ProgramFiles(x86)'),
+    read('LOCALAPPDATA') === undefined ? undefined : join(read('LOCALAPPDATA'), 'Programs'),
+    // The default installer target, kept last so an env-driven hit wins.
+    'C:\\Program Files',
+  ]
+  const out = []
+  for (const root of roots) {
+    if (root === undefined) continue
+    const candidate = join(root, 'Git', 'bin')
+    if (!out.some(existing => existing.toLowerCase() === candidate.toLowerCase())) out.push(candidate)
+  }
+  return out
+}
+
+/** Whether `directory` holds the executable as a regular file. */
+function defaultHasBash(directory) {
+  try {
+    return statSync(join(directory, BASH_EXECUTABLE)).isFile()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The directory that makes `bash` resolvable, or `undefined`.
+ *
+ * @param options.configured - explicit `gitBinDir` from the plugin config; when
+ *   set it is the ONLY candidate (an explicit answer must not be second-guessed).
+ * @param options.env - environment used to build the candidate list.
+ * @param options.hasBash - injectable existence probe (defaults to `fs`).
+ * @returns The first candidate containing the executable, else `undefined`.
+ */
+export function resolveBinDir(options = {}) {
+  const hasBash = options.hasBash ?? defaultHasBash
+  const configured = options.configured
+  if (typeof configured === 'string' && configured.trim() !== '') {
+    const directory = configured.trim()
+    return hasBash(directory) ? directory : undefined
+  }
+  for (const candidate of candidateBinDirs(options.env)) {
+    if (hasBash(candidate)) return candidate
+  }
+  return undefined
+}
+
+/**
+ * Whether one PATH segment list already contains `directory`.
+ *
+ * Windows path comparison is case-insensitive; trailing separators and empty
+ * segments (`;;`) are ignored so a hand-edited PATH cannot defeat the check.
+ */
+export function pathContains(pathValue, directory, options = {}) {
+  const separator = options.delimiter ?? pathDelimiter
+  const fold = options.caseInsensitive ?? process.platform === 'win32'
+  const normalize = value => {
+    const trimmed = value.trim().replace(/[\\/]+$/, '')
+    return fold ? trimmed.toLowerCase() : trimmed
+  }
+  const wanted = normalize(directory)
+  if (wanted === '') return true
+  return String(pathValue ?? '')
+    .split(separator)
+    .some(segment => normalize(segment) === wanted)
+}
+
+/**
+ * Prepend `directory` to a PATH value.
+ *
+ * Returns the input unchanged when the directory is already present anywhere in
+ * the list: re-ordering a PATH the user curated is a side effect this plugin
+ * has no business taking, and an unchanged value also lets the caller detect
+ * "nothing to do" without a second probe.
+ *
+ * @param pathValue - current PATH (may be empty or undefined).
+ * @param directory - directory to prepend.
+ * @param options - `delimiter` and `caseInsensitive` overrides.
+ * @returns The new PATH value, or the original when nothing had to change.
+ */
+export function prependPath(pathValue, directory, options = {}) {
+  const separator = options.delimiter ?? pathDelimiter
+  const current = typeof pathValue === 'string' ? pathValue : ''
+  if (directory === undefined || directory === null || String(directory).trim() === '') return current
+  if (pathContains(current, directory, options)) return current
+  const head = String(directory).replace(/[\\/]+$/, '')
+  return current === '' ? head : `${head}${separator}${current}`
+}

package/lib/index.js

@@ -0,0 +1,13 @@
+/**
+ * dsh-git-bash — Cordis entry.
+ *
+ * This module re-exports exactly the three symbols a Cordis plugin entry is
+ * read for (`name`, `Config`, `apply`) and nothing else: an entry module
+ * carrying extra symbols changes how the loader wraps the activation, which is
+ * the failure mode that costs an afternoon elsewhere in this ecosystem
+ * (see `docs/DSH-PLUGIN-SOP.md` §2.1). Implementation lives in `./plugin.js`.
+ *
+ * @module dsh-git-bash
+ */
+
+export { Config, apply, name } from './plugin.js'

package/lib/plugin.js

@@ -0,0 +1,158 @@
+/**
+ * dsh-git-bash — make a Git for Windows installation resolvable as `bash`.
+ *
+ * WHY A PLUGIN AND NOT A CONFIG FLAG
+ *
+ * The official bash shell stack is platform-gated off on Windows
+ * (`@deepseek-ai/dsh-base` mounts `bash-sandbox` and `tool-bash` with
+ * `disabled: !!js process.platform === 'win32'`), because it spawns the bare
+ * name `bash` — which a stock Windows PATH does not resolve, since Git for
+ * Windows only puts `cmd\git.exe` on PATH, not `bin\bash.exe`.
+ *
+ * Neither the executor's `run()`/`start()` argv nor the sandbox layer's
+ * `confine()` accepts an executable path, so the one seam that reaches both is
+ * the process PATH. This plugin prepends the detected `Git\bin` directory to
+ * `process.env.PATH` of the host process, which is what the child-process
+ * launcher resolves `bash` against. Enabling the bash rows in the profile is
+ * then a separate, explicit composition decision (see README).
+ *
+ * The plugin is deliberately defensive: it never throws, never fails the host
+ * startup, logs what it decided, and restores the PATH it changed on unload
+ * only while it still owns that change.
+ *
+ * @module dsh-git-bash
+ */
+
+import { appendFileSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import z from '@deepseek-ai/schemastery'
+import { BASH_EXECUTABLE, prependPath, resolveBinDir } from './git-path.js'
+
+export const name = 'dsh-git-bash'
+
+/** Every key has a default: a missing composition entry changes nothing. */
+export const Config = z.object({
+  /**
+   * Directory holding `bash.exe`. Empty means "detect it" — an explicit value
+   * is used as given (and reported when it holds no executable), so a machine
+   * with a non-standard install is a one-line config away.
+   */
+  gitBinDir: z.string().default(''),
+})
+
+/** Boot defaults mirroring the schema. */
+const DEFAULTS = Object.freeze({ gitBinDir: '' })
+
+const DIAG_LOG = join(homedir(), '.dsh-tui', 'dsh-git-bash.log')
+/** Above this size the log is trimmed to its newest half. */
+const MAX_LOG_BYTES = 128 * 1024
+/** Inside `node --test` nothing may touch a user's log file. */
+const FILE_LOG_ENABLED = typeof process.env?.NODE_TEST_CONTEXT !== 'string'
+
+/** Coerce an untrusted config object into the known key with a valid type. */
+export function sanitizeConfig(config) {
+  const out = { ...DEFAULTS }
+  if (config !== null && typeof config === 'object' && typeof config.gitBinDir === 'string') {
+    out.gitBinDir = config.gitBinDir
+  }
+  return out
+}
+
+/** Append one bounded diagnostic line. */
+function appendLogLine(path, line) {
+  try {
+    if (statSync(path).size > MAX_LOG_BYTES) {
+      writeFileSync(path, readFileSync(path, 'utf8').slice(-Math.floor(MAX_LOG_BYTES / 2)))
+    }
+  } catch {
+    // Missing or unreadable file: the append below recreates it.
+  }
+  appendFileSync(path, line)
+}
+
+/** Quiet logger: the host logger always, plus the plugin's own bounded file. */
+function createLogger(ctx) {
+  const write = (level, message) => {
+    try {
+      ctx.logger?.[level]?.(`dsh-git-bash: ${message}`)
+    } catch {
+      // Observability only; never let logging break the plugin.
+    }
+    if (!FILE_LOG_ENABLED) return
+    try {
+      appendLogLine(DIAG_LOG, `${new Date().toISOString()} ${level} ${message}\n`)
+    } catch {
+      // An unwritable log path is not worth surfacing.
+    }
+  }
+  return {
+    info: message => write('info', message),
+    warn: message => write('warn', message),
+  }
+}
+
+/**
+ * Wire the plugin.
+ *
+ * @param ctx - Cordis context of this activation.
+ * @param config - composition-entry config; `gitBinDir` defaults to "".
+ */
+export function apply(ctx, config) {
+  const log = createLogger(ctx)
+  try {
+    log.info(`apply started pid=${process.pid} node=${process.version} file=${fileURLToPath(import.meta.url)}`)
+  } catch {
+    // Logging must never be the reason a plugin fails to load.
+  }
+
+  try {
+    const resolved = sanitizeConfig(config)
+    if (process.platform !== 'win32') {
+      // POSIX installs resolve `bash` from the system PATH; prepending a
+      // Windows-style Git directory there would be wrong.
+      log.info('skipped: not win32')
+      return
+    }
+
+    const directory = resolveBinDir({ configured: resolved.gitBinDir, env: process.env })
+    if (directory === undefined) {
+      log.warn(
+        resolved.gitBinDir === ''
+          ? 'no Git for Windows installation found; PATH left unchanged (set gitBinDir to point at one)'
+          : `gitBinDir holds no ${BASH_EXECUTABLE}: ${resolved.gitBinDir}; PATH left unchanged`,
+      )
+      return
+    }
+
+    const before = typeof process.env.PATH === 'string' ? process.env.PATH : ''
+    const after = prependPath(before, directory, { delimiter })
+    if (after === before) {
+      log.info(`already resolvable, PATH left unchanged: ${directory}`)
+      return
+    }
+
+    process.env.PATH = after
+    log.info(`PATH prepended with ${directory}`)
+
+    // Restore only while the value is still ours: another plugin (or the user)
+    // may have edited PATH afterwards, and their change must win.
+    ctx.effect(function* pathEffect() {
+      yield () => {
+        try {
+          if (process.env.PATH === after) {
+            process.env.PATH = before
+            log.info('PATH restored')
+          } else {
+            log.info('PATH left alone: it changed after this plugin')
+          }
+        } catch {
+          // Best-effort teardown.
+        }
+      }
+    }, 'dsh-git-bash PATH')
+  } catch (error) {
+    log.warn(`apply failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "dsh-git-bash",
+  "version": "0.1.1",
+  "description": "Make a Git for Windows installation resolvable as `bash` inside the dsh host process, so the official bash shell stack (dsh-bash-sandbox + dsh-tool-bash) can run on Windows",
+  "packageManager": "pnpm@11.22.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VviLliAm-qwq/dsh-git-bash.git"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "scripts": {
+    "check:encoding": "node scripts/check-encoding.mjs",
+    "test": "node --test",
+    "verify": "npm run check:encoding && npm run test"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}