@operor/cli 0.1.0

package/src/commands/history.ts

@@ -0,0 +1,60 @@
+import { Command } from 'commander';
+import { createInterface } from 'node:readline';
+import { readConfig, configExists } from '../config.js';
+
+export function registerHistoryCommand(program: Command): void {
+  const history = program.command('history').description('Conversation history management');
+
+  history
+    .command('clear')
+    .description('Clear conversation history from the memory database')
+    .option('--customer <id>', 'Clear history for a specific customer ID')
+    .option('--agent <name>', 'Clear history for a specific agent')
+    .option('--all', 'Clear all conversation history')
+    .option('--yes', 'Skip confirmation prompt')
+    .action(async (opts: { customer?: string; agent?: string; all?: boolean; yes?: boolean }) => {
+      if (!opts.customer && !opts.agent && !opts.all) {
+        console.error('Specify --customer <id>, --agent <name>, --all, or a combination.');
+        process.exit(1);
+      }
+
+      if (!configExists()) {
+        console.error('.env file not found. Run "operor setup" first.');
+        process.exit(1);
+      }
+
+      const config = readConfig();
+      if (config.MEMORY_TYPE !== 'sqlite') {
+        console.error('History clear requires SQLite memory (MEMORY_TYPE=sqlite).');
+        process.exit(1);
+      }
+
+      const { SQLiteMemory } = await import('@operor/memory');
+      const memory = new SQLiteMemory(config.MEMORY_DB_PATH || './operor.db');
+      await memory.initialize();
+
+      try {
+        const scope = opts.all
+          ? 'ALL conversation history'
+          : `history for ${[opts.customer && `customer=${opts.customer}`, opts.agent && `agent=${opts.agent}`].filter(Boolean).join(', ')}`;
+
+        if (!opts.yes) {
+          const rl = createInterface({ input: process.stdin, output: process.stdout });
+          const answer = await new Promise<string>(r => rl.question(`Delete ${scope}? Type "yes" to confirm: `, r));
+          rl.close();
+          if (answer.trim().toLowerCase() !== 'yes') {
+            console.log('Aborted.');
+            return;
+          }
+        }
+
+        const { deletedCount } = await memory.clearHistory(
+          opts.all ? undefined : opts.customer,
+          opts.agent,
+        );
+        console.log(`Deleted ${deletedCount} message(s).`);
+      } finally {
+        await memory.close();
+      }
+    });
+}

package/src/commands/init.ts

@@ -0,0 +1,163 @@
+import { Command } from 'commander';
+import * as clack from '@clack/prompts';
+import { readdir, cp, mkdir, access } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function getTemplatesDir(): string {
+  // Walk up from __dirname to find templates/agents — works from both
+  // dist/index.js (production bundle) and src/commands/init.ts (dev)
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    const candidate = join(dir, 'templates', 'agents');
+    if (existsSync(candidate)) return candidate;
+    dir = dirname(dir);
+  }
+  throw new Error('Could not find templates directory. Ensure packages/cli/templates/agents/ exists.');
+}
+
+const TEMPLATES = ['customer-support', 'sales', 'faq-bot'] as const;
+type TemplateName = (typeof TEMPLATES)[number];
+
+async function copyDir(src: string, dest: string): Promise<void> {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await cp(srcPath, destPath);
+    }
+  }
+}
+
+async function dirExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function runInit(templateArg?: string): Promise<void> {
+  clack.intro('Operor — Initialize Agent');
+
+  const templatesDir = getTemplatesDir();
+  let template: TemplateName;
+
+  if (templateArg && TEMPLATES.includes(templateArg as TemplateName)) {
+    template = templateArg as TemplateName;
+  } else if (templateArg === 'blank') {
+    // Blank template: just create the directory structure
+    const name = await clack.text({
+      message: 'Agent name:',
+      placeholder: 'my-agent',
+      validate: (v) => (v.length === 0 ? 'Name is required' : undefined),
+    });
+    if (clack.isCancel(name)) { clack.cancel('Cancelled.'); process.exit(0); }
+
+    const agentDir = join(process.cwd(), 'agents', name as string);
+    if (await dirExists(agentDir)) {
+      clack.log.error(`Directory already exists: agents/${name}`);
+      process.exit(1);
+    }
+
+    await mkdir(agentDir, { recursive: true });
+
+    // Copy defaults if available
+    const defaultsDir = join(templatesDir, '_defaults');
+    if (await dirExists(defaultsDir)) {
+      const defaultsTarget = join(process.cwd(), 'agents', '_defaults');
+      if (!(await dirExists(defaultsTarget))) {
+        await copyDir(defaultsDir, defaultsTarget);
+        clack.log.info('Created agents/_defaults/');
+      }
+    }
+
+    clack.log.success(`Created blank agent at agents/${name}/`);
+    clack.log.info('Add INSTRUCTIONS.md, IDENTITY.md, and SOUL.md to configure your agent.');
+    clack.outro('Done!');
+    return;
+  } else {
+    // Prompt user to choose a template
+    const choice = await clack.select({
+      message: 'Choose a template:',
+      options: [
+        { value: 'customer-support', label: 'Customer Support', hint: 'E-commerce support with Shopify' },
+        { value: 'sales', label: 'Sales', hint: 'Lead qualification and demo booking' },
+        { value: 'faq-bot', label: 'FAQ Bot', hint: 'Simple knowledge base Q&A' },
+        { value: 'blank', label: 'Blank', hint: 'Empty agent directory' },
+      ],
+    });
+    if (clack.isCancel(choice)) { clack.cancel('Cancelled.'); process.exit(0); }
+
+    if (choice === 'blank') {
+      await runInit('blank');
+      return;
+    }
+    template = choice as TemplateName;
+  }
+
+  // Ask for agent name
+  const name = await clack.text({
+    message: 'Agent name:',
+    placeholder: template,
+    defaultValue: template,
+    validate: (v) => (v.length === 0 ? 'Name is required' : undefined),
+  });
+  if (clack.isCancel(name)) { clack.cancel('Cancelled.'); process.exit(0); }
+
+  const agentName = name as string;
+  const agentDir = join(process.cwd(), 'agents', agentName);
+
+  if (await dirExists(agentDir)) {
+    clack.log.error(`Directory already exists: agents/${agentName}`);
+    process.exit(1);
+  }
+
+  const templateDir = join(templatesDir, template);
+  if (!(await dirExists(templateDir))) {
+    clack.log.error(`Template not found: ${template}`);
+    process.exit(1);
+  }
+
+  // Copy template files
+  await copyDir(templateDir, agentDir);
+  clack.log.success(`Created agent from "${template}" template at agents/${agentName}/`);
+
+  // Copy defaults if they don't already exist
+  const defaultsDir = join(templatesDir, '_defaults');
+  if (await dirExists(defaultsDir)) {
+    const defaultsTarget = join(process.cwd(), 'agents', '_defaults');
+    if (!(await dirExists(defaultsTarget))) {
+      await copyDir(defaultsDir, defaultsTarget);
+      clack.log.info('Created agents/_defaults/');
+    }
+  }
+
+  // Copy USER.md to workspace root if it doesn't exist
+  // AgentLoader reads USER.md from the workspace root, not agents/
+  const userMdSrc = join(templatesDir, '_defaults', 'USER.md');
+  const userMdDest = join(process.cwd(), 'USER.md');
+  if (await dirExists(userMdSrc) && !(await dirExists(userMdDest))) {
+    await cp(userMdSrc, userMdDest);
+    clack.log.info('Created USER.md');
+  }
+
+  clack.outro('Done! Edit the files in agents/' + agentName + '/ to customize your agent.');
+}
+
+export function registerInitCommand(program: Command): void {
+  program
+    .command('init [template]')
+    .description('Initialize a new agent from a template (customer-support, sales, faq-bot, blank)')
+    .action(async (template?: string) => {
+      await runInit(template);
+    });
+}

package/src/commands/kb.ts

@@ -0,0 +1,429 @@
+import { Command } from 'commander';
+import * as clack from '@clack/prompts';
+import { readConfig, configExists } from '../config.js';
+
+function getKBConfig() {
+  if (!configExists()) {
+    clack.log.error('.env file not found. Run "operor setup" first.');
+    process.exit(1);
+  }
+  const config = readConfig();
+  if (config.KB_ENABLED !== 'true') {
+    clack.log.error('Knowledge Base is not enabled. Run "operor setup" or set KB_ENABLED=true.');
+    process.exit(1);
+  }
+  return config;
+}
+
+async function loadKB(config: ReturnType<typeof readConfig>) {
+  try {
+    const {
+      SQLiteKnowledgeStore,
+      EmbeddingService,
+      TextChunker,
+      IngestionPipeline,
+      RetrievalPipeline,
+      UrlIngestor,
+      FileIngestor,
+      SiteCrawler,
+    } = await import('@operor/knowledge');
+
+    const embeddings = new EmbeddingService({
+      provider: (config.KB_EMBEDDING_PROVIDER as 'openai' | 'google' | 'mistral' | 'cohere' | 'ollama') || 'openai',
+      apiKey: config.KB_EMBEDDING_API_KEY,
+      model: config.KB_EMBEDDING_MODEL,
+    });
+
+    const store = new SQLiteKnowledgeStore(
+      config.KB_DB_PATH || './knowledge.db',
+      embeddings.dimensions,
+    );
+    await store.initialize();
+
+    const chunker = new TextChunker({
+      chunkSize: config.KB_CHUNK_SIZE ? parseInt(config.KB_CHUNK_SIZE) : undefined,
+      chunkOverlap: config.KB_CHUNK_OVERLAP ? parseInt(config.KB_CHUNK_OVERLAP) : undefined,
+    });
+
+    // Create LLM provider for Q&A extraction during ingestion (if configured)
+    let llmProvider: any;
+    if (config.LLM_PROVIDER && config.LLM_API_KEY) {
+      const { AIProvider } = await import('@operor/llm');
+      llmProvider = new AIProvider({
+        provider: config.LLM_PROVIDER as any,
+        apiKey: config.LLM_API_KEY,
+        model: config.LLM_MODEL,
+      });
+    }
+
+    const ingestion = new IngestionPipeline(store, embeddings, chunker, llmProvider);
+    const retrieval = new RetrievalPipeline(store, embeddings);
+    const crawl4aiUrl = config.CRAWL4AI_URL || undefined;
+    const urlIngestor = new UrlIngestor(ingestion, { crawl4aiUrl });
+    const fileIngestor = new FileIngestor(ingestion);
+    const siteCrawler = new SiteCrawler(ingestion, { crawl4aiUrl });
+
+    return { store, embeddings, ingestion, retrieval, urlIngestor, fileIngestor, siteCrawler };
+  } catch {
+    clack.log.error(
+      '@operor/knowledge package not found. Install it first:\n  pnpm add @operor/knowledge'
+    );
+    process.exit(1);
+  }
+}
+
+export function registerKBCommand(program: Command): void {
+  const kb = program.command('kb').description('Knowledge Base management');
+
+  kb.command('add-url')
+    .description('Ingest a URL into the knowledge base')
+    .argument('<url>', 'URL to ingest')
+    .option('--priority <n>', 'Document priority (1=official, 2=supplementary, 3=archived)', '2')
+    .option('--extract-qa', 'Use LLM to extract Q&A pairs instead of chunking')
+    .action(async (url: string, opts: { priority: string; extractQa?: boolean }) => {
+      clack.intro('KB — Add URL');
+      const config = getKBConfig();
+      const { store, urlIngestor } = await loadKB(config);
+
+      const spinner = clack.spinner();
+      spinner.start(`Fetching and ingesting ${url}`);
+      try {
+        const doc = await urlIngestor.ingestUrl(url, {
+          priority: parseInt(opts.priority),
+          extractQA: opts.extractQa,
+        });
+        spinner.stop(`Ingested: ${doc.title || url}`);
+        clack.log.success(`Document ID: ${doc.id}`);
+      } catch (error: any) {
+        spinner.stop(`Failed to ingest URL`);
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        store.close();
+      }
+      clack.outro('Done');
+    });
+
+  kb.command('add-site')
+    .description('Crawl and ingest an entire website')
+    .argument('<url>', 'Website URL to crawl')
+    .option('--depth <n>', 'Maximum crawl depth', '2')
+    .option('--max-pages <n>', 'Maximum pages to crawl', '50')
+    .option('--no-sitemap', 'Skip sitemap.xml and use link crawling only')
+    .option('--delay <ms>', 'Delay between requests in milliseconds', '500')
+    .action(async (url: string, opts: { depth: string; maxPages: string; sitemap: boolean; delay: string }) => {
+      clack.intro('KB — Crawl Site');
+      const config = getKBConfig();
+      const { store, siteCrawler } = await loadKB(config);
+
+      const spinner = clack.spinner();
+      spinner.start('Starting crawl...');
+
+      try {
+        const docs = await siteCrawler.crawlSite(url, {
+          maxDepth: parseInt(opts.depth),
+          maxPages: parseInt(opts.maxPages),
+          useSitemap: opts.sitemap,
+          delayMs: parseInt(opts.delay),
+          onProgress: (crawled, discovered, currentUrl) => {
+            const shortUrl = currentUrl.length > 60 ? currentUrl.slice(0, 57) + '...' : currentUrl;
+            spinner.message(`Crawling... (${crawled}/${discovered} pages) ${shortUrl}`);
+          },
+        });
+
+        spinner.stop(`Crawled ${docs.length} page(s)`);
+        clack.log.success(`Ingested ${docs.length} document(s) from ${url}`);
+      } catch (error: any) {
+        spinner.stop('Crawl failed');
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        store.close();
+      }
+      clack.outro('Done');
+    });
+
+  kb.command('add-file')
+    .description('Ingest a document file into the knowledge base')
+    .argument('<path>', 'File path to ingest')
+    .option('--priority <n>', 'Document priority (1=official, 2=supplementary, 3=archived)', '2')
+    .action(async (filePath: string, opts: { priority: string }) => {
+      clack.intro('KB — Add File');
+      const config = getKBConfig();
+      const { store, fileIngestor } = await loadKB(config);
+
+      const spinner = clack.spinner();
+      spinner.start(`Ingesting ${filePath}`);
+      try {
+        const doc = await fileIngestor.ingestFile(filePath, undefined, { priority: parseInt(opts.priority) });
+        spinner.stop(`Ingested: ${doc.title || filePath}`);
+        clack.log.success(`Document ID: ${doc.id}`);
+      } catch (error: any) {
+        spinner.stop(`Failed to ingest file`);
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        store.close();
+      }
+      clack.outro('Done');
+    });
+
+  kb.command('add-faq')
+    .description('Add a manual FAQ entry')
+    .argument('<question>', 'FAQ question')
+    .argument('<answer>', 'FAQ answer')
+    .action(async (question: string, answer: string) => {
+      clack.intro('KB — Add FAQ');
+      const config = getKBConfig();
+      const { store, ingestion } = await loadKB(config);
+
+      const spinner = clack.spinner();
+      spinner.start('Adding FAQ entry');
+      try {
+        let doc = await ingestion.ingestFaq(question, answer);
+        // CLI auto-replaces similar FAQs silently
+        if ((doc as any).existingMatch) {
+          const match = (doc as any).existingMatch;
+          clack.log.info(`Replacing similar FAQ (${(match.score * 100).toFixed(0)}% match): "${match.question}"`);
+          doc = await ingestion.ingestFaq(question, answer, { forceReplace: true, replaceId: match.id });
+        }
+        spinner.stop('FAQ entry added');
+        clack.log.success(`Document ID: ${doc.id}`);
+      } catch (error: any) {
+        spinner.stop('Failed to add FAQ');
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        store.close();
+      }
+      clack.outro('Done');
+    });
+
+  kb.command('list')
+    .description('List all KB documents')
+    .action(async () => {
+      clack.intro('KB — Documents');
+      const config = getKBConfig();
+      const { store } = await loadKB(config);
+
+      try {
+        const docs = await store.listDocuments();
+        if (docs.length === 0) {
+          clack.log.info('No documents in the knowledge base.');
+        } else {
+          const header = `${'ID'.padEnd(40)} ${'Type'.padEnd(12)} Title / Source`;
+          clack.log.info(header);
+          clack.log.info('─'.repeat(header.length));
+          for (const doc of docs) {
+            const line = `${doc.id.padEnd(40)} ${doc.sourceType.padEnd(12)} ${doc.title || doc.sourceUrl || doc.fileName || '—'}`;
+            clack.log.info(line);
+          }
+          clack.log.info(`\n${docs.length} document(s)`);
+        }
+      } catch (error: any) {
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        store.close();
+      }
+      clack.outro('');
+    });
+
+  kb.command('search')
+    .description('Test search against the knowledge base')
+    .argument('<query>', 'Search query')
+    .option('-n, --limit <n>', 'Max results', '5')
+    .action(async (query: string, opts: { limit: string }) => {
+      clack.intro('KB — Search');
+      const config = getKBConfig();
+      const { store, retrieval } = await loadKB(config);
+
+      const spinner = clack.spinner();
+      spinner.start(`Searching for "${query}"`);
+      try {
+        const result = await retrieval.retrieve(query, { limit: parseInt(opts.limit) });
+        spinner.stop(`Found ${result.results.length} result(s)`);
+
+        if (result.results.length === 0) {
+          clack.log.info('No results found.');
+        } else {
+          for (const r of result.results) {
+            clack.log.info(`\n[Score: ${r.score.toFixed(4)}] Doc #${r.document.id}`);
+            const preview = r.chunk.content.length > 200 ? r.chunk.content.slice(0, 200) + '…' : r.chunk.content;
+            clack.log.message(preview);
+          }
+        }
+      } catch (error: any) {
+        spinner.stop('Search failed');
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        store.close();
+      }
+      clack.outro('');
+    });
+
+  kb.command('ask')
+    .description('Ask a question using KB retrieval + LLM generation (RAG)')
+    .argument('<question>', 'Question to answer')
+    .option('-n, --limit <n>', 'Max KB chunks to retrieve', '5')
+    .option('--no-sources', 'Hide source attribution')
+    .action(async (question: string, opts: { limit: string; sources: boolean }) => {
+      clack.intro('KB — Ask');
+      const config = getKBConfig();
+      const { store, retrieval } = await loadKB(config);
+
+      const spinner = clack.spinner();
+      spinner.start('Searching knowledge base...');
+      try {
+        const result = await retrieval.retrieve(question, { limit: parseInt(opts.limit) });
+
+        // FAQ fast-path — no LLM needed
+        if (result.isFaqMatch && result.results.length > 0) {
+          spinner.stop('FAQ match found');
+          clack.log.success(result.results[0].chunk.content);
+          if (opts.sources) {
+            clack.log.info(`\nSource: FAQ (score: ${result.results[0].score.toFixed(4)})`);
+          }
+          return;
+        }
+
+        if (result.results.length === 0) {
+          spinner.stop('No relevant KB content found');
+          clack.log.warn('Cannot answer — no matching documents.');
+          return;
+        }
+
+        // LLM generation
+        if (!config.LLM_PROVIDER || !config.LLM_API_KEY) {
+          spinner.stop('KB results found, but no LLM configured');
+          clack.log.error('LLM_PROVIDER and LLM_API_KEY required. Use "operor kb search" for retrieval-only.');
+          return;
+        }
+
+        spinner.message('Generating answer...');
+        const { AIProvider } = await import('@operor/llm');
+        const llm = new AIProvider({
+          provider: config.LLM_PROVIDER as any,
+          apiKey: config.LLM_API_KEY,
+          model: config.LLM_MODEL,
+        });
+
+        const response = await llm.complete([
+          { role: 'system', content: `Answer using ONLY the provided context. If insufficient, say so.\n\n${result.context}` },
+          { role: 'user', content: question },
+        ]);
+
+        spinner.stop('Answer generated');
+        clack.log.success(response.text);
+
+        if (opts.sources) {
+          clack.log.info('\nSources:');
+          for (const r of result.results) {
+            const title = r.document?.title || r.document?.id || 'unknown';
+            clack.log.info(`  - ${title} (score: ${r.score.toFixed(4)})`);
+          }
+        }
+      } catch (error: any) {
+        spinner.stop('Failed');
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        store.close();
+      }
+      clack.outro('');
+    });
+
+  kb.command('delete')
+    .description('Delete a document from the knowledge base')
+    .argument('<id>', 'Document ID to delete')
+    .action(async (id: string) => {
+      clack.intro('KB — Delete');
+      const config = getKBConfig();
+      const { store } = await loadKB(config);
+
+      try {
+        await store.deleteDocument(id);
+        clack.log.success(`Document #${id} deleted`);
+      } catch (error: any) {
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        store.close();
+      }
+      clack.outro('Done');
+    });
+
+  kb.command('rebuild')
+    .description('Rebuild all KB vector embeddings using the current embedding provider')
+    .action(async () => {
+      clack.intro('KB — Rebuild Embeddings');
+      const config = getKBConfig();
+      const { store, ingestion } = await loadKB(config);
+
+      const spinner = clack.spinner();
+      try {
+        const stats = await store.getStats();
+        if (stats.documentCount === 0) {
+          clack.log.warn('Knowledge Base is empty — nothing to rebuild.');
+          return;
+        }
+
+        clack.log.info(`Provider: ${config.KB_EMBEDDING_PROVIDER || 'openai'}`);
+        clack.log.info(`Documents: ${stats.documentCount}, Chunks: ${stats.chunkCount}`);
+        spinner.start('Rebuilding embeddings...');
+
+        const result = await ingestion.rebuild((current, total, docTitle) => {
+          if (current < total) {
+            spinner.message(`Rebuilding... (${current + 1}/${total}) ${docTitle}`);
+          }
+        });
+
+        spinner.stop('Rebuild complete');
+        clack.log.success([
+          `Documents rebuilt: ${result.documentsRebuilt}`,
+          `Chunks rebuilt:    ${result.chunksRebuilt}`,
+          `Old dimensions:    ${result.oldDimensions}`,
+          `New dimensions:    ${result.newDimensions}`,
+        ].join('\n'));
+      } catch (error: any) {
+        spinner.stop('Rebuild failed');
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        store.close();
+      }
+      clack.outro('Done');
+    });
+
+  kb.command('stats')
+    .description('Show knowledge base statistics')
+    .action(async () => {
+      clack.intro('KB — Statistics');
+      const config = getKBConfig();
+      const { store } = await loadKB(config);
+
+      try {
+        const stats = await store.getStats();
+        clack.log.info(`Documents:        ${stats.documentCount}`);
+        clack.log.info(`Chunks:           ${stats.chunkCount}`);
+        clack.log.info(`Embedding dims:   ${stats.embeddingDimensions || '—'}`);
+        clack.log.info(`DB size:          ${formatBytes(stats.dbSizeBytes)}`);
+        clack.log.info(`DB path:          ${config.KB_DB_PATH || './knowledge.db'}`);
+        clack.log.info(`Embedding provider: ${config.KB_EMBEDDING_PROVIDER || 'openai'}`);
+        clack.log.info(`Embedding model:  ${config.KB_EMBEDDING_MODEL || 'default'}`);
+      } catch (error: any) {
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        store.close();
+      }
+      clack.outro('');
+    });
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}