@henryavila/mdprobe 0.1.0 → 0.2.0

package/src/mcp.js

@@ -0,0 +1,258 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+import { resolve, basename, dirname } from 'node:path'
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { createServer } from './server.js'
+import { openBrowser } from './open-browser.js'
+import { AnnotationFile } from './annotations.js'
+import { getConfig } from './config.js'
+import { hashContent } from './hash.js'
+import { discoverExistingServer, joinExistingServer, writeLockFile, computeBuildHash } from './singleton.js'
+
+let httpServerPromise = null
+
+async function getOrCreateServer(port = 3000) {
+  if (!httpServerPromise) {
+    const buildHash = await computeBuildHash()
+
+    const existing = await discoverExistingServer(undefined, buildHash)
+    if (existing) {
+      httpServerPromise = Promise.resolve({
+        url: existing.url,
+        port: existing.port,
+        addFiles: (paths) => joinExistingServer(existing.url, paths),
+        getFiles: () => [],
+        broadcast: () => {},
+        close: async () => {},
+        _remote: true,
+      })
+    } else {
+      httpServerPromise = createServer({ files: [], port, open: false, buildHash }).then(async (srv) => {
+        await writeLockFile({
+          pid: process.pid,
+          port: srv.port,
+          url: srv.url,
+          startedAt: new Date().toISOString(),
+          buildHash,
+        })
+        return srv
+      })
+    }
+  }
+  return httpServerPromise
+}
+
+function buildUrl(port, urlStyle, filePath) {
+  const host = urlStyle === 'mdprobe.localhost' ? 'mdprobe.localhost' : 'localhost'
+  const suffix = filePath ? '/' + filePath : ''
+  return `http://${host}:${port}${suffix}`
+}
+
+export function validateViewParams(params) {
+  const hasPaths = Array.isArray(params.paths) && params.paths.length > 0
+  const hasContent = typeof params.content === 'string' && params.content.length > 0
+
+  if (hasPaths && hasContent) {
+    return { error: 'Cannot provide both paths and content. Use one or the other.' }
+  }
+  if (!hasPaths && !hasContent) {
+    return { error: 'Either paths or content must be provided.' }
+  }
+  if (hasContent && !params.filename) {
+    return { error: 'filename is required when content is provided.' }
+  }
+  return { mode: hasPaths ? 'paths' : 'content' }
+}
+
+export async function saveContentToFile(content, filename) {
+  const absPath = resolve(filename)
+  await mkdir(dirname(absPath), { recursive: true })
+  await writeFile(absPath, content, 'utf-8')
+  return { savedTo: absPath }
+}
+
+export async function startMcpServer() {
+  const config = await getConfig()
+  const author = config.author || 'Agent'
+  const urlStyle = config.urlStyle || 'localhost'
+
+  const server = new McpServer({
+    name: 'mdProbe',
+    version: '0.2.0',
+  })
+
+  server.registerTool('mdprobe_view', {
+    description: 'Open content for human review in the browser. Call this BEFORE asking for feedback on any content >20 lines — findings, specs, plans, analysis, or any long output.',
+    inputSchema: z.object({
+      paths: z.array(z.string()).optional().describe('Paths to .md files (relative or absolute)'),
+      content: z.string().optional().describe('Raw markdown content to save and open'),
+      filename: z.string().optional().describe('Filename to save content to (required with content)'),
+      open: z.boolean().optional().default(true).describe('Auto-open browser'),
+    }),
+  }, async (params) => {
+    const validation = validateViewParams(params)
+    if (validation.error) {
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ error: validation.error }) }],
+        isError: true,
+      }
+    }
+
+    const srv = await getOrCreateServer()
+    let resolved
+    let savedTo
+
+    if (validation.mode === 'content') {
+      const result = await saveContentToFile(params.content, params.filename)
+      savedTo = result.savedTo
+      resolved = [savedTo]
+    } else {
+      resolved = params.paths.map(p => resolve(p))
+    }
+
+    srv.addFiles(resolved)
+
+    const url = resolved.length === 1
+      ? buildUrl(srv.port, urlStyle, basename(resolved[0]))
+      : buildUrl(srv.port, urlStyle)
+    if (params.open) await openBrowser(url).catch(() => {})
+
+    const response = { url, files: resolved.map(p => basename(p)) }
+    if (savedTo) response.savedTo = savedTo
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify(response) }],
+    }
+  })
+
+  server.registerTool('mdprobe_annotations', {
+    description: 'Read annotations for a file after human review',
+    inputSchema: z.object({
+      path: z.string().describe('Path to .md file'),
+    }),
+  }, async ({ path }) => {
+    const resolved = resolve(path)
+    const sidecarPath = resolved.replace(/\.md$/, '.annotations.yaml')
+
+    let af
+    try {
+      af = await AnnotationFile.load(sidecarPath)
+    } catch {
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          source: basename(resolved),
+          sections: [],
+          annotations: [],
+          summary: { total: 0, open: 0, resolved: 0, bugs: 0, questions: 0, suggestions: 0, nitpicks: 0 },
+        }) }],
+      }
+    }
+
+    const json = af.toJSON()
+    const summary = {
+      total: json.annotations.length,
+      open: af.getOpen().length,
+      resolved: af.getResolved().length,
+      bugs: af.getByTag('bug').length,
+      questions: af.getByTag('question').length,
+      suggestions: af.getByTag('suggestion').length,
+      nitpicks: af.getByTag('nitpick').length,
+    }
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ ...json, summary }) }],
+    }
+  })
+
+  server.registerTool('mdprobe_update', {
+    description: 'Update annotations — resolve, reopen, reply, create, delete',
+    inputSchema: z.object({
+      path: z.string().describe('Path to .md file'),
+      actions: z.array(z.object({
+        action: z.enum(['resolve', 'reopen', 'reply', 'add', 'delete']),
+        id: z.string().optional(),
+        comment: z.string().optional(),
+        tag: z.enum(['bug', 'question', 'suggestion', 'nitpick']).optional(),
+        selectors: z.any().optional(),
+      })).describe('Batch operations'),
+    }),
+  }, async ({ path, actions }) => {
+    const resolved = resolve(path)
+    const sidecarPath = resolved.replace(/\.md$/, '.annotations.yaml')
+
+    let af
+    try {
+      af = await AnnotationFile.load(sidecarPath)
+    } catch {
+      // Fix #2: wrap readFile in try/catch for missing source files
+      let content
+      try {
+        content = await readFile(resolved, 'utf-8')
+      } catch {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ error: `File not found: ${path}` }) }],
+          isError: true,
+        }
+      }
+      af = AnnotationFile.create(basename(resolved), `sha256:${hashContent(content)}`)
+    }
+
+    for (const act of actions) {
+      switch (act.action) {
+        case 'resolve': af.resolve(act.id); break
+        case 'reopen': af.reopen(act.id); break
+        case 'reply': af.addReply(act.id, { author, comment: act.comment }); break
+        case 'add': af.add({ selectors: act.selectors, comment: act.comment, tag: act.tag, author }); break
+        case 'delete': af.delete(act.id); break
+      }
+    }
+
+    await af.save(sidecarPath)
+
+    // Fix #6: broadcast via WebSocket if HTTP server is running
+    const srv = await httpServerPromise
+    if (srv?.broadcast) {
+      srv.broadcast({
+        type: 'annotations',
+        file: basename(resolved),
+        annotations: af.toJSON().annotations,
+        sections: af.toJSON().sections,
+      })
+    }
+
+    const json = af.toJSON()
+    return {
+      content: [{ type: 'text', text: JSON.stringify({
+        updated: actions.length,
+        annotations: json.annotations,
+        summary: { total: json.annotations.length, open: af.getOpen().length, resolved: af.getResolved().length },
+      }) }],
+    }
+  })
+
+  // Fix #5: include files field in status response
+  server.registerTool('mdprobe_status', {
+    description: 'Returns current MCP server state',
+    inputSchema: z.object({}),
+  }, async () => {
+    if (!httpServerPromise) {
+      return { content: [{ type: 'text', text: JSON.stringify({ running: false }) }] }
+    }
+    const srv = await httpServerPromise
+    return {
+      content: [{ type: 'text', text: JSON.stringify({
+        running: true,
+        url: srv.url,
+        files: srv.getFiles?.() ?? [],
+      }) }],
+    }
+  })
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}
+
+// For testing: expose internals
+export { getOrCreateServer, buildUrl }
+export function _resetServer() { httpServerPromise = null }

package/src/open-browser.js

@@ -0,0 +1,27 @@
+import { execFile } from 'node:child_process'
+import { readFile } from 'node:fs/promises'
+
+export async function openBrowser(url) {
+  const isWSL = process.platform === 'linux'
+    ? await readFile('/proc/version', 'utf-8').then(v => /microsoft/i.test(v)).catch(() => false)
+    : false
+
+  let cmd, args
+  if (process.platform === 'darwin') {
+    cmd = 'open'
+    args = [url]
+  } else if (process.platform === 'win32') {
+    cmd = 'cmd'
+    args = ['/c', 'start', url]
+  } else if (isWSL) {
+    cmd = '/mnt/c/Windows/System32/cmd.exe'
+    args = ['/c', 'start', url]
+  } else {
+    cmd = 'xdg-open'
+    args = [url]
+  }
+
+  return new Promise((resolve) => {
+    execFile(cmd, args, { stdio: 'ignore' }, () => resolve())
+  })
+}

package/src/server.js

@@ -8,6 +8,7 @@ import { watch } from 'chokidar'
 import { render } from './renderer.js'
 import { AnnotationFile, computeSectionStatus } from './annotations.js'
 import { detectDrift } from './hash.js'
+import { reanchorAll } from './anchoring.js'
 
 // ---------------------------------------------------------------------------
 // File resolution
@@ -236,10 +237,10 @@ if (!SHELL_HTML) {
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>mdprobe</title>
+  <title>mdProbe</title>
 </head>
 <body>
-  <div id="app"><p style="padding:40px;font-family:sans-serif">mdprobe — run <code>npm run build:ui</code> to build the UI</p></div>
+  <div id="app"><p style="padding:40px;font-family:sans-serif">mdProbe — run <code>npm run build:ui</code> to build the UI</p></div>
 </body>
 </html>`
 }
@@ -268,28 +269,35 @@ export async function createServer(options) {
     once = false,
     author,
     onDisconnect,
+    buildHash,
   } = options
 
-  // 1. Resolve files
-  const resolvedFiles = await resolveFiles(files)
+  // 1. Resolve files (allow empty array for lazy MCP mode)
+  const resolvedFiles = (files && files.length > 0) ? await resolveFiles(files) : []
 
-  // Base directory for static asset serving — use the directory of the first file
-  const assetBaseDir = node_path.dirname(resolvedFiles[0])
+  // Base directory for static asset serving — use the directory of the first file or cwd
+  const assetBaseDir = resolvedFiles.length > 0
+    ? node_path.dirname(resolvedFiles[0])
+    : process.cwd()
 
   // 2. Find an available port
   const actualPort = await findAvailablePort(preferredPort)
 
   // 3. Build route handler (onFinish is set below for --once mode)
   let onFinishCallback = null
-  // broadcastToAll is defined below after wss; forward-ref via closure
+  // broadcastToAll and addFiles are defined below; forward-ref via closure
   let broadcastFn = () => {}
+  let addFilesFn = () => {}
   const handleRequest = createRequestHandler({
     resolvedFiles,
     assetBaseDir,
     once,
     author,
+    port: actualPort,
+    buildHash: buildHash || null,
     getOnFinish: () => onFinishCallback,
     broadcast: (msg) => broadcastFn(msg),
+    addFiles: (paths) => addFilesFn(paths),
   })
 
   // 4. Create HTTP server
@@ -354,6 +362,16 @@ export async function createServer(options) {
     }
   }
   broadcastFn = broadcastToAll
+  addFilesFn = (newPaths) => {
+    for (const p of newPaths) {
+      const abs = node_path.resolve(p)
+      if (!resolvedFiles.includes(abs)) {
+        resolvedFiles.push(abs)
+        watcher.add(node_path.dirname(abs))
+        broadcastToAll({ type: 'file-added', file: node_path.basename(abs) })
+      }
+    }
+  }
 
   watcher.on('change', (filePath) => {
     if (!filePath.endsWith('.md')) return
@@ -375,6 +393,25 @@ export async function createServer(options) {
           html: rendered.html,
           toc: rendered.toc,
         })
+
+        // Check for drift and broadcast anchor status
+        const sidecarPath = filePath.replace(/\.md$/, '.annotations.yaml')
+        try {
+          const drift = await detectDrift(sidecarPath, filePath)
+          if (drift.drifted) {
+            const af = await AnnotationFile.load(sidecarPath)
+            const anns = af.toJSON().annotations
+            const anchorResults = reanchorAll(anns, content)
+            broadcastToAll({
+              type: 'drift',
+              warning: true,
+              file: fileName,
+              anchorStatus: Object.fromEntries(
+                [...anchorResults].map(([id, r]) => [id, r.status === 'orphan' ? 'orphan' : 'anchored'])
+              ),
+            })
+          }
+        } catch { /* no sidecar or drift check failed — skip */ }
       } catch (err) {
         broadcastToAll({
           type: 'error',
@@ -404,6 +441,9 @@ export async function createServer(options) {
     url: `http://127.0.0.1:${actualPort}`,
     port: actualPort,
     address: () => httpServer.address(),
+    addFiles: addFilesFn,
+    getFiles: () => resolvedFiles.map(f => node_path.basename(f)),
+    broadcast: (msg) => broadcastToAll(msg),
     close: (cb) => {
       // Clear all debounce timers
       for (const timer of debounceTimers.values()) clearTimeout(timer)
@@ -450,7 +490,7 @@ export async function createServer(options) {
  * @param {string} [ctx.author]
  * @returns {(req: node_http.IncomingMessage, res: node_http.ServerResponse) => void}
  */
-function createRequestHandler({ resolvedFiles, assetBaseDir, once, author, getOnFinish, broadcast }) {
+function createRequestHandler({ resolvedFiles, assetBaseDir, once, author, port, buildHash, getOnFinish, broadcast, addFiles }) {
   return async (req, res) => {
     try {
       const parsedUrl = new URL(req.url, `http://${req.headers.host}`)
@@ -508,10 +548,18 @@ function createRequestHandler({ resolvedFiles, assetBaseDir, once, author, getOn
           const af = await AnnotationFile.load(sidecarPath)
           json = af.toJSON()
           savedSections = json.sections || []
-          // Check for drift
+          // Check for drift and re-anchor annotations
           try {
             const drift = await detectDrift(sidecarPath, match)
-            if (drift.drifted) json.drift = true
+            if (drift.drifted) {
+              const content = await node_fs.readFile(match, 'utf8')
+              const anchorResults = reanchorAll(json.annotations, content)
+              json.drift = {
+                anchorStatus: Object.fromEntries(
+                  [...anchorResults].map(([id, r]) => [id, r.status === 'orphan' ? 'orphan' : 'anchored'])
+                )
+              }
+            }
           } catch { /* no drift info available */ }
         } catch {
           // No sidecar or unreadable
@@ -690,6 +738,35 @@ function createRequestHandler({ resolvedFiles, assetBaseDir, once, author, getOn
         return sendJSON(res, 200, { author: author || 'anonymous' })
       }
 
+      // GET /api/status — identity check for singleton discovery
+      if (req.method === 'GET' && pathname === '/api/status') {
+        return sendJSON(res, 200, {
+          identity: 'mdprobe',
+          pid: process.pid,
+          port,
+          files: resolvedFiles.map(f => node_path.basename(f)),
+          uptime: process.uptime(),
+          buildHash,
+        })
+      }
+
+      // POST /api/add-files — add files from another process (singleton join)
+      if (req.method === 'POST' && pathname === '/api/add-files') {
+        const body = await readBody(req)
+        const { files: newFiles } = body
+        if (!Array.isArray(newFiles) || newFiles.length === 0) {
+          return sendJSON(res, 400, { error: 'Missing or empty files array' })
+        }
+        const before = resolvedFiles.length
+        addFiles(newFiles)
+        const added = resolvedFiles.slice(before).map(f => node_path.basename(f))
+        return sendJSON(res, 200, {
+          ok: true,
+          files: resolvedFiles.map(f => node_path.basename(f)),
+          added,
+        })
+      }
+
       // GET /api/review/status (only in once mode)
       if (req.method === 'GET' && pathname === '/api/review/status') {
         if (once) {
@@ -756,6 +833,12 @@ function createRequestHandler({ resolvedFiles, assetBaseDir, once, author, getOn
         }
       }
 
+      // SPA catch-all: serve HTML shell for any unmatched GET path
+      // This enables deep linking — client reads pathname to auto-select file
+      if (req.method === 'GET') {
+        return sendHTML(res, 200, SHELL_HTML)
+      }
+
       // Fallback — 404
       send404(res)
     } catch (err) {

package/src/setup-ui.js

@@ -0,0 +1,108 @@
+import { intro, outro, text, select, confirm, spinner, isCancel } from '@clack/prompts'
+import { readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  detectIDEs, installSkill, registerMCP,
+  registerHook, saveConfig, removeAll,
+} from './setup.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const PROJECT_ROOT = join(dirname(__filename), '..')
+const pkg = JSON.parse(readFileSync(join(PROJECT_ROOT, 'package.json'), 'utf-8'))
+
+function bail(value) {
+  if (isCancel(value)) {
+    outro('Setup cancelado.')
+    process.exit(0)
+  }
+  return value
+}
+
+export async function runSetup(args) {
+  const isRemove = args.includes('--remove')
+  const isNonInteractive = args.includes('--yes')
+  const authorIdx = args.indexOf('--author')
+  const authorFlag = (authorIdx !== -1 && args[authorIdx + 1] && !args[authorIdx + 1].startsWith('-'))
+    ? args[authorIdx + 1]
+    : undefined
+
+  if (isRemove) {
+    const s = spinner()
+    s.start('Removendo mdProbe...')
+    const removed = await removeAll()
+    s.stop(`Removido: ${removed.length > 0 ? removed.join(', ') : 'nada encontrado'}`)
+    return
+  }
+
+  if (isNonInteractive) {
+    const author = authorFlag || 'anonymous'
+    const urlStyle = 'localhost'
+    const ides = await detectIDEs()
+
+    const s = spinner()
+    s.start('Instalando...')
+
+    for (const ide of ides) {
+      await installSkill(ide)
+    }
+    await registerMCP()
+    await registerHook()
+    await saveConfig({ author, urlStyle })
+
+    s.stop('Instalado com sucesso')
+    console.log(`  IDEs: ${ides.length > 0 ? ides.join(', ') : 'nenhum detectado'}`)
+    console.log(`  Author: ${author}`)
+    return
+  }
+
+  // Interactive mode
+  intro(`mdProbe v${pkg.version} — setup`)
+
+  const author = bail(await text({
+    message: 'Seu nome para anotacoes:',
+    placeholder: 'anonymous',
+    validate: () => undefined,
+  })) || 'anonymous'
+
+  const urlStyle = bail(await select({
+    message: 'Estilo de URL:',
+    options: [
+      { value: 'mdprobe.localhost', label: 'mdprobe.localhost', hint: 'Chrome/Firefox/Edge' },
+      { value: 'localhost', label: 'localhost', hint: 'compativel com todos' },
+    ],
+  }))
+
+  const ides = await detectIDEs()
+  if (ides.length > 0) {
+    console.log(`  IDEs detectados: ${ides.map(i => `✓ ${i}`).join(', ')}`)
+  } else {
+    console.log('  Nenhum IDE detectado.')
+  }
+
+  const s = spinner()
+  s.start('Instalando...')
+
+  const installed = []
+
+  for (const ide of ides) {
+    const path = await installSkill(ide)
+    installed.push(`  ${ide}: ${path}`)
+  }
+
+  const mcpResult = await registerMCP()
+  const hookResult = await registerHook()
+  await saveConfig({ author, urlStyle })
+
+  s.stop('Instalado com sucesso!')
+
+  if (installed.length > 0) {
+    console.log('\n  Skills instaladas:')
+    installed.forEach(p => console.log(`    ${p}`))
+  }
+  console.log(`\n  MCP server registrado (${mcpResult.method})`)
+  if (hookResult.added) console.log('  Hook PostToolUse registrado')
+  console.log(`  Config salva em ~/.mdprobe.json`)
+
+  outro('Reinicie o Claude Code para ativar.')
+}