dsh-grove 0.2.0 → 0.5.0

package/src/server.js

@@ -2,12 +2,29 @@
 import { constants } from 'node:fs'
 import { access, realpath, stat } from 'node:fs/promises'
 import { isAbsolute, join, resolve } from 'node:path'
+import { captureInspiration, findInspirations, readInspiration } from './modules/inspirations.js'
+import { startResearch, listResearch, saveResearch } from './modules/research.js'
+import { importSource, saveEvidence, openSource } from './modules/evidence.js'
+import { listReports, confirmReport, readReport, draftFromFinding } from './modules/reports.js'
+import { runResearchModel } from './modules/model-research.js'
+import { listKnowledge, readKnowledge, saveKnowledge } from './modules/knowledge.js'
+import { listWorks, readWork, saveWork } from './modules/works.js'
 import { Vault } from './vault.js'
 
 export const routes = {
   status: '/api/grove/status',
   config: '/api/grove/config',
+  connection: '/api/grove/connection',
   capture: '/api/grove/capture',
+  model: '/api/grove/model',
+  findings: '/api/grove/findings',
+  knowledge: '/api/grove/knowledge',
+  works: '/api/grove/works',
+  reports: '/api/grove/reports',
+  parsers: '/api/grove/parsers',
+  sources: '/api/grove/sources',
+  research: '/api/grove/research',
+  inspirations: '/api/grove/inspirations',
 }
 
 /** Largest body the panel may post, matching the proposal limit. */
@@ -31,6 +48,9 @@ function statusOf(error) {
     case 'symlink':
     case 'invalid-body':
       return 400
+    case 'not-found':
+    case 'ENOENT':
+      return 404
     case 'not-configured':
       return 409
     case 'too-large':
@@ -57,6 +77,18 @@ export async function inspectVault(value) {
   return { path, looksLikeVault }
 }
 
+async function checkConnection(value) {
+  const candidate = await inspectVault(value)
+  const grove = await new Vault(candidate.path).folder().catch(error => {
+    if (error.code === 'ENOENT') return candidate.path
+    throw coded('invalid-path', 'The Grove directory is not usable')
+  })
+  await access(grove, constants.R_OK | constants.W_OK | constants.X_OK).catch(() => {
+    throw coded('invalid-path', 'The Grove directory must be readable and writable')
+  })
+  return candidate
+}
+
 /** Metadata the panel needs to choose between the cold-start and overview states. Never returns note bodies. */
 export async function vaultStatus(path, source) {
   const empty = {
@@ -105,7 +137,7 @@ export async function capture(vaultPath, input) {
   if (typeof body !== 'string' || body.trim() === '') throw coded('invalid-body', 'Write something first')
   if (Buffer.byteLength(body) > maxBody) throw coded('too-large', 'The note is too large')
   const vault = new Vault(vaultPath)
-  const note = await vault.create({ type: 'inspiration', body, title: input?.title })
+  const note = await captureInspiration(vault, { body, title: input?.title })
   const folder = await vault.folder()
   return {
     id: note.meta.id, type: note.meta.type, title: note.meta.title, version: 1,
@@ -160,10 +192,210 @@ export function registerRoutes(ctx, options) {
         return failure(error)
       }
     })
+    route(routes.inspirations, ['POST'], async request => {
+      try {
+        const input = await readJson(request)
+        const { path } = options.current()
+        if (!path) throw coded('not-configured', 'Grove has no vault yet')
+        const vault = new Vault(path)
+        if (input?.id !== undefined) {
+          if (typeof input.id !== 'string' || !/^[a-f0-9-]{36}$/.test(input.id) ||
+            (input.version !== undefined && (!Number.isSafeInteger(input.version) || input.version < 1))) {
+            throw coded('invalid-body', 'Invalid inspiration reference')
+          }
+          return json(await readInspiration(vault, input.id, input.version))
+        }
+        const query = typeof input?.query === 'string' ? input.query.trim() : ''
+        return json({ notes: (await findInspirations(vault, query)).slice(0, 50) })
+      } catch (error) {
+        return failure(error)
+      }
+    })
+    for (const [path, list, read, save] of [
+      [routes.knowledge, listKnowledge, readKnowledge, saveKnowledge],
+      [routes.works, listWorks, readWork, saveWork],
+    ]) {
+      route(path, ['POST'], async request => {
+        try {
+          const { path } = options.current()
+          if (!path) throw coded('not-configured', 'Grove has no vault yet')
+          const store = new Vault(path)
+          const input = await readJson(request)
+          if (input?.action === 'list') return json({ items: await list(store, typeof input.query === 'string' ? input.query : '') })
+          if (input?.action === 'read') return json(await read(store, input.id, input.version))
+          if (input?.action === 'save' && typeof input.body === 'string' && input.body.trim()) return json(await save(store, input))
+          throw coded('invalid-body', 'Choose an action and supply a body when saving')
+        } catch (error) {
+          return failure(error)
+        }
+      })
+    }
+    route(routes.model, ['GET', 'POST'], async request => {
+      if (request.method === 'GET') return json({ enabled: options.modelConfig?.enabled === true, endpoint: options.modelConfig?.endpoint, name: options.modelConfig?.name })
+      try {
+        const input = await readJson(request)
+        const model = input?.enabled === false ? { enabled: false } :
+          { enabled: true, endpoint: input?.endpoint, name: input?.name }
+        if (model.enabled) {
+          if (typeof model.endpoint !== 'string' || typeof model.name !== 'string' || !model.name.trim() ||
+            model.name.length > 200 || model.endpoint.length > 2048) throw coded('invalid-body', 'Enter the model endpoint and name')
+          const url = new URL(model.endpoint)
+          if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) {
+            throw coded('invalid-body', 'Use an HTTPS endpoint without embedded credentials')
+          }
+          if (input.test === true) {
+            const provider = options.model?.(model)
+            if (!provider) throw coded('invalid-body', 'Set GROVE_MODEL_KEY for the host')
+            const reply = await provider.investigate({ question: 'Confirm the connection. Return JSON.', materials: [], history: [] })
+            if (typeof reply?.text !== 'string' || !Array.isArray(reply.citations) || reply.citations.length) {
+              throw coded('invalid-body', 'The model did not return the expected format')
+            }
+            return json({ ok: true })
+          }
+        }
+        const editor = ctx.get?.('configEditor')
+        const entry = ctx.fiber?.entry
+        if (!entry || typeof editor?.edit !== 'function') throw coded('save-unavailable', 'This profile cannot save model settings')
+        setTimeout(() => {
+          editor.edit(entry, current => ({ ...current, model }))
+            .catch(error => console.warn(`[grove] could not save model settings: ${error.message}`))
+        }, delay)
+        return json({ pending: true })
+      } catch (error) {
+        return failure(error)
+      }
+    })
+    route(routes.findings, ['POST'], async request => {
+      try {
+        const { path } = options.current()
+        if (!path) throw coded('not-configured', 'Grove has no vault yet')
+        const store = new Vault(path)
+        const input = await readJson(request)
+        const findings = (await store.list()).filter(({ meta }) => meta.type === 'finding' &&
+          meta.links?.some(link => link.kind === 'related' && link.id === input?.id))
+        if (input?.action === 'list') return json({ findings })
+        const question = typeof input?.question === 'string' ? input.question.trim() : ''
+        if (!question || question.length > 1000 || !Array.isArray(input.materials) || input.materials.length > 20 ||
+          !Number.isSafeInteger(input.version) || input.version < 1) throw coded('invalid-body', 'Enter a research question and select evidence')
+        const provider = options.modelConfig?.enabled ? options.model?.(options.modelConfig) : null
+        if (!provider) throw coded('not-configured', 'Configure and enable a model first')
+        return json(await runResearchModel(store, provider, { ...input, question, history: input.includeHistory === true ? findings.map(({ meta, body }) => ({ question: meta.title, text: body })).slice(-8) : [] }))
+      } catch (error) {
+        return failure(error)
+      }
+    })
+    route(routes.parsers, ['GET', 'POST'], async request => {
+      if (request.method === 'GET') return json({ pdf: options.pdfEnabled !== false })
+      try {
+        const input = await readJson(request)
+        if (typeof input?.pdf !== 'boolean') throw coded('invalid-body', 'Choose whether PDF parsing is enabled')
+        const editor = ctx.get?.('configEditor')
+        const entry = ctx.fiber?.entry
+        if (!entry || typeof editor?.edit !== 'function') throw coded('save-unavailable', 'This profile cannot save parser settings')
+        setTimeout(() => {
+          editor.edit(entry, current => ({ ...current, parsers: { ...current.parsers, pdf: input.pdf } }))
+            .catch(error => console.warn(`[grove] could not save parser settings: ${error.message}`))
+        }, delay)
+        return json({ pending: true })
+      } catch (error) {
+        return failure(error)
+      }
+    })
+    route(routes.reports, ['POST'], async request => {
+      try {
+        const { path } = options.current()
+        if (!path) throw coded('not-configured', 'Grove has no vault yet')
+        const store = new Vault(path)
+        const input = await readJson(request)
+        if (input?.action === 'list') {
+          const notes = await store.list()
+          const sources = new Set(notes.filter(({ meta }) => meta.type === 'source' &&
+            meta.links?.some(link => link.kind === 'related' && link.id === input.research)).map(({ meta }) => meta.id))
+          const evidence = notes.filter(({ meta }) => meta.type === 'evidence' &&
+            meta.links?.some(link => link.kind === 'derived' && sources.has(link.id))).map(({ meta }) => meta)
+          return json({ reports: await listReports(store, input.research), evidence })
+        }
+        if (input?.action === 'draft' && Number.isSafeInteger(input.version) && input.version > 0) {
+          return json(await draftFromFinding(store, input.research, input.id, input.version))
+        }
+        if (input?.action === 'read') return json(await readReport(store, input.id, input.version))
+        if (input?.action === 'confirm' && typeof input.body === 'string' && input.body.trim() &&
+          (input.evidence === undefined || Array.isArray(input.evidence))) {
+          return json(await confirmReport(store, input))
+        }
+        throw coded('invalid-body', 'Choose a report action and nonempty report body')
+      } catch (error) {
+        return failure(error)
+      }
+    })
+    route(routes.sources, ['POST'], async request => {
+      try {
+        const { path } = options.current()
+        if (!path) throw coded('not-configured', 'Grove has no vault yet')
+        const vault = new Vault(path)
+        const input = await readJson(request)
+        if (input?.action === 'import') {
+          const name = input.name
+          const original = input.original
+          if (typeof name !== 'string' || !name.trim() || name.length > 256 ||
+            typeof original !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(original)) {
+            throw coded('invalid-body', 'Choose a Markdown or PDF file')
+          }
+          if (original.length > 700000) throw coded('too-large', 'File exceeds the import limit')
+          return json(await importSource(vault, options.parsers ?? new Map(), {
+            name, original, research: input.research, bytes: Buffer.from(original, 'base64'),
+          }))
+        }
+        if (input?.action === 'excerpt') {
+          return json(await saveEvidence(vault, { id: input.id, version: input.version }, input.index))
+        }
+        if (input?.action === 'open' && Number.isSafeInteger(input.version) && input.version > 0) {
+          return json(await openSource(vault, input.id, input.version))
+        }
+        if (input?.action === 'list') {
+          const notes = await vault.list()
+          return json({ sources: notes.filter(({ meta }) => meta.type === 'source' &&
+            meta.links?.some(link => link.kind === 'related' && link.id === input.research)).map(({ meta }) => meta) })
+        }
+        throw coded('invalid-body', 'Choose a source action')
+      } catch (error) {
+        return failure(error)
+      }
+    })
+    route(routes.research, ['GET', 'POST'], async request => {
+      try {
+        const { path } = options.current()
+        if (!path) throw coded('not-configured', 'Grove has no vault yet')
+        const vault = new Vault(path)
+        if (request.method === 'GET') return json({ studies: await listResearch(vault) })
+        const input = await readJson(request)
+        const body = typeof input?.body === 'string' ? input.body.trim() : ''
+        if (!body) throw coded('invalid-body', 'Write down your research notes')
+        if (input.id !== undefined) {
+          if (typeof input.id !== 'string' || !Number.isSafeInteger(input.version) || input.version < 1) {
+            throw coded('invalid-body', 'Invalid research version')
+          }
+          return json(await saveResearch(vault, input.id, input.version, body))
+        }
+        const question = typeof input.question === 'string' ? input.question.trim() : ''
+        if (!question || question.length > 300) throw coded('invalid-body', 'Enter a research question up to 300 characters')
+        const origin = input.origin ? (await readKnowledge(vault, input.origin.id, input.origin.version)).meta : undefined
+        return json(await startResearch(vault, question, body, origin))
+      } catch (error) {
+        return failure(error)
+      }
+    })
+    route(routes.connection, ['POST'], async request => {
+      try {
+        return json(await checkConnection((await readJson(request))?.path))
+      } catch (error) {
+        return failure(error)
+      }
+    })
     route(routes.config, ['POST'], async request => {
       let path
       try {
-        path = (await inspectVault((await readJson(request))?.path)).path
+        path = (await checkConnection((await readJson(request))?.path)).path
       } catch (error) {
         return failure(error)
       }

package/src/vault.js

@@ -4,7 +4,7 @@ import { lstat, realpath, mkdir, open, link, unlink, readdir } from 'node:fs/pro
 import { isAbsolute, join } from 'node:path'
 import { parse, stringify } from 'yaml'
 
-export const types = ['inspiration', 'question', 'concept', 'theory', 'claim', 'evidence', 'method', 'output', 'exploration', 'research']
+export const types = ['inspiration', 'question', 'concept', 'theory', 'claim', 'evidence', 'method', 'output', 'exploration', 'research', 'source', 'report', 'finding']
 export const stages = ['question', 'framework', 'evidence', 'analysis', 'judgment', 'validation', 'expression', 'review']
 const relations = ['related', 'derived', 'supports', 'refutes', 'qualifies']
 const validId = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/
@@ -94,6 +94,10 @@ export class Vault {
     return entries
   }
 
+  async versions(id) {
+    return ((await this.inventory()).get(id) ?? []).sort((a, b) => b - a)
+  }
+
   async get(id, version) {
     if (typeof id !== 'string' || !validId.test(id)) throw new Error('Invalid Grove ID')
     const selected = version ?? Math.max(...((await this.inventory()).get(id) ?? []))
@@ -127,11 +131,20 @@ export class Vault {
       meta.source = required(input.source, 'source')
       meta.locator = required(input.locator, 'locator')
     }
+    if (input.links !== undefined) meta.links = await this.resolveLinks(input.links)
     const path = await this.folder(true)
     await publish(path, join(path, `${id}.v1.md`), encode(meta, body))
     return { meta, body }
   }
 
+  async resolveLinks(links) {
+    return Promise.all(links.map(async link => {
+      if (!relations.includes(link.kind)) throw new Error('Invalid relationship')
+      const target = await this.get(link.id, link.version)
+      return { kind: link.kind, id: target.meta.id, version: target.meta.version }
+    }))
+  }
+
   async update(id, expected, change) {
     const note = await this.get(id)
     if (note.meta.version !== expected) throw new Error('Version conflict; read the latest note and retry')
@@ -153,6 +166,7 @@ export class Vault {
       if (meta.type !== 'research' || !stages.includes(change.stage)) throw new Error('Invalid research stage')
       meta.stage = change.stage
     }
+    if (change.links !== undefined) meta.links = await this.resolveLinks(change.links)
     if (change.link) {
       const { kind, id: targetId, version } = change.link
       if (!relations.includes(kind)) throw new Error('Invalid relationship')
@@ -166,6 +180,7 @@ export class Vault {
         meta.links = [...(meta.links ?? []), edge]
       }
     }
+    if (change.revisionReason !== undefined) meta.revisionReason = required(change.revisionReason, 'revision reason')
     meta.version++
     meta.modified = new Date().toISOString()
     const path = await this.folder()