md-annotator 0.5.1

package/server/index.js

@@ -0,0 +1,55 @@
+/**
+ * Express server with Promise-based decision flow.
+ * Waits for user to click Approve or Submit Feedback in the browser.
+ */
+
+import { startAnnotatorServer } from './annotator.js'
+import { config } from './config.js'
+
+// Re-export for plugin usage
+export { startAnnotatorServer } from './annotator.js'
+
+/**
+ * Create and start the annotation server (CLI compatibility wrapper).
+ * Accepts a single file path (string) or an array of file paths.
+ * Returns an object with port, waitForDecision(), and shutdown().
+ */
+export async function createServer(targetFilePaths, origin = 'cli', options = {}) {
+  const filePaths = Array.isArray(targetFilePaths) ? targetFilePaths : [targetFilePaths]
+  let resolveDecision
+
+  const server = await startAnnotatorServer({
+    filePaths,
+    origin,
+    feedbackNotes: options.feedbackNotes || null,
+  })
+
+  // Create a wrapper promise that can be resolved by signals
+  const decisionPromise = new Promise((resolve) => {
+    resolveDecision = resolve
+    // Forward the actual decision
+    server.waitForDecision().then(resolve)
+  })
+
+  // Shutdown handler
+  function shutdown() {
+    server.stop()
+    setTimeout(() => process.exit(1), config.forceExitTimeoutMs)
+  }
+
+  // Graceful shutdown on signals
+  process.on('SIGTERM', () => {
+    resolveDecision({ approved: true })
+    shutdown()
+  })
+  process.on('SIGINT', () => {
+    resolveDecision({ approved: true })
+    shutdown()
+  })
+
+  return {
+    port: server.port,
+    waitForDecision: () => decisionPromise,
+    shutdown,
+  }
+}

package/server/notes.js

@@ -0,0 +1,100 @@
+/**
+ * Convert feedback notes (from --feedback-notes) to annotation objects.
+ * Maps line-referenced notes to block IDs + offsets using the shared parser.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { parseMarkdownToBlocks } from '../client/src/utils/parser.js'
+
+/**
+ * Convert an array of notes into annotation objects for a single file.
+ *
+ * @param {Array<{text: string, line?: number}>} notes
+ * @param {string} markdownContent - The raw markdown file content
+ * @returns {Array<Object>} Annotation objects ready for the store
+ */
+export function convertNotesToAnnotations(notes, markdownContent) {
+  if (!Array.isArray(notes) || notes.length === 0) {
+    return []
+  }
+
+  const blocks = parseMarkdownToBlocks(markdownContent)
+  const contentLines = markdownContent.split('\n')
+
+  return notes
+    .filter(note => note && typeof note.text === 'string' && note.text.trim())
+    .map(note => {
+      if (note.line !== null && typeof note.line === 'number' && note.line > 0) {
+        return createLineAnnotation(note, blocks, contentLines)
+      }
+      return createGlobalAnnotation(note)
+    })
+}
+
+function createGlobalAnnotation(note) {
+  return {
+    id: randomUUID(),
+    blockId: '',
+    startOffset: 0,
+    endOffset: 0,
+    type: 'NOTES',
+    targetType: 'global',
+    text: note.text.trim(),
+    originalText: '',
+    createdAt: Date.now(),
+    startMeta: null,
+    endMeta: null
+  }
+}
+
+function createLineAnnotation(note, blocks, contentLines) {
+  const line = note.line
+  const block = findBlockForLine(blocks, line)
+
+  if (!block) {
+    // Fallback to global if line is out of range
+    return createGlobalAnnotation(note)
+  }
+
+  // Get the line content and compute offsets within the block
+  const lineContent = (line <= contentLines.length) ? contentLines[line - 1] : ''
+  const blockLines = block.content.split('\n')
+
+  // Find which line within the block corresponds to the target line
+  const lineWithinBlock = Math.min(line - block.startLine, blockLines.length - 1)
+  let startOffset = 0
+  for (let i = 0; i < lineWithinBlock && i < blockLines.length; i++) {
+    startOffset += blockLines[i].length + 1 // +1 for newline
+  }
+  const endOffset = startOffset + (blockLines[lineWithinBlock] || '').length
+
+  return {
+    id: randomUUID(),
+    blockId: block.id,
+    startOffset,
+    endOffset,
+    type: 'NOTES',
+    targetType: undefined,
+    text: note.text.trim(),
+    originalText: blockLines[lineWithinBlock] || lineContent,
+    createdAt: Date.now(),
+    startMeta: null,
+    endMeta: null
+  }
+}
+
+/**
+ * Find which block a given line number falls into.
+ * Blocks are sorted by startLine; we find the last block whose startLine <= line.
+ */
+function findBlockForLine(blocks, line) {
+  let matched = null
+  for (const block of blocks) {
+    if (block.startLine <= line) {
+      matched = block
+    } else {
+      break
+    }
+  }
+  return matched
+}

package/server/routes.js

@@ -0,0 +1,151 @@
+import { Router } from 'express'
+import { relative, resolve, dirname, isAbsolute } from 'node:path'
+import { createHash } from 'node:crypto'
+import { readMarkdownFile, isMarkdownFile } from './file.js'
+import { exportFeedback, exportMultiFileFeedback } from './feedback.js'
+
+function success(data) {
+  return { success: true, data }
+}
+
+function failure(error) {
+  return { success: false, error }
+}
+
+export function createApiRouter(filePaths, resolveDecision, origin = 'cli', stores = []) {
+  const router = Router()
+
+  // Multi-file endpoint — returns all files
+  router.get('/api/files', async (_req, res) => {
+    try {
+      const files = await Promise.all(
+        stores.map(async (store, index) => {
+          const content = await readMarkdownFile(store.absolutePath)
+          const relativePath = relative(process.cwd(), store.absolutePath) || store.absolutePath
+          const currentHash = createHash('sha256').update(content).digest('hex')
+          return {
+            index,
+            path: relativePath,
+            content,
+            contentHash: currentHash,
+            hashMismatch: currentHash !== store.contentHash
+          }
+        })
+      )
+      res.json(success({ files, origin }))
+    } catch (error) {
+      res.status(500).json(failure(error.message))
+    }
+  })
+
+  // Single-file endpoint — backward compat (returns first file)
+  router.get('/api/file', async (_req, res) => {
+    try {
+      const content = await readMarkdownFile(filePaths[0])
+      const relativePath = relative(process.cwd(), filePaths[0]) || filePaths[0]
+      res.json(success({
+        content,
+        path: relativePath,
+        origin,
+        contentHash: stores[0]?.contentHash || null
+      }))
+    } catch (error) {
+      res.status(500).json(failure(error.message))
+    }
+  })
+
+  // Open a linked file (linked navigation)
+  const baseDir = process.cwd()
+
+  router.get('/api/file/open', async (req, res) => {
+    const { path: requestedPath, relativeTo } = req.query
+    if (!requestedPath) {
+      return res.status(400).json(failure('path query parameter required'))
+    }
+
+    const referenceDir = relativeTo
+      ? dirname(resolve(baseDir, relativeTo))
+      : dirname(filePaths[0])
+    const absolutePath = resolve(referenceDir, requestedPath)
+
+    const rel = relative(baseDir, absolutePath)
+    if (rel.startsWith('..') || rel === '' || isAbsolute(rel)) {
+      return res.status(403).json(failure('Access denied: path outside project directory'))
+    }
+
+    if (!isMarkdownFile(absolutePath)) {
+      return res.status(400).json(failure('Not a markdown file'))
+    }
+
+    try {
+      const content = await readMarkdownFile(absolutePath)
+      const contentHash = createHash('sha256').update(content).digest('hex')
+      const relativePath = relative(baseDir, absolutePath) || absolutePath
+
+      let fileIndex = stores.findIndex(s => s.absolutePath === absolutePath)
+      if (fileIndex === -1) {
+        stores.push({ absolutePath, contentHash, annotations: [] })
+        fileIndex = stores.length - 1
+      }
+
+      res.json(success({ index: fileIndex, path: relativePath, content, contentHash }))
+    } catch (error) {
+      res.status(404).json(failure(error.message))
+    }
+  })
+
+  // Annotations: scoped by fileIndex query param (default 0)
+  router.get('/api/annotations', (req, res) => {
+    const fileIndex = parseInt(req.query.fileIndex, 10) || 0
+    const store = stores[fileIndex]
+    if (!store) {
+      return res.json(success({ annotations: [], contentHash: null }))
+    }
+    res.json(success({
+      annotations: store.annotations,
+      contentHash: store.contentHash
+    }))
+  })
+
+  router.post('/api/annotations', (req, res) => {
+    const { annotations, fileIndex = 0 } = req.body
+    const store = stores[fileIndex]
+    if (!store) {
+      return res.json(success({ saved: false }))
+    }
+    if (!Array.isArray(annotations)) {
+      return res.status(400).json(failure('annotations must be an array'))
+    }
+    store.annotations = [...annotations]
+    res.json(success({ saved: true, count: annotations.length }))
+  })
+
+  router.post('/api/approve', (_req, res) => {
+    res.json(success({ message: 'Approved' }))
+    setTimeout(() => resolveDecision({ approved: true }), 100)
+  })
+
+  router.post('/api/feedback', (req, res) => {
+    const { files, annotations, blocks } = req.body
+
+    // Multi-file format
+    if (Array.isArray(files)) {
+      const feedback = exportMultiFileFeedback(files)
+      const totalCount = files.reduce((sum, f) => sum + (f.annotations?.length || 0), 0)
+      res.json(success({ message: 'Feedback submitted' }))
+      setTimeout(() => resolveDecision({ approved: false, feedback, annotationCount: totalCount }), 100)
+      return
+    }
+
+    // Single-file backward compat
+    if (!Array.isArray(annotations) || !Array.isArray(blocks)) {
+      return res.status(400).json(failure('Request body must contain "files" array or "annotations" and "blocks" arrays'))
+    }
+
+    const feedback = exportFeedback(annotations, blocks)
+    res.json(success({ message: 'Feedback submitted' }))
+    setTimeout(() => resolveDecision({ approved: false, feedback, annotationCount: annotations.length }), 100)
+  })
+
+  return router
+}