dsh-plugin-wiki-tools 0.14.1 → 0.14.2

package/README.md

@@ -1,11 +1,22 @@
 # dsh-plugin-wiki-tools
 
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-wiki-tools)](https://www.npmjs.com/package/dsh-plugin-wiki-tools)
+[![npm weekly downloads](https://img.shields.io/npm/dw/dsh-plugin-wiki-tools)](https://www.npmjs.com/package/dsh-plugin-wiki-tools)
+[![License: MIT](https://img.shields.io/npm/l/dsh-plugin-wiki-tools)](LICENSE)
+[![Awesome DSH Plugin](https://img.shields.io/badge/listed-awesome--dsh--plugin-4a90d9)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+
 English | [中文](#中文)
 
 Native [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) tools for an Obsidian wiki vault: `wiki_query`, `wiki_write`, and `wiki_lint` implement the mechanical core of the wiki skill suite — path routing, frontmatter completion, index/log bookkeeping, source delta tracking, and health checks — so the model spends its turns on synthesis instead of filesystem chores.
 
+```sh
+dsh plugin --profile web add dsh-plugin-wiki-tools
+```
+
 Pair with **[dsh-plugin-wiki-skills](https://github.com/Lion-1209/dsh-plugin-wiki-skills)** for the prompt-level skills (`wiki`, `wiki-ingest`, `wiki-query`, `wiki-lint`, `save`).
 
+*If this toolchain saves you time maintaining a wiki vault, a ⭐ helps other dsh users find it. 如果这个工具帮到了你，欢迎点个 Star。*
+
 ## Attribution
 
 The vault layout and operation contracts follow the LLM Wiki pattern (Andrej Karpathy) as embodied by [claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian) (MIT, © 2026 AgriciDaniel). This package is an independent plain-ESM implementation of the mechanical core; it contains no code or skill text from claude-obsidian.

package/lib/vault.js

@@ -214,17 +214,21 @@ export class Vault {
   /**
    * Run one mutation under a cross-process advisory lock (the wiki-lock
    * contract): writers in other processes or sessions serialize on the same
-   * lock file under `.vault-meta/locks/`. A held lock is retried once after
-   * 2s and then reported; a lock older than lockStaleSeconds is treated as
-   * crashed and broken.
+   * lock file under `.vault-meta/locks/`. Default semantics retry once after
+   * 2s and then report; pass `{ waitMs }` for patient polling (used by
+   * internal bookkeeping, where failing the write after the page file is
+   * already on disk would be worse than waiting). A lock older than
+   * lockStaleSeconds is treated as crashed and broken either way.
    * @param {string} key - lock key; vault-relative page path, or `__vault__`
    *   for vault-wide mutations (rename, archive) and `__manifest__` for the
    *   ingest manifest.
    * @param {() => Promise<T>} operation - the mutation to guard.
+   * @param {{ waitMs?: number }} [options] - poll until waitMs elapsed
+   *   instead of the legacy retry-once.
    * @returns {Promise<T>}
    * @template T
    */
-  async withFileLock(key, operation) {
+  async withFileLock(key, operation, { waitMs = 0 } = {}) {
     const locksDir = join(this.root, '.vault-meta', 'locks')
     await mkdir(locksDir, { recursive: true })
     const lockPath = join(locksDir, `${createHash('sha1').update(key).digest('hex')}.lock`)
@@ -244,11 +248,14 @@ export class Vault {
         return false
       }
     }
-    if (!(await acquire())) {
-      await new Promise(resolve => setTimeout(resolve, 2000))
-      if (!(await acquire())) {
+    const deadline = Date.now() + waitMs
+    let attempt = 0
+    while (!(await acquire())) {
+      attempt += 1
+      if (Date.now() >= deadline && !(waitMs === 0 && attempt < 2)) {
         throw new Error(`wiki-tools: ${key} is locked by another writer; skipped (retry once it releases)`)
       }
+      await new Promise((resolve) => setTimeout(resolve, waitMs > 0 ? 200 : 2000))
     }
     try {
       return await operation()
@@ -357,11 +364,19 @@ export class Vault {
       await mkdir(join(path, '..'), { recursive: true })
       await writeFile(path, file, 'utf8')
       this.invalidateCollectCache()
-      await this.updateIndex(type, cleanTitle, summary ?? firstContentLine(content))
-      await this.updateFolderIndex(type, cleanTitle, summary ?? firstContentLine(content))
-      await this.prependLog(`## [${date}] ${existing === undefined ? 'create' : 'update'} | ${cleanTitle}`, [
-        `- ${existing === undefined ? 'Created' : 'Updated'}: [[${cleanTitle}]]`,
-      ])
+      // Index and log are shared state across every writer in the vault: the
+      // per-page lock covers this page's file, but two concurrent writes to
+      // DIFFERENT pages would otherwise read-modify-write index.md and log.md
+      // against each other (entries visibly lost). Serialize the bookkeeping
+      // under the vault-wide lock; lock ordering is page → __vault__, and no
+      // other path acquires a page lock while holding __vault__, so no cycle.
+      await this.withFileLock('__vault__', async () => {
+        await this.updateIndex(type, cleanTitle, summary ?? firstContentLine(content))
+        await this.updateFolderIndex(type, cleanTitle, summary ?? firstContentLine(content))
+        await this.prependLog(`## [${date}] ${existing === undefined ? 'create' : 'update'} | ${cleanTitle}`, [
+          `- ${existing === undefined ? 'Created' : 'Updated'}: [[${cleanTitle}]]`,
+        ])
+      }, { waitMs: this.lockStaleMs * 1000 })
       this.gitCommit(`wiki: ${existing === undefined ? 'create' : 'update'} ${cleanTitle}`)
       if (sourcePath !== undefined) {
         await this.trackSource({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wiki-tools",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Native DeepSeek Harness tools for an Obsidian wiki vault: wiki_query, wiki_write, and wiki_lint implement the mechanical core (path routing, delta tracking, index/log bookkeeping, health checks) of the wiki skill suite.",
   "license": "MIT",
   "type": "module",
@@ -11,7 +11,8 @@
     "./lib/search.js": "./lib/search.js",
     "./lib/lint.js": "./lib/lint.js",
     "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./lib/scaffold.js": "./lib/scaffold.js"
   },
   "files": [
     "index.js",