dsh-console-utf8 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## 0.1.1 (2026-09-13)
+
+- Documentation only, no code change. The "host switch" limitation now records what a restarted dsh-tui session measured: the Windows launcher starts the host without a console of its own, so every `chcp.com` child gets a fresh console, the host half logs its warning, and the `BASH_ENV` hook carries the whole fix. The warning is expected on every start, not a fault.
+
+## 0.1.0 (2026-09-13)
+
+- Initial release.
+- Host console: switches the console the dsh host was started in to code page 65001 via `chcp.com`, reads the page back and logs what was observed.
+- Shell hook: writes a `BASH_ENV` hook under the dsh state directory so every non-interactive `bash -c` re-applies the code page inside its own process group, and restores `BASH_ENV` on unload only while it is still the value this plugin set.
+- Bounded lifecycle log at `~/.dsh-tui/dsh-console-utf8.log` (newest half kept past 128 KiB; nothing is written under `node --test`).
+- Config: `enabled`, `codePage`, `setHostConsole`, `shellHook`, `shimPath` — every key defaulted, so an empty composition entry is a safe no-op.
+- Windows only: every other platform takes the `not win32` path and changes nothing.

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,92 @@
+# dsh-console-utf8
+
+**English** · [中文](README.zh.md)
+
+Keeps the Windows console on code page **65001 (UTF-8)** for the dsh host and for the commands the bash tool runs, so output from Windows-native child processes stops arriving as mojibake.
+
+## The problem
+
+The dsh subprocess layer decodes every child's stdout as UTF-8. Windows-native tools that a bash command invokes — `powershell.exe`, `cmd.exe`, `git.exe`, and `chcp.com` itself — write their text in the console's OEM code page instead (936/GBK on a Chinese system, 932 on Japanese, 437 on US-English). The bytes are then read as UTF-8 and every non-ASCII character in that output is destroyed:
+
+| Console state | `chcp` output |
+|---|---|
+| default (936) | the localised line, its Chinese replaced by U+FFFD runs |
+| after `chcp 65001` | `Active code page: 65001` |
+
+It is not a decoding bug that can be fixed by decoding harder: the console has to speak the same encoding the decoder assumes. That is all this plugin does.
+
+## What it does
+
+- **Host console** (`setHostConsole`, default on): switches the console the dsh host was started in to the configured code page using `chcp.com`, then reads the page back and logs what the console actually reports — a sandbox or a foreign locale that accepts the call and keeps the old page is reported instead of being claimed as a success.
+- **Shell hook** (`shellHook`, default on): maintains `~/.dsh-tui/console-utf8.sh` and points `BASH_ENV` at it, so every non-interactive `bash -c` re-applies the code page inside its own process group. This covers the case where the shell executor spawns a command in a fresh console, which would otherwise start back at the system default.
+- **Diagnostics**: a bounded lifecycle log at `~/.dsh-tui/dsh-console-utf8.log` records the resolved config, the observed code page before and after, and the hook decision. It is trimmed to its newest half once it passes 128 KiB, and nothing is written while `node --test` is running.
+
+Exactly two files are written, both under the dsh state directory: the hook and the log. Commands are never rewritten, PATH is never touched, the shell stack is never patched, and no other file is read.
+
+## Install
+
+```sh
+dsh plugin --profile <profile> add dsh-console-utf8
+```
+
+Restart the TUI afterwards (`/restart`) — the plugin acts at mount time.
+
+Manual installation: copy the package into `~/.dsh/profiles/<profile>/node_modules/dsh-console-utf8/` and append `"dsh-console-utf8"` to `dsh.profile.bundles` in that profile's `package.json`. The package declares `dsh.bundle.patch`, so it mounts itself at boot.
+
+## Compatibility
+
+| Item | Value |
+|---|---|
+| Platform | Windows only (`win32`); any other platform takes the `not win32` path and changes nothing |
+| Host | dsh-tui with manifest v0.15 / `v1alpha1` host facet |
+| Node | `^22.19 || >=24`, pure ESM |
+| Contributes | nothing — no command, no permission, no contract, no seam registration |
+| Shell stack | benefits any stack whose commands go through a Windows console; the `BASH_ENV` hook only applies to **bash** (`sh`/`dash` are unaffected) |
+
+## Configuration
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `enabled` | boolean | `true` | Master switch. `false` mounts the plugin and does nothing. |
+| `codePage` | number | `65001` | Code page to enforce. Override only deliberately. |
+| `setHostConsole` | boolean | `true` | Switch the host process's console. |
+| `shellHook` | boolean | `true` | Maintain the `BASH_ENV` hook. |
+| `shimPath` | string | `''` | Hook path. Empty means `~/.dsh-tui/console-utf8.sh`. |
+
+## Known limitations
+
+- **Root cause is upstream.** This plugin makes the console match the decoder's assumption; it does not change how the subprocess layer decodes output. A host that decodes with a fallback would not need it.
+- **`BASH_ENV` is shared.** If another tool already set `BASH_ENV` to a different path, the plugin stands down and logs why rather than clobbering it; point `shimPath` at that path to adopt it, or disable `shellHook`.
+- **`bash` only.** The hook is not read by `sh`, `dash`, `zsh` or PowerShell, and a command that resets the code page itself (`chcp 936`) wins until the next command.
+- **The host switch needs a console the host owns.** When the host starts without one — a headless probe, and the Windows dsh-tui launcher, which hands the host no console handle — every `chcp.com` child gets a console of its own, so the switch cannot take effect. The plugin logs a warning instead of claiming success, and the shell hook then carries the whole fix. Measured twice: in the 0.1.0 integration probe and in a real restarted dsh-tui session. Expect the `host console code page … after asking for …` warning on every start; it is not a fault.
+- **Per console, not per system.** A newly created console starts at the system default again; use the system-wide UTF-8 setting if that is what you want.
+- **The hook costs one `chcp.com` per bash invocation** (a few milliseconds), silenced so it never reaches the tool output.
+- **Nothing already copied is repaired.** Text that is mojibake in the clipboard or in a file stays that way.
+- Verified on Windows 11 with a CP936 system locale; other code pages are expected to behave the same but were not measured.
+
+## Development
+
+```sh
+pnpm install
+npm run verify          # encoding sweep + unit tests + manifest + pack layout
+node --test             # unit tests only
+npm run check:encoding  # BOM / damaged-sequence sweep
+npm run validate:manifest
+npm run pack:verify     # published file list, and that no shipped module is missing
+```
+
+The unit tests never touch the real console or the user's files: the code-page calls, the hook writer and the environment are injected.
+
+## Publishing
+
+Version tags drive the release (`vX.Y.Z`, tag = `package.json` version). The repository ships a GitHub Actions workflow that runs the verification chain and publishes to npm with provenance.
+
+## Publishing
+
+- **Repository**: <https://github.com/VviLliAm-qwq/dsh-console-utf8> (public)
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Built for [dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI).

package/README.zh.md

@@ -0,0 +1,92 @@
+# dsh-console-utf8
+
+[English](README.md) · **中文**
+
+把 **dsh 宿主**和 **bash 工具命令**所用的 Windows 控制台固定在代码页 **65001（UTF-8）**，让 Windows 原生子进程的输出不再变成乱码。
+
+## 问题是什么
+
+dsh 的子进程层统一按 UTF-8 解码每个子进程的 stdout。而 bash 命令里调用的 Windows 原生工具 —— `powershell.exe`、`cmd.exe`、`git.exe`，甚至 `chcp.com` 自己 —— 是用控制台的 OEM 代码页输出的（中文系统 936/GBK，日文 932，美式英文 437）。这些字节被当成 UTF-8 读取后，其中每一个非 ASCII 字符都会被打碎：
+
+| 控制台状态 | `chcp` 的输出 |
+|---|---|
+| 默认（936） | 本地化文案里的中文被替换成一串 U+FFFD |
+| 执行 `chcp 65001` 之后 | `Active code page: 65001` |
+
+这不是「解码再努力一点」能解决的问题：控制台必须说出解码方所假定的那种编码。本插件做的只有这一件事。
+
+## 它做什么
+
+- **宿主控制台**（`setHostConsole`，默认开）：用 `chcp.com` 把 dsh 宿主启动时所在的控制台切换到配置的代码页，然后**回读**实际生效的代码页并写进日志 —— 沙箱或异常区域设置可能出现「调用返回成功但代码页没变」，这种情况会被如实记录，而不是被当成成功。
+- **shell 钩子**（`shellHook`，默认开）：维护 `~/.dsh-tui/console-utf8.sh` 并把 `BASH_ENV` 指向它，使每一次非交互 `bash -c` 都在自己的进程组里重新应用一次代码页。这覆盖了「shell 执行器在新控制台里拉起命令」的情形 —— 那种情况下代码页会退回系统默认值。
+- **可诊断性**：`~/.dsh-tui/dsh-console-utf8.log` 记录解析后的配置、切换前后的代码页以及钩子决策；超过 128 KiB 时裁掉旧的一半；`node --test` 下不写任何日志。
+
+全程只写两个文件，都在 dsh 状态目录下：钩子与日志。不重写命令、不动 PATH、不打补丁到 shell 栈，除这两个文件外不读取任何用户文件。
+
+## 安装
+
+```sh
+dsh plugin --profile <profile> add dsh-console-utf8
+```
+
+之后**重启 TUI**（`/restart`）—— 插件在挂载时动作。
+
+手工安装：把包复制到 `~/.dsh/profiles/<profile>/node_modules/dsh-console-utf8/`，并把 `"dsh-console-utf8"` 追加进该 profile `package.json` 的 `dsh.profile.bundles`。包内声明了 `dsh.bundle.patch`，启动时会自行挂载。
+
+## 兼容性
+
+| 项 | 值 |
+|---|---|
+| 平台 | 仅 Windows（`win32`）；其他平台走 `not win32` 分支，什么都不改 |
+| 宿主 | dsh-tui，manifest v0.15 / `v1alpha1` host facet |
+| Node | `^22.19 || >=24`，纯 ESM |
+| 贡献面 | 无 —— 不注册命令、不申请权限、不声明契约、不使用接缝 |
+| shell 栈 | 任何经由 Windows 控制台执行命令的栈都受益；`BASH_ENV` 钩子只对 **bash** 生效（`sh`/`dash` 不受影响） |
+
+## 配置
+
+| 键 | 类型 | 默认 | 含义 |
+|---|---|---|---|
+| `enabled` | boolean | `true` | 总开关。`false` 时插件照常挂载但什么都不做。 |
+| `codePage` | number | `65001` | 要强制使用的代码页。非必要不建议改。 |
+| `setHostConsole` | boolean | `true` | 切换宿主进程所在的控制台。 |
+| `shellHook` | boolean | `true` | 维护 `BASH_ENV` 钩子。 |
+| `shimPath` | string | `''` | 钩子路径。留空表示 `~/.dsh-tui/console-utf8.sh`。 |
+
+## 已知限制
+
+- **根因在上游**：本插件让控制台迁就解码方的假设，并没有改变子进程层「一律按 UTF-8 解码」这件事。若宿主改为带回退的解码，这个插件就不需要了。
+- **`BASH_ENV` 是共享的**：若已有其他工具把它设成了别的路径，插件会**让位并记录原因**，而不是覆盖它；可以把 `shimPath` 指向那个路径来接管，或关闭 `shellHook`。
+- **只对 bash 生效**：`sh`、`dash`、`zsh`、PowerShell 都不读这个钩子；命令自身重置代码页（如 `chcp 936`）会在下一条命令之前一直生效。
+- **宿主那一半需要宿主真正拥有的控制台**：当宿主启动时就没有自己的控制台 —— 无头探测如此，Windows 上 dsh-tui 的启动器也如此（它不把控制台句柄交给宿主）—— 每个 `chcp.com` 子进程会各自拿到一个新控制台，切换无法生效。此时插件**记录警告**而不谎报成功，改由 shell 钩子独自承担修复。已实测两次：0.1.0 的集成探测，以及真实重启后的 dsh-tui 会话。每次启动都会看到 `host console code page … after asking for …` 这条 warn，**它不是故障**。
+- **按控制台生效，不是全系统**：新建的控制台会回到系统默认值；需要全系统生效请改用系统的 UTF-8 区域设置。
+- **每条 bash 命令多一次 `chcp.com`**（几毫秒），输出已静默，不会混进工具结果。
+- **不修复已经损坏的内容**：剪贴板或文件里已经乱掉的字不会因此恢复。
+- 已在 Windows 11 / CP936 系统区域设置下实测；其他代码页预期行为一致，但未实测。
+
+## 开发
+
+```sh
+pnpm install
+npm run verify          # 编码扫描 + 单测 + manifest + 发布包布局
+node --test             # 只跑单测
+npm run check:encoding  # BOM / 损坏序列扫描
+npm run validate:manifest
+npm run pack:verify     # 发布文件清单，以及「有没有模块漏进清单」
+```
+
+单元测试**不会**碰真实控制台或用户文件：代码页调用、钩子写入器与环境全部由外部注入。
+
+## 发布
+
+版本由 tag 驱动（`vX.Y.Z`，tag 必须等于 `package.json` 的 version）。仓库自带 GitHub Actions 工作流：先跑完整校验链，再带 provenance 发布到 npm。
+
+## 发布
+
+- **仓库**：<https://github.com/VviLliAm-qwq/dsh-console-utf8>（公开）
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。
+
+为 [dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI) 构建。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-console-utf8 bundle patch: mounts the console-code-page plugin.
+#
+# Nothing else is overridden here on purpose. The plugin only touches the
+# console code page and one environment variable; the shell stack itself is
+# left to whoever provides it (the official bash rows, enabled for Windows by
+# a separate PATH-side plugin). Revert by removing this bundle.
+- insert:
+    - id: dsh-console-utf8
+      name: 'dsh-console-utf8'

package/dsh-plugin.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://dsh.community/schemas/dsh-plugin-0.15.json",
+  "manifestVersion": "0.15",
+  "id": "com.dsh-tui-ecosystem.dsh-console-utf8",
+  "name": "dsh-console-utf8",
+  "version": "0.1.1",
+  "facets": {
+    "host": {
+      "entry": "lib/index.js",
+      "apiVersion": "v1alpha1"
+    }
+  },
+  "requires": {
+    "contracts": []
+  },
+  "permissions": [],
+  "subscriptions": [],
+  "contributes": {
+    "commands": []
+  },
+  "source": {
+    "repository": "https://github.com/VviLliAm-qwq/dsh-console-utf8"
+  },
+  "compat": {
+    "hosts": [
+      "dsh-tui"
+    ]
+  },
+  "license": "MIT"
+}

package/lib/console-cp.js

@@ -0,0 +1,103 @@
+/**
+ * dsh-console-utf8 — console code page primitives.
+ *
+ * A Windows console owns its code page, and every console process attached to
+ * it inherits that page. `chcp.com` reports it and rewrites it; because the
+ * value belongs to the CONSOLE rather than to the calling process, a
+ * short-lived child changes what its parent and its siblings observe
+ * (measured 2026-09-13: a piped `chcp.com 65001` child left a later sibling
+ * `powershell.exe` reporting 65001).
+ *
+ * Every function here takes its spawner as an argument so tests can drive
+ * fabricated output: no test may touch the real console.
+ *
+ * @module dsh-console-utf8/console-cp
+ */
+
+/** Turn whatever a spawner returned (string, Buffer or undefined) into text. */
+function asText(value) {
+  if (typeof value === 'string') return value
+  if (value instanceof Uint8Array) return Buffer.from(value).toString('utf8')
+  return ''
+}
+
+/**
+ * Parse the code page number out of `chcp` output.
+ *
+ * The text around the number is localised ("Active code page: 65001",
+ * "活动代码页: 65001") and on a non-UTF-8 console it frequently arrives already
+ * mangled, so only the digits are trusted: the first 2–5 digit run wins.
+ *
+ * @param {unknown} output - Raw `chcp.com` stdout.
+ * @returns {number | undefined} The code page, or undefined when unparseable.
+ */
+export function parseCodePage(output) {
+  const match = /(\d{2,5})/.exec(asText(output))
+  if (match === null) return undefined
+  const value = Number(match[1])
+  return Number.isInteger(value) && value >= 1 && value <= 65535 ? value : undefined
+}
+
+/**
+ * How both calls are made. stdout is PIPED on purpose: the host's screen must
+ * never receive "Active code page: …". Piping stdio does not detach the
+ * console — the child still inherits it and still rewrites its code page.
+ */
+const CALL_OPTIONS = Object.freeze({
+  stdio: ['ignore', 'pipe', 'pipe'],
+  timeout: 5000,
+  windowsHide: true,
+})
+
+/**
+ * Read the code page of the console this process is attached to.
+ *
+ * @param {Function} spawnSync - `node:child_process` spawnSync (or a stand-in).
+ * @returns {number | undefined} The code page, or undefined when there is no
+ *   readable console.
+ */
+export function readConsoleCodePage(spawnSync) {
+  try {
+    const result = spawnSync('chcp.com', [], CALL_OPTIONS)
+    if (result === null || result === undefined || result.status !== 0) return undefined
+    return parseCodePage(result.stdout)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Ask the shared console to switch to `codePage`.
+ *
+ * @param {number} codePage - Target code page (65001 = UTF-8).
+ * @param {Function} spawnSync - `node:child_process` spawnSync (or a stand-in).
+ * @returns {boolean} True when `chcp.com` exited 0.
+ */
+export function switchConsoleCodePage(codePage, spawnSync) {
+  try {
+    const result = spawnSync('chcp.com', [String(codePage)], CALL_OPTIONS)
+    return result !== null && result !== undefined && result.status === 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Bring the console to `codePage` and report the page it is left on.
+ *
+ * The read-back matters: a sandbox, a foreign locale or a denied console can
+ * accept the call and still leave the old page in place, and the log should
+ * say so instead of claiming success.
+ *
+ * @param {number} codePage - Target code page.
+ * @param {Function} spawnSync - `node:child_process` spawnSync (or a stand-in).
+ * @returns {{ before: number | undefined, after: number | undefined,
+ *   switched: boolean }} Observed pages and whether a call was made.
+ */
+export function ensureConsoleCodePage(codePage, spawnSync) {
+  const before = readConsoleCodePage(spawnSync)
+  if (before === codePage) return { before, after: before, switched: false }
+  const accepted = switchConsoleCodePage(codePage, spawnSync)
+  const after = readConsoleCodePage(spawnSync)
+  return { before, after, switched: accepted }
+}

package/lib/index.js

@@ -0,0 +1,13 @@
+/**
+ * dsh-console-utf8 — 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 that
+ * carries extra symbols changes how the loader wraps the activation, which is
+ * the failure mode documented in `docs/DSH-PLUGIN-SOP.md` §2.1. The
+ * implementation lives in `./plugin.js`.
+ *
+ * @module dsh-console-utf8
+ */
+
+export { Config, apply, name } from './plugin.js'

package/lib/log.js

@@ -0,0 +1,64 @@
+/**
+ * dsh-console-utf8 — bounded lifecycle log.
+ *
+ * The host keeps no diagnostics for a bundle-patch plugin, so the plugin
+ * speaks for itself: one file under the dsh state directory, trimmed to its
+ * newest half once it outgrows the cap. Nothing is written under
+ * `node --test`, so a test run never touches a user's log.
+ *
+ * @module dsh-console-utf8/log
+ */
+
+import { appendFileSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+
+/** Above this size the log is trimmed to its newest half. */
+export const MAX_LOG_BYTES = 128 * 1024
+
+/**
+ * Append one line, trimming first when the file has outgrown `maxBytes`.
+ *
+ * @param {string} path - Log file path.
+ * @param {string} line - Complete line, newline included.
+ * @param {number} [maxBytes] - Size cap before trimming.
+ */
+export function appendLogLine(path, line, maxBytes = MAX_LOG_BYTES) {
+  try {
+    if (statSync(path).size > maxBytes) {
+      writeFileSync(path, readFileSync(path, 'utf8').slice(-Math.floor(maxBytes / 2)))
+    }
+  } catch {
+    // Missing or unreadable file: the append below recreates it.
+  }
+  appendFileSync(path, line)
+}
+
+/**
+ * Build the plugin's quiet logger: the host logger always, plus the bounded
+ * file when file logging is allowed.
+ *
+ * @param {object} ctx - Cordis context (its `logger` is optional).
+ * @param {object} options - Logger wiring.
+ * @param {string} options.path - Diagnostic log path.
+ * @param {boolean} options.enabled - False under `node --test`.
+ * @param {string} [options.prefix] - Message prefix.
+ * @returns {{ info: (message: string) => void, warn: (message: string) => void }}
+ */
+export function createLogger(ctx, { path, enabled, prefix = 'dsh-console-utf8' }) {
+  const write = (level, message) => {
+    try {
+      ctx?.logger?.[level]?.(`${prefix}: ${message}`)
+    } catch {
+      // Observability only; never let logging break the plugin.
+    }
+    if (!enabled) return
+    try {
+      appendLogLine(path, `${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),
+  }
+}

package/lib/plugin.js

@@ -0,0 +1,274 @@
+/**
+ * dsh-console-utf8 — keep the Windows console on code page 65001 (UTF-8).
+ *
+ * WHY THIS EXISTS
+ *
+ * The dsh subprocess layer decodes every child's stdout as UTF-8
+ * (`buffer.toString('utf8')`). Windows-native tools that a bash command
+ * invokes — `powershell.exe`, `cmd.exe`, `git.exe`, `chcp.com` itself — write
+ * their text in the console's OEM code page instead (936/GBK on a Chinese
+ * system, 932 on Japanese, 437 on US-English). The bytes are then read as
+ * UTF-8, and every non-ASCII character in that output is destroyed:
+ *
+ *   chcp           →  the localised line, its Chinese replaced by U+FFFD
+ *                     runs — GBK bytes read as UTF-8
+ *   after 65001    →  Active code page: 65001
+ *   中文测试OK      →  中文测试OK             (measured 2026-09-13)
+ *
+ * So the mismatch is not the tools' fault, and it is not fixable by decoding
+ * harder: the console has to speak the same encoding the decoder assumes.
+ * This plugin makes that true, in two places, because the shell executor may
+ * spawn a command either inside the host's console or in a fresh one:
+ *
+ *   1. the host's console is switched to `codePage` through `chcp.com`
+ *      (`setHostConsole`), and
+ *   2. every non-interactive bash gets a `BASH_ENV` hook that repeats the
+ *      switch inside its own process group (`shellHook`).
+ *
+ * WHAT IT DOES NOT DO
+ *
+ * It never rewrites a command, never patches the shell stack, never changes
+ * PATH, and never reads the user's files beyond the one hook it maintains. It
+ * writes exactly two files, both under the dsh state directory: the hook and
+ * this plugin's log.
+ *
+ * @module dsh-console-utf8/plugin
+ */
+
+import { spawnSync } from 'node:child_process'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import z from '@deepseek-ai/schemastery'
+import { ensureConsoleCodePage } from './console-cp.js'
+import { createLogger } from './log.js'
+import { SHIM_FILE_NAME, shimScript, toPosixPath } from './shell-hook.js'
+
+export const name = 'dsh-console-utf8'
+
+/** Every key carries a default: a missing composition entry changes nothing. */
+export const Config = z.object({
+  /** Master switch. False mounts the plugin and does nothing. */
+  enabled: z.boolean().default(true),
+  /** Code page to enforce. 65001 is UTF-8; override only to deliberate. */
+  codePage: z.number().default(65001),
+  /** Switch the host process's console (the one the TUI was started in). */
+  setHostConsole: z.boolean().default(true),
+  /** Maintain the BASH_ENV hook so every bash command re-applies it. */
+  shellHook: z.boolean().default(true),
+  /** Hook path. Empty means `~/.dsh-tui/console-utf8.sh`. */
+  shimPath: z.string().default(''),
+})
+
+/** Boot defaults mirroring the schema. */
+const DEFAULTS = Object.freeze({
+  enabled: true,
+  codePage: 65001,
+  setHostConsole: true,
+  shellHook: true,
+  shimPath: '',
+})
+
+const DIAG_LOG = join(homedir(), '.dsh-tui', 'dsh-console-utf8.log')
+/** Inside `node --test` nothing may touch a user's log or hook file. */
+const FILE_LOG_ENABLED = typeof process.env?.NODE_TEST_CONTEXT !== 'string'
+
+/**
+ * Coerce an untrusted config object into the known keys with valid types.
+ *
+ * @param {unknown} config - Composition-entry config.
+ * @returns {{ enabled: boolean, codePage: number, setHostConsole: boolean,
+ *   shellHook: boolean, shimPath: string }} A complete, safe config.
+ */
+export function sanitizeConfig(config) {
+  const out = { ...DEFAULTS }
+  if (config === null || typeof config !== 'object') return out
+  for (const key of ['enabled', 'setHostConsole', 'shellHook']) {
+    if (typeof config[key] === 'boolean') out[key] = config[key]
+  }
+  if (Number.isInteger(config.codePage) && config.codePage >= 1 && config.codePage <= 65535) {
+    out.codePage = config.codePage
+  }
+  if (typeof config.shimPath === 'string') out.shimPath = config.shimPath
+  return out
+}
+
+/**
+ * Default hook location: the dsh state directory, which is this plugin's only
+ * writable home (`docs/DSH-PLUGIN-SOP.md` §2).
+ *
+ * @param {string} home - User home directory.
+ * @returns {string} Absolute hook path.
+ */
+export function defaultShimPath(home) {
+  return join(home, '.dsh-tui', SHIM_FILE_NAME)
+}
+
+/**
+ * Undo this plugin's `BASH_ENV`, but only while the value is still the one it
+ * set: the user or another plugin may have moved it afterwards, and their
+ * value must win.
+ *
+ * @param {Record<string, string | undefined>} env - Environment to edit.
+ * @param {string} owned - The value this plugin installed.
+ * @returns {'restored' | 'left alone'} What happened.
+ */
+export function restoreBashEnv(env, owned) {
+  if (env.BASH_ENV !== owned) return 'left alone'
+  delete env.BASH_ENV
+  return 'restored'
+}
+
+/**
+ * Write the hook when its content differs, creating the directory if needed.
+ *
+ * A stale hook (an older code page) is the one failure mode that would make
+ * the fix silently do the wrong thing, so the file is compared rather than
+ * assumed.
+ *
+ * @param {string} path - Hook path.
+ * @param {string} content - Desired content.
+ * @returns {boolean} True when the file was (re)written.
+ */
+export function writeShimIfChanged(path, content) {
+  let current
+  try {
+    current = readFileSync(path, 'utf8')
+  } catch {
+    current = undefined
+  }
+  if (current === content) return false
+  mkdirSync(dirname(path), { recursive: true })
+  // No BOM, LF endings: the file is sourced by `sh`, never parsed as JSON.
+  writeFileSync(path, content, 'utf8')
+  return true
+}
+
+/**
+ * Do the work with every side effect injected, so tests can drive it.
+ *
+ * @param {object} deps - Injected environment.
+ * @param {string} deps.platform - `process.platform`.
+ * @param {Record<string, string | undefined>} deps.env - Environment to edit.
+ * @param {string} deps.home - User home directory.
+ * @param {Function} deps.spawnSync - Spawner for `chcp.com`.
+ * @param {(path: string, content: string) => boolean} deps.ensureShim - Hook writer.
+ * @param {{ info: Function, warn: Function }} deps.log - Logger.
+ * @param {object} config - Sanitized config.
+ * @returns {{ skipped: string, console: object | null, shim: object | null }}
+ */
+export function setup(deps, config) {
+  const result = { skipped: '', console: null, shim: null }
+
+  if (!config.enabled) {
+    result.skipped = 'disabled by config'
+    deps.log.info('skipped: disabled by config')
+    return result
+  }
+  if (deps.platform !== 'win32') {
+    // POSIX consoles are UTF-8 already; `chcp.com` does not exist there.
+    result.skipped = 'not win32'
+    deps.log.info('skipped: not win32')
+    return result
+  }
+
+  if (config.setHostConsole) {
+    const { before, after, switched } = ensureConsoleCodePage(config.codePage, deps.spawnSync)
+    result.console = { before, after, switched }
+    if (before === undefined && after === undefined) {
+      // A detached host has no console to read; the shell hook still covers
+      // the commands, so this is a note rather than a failure.
+      deps.log.warn('host console code page unreadable (no attached console?); shell hook still applies')
+    } else if (after === config.codePage) {
+      deps.log.info(`host console code page ${before ?? '?'} -> ${after}`)
+    } else {
+      deps.log.warn(`host console code page is ${after ?? 'unknown'} after asking for ${config.codePage}`)
+    }
+  }
+
+  if (config.shellHook) {
+    const shimPath = config.shimPath === '' ? defaultShimPath(deps.home) : config.shimPath
+    const value = toPosixPath(shimPath)
+    let written = false
+    try {
+      written = deps.ensureShim(shimPath, shimScript(config.codePage))
+    } catch (error) {
+      deps.log.warn(`could not write the shell hook: ${error instanceof Error ? error.message : String(error)}`)
+      result.shim = { path: shimPath, applied: false, reason: 'hook not writable' }
+      return result
+    }
+
+    const existing = typeof deps.env.BASH_ENV === 'string' && deps.env.BASH_ENV !== '' ? deps.env.BASH_ENV : undefined
+    if (existing !== undefined && existing !== value) {
+      // Someone else owns BASH_ENV. Clobbering it would break their hook, so
+      // this plugin stands down and says why; the config can point elsewhere.
+      deps.log.warn(`BASH_ENV is already ${existing}; left untouched (set this plugin's shimPath to adopt it)`)
+      result.shim = { path: shimPath, applied: false, reason: 'BASH_ENV owned by someone else' }
+      return result
+    }
+
+    deps.env.BASH_ENV = value
+    result.shim = {
+      path: shimPath,
+      applied: true,
+      written,
+      previous: undefined,
+      value,
+    }
+    deps.log.info(`BASH_ENV -> ${value} (${written ? 'hook written' : 'hook already current'})`)
+  }
+
+  return result
+}
+
+/**
+ * Wire the plugin.
+ *
+ * @param {object} ctx - Cordis context of this activation.
+ * @param {unknown} config - Composition-entry config.
+ */
+export function apply(ctx, config) {
+  const log = createLogger(ctx, { path: DIAG_LOG, enabled: FILE_LOG_ENABLED })
+
+  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)
+    log.info(`config ${JSON.stringify(resolved)}`)
+
+    const result = setup(
+      {
+        platform: process.platform,
+        env: process.env,
+        home: homedir(),
+        spawnSync,
+        ensureShim: writeShimIfChanged,
+        log,
+      },
+      resolved,
+    )
+
+    const shim = result.shim
+    if (shim !== null && shim.applied === true) {
+      const owned = shim.value
+      ctx.effect(function* bashEnvEffect() {
+        yield () => {
+          try {
+            log.info(`BASH_ENV ${restoreBashEnv(process.env, owned)}`)
+          } catch {
+            // Best-effort teardown.
+          }
+        }
+      }, 'dsh-console-utf8 BASH_ENV')
+    }
+
+    log.info('apply finished')
+  } catch (error) {
+    log.warn(`apply failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}

package/lib/shell-hook.js

@@ -0,0 +1,67 @@
+/**
+ * dsh-console-utf8 — the BASH_ENV hook.
+ *
+ * `chcp` fixes the console the shell itself is attached to, but the shell
+ * executor is free to spawn a command in a fresh console (a detached child
+ * gets the system default page back). `BASH_ENV` closes that hole at the top
+ * of every non-interactive `bash -c`: bash sources the named file before it
+ * runs the command, so the code page is corrected inside the very process
+ * group that is about to invoke `powershell.exe` / `cmd.exe` / `git.exe`.
+ *
+ * Measured 2026-09-13: a non-interactive `bash -c` really does source
+ * `$BASH_ENV`, and `chcp.com 65001` issued from it left the following
+ * `powershell.exe -Command chcp` reporting 65001 and printing its Chinese
+ * message intact.
+ *
+ * @module dsh-console-utf8/shell-hook
+ */
+
+/** File name of the generated hook, written under the dsh state directory. */
+export const SHIM_FILE_NAME = 'console-utf8.sh'
+
+/**
+ * The hook itself.
+ *
+ * Constraints, each of them load-bearing:
+ *   - silent: stdout/stderr of the code page call are discarded, because the
+ *     hook runs in front of every command and any noise would land in the
+ *     tool output;
+ *   - harmless when `chcp.com` is absent (a POSIX machine): `command -v`
+ *     gates it, and the trailing `:` keeps the hook's own exit status 0 so it
+ *     can never masquerade as the command's failure;
+ *   - POSIX `sh` only, no bashisms: `BASH_ENV` is sourced by bash, but
+ *     quoting and `[ ]` conventions here stay portable.
+ *
+ * @param {number} codePage - Code page the hook switches to (65001 = UTF-8).
+ * @returns {string} The complete script text (LF endings, no BOM).
+ */
+export function shimScript(codePage) {
+  return [
+    '#!/bin/sh',
+    '# dsh-console-utf8 — sourced through BASH_ENV before every non-interactive',
+    '# bash command, so Windows-native children of the shell speak UTF-8: that is',
+    '# the encoding the dsh subprocess layer decodes their output with.',
+    `if command -v chcp.com >/dev/null 2>&1; then chcp.com ${codePage} >/dev/null 2>&1; fi`,
+    '# Keep the hook invisible to the command it runs in front of.',
+    ':',
+    '',
+  ].join('\n')
+}
+
+/**
+ * Convert a Windows path into the `/c/...` form Git Bash resolves.
+ *
+ * `BASH_ENV` is consumed by an MSYS bash, and `C:\Users\x\.dsh-tui\f.sh`
+ * survives that hand-off only by accident. The drive-letter form is
+ * deterministic.
+ *
+ * @param {string} windowsPath - `C:\Users\x\.dsh-tui\console-utf8.sh`.
+ * @returns {string} `/c/Users/x/.dsh-tui/console-utf8.sh`; the input with
+ *   forward slashes when it carries no drive letter.
+ */
+export function toPosixPath(windowsPath) {
+  const normalized = String(windowsPath).replaceAll('\\', '/')
+  const drive = /^([A-Za-z]):(\/.*)?$/.exec(normalized)
+  if (drive === null) return normalized
+  return `/${drive[1].toLowerCase()}${drive[2] ?? ''}`
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "dsh-console-utf8",
+  "version": "0.1.1",
+  "description": "Keep the Windows console on code page 65001 (UTF-8) for the dsh host and its bash tool commands, so output from Windows-native child processes stops being decoded as mojibake",
+  "packageManager": "pnpm@11.22.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VviLliAm-qwq/dsh-console-utf8.git"
+  },
+  "author": "VviLliAm-qwq",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "dsh-tui",
+    "deepseek-harness",
+    "encoding",
+    "utf-8",
+    "codepage",
+    "chcp",
+    "windows",
+    "bash",
+    "mojibake"
+  ],
+  "files": [
+    "lib",
+    "dsh-plugin.json",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "scripts": {
+    "test": "node --test",
+    "check:encoding": "node scripts/check-encoding.mjs",
+    "validate:manifest": "node scripts/validate-manifest.mjs",
+    "pack:verify": "node scripts/pack-verify.mjs",
+    "verify": "npm run check:encoding && npm test && npm run validate:manifest && npm run pack:verify",
+    "prepublishOnly": "npm run verify"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}