dsh-plugin-wiki-tools 0.11.0 → 0.13.0

package/index.js

@@ -106,7 +106,9 @@ export function createTools(vault, options = {}) {
       + '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.',
+      + 'the ingest manifest and reports already_ingested for unchanged content unless force is set. '
+      + 'The result lists unresolved wikilinks in the written page (targets that match no page or alias) '
+      + 'so dead links are fixed at write time, not at the next lint.',
     parameters: {
       title: {
         type: 'string',
@@ -164,23 +166,19 @@ export function createTools(vault, options = {}) {
       },
       render: (args, value) => [{
         type: 'text',
-        text: typeof value === 'object' && value !== null && 'path' in value
-          ? `wiki_write: ${value.created ? 'created' : 'updated'} ${value.path}`
-          : `wiki_write: skipped ${args.title} (source unchanged)`,
+        text: typeof value === 'object' && value !== null && value.alreadyIngested === true
+          ? `wiki_write: skipped ${args.title} — source hash unchanged (pass force: true to re-ingest)`
+          : typeof value === 'object' && value !== null && 'path' in value
+            ? `wiki_write: ${value.created ? 'created' : 'updated'} ${value.path}`
+              + (Array.isArray(value.unresolvedLinks) && value.unresolvedLinks.length > 0
+                ? `\nwiki_write: note — ${value.unresolvedLinks.length} unresolved wikilink(s) in this page: ${value.unresolvedLinks.slice(0, 8).join(', ')}${value.unresolvedLinks.length > 8 ? ', …' : ''}. Create those pages or fix the targets; until then lint reports them as dead links.`
+                : '')
+            : `wiki_write: skipped ${args.title} (source unchanged)`,
       }],
     },
     async execute(args) {
-      if (args.source_path !== undefined) {
-        const tracked = await vault.trackSource({
-          sourcePath: args.source_path,
-          pagesCreated: [args.title],
-        })
-        if (tracked.alreadyIngested && args.force !== true) {
-          return { alreadyIngested: true, hash: tracked.hash, title: args.title }
-        }
-      }
-      const { extra_frontmatter: extraFrontmatter, ...rest } = args
-      return await vault.writePage({ ...rest, extraFrontmatter })
+      const { extra_frontmatter: extraFrontmatter, source_path: sourcePath, ...rest } = args
+      return await vault.writePage({ ...rest, extraFrontmatter, sourcePath })
     },
     presentCall: args => ({ card: 'generic', title: `Write wiki page: ${args.title}`, kind: 'other', rawInput: { title: args.title, type: args.type } }),
   })

package/lib/vault.js

@@ -76,6 +76,18 @@ export function today() {
   return new Date().toISOString().slice(0, 10)
 }
 
+/**
+ * Compare a stored manifest key against a normalized vault-relative path.
+ * Hand-written entries (the wiki-ingest skill era) may carry the platform's
+ * backslash separators; matching must not depend on them.
+ * @param {string} storedKey - key as written in `.raw/.manifest.json`.
+ * @param {string} rel - normalized `.raw/…` path.
+ * @returns {boolean}
+ */
+function sameSourceKey(storedKey, rel) {
+  return storedKey === rel || storedKey.replace(/\\/g, '/') === rel
+}
+
 /**
  * One vault root. All bookkeeping mutations go through {@link Vault.writePage},
  * which completes frontmatter, updates the master index, and prepends a log
@@ -277,9 +289,13 @@ export class Vault {
    * @param {Record<string, unknown>} [input.extraFrontmatter] - flat schema fields to merge
    *   (related, sources, question, answer_quality, entity_type, aliases, …); must stay flat and
    *   cannot override the managed fields.
-   * @returns {Promise<{ path: string, created: boolean, title: string }>}
+   * @param {string} [input.sourcePath] - vault-relative `.raw/` source this page derives from;
+   *   registers/refreshes the manifest entry (sha256 delta tracking) and returns `alreadyIngested`
+   *   without writing when the hash is unchanged.
+   * @param {boolean} [input.force] - with sourcePath, write even when the source hash is unchanged.
+   * @returns {Promise<{ path: string, created: boolean, title: string } | { alreadyIngested: true, title: string, sourceHash: string, detail: string }>}
    */
-  async writePage({ type, title, content, tags, status, summary, extraFrontmatter }) {
+  async writePage({ type, title, content, tags, status, summary, extraFrontmatter, sourcePath, force }) {
     const path = this.pagePath(type, title)
     return await this.enqueue(path, async () => await this.withFileLock(relative(this.root, path).split(sep).join('/'), async () => {
       await this.assertRoot()
@@ -290,6 +306,19 @@ export class Vault {
       if (status !== undefined && !PAGE_STATUSES.includes(status)) {
         throw new Error(`wiki-tools: status must be one of ${PAGE_STATUSES.join('/')} (got ${JSON.stringify(status)})`)
       }
+      // Source registration is mechanical bookkeeping, not model work: when the
+      // page summarizes a `.raw/` source, the manifest entry (sha256 delta
+      // tracking) is written by this tool, and an unchanged hash is rejected
+      // unless the caller forces a re-ingest.
+      if (sourcePath !== undefined) {
+        const { hash, alreadyIngested } = await this.inspectSource(sourcePath)
+        if (alreadyIngested && force !== true) {
+          return {
+            alreadyIngested: true, title: cleanTitle, sourceHash: hash,
+            detail: 'source hash unchanged; pass force: true to re-ingest, or omit source_path for a plain page write',
+          }
+        }
+      }
       const date = today()
       const fields = {
         ...(existing?.fields ?? {}),
@@ -310,7 +339,25 @@ export class Vault {
         `- ${existing === undefined ? 'Created' : 'Updated'}: [[${cleanTitle}]]`,
       ])
       this.gitCommit(`wiki: ${existing === undefined ? 'create' : 'update'} ${cleanTitle}`)
-      return { path, created: existing === undefined, title: cleanTitle }
+      if (sourcePath !== undefined) {
+        await this.trackSource({
+          sourcePath,
+          pagesCreated: existing === undefined ? [cleanTitle] : [],
+          pagesUpdated: existing === undefined ? [] : [cleanTitle],
+        })
+      }
+      // 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'))
+      const names = new Set(pagesNow.map(page => page.name))
+      const aliases = buildAliasMap(pagesNow)
+      const unresolvedLinks = [...new Set(extractWikilinks(content))]
+        .filter(target => resolveLinkTarget(target, names, aliases) === undefined)
+      return {
+        path, created: existing === undefined, title: cleanTitle,
+        ...(unresolvedLinks.length > 0 ? { unresolvedLinks } : {}),
+      }
     }))
   }
 
@@ -370,6 +417,9 @@ export class Vault {
       const pages = await collectMarkdown(join(this.root, 'wiki'))
       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)) {
+        throw new Error(`wiki-tools: "${title}" is vault machinery (index, log, hot cache, overview, sub-index, or lint report); renames would break conventions — fix the pages linking to it instead`)
+      }
       if (pages.some(page => page.name !== title && page.name.toLowerCase() === cleanNew.toLowerCase())) {
         throw new Error(`wiki-tools: filename "${cleanNew}.md" already exists; wikilinks need unique filenames`)
       }
@@ -443,7 +493,9 @@ export class Vault {
       await rm(absolute)
       const manifestPath = join(this.root, '.raw', '.manifest.json')
       const manifest = await readJson(manifestPath, { sources: {} })
-      delete manifest.sources[rel]
+      for (const key of Object.keys(manifest.sources)) {
+        if (sameSourceKey(key, rel)) delete manifest.sources[key]
+      }
       await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
       await this.prependLog(`## [${today()}] archive | ${rel}`, [
         `- Archived: \`${rel}\` → \`.archive/${rel.slice('.raw/'.length)}\``,
@@ -559,8 +611,13 @@ export class Vault {
     const hash = createHash('sha256').update(raw).digest('hex')
     const manifestPath = join(this.root, '.raw', '.manifest.json')
     const manifest = await readJson(manifestPath, { sources: {} })
-    const previous = manifest.sources[rel] ?? manifest.sources[sourcePath]
+    let previous
+    let twinKey
+    for (const [key, entry] of Object.entries(manifest.sources)) {
+      if (sameSourceKey(key, rel)) { previous = entry; twinKey = key; break }
+    }
     const alreadyIngested = previous !== undefined && previous.hash === hash
+    if (twinKey !== undefined && twinKey !== rel) delete manifest.sources[twinKey]
     manifest.sources[rel] = {
       hash,
       ingested_at: today(),
@@ -572,6 +629,31 @@ export class Vault {
     return { hash, alreadyIngested }
     })
   }
+
+  /**
+   * Hash one raw source and report whether the manifest already carries this
+   * exact hash — the wiki-ingest delta check's mechanical half.
+   * @param {string} sourcePath - vault-relative (or absolute) `.raw/` path.
+   * @returns {Promise<{ rel: string, hash: string, alreadyIngested: boolean }>}
+   */
+  async inspectSource(sourcePath) {
+    const absolute = isAbsolute(sourcePath) ? sourcePath : join(this.root, sourcePath)
+    const rel = relative(this.root, absolute).split(sep).join('/')
+    if (!rel.startsWith('.raw/')) {
+      throw new Error('wiki-tools: source_path must be a vault-relative path under .raw/')
+    }
+    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
+    })
+    const hash = createHash('sha256').update(raw).digest('hex')
+    const manifest = await readJson(join(this.root, '.raw', '.manifest.json'), { sources: {} })
+    let previous
+    for (const [key, entry] of Object.entries(manifest.sources)) {
+      if (sameSourceKey(key, rel)) { previous = entry; break }
+    }
+    return { rel, hash, alreadyIngested: previous !== undefined && previous.hash === hash }
+  }
 }
 
 /**
@@ -761,7 +843,12 @@ export function extractWikilinks(content) {
  * @returns {boolean} whether the page is machinery.
  */
 export function isMachineryPage(name) {
-  return META_FILENAMES.has(name.toLowerCase())
+  const lowered = name.toLowerCase()
+  return META_FILENAMES.has(lowered)
     || name.startsWith('_')
-    || /^lint-report-/.test(name)
+    || lowered.startsWith('_')
+    // Case-insensitive with a real boundary: reports have been hand-retitled
+    // to "Lint Report …" in real sessions, and those are still machinery —
+    // but "Lint Reporter Profile" is content.
+    || /^lint[- _]?report([- _].+)?$/i.test(name)
 }

package/package.json

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