dsh-plugin-wiki-tools 0.7.0 → 0.8.0

package/index.js

@@ -16,6 +16,7 @@ import z from '@deepseek-ai/schemastery'
 import { Vault } from './lib/vault.js'
 import { quickView, searchVault } from './lib/search.js'
 import { lintVault } from './lib/lint.js'
+import { scaffoldVault, SCAFFOLD_MODES } from './lib/scaffold.js'
 
 export const name = 'wiki-tools'
 export const inject = ['tools']
@@ -215,6 +216,47 @@ export function createTools(vault, options = {}) {
     presentCall: args => ({ card: 'generic', title: `Rename wiki page: ${args.title} → ${args.new_title}`, kind: 'other', rawInput: { from: args.title, to: args.new_title } }),
   })
 
+  const wikiScaffold = defineTool({
+    name: 'wiki_scaffold',
+    description:
+      'Scaffold a wiki vault in one call: the chosen mode\u2019s folder structure with per-folder _index.md, '
+      + 'the core files (wiki/index.md, log.md, hot.md, overview.md), the mode\u2019s key seed pages, a raw-source '
+      + 'manifest, and the vault AGENTS.md conventions file. Idempotent — existing files are kept. Modes: '
+      + 'generic (matches wiki_write routing), sitemap, repository, business, personal, research, book. '
+      + 'The result carries a suggested typeFolders config for non-generic modes to paste into the profile.',
+    parameters: {
+      mode: {
+        type: 'string',
+        required: true,
+        enum: Object.keys(SCAFFOLD_MODES),
+        description: 'Scaffold mode; pick by what the vault is for (generic for a general knowledge base).',
+      },
+      purpose: {
+        type: 'string',
+        description: 'One-line vault purpose, written into overview.md and AGENTS.md.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: typeof value === 'object' && value !== null && 'created' in value
+          ? `wiki_scaffold (${value.mode}): created ${value.created.length} files, skipped ${value.skipped.length} existing`
+            + (Object.keys(value.suggestedTypeFolders ?? {}).length > 0
+              ? `; suggested typeFolders: ${JSON.stringify(value.suggestedTypeFolders)}`
+              : '')
+          : 'wiki_scaffold: failed',
+      }],
+    },
+    async execute(args) {
+      return await scaffoldVault(vault.root, args)
+    },
+    presentCall: args => ({ card: 'generic', title: `Scaffold wiki vault (${args.mode})`, kind: 'other', rawInput: { mode: args.mode } }),
+  })
+
   const wikiLint = defineTool({
     name: 'wiki_lint',
     description:
@@ -238,7 +280,7 @@ export function createTools(vault, options = {}) {
     presentCall: () => ({ card: 'generic', title: 'Lint wiki vault', kind: 'other' }),
   })
 
-  return [wikiQuery, wikiWrite, wikiRename, wikiLint]
+  return [wikiQuery, wikiWrite, wikiRename, wikiScaffold, wikiLint]
 }
 
 /**

package/lib/scaffold.js

@@ -0,0 +1,235 @@
+/**
+ * Vault scaffolding: the mechanical half of the wiki skill's SCAFFOLD
+ * operation as one call. Creates the mode's folder structure, the core wiki
+ * files (index, log, hot cache, overview), per-folder sub-indexes, the mode's
+ * key seed pages, the vault AGENTS.md conventions file, and the raw-source
+ * manifest. Idempotent: existing files are kept and reported as skipped.
+ *
+ * @module dsh-plugin-wiki-tools/lib/scaffold
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { today } from './vault.js'
+
+/**
+ * Folder sets per scaffold mode. `generic` matches the wiki_write routing
+ * (TYPE_FOLDERS); the six named modes follow the wiki skill's modes reference.
+ * `stubFolder` holds the mode's overview page; `stubs` are the key pages the
+ * mode's reference lists, each seeded into the folder named alongside it.
+ */
+export const SCAFFOLD_MODES = {
+  generic: {
+    label: 'Generic knowledge base',
+    folders: ['wiki/sources', 'wiki/entities', 'wiki/concepts', 'wiki/domains', 'wiki/questions', 'wiki/comparisons', 'wiki/meta'],
+    stubs: [],
+    typeFolders: {},
+  },
+  sitemap: {
+    label: 'Website / sitemap',
+    folders: ['wiki/pages', 'wiki/structure', 'wiki/audits', 'wiki/keywords', 'wiki/entities'],
+    stubs: [
+      { title: 'Site Overview', folder: 'wiki/structure', type: 'page' },
+      { title: 'Navigation Structure', folder: 'wiki/structure', type: 'page' },
+      { title: 'Content Gaps', folder: 'wiki/audits', type: 'page' },
+      { title: 'Redirect Map', folder: 'wiki/audits', type: 'page' },
+      { title: 'Keyword Clusters', folder: 'wiki/keywords', type: 'page' },
+    ],
+    typeFolders: { source: 'wiki/pages', entity: 'wiki/entities' },
+  },
+  repository: {
+    label: 'GitHub / repository',
+    folders: ['wiki/modules', 'wiki/components', 'wiki/decisions', 'wiki/dependencies', 'wiki/flows'],
+    stubs: [
+      { title: 'Architecture Overview', folder: 'wiki/modules', type: 'module' },
+      { title: 'Data Flow', folder: 'wiki/flows', type: 'flow' },
+      { title: 'Tech Stack', folder: 'wiki/dependencies', type: 'dependency' },
+      { title: 'Dependency Graph', folder: 'wiki/dependencies', type: 'dependency' },
+      { title: 'Key Decisions', folder: 'wiki/decisions', type: 'decision' },
+    ],
+    typeFolders: { source: 'wiki/modules', comparison: 'wiki/decisions' },
+  },
+  business: {
+    label: 'Business / project',
+    folders: ['wiki/stakeholders', 'wiki/decisions', 'wiki/deliverables', 'wiki/intel', 'wiki/comms'],
+    stubs: [
+      { title: 'Project Overview', folder: 'wiki/deliverables', type: 'deliverable' },
+      { title: 'Stakeholder Map', folder: 'wiki/stakeholders', type: 'stakeholder' },
+      { title: 'Decision Log', folder: 'wiki/decisions', type: 'decision' },
+      { title: 'Competitor Landscape', folder: 'wiki/intel', type: 'competitor' },
+    ],
+    typeFolders: { entity: 'wiki/stakeholders', source: 'wiki/comms', decision: 'wiki/decisions' },
+  },
+  personal: {
+    label: 'Personal / second brain',
+    folders: ['wiki/goals', 'wiki/learning', 'wiki/people', 'wiki/areas', 'wiki/resources'],
+    stubs: [
+      { title: 'North Star', folder: 'wiki/goals', type: 'goal' },
+      { title: 'Annual Goals', folder: 'wiki/goals', type: 'goal' },
+    ],
+    typeFolders: { concept: 'wiki/learning', domain: 'wiki/areas', entity: 'wiki/people', source: 'wiki/resources' },
+  },
+  research: {
+    label: 'Research',
+    folders: ['wiki/papers', 'wiki/concepts', 'wiki/entities', 'wiki/thesis', 'wiki/gaps'],
+    stubs: [
+      { title: 'Research Overview', folder: 'wiki/thesis', type: 'thesis' },
+      { title: 'Open Questions', folder: 'wiki/gaps', type: 'gap' },
+    ],
+    typeFolders: { source: 'wiki/papers', question: 'wiki/gaps', concept: 'wiki/concepts' },
+  },
+  book: {
+    label: 'Book / course',
+    folders: ['wiki/characters', 'wiki/themes', 'wiki/concepts', 'wiki/timeline', 'wiki/synthesis'],
+    stubs: [
+      { title: 'Book Overview', folder: 'wiki/timeline', type: 'chapter' },
+      { title: 'My Takeaways', folder: 'wiki/synthesis', type: 'synthesis' },
+    ],
+    typeFolders: { concept: 'wiki/concepts', question: 'wiki/synthesis' },
+  },
+}
+
+/**
+ * Scaffold one vault for a mode. Every artifact is written only when absent,
+ * so re-running after a partial scaffold or over an existing vault is safe.
+ * @param {string} root - absolute vault root.
+ * @param {object} input - scaffold options.
+ * @param {keyof typeof SCAFFOLD_MODES} input.mode - scaffold mode.
+ * @param {string} [input.purpose] - one-line vault purpose for overview and AGENTS.md.
+ * @returns {Promise<{ mode: string, created: string[], skipped: string[], suggestedTypeFolders: Record<string, string> }>}
+ */
+export async function scaffoldVault(root, { mode, purpose }) {
+  const spec = SCAFFOLD_MODES[mode]
+  if (spec === undefined) {
+    throw new Error(`wiki-tools: unknown scaffold mode "${mode}"; choose one of ${Object.keys(SCAFFOLD_MODES).join(', ')}`)
+  }
+  const date = today()
+  const created = []
+  const skipped = []
+  const writeIfAbsent = async (relPath, content) => {
+    const path = join(root, relPath)
+    if (await readFile(path, 'utf8').then(() => true, () => false)) {
+      skipped.push(relPath)
+      return
+    }
+    await mkdir(join(path, '..'), { recursive: true })
+    await writeFile(path, content, 'utf8')
+    created.push(relPath)
+  }
+
+  await writeIfAbsent('.raw/.manifest.json', '{"sources":{}}\n')
+  for (const folder of spec.folders) {
+    await writeIfAbsent(`${folder}/_index.md`, [
+      '---',
+      'type: meta',
+      `title: "${folder.split('/').pop()} Index"`,
+      `updated: ${date}`,
+      '---',
+      '',
+      `# ${folder.split('/').pop()}`,
+      '',
+    ].join('\n'))
+  }
+
+  await writeIfAbsent('wiki/index.md', indexTemplate(date))
+  await writeIfAbsent('wiki/log.md', `# Wiki Log\n`)
+  await writeIfAbsent('wiki/hot.md', [
+    '---',
+    'type: meta',
+    'title: "Hot Cache"',
+    `updated: ${date}`,
+    '---',
+    '',
+    '# Recent Context',
+    '',
+    `Scaffolded ${date}. ${purpose ?? spec.label}.`,
+    '',
+  ].join('\n'))
+  await writeIfAbsent('wiki/overview.md', [
+    '---',
+    'type: overview',
+    `title: "Overview"`,
+    `updated: ${date}`,
+    '---',
+    '',
+    '# Overview',
+    '',
+    purpose ?? spec.label,
+    '',
+  ].join('\n'))
+
+  for (const stub of spec.stubs) {
+    await writeIfAbsent(`${stub.folder}/${stub.title}.md`, [
+      '---',
+      `type: ${stub.type}`,
+      `title: "${stub.title}"`,
+      'status: seed',
+      `created: ${date}`,
+      `updated: ${date}`,
+      'tags:',
+      `  - ${stub.type}`,
+      '---',
+      '',
+      `# ${stub.title}`,
+      '',
+      `Seed page from ${mode} scaffold. Fill in.`,
+      '',
+    ].join('\n'))
+  }
+
+  await writeIfAbsent('AGENTS.md', agentsTemplate(mode, spec.label, purpose, date))
+
+  return { mode, created, skipped, suggestedTypeFolders: spec.typeFolders }
+}
+
+/**
+ * Master-index template with one empty section per generic type, in catalog
+ * order; named-mode vaults keep the same sections for their mapped types.
+ * @param {string} date - scaffold date.
+ * @returns {string} the index file content.
+ */
+function indexTemplate(date) {
+  const sections = ['Entities', 'Concepts', 'Sources', 'Questions']
+  return [
+    '---',
+    'type: meta',
+    'title: "Wiki Index"',
+    `updated: ${date}`,
+    '---',
+    '',
+    '# Wiki Index',
+    '',
+    ...sections.flatMap(section => [`## ${section}`, '']),
+  ].join('\n')
+}
+
+/**
+ * Vault conventions file: the rules every contributing agent follows.
+ * @param {string} mode - scaffold mode id.
+ * @param {string} label - human-readable mode label.
+ * @param {string | undefined} purpose - one-line vault purpose.
+ * @param {string} date - scaffold date.
+ * @returns {string} the AGENTS.md content.
+ */
+function agentsTemplate(mode, label, purpose, date) {
+  return `# Wiki Vault Conventions
+
+Mode: ${mode} (${label})
+Purpose: ${purpose ?? '(fill in)'}
+Created: ${date}
+
+## Rules
+
+- Every page uses flat YAML frontmatter: type, title, status, created, updated, tags at minimum.
+- status is one of seed | developing | mature | evergreen.
+- Wikilinks use [[Note Name]]; filenames are unique across the vault, no paths needed.
+- .raw/ holds immutable sources; never modify them.
+- wiki/index.md is the master catalog; every page is listed in its section.
+- wiki/log.md is append-only; new entries go at the TOP; never edit past entries.
+- wiki/hot.md is a ~500-word cache of recent context; overwrite it completely each update.
+- Prefer the wiki tools (wiki_query, wiki_write, wiki_rename, wiki_lint) over raw file edits;
+  they keep frontmatter, the index, the folder _index.md files, and the log consistent.
+- Contradictions between pages get > [!contradiction] callouts on both pages, never silent edits.
+`
+}

package/package.json

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