dsh-global-todo 0.12.4 → 0.12.5

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.12.5] — 2026-10-21
+
+A check for the one install mistake that is invisible until the desktop complains.
+
+- **`dsh-global-todo-doctor`** (`npx dsh-global-todo-doctor <dir>`, also `npm run doctor`): inspects
+  a directory that is supposed to contain the plugin — manifest, `dsh.bundle.patch`, host and
+  client entries, `locale/`, `docs/icon.svg`, `lib/` — and exits non-zero when something required
+  is missing. The case it exists for: a hand-copied `plugins-local` directory without `locale/`
+  still loads, while the desktop app prints `Plugin metadata … ENOENT … \locale`, which points at
+  the symptom and not the cause.
+- **Six tests** drive the checker against real temporary directories: complete copy, missing
+  `locale/`, missing client entry, missing patch file, missing icon (warning only), and a directory
+  that is not the plugin at all.
+- FAQ §15 now starts with the command instead of guessing, and both READMEs document it where a
+  hand-copied install would go wrong.
+
 ## [0.12.4] — 2026-10-21
 
 The repository leaked its own location. Three real paths, and a guard that could not see them.

package/README.md

@@ -182,9 +182,19 @@ The plugin is a Loader row, not a hot-loaded script: **restart the host** (`dsh
 after installing, then refresh the page. A "待办 / Todos" entry appears in the sidebar.
 
 The npm package is the source of truth. A community catalog can lag behind it or point at an
-older release; pin the version you want (`dsh plugin --profile web add dsh-global-todo@0.10.0`)
+older release; pin the version you want (`dsh plugin --profile web add dsh-global-todo@0.12.4`)
 when it matters.
 
+**Hand-copied a directory instead?** Check it before wondering why the plugins page looks wrong:
+
+```sh
+npx dsh-global-todo-doctor "$HOME/.dsh/plugins-local/全局待办插件"
+```
+
+It verifies the manifest, the patch file, both entries, `locale/`, the icon and `lib/`, and exits
+non-zero when something required is missing — the `locale/` case is the field failure that makes
+the desktop app print `Plugin metadata … ENOENT … \locale` while the plugin still loads.
+
 To roll back:
 
 ```sh

package/README.zh.md

@@ -162,6 +162,17 @@ dsh plugin --profile web add /绝对路径/dsh-global-todo
 插件是宿主组合里的**一行 Loader**，不是热加载脚本：**装完要重启宿主**（`dsh web`），
 再刷新页面。侧栏会出现「待办」入口。
 
+**如果你是手动拷贝目录（而不是从 npm 装）**，先自检一遍，别靠猜：
+
+```sh
+npx dsh-global-todo-doctor "$HOME/.dsh/plugins-local/全局待办插件"
+# Windows: npx dsh-global-todo-doctor "$env:USERPROFILE\.dsh\plugins-local\全局待办插件"
+```
+
+它逐项检查 manifest、patch 文件、两个入口、`locale/`、图标和 `lib/`；缺必需项时退出码为 1。
+最容易漏的是 `locale/`——少了它插件照样加载，但桌面端会报
+`Plugin metadata … ENOENT … \locale`。
+
 npm 上的包才是事实来源。社区目录可能落后于 npm、或指向某个旧 release；需要确定版本时
 直接钉版本（`dsh plugin --profile web add dsh-global-todo@0.10.0`）。
 

package/docs/FAQ.md

@@ -166,6 +166,16 @@ rm -r "$DSH_HOME/global-todo"
 也就是说：**你那份本地插件目录缺 `locale/` 文件夹**。常见于把仓库文件夹手动复制到
 `%USERPROFILE%\.dsh\plugins-local\` 时只拷了 `lib`、`package.json`、`cordis.patch.yml`。
 
+先确认到底缺什么，别靠猜：
+
+```sh
+npx dsh-global-todo-doctor "$HOME/.dsh/plugins-local/全局待办插件"
+# Windows: npx dsh-global-todo-doctor "$env:USERPROFILE\.dsh\plugins-local\全局待办插件"
+```
+
+它逐项检查 `package.json`、patch 文件、两个入口、`locale/`、图标与 `lib/`，缺哪样直接点出来，
+缺必需项时退出码为 1（可以放进安装脚本里当门禁）。
+
 修法二选一：
 
 1. **推荐**：别用本地目录，直接装 npm 包（包里有 `locale/en.json`、`locale/zh.json`）：

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.4'
+export const VERSION = '0.12.5'
 
 /** Plugin id. Also the Loader row id in `cordis.patch.yml`. */
 export const name = 'dsh-global-todo'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-global-todo",
-  "version": "0.12.4",
+  "version": "0.12.5",
   "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",
@@ -52,6 +52,8 @@
     "docs/FAQ.md",
     "docs/icon.svg",
     "docs/screenshots",
+    "tools/doctor.mjs",
+    "tools/doctor-lib.mjs",
     "!docs/screenshots/demo.mp4",
     "!docs/index.html",
     "!docs/assets",
@@ -63,8 +65,12 @@
     "CONTRIBUTING.md",
     "CODE_OF_CONDUCT.md"
   ],
+  "bin": {
+    "dsh-global-todo-doctor": "./tools/doctor.mjs"
+  },
   "scripts": {
     "check": "node scripts/check.mjs",
+    "doctor": "node tools/doctor.mjs",
     "test": "node --test \"test/**/*.test.mjs\"",
     "verify": "npm run check && npm run check:render && npm test",
     "preview": "node tools/preview.mjs",

package/tools/doctor-lib.mjs

@@ -0,0 +1,123 @@
+/**
+ * A pre-flight check for an installed copy of this plugin.
+ *
+ * The failure this exists for is specific: a hand-copied `plugins-local` directory
+ * usually keeps `lib/`, `package.json` and the patch file, and drops `locale/` —
+ * the plugin still loads, the panel still works, and the desktop app prints
+ * `Plugin metadata … ENOENT … \locale` on the plugins page. Node resolves the
+ * `./locale/*.json` export *without* checking that the file exists, and the Host then
+ * scans the directory, which is why the symptom appears far from the cause.
+ *
+ * Everything here is a pure function of the directory contents, so the test suite can
+ * call it without spawning anything.
+ */
+import { readFile, readdir, stat } from 'node:fs/promises'
+import path from 'node:path'
+
+const EXPORT_LOCALE = './locale/*.json'
+
+const readJson = async (file) => {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+const exists = async (file) => {
+  try {
+    const info = await stat(file)
+    return info.isFile() || info.isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {string} dir directory that should contain the plugin, e.g. …/plugins-local/全局待办插件
+ * @returns {Promise<{ok: boolean, dir: string, findings: {level: 'ok'|'warn'|'error', id: string, message: string, fix?: string}[], version?: string}>}
+ */
+export async function doctor(dir) {
+  const findings = []
+  const add = (level, id, message, fix) => findings.push({ level, id, message, ...(fix === undefined ? {} : { fix }) })
+
+  const manifestFile = path.join(dir, 'package.json')
+  const manifest = await readJson(manifestFile)
+  if (manifest === null) {
+    add('error', 'package-missing', 'package.json 读不到或不是合法 JSON', '把插件目录指到包含 package.json 的那一层（例如 …/plugins-local/全局待办插件）')
+    return { ok: false, dir, findings }
+  }
+
+  if (manifest.name !== 'dsh-global-todo') {
+    add('warn', 'package-name', `package.json 里的 name 是 ${manifest.name ?? '(缺失)'}，不是 dsh-global-todo`, '这个目录可能不是本插件')
+  } else {
+    add('ok', 'package-name', `${manifest.name}@${manifest.version ?? '?'}`)
+  }
+
+  // The patch file is what contributes the Loader row. Without it nothing loads.
+  const patch = manifest.dsh?.bundle?.patch
+  if (typeof patch !== 'string') {
+    add('error', 'patch-declared', 'package.json 没有声明 dsh.bundle.patch', '这不是一个可安装的 DSH bundle')
+  } else if (!(await exists(path.join(dir, patch)))) {
+    add('error', 'patch-file', `dsh.bundle.patch 指向 ${patch}，但文件不存在`, '从 npm 包重新拷贝，或 `dsh plugin add dsh-global-todo`')
+  } else {
+    add('ok', 'patch-file', patch)
+  }
+
+  // Both halves must exist; the client half is what the panel loads.
+  const entry = manifest.exports?.['.']
+  const client = manifest.exports?.['./client']
+  for (const [label, target] of [['host entry', entry], ['client entry', client]]) {
+    if (typeof target !== 'string') {
+      add('warn', 'entry-declared', `package.json 没有 ${label} 的 exports`, '宿主可能用默认解析，先确认版本是否完整')
+      continue
+    }
+    if (await exists(path.join(dir, target))) add('ok', 'entry', target)
+    else add('error', 'entry-file', `${label} 指向 ${target}，文件不存在`, '这个目录不是完整拷贝：重新从 npm 包复制 lib/')
+  }
+
+  // The locale export is the one that fails in the field: the export exists, the
+  // directory does not, and the Host reports it as plugin-metadata trouble.
+  const localeExport = manifest.exports?.[EXPORT_LOCALE]
+  const localeDir = path.join(dir, 'locale')
+  const localeExists = await exists(localeDir)
+  const files = localeExists ? (await readdir(localeDir).catch(() => [])).filter((name) => name.endsWith('.json')) : []
+  if (typeof localeExport === 'string' && !localeExists) {
+    add(
+      'error',
+      'locale-missing',
+      'package.json 声明了 ./locale/*.json，但 locale/ 目录不存在 —— 桌面端会显示 Plugin metadata … ENOENT … \\locale',
+      '拷贝 locale/ 目录，或用 npm 包重装：dsh plugin add dsh-global-todo（插件本身仍能加载，坏的是插件页标题/描述）',
+    )
+  } else if (typeof localeExport === 'string' && files.length === 0) {
+    add('warn', 'locale-empty', 'locale/ 存在但没有 .json 文件', '至少需要 en.json 与 zh.json')
+  } else if (files.length > 0) {
+    add('ok', 'locale', `locale/ → ${files.sort().join(', ')}`)
+  }
+
+  // The icon is cosmetic: a missing one shows a blank mark, not an error.
+  if (await exists(path.join(dir, 'docs', 'icon.svg'))) add('ok', 'icon', 'docs/icon.svg')
+  else add('warn', 'icon-missing', 'docs/icon.svg 不存在，插件页会没有图标', '可选：一并拷过去即可，不影响加载')
+
+  const libDir = path.join(dir, 'lib')
+  const libFiles = (await exists(libDir)) ? (await readdir(libDir).catch(() => [])).filter((name) => name.endsWith('.js')) : []
+  if (libFiles.length === 0) add('error', 'lib-empty', 'lib/ 里没有 .js 文件', '从 npm 包重新复制 lib/')
+  else add('ok', 'lib', `lib/ → ${libFiles.length} 个模块`)
+
+  return { ok: !findings.some((finding) => finding.level === 'error'), dir, version: manifest.version, findings }
+}
+
+/** One line per finding, for a terminal. */
+export function format(report) {
+  const mark = { ok: 'OK  ', warn: 'WARN', error: 'FAIL' }
+  const lines = [`dsh-global-todo doctor — ${report.dir}`, '']
+  for (const finding of report.findings) {
+    lines.push(`${mark[finding.level]}  ${finding.message}`)
+    if (finding.fix !== undefined) lines.push(`      fix: ${finding.fix}`)
+  }
+  const errors = report.findings.filter((finding) => finding.level === 'error').length
+  const warns = report.findings.filter((finding) => finding.level === 'warn').length
+  lines.push('')
+  lines.push(errors === 0 ? `OK — ${warns} warning(s)` : `${errors} error(s), ${warns} warning(s)`)
+  return lines.join('\n')
+}

package/tools/doctor.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * dsh-global-todo-doctor — check that a directory really contains this plugin.
+ *
+ *   npx dsh-global-todo-doctor "~/.dsh/plugins-local/全局待办插件"
+ *   node tools/doctor.mjs .            # from a checkout
+ *
+ * Exists because the field failure is silent-ish: a hand-copied plugin directory
+ * without `locale/` still loads, and only the desktop plugins page complains.
+ */
+import { doctor, format } from './doctor-lib.mjs'
+import path from 'node:path'
+
+const args = process.argv.slice(2).filter((value) => value !== '')
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write('用法 / usage:\n  dsh-global-todo-doctor [插件目录]\n\n默认检查当前目录。\n')
+  process.exit(0)
+}
+
+const target = path.resolve(args[0] ?? process.cwd())
+const report = await doctor(target)
+process.stdout.write(format(report) + '\n')
+process.exit(report.ok ? 0 : 1)