@monoes/monograph 1.5.6 → 1.5.8

package/src/cli/doctor.ts

@@ -1,182 +0,0 @@
-/**
- * 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`,
-  };
-}
-
-async function checkDbReadable(dbPath: string): Promise<DoctorCheck> {
-  try {
-    const Database = (await import('better-sqlite3')).default;
-    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 };
-  }
-}
-
-async function checkNodeCount(dbPath: string): Promise<DoctorCheck> {
-  try {
-    const Database = (await import('better-sqlite3')).default;
-    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(await checkDbReadable(dbPath));
-    checks.push(await 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

@@ -1,126 +0,0 @@
-/**
- * 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 { createRequire } from 'node:module';
-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;
-
-    // createRequire, not a bare require(): this package is ESM
-    // ("type": "module"), where `require` is undefined at runtime — the
-    // eslint-disable that used to sit here silenced the lint but the call
-    // still threw "require is not defined" the moment getApp() ran.
-    // getApp() is synchronous, so `await import()` is not an option; this is
-    // the correct ESM escape hatch for a deliberately deferred load.
-    const require = createRequire(import.meta.url);
-    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

@@ -1,202 +0,0 @@
-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

@@ -1,197 +0,0 @@
-/**
- * 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;
-}