dsh-global-todo 0.12.7 → 0.12.8

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [0.12.8] — 2026-10-21
+
+The Windows runner kept finding things after 0.12.7. Four more, all real.
+
+- **`mkdir` over a file is `EEXIST` on Windows**, not `ENOTDIR`. The store translated only the
+  POSIX code, so an unwritable location could surface as a raw error; both now become
+  `store-unwritable`.
+- **The diagnostics trim could lose its rename** while a reader held the log. The atomic write is
+  now shared (`lib/atomic.js`) by the store, settings and diagnostics, with a longer retry budget
+  for a file that is read constantly.
+- **`tools/preview.mjs` created a directory named `panel.html`** on Windows: it stripped the file
+  name with a SQL-style regex on `/`, which matched nothing there. `path.dirname` instead — this is
+  what made `npm pack --dry-run` fail on the Windows runner.
+- **Two test assertions were POSIX literals** (a default store path and a `path.resolve` result).
+  They now compare resolved paths, which is what the contract actually says.
+- **CI is green on `windows-latest`** — tests, static checks, package shape and
+  `node tools/windows-check.mjs` all run there.
+
 ## [0.12.7] — 2026-10-21
 
 Windows, tested instead of assumed.

package/docs/WINDOWS.md

@@ -21,6 +21,11 @@ Windows machine should run.
 CI runs the suite on **ubuntu-latest and windows-latest** (node 22.19 on both, node 24 on Linux).
 Windows runs `node tools/windows-check.mjs` as an extra step.
 
+That matrix earned its keep on its first day: it found four things Linux could not see — a `mkdir`
+over a file reporting `EEXIST` instead of `ENOTDIR`, the diagnostics trim losing a rename to a busy
+reader, `tools/preview.mjs` creating a directory named `panel.html` (a POSIX-only regex), and two
+test assertions that pinned POSIX literals. All fixed in 0.12.8.
+
 ## The real-filesystem check
 
 ```powershell

package/lib/atomic.js

@@ -0,0 +1,77 @@
+/**
+ * Small, shared file-system guarantees.
+ *
+ * Both the todo file and the diagnostics log are replaced by "write a sibling, then
+ * rename". That pattern has two platform traps this module exists to absorb:
+ *
+ * 1. `fsync` on Windows is `FlushFileBuffers`, which needs a **writable** handle. A
+ *    read-only handle always throws `EPERM`, and a save that throws before its rename
+ *    is a save that never happened (issue #2).
+ * 2. Antivirus, the search indexer and a concurrent reader can hold a handle for a few
+ *    milliseconds, which makes the rename fail with `EPERM`/`EBUSY`/`EACCES`. Retrying
+ *    those turns a spurious failure into a write; other errors still surface at once.
+ *
+ * @module dsh-global-todo/atomic
+ */
+
+import { open, rename, unlink } from 'node:fs/promises'
+
+const TRANSIENT_RENAME_CODES = new Set(['EPERM', 'EBUSY', 'EACCES'])
+
+/**
+ * Rename, retrying only the errors that mean "someone else has it for a moment".
+ *
+ * @param {{ rename: (from: string, to: string) => Promise<void> }} io
+ * @param {string} from temporary file
+ * @param {string} to target file
+ */
+export async function renameWithRetry(io, from, to, attempts = 4) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await io.rename(from, to)
+      return
+    } catch (error) {
+      if (attempt >= attempts || !TRANSIENT_RENAME_CODES.has(error?.code)) throw error
+      await new Promise((resolve) => setTimeout(resolve, 20 * (attempt + 1)))
+    }
+  }
+}
+
+/**
+ * Replace a file atomically, and survive a platform that refuses `fsync`.
+ *
+ * The handle is opened for **writing** on purpose: on Windows `handle.sync()` needs a
+ * writable handle, and opening the temp file read-only made every write throw before the
+ * rename (the todo list looked empty while `*.tmp` debris accumulated).
+ *
+ * The sync itself is best effort: durability matters, but losing a save because a
+ * platform will not flush a handle is worse than a save that reaches the page cache.
+ *
+ * @param {string} file absolute path of the target
+ * @param {string} payload bytes to write
+ * @param {{ fs?: object, onSyncError?: (error: unknown) => void, renameAttempts?: number }} [options]
+ *   injected for tests; `renameAttempts` is there for callers whose target is read constantly
+ */
+export async function atomicWrite(file, payload, options = {}) {
+  const io = options.fs ?? { open, rename, unlink }
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`
+  let handle = null
+  let renamed = false
+  try {
+    handle = await io.open(temp, 'w', 0o600)
+    await handle.writeFile(payload, 'utf8')
+    try {
+      await handle.sync()
+    } catch (error) {
+      options.onSyncError?.(error)
+    }
+    await handle.close()
+    handle = null
+    await renameWithRetry(io, temp, file, options.renameAttempts)
+    renamed = true
+  } finally {
+    if (handle !== null) await handle.close().catch(() => {})
+    // Only debris is cleaned up: after a successful rename the temp file is gone.
+    if (!renamed) await io.unlink(temp).catch(() => {})
+  }
+}

package/lib/diagnostics.js

@@ -9,7 +9,9 @@
  * @module dsh-global-todo/diagnostics
  */
 
-import { appendFile, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { appendFile, readFile, rm } from 'node:fs/promises'
+
+import { atomicWrite } from './atomic.js'
 
 /** How many entries `/health` shows, how many are kept in memory, how many on disk. */
 const RECENT = 5
@@ -66,15 +68,13 @@ export function createDiagnostics(options) {
    * @param {string[]} lines
    */
   const rewrite = async (lines) => {
-    const temp = `${options.file}.${process.pid}.${(rewrites += 1)}.tmp`
-    try {
-      await writeFile(temp, `${lines.slice(-ON_DISK).join('\n')}\n`, 'utf8')
-      await rename(temp, options.file)
-    } catch (error) {
-      // A failed trim must not leave litter beside the log it failed to trim.
-      await rm(temp, { force: true }).catch(() => {})
-      throw error
-    }
+    rewrites += 1
+    // Same helper as the todo file: opened for writing (Windows cannot fsync a read-only
+    // handle), rename retried while an antivirus or a reader holds the file for a moment,
+    // temp file removed if the replace fails.
+    // A debug reader (a tail, an editor, this test) may hold the file almost continuously,
+    // so the trim gets a longer retry budget than a normal save.
+    await atomicWrite(options.file, `${lines.slice(-ON_DISK).join('\n')}\n`, { renameAttempts: 12 })
   }
 
   return {

package/lib/index.js

@@ -36,7 +36,7 @@ import { createStore, resolveStorePath } from './store.js'
 import { createTools } from './tools.js'
 
 /** Must equal `package.json`'s version; `npm run check` enforces that. */
-export const VERSION = '0.12.7'
+export const VERSION = '0.12.8'
 
 /** Plugin id. Also the Loader row id in `cordis.patch.yml`. */
 export const name = 'dsh-global-todo'

package/lib/store.js

@@ -19,76 +19,18 @@
  * @module dsh-global-todo/store
  */
 
-import { open, mkdir, readFile, rename, stat, unlink } from 'node:fs/promises'
-
-/**
- * Rename, retrying only the errors that mean "someone else has it for a moment".
- *
- * @param {{ rename: (from: string, to: string) => Promise<void> }} io
- * @param {string} from temporary file
- * @param {string} to target file
- */
-async function renameWithRetry(io, from, to) {
-  const transient = new Set(['EPERM', 'EBUSY', 'EACCES'])
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      await io.rename(from, to)
-      return
-    } catch (error) {
-      if (attempt >= 4 || !transient.has(error?.code)) throw error
-      await new Promise((resolve) => setTimeout(resolve, 20 * (attempt + 1)))
-    }
-  }
-}
-/**
- * Replace a file atomically, and survive a platform that refuses `fsync`.
- *
- * Opened for **writing** on purpose: on Windows `handle.sync()` is `FlushFileBuffers`,
- * which needs a writable handle. Opening the temp file read-only and syncing it threw
- * `EPERM` on every write, and because that sync sat before `rename()`, the target file
- * was never replaced — the list looked empty while the data piled up as `*.tmp` debris.
- * That was issue #2.
- *
- * The sync itself is best effort: durability matters, but losing a save because a
- * platform will not flush a handle is strictly worse than a save that reaches the page
- * cache. A failing sync is reported and the rename still happens.
- *
- * @param {string} file absolute path of the target
- * @param {string} payload bytes to write
- * @param {{ fs?: object, onSyncError?: (error: unknown) => void }} [options] injected for tests
- */
-export async function atomicWrite(file, payload, options = {}) {
-  const io = options.fs ?? { open, rename, unlink }
-  const temp = `${file}.${process.pid}.${Date.now()}.tmp`
-  let handle = null
-  let renamed = false
-  try {
-    handle = await io.open(temp, 'w', 0o600)
-    await handle.writeFile(payload, 'utf8')
-    try {
-      await handle.sync()
-    } catch (error) {
-      options.onSyncError?.(error)
-    }
-    await handle.close()
-    handle = null
-    // Windows antivirus and the search indexer take short-lived locks on files that were
-    // just written, which makes the rename fail with EPERM/EBUSY for a few milliseconds.
-    // A retry turns a spurious save failure into a save; other errors still surface at once.
-    await renameWithRetry(io, temp, file)
-    renamed = true
-  } finally {
-    if (handle !== null) await handle.close().catch(() => {})
-    // Only debris is cleaned up: after a successful rename the temp file is gone.
-    if (!renamed) await io.unlink(temp).catch(() => {})
-  }
-}
+import { mkdir, open, readFile, stat } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import path from 'node:path'
 
+import { atomicWrite } from './atomic.js'
 import { TodoError } from './errors.js'
 import { LIMITS, SCHEMA_VERSION, normalizeStored } from './model.js'
 
+// Re-exported because the tests (and anyone poking at the store) reach for it here; the
+// implementation lives in atomic.js so the diagnostics log can share it.
+export { atomicWrite }
+
 /**
  * @param {Record<string, string | undefined>} [env]
  * @returns {string} the DSH home directory
@@ -248,7 +190,13 @@ export function createStore(options) {
    */
   async function write(doc) {
     const directory = path.dirname(file)
-    await mkdir(directory, { recursive: true })
+    try {
+      await mkdir(directory, { recursive: true })
+    } catch (error) {
+      // A file where the directory should be reports ENOTDIR on POSIX and EEXIST on
+      // Windows; both mean the same thing to the caller, so both become store-unwritable.
+      throw new TodoError('store-unwritable', `建不了待办目录 ${directory}：${error?.message ?? error}`, { file })
+    }
     const payload = `${JSON.stringify({ version: SCHEMA_VERSION, todos: doc.todos }, null, 2)}\n`
     try {
       await atomicWrite(file, payload, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-global-todo",
-  "version": "0.12.7",
+  "version": "0.12.8",
   "icon": "./docs/icon.svg",
   "description": "Cross-session todo list for DeepSeek Harness: one JSON file a person and an agent both write to, with step plans that ship as a numbered hand-off, session read-back, and a human confirmation before an agent's \"done\" counts.",
   "type": "module",