sdd-toolkit 1.0.0 → 1.5.0

package/src/lib/agents.js

@@ -1,68 +1,125 @@
-const fs = require('fs/promises');
-const path = require('path');
-const yaml = require('js-yaml');
-const { AgentSchema } = require('./schema');
-const pc = require('picocolors');
-
-/**
- * Carrega e valida todas as definições de agentes da pasta definitions
- * @returns {Promise<Array>} Lista de agentes validados
- */
-async function loadAgents() {
-    const definitionsDir = path.join(__dirname, '..', '..', 'definitions');
-    
-    try {
-        await fs.access(definitionsDir);
-    } catch {
-        throw new Error(`Pasta de definições não encontrada: ${definitionsDir}`);
-    }
-
-    const files = await fs.readdir(definitionsDir);
-    const yamlFiles = files.filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
-    
-    // Leitura e processamento em paralelo
-    const results = await Promise.all(yamlFiles.map(async (file) => {
-        try {
-            const content = await fs.readFile(path.join(definitionsDir, file), 'utf8');
-            const raw = yaml.load(content);
-            
-            const parsed = AgentSchema.safeParse(raw);
-            if (!parsed.success) {
-                return { 
-                    success: false, 
-                    file, 
-                    error: 'Validação do Schema falhou',
-                    details: parsed.error.format()
-                };
-            }
-
-            const agent = parsed.data;
-            // Normaliza o slug: dev.coder -> dev-coder
-            agent.slug = file.replace(/\.ya?ml$/, '').replace(/\./g, '-');
-            // Mantém o nome original do arquivo para referência (útil para Gemini CLI)
-            agent.originalName = file.replace(/\.ya?ml$/, '');
-            
-            return { success: true, agent };
-
-        } catch (e) {
-            return { success: false, file, error: e.message };
-        }
-    }));
-
-    // Separa sucessos e falhas
-    const validAgents = [];
-    const errors = [];
-
-    results.forEach(res => {
-        if (res.success) {
-            validAgents.push(res.agent);
-        } else {
-            errors.push(res);
-            console.warn(pc.yellow(`⚠️  Ignorando ${res.file}: ${res.error}`));
-        }
-    });
-
-    return validAgents;
-}
-
-module.exports = { loadAgents };
+const fs = require('fs/promises');
+const path = require('path');
+const yaml = require('js-yaml');
+const { AgentSchema } = require('./schema');
+const { STACK_PROFILES } = require('./profiles');
+const pc = require('picocolors');
+
+/**
+ * Loads and validates all agent definitions from the definitions folder.
+ * Supports local override (sdd-toolkit/agents) and rule injection.
+ * 
+ * @param {Object} options
+ * @param {string} options.stackProfile - Stack profile key (e.g., 'frontend-react')
+ * @param {string} options.globalRules - Global rules separated by newlines
+ * @returns {Promise<Array>} List of validated agents
+ */
+async function loadAgents(options = {}) {
+    const definitionsDir = path.join(__dirname, '..', '..', 'definitions');
+    const localDefinitionsDir = path.join(process.cwd(), 'sdd-toolkit', 'agents');
+    
+    // Check default directory
+    try {
+        await fs.access(definitionsDir);
+    } catch {
+        throw new Error(`Default definitions folder not found: ${definitionsDir}`);
+    }
+
+    // Identify default files
+    const files = await fs.readdir(definitionsDir);
+    const yamlFiles = files.filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+
+    // Check if local override directory exists
+    let hasLocalOverrides = false;
+    try {
+        await fs.access(localDefinitionsDir);
+        hasLocalOverrides = true;
+    } catch {
+        // Ignore if it doesn't exist
+    }
+    
+    // Parallel reading and processing
+    const results = await Promise.all(yamlFiles.map(async (file) => {
+        try {
+            let content;
+            let source = 'default';
+
+            // Feature 2: Local Override
+            if (hasLocalOverrides) {
+                try {
+                    const localPath = path.join(localDefinitionsDir, file);
+                    await fs.access(localPath);
+                    content = await fs.readFile(localPath, 'utf8');
+                    source = 'local';
+                } catch {
+                    // Local file doesn't exist, use default
+                }
+            }
+
+            if (!content) {
+                content = await fs.readFile(path.join(definitionsDir, file), 'utf8');
+            }
+
+            const raw = yaml.load(content);
+            
+            const parsed = AgentSchema.safeParse(raw);
+            if (!parsed.success) {
+                return { 
+                    success: false, 
+                    file, 
+                    error: 'Schema validation failed',
+                    details: parsed.error.format()
+                };
+            }
+
+            const agent = parsed.data;
+            
+            // Normalize slug
+            agent.slug = file.replace(/\.ya?ml$/, '').replace(/\./g, '-');
+            agent.originalName = file.replace(/\.ya?ml$/, '');
+            agent.source = source; // Useful metadata for logs
+
+            // Feature 5: Stack Rules Injection
+            if (options.stackProfile && STACK_PROFILES[options.stackProfile]) {
+                const stackRules = STACK_PROFILES[options.stackProfile].rules;
+                if (stackRules && stackRules.length > 0) {
+                    agent.rules = [...agent.rules, ...stackRules];
+                }
+            }
+
+            // Feature 3: Global Rules Injection
+            if (options.globalRules && typeof options.globalRules === 'string') {
+                const customRules = options.globalRules
+                    .split('\n')
+                    .map(r => r.trim())
+                    .filter(r => r.length > 0);
+                
+                if (customRules.length > 0) {
+                    agent.rules = [...agent.rules, ...customRules];
+                }
+            }
+            
+            return { success: true, agent };
+
+        } catch (e) {
+            return { success: false, file, error: e.message };
+        }
+    }));
+
+    // Separate successes and failures
+    const validAgents = [];
+    const errors = [];
+
+    results.forEach(res => {
+        if (res.success) {
+            validAgents.push(res.agent);
+        } else {
+            errors.push(res);
+            console.warn(pc.yellow(`⚠️  Skipping ${res.file}: ${res.error}`));
+        }
+    });
+
+    return validAgents;
+}
+
+module.exports = { loadAgents };

package/src/lib/docs.js

@@ -1,104 +1,68 @@
 const fs = require('fs');
 const path = require('path');
-const pc = require('picocolors');
 
 /**
- * Gera o guia de workflow e a estrutura de pastas necessária para os agentes
+ * Generates the necessary folder structure for the agents
+ * Implements Smart Scaffolding: Only creates missing files/folders.
  */
 function generateWorkflowGuide(baseDir) {
     const docsDir = path.join(baseDir, 'docs');
-    const logsDir = path.join(docsDir, 'logs');
     
-    // Cria a estrutura de pastas recursivamente (Funciona em Windows, Mac e Linux)
-    if (!fs.existsSync(logsDir)) {
-        fs.mkdirSync(logsDir, { recursive: true });
-    }
+    // 1. Define folder structure based on new logging architecture
+    const folders = [
+        path.join(docsDir, 'logs'),
+        path.join(docsDir, 'logs', 'executions'),
+        path.join(docsDir, 'logs', 'reviews'),
+        path.join(docsDir, 'logs', 'archive'),
+    ];
 
-    // Conteúdo do README.md
-    const content = `# 🤖 Agent Workflow Guide
+    let stats = { created: 0, verified: 0 };
 
-Este documento descreve o fluxo de desenvolvimento padrão usando os Agentes instalados.
-O sistema segue um processo **Waterfall** para planejamento (precisão) e **Iterativo** para execução.
+    // Create folders
+    folders.forEach(dir => {
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+            stats.created++;
+        } else {
+            stats.verified++;
+        }
+    });
 
----
-
-## 1. 🏗️ Project Spec (@Project Architect)
-**Role:** O Visionário.
-**Goal:** Traduzir sua ideia vaga em uma Especificação concreta com "Project Principles" definidos.
-- **Comando:** \\
-/dev:project "Eu quero um App de Todo que..."
-- **Saída:** 
-\`docs/project.md\`
-
-## 2. 🧱 Requirements Engineering (@Requirements Engineer)
-**Role:** O Tech Lead.
-**Goal:** Fechar decisões técnicas (Stack, Banco de Dados, Libs).
-- **Why?** Evita que o Coder "invente" arquitetura. Cria o "Contrato".
-- **Comando:** 
-/dev:requirements
-- **Saída:** 
-\`docs/requirements.md\`
-
-## 3. 🗺️ Roadmap Strategy (@Milestone Manager)
-**Role:** O Estrategista.
-**Goal:** Fatiar o projeto em fases de entrega (MVPs).
-- **Comando:** 
-/dev:milestone
-- **Saída:** 
-\`docs/milestones.md\`
-
-## 4. 📋 Task Planning (@Task Planner)
-**Role:** O Gerente.
-**Goal:** Quebrar um Milestone específico em tarefas atômicas para desenvolvedores.
-- **Why?** IAs falham com contextos gigantes. Tarefas pequenas = Código perfeito.
-- **Comando:** 
-/dev:tasks <Milestone_ID>
-- **Saída:** 
-\`docs/task.md\`
-
-## 5. 🕵️ Blueprint Audit (@Auditor)
-**Role:** O Guardião.
-**Goal:** Validar consistência entre **Requirements** e **Tasks**.
-- **Comando:** 
-/dev:auditor
-- **Saída:** 
-\`audit_report.md\`
-
-## 6. 💻 Implementation (@Coder)
-**Role:** O Construtor.
-**Goal:** Executar *uma tarefa por vez* do arquivo 
-\`task.md\`.
-- **Comando:** 
-/dev:coder <Task_ID>
-- **Buffer:** 
-\`work_log.md\`
-
-## 7. ⚖️ Quality Assurance (@QA Engineer)
-**Role:** O Inspetor.
-**Goal:** Verificar se a implementação bate com os Requisitos.
-- **Comando:** 
-/dev:review <Task_ID>
-- **Saída:** 
-\`docs/logs/review_log.md\`
-
-## 8. 📦 Release Management (@Release Manager)
-**Role:** O Historiador.
-**Goal:** Consolidar o 
-\`work_log.md\` em um 
-\`changelog.md\` permanente.
-- **Comando:** 
-/dev:log
-- **Saída:** 
-\`changelog.md\`
-`;
+    // 2. Define Templates Mapping
+    // Assumes templates are located in project_root/templates/
+    // __dirname is src/lib/, so templates is ../../templates
+    const templatesDir = path.join(__dirname, '..', '..', 'templates');
+    
+    const templateFiles = [
+        { src: 'guidelines.md', dest: 'guidelines.md' },
+        { src: 'project.md', dest: 'project.md' },
+        { src: 'requirements.md', dest: 'requirements.md' },
+        { src: 'milestones.md', dest: 'milestones.md' },
+        { src: 'task.md', dest: 'task.md' }
+    ];
 
-    const readmePath = path.join(docsDir, 'README.md');
-    if (!fs.existsSync(readmePath)) {
-        fs.writeFileSync(readmePath, content);
-        return true;
-    }
+    // Create files if they don't exist
+    templateFiles.forEach(tpl => {
+        const destPath = path.join(docsDir, tpl.dest);
+        if (!fs.existsSync(destPath)) {
+            try {
+                // Ensure template exists before reading
+                const templatePath = path.join(templatesDir, tpl.src);
+                if (fs.existsSync(templatePath)) {
+                    const content = fs.readFileSync(templatePath, 'utf8');
+                    fs.writeFileSync(destPath, content);
+                    stats.created++;
+                }
+            } catch (e) {
+                // Fail silently/warn, do not crash the installer
+                console.warn(`Warning: Could not scaffold ${tpl.dest}`);
+            }
+        } else {
+            stats.verified++;
+        }
+    });
     
-    return true; // Retorna true indicando que a estrutura foi garantida
+    return stats;
 }
 
 module.exports = { generateWorkflowGuide };

package/src/lib/i18n.js

@@ -0,0 +1,65 @@
+/**
+ * Internal i18n Engine
+ */
+const { TRANSLATIONS } = require('./messages');
+
+let currentLocale = 'en';
+
+function setLocale(locale) {
+    // Normalize logic (pt-br -> pt_br) if passed incorrectly, though prompts usually give controlled values
+    const normalized = locale.toLowerCase().replace('-', '_');
+    
+    if (TRANSLATIONS[normalized]) {
+        currentLocale = normalized;
+    } else {
+        // Fallback to en
+        currentLocale = 'en';
+    }
+}
+
+function getLocale() {
+    return currentLocale;
+}
+
+/**
+ * Retrieves a string from the dictionary based on dot notation.
+ * e.g. t('INTRO.TITLE')
+ */
+function t(path, ...args) {
+    const keys = path.split('.');
+    let value = TRANSLATIONS[currentLocale];
+
+    // Traverse the object for the current locale
+    for (const key of keys) {
+        if (value && value[key]) {
+            value = value[key];
+        } else {
+            value = undefined;
+            break;
+        }
+    }
+
+    // If not found, Try Fallback to EN
+    if (!value) {
+        let fallback = TRANSLATIONS['en'];
+        for (const k of keys) {
+            if (fallback && fallback[k]) fallback = fallback[k];
+            else {
+                fallback = undefined;
+                break;
+            }
+        }
+        value = fallback;
+    }
+
+    // If still not found, return the path itself as a debug marker
+    if (!value) return path;
+
+    if (typeof value === 'function') {
+        return value(...args);
+    }
+
+    return value;
+}
+
+module.exports = { t, setLocale, getLocale };

package/src/lib/messages.js

@@ -0,0 +1,186 @@
+/**
+ * Centralized User-Facing Strings
+ * Used for future Internationalization (i18n)
+ */
+
+const EN = {
+    INTRO: {
+        TITLE: ' UNIVERSAL SPEC CLI ',
+        UPGRADE_TITLE: ' SDD TOOLKIT: UPGRADE MODE ',
+    },
+    GENERAL: {
+        CANCELLED: 'Operation cancelled.',
+    },
+    UPGRADE: {
+        NO_CONFIG: 'No existing configuration detected for upgrade. Starting standard installation.',
+        NO_CONFIG_TITLE: 'Info',
+        DETECTED_TOOLS: (tools) => `Tools detected: ${tools}`,
+        DETECTED_TITLE: 'Upgrading...',
+        SUCCESS: 'Agents updated successfully! 🚀',
+    },
+    SCAFFOLD: {
+        LOADING: 'Checking workspace structure...',
+        SUCCESS: '✔ Folder structure (docs/) created.',
+        ALREADY_EXISTS: '✔ Folder structure (docs/) verified.',
+        ERROR: 'Failed to verify workspace structure.',
+    },
+    SETUP: {
+        STACK_SELECT: 'What is your technology Stack profile?',
+        GLOBAL_RULES: 'Do you want to add any Global Rules for ALL agents?',
+        GLOBAL_RULES_HINT: 'Ex: Always reply in English; Use Conventional Commits...',
+        TOOL_SELECT: 'Which tools do you want to install the Agents for?',
+        TOOL_HINT: 'Space to select, Enter to confirm',
+        NO_TOOLS: 'No tools selected. Operation cancelled.',
+        SUCCESS: 'Setup completed successfully! 🚀',
+    },
+    INSTALL: {
+        LOADING: 'Loading definitions...',
+        NO_AGENTS: 'No valid agents found.',
+        INSTALLING: (tools) => `Installing agents for: ${tools}...`,
+        FINISHED: 'Installation finished!',
+        ROO_WARNING: 'Remember to configure Custom Modes in settings.json for Roo/Cline.',
+        ROO_WARNING_TITLE: 'Warning',
+        FAILED: 'Failed',
+    },
+    TOOLS: {
+        GEMINI: 'Gemini CLI',
+        ROO: 'Roo Code',
+        CLINE: 'Cline',
+        CURSOR: 'Cursor',
+        WINDSURF: 'Windsurf',
+        TRAE: 'Trae IDE',
+        KILO: 'Kilo Code',
+        COPILOT: 'GitHub Copilot',
+        WEB: 'OpenAI / Claude',
+        OPENCODE: 'OpenCode',
+    },
+    LANGUAGE_RULES: {
+        EN: 'Always reply in English unless told otherwise.',
+        PT_BR: 'Responda sempre em Português (Brasil), a menos que solicitado o contrário.',
+        ES: 'Responda siempre en Español, a menos que se solicite lo contrario.',
+    }
+};
+
+const PT_BR = {
+    INTRO: {
+        TITLE: ' UNIVERSAL SPEC CLI ',
+        UPGRADE_TITLE: ' SDD TOOLKIT: MODO ATUALIZAÇÃO ',
+    },
+    GENERAL: {
+        CANCELLED: 'Operação cancelada.',
+    },
+    UPGRADE: {
+        NO_CONFIG: 'Nenhuma configuração existente detectada. Iniciando instalação padrão.',
+        NO_CONFIG_TITLE: 'Info',
+        DETECTED_TOOLS: (tools) => `Ferramentas detectadas: ${tools}`,
+        DETECTED_TITLE: 'Atualizando...',
+        SUCCESS: 'Agentes atualizados com sucesso! 🚀',
+    },
+    SCAFFOLD: {
+        LOADING: 'Verificando estrutura do workspace...',
+        SUCCESS: '✔ Estrutura de pastas (docs/) criada.',
+        ALREADY_EXISTS: '✔ Estrutura de pastas (docs/) verificada.',
+        ERROR: 'Falha ao verificar estrutura do workspace.',
+    },
+    SETUP: {
+        STACK_SELECT: 'Qual é o perfil de tecnologia (Stack)?',
+        GLOBAL_RULES: 'Deseja adicionar Regras Globais para TODOS os agentes?',
+        GLOBAL_RULES_HINT: 'Ex: Sempre responda em Português; Use Conventional Commits...',
+        TOOL_SELECT: 'Para quais ferramentas você deseja instalar os Agentes?',
+        TOOL_HINT: 'Espaço para selecionar, Enter para confirmar',
+        NO_TOOLS: 'Nenhuma ferramenta selecionada. Operação cancelada.',
+        SUCCESS: 'Instalação concluída com sucesso! 🚀',
+    },
+    INSTALL: {
+        LOADING: 'Carregando definições...',
+        NO_AGENTS: 'Nenhum agente válido encontrado.',
+        INSTALLING: (tools) => `Instalando agentes para: ${tools}...`,
+        FINISHED: 'Instalação finalizada!',
+        ROO_WARNING: 'Lembre-se de configurar os Custom Modes em settings.json para Roo/Cline.',
+        ROO_WARNING_TITLE: 'Aviso',
+        FAILED: 'Falhou',
+    },
+    TOOLS: {
+        GEMINI: 'Gemini CLI',
+        ROO: 'Roo Code',
+        CLINE: 'Cline',
+        CURSOR: 'Cursor',
+        WINDSURF: 'Windsurf',
+        TRAE: 'Trae IDE',
+        KILO: 'Kilo Code',
+        COPILOT: 'GitHub Copilot',
+        WEB: 'OpenAI / Claude',
+        OPENCODE: 'OpenCode',
+    },
+    LANGUAGE_RULES: {
+        EN: 'Always reply in English unless told otherwise.',
+        PT_BR: 'Responda sempre em Português (Brasil), a menos que solicitado o contrário.',
+        ES: 'Responda siempre en Español, a menos que se solicite lo contrario.',
+    }
+};
+
+const ES = {
+    INTRO: {
+        TITLE: ' UNIVERSAL SPEC CLI ',
+        UPGRADE_TITLE: ' SDD TOOLKIT: MODO ACTUALIZACIÓN ',
+    },
+    GENERAL: {
+        CANCELLED: 'Operación cancelada.',
+    },
+    UPGRADE: {
+        NO_CONFIG: 'No se detectó configuración existente. Iniciando instalación estándar.',
+        NO_CONFIG_TITLE: 'Info',
+        DETECTED_TOOLS: (tools) => `Herramientas detectadas: ${tools}`,
+        DETECTED_TITLE: 'Actualizando...',
+        SUCCESS: '¡Agentes actualizados con éxito! 🚀',
+    },
+    SCAFFOLD: {
+        LOADING: 'Verificando estructura del espacio de trabajo...',
+        SUCCESS: '✔ Estructura de carpetas (docs/) creada.',
+        ALREADY_EXISTS: '✔ Estructura de carpetas (docs/) verificada.',
+        ERROR: 'Fallo al verificar estructura del espacio de trabajo.',
+    },
+    SETUP: {
+        STACK_SELECT: '¿Cuál es su perfil tecnológico (Stack)?',
+        GLOBAL_RULES: '¿Desea agregar Reglas Globales para TODOS los agentes?',
+        GLOBAL_RULES_HINT: 'Ej: Siempre responda en Español; Use Conventional Commits...',
+        TOOL_SELECT: '¿Para qué herramientas desea instalar los Agentes?',
+        TOOL_HINT: 'Espacio para seleccionar, Enter para confirmar',
+        NO_TOOLS: 'Ninguna herramienta seleccionada. Operación cancelada.',
+        SUCCESS: '¡Instalación completada con éxito! 🚀',
+    },
+    INSTALL: {
+        LOADING: 'Cargando definiciones...',
+        NO_AGENTS: 'No se encontraron agentes válidos.',
+        INSTALLING: (tools) => `Instalando agentes para: ${tools}...`,
+        FINISHED: '¡Instalación finalizada!',
+        ROO_WARNING: 'Recuerde configurar los Modos Personalizados en settings.json para Roo/Cline.',
+        ROO_WARNING_TITLE: 'Aviso',
+        FAILED: 'Falló',
+    },
+    TOOLS: {
+        GEMINI: 'Gemini CLI',
+        ROO: 'Roo Code',
+        CLINE: 'Cline',
+        CURSOR: 'Cursor',
+        WINDSURF: 'Windsurf',
+        TRAE: 'Trae IDE',
+        KILO: 'Kilo Code',
+        COPILOT: 'GitHub Copilot',
+        WEB: 'OpenAI / Claude',
+        OPENCODE: 'OpenCode',
+    },
+    LANGUAGE_RULES: {
+        EN: 'Always reply in English unless told otherwise.',
+        PT_BR: 'Responda sempre em Português (Brasil), a menos que solicitado o contrário.',
+        ES: 'Responda siempre en Español, a menos que se solicite lo contrario.',
+    }
+};
+
+const TRANSLATIONS = {
+    en: EN,
+    pt_br: PT_BR,
+    es: ES
+};
+
+module.exports = { TRANSLATIONS, MESSAGES: EN };