@codexa/cli 9.0.2 → 9.0.4

package/protocol/subagent-protocol.ts

@@ -27,6 +27,8 @@ export interface Reasoning {
 }
 
 export interface SubagentReturn {
+  // v9.1: Versao do protocolo (opcional por compatibilidade)
+  protocol_version?: string;
   status: "completed" | "blocked" | "needs_decision";
   summary: string;
   files_created: string[];
@@ -58,11 +60,14 @@ const VALID_STATUSES = ["completed", "blocked", "needs_decision"];
 const VALID_KNOWLEDGE_CATEGORIES = ["discovery", "decision", "blocker", "pattern", "constraint"];
 const VALID_SEVERITIES = ["info", "warning", "critical"];
 
+// v9.1: Versao atual do protocolo de subagentes
+export const CURRENT_PROTOCOL_VERSION = "9.1";
+
 /**
  * Extrai JSON de uma string que pode conter texto misto
  * Subagents podem retornar texto com JSON embutido
  */
-function extractJsonFromText(text: string): string | null {
+export function extractJsonFromText(text: string): string | null {
   // Tenta encontrar JSON em bloco de codigo
   const codeBlockMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
   if (codeBlockMatch) {
@@ -350,6 +355,17 @@ export function parseSubagentReturn(input: string): ParseResult {
     }
   }
 
+  // v9.1: protocol_version (opcional, warn on mismatch)
+  if (parsed.protocol_version !== undefined) {
+    if (typeof parsed.protocol_version !== "string") {
+      errors.push("Campo 'protocol_version' deve ser string");
+    } else if (parsed.protocol_version !== CURRENT_PROTOCOL_VERSION) {
+      console.warn(
+        `[protocol] Versao do protocolo: esperado ${CURRENT_PROTOCOL_VERSION}, recebido ${parsed.protocol_version}`
+      );
+    }
+  }
+
   // 5. Validacoes semanticas
 
   // Se blocked, deve ter blockers
@@ -376,6 +392,7 @@ export function parseSubagentReturn(input: string): ParseResult {
 
   // Cast para tipo correto
   const data: SubagentReturn = {
+    protocol_version: parsed.protocol_version as string | undefined,
     status: parsed.status as SubagentReturn["status"],
     summary: parsed.summary as string,
     files_created: parsed.files_created as string[],
@@ -412,6 +429,7 @@ export function formatValidationErrors(result: ParseResult): string {
   output += "\n" + "─".repeat(50) + "\n";
   output += "O retorno deve seguir o formato:\n\n";
   output += `{
+  "protocol_version": "9.1",
   "status": "completed | blocked | needs_decision",
   "summary": "Resumo do que foi feito (10-500 chars)",
   "files_created": ["path/to/file.ts"],

package/workflow.ts

@@ -6,7 +6,7 @@ import { checkRequest, checkApprove, checkReject } from "./commands/check";
 import { taskNext, taskStart, taskDone } from "./commands/task";
 import { decide, listDecisions } from "./commands/decide";
 import { reviewStart, reviewApprove, reviewSkip } from "./commands/review";
-import { addKnowledge, listKnowledge, acknowledgeKnowledge, queryGraph, resolveKnowledge } from "./commands/knowledge";
+import { addKnowledge, listKnowledge, acknowledgeKnowledge, queryGraph, resolveKnowledge, compactKnowledge } from "./commands/knowledge";
 import { status, contextExport, recover, contextUpdate, contextDetail } from "./commands/utils";
 import {
   discoverStart,
@@ -22,12 +22,14 @@ import {
   discoverPatternRemove,
   discoverRefreshPatterns,
   discoverExportPatterns,
+  discoverIncremental,
 } from "./commands/discover";
 import { clearTasks, clearShow } from "./commands/clear";
 import { standardsList, standardsAdd, standardsEdit, standardsRemove, standardsExport } from "./commands/standards";
 import { productGuide, productImport, productSet, productGoalAdd, productFeatureAdd, productConfirm, productShow, productReset } from "./commands/product";
 import { researchStart, researchShow, researchFill, researchMapAgent, researchReset } from "./commands/research";
 import { patternsExtract, patternsAnalyze } from "./commands/patterns";
+import { syncAgents } from "./commands/sync";
 import {
   architectStart,
   architectShow,
@@ -38,11 +40,12 @@ import {
   architectCancel,
 } from "./commands/architect";
 import { initSchema } from "./db/schema";
-import { getDb } from "./db/connection";
+import { getDb, closeDb } from "./db/connection";
 import { execSync } from "child_process";
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import pkg from "./package.json";
+import { CodexaError, ValidationError, GateError } from "./errors";
 
 function checkVersionSync(): void {
   // 1. Check CLI vs Plugin (dev repo only)
@@ -52,10 +55,11 @@ function checkVersionSync(): void {
     if (existsSync(pluginJson)) {
       const plugin = JSON.parse(readFileSync(pluginJson, "utf-8"));
       if (plugin.version && plugin.version !== pkg.version) {
-        console.error(`\n✘ Versao incompativel: CLI=${pkg.version} Plugin=${plugin.version}`);
-        console.error(`  O CLI e o plugin DEVEM ter a mesma versao.`);
-        console.error(`  Atualize o CLI: bun add -g @codexa/cli@${plugin.version}\n`);
-        process.exit(1);
+        throw new CodexaError(
+          `✘ Versao incompativel: CLI=${pkg.version} Plugin=${plugin.version}\n` +
+          `  O CLI e o plugin DEVEM ter a mesma versao.\n` +
+          `  Atualize o CLI: bun add -g @codexa/cli@${plugin.version}`
+        );
       }
     }
   } catch {
@@ -83,25 +87,73 @@ function checkVersionSync(): void {
     }
 
     if (project.cli_version !== pkg.version) {
-      console.error(`\n✘ Versao incompativel: CLI=${pkg.version} Projeto=${project.cli_version}`);
-      console.error(`  O projeto foi configurado com CLI v${project.cli_version} mas voce esta usando v${pkg.version}.`);
-      console.error(`  Opcoes:`);
-      console.error(`    1. Atualize o CLI: bun add -g @codexa/cli@${project.cli_version}`);
-      console.error(`    2. Reconfigure o projeto: codexa discover reset && codexa discover start\n`);
-      process.exit(1);
+      throw new CodexaError(
+        `✘ Versao incompativel: CLI=${pkg.version} Projeto=${project.cli_version}\n` +
+        `  O projeto foi configurado com CLI v${project.cli_version} mas voce esta usando v${pkg.version}.\n` +
+        `  Opcoes:\n` +
+        `    1. Atualize o CLI: bun add -g @codexa/cli@${project.cli_version}\n` +
+        `    2. Reconfigure o projeto: codexa discover reset && codexa discover start`
+      );
     }
   } catch {
     // DB not available or column doesn't exist yet — skip
   }
 }
 
+function handleError(e: unknown): never {
+  if (e instanceof CodexaError) {
+    console.error(`\n${e.message}\n`);
+
+    // v9.3: Exibir diagnostico e passos de recuperacao para falhas de gate
+    if (e instanceof GateError && e.recovery) {
+      console.error("\u2500".repeat(50));
+      console.error("DIAGNOSTICO:");
+      console.error(`  ${e.recovery.diagnostic}\n`);
+      console.error("PASSOS PARA CORRIGIR:");
+      for (const step of e.recovery.steps) {
+        console.error(`  \u2192 ${step}`);
+      }
+      if (e.recovery.command) {
+        console.error(`\nPara mais detalhes: ${e.recovery.command}`);
+      }
+      console.error();
+    }
+
+    closeDb();
+    process.exit(e.exitCode);
+  }
+  console.error(`\n[ERRO INESPERADO] ${(e as Error).message}\n`);
+  closeDb();
+  process.exit(1);
+}
+
+function wrapAction<T extends (...args: any[]) => any>(fn: T): T {
+  return ((...args: any[]) => {
+    try {
+      const result = fn(...args);
+      if (result instanceof Promise) {
+        return result.catch((e) => {
+          closeDb();
+          handleError(e);
+        });
+      }
+      return result;
+    } catch (e) {
+      closeDb();
+      handleError(e);
+    }
+  }) as T;
+}
+
 const program = new Command();
 
 program
   .name("codexa")
   .description(`Codexa Workflow v${pkg.version} - Sistema de workflow para Claude Code`)
   .version(pkg.version)
-  .hook("preAction", () => checkVersionSync());
+  .hook("preAction", () => {
+    checkVersionSync();
+  });
 
 // ═══════════════════════════════════════════════════════════════
 // FASE: PLAN
@@ -122,8 +174,9 @@ planCmd
   .command("show")
   .description("Mostra o plano atual")
   .option("--json", "Saida em JSON")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
   .action((options) => {
-    planShow(options.json);
+    planShow(options.json, options.spec);
   });
 
 planCmd
@@ -134,15 +187,17 @@ planCmd
   .option("--depends <ids>", "IDs das tasks que esta depende (ex: 1,2)")
   .option("--files <files>", "Arquivos esperados (ex: src/a.ts,src/b.ts)")
   .option("--sequential", "Marca como sequencial (nao paralelizavel)")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
   .action((options) => {
-    planTaskAdd(options);
+    planTaskAdd({ ...options, specId: options.spec });
   });
 
 planCmd
   .command("cancel")
   .description("Cancela a feature atual (soft-cancel, preserva historico)")
-  .action(() => {
-    planCancel();
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action((options) => {
+    planCancel(options.spec);
   });
 
 // ═══════════════════════════════════════════════════════════════
@@ -154,22 +209,25 @@ const checkCmd = program.command("check").description("Comandos da fase CHECK");
 checkCmd
   .command("request")
   .description("Solicita aprovacao do plano")
-  .action(() => {
-    checkRequest();
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action((options) => {
+    checkRequest(options.spec);
   });
 
 checkCmd
   .command("approve")
   .description("Aprova o plano")
-  .action(() => {
-    checkApprove();
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action((options) => {
+    checkApprove(options.spec);
   });
 
 checkCmd
   .command("reject <reason>")
   .description("Rejeita o plano com motivo")
-  .action((reason: string) => {
-    checkReject(reason);
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action((reason: string, options) => {
+    checkReject(reason, options.spec);
   });
 
 // ═══════════════════════════════════════════════════════════════
@@ -182,18 +240,20 @@ taskCmd
   .command("next")
   .description("Mostra proximas tasks disponiveis")
   .option("--json", "Saida em JSON")
-  .action((options) => {
-    taskNext(options.json);
-  });
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action(wrapAction((options) => {
+    taskNext(options.json, options.spec);
+  }));
 
 taskCmd
   .command("start <ids>")
   .description("Inicia task(s) - pode ser multiplas separadas por virgula")
   .option("--json", "Saida em JSON")
   .option("--full-context", "Incluir contexto completo (modo legado)")
-  .action((ids: string, options) => {
-    taskStart(ids, options.json, options.fullContext);
-  });
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action(wrapAction((ids: string, options) => {
+    taskStart(ids, options.json, options.fullContext, options.spec);
+  }));
 
 taskCmd
   .command("done <id>")
@@ -204,15 +264,15 @@ taskCmd
   .option("--files <files>", "Arquivos criados/modificados (extraido automaticamente de --output)")
   .option("--force", "Ignorar validacao de standards (sera registrado)")
   .option("--force-reason <reason>", "Motivo do bypass de validacao")
-  .action((id: string, options) => {
+  .action(wrapAction((id: string, options) => {
     // Resolver --output-file: ler conteudo do arquivo
     if (options.outputFile && !options.output) {
       try {
         options.output = readFileSync(options.outputFile, "utf-8");
       } catch (e) {
-        console.error(`\n[ERRO] Nao foi possivel ler arquivo: ${options.outputFile}`);
-        console.error(`  ${(e as Error).message}\n`);
-        process.exit(1);
+        throw new ValidationError(
+          `[ERRO] Nao foi possivel ler arquivo: ${options.outputFile}\n  ${(e as Error).message}`
+        );
       }
     }
 
@@ -221,17 +281,17 @@ taskCmd
       try {
         options.output = readFileSync("/dev/stdin", "utf-8");
       } catch (e) {
-        console.error("\n[ERRO] Nao foi possivel ler de stdin.");
-        console.error(`  ${(e as Error).message}\n`);
-        process.exit(1);
+        throw new ValidationError(
+          `[ERRO] Nao foi possivel ler de stdin.\n  ${(e as Error).message}`
+        );
       }
     }
 
     // Checkpoint obrigatorio se nao houver --output
     if (!options.output && !options.checkpoint) {
-      console.error("\n[ERRO] Checkpoint obrigatorio.");
-      console.error("Use: --checkpoint 'resumo' ou --output '{json do subagent}'\n");
-      process.exit(1);
+      throw new ValidationError(
+        "[ERRO] Checkpoint obrigatorio.\nUse: --checkpoint 'resumo' ou --output '{json do subagent}'"
+      );
     }
 
     taskDone(id, {
@@ -241,7 +301,7 @@ taskCmd
       forceReason: options.forceReason,
       output: options.output,
     });
-  });
+  }));
 
 // ═══════════════════════════════════════════════════════════════
 // DECISOES
@@ -252,16 +312,18 @@ program
   .description("Registra uma decisao")
   .option("--rationale <text>", "Justificativa da decisao")
   .option("--force", "Ignorar deteccao de conflitos")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
   .action((title: string, decision: string, options) => {
-    decide(title, decision, options);
+    decide(title, decision, { ...options, specId: options.spec });
   });
 
 program
   .command("decisions")
   .description("Lista decisoes")
   .option("--json", "Saida em JSON")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
   .action((options) => {
-    listDecisions(options.json);
+    listDecisions(options.json, options.spec);
   });
 
 // ═══════════════════════════════════════════════════════════════
@@ -277,12 +339,14 @@ knowledgeCmd
   .requiredOption("--category <cat>", "Categoria (discovery, decision, blocker, pattern, constraint)")
   .option("--severity <level>", "Severidade (info, warning, critical)", "info")
   .option("--broadcast <target>", "Destino (all ou IDs separados por virgula)", "all")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
   .action((options) => {
     addKnowledge({
       content: options.content,
       category: options.category,
       severity: options.severity,
       broadcastTo: options.broadcast,
+      specId: options.spec,
     });
   });
 
@@ -293,23 +357,26 @@ knowledgeCmd
   .option("--category <cat>", "Filtrar por categoria")
   .option("--severity <level>", "Filtrar por severidade (critical, warning, info)")
   .option("--json", "Saida em JSON")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
   .action((options) => {
-    listKnowledge(options);
+    listKnowledge({ ...options, specId: options.spec });
   });
 
 knowledgeCmd
   .command("ack <id>")
   .description("Marca knowledge como lido pela task atual")
-  .action((id: string) => {
-    acknowledgeKnowledge(id);
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action((id: string, options) => {
+    acknowledgeKnowledge(id, options.spec);
   });
 
 knowledgeCmd
   .command("resolve <ids>")
   .description("Resolve/reconhece knowledge item(s) critico(s)")
   .option("--resolution <text>", "Descricao de como o blocker foi resolvido")
-  .action((ids: string, opts: { resolution?: string }) => {
-    resolveKnowledge(ids, opts.resolution);
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action((ids: string, opts: { resolution?: string; spec?: string }) => {
+    resolveKnowledge(ids, opts.resolution, opts.spec);
   });
 
 knowledgeCmd
@@ -317,10 +384,20 @@ knowledgeCmd
   .description("Consulta o knowledge graph (relacoes entre arquivos, decisoes, patterns)")
   .option("--file <path>", "Buscar relacoes de um arquivo")
   .option("--decision <id>", "Buscar arquivos afetados por uma decisao")
-  .option("--contradictions", "Detectar contradicoes entre decisoes")
+  .option("--json", "Saida em JSON")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action((options) => {
+    queryGraph({ ...options, specId: options.spec });
+  });
+
+knowledgeCmd
+  .command("compact")
+  .description("Compacta knowledge (merge similares, arquivar antigos)")
+  .option("--spec <id>", "ID do spec (padrao: todos)")
+  .option("--dry-run", "Apenas mostrar o que seria compactado")
   .option("--json", "Saida em JSON")
   .action((options) => {
-    queryGraph(options);
+    compactKnowledge({ specId: options.spec, dryRun: options.dryRun, json: options.json });
   });
 
 // ═══════════════════════════════════════════════════════════════
@@ -333,22 +410,27 @@ reviewCmd
   .command("start")
   .description("Inicia o review")
   .option("--json", "Saida em JSON")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
   .action((options) => {
-    reviewStart(options.json);
+    reviewStart(options.json, options.spec);
   });
 
 reviewCmd
   .command("approve")
   .description("Aprova o review e finaliza a feature")
-  .action(() => {
-    reviewApprove();
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .option("--force", "Aprovar mesmo com score baixo (<50)")
+  .option("--force-reason <reason>", "Motivo para aprovacao forcada")
+  .action((options) => {
+    reviewApprove({ specId: options.spec, force: options.force, forceReason: options.forceReason });
   });
 
 reviewCmd
   .command("skip")
   .description("Pula o review e finaliza a feature diretamente")
-  .action(() => {
-    reviewSkip();
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action((options) => {
+    reviewSkip(options.spec);
   });
 
 // ═══════════════════════════════════════════════════════════════
@@ -359,8 +441,9 @@ program
   .command("status")
   .description("Mostra status atual")
   .option("--json", "Saida em JSON")
+  .option("--spec <id>", "ID do spec (padrao: todos ativos)")
   .action((options) => {
-    status(options.json);
+    status(options.json, options.spec);
   });
 
 const contextCmd = program.command("context").description("Comandos de contexto");
@@ -369,8 +452,9 @@ contextCmd
   .command("export")
   .description("Exporta contexto para subagent")
   .option("--task <id>", "ID da task especifica")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
   .action((options) => {
-    contextExport({ ...options, json: true }); // Sempre JSON
+    contextExport({ ...options, json: true, specId: options.spec }); // Sempre JSON
   });
 
 contextCmd
@@ -379,16 +463,18 @@ contextCmd
   .option("--approach <text>", "Adiciona nova abordagem descoberta")
   .option("--pattern <text>", "Registra padrao identificado no codigo")
   .option("--constraint <text>", "Adiciona nova limitacao encontrada")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
   .action((options) => {
-    contextUpdate(options);
+    contextUpdate({ ...options, specId: options.spec });
   });
 
 contextCmd
   .command("detail <section>")
   .description("Mostra secao especifica do contexto (standards, decisions, patterns, knowledge, architecture)")
   .option("--json", "Output JSON")
-  .action((section: string, opts: { json?: boolean }) => {
-    contextDetail(section, opts.json);
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action((section: string, opts: { json?: boolean; spec?: string }) => {
+    contextDetail(section, opts.json, opts.spec);
   });
 
 // Manter compatibilidade: context sem subcomando = export
@@ -396,8 +482,9 @@ program
   .command("ctx")
   .description("Alias para context export (compatibilidade)")
   .option("--task <id>", "ID da task especifica")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
   .action((options) => {
-    contextExport({ ...options, json: true });
+    contextExport({ ...options, json: true, specId: options.spec });
   });
 
 program
@@ -463,7 +550,7 @@ discoverCmd
   });
 
 discoverCmd
-  .command("reset")
+  .command("reset", { hidden: true })
   .description("Reseta descoberta para refazer")
   .action(() => {
     discoverReset();
@@ -477,6 +564,13 @@ discoverCmd
     await discoverRefresh(options);
   });
 
+discoverCmd
+  .command("incremental")
+  .description("Atualiza discover incrementalmente (arquivos modificados desde ultimo discover)")
+  .action(async () => {
+    await discoverIncremental();
+  });
+
 // ─────────────────────────────────────────────────────────────────
 // PATTERNS (v7.4)
 // ─────────────────────────────────────────────────────────────────
@@ -524,7 +618,7 @@ discoverCmd
   });
 
 discoverCmd
-  .command("pattern-edit <name>")
+  .command("pattern-edit <name>", { hidden: true })
   .description("Edita um implementation pattern")
   .option("--category <cat>", "Nova categoria")
   .option("--scope <scope>", "Novo escopo")
@@ -574,7 +668,7 @@ discoverCmd
   });
 
 discoverCmd
-  .command("analyze-file <path>")
+  .command("analyze-file <path>", { hidden: true })
   .description("Analisa estrutura de um arquivo (imports, exports, convencoes)")
   .option("--json", "Saida em JSON")
   .action((path, options) => {
@@ -583,7 +677,7 @@ discoverCmd
 
 // v9.0: Analise profunda com metadata enriquecida + grepai
 discoverCmd
-  .command("analyze-deep <files...>")
+  .command("analyze-deep <files...>", { hidden: true })
   .description("Analise profunda de arquivos (hooks, patterns, directives)")
   .option("--json", "Saida em JSON")
   .action((files, options) => {
@@ -593,7 +687,7 @@ discoverCmd
 
 // v9.0: Anti-patterns de gate bypasses
 discoverCmd
-  .command("extract-anti-patterns")
+  .command("extract-anti-patterns", { hidden: true })
   .description("Extrai anti-patterns do historico de gate bypasses")
   .action(() => {
     const { extractAntiPatternsFromHistory } = require("./commands/patterns");
@@ -601,7 +695,7 @@ discoverCmd
   });
 
 discoverCmd
-  .command("export-patterns")
+  .command("export-patterns", { hidden: true })
   .description("Regenera arquivo patterns.md")
   .action(() => {
     discoverExportPatterns();
@@ -819,11 +913,12 @@ program
   .description("Limpa tasks/features mantendo configuracoes do projeto (standards, patterns, PRD)")
   .option("--force", "Confirma a limpeza (sem isso apenas mostra o que sera removido)")
   .option("--show", "Mostra estado atual dos arquivos do workflow")
+  .option("--spec <id>", "Limpa apenas o spec especificado")
   .action((options) => {
     if (options.show) {
       clearShow();
     } else {
-      clearTasks({ force: options.force });
+      clearTasks({ force: options.force, specId: options.spec });
     }
   });
 
@@ -895,5 +990,19 @@ architectCmd
     architectCancel(options);
   });
 
+// ═══════════════════════════════════════════════════════════════
+// PLUGIN
+// ═══════════════════════════════════════════════════════════════
+
+const pluginCmd = program.command("plugin").description("Comandos de gestao do plugin");
+
+pluginCmd
+  .command("sync-agents")
+  .description("Copia agents do plugin para .claude/agents/ do projeto (resolve limitacao de subagent_type)")
+  .option("--force", "Sobrescrever agents existentes")
+  .action((options) => {
+    syncAgents(options);
+  });
+
 // Parse e executa
 program.parse();