dsh-plugin-wiki-tools 0.9.0 → 0.10.0

package/index.js

@@ -11,6 +11,8 @@
  * @module dsh-plugin-wiki-tools
  */
 
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import z from '@deepseek-ai/schemastery'
 import { Vault } from './lib/vault.js'
@@ -27,6 +29,10 @@ export const Config = z.object({
   vaultPath: z.string().required(),
   /** Maximum pages returned by one wiki_query standard-mode call. */
   maxQueryResults: z.number().default(10),
+  /** Commit each vault mutation when the vault is a git repository. */
+  gitAutoCommit: z.boolean().default(false),
+  /** Age in seconds at which a held cross-process lock is treated as crashed. */
+  lockStaleSeconds: z.number().default(60),
   /** Per-type folder overrides over the default routing, e.g. `{ domain: "wiki/areas" }`. */
   typeFolders: z.object({
     source: z.string(),
@@ -403,7 +409,16 @@ export async function apply(ctx, config) {
       + 'The vault is the directory holding wiki/ and .raw/ (scaffold it with the wiki skill first).',
     )
   }
-  const vault = new Vault(config.vaultPath, config.typeFolders ?? {})
+  if (config.gitAutoCommit === true && !existsSync(join(config.vaultPath, '.git'))) {
+    throw new Error(
+      'wiki-tools: gitAutoCommit is enabled but the vault is not a git repository; run git init in it first',
+    )
+  }
+  const vault = new Vault(config.vaultPath, {
+    typeFolders: config.typeFolders ?? {},
+    gitAutoCommit: config.gitAutoCommit ?? false,
+    lockStaleSeconds: config.lockStaleSeconds ?? 60,
+  })
   await vault.assertRoot()
   for (const tool of createTools(vault, config)) {
     ctx.tools.register(tool)

package/lib/search.js

@@ -26,9 +26,12 @@ export async function quickView(root) {
 }
 
 /**
- * Full-text search over the wiki tree with link-graph context. Matches are
- * case-insensitive substrings scored by where they hit: title 5, tags 4,
- * headings 2, body 1 per occurrence.
+ * Full-text search over the wiki tree with link-graph context. BM25 ranks
+ * term overlap (latin words; CJK unigram/bigram) at two granularities: whole
+ * pages for the ranking core, and heading/paragraph chunks (the wiki-retrieve
+ * design) so each hit's snippet is its best-matching passage. Substring
+ * bonuses keep exact title/alias/tag phrases and partial words ahead, and a
+ * substring-only hit still surfaces when tokenization misses it.
  * @param {string} root - absolute vault root.
  * @param {object} options - search options.
  * @param {string} options.query - the search text.
@@ -55,31 +58,48 @@ export async function searchVault(root, { query, limit = 10 }) {
       if (resolved !== undefined) inbound.get(resolved)?.push(page.name)
     }
   }
-  // BM25 ranks term overlap (latin words; CJK unigram+bigram); the substring
-  // bonuses below keep exact title/alias/tag phrases and partial words ahead,
-  // and a substring-only hit still surfaces when tokenization misses it.
   const documents = new Map(searchable.map(page => [
     page.name,
     `${page.name} ${(page.aliases ?? []).join(' ')} ${tagsOf(page)} ${page.content}`,
   ]))
   const bm25Scores = rank(buildIndex(documents), query)
 
+  const chunksByPage = new Map(searchable.map(page => [page.name, chunkPage(page.content)]))
+  const chunkDocs = new Map()
+  for (const [name, chunks] of chunksByPage) {
+    chunks.forEach((chunk, index) => chunkDocs.set(`${name}\u0000${index}`, chunk))
+  }
+  /** Best chunk (index + score) per page from chunk-level BM25. */
+  const bestChunk = new Map()
+  for (const [key, score] of rank(buildIndex(chunkDocs), query)) {
+    const name = key.slice(0, key.indexOf('\u0000'))
+    if (score > (bestChunk.get(name)?.score ?? 0)) {
+      bestChunk.set(name, { score, index: Number(key.slice(key.indexOf('\u0000') + 1)) })
+    }
+  }
+
   const results = []
   let totalMatches = 0
   for (const page of searchable) {
     const bm25 = bm25Scores.get(page.name) ?? 0
+    const chunk = bestChunk.get(page.name)
     const titleHit = page.name.toLowerCase().includes(needle)
       || (page.aliases ?? []).some(alias => alias.toLowerCase().includes(needle))
     const tagHit = tagsOf(page).includes(needle)
     const bodyHit = page.content.toLowerCase().includes(needle)
-    if (bm25 === 0 && !titleHit && !tagHit && !bodyHit) continue
+    if (bm25 === 0 && chunk === undefined && !titleHit && !tagHit && !bodyHit) continue
     totalMatches += 1
-    const score = bm25 + (titleHit ? 5 : 0) + (tagHit ? 4 : 0) + (bodyHit ? 1 : 0)
+    const score = bm25 + (chunk?.score ?? 0) + (titleHit ? 5 : 0) + (tagHit ? 4 : 0) + (bodyHit ? 1 : 0)
+    const chunks = chunksByPage.get(page.name) ?? []
+    const snippetChunk = chunk !== undefined ? chunks[chunk.index] : undefined
+    const snippets = snippetChunk !== undefined && snippetChunk.trim().length > 0
+      ? [trimForSnippet(snippetChunk)]
+      : matchLines(page.content, needle).slice(0, 2)
     results.push({
       name: page.name,
       path: page.path,
       score: Math.round(score * 100) / 100,
-      snippets: matchLines(page.content, needle).slice(0, 2),
+      snippets,
       inbound: inbound.get(page.name) ?? [],
       outbound: new Set(page.links).size,
     })
@@ -88,6 +108,44 @@ export async function searchVault(root, { query, limit = 10 }) {
   return { results: results.slice(0, limit), totalMatches: results.length }
 }
 
+/**
+ * Split a page body into retrieval chunks: blocks separated by blank lines,
+ * accumulated up to ~800 characters per chunk without splitting a block.
+ * @param {string} content - page body.
+ * @returns {string[]} non-empty chunks.
+ */
+function chunkPage(content) {
+  const chunks = []
+  let current = ''
+  for (const block of content.split(/\n\s*\n/)) {
+    const trimmed = block.trim()
+    if (trimmed.length === 0) continue
+    if (current.length === 0) {
+      current = trimmed
+    } else if (current.length + trimmed.length + 2 <= 800) {
+      current += `\n\n${trimmed}`
+    } else {
+      chunks.push(current)
+      current = trimmed
+    }
+  }
+  if (current.length > 0) chunks.push(current)
+  return chunks
+}
+
+/**
+ * Trim one chunk for snippet display, cutting at a word boundary.
+ * @param {string} chunk - the chunk text.
+ * @returns {string} at most ~300 characters with an ellipsis marker.
+ */
+function trimForSnippet(chunk) {
+  const text = chunk.replace(/\n+/g, ' ').trim()
+  if (text.length <= 300) return text
+  const cut = text.slice(0, 300)
+  const lastSpace = cut.lastIndexOf(' ')
+  return `${cut.slice(0, lastSpace > 200 ? lastSpace : 300)}...`
+}
+
 /**
  * Case-insensitive matching lines, trimmed for a result snippet.
  * @param {string} content - page body.
@@ -106,7 +164,6 @@ function matchLines(content, needle) {
   return lines
 }
 
-
 /**
  * A page's tags as one lowercase string for matching.
  * @param {{ fields?: Record<string, unknown> }} page - collected page.

package/lib/vault.js

@@ -12,7 +12,8 @@
  */
 
 import { createHash } from 'node:crypto'
-import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { spawnSync } from 'node:child_process'
+import { mkdir, open, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
 import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 
@@ -74,19 +75,31 @@ export function today() {
 /**
  * One vault root. All bookkeeping mutations go through {@link Vault.writePage},
  * which completes frontmatter, updates the master index, and prepends a log
- * entry in one serialized write per file.
+ * entry in one serialized write per file, guarded by a cross-process advisory
+ * lock (the wiki-lock contract) and optionally followed by a git commit.
  */
 export class Vault {
   /**
    * @param {string} root - absolute path to the vault root (the directory holding `wiki/` and `.raw/`).
-   * @param {Record<string, string>} [typeFolders] - per-type folder overrides over {@link TYPE_FOLDERS}
-   *   (e.g. `{ domain: 'wiki/areas' }` for a vault whose top-level topics live in `areas/`).
+   * @param {object} [options] - vault options.
+   * @param {Record<string, string>} [options.typeFolders] - per-type folder overrides over
+   *   {@link TYPE_FOLDERS} (e.g. `{ domain: 'wiki/areas' }` for a vault whose topics live in `areas/`).
+   * @param {boolean} [options.gitAutoCommit] - commit each mutation when the vault is a git repository.
+   * @param {number} [options.lockStaleSeconds] - age at which a held advisory lock is considered
+   *   crashed and may be broken; default 60.
    */
-  constructor(root, typeFolders = {}) {
+  constructor(root, { typeFolders = {}, gitAutoCommit = false, lockStaleSeconds = 60 } = {}) {
     if (typeof root !== 'string' || root.length === 0 || !isAbsolute(root)) {
       throw new Error(`wiki-tools: vaultPath must be an absolute directory path (got ${JSON.stringify(root)})`)
     }
+    for (const key of Object.keys(arguments[1] ?? {})) {
+      if (!['typeFolders', 'gitAutoCommit', 'lockStaleSeconds'].includes(key)) {
+        throw new Error(`wiki-tools: unknown Vault option "${key}"`)
+      }
+    }
     this.root = root
+    this.gitAutoCommit = gitAutoCommit
+    this.lockStaleMs = lockStaleSeconds * 1000
     this.typeFolders = { ...TYPE_FOLDERS }
     for (const [type, folder] of Object.entries(typeFolders)) {
       if (!(type in this.typeFolders)) {
@@ -159,6 +172,70 @@ export class Vault {
     return next
   }
 
+  /**
+   * 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.
+   * @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.
+   * @returns {Promise<T>}
+   * @template T
+   */
+  async withFileLock(key, operation) {
+    const locksDir = join(this.root, '.vault-meta', 'locks')
+    await mkdir(locksDir, { recursive: true })
+    const lockPath = join(locksDir, `${createHash('sha1').update(key).digest('hex')}.lock`)
+    const acquire = async () => {
+      try {
+        const handle = await open(lockPath, 'wx')
+        await handle.writeFile(`${JSON.stringify({ key, at: Date.now() })}\n`)
+        await handle.close()
+        return true
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error
+        const info = await stat(lockPath).catch(() => undefined)
+        if (info !== undefined && Date.now() - info.mtimeMs > this.lockStaleMs) {
+          await rm(lockPath, { force: true })
+          return await acquire()
+        }
+        return false
+      }
+    }
+    if (!(await acquire())) {
+      await new Promise(resolve => setTimeout(resolve, 2000))
+      if (!(await acquire())) {
+        throw new Error(`wiki-tools: ${key} is locked by another writer; skipped (retry once it releases)`)
+      }
+    }
+    try {
+      return await operation()
+    } finally {
+      await rm(lockPath, { force: true })
+    }
+  }
+
+  /**
+   * Stage and commit vault changes when git auto-commit is enabled (the
+   * upstream PostToolUse behavior). Commits only when something is staged.
+   * @param {string} message - the conventional commit message.
+   * @returns {void} throws with git's stderr when git itself fails.
+   */
+  gitCommit(message) {
+    if (!this.gitAutoCommit) return
+    const run = args => spawnSync('git', ['-C', this.root, ...args], { encoding: 'utf8' })
+    const add = run(['add', '-A'])
+    if (add.status !== 0) throw new Error(`wiki-tools: git add failed in the vault: ${String(add.stderr).trim()}`)
+    const pending = run(['diff', '--cached', '--quiet'])
+    if (pending.status === 1) {
+      const commit = run(['commit', '-m', message])
+      if (commit.status !== 0) throw new Error(`wiki-tools: git commit failed in the vault: ${String(commit.stderr).trim()}`)
+    }
+  }
+
   /**
    * Write one wiki page with complete bookkeeping: frontmatter completion,
    * filename-uniqueness guard, master-index entry, folder `_index.md` entry,
@@ -178,7 +255,7 @@ export class Vault {
    */
   async writePage({ type, title, content, tags, status, summary, extraFrontmatter }) {
     const path = this.pagePath(type, title)
-    return await this.enqueue(path, async () => {
+    return await this.enqueue(path, async () => await this.withFileLock(relative(this.root, path).split(sep).join('/'), async () => {
       await this.assertRoot()
       const cleanTitle = title.endsWith('.md') ? title.slice(0, -3) : title
       const existing = await this.readPage(path)
@@ -203,8 +280,9 @@ export class Vault {
       await this.prependLog(`## [${date}] ${existing === undefined ? 'create' : 'update'} | ${cleanTitle}`, [
         `- ${existing === undefined ? 'Created' : 'Updated'}: [[${cleanTitle}]]`,
       ])
+      this.gitCommit(`wiki: ${existing === undefined ? 'create' : 'update'} ${cleanTitle}`)
       return { path, created: existing === undefined, title: cleanTitle }
-    })
+    }))
   }
 
   /**
@@ -253,7 +331,7 @@ export class Vault {
    * @returns {Promise<{ from: string, to: string, path: string, linksRewritten: number, filesRewritten: string[] }>}
    */
   async renamePage({ title, newTitle }) {
-    return await this.enqueue(join(this.root, 'wiki'), async () => {
+    return await this.enqueue(join(this.root, 'wiki'), async () => await this.withFileLock('__vault__', async () => {
       await this.assertRoot()
       const cleanNew = newTitle.endsWith('.md') ? newTitle.slice(0, -3) : newTitle
       if (!/^[^/\\]+(\.md)?$/.test(newTitle) || newTitle.includes('\n')) {
@@ -300,8 +378,9 @@ export class Vault {
       await this.prependLog(`## [${today()}] rename | ${title}`, [
         `- Renamed: [[${title}]] → [[${cleanNew}]] (${rewritten.length} files' links rewritten)`,
       ])
+      this.gitCommit(`wiki: rename ${title} -> ${cleanNew}`)
       return { from: title, to: cleanNew, path: newPath, linksRewritten: rewritten.length, filesRewritten: rewritten }
-    })
+    }))
   }
 
   /**
@@ -313,7 +392,7 @@ export class Vault {
    * @returns {Promise<{ archivedFrom: string, archivedTo: string }>}
    */
   async archiveSource({ sourcePath }) {
-    return await this.enqueue(join(this.root, '.archive'), async () => {
+    return await this.enqueue(join(this.root, '.archive'), async () => await this.withFileLock('__vault__', async () => {
       await this.assertRoot()
       const absolute = isAbsolute(sourcePath) ? sourcePath : join(this.root, sourcePath)
       const rel = relative(this.root, absolute).split(sep).join('/')
@@ -335,8 +414,9 @@ export class Vault {
       await this.prependLog(`## [${today()}] archive | ${rel}`, [
         `- Archived: \`${rel}\` → \`.archive/${rel.slice('.raw/'.length)}\``,
       ])
+      this.gitCommit(`wiki: archive ${rel}`)
       return { archivedFrom: rel, archivedTo: `.archive/${rel.slice('.raw/'.length)}` }
-    })
+    }))
   }
 
   /**
@@ -435,6 +515,7 @@ export class Vault {
    * @returns {Promise<{ hash: string, alreadyIngested: boolean }>}
    */
   async trackSource({ sourcePath, pagesCreated = [], pagesUpdated = [] }) {
+    return await this.withFileLock('__manifest__', async () => {
     const absolute = isAbsolute(sourcePath) ? sourcePath : join(this.root, sourcePath)
     const rel = relative(this.root, absolute).split(sep).join('/')
     const raw = await readFile(absolute).catch(error => {
@@ -455,6 +536,7 @@ export class Vault {
     await mkdir(join(manifestPath, '..'), { recursive: true })
     await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
     return { hash, alreadyIngested }
+    })
   }
 }
 

package/package.json

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