dsh-global-todo 0.12.5 → 0.12.7

package/CHANGELOG.md

@@ -1,3 +1,40 @@
+## [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).
+
+- **`open(temp, 'r')` → opened for writing.** The atomic write reopened its temp file read-only
+  and called `handle.sync()`. On Windows that is `FlushFileBuffers`, which requires a writable
+  handle, so **every** save threw `EPERM` — and because the sync sat before `rename()`, the
+  target file was never replaced: the list looked empty while `*.tmp` debris accumulated. POSIX
+  allows `fsync` on a read-only descriptor, which is why Linux and macOS never showed it.
+- **The sync is best effort now.** A platform that refuses to flush the temp file gets a warning,
+  and the rename still happens: losing a save is worse than a save that only reached the page
+  cache. The temp file is unlinked when a write fails, so a failure leaves no debris.
+- **The write path is a function with tests.** `atomicWrite()` takes an injectable fs surface; four
+  tests pin the invariant that failed: the handle must be opened for writing, a refused sync must
+  not lose the save, a failed write must clean up, and the payload must reach the file first.
+
 ## [0.12.5] — 2026-10-21
 
 A check for the one install mistake that is invisible until the desktop complains.

package/docs/WINDOWS.md

@@ -0,0 +1,54 @@
+# 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.
+
+## 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/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.5'
+export const VERSION = '0.12.7'
 
 /** 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,7 +19,70 @@
  * @module dsh-global-todo/store
  */
 
-import { open, mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
+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 { homedir } from 'node:os'
 import path from 'node:path'
 
@@ -187,16 +250,12 @@ export function createStore(options) {
     const directory = path.dirname(file)
     await mkdir(directory, { recursive: true })
     const payload = `${JSON.stringify({ version: SCHEMA_VERSION, todos: doc.todos }, null, 2)}\n`
-    const temp = `${file}.${process.pid}.${now()}.tmp`
     try {
-      await writeFile(temp, payload, { mode: 0o600 })
-      const handle = await open(temp, 'r')
-      try {
-        await handle.sync()
-      } finally {
-        await handle.close()
-      }
-      await rename(temp, file)
+      await atomicWrite(file, payload, {
+        // A platform that will not flush the temp file is a warning, not a lost save.
+        onSyncError: (error) =>
+          logger?.warn?.(`dsh-global-todo: 落盘后 fsync 失败（已继续）${file}：${error?.message ?? error}`),
+      })
     } catch (error) {
       throw new TodoError('store-unwritable', `写入待办文件失败 ${file}：${error?.message ?? error}`, { file })
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-global-todo",
-  "version": "0.12.5",
+  "version": "0.12.7",
   "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",