@monoes/monograph 1.0.0 → 1.2.0

package/src/cli/doctor.ts

@@ -0,0 +1,186 @@
+/**
+ * runDoctor — Platform health checks for the Monograph knowledge graph.
+ *
+ * Checks:
+ * 1. Node.js version (must be >= 18)
+ * 2. SQLite DB file exists at .monomind/monograph.db
+ * 3. SQLite DB is readable (SELECT 1)
+ * 4. DB node count (warns if graph not built)
+ * 5. Disk space (warns if < 100 MB free)
+ * 6. Tree-sitter availability
+ */
+
+import { existsSync, statfsSync } from 'fs';
+import { join } from 'path';
+
+export interface DoctorCheck {
+  name: string;
+  status: 'ok' | 'warn' | 'error';
+  message: string;
+}
+
+export interface DoctorResult {
+  checks: DoctorCheck[];
+  /** true if no 'error' level checks */
+  healthy: boolean;
+}
+
+// ─── Individual checks ────────────────────────────────────────────────────────
+
+function checkNodeVersion(): DoctorCheck {
+  const raw = process.version; // e.g. 'v20.1.0'
+  const major = parseInt(raw.replace(/^v/, '').split('.')[0], 10);
+  if (major >= 18) {
+    return { name: 'Node version', status: 'ok', message: `${raw} (>= 18 required)` };
+  }
+  return {
+    name: 'Node version',
+    status: 'error',
+    message: `${raw} — Node >= 18 is required`,
+  };
+}
+
+function checkDbExists(dbPath: string): DoctorCheck {
+  if (existsSync(dbPath)) {
+    return { name: 'SQLite DB exists', status: 'ok', message: dbPath };
+  }
+  return {
+    name: 'SQLite DB exists',
+    status: 'error',
+    message: `DB not found at ${dbPath} — run monograph build first`,
+  };
+}
+
+function checkDbReadable(dbPath: string): DoctorCheck {
+  try {
+    // Dynamic require keeps this check lazy so missing better-sqlite3 doesn't
+    // crash the entire doctor invocation.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const Database = require('better-sqlite3') as typeof import('better-sqlite3');
+    const db = new Database(dbPath, { readonly: true });
+    db.prepare('SELECT 1').get();
+    db.close();
+    return { name: 'SQLite DB readable', status: 'ok', message: 'SELECT 1 passed' };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { name: 'SQLite DB readable', status: 'error', message: msg };
+  }
+}
+
+function checkNodeCount(dbPath: string): DoctorCheck {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const Database = require('better-sqlite3') as typeof import('better-sqlite3');
+    const db = new Database(dbPath, { readonly: true });
+    const row = db.prepare('SELECT COUNT(*) AS n FROM nodes').get() as { n: number } | undefined;
+    db.close();
+    const count = row?.n ?? 0;
+    if (count === 0) {
+      return {
+        name: 'DB node count',
+        status: 'warn',
+        message: '0 nodes — graph not built yet. Run monograph build.',
+      };
+    }
+    return { name: 'DB node count', status: 'ok', message: `${count} nodes indexed` };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { name: 'DB node count', status: 'warn', message: `Could not read node count: ${msg}` };
+  }
+}
+
+function checkDiskSpace(repoPath: string): DoctorCheck {
+  const MIN_FREE_BYTES = 100 * 1024 * 1024; // 100 MB
+  try {
+    if (typeof statfsSync !== 'function') {
+      return {
+        name: 'Disk space',
+        status: 'ok',
+        message: 'statfsSync not available on this platform — skipped',
+      };
+    }
+    const stats = statfsSync(repoPath);
+    const freeBytes = stats.bsize * stats.bavail;
+    const freeMB = Math.round(freeBytes / (1024 * 1024));
+    if (freeBytes < MIN_FREE_BYTES) {
+      return {
+        name: 'Disk space',
+        status: 'warn',
+        message: `Only ${freeMB} MB free — less than 100 MB recommended`,
+      };
+    }
+    return { name: 'Disk space', status: 'ok', message: `${freeMB} MB free` };
+  } catch {
+    // statfsSync may throw on some platforms (e.g. Windows)
+    return {
+      name: 'Disk space',
+      status: 'ok',
+      message: 'Disk space check not supported on this platform — skipped',
+    };
+  }
+}
+
+async function checkTreeSitter(): Promise<DoctorCheck> {
+  try {
+    await import('tree-sitter');
+    return { name: 'Tree-sitter', status: 'ok', message: 'tree-sitter module available' };
+  } catch {
+    return {
+      name: 'Tree-sitter',
+      status: 'warn',
+      message: 'tree-sitter not available — install it to enable code parsing',
+    };
+  }
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Run all platform health checks and return a structured result.
+ *
+ * @param repoPath - Absolute path to the repository root
+ * @returns DoctorResult with individual check outcomes and overall health
+ *
+ * @example
+ * const result = await runDoctor('/path/to/repo');
+ * if (!result.healthy) console.error('Some checks failed.');
+ */
+export async function runDoctor(repoPath: string): Promise<DoctorResult> {
+  const dbPath = join(repoPath, '.monomind', 'monograph.db');
+
+  const checks: DoctorCheck[] = [];
+
+  // 1. Node version
+  checks.push(checkNodeVersion());
+
+  // 2. DB file existence
+  const dbExistsCheck = checkDbExists(dbPath);
+  checks.push(dbExistsCheck);
+
+  // 3. DB readable (only if DB exists)
+  if (dbExistsCheck.status !== 'error') {
+    checks.push(checkDbReadable(dbPath));
+    checks.push(checkNodeCount(dbPath));
+  } else {
+    checks.push({
+      name: 'SQLite DB readable',
+      status: 'error',
+      message: 'Skipped — DB file not found',
+    });
+    checks.push({
+      name: 'DB node count',
+      status: 'error',
+      message: 'Skipped — DB file not found',
+    });
+  }
+
+  // 4. Disk space
+  checks.push(checkDiskSpace(repoPath));
+
+  // 5. Tree-sitter
+  checks.push(await checkTreeSitter());
+
+  const healthy = checks.every((c) => c.status !== 'error');
+
+  return { checks, healthy };
+}

package/src/cli/eval-server.ts

@@ -0,0 +1,119 @@
+/**
+ * Eval Server — Lightweight HTTP server for CI/integration evaluation of monograph queries.
+ *
+ * Exposes /health, /query, and /search endpoints backed by the monograph DB.
+ * Designed for integration tests and evaluation scripts.
+ *
+ * Usage:
+ *   createEvalServer('/path/to/repo')
+ *   createEvalServer('/path/to/repo', 4848)
+ */
+
+import type { Server } from 'http';
+import type { Application } from 'express';
+import { openDb, closeDb } from '../storage/db.js';
+import { querySearch, queryStats } from '../web/api.js';
+import { hybridQuery } from '../search/hybrid-query.js';
+import type { HybridResult } from '../search/hybrid-query.js';
+import type { ApiNode } from '../web/api.js';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface EvalServerHandle {
+  app: Application;
+  start(port: number): Promise<Server>;
+  stop(): void;
+}
+
+export type SearchResult = HybridResult;
+
+// ── createEvalServer ──────────────────────────────────────────────────────────
+
+/**
+ * Create an eval server for a monograph DB at the given repo path.
+ *
+ * Returns an object with:
+ *  - `app` — Express application (useful for supertest)
+ *  - `start(port)` — begins listening; resolves with the Node http.Server
+ *  - `stop()` — closes the DB and server
+ */
+export function createEvalServer(repoPath: string, _port?: number): EvalServerHandle {
+  const dbPath = `${repoPath}/.monomind/monograph.db`;
+  const db = openDb(dbPath);
+
+  let server: Server | null = null;
+
+  // Lazy-import express to keep startup fast
+  let _app: Application | null = null;
+
+  function getApp(): Application {
+    if (_app) return _app;
+
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const express = require('express') as typeof import('express');
+    const app = express();
+    app.use(express.json());
+
+    // GET /health
+    app.get('/health', (_req, res) => {
+      try {
+        const stats = queryStats(db);
+        res.json({ status: 'ok', nodeCount: stats.nodeCount, edgeCount: stats.edgeCount });
+      } catch {
+        res.status(500).json({ status: 'error' });
+      }
+    });
+
+    // POST /query — text search returning MonographNode[]
+    app.post('/query', (req, res) => {
+      try {
+        const q: string = (req.body as { q?: string }).q ?? '';
+        const limit: number = (req.body as { limit?: number }).limit ?? 20;
+        const results: ApiNode[] = q.trim() ? querySearch(db, q).slice(0, limit) : [];
+        res.json({ results });
+      } catch (err) {
+        res.status(500).json({ error: String(err) });
+      }
+    });
+
+    // POST /search — hybrid BM25+vector search returning SearchResult[]
+    app.post('/search', async (req, res) => {
+      try {
+        const query: string = (req.body as { query?: string }).query ?? '';
+        const limit: number = (req.body as { limit?: number }).limit ?? 20;
+        const results: HybridResult[] = query.trim()
+          ? await hybridQuery(db, query, { limit })
+          : [];
+        res.json({ results });
+      } catch (err) {
+        res.status(500).json({ error: String(err) });
+      }
+    });
+
+    _app = app;
+    return app;
+  }
+
+  return {
+    get app(): Application {
+      return getApp();
+    },
+
+    start(port: number): Promise<Server> {
+      const app = getApp();
+      return new Promise((resolve, reject) => {
+        const s = app.listen(port, '127.0.0.1', () => resolve(s));
+        s.on('error', reject);
+        server = s;
+      });
+    },
+
+    stop(): void {
+      if (server) {
+        server.close();
+        server = null;
+      }
+      closeDb(db);
+    },
+  };
+}

package/src/cli/hooks-install.ts

@@ -0,0 +1,202 @@
+import {
+  existsSync,
+  writeFileSync,
+  chmodSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+} from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+
+export const HOOK_MARKER_START = '# monograph-hook-start';
+export const HOOK_MARKER_END = '# monograph-hook-end';
+
+/**
+ * Rebase / merge / cherry-pick skip guard.
+ * Prevents the hook from running during interactive operations.
+ */
+const SKIP_GUARD = `# Skip during rebase, merge, or cherry-pick
+if [ -d "$(git rev-parse --git-dir 2>/dev/null)/rebase-merge" ] || \\
+   [ -d "$(git rev-parse --git-dir 2>/dev/null)/rebase-apply" ] || \\
+   [ -f "$(git rev-parse --git-dir 2>/dev/null)/MERGE_HEAD" ] || \\
+   [ -f "$(git rev-parse --git-dir 2>/dev/null)/CHERRY_PICK_HEAD" ]; then
+  exit 0
+fi`;
+
+function buildHookBlock(hookName: string): string {
+  const verb =
+    hookName === 'post-merge' || hookName === 'post-checkout'
+      ? 'rebuild knowledge graph after ' + hookName.replace('post-', '')
+      : 'rebuild knowledge graph on ' + hookName.replace('pre-', '');
+
+  return [
+    HOOK_MARKER_START,
+    `# Monograph: ${verb}`,
+    SKIP_GUARD,
+    'if command -v monograph >/dev/null 2>&1; then',
+    '  monograph build --silent || true',
+    'elif command -v npx >/dev/null 2>&1; then',
+    '  npx monograph build --silent || true',
+    'fi',
+    HOOK_MARKER_END,
+  ].join('\n');
+}
+
+/**
+ * Detect the git hooks directory, supporting Husky / custom `core.hooksPath`.
+ */
+function getHooksDir(repoPath: string): string {
+  try {
+    const custom = execSync('git config core.hooksPath', {
+      cwd: repoPath,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (custom) {
+      return join(repoPath, custom);
+    }
+  } catch {
+    // Not configured — fall through to default
+  }
+  return join(repoPath, '.git', 'hooks');
+}
+
+/**
+ * Install (or update) monograph hooks by appending a marked block.
+ * Existing hook content is preserved. Re-running is idempotent.
+ */
+export function installGitHooks(repoPath: string, hooks: string[]): void {
+  const hooksDir = getHooksDir(repoPath);
+  if (!existsSync(hooksDir)) {
+    throw new Error(`No .git/hooks directory found at ${repoPath}`);
+  }
+  for (const hook of hooks) {
+    if (!/^[\w-]+$/.test(hook)) {
+      throw new Error(`Invalid hook name: "${hook}" — must be alphanumeric with hyphens only`);
+    }
+    const hookPath = join(hooksDir, hook);
+    const block = buildHookBlock(hook);
+
+    let existing = '';
+    if (existsSync(hookPath)) {
+      existing = readFileSync(hookPath, 'utf8');
+    }
+
+    // Remove any existing monograph block (for idempotence)
+    const stripped = removeMarkerBlock(existing);
+
+    // If there was no prior content (beyond whitespace/shebang), start fresh with a shebang
+    const hasMeaningfulContent = stripped.replace(/^#!.*$/m, '').trim().length > 0;
+    const preamble = hasMeaningfulContent
+      ? stripped.trimEnd() + '\n\n'
+      : '#!/bin/sh\n\n';
+
+    writeFileSync(hookPath, preamble + block + '\n', 'utf8');
+    chmodSync(hookPath, 0o755);
+  }
+}
+
+/**
+ * Remove the monograph marker block from hook content.
+ * Returns the content with the block stripped.
+ */
+function removeMarkerBlock(content: string): string {
+  const startIdx = content.indexOf(HOOK_MARKER_START);
+  const endIdx = content.indexOf(HOOK_MARKER_END);
+  if (startIdx === -1) return content;
+  const afterEnd = endIdx !== -1 ? content.slice(endIdx + HOOK_MARKER_END.length) : '';
+  return content.slice(0, startIdx) + afterEnd;
+}
+
+/**
+ * Uninstall monograph from hooks.
+ * Only removes the marker block — surrounding content is preserved.
+ * Removes the file entirely if nothing meaningful remains.
+ */
+export function uninstallGitHooks(repoPath: string, hooks: string[]): void {
+  const hooksDir = getHooksDir(repoPath);
+  for (const hook of hooks) {
+    if (!/^[\w-]+$/.test(hook)) {
+      throw new Error(`Invalid hook name: "${hook}" — must be alphanumeric with hyphens only`);
+    }
+    const hookPath = join(hooksDir, hook);
+    if (!existsSync(hookPath)) continue;
+    const original = readFileSync(hookPath, 'utf8');
+    if (!original.includes(HOOK_MARKER_START)) continue;
+    const stripped = removeMarkerBlock(original);
+    // If only a shebang (or whitespace) remains, the file was created entirely by us
+    const meaningful = stripped.replace(/^#!.*$/m, '').trim();
+    if (!meaningful) {
+      // Remove the file — nothing custom was there
+      try {
+        unlinkSync(hookPath);
+      } catch {
+        writeFileSync(hookPath, stripped, 'utf8');
+      }
+    } else {
+      writeFileSync(hookPath, stripped.trimEnd() + '\n', 'utf8');
+    }
+  }
+}
+
+/**
+ * List hook names that contain a monograph marker block.
+ */
+export function listInstalledHooks(repoPath: string): string[] {
+  const hooksDir = getHooksDir(repoPath);
+  if (!existsSync(hooksDir)) return [];
+  const installed: string[] = [];
+  for (const f of readdirSync(hooksDir)) {
+    try {
+      const content = readFileSync(join(hooksDir, f), 'utf8');
+      if (content.includes(HOOK_MARKER_START)) installed.push(f);
+    } catch { /* skip */ }
+  }
+  return installed;
+}
+
+export interface PerHookStatus {
+  installed: boolean;
+  path: string;
+  hasCustomContent: boolean;
+}
+
+export interface HookStatus {
+  installed: boolean;
+  hooks: string[];
+  hooksDir: string;
+  /** Per-hook details keyed by hook name. */
+  perHook?: Record<string, PerHookStatus>;
+}
+
+export function getHookStatus(repoPath: string): HookStatus {
+  const hooksDir = getHooksDir(repoPath);
+  let installed: string[] = [];
+  try {
+    installed = listInstalledHooks(repoPath);
+  } catch { /* .git dir missing or unreadable */ }
+
+  // Build per-hook status for all known hooks + any installed ones
+  const knownHooks = ['pre-commit', 'post-merge', 'post-checkout', 'pre-push'];
+  const allHooks = new Set([...knownHooks, ...installed]);
+  const perHook: Record<string, PerHookStatus> = {};
+  for (const hook of allHooks) {
+    const hookPath = join(hooksDir, hook);
+    const isInstalled = installed.includes(hook);
+    let hasCustomContent = false;
+    if (existsSync(hookPath)) {
+      const content = readFileSync(hookPath, 'utf8');
+      const stripped = removeMarkerBlock(content);
+      hasCustomContent = stripped.replace(/^#!.*$/m, '').trim().length > 0;
+    }
+    perHook[hook] = { installed: isInstalled, path: hookPath, hasCustomContent };
+  }
+
+  return {
+    installed: installed.length > 0,
+    hooks: installed,
+    hooksDir,
+    perHook,
+  };
+}

package/src/cli/setup.ts

@@ -0,0 +1,197 @@
+/**
+ * setupMonograph — Writes monograph MCP server configuration into AI tool
+ * config files (CLAUDE.md, AGENTS.md, .cursor/mcp.json) for a given repo.
+ *
+ * Running it multiple times is idempotent: if the config block is already
+ * present the file is left unchanged.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+export type SetupTool = 'claude' | 'cursor' | 'agents-md';
+
+export interface SetupOptions {
+  /** Absolute path to the repository root */
+  repoPath: string;
+  /** Which tool configs to write. Defaults to all three. */
+  tools?: SetupTool[];
+}
+
+export interface SetupResult {
+  /** Files that were written or updated */
+  configured: string[];
+  /** Files that were skipped because the config was already present */
+  skipped: string[];
+  /** Errors encountered (file not written) */
+  errors: string[];
+}
+
+// ─── MCP server config ───────────────────────────────────────────────────────
+
+const MCP_SERVER_ENTRY = {
+  command: 'npx',
+  args: ['@monoes/monograph', 'mcp'],
+  env: {},
+};
+
+const MCP_CONFIG_BLOCK = JSON.stringify(
+  { mcpServers: { monograph: MCP_SERVER_ENTRY } },
+  null,
+  2,
+);
+
+// Sentinel used to detect whether the block is already present in markdown.
+const MONOGRAPH_SENTINEL = '@monoes/monograph';
+
+const MARKDOWN_BLOCK = `
+## Monograph MCP Server
+
+Add the following to your MCP configuration to enable monograph code intelligence:
+
+\`\`\`json
+${MCP_CONFIG_BLOCK}
+\`\`\`
+`;
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+async function readFileSafe(filePath: string): Promise<string> {
+  try {
+    return await fs.readFile(filePath, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Append the monograph config block to a markdown file (CLAUDE.md / AGENTS.md).
+ * Idempotent: does nothing when the sentinel string is already present.
+ */
+async function upsertMarkdownFile(filePath: string): Promise<'configured' | 'skipped'> {
+  const existing = await readFileSafe(filePath);
+
+  if (existing.includes(MONOGRAPH_SENTINEL)) {
+    return 'skipped';
+  }
+
+  const updated = existing.trimEnd() + '\n' + MARKDOWN_BLOCK.trimStart();
+  await fs.writeFile(filePath, updated, 'utf-8');
+  return 'configured';
+}
+
+/**
+ * Merge the monograph server entry into a JSON MCP config file.
+ * Preserves existing keys. Idempotent.
+ *
+ * Handles corrupt / unreadable files gracefully (leaves them untouched).
+ */
+async function upsertJsonMcpFile(
+  filePath: string,
+): Promise<'configured' | 'skipped' | 'error'> {
+  const raw = await readFileSafe(filePath);
+
+  let config: Record<string, unknown> = {};
+
+  if (raw.trim().length > 0) {
+    try {
+      config = JSON.parse(raw);
+    } catch {
+      // Corrupt JSON — leave untouched
+      return 'error';
+    }
+  }
+
+  // Check idempotency
+  const servers = (config.mcpServers ?? {}) as Record<string, unknown>;
+  if (servers.monograph !== undefined) {
+    return 'skipped';
+  }
+
+  config.mcpServers = { ...servers, monograph: MCP_SERVER_ENTRY };
+
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+  return 'configured';
+}
+
+// ─── Per-tool handlers ────────────────────────────────────────────────────────
+
+async function setupClaude(repoPath: string, result: SetupResult): Promise<void> {
+  const filePath = path.join(repoPath, 'CLAUDE.md');
+  try {
+    const outcome = await upsertMarkdownFile(filePath);
+    if (outcome === 'configured') {
+      result.configured.push('CLAUDE.md');
+    } else {
+      result.skipped.push('CLAUDE.md');
+    }
+  } catch (err: unknown) {
+    result.errors.push(`CLAUDE.md: ${(err as Error).message}`);
+  }
+}
+
+async function setupCursor(repoPath: string, result: SetupResult): Promise<void> {
+  const filePath = path.join(repoPath, '.cursor', 'mcp.json');
+  try {
+    const outcome = await upsertJsonMcpFile(filePath);
+    if (outcome === 'configured') {
+      result.configured.push('.cursor/mcp.json');
+    } else if (outcome === 'skipped') {
+      result.skipped.push('.cursor/mcp.json');
+    } else {
+      result.errors.push('.cursor/mcp.json: file is corrupt — skipping to preserve existing content');
+    }
+  } catch (err: unknown) {
+    result.errors.push(`.cursor/mcp.json: ${(err as Error).message}`);
+  }
+}
+
+async function setupAgentsMd(repoPath: string, result: SetupResult): Promise<void> {
+  const filePath = path.join(repoPath, 'AGENTS.md');
+  try {
+    const outcome = await upsertMarkdownFile(filePath);
+    if (outcome === 'configured') {
+      result.configured.push('AGENTS.md');
+    } else {
+      result.skipped.push('AGENTS.md');
+    }
+  } catch (err: unknown) {
+    result.errors.push(`AGENTS.md: ${(err as Error).message}`);
+  }
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+const ALL_TOOLS: SetupTool[] = ['claude', 'cursor', 'agents-md'];
+
+/**
+ * Write the monograph MCP server configuration into AI tool config files.
+ *
+ * @param repoPath  - Absolute path to the target repository root
+ * @param tools     - Which tools to configure (default: all)
+ * @returns         - SetupResult describing what was written / skipped / errored
+ *
+ * @example
+ * const result = await setupMonograph({ repoPath: '/path/to/repo' });
+ * console.log(result.configured); // ['CLAUDE.md', '.cursor/mcp.json', 'AGENTS.md']
+ */
+export async function setupMonograph(options: SetupOptions): Promise<SetupResult> {
+  const { repoPath, tools = ALL_TOOLS } = options;
+
+  const result: SetupResult = {
+    configured: [],
+    skipped: [],
+    errors: [],
+  };
+
+  const handlers: Record<SetupTool, (repoPath: string, result: SetupResult) => Promise<void>> = {
+    claude: setupClaude,
+    cursor: setupCursor,
+    'agents-md': setupAgentsMd,
+  };
+
+  await Promise.all(tools.map((tool) => handlers[tool](repoPath, result)));
+
+  return result;
+}