dsh-plugin-wiki-tools 0.4.0 → 0.6.0

package/index.js

@@ -76,7 +76,7 @@ export function createTools(vault, options = {}) {
       },
       render: (_args, value) => [{
         type: 'text',
-        text: renderQueryResult(value),
+        text: `${renderVaultRoot(vault.root)}\n\n${renderQueryResult(value)}`,
       }],
     },
     async execute(args) {
@@ -95,7 +95,9 @@ export function createTools(vault, options = {}) {
     description:
       'Write or update one wiki page with full bookkeeping: routes the page to its type folder, '
       + 'completes YAML frontmatter (type, title, status, created, updated, tags), guards filename '
-      + 'uniqueness, updates the master index entry, and prepends a log entry. The content is the '
+      + 'uniqueness, updates the master index entry, and prepends a log entry. Writes go to the '
+      + 'CONFIGURED VAULT (run wiki_query to see its absolute root), not the session workspace. '
+      + 'The content is the '
       + 'markdown body only — frontmatter is managed. With source_path, records the source hash in '
       + 'the ingest manifest and reports already_ingested for unchanged content unless force is set.',
     parameters: {
@@ -191,6 +193,17 @@ export function createTools(vault, options = {}) {
   return [wikiQuery, wikiWrite, wikiLint]
 }
 
+/**
+ * Render a compact byline disclosing the vault root. Without it, a model whose
+ * session workspace differs from the vault resolves `.raw/…` against the
+ * workspace and concludes the tools point somewhere else.
+ * @param {string} root - absolute vault root.
+ * @returns {string} the byline.
+ */
+function renderVaultRoot(root) {
+  return `wiki vault: ${root} — every wiki tool (query, write, lint) operates on this configured vault, not the session workspace. Resolve vault-relative paths like .raw/… and wiki/… against this root.`
+}
+
 /**
  * Render a wiki_query result as the model-facing text. The render output is the
  * ONLY content the model sees, so it carries the full payload — hot cache and

package/lib/lint.js

@@ -8,7 +8,14 @@
 
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { collectMarkdown, isMachineryPage, splitFrontmatter, today } from './vault.js'
+import {
+  buildAliasMap,
+  collectMarkdown,
+  isMachineryPage,
+  resolveLinkTarget,
+  splitFrontmatter,
+  today,
+} from './vault.js'
 
 /** Frontmatter fields every content page must carry. */
 const REQUIRED_FIELDS = ['type', 'status', 'created', 'updated', 'tags']
@@ -98,19 +105,29 @@ async function checkStaleIndexEntries(root, pages, add) {
  * @param {Add} add - issue recorder.
  * @returns {Map<string, string[]>} inbound links per page title.
  */
+/**
+ * Wikilinks targeting pages that do not exist. Targets resolve through page
+ * titles first, then frontmatter `aliases` (Obsidian's order); only an
+ * unresolved target is dead.
+ * @param {Pages} pages - collected pages.
+ * @param {Add} add - issue recorder.
+ * @returns {Map<string, string[]>} inbound links per resolved page title.
+ */
 function checkDeadLinks(pages, add) {
   const names = new Set(pages.map(page => page.name))
+  const aliases = buildAliasMap(pages)
   const inbound = new Map(pages.map(page => [page.name, []]))
   for (const page of pages) {
     if (isMachineryPage(page.name)) continue
     for (const target of page.links) {
-      if (names.has(target)) {
-        inbound.get(target)?.push(page.name)
+      const resolved = resolveLinkTarget(target, names, aliases)
+      if (resolved !== undefined) {
+        inbound.get(resolved)?.push(page.name)
         continue
       }
       add('dead-link', 'error', page.name,
         `links to [[${target}]] which does not exist`,
-        'Create a stub page or remove the link')
+        'Create a stub page, add the target to a page\u2019s aliases, or remove the link')
     }
   }
   return inbound

package/lib/search.js

@@ -8,7 +8,7 @@
 
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { collectMarkdown, isMachineryPage } from './vault.js'
+import { buildAliasMap, collectMarkdown, isMachineryPage, resolveLinkTarget } from './vault.js'
 
 /**
  * Answer the quick mode: the hot cache and master index verbatim. The caller
@@ -43,17 +43,23 @@ export async function searchVault(root, { query, limit = 10 }) {
   // quick-mode payload, and dated lint reports quote past wikilinks as records,
   // not graph edges — so they neither appear as hits nor count as inbound.
   const searchable = pages.filter(page => !isMachineryPage(page.name))
+  const names = new Set(pages.map(page => page.name))
+  const aliases = buildAliasMap(pages)
   const inbound = new Map(pages.map(page => [page.name, []]))
   for (const page of searchable) {
-    // One inbound record per source page, however many times it links.
+    // One inbound record per source page, however many times it links; alias
+    // targets resolve to their owning page.
     for (const target of new Set(page.links)) {
-      inbound.get(target)?.push(page.name)
+      const resolved = resolveLinkTarget(target, names, aliases)
+      if (resolved !== undefined) inbound.get(resolved)?.push(page.name)
     }
   }
   const results = []
   let totalMatches = 0
   for (const page of searchable) {
-    const titleHits = countOccurrences(page.name.toLowerCase(), needle) * 5
+    const aliasText = (page.aliases ?? []).join(' ').toLowerCase()
+    const titleHits = (countOccurrences(page.name.toLowerCase(), needle)
+      + (aliasText.includes(needle) ? 1 : 0)) * 5
     const tags = Array.isArray(page.fields?.tags) ? page.fields.tags.join(' ').toLowerCase() : ''
     const tagHits = tags.includes(needle) ? 4 : 0
     const headings = page.content.split('\n').filter(line => line.startsWith('#')).join('\n').toLowerCase()

package/lib/vault.js

@@ -279,7 +279,7 @@ export class Vault {
    */
   async trackSource({ sourcePath, pagesCreated = [], pagesUpdated = [] }) {
     const absolute = isAbsolute(sourcePath) ? sourcePath : join(this.root, sourcePath)
-    const rel = relative(this.root, absolute)
+    const rel = relative(this.root, absolute).split(sep).join('/')
     const raw = await readFile(absolute).catch(error => {
       if (error.code === 'ENOENT') throw new Error(`wiki-tools: source ${sourcePath} not found under the vault`)
       throw error
@@ -382,12 +382,57 @@ export async function collectMarkdown(directory) {
         fields,
         content,
         links: extractWikilinks(content),
+        aliases: frontmatterAliases(fields),
       })
     }
   }
+  pages.sort((left, right) => left.name.localeCompare(right.name))
   return pages
 }
 
+/**
+ * Read a page's declared `aliases` frontmatter field (Obsidian resolves these
+ * as link targets): a string or list of strings.
+ * @param {Record<string, unknown> | undefined} fields - parsed frontmatter.
+ * @returns {string[]} declared aliases, empty when absent or malformed.
+ */
+function frontmatterAliases(fields) {
+  const raw = fields?.aliases
+  if (typeof raw === 'string') return raw.trim().length > 0 ? [raw.trim()] : []
+  if (Array.isArray(raw)) return raw.filter(alias => typeof alias === 'string' && alias.trim().length > 0).map(alias => alias.trim())
+  return []
+}
+
+/**
+ * Build the alias resolution map every link consumer shares: alias → page
+ * title. Earlier pages win a duplicate alias, deterministically, because
+ * {@link collectMarkdown} sorts by name.
+ * @param {{ name: string, aliases?: string[] }[]} pages - collected pages.
+ * @returns {Map<string, string>} alias → owning page title.
+ */
+export function buildAliasMap(pages) {
+  const map = new Map()
+  for (const page of pages) {
+    for (const alias of page.aliases ?? []) {
+      if (!map.has(alias)) map.set(alias, page.name)
+    }
+  }
+  return map
+}
+
+/**
+ * Resolve one wikilink target to a page title: direct name hit first, then the
+ * alias map (Obsidian's resolution order).
+ * @param {string} target - the raw link target.
+ * @param {Set<string>} names - every page title.
+ * @param {Map<string, string>} aliases - alias → page title.
+ * @returns {string | undefined} the resolved page title, or undefined when dead.
+ */
+export function resolveLinkTarget(target, names, aliases) {
+  if (names.has(target)) return target
+  return aliases.get(target)
+}
+
 /**
  * Extract wikilink targets from markdown, dropping aliases and heading anchors.
  * Fenced code blocks and inline code spans are not links: examples written as

package/package.json

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