@codexa/cli 9.0.3 → 9.0.4

package/commands/knowledge.ts

@@ -1,5 +1,7 @@
 import { getDb } from "../db/connection";
 import { initSchema, getRelatedDecisions, getRelatedFiles } from "../db/schema";
+import { resolveSpec } from "./spec-resolver";
+import { CodexaError, ValidationError } from "../errors";
 
 type KnowledgeCategory = "discovery" | "decision" | "blocker" | "pattern" | "constraint";
 type KnowledgeSeverity = "info" | "warning" | "critical";
@@ -9,13 +11,7 @@ interface AddKnowledgeOptions {
   category: KnowledgeCategory;
   severity?: KnowledgeSeverity;
   broadcastTo?: string;
-}
-
-function getActiveSpec(): any {
-  const db = getDb();
-  return db
-    .query("SELECT * FROM specs WHERE phase NOT IN ('completed', 'cancelled') ORDER BY created_at DESC LIMIT 1")
-    .get();
+  specId?: string;
 }
 
 function getCurrentTask(specId: string): any {
@@ -31,24 +27,16 @@ export function addKnowledge(options: AddKnowledgeOptions): void {
   const db = getDb();
   const now = new Date().toISOString();
 
-  const spec = getActiveSpec();
-  if (!spec) {
-    console.error("\nNenhuma feature ativa.\n");
-    process.exit(1);
-  }
+  const spec = resolveSpec(options.specId);
 
   const currentTask = getCurrentTask(spec.id);
   if (!currentTask) {
-    console.error("\nNenhuma task em execucao.");
-    console.error("Knowledge so pode ser adicionado durante execucao de uma task.\n");
-    process.exit(1);
+    throw new CodexaError("Nenhuma task em execucao.\nKnowledge so pode ser adicionado durante execucao de uma task.");
   }
 
   const validCategories: KnowledgeCategory[] = ["discovery", "decision", "blocker", "pattern", "constraint"];
   if (!validCategories.includes(options.category)) {
-    console.error(`\nCategoria invalida: ${options.category}`);
-    console.error(`Validas: ${validCategories.join(", ")}\n`);
-    process.exit(1);
+    throw new ValidationError(`Categoria invalida: ${options.category}\nValidas: ${validCategories.join(", ")}`);
   }
 
   const severity = options.severity || "info";
@@ -79,20 +67,13 @@ export function listKnowledge(options: {
   category?: string;
   severity?: string;  // v8.0: Filtro por severidade
   json?: boolean;
+  specId?: string;
 }): void {
   initSchema();
 
   const db = getDb();
 
-  const spec = getActiveSpec();
-  if (!spec) {
-    if (options.json) {
-      console.log(JSON.stringify({ knowledge: [], message: "Nenhuma feature ativa" }));
-      return;
-    }
-    console.error("\nNenhuma feature ativa.\n");
-    process.exit(1);
-  }
+  const spec = resolveSpec(options.specId);
 
   let query = "SELECT * FROM knowledge WHERE spec_id = ?";
   const params: any[] = [spec.id];
@@ -122,9 +103,10 @@ export function listKnowledge(options: {
     const currentTask = getCurrentTask(spec.id);
     if (currentTask) {
       filtered = knowledge.filter((k) => {
-        if (!k.acknowledged_by) return true;
-        const acked = JSON.parse(k.acknowledged_by) as number[];
-        return !acked.includes(currentTask.id);
+        const isAcked = db.query(
+          "SELECT 1 FROM knowledge_acknowledgments WHERE knowledge_id = ? AND task_id = ?"
+        ).get(k.id, currentTask.id);
+        return !isAcked;
       });
     }
   }
@@ -158,42 +140,29 @@ export function listKnowledge(options: {
   }
 }
 
-export function acknowledgeKnowledge(knowledgeId: string): void {
+export function acknowledgeKnowledge(knowledgeId: string, specId?: string): void {
   initSchema();
 
   const db = getDb();
 
-  const spec = getActiveSpec();
-  if (!spec) {
-    console.error("\nNenhuma feature ativa.\n");
-    process.exit(1);
-  }
+  const spec = resolveSpec(specId);
 
   const currentTask = getCurrentTask(spec.id);
   if (!currentTask) {
-    console.error("\nNenhuma task em execucao.\n");
-    process.exit(1);
+    throw new CodexaError("Nenhuma task em execucao.");
   }
 
   const kid = parseInt(knowledgeId);
   const knowledge = db.query("SELECT * FROM knowledge WHERE id = ?").get(kid) as any;
 
   if (!knowledge) {
-    console.error(`\nKnowledge #${kid} nao encontrado.\n`);
-    process.exit(1);
+    throw new CodexaError(`Knowledge #${kid} nao encontrado.`);
   }
 
-  const acknowledged = knowledge.acknowledged_by
-    ? (JSON.parse(knowledge.acknowledged_by) as number[])
-    : [];
-
-  if (!acknowledged.includes(currentTask.id)) {
-    acknowledged.push(currentTask.id);
-    db.run("UPDATE knowledge SET acknowledged_by = ? WHERE id = ?", [
-      JSON.stringify(acknowledged),
-      kid,
-    ]);
-  }
+  db.run(
+    "INSERT OR IGNORE INTO knowledge_acknowledgments (knowledge_id, task_id) VALUES (?, ?)",
+    [kid, currentTask.id]
+  );
 
   console.log(`\nKnowledge #${kid} marcado como lido pela Task #${currentTask.number}.\n`);
 }
@@ -221,11 +190,13 @@ export function getKnowledgeForTask(specId: string, taskId: number): any[] {
 
 export function getUnreadKnowledgeForTask(specId: string, taskId: number): any[] {
   const all = getKnowledgeForTask(specId, taskId);
+  const db = getDb();
 
   return all.filter((k) => {
-    if (!k.acknowledged_by) return true;
-    const acked = JSON.parse(k.acknowledged_by) as number[];
-    return !acked.includes(taskId);
+    const isAcked = db.query(
+      "SELECT 1 FROM knowledge_acknowledgments WHERE knowledge_id = ? AND task_id = ?"
+    ).get(k.id, taskId);
+    return !isAcked;
   });
 }
 
@@ -234,15 +205,12 @@ export function queryGraph(options: {
   file?: string;
   decision?: string;
   json?: boolean;
+  specId?: string;
 }): void {
   initSchema();
   const db = getDb();
 
-  const spec = getActiveSpec();
-  if (!spec) {
-    console.error("\nNenhuma feature ativa.\n");
-    process.exit(1);
-  }
+  const spec = resolveSpec(options.specId);
 
   // Buscar relacoes para um arquivo
   if (options.file) {
@@ -336,17 +304,172 @@ export function queryGraph(options: {
   console.log(`  knowledge graph --decision <id>         Arquivos afetados por decisao\n`);
 }
 
+// v9.2: Jaccard similarity for knowledge compaction
+export function jaccardSimilarity(a: string, b: string): number {
+  const tokenize = (s: string): Set<string> => {
+    const words = s
+      .toLowerCase()
+      .replace(/[^\w\s-]/g, " ")
+      .split(/\s+/)
+      .filter((w) => w.length > 2);
+    return new Set(words);
+  };
+
+  const setA = tokenize(a);
+  const setB = tokenize(b);
+
+  if (setA.size === 0 && setB.size === 0) return 1;
+  if (setA.size === 0 || setB.size === 0) return 0;
+
+  let intersection = 0;
+  for (const word of setA) {
+    if (setB.has(word)) intersection++;
+  }
+
+  const union = setA.size + setB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+// v9.2: Knowledge compaction — merge similar, archive old, archive completed
+export function compactKnowledge(options: {
+  specId?: string;
+  dryRun?: boolean;
+  json?: boolean;
+}): void {
+  initSchema();
+  const db = getDb();
+
+  let merged = 0;
+  let archivedOld = 0;
+  let archivedCompleted = 0;
+
+  // Phase 1: Merge similar entries (same category + spec_id, Jaccard >= 0.8)
+  const specFilter = options.specId
+    ? "AND spec_id = ?"
+    : "";
+  const specParams = options.specId ? [options.specId] : [];
+
+  const entries = db
+    .query(
+      `SELECT * FROM knowledge WHERE severity != 'archived' ${specFilter} ORDER BY category, spec_id, created_at DESC`
+    )
+    .all(...specParams) as any[];
+
+  // Group by category + spec_id
+  const groups = new Map<string, any[]>();
+  for (const entry of entries) {
+    const key = `${entry.category}:${entry.spec_id}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key)!.push(entry);
+  }
+
+  const toArchive = new Set<number>();
+
+  for (const [, group] of groups) {
+    for (let i = 0; i < group.length; i++) {
+      if (toArchive.has(group[i].id)) continue;
+      for (let j = i + 1; j < group.length; j++) {
+        if (toArchive.has(group[j].id)) continue;
+
+        const sim = jaccardSimilarity(group[i].content, group[j].content);
+        if (sim >= 0.8) {
+          // Keep higher severity or newer; archive the other
+          const severityOrder: Record<string, number> = { critical: 3, warning: 2, info: 1, archived: 0 };
+          const keepI = (severityOrder[group[i].severity] || 0) >= (severityOrder[group[j].severity] || 0);
+          const archiveId = keepI ? group[j].id : group[i].id;
+          toArchive.add(archiveId);
+          merged++;
+        }
+      }
+    }
+  }
+
+  // Phase 2: Archive old info entries (>7 days, no graph references)
+  const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+  const oldInfoEntries = db
+    .query(
+      `SELECT k.id FROM knowledge k
+       WHERE k.severity = 'info' AND k.created_at < ? ${specFilter}
+       AND NOT EXISTS (
+         SELECT 1 FROM knowledge_graph kg
+         WHERE kg.source_id = CAST(k.id AS TEXT) AND kg.source_type = 'knowledge'
+       )
+       AND NOT EXISTS (
+         SELECT 1 FROM knowledge_graph kg
+         WHERE kg.target_id = CAST(k.id AS TEXT) AND kg.target_type = 'knowledge'
+       )`
+    )
+    .all(sevenDaysAgo, ...specParams) as any[];
+
+  for (const entry of oldInfoEntries) {
+    if (!toArchive.has(entry.id)) {
+      toArchive.add(entry.id);
+      archivedOld++;
+    }
+  }
+
+  // Phase 3: Archive all entries from completed/cancelled specs
+  const completedEntries = db
+    .query(
+      `SELECT k.id FROM knowledge k
+       JOIN specs s ON k.spec_id = s.id
+       WHERE s.phase IN ('completed', 'cancelled')
+       AND k.severity != 'archived'
+       ${options.specId ? "AND k.spec_id = ?" : ""}`
+    )
+    .all(...specParams) as any[];
+
+  for (const entry of completedEntries) {
+    if (!toArchive.has(entry.id)) {
+      toArchive.add(entry.id);
+      archivedCompleted++;
+    }
+  }
+
+  // Apply changes
+  if (!options.dryRun && toArchive.size > 0) {
+    const ids = Array.from(toArchive);
+    const placeholders = ids.map(() => "?").join(",");
+    db.run(
+      `UPDATE knowledge SET severity = 'archived' WHERE id IN (${placeholders})`,
+      ids
+    );
+  }
+
+  // Output
+  const result = {
+    merged,
+    archivedOld,
+    archivedCompleted,
+    totalArchived: toArchive.size,
+    dryRun: !!options.dryRun,
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+
+  const mode = options.dryRun ? "[DRY RUN] " : "";
+  console.log(`\n${mode}Knowledge Compaction:`);
+  console.log(`${"─".repeat(50)}`);
+  console.log(`  Similares mesclados: ${merged}`);
+  console.log(`  Info antigos (>7d): ${archivedOld}`);
+  console.log(`  Specs finalizados: ${archivedCompleted}`);
+  console.log(`  Total arquivado: ${toArchive.size}`);
+  if (options.dryRun) {
+    console.log(`\nPara aplicar: knowledge compact${options.specId ? ` --spec ${options.specId}` : ""}`);
+  }
+  console.log();
+}
+
 // v9.0: Resolver/reconhecer knowledge critico (para desbloquear task start)
-export function resolveKnowledge(ids: string, resolution?: string): void {
+export function resolveKnowledge(ids: string, resolution?: string, specId?: string): void {
   initSchema();
   const db = getDb();
   const now = new Date().toISOString();
 
-  const spec = getActiveSpec();
-  if (!spec) {
-    console.error("\nNenhuma feature ativa.\n");
-    process.exit(1);
-  }
+  const spec = resolveSpec(specId);
 
   const knowledgeIds = ids.split(",").map(s => parseInt(s.trim()));
 
@@ -358,18 +481,10 @@ export function resolveKnowledge(ids: string, resolution?: string): void {
       continue;
     }
 
-    const acknowledged = knowledge.acknowledged_by
-      ? (JSON.parse(knowledge.acknowledged_by) as number[])
-      : [];
-
     // Usar -1 como marker de "resolvido pelo orquestrador"
-    if (!acknowledged.includes(-1)) {
-      acknowledged.push(-1);
-    }
-
     db.run(
-      "UPDATE knowledge SET acknowledged_by = ? WHERE id = ?",
-      [JSON.stringify(acknowledged), kid]
+      "INSERT OR IGNORE INTO knowledge_acknowledgments (knowledge_id, task_id) VALUES (?, ?)",
+      [kid, -1]
     );
 
     console.log(`Knowledge #${kid} resolvido.`);

package/commands/patterns.ts

@@ -8,6 +8,7 @@
 import { execSync, spawnSync } from "child_process";
 import { readFileSync, existsSync } from "fs";
 import { extname, basename, dirname } from "path";
+import { CodexaError, ValidationError } from "../errors";
 import { getDb } from "../db/connection";
 import { initSchema } from "../db/schema";
 
@@ -601,10 +602,7 @@ export function patternsExtract(options: ExtractOptions): void {
 
   // Verificar grepai
   if (!isGrepaiAvailable()) {
-    console.error("\n[ERRO] grepai nao encontrado.");
-    console.error("Instale com: go install github.com/your-org/grepai@latest");
-    console.error("Ou configure no PATH.\n");
-    process.exit(1);
+    throw new CodexaError("grepai nao encontrado.\nInstale com: go install github.com/your-org/grepai@latest\nOu configure no PATH.");
   }
 
   const db = getDb();
@@ -617,9 +615,7 @@ export function patternsExtract(options: ExtractOptions): void {
   }
 
   if (queries.length === 0) {
-    console.error(`\n[ERRO] Escopo '${options.scope}' nao reconhecido.`);
-    console.error("Escopos validos: frontend, backend, database, testing\n");
-    process.exit(1);
+    throw new ValidationError("Escopo '" + options.scope + "' nao reconhecido.\nEscopos validos: frontend, backend, database, testing");
   }
 
   console.log(`\n🔍 Extraindo patterns via grepai...`);
@@ -737,15 +733,13 @@ export function patternsExtract(options: ExtractOptions): void {
 
 export function patternsAnalyze(filePath: string, json: boolean = false): void {
   if (!existsSync(filePath)) {
-    console.error(`\n[ERRO] Arquivo nao encontrado: ${filePath}\n`);
-    process.exit(1);
+    throw new CodexaError("Arquivo nao encontrado: " + filePath);
   }
 
   const analysis = analyzeFile(filePath);
 
   if (!analysis) {
-    console.error(`\n[ERRO] Nao foi possivel analisar o arquivo.\n`);
-    process.exit(1);
+    throw new CodexaError("Nao foi possivel analisar o arquivo.");
   }
 
   if (json) {
@@ -855,8 +849,7 @@ export function patternsAnalyzeDeep(files: string[], json: boolean = false): voi
   }
 
   if (analyses.length === 0) {
-    console.error("\nNenhum arquivo analisado.\n");
-    process.exit(1);
+    throw new CodexaError("Nenhum arquivo analisado.");
   }
 
   const summary = {

package/commands/plan.ts

@@ -1,5 +1,7 @@
 import { getDb } from "../db/connection";
 import { initSchema, getArchitecturalAnalysisForSpec } from "../db/schema";
+import { resolveSpec } from "./spec-resolver";
+import { CodexaError, ValidationError } from "../errors";
 
 export function generateSpecId(name: string): string {
     const date = new Date().toISOString().split("T")[0];
@@ -17,28 +19,6 @@ export function planStart(description: string, options: { fromAnalysis?: string;
     initSchema();
     const db = getDb();
 
-    // Verificar se ja existe spec ativo (ignorar completed e cancelled)
-    const existing = db
-        .query("SELECT * FROM specs WHERE phase NOT IN ('completed', 'cancelled') ORDER BY created_at DESC LIMIT 1")
-        .get() as any;
-
-    if (existing) {
-        if (options.json) {
-            console.log(JSON.stringify({
-                error: "FEATURE_ACTIVE",
-                name: existing.name,
-                id: existing.id,
-                phase: existing.phase,
-            }));
-        } else {
-            console.error(`\nJa existe uma feature ativa: ${existing.name} (${existing.id})`);
-            console.error(`Fase atual: ${existing.phase}`);
-            console.error(`\nPara continuar, use: status`);
-            console.error(`Para cancelar a atual, use: plan cancel\n`);
-        }
-        process.exit(1);
-    }
-
     // v8.4: Buscar analise arquitetural se --from-analysis fornecido
     let analysis: any = null;
     if (options.fromAnalysis) {
@@ -52,7 +32,7 @@ export function planStart(description: string, options: { fromAnalysis?: string;
             } else {
                 console.error(`\n[ERRO] Analise arquitetural '${options.fromAnalysis}' nao encontrada.\n`);
             }
-            process.exit(1);
+            throw new CodexaError(`Analise arquitetural '${options.fromAnalysis}' nao encontrada.`);
         }
 
         if (analysis.status !== "approved") {
@@ -62,7 +42,7 @@ export function planStart(description: string, options: { fromAnalysis?: string;
                 console.error(`\n[ERRO] Analise '${analysis.id}' nao esta aprovada (status: ${analysis.status}).`);
                 console.error("Use 'architect approve' primeiro.\n");
             }
-            process.exit(1);
+            throw new CodexaError(`Analise '${analysis.id}' nao esta aprovada (status: ${analysis.status}). Use 'architect approve' primeiro.`);
         }
     } else {
         // v8.4: Auto-deteccao por nome
@@ -161,19 +141,11 @@ export function planStart(description: string, options: { fromAnalysis?: string;
     }
 }
 
-export function planShow(json: boolean = false): void {
+export function planShow(json: boolean = false, specId?: string): void {
     initSchema();
     const db = getDb();
 
-    const spec = db
-        .query("SELECT * FROM specs WHERE phase NOT IN ('completed', 'cancelled') ORDER BY created_at DESC LIMIT 1")
-        .get() as any;
-
-    if (!spec) {
-        console.error("\nNenhuma feature ativa.");
-        console.error("Inicie com: /codexa:feature'\n");
-        process.exit(1);
-    }
+    const spec = resolveSpec(specId);
 
     const tasks = db
         .query("SELECT * FROM tasks WHERE spec_id = ? ORDER BY number")
@@ -227,25 +199,12 @@ export function planTaskAdd(options: {
     depends?: string;
     files?: string;
     sequential?: boolean;
+    specId?: string;
 }): void {
     initSchema();
     const db = getDb();
 
-    const spec = db
-        .query("SELECT * FROM specs WHERE phase NOT IN ('completed', 'cancelled') ORDER BY created_at DESC LIMIT 1")
-        .get() as any;
-
-    if (!spec) {
-        console.error("\nNenhuma feature ativa.");
-        console.error("Inicie com: /codexa:feature\n");
-        process.exit(1);
-    }
-
-    if (spec.phase !== "planning") {
-        console.error(`\nNao e possivel adicionar tasks na fase '${spec.phase}'.`);
-        console.error("Tasks so podem ser adicionadas na fase 'planning'.\n");
-        process.exit(1);
-    }
+    const spec = resolveSpec(options.specId, ["planning"]);
 
     // Pegar proximo numero
     const lastTask = db
@@ -262,8 +221,7 @@ export function planTaskAdd(options: {
                 .query("SELECT id FROM tasks WHERE spec_id = ? AND number = ?")
                 .get(spec.id, depId);
             if (!exists) {
-                console.error(`\nDependencia invalida: task #${depId} nao existe.\n`);
-                process.exit(2);
+                throw new ValidationError(`Dependencia invalida: task #${depId} nao existe.`);
             }
         }
 
@@ -302,10 +260,9 @@ export function planTaskAdd(options: {
         }
 
         if (hasCycle(nextNumber)) {
-            console.error(`\nERRO: Dependencia circular detectada!`);
-            console.error(`Task #${nextNumber} -> [${dependsOn.join(", ")}] cria um ciclo.`);
-            console.error(`Corrija as dependencias para evitar deadlocks.\n`);
-            process.exit(2);
+            throw new ValidationError(
+              `Dependencia circular detectada! Task #${nextNumber} -> [${dependsOn.join(", ")}] cria um ciclo.\nCorrija as dependencias para evitar deadlocks.`
+            );
         }
     }
 
@@ -344,18 +301,11 @@ export function planTaskAdd(options: {
     console.log(`  Paralelizavel: ${options.sequential ? "Nao" : "Sim"}\n`);
 }
 
-export function planCancel(): void {
+export function planCancel(specId?: string): void {
     initSchema();
     const db = getDb();
 
-    const spec = db
-        .query("SELECT * FROM specs WHERE phase NOT IN ('completed', 'cancelled') ORDER BY created_at DESC LIMIT 1")
-        .get() as any;
-
-    if (!spec) {
-        console.error("\nNenhuma feature ativa para cancelar.\n");
-        process.exit(1);
-    }
+    const spec = resolveSpec(specId);
 
     const now = new Date().toISOString();
 

package/commands/product.ts

@@ -2,6 +2,7 @@ import { getDb } from "../db/connection";
 import { initSchema } from "../db/schema";
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
+import { CodexaError } from "../errors";
 
 interface ProductContext {
   name: string;
@@ -93,15 +94,13 @@ export function productImport(options: { file?: string; content?: string }): voi
 
   if (options.file) {
     if (!existsSync(options.file)) {
-      console.error(`\nArquivo nao encontrado: ${options.file}\n`);
-      process.exit(1);
+      throw new CodexaError("Arquivo nao encontrado: " + options.file);
     }
     prdContent = readFileSync(options.file, "utf-8");
   } else if (options.content) {
     prdContent = options.content;
   } else {
-    console.error("\nForneca --file ou --content\n");
-    process.exit(1);
+    throw new CodexaError("Forneca --file ou --content");
   }
 
   // Salvar como pendente para o agente processar
@@ -286,21 +285,15 @@ export function productConfirm(): void {
 
   const pending = db.query("SELECT * FROM product_context WHERE id = 'pending'").get() as any;
   if (!pending) {
-    console.error("\nNenhum contexto de produto pendente.");
-    console.error("Execute: product guide ou product import primeiro\n");
-    process.exit(1);
+    throw new CodexaError("Nenhum contexto de produto pendente.\nExecute: product guide ou product import primeiro");
   }
 
   // Validar campos obrigatorios
   if (!pending.name || pending.name === "Pendente") {
-    console.error("\nCampo obrigatorio ausente: name");
-    console.error("Use: product set --name \"Nome do Produto\"\n");
-    process.exit(1);
+    throw new CodexaError("Campo obrigatorio ausente: name\nUse: product set --name \"Nome do Produto\"");
   }
   if (!pending.problem || pending.problem === "") {
-    console.error("\nCampo obrigatorio ausente: problem");
-    console.error("Use: product set --problem \"Problema que resolve\"\n");
-    process.exit(1);
+    throw new CodexaError("Campo obrigatorio ausente: problem\nUse: product set --problem \"Problema que resolve\"");
   }
 
   const now = new Date().toISOString();
@@ -358,12 +351,10 @@ export function productShow(options: { json?: boolean; pending?: boolean } = {})
 
   if (!product) {
     if (options.pending) {
-      console.error("\nNenhum contexto pendente.");
+      throw new CodexaError("Nenhum contexto pendente.");
     } else {
-      console.error("\nContexto de produto nao definido.");
-      console.error("Execute: product guide ou product import\n");
+      throw new CodexaError("Contexto de produto nao definido.\nExecute: product guide ou product import");
     }
-    process.exit(1);
   }
 
   const goals = db.query(`SELECT * FROM product_goals WHERE product_id = ? ORDER BY priority, category`).all(id) as any[];

package/commands/research.ts

@@ -2,6 +2,7 @@ import { getDb } from "../db/connection";
 import { initSchema } from "../db/schema";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
+import { CodexaError } from "../errors";
 import { getDetectors } from "../detectors/loader";
 
 // ============================================================
@@ -359,7 +360,7 @@ export async function researchStart(options: { json?: boolean } = {}): Promise<v
             console.error("Certifique-se de estar na raiz do projeto.");
             console.error("Ecossistemas suportados: Node.js, Python, Go, .NET, Rust, Java/Kotlin, Flutter\n");
         }
-        process.exit(1);
+        throw new CodexaError("Nenhum ecossistema ou biblioteca detectada.\nCertifique-se de estar na raiz do projeto.");
     }
 
     const libContextDir = ensureLibContextDir();
@@ -517,7 +518,7 @@ export function researchShow(options: { json?: boolean; lib?: string } = {}): vo
             console.error("\nNenhuma biblioteca registrada.");
             console.error("Execute: research start\n");
         }
-        process.exit(1);
+        throw new CodexaError("Nenhuma biblioteca registrada.\nExecute: research start");
     }
 
     if (options.json) {
@@ -590,7 +591,7 @@ export function researchFill(libName: string, options: { json?: boolean } = {}):
             console.error(`\nBiblioteca '${libName}' nao encontrada.`);
             console.error("Execute: research show para ver bibliotecas disponiveis.\n");
         }
-        process.exit(1);
+        throw new CodexaError("Biblioteca '" + libName + "' nao encontrada.\nExecute: research show para ver bibliotecas disponiveis.");
     }
 
     const versionStr = lib.version && lib.version !== "latest" ? lib.version : "latest";