shark-ai 0.4.6 → 0.4.10

package/dist/bin/shark.js

@@ -1717,46 +1717,93 @@ function getAgentId2(overrideId) {
 }
 async function interactiveSpecificationAgent(options = {}) {
   FileLogger.init();
-  tui.intro("\u{1F3D7}\uFE0F  Specification Agent");
+  tui.intro("\u{1F3D7}\uFE0F  Specification Agent (Template-Based)");
   const projectRoot = process.cwd();
+  const sharkRcDir = path6.resolve(projectRoot, "_sharkrc");
+  if (!fs5.existsSync(sharkRcDir)) fs5.mkdirSync(sharkRcDir, { recursive: true });
+  const outputFile = path6.resolve(sharkRcDir, "tech-spec.md");
+  if (!fs5.existsSync(outputFile)) {
+    let initialContent = `# Technical Specification: {{PROJECT_NAME}}
+
+## 1. Technology Stack
+[TO BE ANALYZED]
+- Language: [e.g. TypeScript]
+- Framework: [e.g. Node.js / React]
+- Database: [e.g. SQLite / PostgreSQL]
+- Key Libraries: [Top 5 dependencies]
+
+## 2. Architecture Overview
+[TO BE ANALYZED]
+[Brief description of architectural pattern]
+
+## 3. Data Model
+[TO BE ANALYZED]
+[Schema/ERD definitions]
+
+## 4. API / Interface Contracts
+[TO BE ANALYZED]
+[Main endpoints or CLI commands]
+
+## 5. Implementation Steps
+[TO BE FILLED - MUST BE CHECKBOXES]
+`;
+    const projectName = path6.basename(projectRoot);
+    initialContent = initialContent.replace(/{{PROJECT_NAME}}/g, projectName);
+    const BOM = "\uFEFF";
+    fs5.writeFileSync(outputFile, BOM + initialContent, { encoding: "utf-8" });
+    tui.log.success(`\u2705 Created: ${colors.bold("_sharkrc/tech-spec.md")}`);
+  } else {
+    tui.log.info(`\u{1F4C4} Using existing ${colors.bold("_sharkrc/tech-spec.md")}`);
+  }
   let contextContent = "";
   const contextPath = path6.resolve(projectRoot, "_sharkrc", "project-context.md");
   if (fs5.existsSync(contextPath)) {
-    try {
-      contextContent = fs5.readFileSync(contextPath, "utf-8");
-      tui.log.info(`\u{1F4D8} Context loaded from: ${colors.dim(path6.relative(projectRoot, contextPath))}`);
-    } catch (e) {
-      tui.log.warning(`Failed to read context file: ${e}`);
-    }
+    contextContent = fs5.readFileSync(contextPath, "utf-8");
+    tui.log.info(`\u{1F4D8} Context loaded.`);
   }
   let briefingContent = "";
   if (options.briefingPath && fs5.existsSync(options.briefingPath)) {
     briefingContent = fs5.readFileSync(options.briefingPath, "utf-8");
     tui.log.info(`\u{1F4C4} Briefing loaded from: ${colors.dim(options.briefingPath)}`);
   } else {
-    const sharkRcBriefing = path6.resolve(projectRoot, "_sharkrc", "briefing.md");
-    if (fs5.existsSync(sharkRcBriefing)) {
-      briefingContent = fs5.readFileSync(sharkRcBriefing, "utf-8");
-      tui.log.info(`\u{1F4C4} Standard Briefing loaded: ${colors.dim("_sharkrc/briefing.md")}`);
-    } else {
-      tui.log.info(colors.dim("\u2139\uFE0F No briefing file found in _sharkrc/briefing.md. Starting in interactive mode."));
-    }
-  }
-  let initialPrompt = "";
-  if (options.initialContext) {
-    initialPrompt += `
-\u26A0\uFE0F **CONTEXTO DE EXECU\xC7\xC3O ANTERIOR (HANDOVER)**:
-O Developer Agent estava executando tarefas. Aqui est\xE1 o resumo do que aconteceu at\xE9 agora:
-"""
-${options.initialContext}
-"""
-Analise esse hist\xF3rico acima. Se houve falha, proponha fixes na spec. Se o usu\xE1rio pediu mudan\xE7a, use isso como base.
+    const standardBriefing = path6.resolve(projectRoot, "_sharkrc", "briefing.md");
+    if (fs5.existsSync(standardBriefing)) {
+      briefingContent = fs5.readFileSync(standardBriefing, "utf-8");
+      tui.log.info(`\u{1F4C4} Briefing loaded.`);
+    }
+  }
+  let initialPrompt = `
+Voc\xEA \xE9 o **Shark Spec**, um Arquiteto de Software S\xEAnior e Tech Lead.
+Seu objetivo \xE9 produzir uma especifica\xE7\xE3o t\xE9cnica precisa e espec\xEDfica para a tarefa no arquivo \`_sharkrc/tech-spec.md\`.
+
+\u26A0\uFE0F WORKFLOW OBRIGAT\xD3RIO \u2013 SIGA ESSA SEQU\xCANCIA ESTRITAMENTE. N\xC3O PULE ETAPAS.
+
+**FASE 1 \u2013 ENTENDA A TAREFA (COMECE AQUI):**
+- Use \`talk_with_user\` para perguntar ao usu\xE1rio qual tarefa espec\xEDfica, funcionalidade ou bug ele precisa especificar.
+- N\xC3O explore o c\xF3digo ou leia arquivos ainda.
+- Confirme o escopo e os limites com o usu\xE1rio antes de prosseguir.
+
+**FASE 2 \u2013 INVESTIGUE (FOCADO APENAS NA TAREFA):**
+- Use \`list_files\` e \`read_file\` APENAS em arquivos diretamente relevantes para a tarefa confirmada.
+- N\xC3O leia o projeto de forma gen\xE9rica.
+- REGRA DE LEITURA PR\xC9VIA: Voc\xEA N\xC3O PODE adicionar uma tarefa referenciando um arquivo que voc\xEA n\xE3o leu nesta sess\xE3o (exce\xE7\xE3o: novos arquivos a serem criados).
+
+**FASE 3 \u2013 PREENCHA O TEMPLATE:**
+- Use \`modify_file\` em \`_sharkrc/tech-spec.md\` para substituir os placeholders com conte\xFAdo real e espec\xEDfico da tarefa.
+- As Se\xE7\xF5es 1-4 (Stack, Arquitetura, Modelo de Dados, API) devem descrever o contexto da TAREFA, n\xE3o do projeto como um todo.
+- Passos de Implementa\xE7\xE3o: APENAS checkboxes markdown: \`- [ ] [Verbo de A\xE7\xE3o] [O Que] em [Caminho Relativo]\`. SEM listas numeradas, SEM subn\xEDveis.
+- Quando todos os placeholders acabarem e voc\xEA estiver satisfeito, retorne: \`SPEC_UPDATED: Complete\`.
+
+**REGRAS CR\xCDTICAS:**
+- NUNCA preencha a Technology Stack ou Architecture com informa\xE7\xF5es gen\xE9ricas do projeto. Essas se\xE7\xF5es devem refletir o que a tarefa ir\xE1 usar ou alterar.
+- Use \`talk_with_user\` sempre que os requisitos forem amb\xEDguos.
+- N\xC3O tente escrever todas as se\xE7\xF5es de uma vez. Trabalhe de forma incremental, uma se\xE7\xE3o por vez.
+- IMPORTANTE: Toda a sua comunica\xE7\xE3o e a especifica\xE7\xE3o gerada DEVEM ser em Portugu\xEAs.
 `;
-  }
   if (briefingContent) {
     initialPrompt += `
-Abaixo est\xE1 o **Briefing de Neg\xF3cio** ou Descri\xE7\xE3o da Tarefa.
-Analise-o e ajude-me a definir a Especifica\xE7\xE3o T\xE9cnica (tech-spec.md).
+\u2139\uFE0F Um documento de briefing foi encontrado. Ele define parcialmente a tarefa para a Fase 1.
+Confirme seu entendimento com o usu\xE1rio via \`talk_with_user\` antes de prosseguir para a Fase 2.
 
 --- BRIEFING ---
 ${briefingContent}
@@ -1764,48 +1811,44 @@ ${briefingContent}
 `;
   } else {
     initialPrompt += `
-N\xE3o h\xE1 um documento de briefing formal.
-Por favor, pergunte-me qual \xE9 a tarefa ou funcionalidade que vamos especificar hoje.
+\u2139\uFE0F Nenhum documento de briefing foi encontrado. Inicie a Fase 1 imediatamente: use \`talk_with_user\` para perguntar ao usu\xE1rio o que precisa ser especificado.
+`;
+  }
+  if (options.initialContext) {
+    initialPrompt += `
+--- CONTEXTO DE EXECU\xC7\xC3O ANTERIOR (HANDOVER/FEEDBACK) ---
+${options.initialContext}
+-----------------------------------------------------
 `;
   }
   if (contextContent) {
     initialPrompt += `
-Abaixo est\xE1 o **Contexto do Projeto** atual. Use-o para alinhar a especifica\xE7\xE3o com a arquitetura existente.
+\u2139\uFE0F O contexto do projeto est\xE1 dispon\xEDvel para refer\xEAncia. Use-o na Fase 2 para se alinhar com os padr\xF5es de arquitetura existentes, mas N\xC3O o use para preencher as se\xE7\xF5es de forma gen\xE9rica.
 
 --- PROJECT CONTEXT ---
 ${contextContent}
 -----------------------
 `;
   }
-  initialPrompt += `
-
-Seu objetivo final \xE9 gerar o arquivo 'tech-spec.md'.
-
-\u26A0\uFE0F ATEN\xC7\xC3O: WORKFLOW DE AN\xC1LISE
-1. **Entenda**: Alinhe o objetivo com o usu\xE1rio.
-2. **Explore**: Use 'list_files' e 'read_file' para encontrar os arquivos RELEVANTES para a tarefa.
-3. **Especifique**: Gere o 'tech-spec.md' citando nomes de arquivos REAIS que voc\xEA leu.
-
-\u26A0\uFE0F REGRA DE FORMATA\xC7\xC3O (CRITICA):
-Na se\xE7\xE3o 'Implementation Steps', voc\xEA DEVE usar CHECKBOXES markdown ( - [ ] ) e N\xC3O listas numeradas.
-O agente de desenvolvimento S\xD3 reconhece checkboxes.
-
-Exemplo CORRETO:
-- [ ] Criar arquivo X
-- [ ] Atualizar fun\xE7\xE3o Y
-
-Exemplo ERRADO (N\xC3O FA\xC7A):
-1. Criar arquivo X
-2. Atualizar fun\xE7\xE3o Y
-`;
-  await runSpecLoop(initialPrompt.trim(), options.agentId);
+  await runSpecLoop(initialPrompt.trim(), outputFile, options.agentId);
 }
-async function runSpecLoop(initialMessage, overrideAgentId) {
+async function runSpecLoop(initialMessage, targetPath, overrideAgentId) {
   let nextPrompt = initialMessage;
   let keepGoing = true;
-  while (keepGoing) {
+  let stepCount = 0;
+  const MAX_STEPS = 30;
+  while (keepGoing && stepCount < MAX_STEPS) {
+    stepCount++;
     const spinner = tui.spinner();
-    spinner.start("\u{1F3D7}\uFE0F  Specification Agent is thinking...");
+    spinner.start(`\u{1F3D7}\uFE0F  Spec Agent working (Step ${stepCount}/${MAX_STEPS})...`);
+    let pendingSections = [];
+    if (fs5.existsSync(targetPath)) {
+      const content = fs5.readFileSync(targetPath, "utf-8");
+      if (content.includes("[TO BE ANALYZED]")) pendingSections.push("Analysis Sections (Stack, Arch, Data, API)");
+      if (content.includes("[TO BE FILLED")) pendingSections.push("Implementation Steps");
+    }
+    if (pendingSections.length === 0 && stepCount > 1) {
+    }
     let responseText = "";
     let lastResponse = null;
     try {
@@ -1816,10 +1859,10 @@ async function runSpecLoop(initialMessage, overrideAgentId) {
       if (lastResponse && lastResponse.actions) {
         let executionResults = "";
         let waitingForUser = false;
+        let specUpdated = false;
         if (lastResponse.message && lastResponse.message.includes("SPEC_UPDATED:")) {
           const updateSummary = lastResponse.message.split("SPEC_UPDATED:")[1].trim();
-          tui.log.success(`\u2705 Spec Updated: ${updateSummary}`);
-          tui.log.info("\u{1F4CB} Returning to orchestration loop...");
+          tui.log.success(`\u2705 Spec Finalized: ${updateSummary}`);
           return;
         }
         for (const action of lastResponse.actions) {
@@ -1848,97 +1891,78 @@ ${result}
 ${result}
 
 `;
-          } else if (["create_file", "modify_file", "delete_file"].includes(action.type)) {
-            tui.log.warning(`
-\u{1F916} Agent wants to ${action.type}: ${colors.bold(action.path || "unknown")}`);
-            if (action.content) {
-              const preview = action.content.length > 500 ? action.content.substring(0, 500) + "..." : action.content;
-              console.log(colors.dim("--- Preview ---\n") + preview + "\n" + colors.dim("---------------"));
+          } else if (["create_file", "modify_file"].includes(action.type)) {
+            let actionPath = path6.resolve(action.path || "");
+            const resolvedTargetPath = path6.resolve(targetPath);
+            let isTarget = actionPath === resolvedTargetPath;
+            if (!isTarget && path6.basename(actionPath) === "tech-spec.md") {
+              tui.log.warning(`Redirecting ${action.type} from ${action.path} to ${path6.relative(process.cwd(), targetPath)}`);
+              action.path = targetPath;
+              actionPath = resolvedTargetPath;
+              isTarget = true;
             }
-            const confirm = await tui.confirm({
-              message: `Approve ${action.type}?`,
-              active: "Yes",
-              inactive: "No"
-            });
-            if (confirm) {
-              if (action.path) {
-                try {
-                  if (action.type === "create_file") {
-                    const BOM = "\uFEFF";
-                    const contentToWrite = action.content || "";
-                    const finalContent = contentToWrite.startsWith(BOM) ? contentToWrite : BOM + contentToWrite;
-                    const dir = path6.dirname(action.path);
-                    if (!fs5.existsSync(dir)) fs5.mkdirSync(dir, { recursive: true });
-                    fs5.writeFileSync(action.path, finalContent, { encoding: "utf-8" });
-                    tui.log.success(`\u2705 Created: ${action.path}`);
-                    executionResults += `[Action create_file(${action.path})]: Success
-
+            if (!isTarget && action.type === "create_file") {
+              const confirm = await tui.confirm({ message: `Agent wants to create ${action.path}. Allow?` });
+              if (!confirm) {
+                executionResults += `[Action create_file]: User denied.
 `;
-                  } else if (action.type === "modify_file") {
-                    if (action.target_content) {
-                      const success = startSmartReplace(action.path, action.content || "", action.target_content, tui);
-                      executionResults += `[Action modify_file(${action.path})]: ${success ? "Success" : "Failed"}
-
+                continue;
+              }
+            }
+            try {
+              if (action.type === "create_file") {
+                const BOM = "\uFEFF";
+                fs5.writeFileSync(action.path, BOM + (action.content || ""), "utf-8");
+                tui.log.success(`\u2705 Created: ${action.path}`);
+                executionResults += `[Action create_file]: Success.
 `;
-                    } else {
-                      tui.log.error("\u274C Missing target_content. Modification aborted.");
-                      executionResults += `[Action modify_file]: Failed. 'target_content' is mandatory required for precision.
-
+              } else if (action.type === "modify_file") {
+                if (action.target_content) {
+                  const success = startSmartReplace(action.path, action.content || "", action.target_content, tui);
+                  if (success) {
+                    executionResults += `[Action modify_file]: Success.
 `;
-                    }
-                  } else if (action.type === "delete_file") {
-                    fs5.unlinkSync(action.path);
-                    tui.log.success(`\u2705 Deleted: ${action.path}`);
-                    executionResults += `[Action delete_file(${action.path})]: Success
-
+                    specUpdated = true;
+                  } else {
+                    executionResults += `[Action modify_file]: Failed. Target content not found.
 `;
                   }
-                } catch (e) {
-                  tui.log.error(`\u274C Failed: ${e.message}`);
-                  executionResults += `[Action ${action.type}(${action.path})]: Error: ${e.message}
-
+                } else {
+                  executionResults += `[Action modify_file]: Failed. 'target_content' is required.
 `;
                 }
               }
-            } else {
-              tui.log.error("\u274C Action denied.");
-              executionResults += `[Action ${action.type}]: User Denied
-
+            } catch (e) {
+              executionResults += `[Action ${action.type}]: Error: ${e.message}
 `;
             }
           }
         }
-        if (executionResults) {
-          if (waitingForUser) {
-            const userReply = await tui.text({
-              message: "Your answer",
-              placeholder: "Type your answer..."
-            });
-            if (tui.isCancel(userReply)) {
-              keepGoing = false;
-              return;
-            }
-            nextPrompt = `${executionResults}
-
-User Reply: ${userReply}`;
-          } else {
-            nextPrompt = executionResults;
-            FileLogger.log("SYSTEM", "Auto-replying with Tool Results", { length: executionResults.length });
-            tui.log.info(colors.dim("Processing tool results..."));
-          }
-        } else if (waitingForUser) {
-          const userReply = await tui.text({
-            message: "Your answer",
-            placeholder: "Type your answer..."
-          });
+        if (waitingForUser) {
+          const userReply = await tui.text({ message: "Your answer", placeholder: "Type your answer..." });
           if (tui.isCancel(userReply)) {
             keepGoing = false;
             return;
           }
-          nextPrompt = userReply;
+          nextPrompt = `${executionResults}
+
+User Reply: ${userReply}`;
+        } else if (executionResults) {
+          const content = fs5.existsSync(targetPath) ? fs5.readFileSync(targetPath, "utf-8") : "";
+          let systemMsg = "Execu\xE7\xE3o da ferramenta conclu\xEDda.";
+          if (specUpdated) {
+            if (content.includes("[TO BE")) {
+              systemMsg += "\n[System]: Se\xE7\xE3o atualizada. Por favor, continue harmonizando e preenchendo os placeholders '[TO BE ...]' restantes.";
+            } else {
+              systemMsg += "\n[System]: O arquivo parece completo! Se estiver satisfeito, retorne 'SPEC_UPDATED: Complete'.";
+            }
+          }
+          nextPrompt = `${executionResults}
+
+${systemMsg}`;
         } else {
           if (lastResponse.message) {
-            tui.log.info(colors.primary("\u{1F916} Architect:"));
+            tui.log.info(colors.primary("\u{1F916} Architect (Message only):"));
             console.log(lastResponse.message);
             const userReply = await tui.text({ message: "Your answer:" });
             if (tui.isCancel(userReply)) {
@@ -1947,12 +1971,11 @@ User Reply: ${userReply}`;
             }
             nextPrompt = userReply;
           } else {
-            tui.log.warning("No actions taken.");
             keepGoing = false;
           }
         }
       } else {
-        tui.log.warning("No actions received from agent.");
+        tui.log.warning("No actions received.");
         keepGoing = false;
       }
     } catch (error) {
@@ -1978,12 +2001,7 @@ async function callSpecAgentApi(prompt, onChunk, agentId) {
   const url = `${STACKSPOT_AGENT_API_BASE}/v1/agent/${effectiveAgentId}/chat`;
   let fullMsg = "";
   let raw = {};
-  FileLogger.log("AGENT", "Calling Agent API", {
-    agentId: effectiveAgentId,
-    conversationId,
-    prompt: prompt.substring(0, 500)
-    // Log summary of prompt
-  });
+  FileLogger.log("AGENT", "Calling Agent API", { agentId: effectiveAgentId, conversationId });
   await sseClient.streamAgentResponse(url, payload, { "Authorization": `Bearer ${token}`, "Content-Type": "application/json" }, {
     onChunk: (c) => {
       fullMsg += c;
@@ -1991,15 +2009,7 @@ async function callSpecAgentApi(prompt, onChunk, agentId) {
     },
     onComplete: (msg, metadata) => {
       const returnedId = metadata?.conversation_id;
-      FileLogger.log("AGENT", "Response Complete", {
-        conversationId,
-        returnedId,
-        messageLength: msg?.length
-      });
-      raw = {
-        message: msg || fullMsg,
-        conversation_id: returnedId || conversationId
-      };
+      raw = { message: msg || fullMsg, conversation_id: returnedId || conversationId };
     },
     onError: (e) => {
       throw e;