dsh-console-utf8 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -4,6 +4,11 @@ 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.3 (2026-09-16)
+
+- **A hook file this plugin does not own is never overwritten.** `BASH_ENV` ownership is now decided *before* anything is written — it used to stand down only after `writeShimIfChanged` had already run — and `writeShimIfChanged` refuses to replace a file that exists but does not carry this plugin's marker, raising `ForeignShimError` instead. Following the old warning's advice ("set this plugin's `shimPath` to adopt it") replaced that user's script with no backup. The warning no longer suggests it, and a foreign hook path stands the plugin down with reason `hook path holds a foreign file`.
+- `SHIM_MARKER` and `ForeignShimError` are exported, and five unit tests pin the behaviour: a free path is written, this plugin's own hook follows a code-page change, a foreign file is refused and left byte-identical, ownership is decided before any write, and the marker is exactly what `shimScript()` emits.
+
 ## 0.1.2 (2026-09-13)
 
 - Documentation only, no code change. The READMEs gain a CI badge, the release section records that publishing goes through npm trusted publishing (OIDC) with no stored token, and the duplicated publishing heading is merged into one section.

package/dsh-plugin.json

@@ -3,7 +3,7 @@
   "manifestVersion": "0.15",
   "id": "com.dsh-tui-ecosystem.dsh-console-utf8",
   "name": "dsh-console-utf8",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "facets": {
     "host": {
       "entry": "lib/index.js",

package/lib/plugin.js

@@ -120,6 +120,24 @@ export function restoreBashEnv(env, owned) {
   return 'restored'
 }
 
+/**
+ * Substring that identifies a hook file as THIS plugin's own. Any file at the
+ * configured `shimPath` that does not carry it belongs to somebody else and is
+ * never overwritten.
+ */
+export const SHIM_MARKER = 'dsh-console-utf8'
+
+/** Raised instead of replacing a hook file this plugin does not own. */
+export class ForeignShimError extends Error {
+  /**
+   * @param {string} path - The offending hook path.
+   */
+  constructor(path) {
+    super(`refusing to overwrite ${path}: the file exists and is not this plugin's hook (move it aside, or point shimPath at a free path)`)
+    this.name = 'ForeignShimError'
+  }
+}
+
 /**
  * Write the hook when its content differs, creating the directory if needed.
  *
@@ -127,9 +145,16 @@ export function restoreBashEnv(env, owned) {
  * the fix silently do the wrong thing, so the file is compared rather than
  * assumed.
  *
+ * The file is only ever replaced when it is missing, already identical, or
+ * recognisably this plugin's own (it carries {@link SHIM_MARKER}). Following
+ * the old warning's advice — "set shimPath to adopt an existing BASH_ENV" —
+ * used to overwrite that user's script with no backup; a foreign file now
+ * raises {@link ForeignShimError} instead, and the plugin stands down.
+ *
  * @param {string} path - Hook path.
  * @param {string} content - Desired content.
  * @returns {boolean} True when the file was (re)written.
+ * @throws {ForeignShimError} When `path` holds a file this plugin does not own.
  */
 export function writeShimIfChanged(path, content) {
   let current
@@ -139,6 +164,7 @@ export function writeShimIfChanged(path, content) {
     current = undefined
   }
   if (current === content) return false
+  if (current !== undefined && !current.includes(SHIM_MARKER)) throw new ForeignShimError(path)
   mkdirSync(dirname(path), { recursive: true })
   // No BOM, LF endings: the file is sourced by `sh`, never parsed as JSON.
   writeFileSync(path, content, 'utf8')
@@ -190,24 +216,29 @@ export function setup(deps, config) {
   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
-    }
 
+    // Ownership is decided BEFORE anything is written. Standing down after a
+    // write would already have replaced a file this plugin does not own, so
+    // pointing `shimPath` at somebody else's hook must never destroy it.
     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)`)
+      // this plugin stands down and says why.
+      deps.log.warn(`BASH_ENV is already ${existing}; left untouched. This plugin only maintains its own hook file (shimPath), so that hook wins — remove it first if this plugin should own BASH_ENV`)
       result.shim = { path: shimPath, applied: false, reason: 'BASH_ENV owned by someone else' }
       return result
     }
 
+    let written = false
+    try {
+      written = deps.ensureShim(shimPath, shimScript(config.codePage))
+    } catch (error) {
+      const reason = error instanceof ForeignShimError ? 'hook path holds a foreign file' : 'hook not writable'
+      deps.log.warn(`could not write the shell hook: ${error instanceof Error ? error.message : String(error)}`)
+      result.shim = { path: shimPath, applied: false, reason }
+      return result
+    }
+
     deps.env.BASH_ENV = value
     result.shim = {
       path: shimPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-console-utf8",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",