@kiyeonjeon21/datacontext 0.2.0 → 0.3.0

package/src/api/start-server.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Start DataContext REST API Server
+ * 
+ * Usage:
+ *   node dist/api/start-server.js
+ *   DATABASE_URL=sqlite:./test.db npm run serve
+ */
+
+import 'dotenv/config';
+import { createPostgresAdapter } from '../adapters/postgres.js';
+import { createSQLiteAdapter } from '../adapters/sqlite.js';
+import { createDataContextService } from '../core/context-service.js';
+import { KnowledgeStore } from '../knowledge/store.js';
+import { startApiServer } from './server.js';
+
+async function main() {
+  const port = parseInt(process.env.PORT || '3000', 10);
+  const dbUrl = process.env.DATABASE_URL || 'sqlite:./datacontext.db';
+  
+  console.log('[datacontext-api] Starting server...');
+  console.log(`[datacontext-api] Port: ${port}`);
+  console.log(`[datacontext-api] Database: ${dbUrl.split('?')[0]}`);
+
+  // Create appropriate adapter based on URL
+  let adapter;
+  if (dbUrl.startsWith('postgres://') || dbUrl.startsWith('postgresql://')) {
+    adapter = createPostgresAdapter(dbUrl);
+  } else if (dbUrl.startsWith('sqlite:')) {
+    const dbPath = dbUrl.replace('sqlite:', '');
+    adapter = createSQLiteAdapter(dbPath);
+  } else {
+    console.error('[datacontext-api] Unsupported database URL. Use postgres:// or sqlite:');
+    process.exit(1);
+  }
+
+  // Create knowledge store
+  const databaseId = dbUrl.split('/').pop()?.split('?')[0] || 'default';
+  const knowledge = new KnowledgeStore(databaseId);
+
+  // Create service
+  const service = createDataContextService({
+    adapter,
+    knowledge,
+    safety: {
+      readOnly: true,
+      timeoutMs: 30000,
+      maxRows: 1000,
+    },
+  });
+
+  // Initialize service
+  await service.initialize();
+  console.log('[datacontext-api] ✓ Service initialized');
+
+  try {
+    await startApiServer({
+      service,
+      port,
+      cors: true,
+    });
+    
+    console.log('[datacontext-api] ✓ Server started successfully');
+    console.log('[datacontext-api] ✓ API: http://localhost:' + port + '/api');
+    console.log('[datacontext-api] ✓ Health: http://localhost:' + port + '/health');
+    console.log('');
+    console.log('[datacontext-api] Press Ctrl+C to stop');
+  } catch (error) {
+    console.error('[datacontext-api] Failed to start server:', error);
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error('[datacontext-api] Fatal error:', error);
+  process.exit(1);
+});
+

package/src/cli/index.ts

@@ -282,6 +282,540 @@ function printTable(table: { name: string; schema: string; type: string; columns
   }
 }
 
+// ============================================================
+// Glossary Commands
+// ============================================================
+
+const glossaryCmd = program
+  .command('glossary')
+  .description('Manage business glossary/terms');
+
+/**
+ * List all terms
+ */
+glossaryCmd
+  .command('list')
+  .description('List all business terms in the glossary')
+  .option('--connection <string>', 'Database connection string')
+  .option('--category <cat>', 'Filter by category (status, time, money, entity, metric, filter, custom)')
+  .option('--table <table>', 'Filter by table name')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    try {
+      const knowledge = await loadKnowledgeStore(options.connection);
+      let terms = knowledge.getActiveTerms();
+
+      // Apply filters
+      if (options.category) {
+        terms = terms.filter(t => t.category === options.category);
+      }
+      if (options.table) {
+        terms = terms.filter(t => t.appliesTo?.tables?.includes(options.table));
+      }
+
+      if (options.json) {
+        console.log(JSON.stringify(terms, null, 2));
+      } else {
+        if (terms.length === 0) {
+          console.log('[datacontext] No terms found. Use "glossary add" or "glossary generate" to add terms.');
+          return;
+        }
+
+        console.log(`\n📚 Business Glossary (${terms.length} terms)\n`);
+        for (const term of terms) {
+          console.log(`  ${term.term}`);
+          console.log(`    Definition: ${term.definition}`);
+          if (term.sqlExpression) {
+            console.log(`    SQL: ${term.sqlExpression}`);
+          }
+          if (term.synonyms.length > 0) {
+            console.log(`    Synonyms: ${term.synonyms.join(', ')}`);
+          }
+          if (term.appliesTo?.tables?.length) {
+            console.log(`    Tables: ${term.appliesTo.tables.join(', ')}`);
+          }
+          if (term.category) {
+            console.log(`    Category: ${term.category}`);
+          }
+          console.log('');
+        }
+      }
+    } catch (error) {
+      console.error(`[datacontext] Error: ${error instanceof Error ? error.message : error}`);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Add a term manually
+ */
+glossaryCmd
+  .command('add')
+  .description('Add a business term to the glossary')
+  .argument('<term>', 'The business term (e.g., "활성 사용자")')
+  .argument('<definition>', 'Definition of the term')
+  .option('--sql <expression>', 'SQL expression (e.g., "status = 1")')
+  .option('--synonyms <list>', 'Comma-separated synonyms')
+  .option('--tables <list>', 'Comma-separated table names')
+  .option('--category <cat>', 'Category: status, time, money, entity, metric, filter, custom')
+  .option('--connection <string>', 'Database connection string')
+  .action(async (term: string, definition: string, options) => {
+    try {
+      const knowledge = await loadKnowledgeStore(options.connection);
+
+      const added = await knowledge.addBusinessTerm(term, definition, {
+        sqlExpression: options.sql,
+        synonyms: options.synonyms ? options.synonyms.split(',').map((s: string) => s.trim()) : undefined,
+        appliesTo: options.tables ? { tables: options.tables.split(',').map((s: string) => s.trim()) } : undefined,
+        category: options.category,
+      });
+
+      console.log(`[datacontext] ✓ Added term: "${added.term}"`);
+      if (added.sqlExpression) {
+        console.log(`[datacontext]   SQL: ${added.sqlExpression}`);
+      }
+    } catch (error) {
+      console.error(`[datacontext] Error: ${error instanceof Error ? error.message : error}`);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Search terms
+ */
+glossaryCmd
+  .command('search')
+  .description('Search for business terms')
+  .argument('<query>', 'Search query')
+  .option('--connection <string>', 'Database connection string')
+  .option('--json', 'Output as JSON')
+  .action(async (query: string, options) => {
+    try {
+      const knowledge = await loadKnowledgeStore(options.connection);
+      const terms = knowledge.findMatchingTerms(query);
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          query,
+          count: terms.length,
+          terms,
+          suggestedConditions: terms.filter(t => t.sqlExpression).map(t => t.sqlExpression),
+        }, null, 2));
+      } else {
+        if (terms.length === 0) {
+          console.log(`[datacontext] No terms found matching "${query}"`);
+          return;
+        }
+
+        console.log(`\n🔍 Search results for "${query}" (${terms.length} matches)\n`);
+        for (const term of terms) {
+          console.log(`  ${term.term}`);
+          console.log(`    ${term.definition}`);
+          if (term.sqlExpression) {
+            console.log(`    → SQL: ${term.sqlExpression}`);
+          }
+          console.log('');
+        }
+
+        const conditions = terms.filter(t => t.sqlExpression).map(t => t.sqlExpression);
+        if (conditions.length > 0) {
+          console.log('  💡 Suggested SQL conditions:');
+          for (const cond of conditions) {
+            console.log(`    ${cond}`);
+          }
+        }
+      }
+    } catch (error) {
+      console.error(`[datacontext] Error: ${error instanceof Error ? error.message : error}`);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Generate terms using AI
+ */
+glossaryCmd
+  .command('generate')
+  .description('Generate business terms from natural language using AI')
+  .argument('<terms>', 'Raw term definitions (e.g., "활성 사용자 = status가 1인 사용자, 최근 주문 = 30일 이내")')
+  .option('--connection <string>', 'Database connection string')
+  .option('--json', 'Output as JSON')
+  .action(async (rawTerms: string, options) => {
+    try {
+      // Load .env for API key
+      await import('dotenv/config');
+
+      const { isLLMAvailable, createLLMService } = await import('../core/llm-service.js');
+      
+      if (!isLLMAvailable()) {
+        console.error('[datacontext] Error: ANTHROPIC_API_KEY not configured.');
+        console.error('[datacontext] Set the environment variable or add it to .env file.');
+        process.exit(1);
+      }
+
+      const knowledge = await loadKnowledgeStore(options.connection);
+
+      console.log('[datacontext] Generating terms using AI...');
+
+      // Get schema context if connected to DB
+      type SchemaContextType = import('../core/llm-service.js').SchemaContext;
+      let schemaContext: SchemaContextType = { 
+        tables: [] as SchemaContextType['tables'], 
+        existingTerms: knowledge.getBusinessTerms() 
+      };
+      
+      if (options.connection) {
+        const adapter = createAdapter(options.connection);
+        await adapter.connect();
+        const schemaInfo = await adapter.getSchema();
+        schemaContext = {
+          tables: schemaInfo.tables.slice(0, 20).map(t => ({
+            name: t.name,
+            columns: t.columns.map(c => ({
+              name: c.name,
+              type: c.dataType,
+              nullable: c.isNullable,
+            })),
+          })),
+          existingTerms: knowledge.getBusinessTerms(),
+        };
+        await adapter.disconnect();
+      }
+
+      const llm = createLLMService();
+      const generated = await llm.generateGlossary(
+        rawTerms,
+        schemaContext,
+        knowledge.getSchemaHash()
+      );
+
+      // Save to knowledge store
+      const added = await knowledge.addBusinessTerms(generated);
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          success: true,
+          generated: added.length,
+          terms: added,
+        }, null, 2));
+      } else {
+        console.log(`\n[datacontext] ✓ Generated ${added.length} term(s)\n`);
+        for (const term of added) {
+          console.log(`  📝 ${term.term}`);
+          console.log(`     Definition: ${term.definition}`);
+          if (term.sqlExpression) {
+            console.log(`     SQL: ${term.sqlExpression}`);
+          }
+          if (term.synonyms.length > 0) {
+            console.log(`     Synonyms: ${term.synonyms.join(', ')}`);
+          }
+          console.log('');
+        }
+      }
+    } catch (error) {
+      console.error(`[datacontext] Error: ${error instanceof Error ? error.message : error}`);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Export glossary to YAML/JSON
+ */
+glossaryCmd
+  .command('export')
+  .description('Export glossary to YAML or JSON file')
+  .option('--connection <string>', 'Database connection string')
+  .option('--format <format>', 'Output format: yaml or json', 'yaml')
+  .option('--output <file>', 'Output file path (default: stdout)')
+  .action(async (options) => {
+    try {
+      const knowledge = await loadKnowledgeStore(options.connection);
+      const terms = knowledge.getActiveTerms();
+
+      if (terms.length === 0) {
+        console.error('[datacontext] No terms to export.');
+        process.exit(1);
+      }
+
+      const exportData = {
+        version: '1.0.0',
+        exportedAt: new Date().toISOString(),
+        terms: terms.map(t => ({
+          term: t.term,
+          definition: t.definition,
+          sql: t.sqlExpression,
+          synonyms: t.synonyms,
+          tables: t.appliesTo?.tables,
+          columns: t.appliesTo?.columns,
+          category: t.category,
+          examples: t.examples,
+        })),
+      };
+
+      let output: string;
+      if (options.format === 'yaml') {
+        // Simple YAML serialization
+        output = serializeToYaml(exportData);
+      } else {
+        output = JSON.stringify(exportData, null, 2);
+      }
+
+      if (options.output) {
+        const fs = await import('fs/promises');
+        await fs.writeFile(options.output, output);
+        console.log(`[datacontext] ✓ Exported ${terms.length} terms to ${options.output}`);
+      } else {
+        console.log(output);
+      }
+    } catch (error) {
+      console.error(`[datacontext] Error: ${error instanceof Error ? error.message : error}`);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Import glossary from YAML/JSON
+ */
+glossaryCmd
+  .command('import')
+  .description('Import glossary from YAML or JSON file')
+  .argument('<file>', 'Input file path')
+  .option('--connection <string>', 'Database connection string')
+  .option('--merge', 'Merge with existing terms (default: true)', true)
+  .option('--replace', 'Replace all existing terms')
+  .action(async (file: string, options) => {
+    try {
+      const fs = await import('fs/promises');
+      const content = await fs.readFile(file, 'utf-8');
+
+      let data: { terms: Array<{
+        term: string;
+        definition: string;
+        sql?: string;
+        synonyms?: string[];
+        tables?: string[];
+        columns?: string[];
+        category?: string;
+        examples?: string[];
+      }> };
+
+      if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+        data = parseYaml(content);
+      } else {
+        data = JSON.parse(content);
+      }
+
+      if (!data.terms || !Array.isArray(data.terms)) {
+        console.error('[datacontext] Error: Invalid file format. Expected "terms" array.');
+        process.exit(1);
+      }
+
+      const knowledge = await loadKnowledgeStore(options.connection);
+
+      let added = 0;
+      for (const term of data.terms) {
+        await knowledge.addBusinessTerm(term.term, term.definition, {
+          sqlExpression: term.sql,
+          synonyms: term.synonyms,
+          appliesTo: term.tables || term.columns ? {
+            tables: term.tables,
+            columns: term.columns,
+          } : undefined,
+          category: term.category as import('../knowledge/types.js').TermCategory,
+          examples: term.examples,
+        });
+        added++;
+      }
+
+      console.log(`[datacontext] ✓ Imported ${added} term(s) from ${file}`);
+    } catch (error) {
+      console.error(`[datacontext] Error: ${error instanceof Error ? error.message : error}`);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Delete a term
+ */
+glossaryCmd
+  .command('delete')
+  .description('Delete a business term')
+  .argument('<term>', 'Term name or ID to delete')
+  .option('--connection <string>', 'Database connection string')
+  .action(async (termToDelete: string, options) => {
+    try {
+      const knowledge = await loadKnowledgeStore(options.connection);
+      const terms = knowledge.getBusinessTerms();
+
+      // Find by term name or ID
+      const found = terms.find(t => t.term === termToDelete || t.id === termToDelete);
+      if (!found) {
+        console.error(`[datacontext] Error: Term "${termToDelete}" not found.`);
+        process.exit(1);
+      }
+
+      await knowledge.deleteBusinessTerm(found.id);
+      console.log(`[datacontext] ✓ Deleted term: "${found.term}"`);
+    } catch (error) {
+      console.error(`[datacontext] Error: ${error instanceof Error ? error.message : error}`);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// Helper Functions
+// ============================================================
+
+/**
+ * Load knowledge store with optional connection
+ */
+async function loadKnowledgeStore(connectionString?: string): Promise<KnowledgeStore> {
+  let databaseId = 'default';
+  
+  if (connectionString) {
+    const config = parseConnectionString(connectionString);
+    databaseId = `${config.host}_${config.database}`;
+  }
+
+  const knowledge = createKnowledgeStore(databaseId);
+  await knowledge.load();
+  return knowledge;
+}
+
+/**
+ * Simple YAML serializer for export
+ */
+function serializeToYaml(data: unknown): string {
+  const lines: string[] = [];
+  
+  function serialize(obj: unknown, indent: number = 0): void {
+    const prefix = '  '.repeat(indent);
+    
+    if (Array.isArray(obj)) {
+      for (const item of obj) {
+        if (typeof item === 'object' && item !== null) {
+          lines.push(`${prefix}-`);
+          serialize(item, indent + 1);
+        } else {
+          lines.push(`${prefix}- ${formatValue(item)}`);
+        }
+      }
+    } else if (typeof obj === 'object' && obj !== null) {
+      for (const [key, value] of Object.entries(obj)) {
+        if (value === undefined || value === null) continue;
+        
+        if (Array.isArray(value)) {
+          if (value.length === 0) continue;
+          if (typeof value[0] === 'string') {
+            lines.push(`${prefix}${key}: [${value.map(v => `"${v}"`).join(', ')}]`);
+          } else {
+            lines.push(`${prefix}${key}:`);
+            serialize(value, indent + 1);
+          }
+        } else if (typeof value === 'object') {
+          lines.push(`${prefix}${key}:`);
+          serialize(value, indent + 1);
+        } else {
+          lines.push(`${prefix}${key}: ${formatValue(value)}`);
+        }
+      }
+    }
+  }
+
+  function formatValue(val: unknown): string {
+    if (typeof val === 'string') {
+      if (val.includes('\n') || val.includes(':') || val.includes('#')) {
+        return `"${val.replace(/"/g, '\\"')}"`;
+      }
+      return val;
+    }
+    return String(val);
+  }
+
+  serialize(data);
+  return lines.join('\n');
+}
+
+/**
+ * Simple YAML parser for import
+ */
+function parseYaml(content: string): { terms: Array<{
+  term: string;
+  definition: string;
+  sql?: string;
+  synonyms?: string[];
+  tables?: string[];
+  columns?: string[];
+  category?: string;
+  examples?: string[];
+}> } {
+  const lines = content.split('\n');
+  const result: { terms: unknown[] } = { terms: [] };
+  let currentTerm: Record<string, unknown> | null = null;
+  let inTermsArray = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd();
+    if (!line || line.startsWith('#')) continue;
+
+    // Check for terms array start
+    if (line.match(/^terms:\s*$/)) {
+      inTermsArray = true;
+      continue;
+    }
+
+    if (!inTermsArray) continue;
+
+    // New term
+    if (line.match(/^\s*-\s*$/)) {
+      if (currentTerm) {
+        result.terms.push(currentTerm);
+      }
+      currentTerm = {};
+      continue;
+    }
+
+    // Property
+    const match = line.match(/^\s+(\w+):\s*(.*)$/);
+    if (match && currentTerm) {
+      const [, key, rawValue] = match;
+      let value: unknown = rawValue.trim();
+      
+      // Parse array values
+      if (typeof value === 'string' && value.startsWith('[') && value.endsWith(']')) {
+        value = value.slice(1, -1).split(',').map(s => 
+          s.trim().replace(/^["']|["']$/g, '')
+        );
+      }
+      // Remove quotes
+      if (typeof value === 'string' && (value.startsWith('"') || value.startsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      
+      currentTerm[key] = value;
+    }
+  }
+
+  if (currentTerm) {
+    result.terms.push(currentTerm);
+  }
+
+  return result as { terms: Array<{
+    term: string;
+    definition: string;
+    sql?: string;
+    synonyms?: string[];
+    tables?: string[];
+    columns?: string[];
+    category?: string;
+    examples?: string[];
+  }> };
+}
+
+// ============================================================
+// Server Commands
+// ============================================================
+
 /**
  * Serve command - Start REST API server
  */