dsh-plugin-wiki-tools 0.5.0 → 0.7.0

package/index.js

@@ -38,8 +38,8 @@ export const Config = z.object({
   }).default({}),
 })
 
-const PAGE_TYPES = ['source', 'entity', 'concept', 'domain', 'question', 'comparison', 'meta']
-const STATUSES = ['seed', 'developing', 'solid']
+const PAGE_TYPES = ['source', 'entity', 'concept', 'domain', 'question', 'synthesis', 'comparison', 'decision', 'session', 'meta']
+const STATUSES = ['seed', 'developing', 'mature', 'evergreen']
 
 /**
  * Build the three wiki tool definitions over one vault. Exported for tests.
@@ -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: {
@@ -123,12 +125,22 @@ export function createTools(vault, options = {}) {
       status: {
         type: 'string',
         enum: STATUSES,
-        description: 'Frontmatter status; defaults to developing (kept on update).',
+        description: 'Frontmatter status (seed | developing | mature | evergreen); defaults to developing (kept on update).',
       },
       summary: {
         type: 'string',
         description: 'One-line master-index entry; defaults to the first content line.',
       },
+      extra_frontmatter: {
+        type: 'object',
+        additionalProperties: true,
+        description:
+          'Flat schema fields to merge into frontmatter, e.g. related, sources, question, answer_quality '
+          + '(question/synthesis), entity_type/role (entity), complexity/domain/aliases (concept), '
+          + 'source_type/author/url/key_claims (source), subjects/dimensions/verdict (comparison), '
+          + 'decision_date (decision). Values are scalars or scalar lists; nesting is forbidden; '
+          + 'managed fields (type/title/status/created/updated/tags) are rejected.',
+      },
       source_path: {
         type: 'string',
         description: 'Vault-relative .raw/ source this page derives from, for delta tracking.',
@@ -160,11 +172,49 @@ export function createTools(vault, options = {}) {
           return { alreadyIngested: true, hash: tracked.hash, title: args.title }
         }
       }
-      return await vault.writePage(args)
+      const { extra_frontmatter: extraFrontmatter, ...rest } = args
+      return await vault.writePage({ ...rest, extraFrontmatter })
     },
     presentCall: args => ({ card: 'generic', title: `Write wiki page: ${args.title}`, kind: 'other', rawInput: { title: args.title, type: args.type } }),
   })
 
+  const wikiRename = defineTool({
+    name: 'wiki_rename',
+    description:
+      'Rename one wiki page and rewrite every [[wikilink]] to it across the vault (aliases and heading '
+      + 'anchors preserved), move the file to the new title, retitle its frontmatter, swap its master-index '
+      + 'and folder _index entries, and log the rename. The append-only log and dated lint reports keep the '
+      + 'old name as history. Use this instead of manual file renames, which strand every inbound link.',
+    parameters: {
+      title: {
+        type: 'string',
+        required: true,
+        description: 'Exact current page title.',
+      },
+      new_title: {
+        type: 'string',
+        required: true,
+        description: 'New title; also the new filename and [[wikilink]] target. Title Case with spaces.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: typeof value === 'object' && value !== null && 'to' in value
+          ? `wiki_rename: [[${value.from}]] → [[${value.to}]]; rewrote links in ${value.linksRewritten} files; page at ${value.path}`
+          : 'wiki_rename: failed',
+      }],
+    },
+    async execute(args) {
+      return await vault.renamePage({ title: args.title, newTitle: args.new_title })
+    },
+    presentCall: args => ({ card: 'generic', title: `Rename wiki page: ${args.title} → ${args.new_title}`, kind: 'other', rawInput: { from: args.title, to: args.new_title } }),
+  })
+
   const wikiLint = defineTool({
     name: 'wiki_lint',
     description:
@@ -188,7 +238,18 @@ export function createTools(vault, options = {}) {
     presentCall: () => ({ card: 'generic', title: 'Lint wiki vault', kind: 'other' }),
   })
 
-  return [wikiQuery, wikiWrite, wikiLint]
+  return [wikiQuery, wikiWrite, wikiRename, 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.`
 }
 
 /**

package/lib/vault.js

@@ -12,8 +12,8 @@
  */
 
 import { createHash } from 'node:crypto'
-import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises'
-import { basename, isAbsolute, join, relative, sep } from 'node:path'
+import { mkdir, 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'
 
 /** Page-type to vault folder routing (the suite's generic mode). */
@@ -24,6 +24,9 @@ export const TYPE_FOLDERS = {
   domain: 'wiki/domains',
   question: 'wiki/questions',
   comparison: 'wiki/comparisons',
+  synthesis: 'wiki/questions',
+  decision: 'wiki/meta',
+  session: 'wiki/meta',
   meta: 'wiki/meta',
 }
 
@@ -158,25 +161,29 @@ export class Vault {
 
   /**
    * Write one wiki page with complete bookkeeping: frontmatter completion,
-   * filename-uniqueness guard, master-index entry, and a log entry. Existing
-   * pages keep `created` and any unknown frontmatter fields; `updated` moves
-   * to today.
+   * filename-uniqueness guard, master-index entry, folder `_index.md` entry,
+   * and a log entry. Existing pages keep `created` and any unknown frontmatter
+   * fields; `updated` moves to today.
    * @param {object} input - the write request.
    * @param {string} input.type - page type (routed to a folder).
    * @param {string} input.title - page title; also the filename and wikilink target.
    * @param {string} input.content - markdown body after frontmatter.
    * @param {string[]} [input.tags] - frontmatter tags; defaults to `[type]`.
-   * @param {string} [input.status] - frontmatter status; defaults to `developing` on create.
+   * @param {string} [input.status] - frontmatter status; one of seed/developing/mature/evergreen.
    * @param {string} [input.summary] - one-line index entry; defaults to the first content line.
+   * @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 }>}
    */
-  async writePage({ type, title, content, tags, status, summary }) {
+  async writePage({ type, title, content, tags, status, summary, extraFrontmatter }) {
     const path = this.pagePath(type, title)
     return await this.enqueue(path, async () => {
       await this.assertRoot()
       const cleanTitle = title.endsWith('.md') ? title.slice(0, -3) : title
       const existing = await this.readPage(path)
       await this.assertUniqueFilename(cleanTitle, path)
+      validateExtraFrontmatter(extraFrontmatter)
       const date = today()
       const fields = {
         ...(existing?.fields ?? {}),
@@ -186,11 +193,13 @@ export class Vault {
         created: existing?.fields?.created ?? date,
         updated: date,
         tags: tags ?? existing?.fields?.tags ?? [type],
+        ...(extraFrontmatter ?? {}),
       }
       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}]]`,
       ])
@@ -198,6 +207,119 @@ export class Vault {
     })
   }
 
+  /**
+   * Add or refresh one entry in the owning folder's `_index.md` sub-index, the
+   * wiki-ingest contract's per-folder catalog. Missing files are created with
+   * a single `## <Type>` section; existing entries are replaced in place in
+   * the section's dominant separator style.
+   * @param {string} type - page type selecting folder and section label.
+   * @param {string} title - page title.
+   * @param {string} summary - one-line description.
+   */
+  async updateFolderIndex(type, title, summary) {
+    const folder = this.typeFolders[type]
+    const indexPath = join(this.root, folder, '_index.md')
+    const entryPattern = new RegExp(`^\\s*-?\\s*\\[\\[${escapeRegExp(title)}\\]\\]`)
+    let raw = await readFile(indexPath, 'utf8').catch(() => undefined)
+    if (raw === undefined) {
+      const heading = `## ${capitalize(type)}s`
+      const file = `---\ntype: meta\ntitle: "${capitalize(basename(folder))} Index"\nupdated: ${today()}\n---\n\n${heading}\n\n- [[${title}]]: ${summary.replace(/\n/g, ' ')}\n`
+      await writeFile(indexPath, file, 'utf8')
+      return
+    }
+    const lines = raw.split('\n')
+    const at = lines.findIndex(line => entryPattern.test(line))
+    const entry = `- [[${title}]]: ${summary.replace(/\n/g, ' ')}`
+    if (at >= 0) {
+      lines[at] = entry
+    } else {
+      let insert = lines.length
+      while (insert > 0 && lines[insert - 1].trim() === '') insert -= 1
+      lines.splice(insert, 0, entry)
+    }
+    const updatedLine = lines.findIndex(line => /^updated: /.test(line))
+    if (updatedLine >= 0) lines[updatedLine] = `updated: ${today()}`
+    await writeFile(indexPath, `${lines.join('\n')}\n`, 'utf8')
+  }
+
+  /**
+   * Rename one page and rewrite every wikilink to it across the vault:
+   * `[[Old]]` → `[[New]]`, preserving aliases (`[[Old|x]]` → `[[New|x]]`) and
+   * heading anchors. The append-only log and dated lint reports are historical
+   * records and keep the old name; frontmatter aliases keep resolving.
+   * @param {object} input - the rename request.
+   * @param {string} input.title - exact current page title.
+   * @param {string} input.newTitle - the new title and filename.
+   * @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 () => {
+      await this.assertRoot()
+      const cleanNew = newTitle.endsWith('.md') ? newTitle.slice(0, -3) : newTitle
+      if (!/^[^/\\]+(\.md)?$/.test(newTitle) || newTitle.includes('\n')) {
+        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 target = pages.find(page => page.name === title)
+      if (target === undefined) throw new Error(`wiki-tools: no page named "${title}" exists in the vault`)
+      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`)
+      }
+      const type = typeof target.fields?.type === 'string' && target.fields.type in this.typeFolders
+        ? target.fields.type
+        : 'meta'
+
+      // 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
+        const raw = await readFile(page.path, 'utf8').catch(() => undefined)
+        if (raw === undefined) continue
+        const pattern = new RegExp(`\\[\\[${escapeRegExp(title)}(\]\]|\||#)`, 'g')
+        const updated = raw.replace(pattern, `[[${cleanNew}$1`)
+        if (updated !== raw) {
+          await writeFile(page.path, updated, 'utf8')
+          rewritten.push(page.name)
+        }
+      }
+
+      // 2. Move the page and retitle its frontmatter.
+      const newPath = this.pagePath(type, cleanNew)
+      const oldRaw = await readFile(target.path, 'utf8')
+      const retitled = oldRaw.replace(/^(title:.*)$/m, `title: ${cleanNew}`)
+      await mkdir(dirname(newPath), { recursive: true })
+      await writeFile(newPath, retitled, 'utf8')
+      if (newPath !== target.path) await rm(target.path)
+
+      // 3. Swap index entries: drop the old lines, add the new.
+      await this.removeIndexEntries(title)
+      const summary = firstContentLine(splitFrontmatter(retitled, newPath).content)
+      await this.updateIndex(type, cleanNew, summary)
+      await this.updateFolderIndex(type, cleanNew, summary)
+      await this.prependLog(`## [${today()}] rename | ${title}`, [
+        `- Renamed: [[${title}]] → [[${cleanNew}]] (${rewritten.length} files' links rewritten)`,
+      ])
+      return { from: title, to: cleanNew, path: newPath, linksRewritten: rewritten.length, filesRewritten: rewritten }
+    })
+  }
+
+  /**
+   * Remove one page's entry lines from the master index and its folder
+   * `_index.md`, used when a rename replaces rather than refreshes.
+   * @param {string} title - page title whose entries are removed.
+   */
+  async removeIndexEntries(title) {
+    const pattern = new RegExp(`^\\s*-?\\s*\\[\\[${escapeRegExp(title)}\\]\\]`)
+    for (const indexPath of [join(this.root, 'wiki', 'index.md'), ...Object.values(this.typeFolders).map(folder => join(this.root, folder, '_index.md'))]) {
+      const raw = await readFile(indexPath, 'utf8').catch(() => undefined)
+      if (raw === undefined) continue
+      const lines = raw.split('\n')
+      const filtered = lines.filter(line => !pattern.test(line))
+      if (filtered.length !== lines.length) await writeFile(indexPath, `${filtered.join('\n')}\n`, 'utf8')
+    }
+  }
+
   /**
    * Reject a title whose filename already exists elsewhere in the tree:
    * wikilinks address pages by bare filename, so duplicates break resolution.
@@ -279,7 +401,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
@@ -325,6 +447,33 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
+/** Frontmatter fields writePage manages itself; extraFrontmatter cannot override them. */
+const MANAGED_FIELDS = new Set(['type', 'title', 'status', 'created', 'updated', 'tags'])
+
+/**
+ * Validate caller-supplied schema fields: flat mapping of primitives or lists
+ * of primitives (the vault schema forbids nesting for Obsidian's Properties UI).
+ * @param {Record<string, unknown> | undefined} extra - the extraFrontmatter input.
+ * @returns {void} throws on any violation.
+ */
+function validateExtraFrontmatter(extra) {
+  if (extra === undefined) return
+  if (typeof extra !== 'object' || extra === null || Array.isArray(extra)) {
+    throw new Error('wiki-tools: extraFrontmatter must be a flat object of schema fields')
+  }
+  for (const [key, value] of Object.entries(extra)) {
+    if (MANAGED_FIELDS.has(key)) {
+      throw new Error(`wiki-tools: extraFrontmatter cannot override managed field "${key}"`)
+    }
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      throw new Error(`wiki-tools: extraFrontmatter must stay flat; "${key}" is an object (the schema forbids nesting)`)
+    }
+    if (Array.isArray(value) && value.some(item => item !== null && typeof item === 'object')) {
+      throw new Error(`wiki-tools: extraFrontmatter list "${key}" may hold only scalars`)
+    }
+  }
+}
+
 /**
  * Pick the index separator for one entry: reuse the matched line's style, else
  * the section's dominant style (`: ` or ` — `), else the canonical colon.

package/package.json

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