@henryavila/mdprobe 0.1.0 → 0.2.0

package/src/setup.js

@@ -0,0 +1,203 @@
+import { readFile, writeFile, mkdir, rm, access } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+import { execFile } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const PROJECT_ROOT = join(dirname(__filename), '..')
+const SKILL_SOURCE = join(PROJECT_ROOT, 'skills', 'mdprobe', 'SKILL.md')
+const DEFAULT_CONFIG_PATH = join(homedir(), '.mdprobe.json')
+
+// IDE skill directory mappings
+const IDE_CONFIGS = {
+  'Claude Code': { skillsDir: join(homedir(), '.claude', 'skills') },
+  'Cursor': { skillsDir: join(homedir(), '.cursor', 'skills') },
+  'Gemini': { skillsDir: join(homedir(), '.gemini', 'skills') },
+}
+
+/**
+ * Detect which IDEs have skill directories.
+ * @returns {Promise<string[]>} List of IDE names with skills dirs
+ */
+export async function detectIDEs() {
+  const detected = []
+  for (const [name, config] of Object.entries(IDE_CONFIGS)) {
+    try {
+      await access(config.skillsDir)
+      detected.push(name)
+    } catch {
+      // Directory doesn't exist
+    }
+  }
+  return detected
+}
+
+/**
+ * Install the SKILL.md file to an IDE's skill directory.
+ * @param {string} ide - IDE name (e.g., 'Claude Code')
+ * @param {string} [content] - Skill content (reads from source if omitted)
+ * @returns {Promise<string>} Path where skill was installed
+ */
+export async function installSkill(ide, content) {
+  const config = IDE_CONFIGS[ide]
+  if (!config) throw new Error(`Unknown IDE: ${ide}`)
+
+  if (!content) {
+    content = await readFile(SKILL_SOURCE, 'utf-8')
+  }
+
+  const destDir = join(config.skillsDir, 'mdprobe')
+  await mkdir(destDir, { recursive: true })
+  const destPath = join(destDir, 'SKILL.md')
+  await writeFile(destPath, content, 'utf-8')
+  return destPath
+}
+
+/**
+ * Register the MCP server via claude CLI.
+ * Falls back to direct ~/.claude.json write if CLI not available.
+ * @returns {Promise<{method: string}>}
+ */
+export async function registerMCP() {
+  try {
+    await execFileAsync('claude', [
+      'mcp', 'add', '--scope', 'user', '--transport', 'stdio',
+      'mdprobe', '--', 'mdprobe', 'mcp',
+    ])
+    return { method: 'cli' }
+  } catch {
+    // Fallback: write directly to ~/.claude.json
+    const claudeJsonPath = join(homedir(), '.claude.json')
+    let config = {}
+    try {
+      config = JSON.parse(await readFile(claudeJsonPath, 'utf-8'))
+    } catch { /* start fresh */ }
+
+    if (!config.mcpServers) config.mcpServers = {}
+    config.mcpServers.mdprobe = {
+      command: 'mdprobe',
+      args: ['mcp'],
+      type: 'stdio',
+    }
+
+    await writeFile(claudeJsonPath, JSON.stringify(config, null, 2), 'utf-8')
+    return { method: 'file' }
+  }
+}
+
+/**
+ * Register PostToolUse hook in settings.json (safe merge).
+ * @param {string} [settingsPath] - Override path for testing
+ * @returns {Promise<{added: boolean}>}
+ */
+export async function registerHook(settingsPath) {
+  if (!settingsPath) {
+    settingsPath = join(homedir(), '.claude', 'settings.json')
+  }
+
+  let settings = {}
+  try {
+    settings = JSON.parse(await readFile(settingsPath, 'utf-8'))
+  } catch { /* start fresh */ }
+
+  if (!settings.hooks) settings.hooks = {}
+  if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = []
+
+  // Check if mdprobe hook already exists
+  const existing = settings.hooks.PostToolUse.find(h =>
+    h.hooks?.some(hh => typeof hh.command === 'string' && hh.command.includes('[mdprobe]'))
+  )
+  if (existing) return { added: false }
+
+  const hookCommand = `node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8')); const p=d.tool_input?.file_path||''; if(p.endsWith('.md')){const j={decision:'allow',reason:'[mdprobe] .md file modified: '+require('path').basename(p)+'. Offer to open with mdProbe.'}; process.stdout.write(JSON.stringify(j))}"`
+
+  settings.hooks.PostToolUse.push({
+    matcher: 'Write|Edit',
+    hooks: [{ type: 'command', command: hookCommand }],
+  })
+
+  await mkdir(dirname(settingsPath), { recursive: true })
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2), 'utf-8')
+  return { added: true }
+}
+
+/**
+ * Save user config to ~/.mdprobe.json.
+ * @param {object} config - { author, urlStyle }
+ * @param {string} [configPath]
+ */
+export async function saveConfig(config, configPath = DEFAULT_CONFIG_PATH) {
+  await mkdir(dirname(configPath), { recursive: true })
+  await writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8')
+}
+
+/**
+ * Remove all mdprobe installations.
+ * @param {object} [opts]
+ * @param {string} [opts.configPath]
+ * @param {string} [opts.settingsPath]
+ */
+export async function removeAll(opts = {}) {
+  const configPath = opts.configPath || DEFAULT_CONFIG_PATH
+  const settingsPath = opts.settingsPath || join(homedir(), '.claude', 'settings.json')
+  const removed = []
+
+  // Remove skill from all IDEs
+  for (const [name, config] of Object.entries(IDE_CONFIGS)) {
+    const skillDir = join(config.skillsDir, 'mdprobe')
+    try {
+      await rm(skillDir, { recursive: true })
+      removed.push(`skill:${name}`)
+    } catch { /* not installed */ }
+  }
+
+  // Remove MCP registration (both CLI and file-based)
+  try {
+    await execFileAsync('claude', ['mcp', 'remove', 'mdprobe'])
+    removed.push('mcp:cli')
+  } catch { /* CLI not available or entry not found */ }
+
+  // Always clean up file-based entry too (may exist from fallback registration)
+  try {
+    const claudeJsonPath = join(homedir(), '.claude.json')
+    const config = JSON.parse(await readFile(claudeJsonPath, 'utf-8'))
+    if (config.mcpServers?.mdprobe) {
+      delete config.mcpServers.mdprobe
+      await writeFile(claudeJsonPath, JSON.stringify(config, null, 2), 'utf-8')
+      removed.push('mcp:file')
+    }
+  } catch { /* ignore */ }
+
+  // Remove hook from settings.json
+  try {
+    const settings = JSON.parse(await readFile(settingsPath, 'utf-8'))
+    if (settings.hooks?.PostToolUse) {
+      const before = settings.hooks.PostToolUse.length
+      settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(h =>
+        !h.hooks?.some(hh => typeof hh.command === 'string' && hh.command.includes('[mdprobe]'))
+      )
+      if (settings.hooks.PostToolUse.length < before) {
+        await writeFile(settingsPath, JSON.stringify(settings, null, 2), 'utf-8')
+        removed.push('hook')
+      }
+    }
+  } catch { /* ignore */ }
+
+  // Remove config file
+  try {
+    await rm(configPath)
+    removed.push('config')
+  } catch { /* ignore */ }
+
+  return removed
+}
+
+function execFileAsync(cmd, args) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, (err, stdout) => {
+      if (err) reject(err)
+      else resolve(stdout)
+    })
+  })
+}

package/src/singleton.js

@@ -0,0 +1,236 @@
+import { readFile, writeFile, unlink } from 'node:fs/promises'
+import { unlinkSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { tmpdir } from 'node:os'
+import node_http from 'node:http'
+import { fileURLToPath } from 'node:url'
+import { hashContent } from './hash.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const DIST_INDEX = join(dirname(__filename), '..', 'dist', 'index.html')
+
+const DEFAULT_LOCK_PATH = join(tmpdir(), 'mdprobe.lock')
+
+/**
+ * Compute a build hash from dist/index.html content.
+ * Falls back to package version if dist doesn't exist (dev mode).
+ * @returns {Promise<string>}
+ */
+export async function computeBuildHash() {
+  try {
+    const content = await readFile(DIST_INDEX, 'utf-8')
+    return hashContent(content)
+  } catch {
+    try {
+      const pkg = JSON.parse(await readFile(join(dirname(__filename), '..', 'package.json'), 'utf-8'))
+      return `pkg:${pkg.version}`
+    } catch {
+      return 'unknown'
+    }
+  }
+}
+
+/**
+ * Read and parse the lock file.
+ * @param {string} [lockPath]
+ * @returns {Promise<{pid: number, port: number, url: string, startedAt: string} | null>}
+ */
+export async function readLockFile(lockPath = DEFAULT_LOCK_PATH) {
+  try {
+    const raw = await readFile(lockPath, 'utf-8')
+    return JSON.parse(raw)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Write lock file with server instance data.
+ * @param {{pid: number, port: number, url: string, startedAt: string}} data
+ * @param {string} [lockPath]
+ */
+export async function writeLockFile(data, lockPath = DEFAULT_LOCK_PATH) {
+  await writeFile(lockPath, JSON.stringify(data), 'utf-8')
+}
+
+/**
+ * Remove lock file. Silently ignores ENOENT.
+ * @param {string} [lockPath]
+ */
+export async function removeLockFile(lockPath = DEFAULT_LOCK_PATH) {
+  try {
+    await unlink(lockPath)
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err
+  }
+}
+
+/**
+ * Synchronous lock file removal — last resort for process.on('exit').
+ * @param {string} [lockPath]
+ */
+export function removeLockFileSync(lockPath = DEFAULT_LOCK_PATH) {
+  try {
+    unlinkSync(lockPath)
+  } catch { /* ignore */ }
+}
+
+/**
+ * Check if a process with the given PID is alive.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+export function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    if (err.code === 'EPERM') return true
+    return false
+  }
+}
+
+/**
+ * Ping a server's /api/status endpoint to verify it's a running mdprobe instance.
+ * @param {string} url - Base URL (e.g. "http://127.0.0.1:3000")
+ * @param {number} [timeout=2000]
+ * @returns {Promise<{alive: boolean}>}
+ */
+export function pingServer(url, timeout = 2000) {
+  return new Promise((resolve) => {
+    const req = node_http.get(`${url}/api/status`, { timeout }, (res) => {
+      let data = ''
+      res.on('data', (chunk) => { data += chunk })
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data)
+          resolve({ alive: json.identity === 'mdprobe' })
+        } catch {
+          resolve({ alive: false })
+        }
+      })
+    })
+    req.on('error', () => resolve({ alive: false }))
+    req.on('timeout', () => {
+      req.destroy()
+      resolve({ alive: false })
+    })
+  })
+}
+
+/**
+ * Discover an existing running mdprobe server via lock file + HTTP verification.
+ * Cleans up stale lock files automatically.
+ * @param {string} [lockPath]
+ * @param {string} [currentBuildHash] - If provided, reject servers with different buildHash
+ * @returns {Promise<{url: string, port: number} | null>}
+ */
+export async function discoverExistingServer(lockPath = DEFAULT_LOCK_PATH, currentBuildHash) {
+  const lock = await readLockFile(lockPath)
+  if (!lock) return null
+
+  // Reject lock files without buildHash when we have one (backward compat)
+  if (currentBuildHash && !lock.buildHash) {
+    await removeLockFile(lockPath)
+    return null
+  }
+
+  // Reject lock files with different buildHash (stale server)
+  if (currentBuildHash && lock.buildHash !== currentBuildHash) {
+    await removeLockFile(lockPath)
+    return null
+  }
+
+  if (!isProcessAlive(lock.pid)) {
+    await removeLockFile(lockPath)
+    return null
+  }
+
+  const { alive } = await pingServer(lock.url)
+  if (!alive) {
+    await removeLockFile(lockPath)
+    return null
+  }
+
+  return { url: lock.url, port: lock.port }
+}
+
+/**
+ * Join an existing server by adding files via its HTTP API.
+ * @param {string} url - Base URL of the running server
+ * @param {string[]} files - Absolute file paths to add
+ * @returns {Promise<{ok: boolean, files?: string[], added?: string[]}>}
+ */
+export function joinExistingServer(url, files) {
+  return new Promise((resolve) => {
+    const body = JSON.stringify({ files })
+    const parsed = new URL(`${url}/api/add-files`)
+
+    const req = node_http.request({
+      hostname: parsed.hostname,
+      port: parsed.port,
+      path: parsed.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+      },
+      timeout: 5000,
+    }, (res) => {
+      let data = ''
+      res.on('data', (chunk) => { data += chunk })
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data)
+          resolve({ ok: json.ok === true, files: json.files, added: json.added })
+        } catch {
+          resolve({ ok: false })
+        }
+      })
+    })
+
+    req.on('error', () => resolve({ ok: false }))
+    req.on('timeout', () => {
+      req.destroy()
+      resolve({ ok: false })
+    })
+    req.end(body)
+  })
+}
+
+let shuttingDown = false
+
+/**
+ * Register signal handlers to clean up lock file and close server on exit.
+ * @param {{close: Function}} serverObj
+ * @param {string} [lockPath]
+ */
+export function registerShutdownHandlers(serverObj, lockPath = DEFAULT_LOCK_PATH) {
+  shuttingDown = false
+
+  async function shutdown() {
+    if (shuttingDown) return
+    shuttingDown = true
+
+    await removeLockFile(lockPath)
+
+    try {
+      await serverObj.close()
+    } catch { /* ignore */ }
+
+    process.exit(0)
+  }
+
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+
+  // Synchronous last-resort cleanup on exit
+  process.on('exit', () => {
+    removeLockFileSync(lockPath)
+  })
+}
+
+export { DEFAULT_LOCK_PATH }
+
+// For testing
+export function _resetShutdownFlag() { shuttingDown = false }

package/src/ui/app.jsx

@@ -6,7 +6,8 @@ import { useTheme } from './hooks/useTheme.js'
 import { useAnnotations } from './hooks/useAnnotations.js'
 import { useClientLibs } from './hooks/useClientLibs.js'
 import { files, currentFile, currentHtml, currentToc, author, reviewMode,
-         leftPanelOpen, rightPanelOpen, openAnnotations, sectionStats, driftWarning } from './state/store.js'
+         leftPanelOpen, rightPanelOpen, openAnnotations, sectionStats, driftWarning,
+         orphanedAnnotations } from './state/store.js'
 import { LeftPanel } from './components/LeftPanel.jsx'
 import { RightPanel } from './components/RightPanel.jsx'
 import { Content } from './components/Content.jsx'
@@ -40,17 +41,23 @@ function App() {
   useEffect(() => {
     fetch('/api/files').then(r => r.json()).then(data => {
       files.value = data
-      if (data.length > 0) {
-        const first = data[0].path || data[0]
-        currentFile.value = first
-        // Fetch rendered content
-        fetch(`/api/file?path=${encodeURIComponent(first)}`).then(r => r.json()).then(d => {
-          currentHtml.value = d.html
-          currentToc.value = d.toc || []
+      if (data.length === 0) return
+
+      // Deep link: check if URL pathname matches a file
+      const pathname = window.location.pathname
+      let target = null
+      if (pathname && pathname !== '/') {
+        const cleaned = pathname.replace(/^\//, '')
+        target = data.find(f => {
+          const fp = f.path || f
+          return fp === cleaned ||
+            fp === cleaned.split('/').pop() ||
+            (f.absPath && f.absPath.endsWith('/' + cleaned))
         })
-        // Fetch annotations
-        annotationOps.fetchAnnotations(first)
       }
+
+      const selected = target ? (target.path || target) : (data[0].path || data[0])
+      handleFileSelect(selected)
     })
 
     fetch('/api/config').then(r => r.json()).then(data => {
@@ -76,7 +83,7 @@ function App() {
     <>
       {/* Header */}
       <header class="header">
-        <h1>mdprobe</h1>
+        <h1>mdProbe</h1>
         <span class="header-file">{currentFile.value || 'No file selected'}</span>
         <div style="flex: 1" />
         {sectionStats.value.total > 0 && (reviewMode.value || sectionStats.value.reviewed > 0) && (
@@ -99,7 +106,9 @@ function App() {
       {/* Drift warning banner */}
       {driftWarning.value && (
         <div class="drift-banner">
-          Arquivo modificado desde a ultima revisao. Algumas anotacoes podem estar desalinhadas.
+          {orphanedAnnotations.value.length > 0
+            ? `Arquivo modificado — ${orphanedAnnotations.value.length} anotação(ões) não encontrada(s)`
+            : 'Arquivo modificado desde a ultima revisao. Algumas anotacoes podem estar desalinhadas.'}
           <button class="btn btn-sm" style="margin-left: 8px" onClick={() => driftWarning.value = false}>Dismiss</button>
         </div>
       )}