dsh-plugin-wiki-tools 0.10.1 → 0.12.0

package/index.js

@@ -164,23 +164,16 @@ 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}`
+            : `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/lint.js

@@ -9,6 +9,7 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import {
+  PAGE_STATUSES,
   buildAliasMap,
   collectMarkdown,
   isMachineryPage,
@@ -37,6 +38,7 @@ export async function lintVault(root) {
   const inbound = checkDeadLinks(pages, add)
   checkOrphans(pages, inbound, indexed, add)
   checkFrontmatterGaps(pages, add)
+  checkStatusVocabulary(pages, add)
   checkEmptySections(pages, add)
   await checkHotCacheStaleness(root, pages, add)
 
@@ -172,6 +174,25 @@ function checkFrontmatterGaps(pages, add) {
   }
 }
 
+/**
+ * Status values outside the lifecycle vocabulary (seed/developing/mature/
+ * evergreen). A stray value silently breaks status-based queries and
+ * promotion flows, so it is flagged even though links stay intact.
+ * @param {Pages} pages - collected pages.
+ * @param {Add} add - issue recorder.
+ */
+function checkStatusVocabulary(pages, add) {
+  for (const page of pages) {
+    if (isMachineryPage(page.name)) continue
+    const status = page.fields?.status
+    if (typeof status === 'string' && !PAGE_STATUSES.includes(status)) {
+      add('status-vocabulary', 'warn', page.name,
+        `status "${status}" is outside the lifecycle vocabulary (${PAGE_STATUSES.join('/')})`,
+        `Set status to one of ${PAGE_STATUSES.join('/')}`)
+    }
+  }
+}
+
 /**
  * Headings with no content before the next heading.
  * @param {Pages} pages - collected pages.

package/lib/vault.js

@@ -32,6 +32,9 @@ export const TYPE_FOLDERS = {
   meta: 'wiki/meta',
 }
 
+/** Lifecycle status vocabulary; writePage rejects anything else and lint flags it. */
+export const PAGE_STATUSES = ['seed', 'developing', 'mature', 'evergreen']
+
 /** Master-index section headings follow the mapped folder basename, computed per vault. */
 
 /**
@@ -73,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
@@ -274,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()
@@ -284,6 +303,22 @@ export class Vault {
       const existing = await this.readPage(path)
       await this.assertUniqueFilename(cleanTitle, path)
       validateExtraFrontmatter(extraFrontmatter)
+      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 ?? {}),
@@ -304,6 +339,13 @@ export class Vault {
         `- ${existing === undefined ? 'Created' : 'Updated'}: [[${cleanTitle}]]`,
       ])
       this.gitCommit(`wiki: ${existing === undefined ? 'create' : 'update'} ${cleanTitle}`)
+      if (sourcePath !== undefined) {
+        await this.trackSource({
+          sourcePath,
+          pagesCreated: existing === undefined ? [cleanTitle] : [],
+          pagesUpdated: existing === undefined ? [] : [cleanTitle],
+        })
+      }
       return { path, created: existing === undefined, title: cleanTitle }
     }))
   }
@@ -437,7 +479,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)}\``,
@@ -553,8 +597,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(),
@@ -566,6 +615,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 }
+  }
 }
 
 /**

package/package.json

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