md-annotator 0.5.1

package/index.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+import { resolve } from 'node:path'
+import { readFileSync } from 'node:fs'
+import { createServer } from './server/index.js'
+import { isMarkdownFile, fileExists } from './server/file.js'
+import { openBrowser } from './server/browser.js'
+
+const HELP_TEXT = `
+md-annotator — Annotate Markdown files in the browser
+
+Usage:
+  md-annotator [options] <file.md> [file2.md ...]
+
+Options:
+  --help                       Show this help message
+  --origin <name>              Set caller origin (cli, claude-code, opencode)
+  --feedback-notes <json|path> AI notes to display as read-only annotations
+
+Environment:
+  MD_ANNOTATOR_PORT      Base port (default: 3000)
+  MD_ANNOTATOR_BROWSER   Custom browser app name
+  MD_ANNOTATOR_TIMEOUT   Heartbeat timeout in ms (default: 30000, range: 5000–300000)
+
+Examples:
+  md-annotator README.md
+  md-annotator docs/api.md docs/guide.md
+  md-annotator --feedback-notes '[{"text":"Rewrote intro","line":5}]' README.md
+  md-annotator --feedback-notes notes.json README.md
+`.trim()
+
+function parseFeedbackNotes(value) {
+  const trimmed = value.trim()
+  let parsed
+  if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+    parsed = JSON.parse(trimmed)
+  } else {
+    // Treat as file path
+    const content = readFileSync(resolve(value), 'utf-8')
+    parsed = JSON.parse(content)
+  }
+  if (!Array.isArray(parsed) && (typeof parsed !== 'object' || parsed === null)) {
+    throw new Error('Expected a JSON array or object')
+  }
+  return parsed
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2)
+
+  if (args.includes('--help') || args.includes('-h')) {
+    return { help: true }
+  }
+
+  const validOrigins = ['cli', 'claude-code', 'opencode']
+  let origin = 'cli'
+  let feedbackNotes = null
+  const filePaths = []
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--origin') {
+      if (!args[i + 1] || args[i + 1].startsWith('-')) {
+        return { error: '--origin requires a value (cli, claude-code, opencode)' }
+      }
+      origin = args[i + 1]
+      i++
+    } else if (args[i] === '--feedback-notes') {
+      if (!args[i + 1]) {
+        return { error: '--feedback-notes requires a JSON string or file path' }
+      }
+      const value = args[i + 1]
+      i++
+      try {
+        feedbackNotes = parseFeedbackNotes(value)
+      } catch (err) {
+        return { error: `--feedback-notes: ${err.message}` }
+      }
+    } else if (!args[i].startsWith('-')) {
+      filePaths.push(args[i])
+    } else {
+      return { error: `Unknown option: ${args[i]}` }
+    }
+  }
+
+  if (!validOrigins.includes(origin)) {
+    return { error: `Unknown origin "${origin}". Valid: ${validOrigins.join(', ')}` }
+  }
+
+  return { filePaths, origin, feedbackNotes }
+}
+
+async function main() {
+  const { help, filePaths, origin, feedbackNotes, error } = parseArgs(process.argv)
+
+  if (error) {
+    process.stderr.write(`Error: ${error}\n\n`)
+    process.stderr.write(HELP_TEXT + '\n')
+    process.exit(1)
+  }
+
+  if (help) {
+    process.stderr.write(HELP_TEXT + '\n')
+    process.exit(0)
+  }
+
+  if (!filePaths || filePaths.length === 0) {
+    process.stderr.write('Error: No file specified.\n\n')
+    process.stderr.write(HELP_TEXT + '\n')
+    process.exit(1)
+  }
+
+  const absolutePaths = []
+  for (const fp of filePaths) {
+    const abs = resolve(fp)
+    if (!isMarkdownFile(abs)) {
+      process.stderr.write(`Error: Not a Markdown file: ${fp}\n`)
+      process.exit(1)
+    }
+    if (!(await fileExists(abs))) {
+      process.stderr.write(`Error: File not found: ${abs}\n`)
+      process.exit(1)
+    }
+    absolutePaths.push(abs)
+  }
+
+  const server = await createServer(absolutePaths, origin, { feedbackNotes })
+  const url = `http://localhost:${server.port}`
+
+  process.stderr.write(`Server running at ${url}\n`)
+  process.stderr.write(`Annotating: ${absolutePaths.join(', ')}\n`)
+
+  await openBrowser(url)
+
+  // Block until user clicks Approve or Submit Feedback (or browser disconnects)
+  const decision = await server.waitForDecision()
+
+  // Handle browser disconnect (no need to wait for browser)
+  if (decision.disconnected) {
+    process.stderr.write('Browser tab closed — no decision made.\n')
+    server.shutdown()
+    process.exit(1)
+  }
+
+  // Give browser time to receive response
+  await new Promise(r => setTimeout(r, 500))
+
+  // Log decision to stderr
+  if (decision.approved) {
+    process.stderr.write('Decision: Approved (no changes)\n')
+  } else {
+    process.stderr.write(`Decision: Feedback with ${decision.annotationCount} annotation(s)\n`)
+  }
+
+  // Output feedback to stdout — this is what Claude reads
+  const output = decision.approved
+    ? 'APPROVED: No changes requested.\n'
+    : decision.feedback + '\n'
+
+  process.stdout.write(output, () => {
+    server.shutdown()
+    process.exit(0)
+  })
+}
+
+main().catch((error) => {
+  process.stderr.write(`Fatal: ${error.message}\n`)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "md-annotator",
+  "version": "0.5.1",
+  "description": "Browser-based Markdown annotator for AI-assisted review",
+  "type": "module",
+  "bin": {
+    "md-annotator": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "server",
+    "client/dist"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "dev": "node --watch index.js",
+    "build": "vite build",
+    "prepack": "npm run build",
+    "dev:client": "vite dev",
+    "lint": "eslint . && stylelint '**/*.css'",
+    "lint:js": "eslint .",
+    "lint:css": "stylelint '**/*.css'",
+    "lint:fix": "eslint . --fix && stylelint '**/*.css' --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "markdown",
+    "annotator",
+    "editor",
+    "ai",
+    "claude"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "cors": "^2.8.5",
+    "dompurify": "^3.3.1",
+    "express": "^4.21.0",
+    "highlight.js": "^11.11.0",
+    "mermaid": "^11.12.3",
+    "open": "^10.1.0",
+    "portfinder": "^1.0.32",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "web-highlighter": "^0.7.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@vitejs/plugin-react": "^4.3.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "globals": "^17.2.0",
+    "stylelint": "^17.0.0",
+    "stylelint-config-standard": "^40.0.0",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.0.3",
+    "vitest": "^4.0.18"
+  }
+}

package/server/annotator.js

@@ -0,0 +1,171 @@
+/**
+ * Annotator server module.
+ * Provides startAnnotatorServer() for both CLI and plugin usage.
+ */
+
+import { existsSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import express from 'express'
+import cors from 'cors'
+import portfinder from 'portfinder'
+import { config } from './config.js'
+import { createApiRouter } from './routes.js'
+import { readMarkdownFile } from './file.js'
+import { convertNotesToAnnotations } from './notes.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const DIST_PATH = join(__dirname, '..', 'client', 'dist')
+const DEV_PATH = join(__dirname, '..', 'client')
+
+/**
+ * Resolve notes for a specific file from the feedbackNotes array.
+ * Notes apply to the first file only (multi-file uses one invocation per file).
+ */
+function resolveNotesForFile(feedbackNotes, fileIndex, content) {
+  if (!Array.isArray(feedbackNotes) || fileIndex !== 0) {
+    return []
+  }
+  return convertNotesToAnnotations(feedbackNotes, content)
+}
+
+/**
+ * Start the annotator server with configurable options.
+ *
+ * @param {Object} options - Server configuration
+ * @param {string} [options.filePath] - Absolute path to markdown file (single-file compat)
+ * @param {string[]} [options.filePaths] - Array of absolute paths to markdown files
+ * @param {string} [options.origin='cli'] - Origin identifier ('cli' | 'claude-code' | 'opencode')
+ * @param {string} [options.htmlContent] - Embedded HTML content (for plugin usage)
+ * @param {Function} [options.onReady] - Callback when server is ready: (url, port) => void
+ * @returns {Promise<Object>} Server control object
+ */
+export async function startAnnotatorServer(options) {
+  const {
+    filePath,
+    filePaths: filePathsOpt,
+    origin = 'cli',
+    htmlContent = null,
+    onReady = null,
+    feedbackNotes = null,
+  } = options
+
+  const filePaths = filePathsOpt || (filePath ? [filePath] : [])
+
+  const app = express()
+
+  // Middleware
+  app.use(cors())
+  app.use(express.json({ limit: config.jsonLimit }))
+
+  // Serve static files or embedded HTML
+  if (htmlContent) {
+    // Plugin mode: serve embedded HTML
+    app.get('/', (_req, res) => {
+      res.type('html').send(htmlContent)
+    })
+  } else {
+    // CLI mode: serve from disk
+    const clientPath = existsSync(DIST_PATH) ? DIST_PATH : DEV_PATH
+    app.use(express.static(clientPath))
+  }
+
+  // Serve static files from markdown file directories (for relative images, etc.)
+  const servedDirs = new Set()
+  for (const fp of filePaths) {
+    const dir = dirname(fp)
+    if (!servedDirs.has(dir)) {
+      servedDirs.add(dir)
+      app.use(express.static(dir))
+    }
+  }
+
+  // Fallback: also serve from cwd for absolute-style paths
+  if (!servedDirs.has(process.cwd())) {
+    app.use(express.static(process.cwd()))
+  }
+
+  // Health check
+  app.get('/health', (_req, res) => {
+    res.json({ status: 'ok' })
+  })
+
+  // Client heartbeat — detect browser tab close
+  let lastHeartbeat = 0
+  let heartbeatReceived = false
+
+  app.post('/api/heartbeat', (_req, res) => {
+    lastHeartbeat = Date.now()
+    heartbeatReceived = true
+    res.json({ status: 'ok' })
+  })
+
+  // Compute content hash per file for annotation persistence
+  const stores = await Promise.all(
+    filePaths.map(async (fp, index) => {
+      try {
+        const content = await readMarkdownFile(fp)
+        const contentHash = createHash('sha256').update(content).digest('hex')
+        const notes = resolveNotesForFile(feedbackNotes, index, content)
+        return { absolutePath: fp, contentHash, annotations: notes }
+      } catch (_e) {
+        return { absolutePath: fp, contentHash: null, annotations: [] }
+      }
+    })
+  )
+
+  // Decision promise with guard against double resolution
+  let resolveDecision
+  let decided = false
+  const decisionPromise = new Promise((resolve) => {
+    resolveDecision = resolve
+  })
+
+  function safeResolve(value) {
+    if (decided) {return}
+    decided = true
+    resolveDecision(value)
+  }
+
+  // API routes with multi-file support
+  app.use(createApiRouter(filePaths, safeResolve, origin, stores))
+
+  // Find available port
+  portfinder.basePort = config.port
+  const port = await portfinder.getPortPromise()
+
+  // Start server
+  const server = await new Promise((resolve) => {
+    const s = app.listen(port, () => resolve(s))
+  })
+
+  const url = `http://localhost:${port}`
+
+  // Call onReady callback if provided
+  if (onReady) {
+    onReady(url, port)
+  }
+
+  // Heartbeat monitor — resolve as disconnected if client goes silent
+  const heartbeatInterval = setInterval(() => {
+    if (heartbeatReceived && Date.now() - lastHeartbeat > config.heartbeatTimeoutMs) {
+      clearInterval(heartbeatInterval)
+      safeResolve({ disconnected: true })
+    }
+  }, 5000)
+  heartbeatInterval.unref()
+
+  // Stop function
+  function stop() {
+    clearInterval(heartbeatInterval)
+    server.close()
+  }
+
+  return {
+    port,
+    url,
+    waitForDecision: () => decisionPromise,
+    stop,
+  }
+}

package/server/browser.js

@@ -0,0 +1,20 @@
+/**
+ * Cross-platform browser opening utility.
+ */
+
+import open from 'open'
+import { config } from './config.js'
+
+/**
+ * Open URL in the user's default browser.
+ * Optionally uses MD_ANNOTATOR_BROWSER environment variable.
+ */
+export async function openBrowser(url) {
+  const options = config.browser ? { app: { name: config.browser } } : {}
+
+  try {
+    await open(url, options)
+  } catch {
+    // Silent failure — browser opening is best-effort
+  }
+}

package/server/config.js

@@ -0,0 +1,36 @@
+/**
+ * Centralized configuration from environment variables.
+ */
+
+const DEFAULT_PORT = 3000
+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 30_000
+
+function getServerPort() {
+  const envPort = process.env.MD_ANNOTATOR_PORT
+  if (envPort) {
+    const parsed = parseInt(envPort, 10)
+    if (!isNaN(parsed) && parsed > 0 && parsed < 65536) {
+      return parsed
+    }
+  }
+  return DEFAULT_PORT
+}
+
+function getHeartbeatTimeoutMs() {
+  const envTimeout = process.env.MD_ANNOTATOR_TIMEOUT
+  if (envTimeout) {
+    const parsed = parseInt(envTimeout, 10)
+    if (!isNaN(parsed) && parsed >= 5000 && parsed <= 300_000) {
+      return parsed
+    }
+  }
+  return DEFAULT_HEARTBEAT_TIMEOUT_MS
+}
+
+export const config = {
+  port: getServerPort(),
+  browser: process.env.MD_ANNOTATOR_BROWSER || null,
+  heartbeatTimeoutMs: getHeartbeatTimeoutMs(),
+  forceExitTimeoutMs: 5000,
+  jsonLimit: '10mb',
+}

package/server/feedback.js

@@ -0,0 +1,156 @@
+/**
+ * Format a single annotation as Markdown feedback.
+ */
+function formatAnnotation(ann, block, heading) {
+  const blockStartLine = block?.startLine || 1
+
+  // Element-level annotations (image or diagram)
+  if (ann.targetType === 'image') {
+    const isDeletion = ann.type === 'DELETION'
+    const label = isDeletion ? 'Remove image' : 'Comment on image'
+    let output = `${heading} ${label} (Line ${blockStartLine})\n`
+    output += `Image: \`${ann.originalText}\`\n`
+    if (ann.imageAlt) { output += `Alt text: "${ann.imageAlt}"\n` }
+    if (ann.imageSrc) { output += `Source: ${ann.imageSrc}\n` }
+    if (isDeletion) {
+      output += `> User wants this image removed from the document.\n`
+    } else {
+      output += `> ${(ann.text ?? '').replace(/\n/g, '\n> ')}\n`
+    }
+    return output + '\n'
+  }
+
+  if (ann.targetType === 'diagram') {
+    const isDeletion = ann.type === 'DELETION'
+    const label = isDeletion ? 'Remove Mermaid diagram' : 'Comment on Mermaid diagram'
+    let output = `${heading} ${label} (Line ${blockStartLine})\n`
+    output += `\`\`\`mermaid\n${block?.content || ann.originalText}\n\`\`\`\n`
+    if (isDeletion) {
+      output += `> User wants this diagram removed from the document.\n`
+    } else {
+      output += `> ${(ann.text ?? '').replace(/\n/g, '\n> ')}\n`
+    }
+    return output + '\n'
+  }
+
+  const blockContent = block?.content || ''
+  const textBeforeSelection = blockContent.slice(0, ann.startOffset)
+  const linesBeforeSelection = (textBeforeSelection.match(/\n/g) || []).length
+  const startLine = blockStartLine + linesBeforeSelection
+  const newlinesInSelection = (ann.originalText.match(/\n/g) || []).length
+  const endLine = startLine + newlinesInSelection
+  const lineRef = startLine === endLine ? `Line ${startLine}` : `Lines ${startLine}-${endLine}`
+
+  let output = `${heading} `
+
+  if (ann.type === 'DELETION') {
+    output += `Remove this (${lineRef})\n`
+    output += `\`\`\`\n${ann.originalText}\n\`\`\`\n`
+    output += `> User wants this removed from the document.\n`
+  } else if (ann.type === 'COMMENT') {
+    output += `Comment on (${lineRef})\n`
+    output += `\`\`\`\n${ann.originalText}\n\`\`\`\n`
+    output += `> ${ann.text.replace(/\n/g, '\n> ')}\n`
+  } else if (ann.type === 'INSERTION') {
+    output += `Insert text (${lineRef})\n`
+    if (ann.afterContext) {
+      output += `After: \`${ann.afterContext}\`\n`
+    }
+    output += `\`\`\`\n${ann.text}\n\`\`\`\n`
+    output += `> User wants this text inserted at this point in the document.\n`
+  }
+
+  return output + '\n'
+}
+
+function sortAnnotations(annotations, blocks) {
+  return [...annotations].sort((a, b) => {
+    const blockA = blocks.findIndex(blk => blk.id === a.blockId)
+    const blockB = blocks.findIndex(blk => blk.id === b.blockId)
+    if (blockA !== blockB) {return blockA - blockB}
+    return a.startOffset - b.startOffset
+  })
+}
+
+/**
+ * Format annotations from multiple files as readable Markdown feedback.
+ * Single file delegates to exportFeedback. Multi-file groups by file.
+ */
+export function exportMultiFileFeedback(files) {
+  // Exclude NOTES (read-only AI notes) from feedback
+  const filesFiltered = files.map(f => ({
+    ...f,
+    annotations: (f.annotations || []).filter(a => a.type !== 'NOTES')
+  }))
+  const filesWithAnnotations = filesFiltered.filter(f => f.annotations.length > 0)
+
+  if (filesWithAnnotations.length === 0) {
+    return 'No annotations.'
+  }
+
+  if (filesWithAnnotations.length === 1) {
+    return exportFeedback(filesWithAnnotations[0].annotations, filesWithAnnotations[0].blocks)
+  }
+
+  const totalCount = filesWithAnnotations.reduce((sum, f) => sum + f.annotations.length, 0)
+  let output = `# Annotation Feedback\n\n`
+  output += `${totalCount} annotation${totalCount > 1 ? 's' : ''} across ${filesWithAnnotations.length} file${filesWithAnnotations.length > 1 ? 's' : ''}:\n\n`
+
+  let globalIndex = 1
+  for (const file of filesWithAnnotations) {
+    output += `---\n\n## File: ${file.path}\n\n`
+    const sorted = sortAnnotations(file.annotations, file.blocks)
+    const globalComments = sorted.filter(a => a.targetType === 'global')
+    const regularAnnotations = sorted.filter(a => a.targetType !== 'global')
+
+    if (globalComments.length > 0) {
+      output += `### General Feedback\n\n`
+      globalComments.forEach(ann => {
+        output += `> ${(ann.text ?? '').replace(/\n/g, '\n> ')}\n\n`
+      })
+    }
+
+    for (const ann of regularAnnotations) {
+      const block = file.blocks.find(blk => blk.id === ann.blockId)
+      output += formatAnnotation(ann, block, `### ${globalIndex}.`)
+      globalIndex++
+    }
+  }
+
+  output += '---\n'
+  return output
+}
+
+/**
+ * Format annotations as readable Markdown feedback for Claude.
+ */
+export function exportFeedback(annotations, blocks) {
+  // Exclude NOTES (read-only AI notes) from feedback
+  const filtered = annotations.filter(a => a.type !== 'NOTES')
+
+  if (filtered.length === 0) {
+    return 'No annotations.'
+  }
+
+  const sorted = sortAnnotations(filtered, blocks)
+  const globalComments = sorted.filter(a => a.targetType === 'global')
+  const regularAnnotations = sorted.filter(a => a.targetType !== 'global')
+
+  let output = `# Annotation Feedback\n\n`
+  output += `${filtered.length} annotation${filtered.length > 1 ? 's' : ''}:\n\n`
+
+  if (globalComments.length > 0) {
+    output += `## General Feedback\n\n`
+    globalComments.forEach(ann => {
+      output += `> ${(ann.text ?? '').replace(/\n/g, '\n> ')}\n\n`
+    })
+  }
+
+  regularAnnotations.forEach((ann, index) => {
+    const block = blocks.find(blk => blk.id === ann.blockId)
+    output += formatAnnotation(ann, block, `## ${index + 1}.`)
+  })
+
+  output += '---\n'
+  return output
+}

package/server/file.js

@@ -0,0 +1,43 @@
+/**
+ * File I/O utilities for markdown files.
+ */
+
+import { readFile } from 'node:fs/promises'
+import { access, constants } from 'node:fs/promises'
+import { extname, resolve } from 'node:path'
+
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown', '.mdown', '.mkd'])
+
+export function isMarkdownFile(filePath) {
+  const ext = extname(filePath).toLowerCase()
+  return MARKDOWN_EXTENSIONS.has(ext)
+}
+
+export async function fileExists(filePath) {
+  try {
+    await access(filePath, constants.R_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function readMarkdownFile(filePath) {
+  const absolutePath = resolve(filePath)
+
+  if (!isMarkdownFile(absolutePath)) {
+    throw new Error(`Not a Markdown file: ${absolutePath}`)
+  }
+
+  try {
+    return await readFile(absolutePath, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`File not found: ${absolutePath}`)
+    }
+    if (error.code === 'EACCES') {
+      throw new Error(`Permission denied: ${absolutePath}`)
+    }
+    throw new Error(`Failed to read file: ${error.message}`)
+  }
+}