@lon-ask/dockit 0.1.0

package/apps/server/src/services/textExtractor.ts

@@ -0,0 +1,49 @@
+export function extractTextFromHtml(html: string, maxLength: number = 50000): string {
+  const withoutStyles = html
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+    .replace(/<link[^>]*>/gi, '')
+    .replace(/<meta[^>]*>/gi, '');
+
+  const withoutTags = withoutStyles
+    .replace(/<h1[^>]*>/gi, '\n\n## ')
+    .replace(/<\/h1>/gi, '\n')
+    .replace(/<h2[^>]*>/gi, '\n\n### ')
+    .replace(/<\/h2>/gi, '\n')
+    .replace(/<h3[^>]*>/gi, '\n\n#### ')
+    .replace(/<\/h3>/gi, '\n')
+    .replace(/<h4[^>]*>/gi, '\n\n**')
+    .replace(/<\/h4>/gi, '**\n')
+    .replace(/<li[^>]*>/gi, '\n- ')
+    .replace(/<\/li>/gi, '')
+    .replace(/<\/?p[^>]*>/gi, '\n\n')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<hr\s*\/?>/gi, '\n---\n')
+    .replace(/<\/?pre[^>]*>/gi, '\n```\n')
+    .replace(/<\/?code[^>]*>/gi, '`')
+    .replace(/<a[^>]*href="([^"]*)"[^>]*>/gi, ' [$1] ')
+    .replace(/<\/a>/gi, '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&#x2F;/g, '/')
+    .replace(/&#(\d+);/g, (_, d) => String.fromCharCode(Number(d)));
+
+  const cleaned = withoutTags
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/[ \t]{3,}/g, '  ')
+    .trim();
+
+  if (cleaned.length <= maxLength) return cleaned;
+
+  const truncated = cleaned.slice(0, maxLength);
+  const lastNewline = truncated.lastIndexOf('\n');
+  const cutPoint = lastNewline > maxLength * 0.8 ? lastNewline : truncated.lastIndexOf(' ');
+  const final = cutPoint > maxLength * 0.8 ? truncated.slice(0, cutPoint) : truncated;
+
+  return final + '\n\n[... content truncated ...]';
+}

package/apps/server/src/services/zip.ts

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import unzipper from 'unzipper';
+import type { ZipSourceConfig } from '../core/domain/types.js';
+
+export async function extractLocalZip(
+  localPath: string,
+  targetDir: string,
+  log: (msg: string) => void
+): Promise<void> {
+  if (!fs.existsSync(localPath)) {
+    throw new Error(`Local file not found: ${localPath}`);
+  }
+  const stat = fs.statSync(localPath);
+  if (!stat.isFile()) {
+    throw new Error(`localPath must be a ZIP file, got directory: ${localPath}`);
+  }
+
+  log(`Extracting local ZIP from ${localPath}`);
+  fs.mkdirSync(targetDir, { recursive: true });
+  const data = fs.readFileSync(localPath);
+  const stream = Readable.from(data);
+  await pipeline(stream, unzipper.Extract({ path: targetDir }));
+  log(`Extracted ZIP to ${targetDir}`);
+  const files = countFilesRecursive(targetDir);
+  log(`Found ${files} files in extracted archive`);
+}
+
+export async function downloadAndExtractZip(
+  configOrUrl: ZipSourceConfig | string,
+  targetDir: string,
+  log: (msg: string) => void
+): Promise<void> {
+  const config = typeof configOrUrl === 'string'
+    ? { url: configOrUrl }
+    : configOrUrl;
+
+  if (config.localPath) {
+    await extractLocalZip(config.localPath, targetDir, log);
+    return;
+  }
+
+  if (!config.url) {
+    throw new Error('ZIP source requires url or localPath');
+  }
+
+  log(`Downloading ZIP from ${config.url}`);
+  const response = await fetch(config.url);
+  if (!response.ok) {
+    throw new Error(`Failed to download ZIP: ${response.status} ${response.statusText}`);
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  if (!response.body) {
+    throw new Error('No response body');
+  }
+
+  const nodeStream = Readable.fromWeb(response.body as never);
+  await pipeline(
+    nodeStream,
+    unzipper.Extract({ path: targetDir })
+  );
+
+  log(`Extracted ZIP to ${targetDir}`);
+  const files = countFilesRecursive(targetDir);
+  log(`Found ${files} files in extracted archive`);
+}
+
+function countFilesRecursive(dir: string): number {
+  let count = 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      count += countFilesRecursive(fullPath);
+    } else {
+      count++;
+    }
+  }
+  return count;
+}

package/bin/commands/build.ts

@@ -0,0 +1,85 @@
+import path from 'node:path';
+import { resolveConfigPath } from '../utils.js';
+
+export default async function build(root, positional, flags) {
+  const entryId = positional[0];
+  if (!entryId) {
+    console.error('Error: entry ID is required');
+    console.error('Usage: dockit build <entry>');
+    process.exit(1);
+  }
+
+  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 { ConfigUseCase } = await import(path.join(root, 'apps/server/src/core/usecases/ConfigUseCase.js'));
+  const { BuildUseCase } = await import(path.join(root, 'apps/server/src/core/usecases/BuildUseCase.js'));
+  const { ZipSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/ZipSourceProcessor.js'));
+  const { AntoraSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/AntoraSourceProcessor.js'));
+  const { AsciidocSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/AsciidocSourceProcessor.js'));
+  const { MavenSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/MavenSourceProcessor.js'));
+  const { GithubMarkdownSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/GithubMarkdownSourceProcessor.js'));
+  const { SourceCodeSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/SourceCodeSourceProcessor.js'));
+  const { DocumentNormalizer } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/DocumentNormalizer.js'));
+  const { PathResolver } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/PathResolver.js'));
+  const { loadConfig, syncConfigToDb } = await import(path.join(root, 'apps/server/src/services/configLoader.js'));
+
+  // Ensure DB is initialized (getDb calls initDb internally)
+  const db = getDb();
+
+  const entryRepo = new SqliteEntryRepository(db);
+  const sourceRepo = new SqliteSourceRepository(db);
+  const buildRepo = new SqliteBuildRepository(db);
+
+  // Sync config to DB
+  const configPath = resolveConfigPath(root);
+  const config = loadConfig(configPath);
+  syncConfigToDb(config, entryRepo, sourceRepo);
+  const entryReadModel = new SqliteEntryReadModel(db);
+  const searchEngine = await createSearchEngine(entryReadModel, config.search?.engine);
+
+  const configUseCase = new ConfigUseCase(entryRepo, sourceRepo);
+
+  const processors = [
+    new ZipSourceProcessor(),
+    new AntoraSourceProcessor(),
+    new AsciidocSourceProcessor(),
+    new MavenSourceProcessor(),
+    new GithubMarkdownSourceProcessor(),
+    new SourceCodeSourceProcessor(),
+  ];
+  const documentNormalizer = new DocumentNormalizer();
+  const pathResolver = new PathResolver();
+
+  const buildUseCase = new BuildUseCase(
+    buildRepo, sourceRepo, entryRepo, searchEngine,
+    processors, documentNormalizer, pathResolver,
+  );
+
+  const entry = await configUseCase.getEntry(entryId);
+
+  if (!entry) {
+    console.error(`Entry not found: ${entryId}`);
+    process.exit(1);
+  }
+
+  const entryWithSources = await configUseCase.getEntryWithSources(entryId);
+  const sources = entryWithSources?.sources || [];
+  if (sources.length === 0) {
+    console.error(`Entry "${entry.name}" has no sources configured.`);
+    process.exit(1);
+  }
+
+  console.log(`Building documentation for ${entry.name} ${entry.version}...`);
+  console.log('');
+
+  const result = await buildUseCase.build(entryId);
+  console.log(`Build ${entryId}: ${result.status}`);
+  if (result.status === 'error') {
+    console.error(result.log);
+    process.exit(1);
+  }
+}

package/bin/commands/dev.ts

@@ -0,0 +1,36 @@
+import { spawn } from 'node:child_process';
+
+export default function dev(root, positional, flags) {
+  console.log('Starting Dockit dev servers...');
+  console.log('');
+
+  const server = spawn('npm', ['run', 'dev:server'], {
+    cwd: root,
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  const client = spawn('npm', ['run', 'dev:client'], {
+    cwd: root,
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  const cleanup = () => {
+    server.kill();
+    client.kill();
+  };
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  server.on('close', (code) => {
+    console.log(`Server exited with code ${code}`);
+    cleanup();
+  });
+
+  client.on('close', (code) => {
+    console.log(`Client exited with code ${code}`);
+    cleanup();
+  });
+}

package/bin/commands/get.ts

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import fs from 'node:fs';
+
+export default async function getDoc(root, positional, flags) {
+  const entryId = positional[0];
+  const docPath = positional[1];
+
+  if (!entryId || !docPath) {
+    console.error('Error: entry ID and document path are required');
+    console.error('Usage: dockit get <entry> <path>');
+    console.error('Example: dockit get react asciidoc/getting-started.html');
+    process.exit(1);
+  }
+
+  const asJson = !!flags.json;
+
+  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'));
+
+  const filePath = path.join(DATA_ROOT, entryId, 'bundle', docPath);
+
+  if (!fs.existsSync(filePath)) {
+    console.error(`Document not found: ${docPath}`);
+    console.error(`Has the entry "${entryId}" been built?`);
+    process.exit(1);
+  }
+
+  const html = fs.readFileSync(filePath, 'utf-8');
+  const text = extractTextFromHtml(html);
+
+  if (asJson) {
+    console.log(JSON.stringify({ entryId, path: docPath, content: text }, null, 2));
+  } else {
+    console.log(text);
+  }
+}

package/bin/commands/graph.ts

@@ -0,0 +1,153 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { formatTable } from '../utils.js';
+
+const SUBCOMMANDS = ['query', 'path', 'gods', 'explain'];
+
+export default async function graph(root, positional, flags) {
+  const sub = positional[0];
+  if (!sub || !SUBCOMMANDS.includes(sub)) {
+    console.error('Usage: dockit graph <query|path|gods|explain> <entry> [args...]');
+    console.error('');
+    console.error('Commands:');
+    console.error('  dockit graph query <entry> <query>     Search graph nodes by name, file, or type');
+    console.error('  dockit graph path <entry> <from> <to>  Find shortest dependency path between two nodes');
+    console.error('  dockit graph gods <entry>               List most connected nodes');
+    console.error('  dockit graph explain <entry> <node>     Get node details with edges and connections');
+    process.exit(1);
+  }
+
+  const entry = positional[1];
+  if (!entry) {
+    console.error('Error: entry ID is required');
+    console.error(`Usage: dockit graph ${sub} <entry> ...`);
+    process.exit(1);
+  }
+
+  const { GraphifyKnowledgeGraph } = await import(path.join(root, 'apps/server/src/infrastructure/graph/GraphifyKnowledgeGraph.js'));
+  const { DATA_ROOT } = await import(path.join(root, 'apps/server/src/services/paths.js'));
+
+  const kg = new GraphifyKnowledgeGraph(path.join(DATA_ROOT, entry));
+
+  if (!kg.exists()) {
+    console.error(`No knowledge graph found for entry "${entry}". Build the entry first.`);
+    process.exit(1);
+  }
+
+  const asJson = !!flags.json;
+
+  switch (sub) {
+    case 'query': {
+      const query = positional.slice(2).join(' ');
+      if (!query) {
+        console.error('Error: query string is required');
+        console.error(`Usage: dockit graph query ${entry} \"<query>\"`);
+        process.exit(1);
+      }
+      const limit = parseInt(flags.limit || '20', 10);
+      const result = kg.query(query, limit);
+      if (asJson) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Query: "${query}" — ${result.totalNodes} node(s), ${result.totalEdges} edge(s) found\n`);
+        if (result.nodes.length === 0) {
+          console.log('No matching nodes.');
+        } else {
+          const rows = result.nodes.map((n) => [
+            n.name.slice(0, 40),
+            n.type.slice(0, 12),
+            n.file.slice(0, 50),
+          ]);
+          console.log(formatTable(['Name', 'Type', 'File'], rows));
+        }
+      }
+      break;
+    }
+
+    case 'path': {
+      const from = positional[2];
+      const to = positional[3];
+      if (!from || !to) {
+        console.error('Error: from and to node names are required');
+        console.error(`Usage: dockit graph path ${entry} <from> <to>`);
+        process.exit(1);
+      }
+      const result = kg.findPath(from, to);
+      if (asJson) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        if (result.found) {
+          console.log(`Path found (length: ${result.length}):`);
+          result.nodes.forEach((n, i) => {
+            const prefix = i === 0 ? '  Start' : i === result.nodes.length - 1 ? '  End  ' : '  ->   ';
+            console.log(`${prefix} ${n.name}  (${n.file})`);
+          });
+        } else {
+          console.log(`No path found between "${from}" and "${to}".`);
+        }
+      }
+      break;
+    }
+
+    case 'gods': {
+      const limit = parseInt(flags.limit || '10', 10);
+      const nodes = kg.findGodNodes(limit);
+      const meta = kg.getMetadata();
+      if (asJson) {
+        console.log(JSON.stringify({ nodes, metadata: meta }, null, 2));
+      } else {
+        console.log(`Top ${nodes.length} most connected nodes (${meta.nodeCount} total nodes):\n`);
+        const rows = nodes.map((n) => [
+          n.name.slice(0, 40),
+          String(n.degree ?? 0),
+          n.file.slice(0, 50),
+        ]);
+        console.log(formatTable(['Name', 'Degree', 'File'], rows));
+      }
+      break;
+    }
+
+    case 'explain': {
+      const nodeName = positional.slice(2).join(' ');
+      if (!nodeName) {
+        console.error('Error: node name is required');
+        console.error(`Usage: dockit graph explain ${entry} <node>`);
+        process.exit(1);
+      }
+      const queryResult = kg.query(nodeName);
+      const node = queryResult.nodes[0] || null;
+      if (asJson) {
+        const result = {
+          node,
+          connectedNodes: queryResult.nodes.slice(1, 11),
+          edges: queryResult.edges.filter((e) => e.source === node?.id || e.target === node?.id).slice(0, 20),
+          totalConnections: queryResult.totalEdges,
+        };
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        if (!node) {
+          console.log(`Node "${nodeName}" not found.`);
+        } else {
+          console.log(`Node: ${node.name}`);
+          console.log(`  Type: ${node.type}`);
+          console.log(`  File: ${node.file}`);
+          if (node.community !== undefined) console.log(`  Community: ${node.community}`);
+          console.log('');
+          const nodeEdges = queryResult.edges.filter((e) => e.source === node.id || e.target === node.id);
+          if (nodeEdges.length > 0) {
+            console.log(`Connections (${nodeEdges.length}):`);
+            nodeEdges.slice(0, 20).forEach((e) => {
+              const direction = e.source === node.id ? '->' : '<-';
+              const other = e.source === node.id ? e.target : e.source;
+              console.log(`  ${node.name} ${direction} ${other}  [${e.type}]`);
+            });
+            if (nodeEdges.length > 20) console.log(`  ... and ${nodeEdges.length - 20} more`);
+          } else {
+            console.log('No connections.');
+          }
+        }
+      }
+      break;
+    }
+  }
+}

package/bin/commands/init.ts

@@ -0,0 +1,170 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { load as loadYaml, dump as dumpYaml } from 'js-yaml';
+import { resolveDockitHome, resolveConfigPath } from '../utils.js';
+
+export default async function init(root, positional, flags) {
+  const sourcePath = path.resolve(flags.path || flags.dir || '.');
+  const name = flags.name || path.basename(sourcePath);
+  const version = flags.version || '1.0';
+  const codePath = flags['code-path'] || '';
+  const entryId = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'project';
+
+  if (!fs.existsSync(sourcePath)) {
+    console.error(`Path not found: ${sourcePath}`);
+    process.exit(1);
+  }
+  if (!fs.statSync(sourcePath).isDirectory()) {
+    console.error(`Path must be a directory: ${sourcePath}`);
+    process.exit(1);
+  }
+
+  console.log(`Initializing dockit for ${name} ${version}`);
+  console.log(`  Source: ${sourcePath}`);
+  console.log(`  Entry:  ${entryId}`);
+  console.log('');
+
+  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 { ConfigUseCase } = await import(path.join(root, 'apps/server/src/core/usecases/ConfigUseCase.js'));
+  const { BuildUseCase } = await import(path.join(root, 'apps/server/src/core/usecases/BuildUseCase.js'));
+  const { GithubMarkdownSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/GithubMarkdownSourceProcessor.js'));
+  const { SourceCodeSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/SourceCodeSourceProcessor.js'));
+  const { DocumentNormalizer } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/DocumentNormalizer.js'));
+  const { PathResolver } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/PathResolver.js'));
+  const { ZipSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/ZipSourceProcessor.js'));
+  const { AntoraSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/AntoraSourceProcessor.js'));
+  const { AsciidocSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/AsciidocSourceProcessor.js'));
+  const { MavenSourceProcessor } = await import(path.join(root, 'apps/server/src/infrastructure/source-processors/MavenSourceProcessor.js'));
+  const { loadConfig } = await import(path.join(root, 'apps/server/src/services/configLoader.js'));
+
+  const db = getDb();
+  const entryRepo = new SqliteEntryRepository(db);
+  const sourceRepo = new SqliteSourceRepository(db);
+  const buildRepo = new SqliteBuildRepository(db);
+  const configUseCase = new ConfigUseCase(entryRepo, sourceRepo);
+
+  const existing = await configUseCase.getEntry(entryId);
+  if (existing) {
+    console.log(`Removing existing entry "${entryId}"...`);
+    const sources = await sourceRepo.findByEntryId(entryId);
+    for (const s of sources) await sourceRepo.delete(s.id);
+    await entryRepo.delete(entryId);
+  }
+
+  const now = new Date().toISOString();
+  await entryRepo.save({
+    id: entryId, name, version,
+    description: `${name} source code and documentation`,
+    status: 'pending', created_at: now, updated_at: now,
+  });
+
+  const label = path.basename(sourcePath);
+  const sourceCodeId = `${entryId}-src-code`;
+  const markdownId = `${entryId}-src-md`;
+
+  await sourceRepo.save({
+    id: sourceCodeId, entry_id: entryId,
+    type: 'source-code', label: `${label} Code`,
+    config: { localPath: sourcePath, sourcePath: codePath || undefined },
+    status: 'pending', created_at: now,
+  });
+  console.log(`  + Source Code: ${codePath ? path.join(sourcePath, codePath) : sourcePath}`);
+
+  await sourceRepo.save({
+    id: markdownId, entry_id: entryId,
+    type: 'github-markdown', label: `${label} Markdown`,
+    config: { localPath: sourcePath },
+    status: 'pending', created_at: now,
+  });
+  console.log(`  + Markdown Docs: ${sourcePath}`);
+
+  console.log('');
+  console.log('Building...');
+  console.log('');
+
+  const dockitHome = resolveDockitHome();
+  fs.mkdirSync(dockitHome, { recursive: true });
+
+  let searchEngineType: 'json' | 'vector' | undefined;
+  try {
+    const configPath = resolveConfigPath(root);
+    const config = loadConfig(configPath);
+    searchEngineType = config.search?.engine;
+  } catch {
+    // No config file yet, use defaults
+  }
+  const entryReadModel = new SqliteEntryReadModel(db);
+  const searchEngine = await createSearchEngine(entryReadModel, searchEngineType);
+
+  const processors = [
+    new ZipSourceProcessor(),
+    new AntoraSourceProcessor(),
+    new AsciidocSourceProcessor(),
+    new MavenSourceProcessor(),
+    new GithubMarkdownSourceProcessor(),
+    new SourceCodeSourceProcessor(),
+  ];
+  const documentNormalizer = new DocumentNormalizer();
+  const pathResolver = new PathResolver();
+  const buildUseCase = new BuildUseCase(
+    buildRepo, sourceRepo, entryRepo, searchEngine,
+    processors, documentNormalizer, pathResolver,
+  );
+
+  const result = await buildUseCase.build(entryId);
+  console.log(`Build ${entryId}: ${result.status}`);
+  if (result.status === 'error') {
+    console.error(result.log);
+    process.exit(1);
+  }
+
+  // Write entry config to dockit home
+  const homeConfigPath = path.join(dockitHome, 'dockit.yaml');
+  const entryYamlObj: Record<string, unknown> = {
+    id: entryId,
+    name,
+    version,
+    description: `${name} source code and documentation`,
+    sources: [
+      {
+        type: 'source-code',
+        label: `${label} Code`,
+        localPath: sourcePath,
+        ...(codePath ? { sourcePath: codePath } : {}),
+      },
+      {
+        type: 'github-markdown',
+        label: `${label} Markdown`,
+        localPath: sourcePath,
+      },
+    ],
+  };
+
+  if (fs.existsSync(homeConfigPath)) {
+    const existing = loadYaml(fs.readFileSync(homeConfigPath, 'utf-8')) as Record<string, unknown>;
+    const entries = (existing.entries as Record<string, unknown>[]) || [];
+    const existingIdx = entries.findIndex((e) => e.id === entryId);
+    if (existingIdx !== -1) {
+      entries[existingIdx] = entryYamlObj;
+    } else {
+      entries.push(entryYamlObj);
+    }
+    existing.entries = entries;
+    fs.writeFileSync(homeConfigPath, dumpYaml(existing, { noRefs: true }));
+  } else {
+    fs.writeFileSync(homeConfigPath, dumpYaml({ entries: [entryYamlObj] }, { noRefs: true }));
+  }
+
+  console.log('');
+  console.log(`Entry "${name}" (${entryId}) is ready.`);
+  console.log('');
+  console.log('Search docs:  dockit search ' + entryId + ' "<query>"');
+  console.log('Graph query:  dockit graph query ' + entryId + ' "<query>"');
+  console.log('God nodes:    dockit graph gods ' + entryId);
+  console.log('Web UI:       http://localhost:5173/entries/' + entryId);
+}

package/bin/commands/list.ts

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import { formatTable } from '../utils.js';
+
+export default async function list(root, positional, flags) {
+  const asJson = !!flags.json;
+
+  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 db = getDb();
+  const entryRepo = new SqliteEntryRepository(db);
+  const sourceRepo = new SqliteSourceRepository(db);
+
+  const entries = await entryRepo.findAll();
+
+  const output = [];
+  for (const e of entries) {
+    const sources = await sourceRepo.findByEntryId(e.id);
+    output.push({
+      id: e.id,
+      name: e.name,
+      version: e.version,
+      description: e.description,
+      status: e.status,
+      sourceCount: sources.length,
+    });
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify(output, null, 2));
+  } else if (output.length === 0) {
+    console.log('No documentation entries found.');
+  } else {
+    const headers = ['Name', 'Version', 'Status', 'Sources', 'ID'];
+    const rows = output.map((e) => [
+      e.name,
+      e.version,
+      e.status,
+      String(e.sourceCount),
+      e.id,
+    ]);
+
+    console.log(formatTable(headers, rows));
+    console.log(`\n${output.length} entry/entries.`);
+  }
+}