@lon-ask/dockit 0.1.0

package/bin/commands/mcp.ts

@@ -0,0 +1,32 @@
+import { spawn } from 'node:child_process';
+
+export default function mcp(root, positional, flags) {
+  const httpPort = flags.port || process.env.DOCKIT_MCP_HTTP_PORT;
+  const useHttp = flags.http || !!httpPort;
+
+  if (useHttp) {
+    const port = httpPort || 3456;
+    console.log(`Starting Dockit MCP server (HTTP) on port ${port}...`);
+    const env = { ...process.env, DOCKIT_MCP_HTTP_PORT: String(port) };
+
+    const proc = spawn('npx', ['tsx', 'apps/server/src/mcp.ts'], {
+      cwd: root,
+      stdio: 'inherit',
+      shell: true,
+      env,
+    });
+
+    process.on('SIGINT', () => proc.kill());
+    process.on('SIGTERM', () => proc.kill());
+  } else {
+    console.log('Starting Dockit MCP server (stdio)...');
+    const proc = spawn('npx', ['tsx', 'apps/server/src/mcp.ts'], {
+      cwd: root,
+      stdio: 'inherit',
+      shell: true,
+    });
+
+    process.on('SIGINT', () => proc.kill());
+    process.on('SIGTERM', () => proc.kill());
+  }
+}

package/bin/commands/search.ts

@@ -0,0 +1,185 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { resolveConfigPath } from '../utils.js';
+
+export default async function search(root, positional, flags) {
+  let entryId = flags.entry || null;
+  let query = positional[0];
+
+  if (positional.length >= 2 && !flags.entry) {
+    entryId = positional[0];
+    query = positional.slice(1).join(' ');
+  }
+
+  if (!query) {
+    console.error('Error: search query is required');
+    console.error('Usage: dockit search [<entry>] <query> [--json] [--limit <n>] [--get-top <N>]');
+    console.error('');
+    console.error('Examples:');
+    console.error('  dockit search react "how to create a hook"');
+    console.error('  dockit search quarkus "configure cache"');
+    console.error('  dockit search "react hooks"');
+    process.exit(1);
+  }
+
+  const limit = parseInt(flags.limit || '20', 10);
+  const asJson = !!flags.json;
+  const getTop = flags['get-top'] === true ? 3 : parseInt(String(flags['get-top']), 10);
+
+  const { getDb } = await import(path.join(root, 'apps/server/src/infrastructure/persistence/sqlite/connection.js'));
+  const { SqliteEntryRepository } = await import(path.join(root, 'apps/server/src/infrastructure/persistence/sqlite/SqliteEntryRepository.js'));
+  const { SqliteSourceRepository } = await import(path.join(root, 'apps/server/src/infrastructure/persistence/sqlite/SqliteSourceRepository.js'));
+  const { SqliteBuildRepository } = await import(path.join(root, 'apps/server/src/infrastructure/persistence/sqlite/SqliteBuildRepository.js'));
+  const { SqliteEntryReadModel } = await import(path.join(root, 'apps/server/src/infrastructure/persistence/sqlite/SqliteEntryReadModel.js'));
+  const { createSearchEngine } = await import(path.join(root, 'apps/server/src/infrastructure/search/SearchEngineFactory.js'));
+  const { SearchUseCase } = await import(path.join(root, 'apps/server/src/core/usecases/SearchUseCase.js'));
+  const { loadConfig, syncConfigToDb } = await import(path.join(root, 'apps/server/src/services/configLoader.js'));
+  const { DATA_ROOT } = await import(path.join(root, 'apps/server/src/services/paths.js'));
+  const { extractTextFromHtml } = await import(path.join(root, 'apps/server/src/services/textExtractor.js'));
+
+  // Ensure DB is initialized
+  const db = getDb();
+
+  // Sync config to DB
+  const configPath = resolveConfigPath(root);
+  const config = loadConfig(configPath);
+
+  const entryRepo = new SqliteEntryRepository(db);
+  const sourceRepo = new SqliteSourceRepository(db);
+  await syncConfigToDb(config, entryRepo, sourceRepo);
+
+  const entryReadModel = new SqliteEntryReadModel(db);
+  const searchEngine = await createSearchEngine(entryReadModel, config.search?.engine);
+  const searchUseCase = new SearchUseCase(searchEngine);
+
+  let results: any[] = [];
+  let scoped = false;
+
+  if (entryId) {
+    scoped = true;
+    const entry = await entryRepo.findById(entryId);
+    if (!entry || entry.status !== 'ready') {
+      console.error(`Entry "${entryId}" not found or not built.`);
+      console.error('Run "dockit list" to see available entries.');
+      process.exit(1);
+    }
+    results = await searchUseCase.searchEntry(entryId, query, limit);
+    results = results.map((r) => ({
+      entryId,
+      ...r,
+    }));
+  } else {
+    results = await searchUseCase.globalSearch(query, limit);
+  }
+
+  if (getTop) {
+    for (let i = 0; i < Math.min(getTop, results.length); i++) {
+      const r = results[i];
+      const filePath = path.join(DATA_ROOT, r.entryId, 'bundle', r.path);
+      if (fs.existsSync(filePath)) {
+        const html = fs.readFileSync(filePath, 'utf-8');
+        r.content = extractTextFromHtml(html);
+      } else {
+        r.content = null;
+      }
+    }
+  }
+
+  if (asJson) {
+    if (getTop) {
+      const output = results.slice(0, getTop).map((r, i) => ({
+        rank: i + 1,
+        entryId: r.entryId,
+        entryName: r.entryName,
+        title: r.title,
+        path: r.path,
+        content: r.content,
+      }));
+      console.log(JSON.stringify(output, null, 2));
+    } else {
+      console.log(JSON.stringify(results, null, 2));
+    }
+  } else if (results.length === 0) {
+    console.log('No results found.');
+  } else {
+    const scope = entryId ? ` [${entryId}]` : '';
+    console.log(`Search${scope}: "${query}" — ${results.length} result(s)\n`);
+
+    if (getTop) {
+      console.log(`Showing full content for top ${Math.min(getTop, results.length)} result(s).\n`);
+
+      for (let i = 0; i < Math.min(getTop, results.length); i++) {
+        const r = results[i];
+        const entryLabel = r.entryName || r.entryId;
+        const title = r.title || '(no title)';
+
+        console.log(`[${i + 1}] [${entryLabel}] ${title}`);
+        console.log(`  Path: ${r.path || ''}`);
+        console.log('  ─────────────────────────────────────────────');
+        if (r.content) {
+          console.log(r.content);
+        } else {
+          console.log('  (content not available — entry may not be built)');
+        }
+        console.log('  ─────────────────────────────────────────────');
+        console.log('');
+      }
+    } else if (!scoped) {
+      // Global search: show top result per entry with hint to scope
+      for (const r of results) {
+        const entryLabel = r.entryName || r.entryId;
+        const title = r.title || '(no title)';
+        const snippet = r.snippet ? `\n  ${extractSnippet(query, r.snippet)}` : '';
+
+        console.log(`[${entryLabel}] ${title}`);
+        console.log(`  Path: ${r.path || ''}${snippet}`);
+        console.log('');
+      }
+
+      console.log(`Use 'dockit search <entry> "<query>"' to search within a specific entry.`);
+      console.log(`Use 'dockit search <entry> "<query>" --get-top' to fetch full content.`);
+    } else {
+      for (const r of results) {
+        const entryLabel = r.entryName || r.entryId;
+        const title = r.title || '(no title)';
+        const headings = r.headings && r.headings.length > 0 ? `\n  Headings: ${r.headings.slice(0, 3).join(' > ')}` : '';
+        const snippet = r.snippet ? `\n  ${extractSnippet(query, r.snippet)}` : '';
+
+        console.log(`[${entryLabel}] ${title}`);
+        console.log(`  Path: ${r.path || ''}${headings}${snippet}`);
+        console.log('');
+      }
+
+      console.log(`Use 'dockit search ${entryId} "<query>" --get-top [N]' to fetch full content.`);
+    }
+  }
+}
+
+function extractSnippet(query: string, fullSnippet: string, contextLength: number = 150): string {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const lower = fullSnippet.toLowerCase();
+
+  let bestStart = 0;
+  let bestScore = 0;
+
+  for (const term of terms) {
+    const idx = lower.indexOf(term);
+    if (idx !== -1) {
+      const start = Math.max(0, idx - 30);
+      const score = terms.filter((t) => lower.slice(start, start + contextLength).includes(t)).length;
+      if (score > bestScore) {
+        bestScore = score;
+        bestStart = start;
+      }
+    }
+  }
+
+  const start = Math.max(0, bestStart);
+  const end = Math.min(fullSnippet.length, start + contextLength);
+  let snippet = fullSnippet.slice(start, end).replace(/\s+/g, ' ').trim();
+
+  if (start > 0) snippet = '...' + snippet;
+  if (end < fullSnippet.length) snippet = snippet + '...';
+
+  return snippet;
+}

package/bin/commands/serve.ts

@@ -0,0 +1,23 @@
+import { spawn } from 'node:child_process';
+
+export default function serve(root, positional, flags) {
+  const port = flags.port || process.env.PORT || 3001;
+  console.log(`Starting Dockit production server on port ${port}...`);
+  console.log('');
+
+  const env = { ...process.env, PORT: String(port) };
+
+  const server = spawn('npm', ['run', 'start', '-w', 'apps/server'], {
+    cwd: root,
+    stdio: 'inherit',
+    shell: true,
+    env,
+  });
+
+  process.on('SIGINT', () => server.kill());
+  process.on('SIGTERM', () => server.kill());
+
+  server.on('close', (code) => {
+    console.log(`Server exited with code ${code}`);
+  });
+}

package/bin/commands/status.ts

@@ -0,0 +1,46 @@
+import path from 'node:path';
+
+export default async function status(root, positional, flags) {
+  const entryId = positional[0];
+  if (!entryId) {
+    console.error('Error: entry ID is required');
+    console.error('Usage: dockit status <entry>');
+    process.exit(1);
+  }
+
+  const asJson = !!flags.json;
+
+  const { getDb } = await import(path.join(root, 'apps/server/src/infrastructure/persistence/sqlite/connection.js'));
+  const { SqliteBuildRepository } = await import(path.join(root, 'apps/server/src/infrastructure/persistence/sqlite/SqliteBuildRepository.js'));
+
+  const db = getDb();
+  const buildRepo = new SqliteBuildRepository(db);
+  const build = await buildRepo.findLatest(entryId);
+
+  if (!build) {
+    if (asJson) {
+      console.log(JSON.stringify({ status: 'none', message: 'No builds found' }, null, 2));
+    } else {
+      console.log(`No builds found for entry: ${entryId}`);
+    }
+    return;
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify({
+      status: build.status,
+      startedAt: build.started_at,
+      finishedAt: build.finished_at,
+      log: build.log.slice(-2000),
+    }, null, 2));
+  } else {
+    console.log(`Entry: ${entryId}`);
+    console.log(`Status: ${build.status}`);
+    console.log(`Started: ${build.started_at}`);
+    console.log(`Finished: ${build.finished_at || 'N/A'}`);
+    console.log('');
+    console.log('Last 2000 chars of build log:');
+    console.log('---');
+    console.log(build.log.slice(-2000));
+  }
+}

package/bin/dockit-cli.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs, resolveProjectRoot } from './utils.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const { command, positional, flags } = parseArgs(process.argv);
+
+const commands = {
+  dev: () => import('./commands/dev.js'),
+  serve: () => import('./commands/serve.js'),
+  mcp: () => import('./commands/mcp.js'),
+  search: () => import('./commands/search.js'),
+  list: () => import('./commands/list.js'),
+  build: () => import('./commands/build.js'),
+  status: () => import('./commands/status.js'),
+  get: () => import('./commands/get.js'),
+  graph: () => import('./commands/graph.js'),
+  init: () => import('./commands/init.js'),
+};
+
+if (command && commands[command]) {
+  const root = resolveProjectRoot();
+  const mod = await commands[command]();
+  mod.default(root, positional, flags);
+} else if (command === 'help' || command === '--help' || command === '-h') {
+  showHelp();
+} else if (command) {
+  console.error(`Unknown command: ${command}\n`);
+  showHelp();
+  process.exit(1);
+} else {
+  showHelp();
+}
+
+function showHelp() {
+  console.log(`
+Dockit - Local documentation hub
+
+Usage:
+  dockit <command> [options]
+
+Commands:
+  dev                     Start dev servers (client + server)
+  serve [--port <port>]   Start production server
+  mcp [--http] [--port <port>]  Start MCP server
+  search [<entry>] <query>  Search documentation (scoped to entry if provided)
+    Without entry: shows top result per entry to help pick the right one
+    With entry: shows all matching results within that entry
+    --limit <n>           Max results (default 20)
+    --get-top [N]         Fetch full content for top N results (default 3)
+    --json                Output as JSON
+  list                    List all documentation entries
+    --json                Output as JSON
+  build <entry>           Build documentation for an entry
+  status <entry>          Check build status
+    --json                Output as JSON
+  get <entry> <path>      Fetch full document content
+    --json                Output as JSON
+  graph query <entry> <query>  Search knowledge graph nodes
+    --limit <n>           Max results (default 20)
+    --json                Output as JSON
+  graph path <entry> <from> <to>  Find shortest path between two nodes
+    --json                Output as JSON
+  graph gods <entry>      List most connected (god) nodes
+    --limit <n>           Max nodes (default 10)
+    --json                Output as JSON
+  graph explain <entry> <node>  Show node details and connections
+    --json                Output as JSON
+  init [--path <dir>] [--name <name>]  Initialize a project as a dockit source
+    --path <dir>          Path to source directory (default: .)
+    --name <name>         Entry name (default: directory name)
+    --version <ver>       Version string (default: 1.0)
+    --code-path <path>    Subdirectory for source code scanning (optional)
+
+Examples:
+  dockit search react "how to create a hook"
+  dockit search quarkus "configure cache"
+  dockit search "react hooks" --get-top
+  dockit search "react hooks" --get-top 3 --json
+  dockit list
+  dockit build quarkus
+  dockit status quarkus
+  dockit get react asciidoc/getting-started.html
+  dockit graph query dockit-code "SourceCodeSourceProcessor"
+  dockit graph gods dockit-code
+  dockit graph path dockit-code "BuildUseCase" "SourceCodeSourceProcessor"
+  dockit serve --port 8080
+`);
+}

package/bin/dockit.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, '..');
+
+const proc = spawn('npx', ['tsx', path.join(projectRoot, 'bin/dockit-cli.ts'), ...process.argv.slice(2)], {
+  cwd: projectRoot,
+  stdio: 'inherit',
+});
+
+proc.on('close', (code) => {
+  process.exit(code || 0);
+});

package/bin/utils.ts

@@ -0,0 +1,85 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function resolveProjectRoot() {
+  let dir = __dirname;
+  while (dir !== path.parse(dir).root) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  throw new Error('Could not find dockit project root');
+}
+
+export function resolveDockitHome(): string {
+  const home = os.homedir() || process.cwd();
+  return process.env.DOCKIT_DATA_DIR || path.join(home, '.dockit');
+}
+
+export function resolveConfigPath(root: string): string {
+  const homeConfig = path.join(resolveDockitHome(), 'dockit.yaml');
+  if (fs.existsSync(homeConfig)) return homeConfig;
+  const projectConfig = path.join(root, 'dockit.yaml');
+  if (fs.existsSync(projectConfig)) return projectConfig;
+  return homeConfig;
+}
+
+export function parseArgs(argv) {
+  const args = argv.slice(2);
+  const flags = {};
+  const positional = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith('--')) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else if (arg.startsWith('-')) {
+      const key = arg.slice(1);
+      flags[key] = true;
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { command: positional[0] || null, positional: positional.slice(1), flags };
+}
+
+export function formatTable(headers, rows) {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => String(r[i] || '').length))
+  );
+
+  const pad = (str, width) => String(str).padEnd(width);
+
+  const headerLine = headers.map((h, i) => pad(h, widths[i])).join('  ');
+  const separator = widths.map((w) => '─'.repeat(w)).join('  ');
+  const dataLines = rows.map((row) =>
+    row.map((cell, i) => pad(cell || '', widths[i])).join('  ')
+  );
+
+  return [headerLine, separator, ...dataLines].join('\n');
+}
+
+export function spawnProcess(cmd, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { cwd, stdio: 'inherit', shell: true });
+    proc.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`Process exited with code ${code}`));
+    });
+    proc.on('error', reject);
+  });
+}

package/dockit.yaml

@@ -0,0 +1,154 @@
+# Dockit - Documentation index for LLM context
+# Define your documentation entries and their sources below.
+# Run `npx tsx apps/server/src/mcp.ts` to start the MCP server.
+
+entries:
+  - id: quarkus
+    name: Quarkus
+    version: "3.35"
+    description: "Quarkus - Supersonic Subatomic Java"
+    sources:
+      - type: asciidoc
+        label: "Quarkus Docs (AsciiDoc)"
+        repoUrl: "https://github.com/quarkusio/quarkus.git"
+        sourcePath: "docs/src/main/asciidoc"
+
+  - id: quarkus-core
+    name: Quarkus Core
+    version: "3.35.2"
+    description: "Quarkus Core API"
+    sources:
+      - type: maven
+        label: "Quarkus Core Javadoc"
+        groupId: "io.quarkus"
+        artifactId: "quarkus-core"
+        version: "3.35.2"
+        classifier: "javadoc"
+
+  - id: spring-boot
+    name: Spring Boot
+    version: "3.5.x"
+    description: "Spring Boot - Production-ready Spring applications"
+    sources:
+      - type: antora
+        label: "Spring Boot Reference Docs"
+        repoUrl: "https://github.com/spring-projects/spring-boot.git"
+
+  - id: spring-framework
+    name: Spring Framework
+    version: "7.x"
+    description: "Spring Framework - The core of the Spring ecosystem"
+    sources:
+      - type: antora
+        label: "Spring Framework Reference Docs"
+        repoUrl: "https://github.com/spring-projects/spring-framework.git"
+
+  - id: react
+    name: React
+    version: "19"
+    description: "React - The library for web and native user interfaces"
+    sources:
+      - type: github-markdown
+        label: "React Docs (Markdown)"
+        repoUrl: "https://github.com/reactjs/react.dev.git"
+        sourcePath: "src/content"
+
+  # --- Local/Offline mode examples (uncomment to use) ---
+
+  # - id: quarkus-local
+  #   name: Quarkus (Local Clone)
+  #   version: "3.35"
+  #   description: "Quarkus docs from a pre-cloned repo"
+  #   sources:
+  #     - type: asciidoc
+  #       label: "Quarkus Docs (local)"
+  #       localPath: "/home/user/repos/quarkus"
+  #       sourcePath: "docs/src/main/asciidoc"
+
+  # - id: quarkus-mvn
+  #   name: Quarkus Core (Maven CLI)
+  #   version: "3.35.2"
+  #   description: "Quarkus Core via local Maven + settings.xml"
+  #   sources:
+  #     - type: maven
+  #       label: "Quarkus Core Javadoc"
+  #       groupId: "io.quarkus"
+  #       artifactId: "quarkus-core"
+  #       version: "3.35.2"
+  #       useMavenCommand: true
+
+  # - id: spring-boot-local
+  #   name: Spring Boot (Local)
+  #   version: "3.4.x"
+  #   description: "Spring Boot from a pre-cloned repo"
+  #   sources:
+  #     - type: antora
+  #       label: "Spring Boot Reference"
+  #       localPath: "/home/user/repos/spring-boot"
+  #     - type: asciidoc
+  #       label: "Spring Boot Docs"
+  #       localPath: "/home/user/repos/spring-boot"
+  #       sourcePath: "spring-boot-project/spring-boot-docs/src/docs/asciidoc"
+
+  # - id: company-docs
+  #   name: Company Docs
+  #   version: "1.0"
+  #   description: "Internal documentation"
+  #   sources:
+  #     - type: zip
+  #       label: "Docs ZIP"
+  #       localPath: "/home/user/downloads/docs.zip"
+
+  # - id: react-local
+  #   name: React (Local)
+  #   version: "19"
+  #   description: "React docs from a pre-cloned repo"
+  #   sources:
+  #     - type: github-markdown
+  #       label: "React Docs (local)"
+  #       localPath: "/home/user/repos/react.dev"
+  #       sourcePath: "src/content"
+
+  # --- Source code entries (powered by Graphify) ---
+
+  - id: quarkus-code
+    name: Quarkus Source Code
+    version: "3.35"
+    description: "Quarkus framework source code — knowledge graph"
+    sources:
+      - type: source-code
+        label: "Quarkus Core"
+        repoUrl: "https://github.com/quarkusio/quarkus.git"
+        sourcePath: "core/src/main/java"
+
+  - id: quarkus-combined
+    name: Quarkus (Docs + Code)
+    version: "3.35"
+    description: "Quarkus with searchable docs and code knowledge graph"
+    sources:
+      - type: asciidoc
+        label: "Quarkus Docs"
+        repoUrl: "https://github.com/quarkusio/quarkus.git"
+        sourcePath: "docs/src/main/asciidoc"
+      - type: source-code
+        label: "Quarkus Core"
+        repoUrl: "https://github.com/quarkusio/quarkus.git"
+        sourcePath: "core/src/main/java"
+
+  - id: dockit-code
+    name: Dockit Source Code
+    version: "1.0"
+    description: "Dockit project source code — knowledge graph"
+    sources:
+      - type: source-code
+        label: "Dockit Code"
+        localPath: "/home/karthik/projects/ai/dockit"
+        sourcePath: "apps"
+
+search:
+  engine: vector  # 'vector' (default, semantic search) | 'json' (fallback, low-resource)
+
+mcp:
+  toolPrefix: "dockit_"
+  maxSearchResults: 10
+  autoBuild: false