dsh-plugin-wiki-tools 0.14.0 → 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.
@@ -16,7 +27,7 @@ The vault layout and operation contracts follow the LLM Wiki pattern (Andrej Kar
 | --- | --- |
 | `wiki_query` | Quick mode returns `hot.md` + `index.md` verbatim (the skill's read order); standard mode is full-text search over content pages with snippets and the inbound/outbound link graph |
 | `wiki_write` | Writes one page with complete bookkeeping: type→folder routing, frontmatter completion (keeps `created` and unknown fields on update), filename-uniqueness guard, master-index entry, log entry; with `source_path`, records the source hash and skips unchanged sources unless `force` |
-| `wiki_lint` | Health check: duplicate filenames, dead wikilinks, orphan pages, frontmatter gaps, empty sections, stale index entries, stale hot cache — report only, with suggestions, written to `wiki/meta/lint-report-<date>.md` |
+| `wiki_lint` | Health check: duplicate filenames, dead wikilinks, orphan pages, frontmatter gaps, empty sections, stale index entries, stale hot cache — report only, with suggestions, written to `wiki/meta/Lint Report <date>.md` |
 
 ## Install and configure
 

package/lib/lint.js

@@ -1,7 +1,7 @@
 /**
  * Vault health checks: the mechanical half of the wiki-lint skill. Report
  * only — auto-fixing is a human decision, so every issue carries a suggestion
- * and the report lands in `wiki/meta/lint-report-YYYY-MM-DD.md`.
+ * and the report lands in `wiki/meta/Lint Report YYYY-MM-DD.md`.
  *
  * @module dsh-plugin-wiki-tools/lib/lint
  */
@@ -289,7 +289,7 @@ async function checkHotCacheStaleness(root, pages, add) {
  */
 async function writeReport(root, issues, pagesScanned) {
   const date = today()
-  const path = join(root, 'wiki', 'meta', `lint-report-${date}.md`)
+  const path = join(root, 'wiki', 'meta', `Lint Report ${date}.md`)
   const sections = new Map()
   for (const issue of issues) {
     if (!sections.has(issue.check)) sections.set(issue.check, [])

package/lib/vault.js

@@ -132,9 +132,32 @@ export class Vault {
     )
     /** Per-file write chains so concurrent tool calls serialize per target. */
     this.writeChains = new Map()
+    /** collectMarkdown result cache: { pages, ts }. Invalidated on every mutation. */
+    this._collectCache = null
   }
 
-  /** Absolute path of one routed page. @param {string} type - page type. @param {string} title - page title (also the filename). */
+    /**
+  * Cached wrapper around the module-level collectMarkdown. The cache lives
+  * for 30 s or until the next invalidateCollectCache call, whichever comes
+  * first. Writes always invalidate first, so a writer never sees stale data
+  * from its own session. Cross-process writes are visible on the next call
+  * after the cache expires.
+  * @returns {Promise<ReturnType<typeof collectMarkdown>>}
+  */
+ async collectPages() {
+   if (this._collectCache !== null) {
+     const { pages, ts } = this._collectCache
+     if (Date.now() - ts < 30000) return pages
+   }
+   const pages = await collectMarkdown(join(this.root, 'wiki'))
+   this._collectCache = { pages, ts: Date.now() }
+   return pages
+ }
+
+ /** Drop the collectMarkdown cache. Call after every vault mutation. */
+ invalidateCollectCache() { this._collectCache = null }
+
+ /** Absolute path of one routed page. @param {string} type - page type. @param {string} title - page title (also the filename). */
   pagePath(type, title) {
     const folder = this.typeFolders[type]
     if (folder === undefined) throw new Error(`wiki-tools: unknown page type "${type}"`)
@@ -191,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`)
@@ -221,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()
@@ -333,11 +363,20 @@ export class Vault {
       const file = `---\n${stringifyYaml(fields).trimEnd()}\n---\n\n${content.replace(/^\s*\n/, '')}\n`
       await mkdir(join(path, '..'), { recursive: true })
       await writeFile(path, file, 'utf8')
-      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}]]`,
-      ])
+      this.invalidateCollectCache()
+      // 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({
@@ -349,7 +388,11 @@ export class Vault {
       // Surface dead-on-arrival wikilinks now, not at the next lint: forward
       // links to pages about to be created are legitimate, so this is a note,
       // never a rejection.
-      const pagesNow = await collectMarkdown(join(this.root, 'wiki'))
+      // All vault mutations above this point may have invalidated earlier
+      // cache entries; force a fresh scan so the unresolved-links report
+      // reflects every page the vault actually contains right now.
+      this.invalidateCollectCache()
+      const pagesNow = await this.collectPages()
       const names = new Set(pagesNow.map(page => page.name))
       const aliases = buildAliasMap(pagesNow)
       const unresolvedLinks = [...new Set(extractWikilinks(content))]
@@ -414,7 +457,7 @@ export class Vault {
         throw new Error(`wiki-tools: newTitle must be a plain filename without path separators (got ${JSON.stringify(newTitle)})`)
       }
       if (cleanNew === title) throw new Error('wiki-tools: newTitle equals the current title')
-      const pages = await collectMarkdown(join(this.root, 'wiki'))
+      const pages = await this.collectPages()
       const target = pages.find(page => page.name === title)
       if (target === undefined) throw new Error(`wiki-tools: no page named "${title}" exists in the vault`)
       if (isMachineryPage(title)) {
@@ -430,7 +473,7 @@ export class Vault {
       // 1. Rewrite links everywhere except immutable records.
       const rewritten = []
       for (const page of pages) {
-        if (page.name === title || page.name.toLowerCase() === 'log' || /^lint-report-/.test(page.name)) continue
+        if (page.name === title || page.name.toLowerCase() === 'log' || isMachineryPage(page.name)) continue
         const raw = await readFile(page.path, 'utf8').catch(() => undefined)
         if (raw === undefined) continue
         // Exact-target boundary: the title must end the link target (`]]`),
@@ -465,6 +508,7 @@ export class Vault {
         `- Renamed: [[${title}]] → [[${cleanNew}]] (${rewritten.length} files' links rewritten)`,
       ])
       this.gitCommit(`wiki: rename ${title} -> ${cleanNew}`)
+      this.invalidateCollectCache()
       return { from: title, to: cleanNew, path: newPath, linksRewritten: rewritten.length, filesRewritten: rewritten }
     }))
   }
@@ -503,6 +547,7 @@ export class Vault {
         `- Archived: \`${rel}\` → \`.archive/${rel.slice('.raw/'.length)}\``,
       ])
       this.gitCommit(`wiki: archive ${rel}`)
+      this.invalidateCollectCache()
       return { archivedFrom: rel, archivedTo: `.archive/${rel.slice('.raw/'.length)}` }
     }))
   }
@@ -530,7 +575,7 @@ export class Vault {
    * @param {string} path - the routed destination path.
    */
   async assertUniqueFilename(title, path) {
-    const pages = await collectMarkdown(join(this.root, 'wiki'))
+    const pages = await this.collectPages()
     for (const page of pages) {
       if (page.name.toLowerCase() === title.toLowerCase() && page.path !== path) {
         throw new Error(`wiki-tools: filename "${title}.md" already exists at ${page.path}; wikilinks need unique filenames`)
@@ -560,7 +605,8 @@ export class Vault {
     const lines = raw.split('\n')
     let headingLine = lines.findIndex(line => line === heading)
     if (headingLine < 0) {
-      lines.push('', heading, `- [[${title}]]: ${summary.replace(/\n/g, ' ')}`)
+      const separator = dominantSeparator(raw)
+      lines.push('', heading, `- [[${title}]]${separator} ${summary.replace(/\n/g, ' ')}`)
       await writeFile(indexPath, `${lines.join('\n')}\n`, 'utf8')
       return
     }
@@ -723,6 +769,20 @@ function indexSeparator(section, matched) {
   return dashes > colons ? ' —' : ':'
 }
 
+/**
+ * Pick the dominant separator style across all index entry lines in one body
+ * of text: ` — ` (em-dash) if it appears in more entries than `: `, else colon.
+ * Used when a new section has no prior entries to copy style from.
+ * @param {string} text - the full index text.
+ * @returns {string} either ' —' or ':'.
+ */
+function dominantSeparator(text) {
+  const entries = text.split('\n').filter(line => /^- \[\[/.test(line))
+  const dashCount = entries.filter(line => line.includes(' — ')).length
+  const colonCount = entries.filter(line => line.includes(': ')).length
+  return dashCount > colonCount ? ' —' : ':'
+}
+
 /**
  * Read a JSON file, returning the fallback when absent.
  * @param {string} path - absolute file path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wiki-tools",
-  "version": "0.14.0",
+  "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",