dsh-global-todo 0.12.6 → 0.12.8

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+## [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.
+
+- **CI runs on windows-latest.** Issue #2 shipped for months because only Linux was ever
+  exercised; the suite now runs on both, plus `node tools/windows-check.mjs` on Windows.
+- **`npm run check:windows`** — a real-filesystem smoke test (no faked `fs`): create a store,
+  update/complete/review then reload, assert no `.tmp` debris, write and read 500 todos, import a
+  CRLF Markdown file, use a path with spaces and non-ASCII characters, and rename over an existing
+  file. `docs/WINDOWS.md` says what to report when one of them fails.
+- **Windows paths are exempt-able.** Settings compared exemptions with `startsWith('/')`, so every
+  workspace a Windows user configured was silently dropped. Now `isAbsolutePath` (drive and UNC),
+  with case-insensitive comparison on Windows and trailing separators of either kind removed.
+- **CRLF Markdown imports.** `fromMarkdown` split on `\n` and left `\r` on every line; a document
+  saved on Windows now parses exactly like the same document saved on Linux.
+- **Transient locks are retried.** Antivirus and the indexer can hold a just-written file for a few
+  milliseconds; `EPERM`/`EBUSY`/`EACCES` during the final rename are retried (bounded), other
+  errors still fail at once, and a real failure cleans up its temp file.
+- **Settings writes are atomic too.** A half-written `settings.json` would silently reset every
+  switch; it now goes through the same temp-file-and-rename path as the todo list.
+
 ## [0.12.6] — 2026-10-21
 
 Saving on Windows never worked. Fixed, with the root cause written down (#2).

package/docs/WINDOWS.md

@@ -0,0 +1,59 @@
+# Windows
+
+Issue #2 was a Windows-only save failure that shipped for months because CI only ever ran Linux:
+the atomic write reopened its temp file read-only and called `fsync`, which on Windows is
+`FlushFileBuffers` and requires a writable handle. Every save threw `EPERM` **before** the rename,
+so the list looked empty while the data piled up as `*.tmp` debris. Fixed in 0.12.6.
+
+This file is the checklist that keeps that from happening again, and the script a tester on a real
+Windows machine should run.
+
+## What the test suite already covers on every platform
+
+| Area | Where | What it pins |
+|---|---|---|
+| atomic write | `test/atomic-write.test.mjs` | the temp file is opened for **writing**; a refused `fsync` warns instead of losing the save; a failed write leaves no debris |
+| rename under a lock | `test/windows.test.mjs` | `EPERM`/`EBUSY`/`EACCES` are retried (bounded), other errors fail at once, no temp file survives a real failure |
+| workspace paths | `test/windows.test.mjs` | `C:\\dev\\demo`, `C:/dev/demo` and `\\\\server\\share` are accepted as exemptions; relative paths are not |
+| CRLF markdown | `test/windows.test.mjs` | a document saved on Windows imports like the same document saved on Linux |
+| install shape | `test/manifest.test.mjs` | `locale/` ships and the `./locale/*.json` export exists (the desktop metadata error) |
+
+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
+git clone https://github.com/LUgABeEEE/dsh-global-todo
+cd dsh-global-todo
+node tools/windows-check.mjs      # or: npm run check:windows
+```
+
+It uses `os.tmpdir()` and does seven things a faked `fs` cannot: create a store, update/complete/
+review then reload, assert no `.tmp` debris, write and read back 500 todos, import a CRLF Markdown
+file, write into a path with spaces and non-ASCII characters, and rename over an existing file. It
+prints one line per check and exits non-zero on the first failure.
+
+## What to report if something fails
+
+1. the check name from the `FAIL` line and the full message;
+2. `node -v`, `dsh --version`, Windows build (`winver`);
+3. whether the data directory is on a network drive, OneDrive, or a synced folder — those change
+   `fsync`/`rename` semantics more than the OS version does;
+4. the contents of `%USERPROFILE%\.dsh\global-todo\` (file names are enough; redact titles if you
+   prefer) — `*.tmp` files are evidence of a write that never renamed.
+
+## Known Windows behaviours that are *not* bugs
+
+- **A `*.tmp` file can briefly appear** while a write is in flight. After a successful save it is
+  gone; after a failed one it is removed by the writer.
+- **Antivirus can hold a handle for a few milliseconds.** That is why the rename is retried rather
+  than reported on the first `EPERM`.
+- **Paths longer than 260 characters** depend on the machine's `LongPathsEnabled` policy; the plugin
+  uses normal Node file APIs, so it inherits that limit rather than working around it.
+- **Case**: workspace exemptions are compared case-insensitively on Windows only.

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.6'
+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/markdown.js

@@ -79,7 +79,10 @@ export function toMarkdown(doc, options = {}) {
 export function fromMarkdown(text) {
   const todos = []
   let current = null
-  for (const raw of clean(text).split('\n')) {
+  // A file saved on Windows arrives with CRLF; split the same way everywhere instead of
+  // leaving a trailing \r on every line for the matchers to trip over.
+  const normalized = clean(text).replace(/\r\n?/g, '\n')
+  for (const raw of normalized.split('\n')) {
     const line = raw.replace(/\s+$/, '')
     const task = /^- \[([ xX])\] (.+)$/.exec(line)
     if (task !== null) {

package/lib/settings.js

@@ -8,7 +8,9 @@
  * @module dsh-global-todo/settings
  */
 
-import { chmod, readFile, writeFile } from 'node:fs/promises'
+import { chmod, readFile } from 'node:fs/promises'
+import { isAbsolutePath } from './links.js'
+import { atomicWrite } from './store.js'
 
 /** How many sessions the cooldown bookkeeping remembers. */
 const ASKED_LIMIT = 50
@@ -91,13 +93,19 @@ export function normalizeSettings(raw) {
   // Newest first, so the cap drops the oldest bookkeeping rather than the newest.
   entries.sort((left, right) => right[1] - left[1])
   for (const [sessionId, at] of entries.slice(0, ASKED_LIMIT)) asked[sessionId] = at
-  // Trailing slashes come off so `/x/` and `/x` cannot both be listed and both match.
+  // Trailing separators come off so `/x/` and `/x` (or `C:\\x\\` and `C:\\x`) cannot both be
+  // listed and both match. Windows workspaces are drive or UNC paths, so the test is
+  // `isAbsolutePath`, not "starts with a slash" — the latter silently rejected every
+  // exempt workspace a Windows user configured.
   const exemptWorkspaces = []
   for (const entry of Array.isArray(source.exemptWorkspaces) ? source.exemptWorkspaces : []) {
     if (typeof entry !== 'string') continue
-    const dir = entry.trim().replace(/\/+$/, '')
+    const dir = entry.trim().replace(/[\\/]+$/, '')
     // A relative path would match by accident; an exemption has to name a place.
-    if (dir === '' || !dir.startsWith('/') || exemptWorkspaces.includes(dir)) continue
+    if (dir === '' || !isAbsolutePath(dir)) continue
+    // Windows paths are case-insensitive, so `C:\\Dev` and `c:\\dev` are one place.
+    const key = process.platform === 'win32' ? dir.toLowerCase() : dir
+    if (exemptWorkspaces.some((listed) => (process.platform === 'win32' ? listed.toLowerCase() : listed) === key)) continue
     if (exemptWorkspaces.length >= EXEMPT_LIMIT) break
     exemptWorkspaces.push(dir)
   }
@@ -161,7 +169,9 @@ export function createSettings(options) {
 
   const persist = async () => {
     try {
-      await writeFile(options.file, `${JSON.stringify({ version: 1, ...state }, null, 2)}\n`, 'utf8')
+      // Same atomic path as the todo file: a half-written settings file on Windows (the
+      // kind a crash or a locked rename leaves behind) would silently reset every switch.
+      await atomicWrite(options.file, `${JSON.stringify({ version: 1, ...state }, null, 2)}\n`)
       // The file can hold an ingest token; keep it readable by the Host user only. Best-effort:
       // a filesystem without POSIX modes must not fail the write.
       await chmod(options.file, 0o600).catch(() => {})

package/lib/store.js

@@ -19,54 +19,18 @@
  * @module dsh-global-todo/store
  */
 
-import { open, mkdir, readFile, rename, stat, unlink } from 'node:fs/promises'
-
-/**
- * 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
-    await io.rename(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
@@ -226,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.6",
+  "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",
@@ -50,6 +50,7 @@
     "docs/ROADMAP.md",
     "docs/QUICKSTART.md",
     "docs/FAQ.md",
+    "docs/WINDOWS.md",
     "docs/icon.svg",
     "docs/screenshots",
     "tools/doctor.mjs",
@@ -71,6 +72,7 @@
   "scripts": {
     "check": "node scripts/check.mjs",
     "doctor": "node tools/doctor.mjs",
+    "check:windows": "node tools/windows-check.mjs",
     "test": "node --test \"test/**/*.test.mjs\"",
     "verify": "npm run check && npm run check:render && npm test",
     "preview": "node tools/preview.mjs",