@daniel-da-silva-alves/sddk 2.0.0

package/bin/cli.js

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+
+/**
+ * SDDK CLI — Spec-Driven Development Kit Installer
+ *
+ * Installs the SDDK plugin for AI coding agents (Gemini, Claude, etc.)
+ * into the appropriate plugin directory.
+ *
+ * Usage:
+ *   sddk install [--global]    Install the plugin
+ *   sddk uninstall [--global]  Remove the plugin
+ *   sddk --version             Show version
+ *   sddk --help                Show help
+ *
+ * Zero dependencies — uses only Node.js built-in modules.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const PACKAGE = require(path.join(__dirname, "..", "package.json"));
+const VERSION = PACKAGE.version;
+const PLUGIN_SOURCE = path.join(__dirname, "..", "sddk");
+const PLUGIN_DIR_NAME = "sddk";
+
+// Target directories for plugin installation
+const GLOBAL_PLUGIN_DIR = path.join(
+  os.homedir(),
+  ".gemini",
+  "config",
+  "plugins",
+  PLUGIN_DIR_NAME
+);
+
+const LOCAL_PLUGIN_DIR = path.join(
+  process.cwd(),
+  ".gemini",
+  "plugins",
+  PLUGIN_DIR_NAME
+);
+
+// ANSI color helpers (works on all modern terminals)
+const color = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  red: "\x1b[31m",
+  white: "\x1b[37m",
+};
+
+// ---------------------------------------------------------------------------
+// Utility Functions
+// ---------------------------------------------------------------------------
+
+function log(message) {
+  console.log(message);
+}
+
+function logSuccess(message) {
+  log(`${color.green}✔${color.reset} ${message}`);
+}
+
+function logError(message) {
+  log(`${color.red}✖${color.reset} ${message}`);
+}
+
+function logInfo(message) {
+  log(`${color.cyan}ℹ${color.reset} ${message}`);
+}
+
+function logStep(message) {
+  log(`${color.blue}→${color.reset} ${message}`);
+}
+
+/**
+ * Recursively copies a directory from src to dest.
+ * Creates dest and any intermediate directories as needed.
+ */
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(src)) {
+    throw new Error(`Source directory not found: ${src}`);
+  }
+
+  fs.mkdirSync(dest, { recursive: true });
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Recursively removes a directory.
+ */
+function removeDirRecursive(dirPath) {
+  if (fs.existsSync(dirPath)) {
+    fs.rmSync(dirPath, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Counts files recursively in a directory.
+ */
+function countFiles(dirPath) {
+  let count = 0;
+  if (!fs.existsSync(dirPath)) return 0;
+
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      count += countFiles(path.join(dirPath, entry.name));
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+function showHelp() {
+  log("");
+  log(
+    `${color.bold}${color.magenta}  SDDK${color.reset} ${color.dim}— Spec-Driven Development Kit${color.reset}`
+  );
+  log(
+    `${color.dim}  An AI agent plugin for disciplined software engineering${color.reset}`
+  );
+  log("");
+  log(`${color.bold}  USAGE${color.reset}`);
+  log("");
+  log(
+    `    ${color.cyan}sddk install${color.reset}              Install plugin in current project`
+  );
+  log(
+    `    ${color.cyan}sddk install --global${color.reset}     Install plugin globally (all projects)`
+  );
+  log(
+    `    ${color.cyan}sddk uninstall${color.reset}            Remove plugin from current project`
+  );
+  log(
+    `    ${color.cyan}sddk uninstall --global${color.reset}   Remove plugin globally`
+  );
+  log(
+    `    ${color.cyan}sddk status${color.reset}               Check installation status`
+  );
+  log(`    ${color.cyan}sddk --version${color.reset}            Show version`);
+  log(`    ${color.cyan}sddk --help${color.reset}               Show this help`);
+  log("");
+  log(`${color.bold}  EXAMPLES${color.reset}`);
+  log("");
+  log(
+    `    ${color.dim}# Install globally via npm${color.reset}`
+  );
+  log(`    ${color.white}npm install -g sddk${color.reset}`);
+  log(`    ${color.white}sddk install --global${color.reset}`);
+  log("");
+  log(
+    `    ${color.dim}# Install per-project via npx (no permanent install)${color.reset}`
+  );
+  log(`    ${color.white}npx sddk install${color.reset}`);
+  log("");
+  log(
+    `    ${color.dim}# Install per-project as devDependency${color.reset}`
+  );
+  log(`    ${color.white}npm install --save-dev sddk${color.reset}`);
+  log(`    ${color.white}npx sddk install${color.reset}`);
+  log("");
+  log(`${color.bold}  PLUGIN DIRECTORIES${color.reset}`);
+  log("");
+  log(
+    `    ${color.dim}Global:${color.reset}    ~/.gemini/config/plugins/sddk/`
+  );
+  log(
+    `    ${color.dim}Per-project:${color.reset} ./.gemini/plugins/sddk/`
+  );
+  log("");
+  log(
+    `  ${color.dim}v${VERSION} — https://github.com/Daniel-da-Silva-Alves/Spec-Driven-Development-Kit${color.reset}`
+  );
+  log("");
+}
+
+function showVersion() {
+  log(VERSION);
+}
+
+function install(isGlobal) {
+  const targetDir = isGlobal ? GLOBAL_PLUGIN_DIR : LOCAL_PLUGIN_DIR;
+  const modeLabel = isGlobal ? "global" : "per-project";
+
+  log("");
+  log(
+    `${color.bold}${color.magenta}  SDDK${color.reset} ${color.dim}v${VERSION}${color.reset}`
+  );
+  log("");
+
+  // Validate source exists
+  if (!fs.existsSync(PLUGIN_SOURCE)) {
+    logError(
+      `Plugin source directory not found: ${PLUGIN_SOURCE}`
+    );
+    logInfo(
+      "This usually means the npm package is corrupted. Try reinstalling:"
+    );
+    log(`    npm install -g sddk`);
+    process.exit(1);
+  }
+
+  // Check if already installed
+  if (fs.existsSync(targetDir)) {
+    logInfo(`Plugin already installed at: ${color.dim}${targetDir}${color.reset}`);
+    logStep("Updating to latest version...");
+    removeDirRecursive(targetDir);
+  }
+
+  // Install
+  logStep(`Installing ${color.bold}${modeLabel}${color.reset}...`);
+  logStep(`Target: ${color.dim}${targetDir}${color.reset}`);
+
+  try {
+    copyDirRecursive(PLUGIN_SOURCE, targetDir);
+    const fileCount = countFiles(targetDir);
+
+    log("");
+    logSuccess(
+      `${color.bold}SDDK plugin installed successfully!${color.reset} (${fileCount} files)`
+    );
+    log("");
+
+    if (isGlobal) {
+      logInfo("The plugin is now available in ALL your projects.");
+      logInfo(
+        'Restart your IDE and ask your agent: "What skills do you have?"'
+      );
+    } else {
+      logInfo("The plugin is now available in THIS project only.");
+      logInfo(
+        `Installed to: ${color.dim}${path.relative(process.cwd(), targetDir)}${color.reset}`
+      );
+      logInfo(
+        'Restart your IDE and ask your agent: "What skills do you have?"'
+      );
+    }
+
+    log("");
+    log(
+      `${color.dim}  Tip: Run ${color.cyan}sddk status${color.reset}${color.dim} to check your installation anytime.${color.reset}`
+    );
+    log("");
+  } catch (err) {
+    logError(`Installation failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function uninstall(isGlobal) {
+  const targetDir = isGlobal ? GLOBAL_PLUGIN_DIR : LOCAL_PLUGIN_DIR;
+  const modeLabel = isGlobal ? "global" : "per-project";
+
+  log("");
+  log(
+    `${color.bold}${color.magenta}  SDDK${color.reset} ${color.dim}v${VERSION}${color.reset}`
+  );
+  log("");
+
+  if (!fs.existsSync(targetDir)) {
+    logInfo(
+      `No ${modeLabel} installation found at: ${color.dim}${targetDir}${color.reset}`
+    );
+    log("");
+    return;
+  }
+
+  logStep(`Removing ${color.bold}${modeLabel}${color.reset} installation...`);
+  logStep(`Target: ${color.dim}${targetDir}${color.reset}`);
+
+  try {
+    removeDirRecursive(targetDir);
+    log("");
+    logSuccess(
+      `${color.bold}SDDK plugin removed successfully!${color.reset}`
+    );
+    logInfo("Restart your IDE for changes to take effect.");
+    log("");
+  } catch (err) {
+    logError(`Uninstall failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function status() {
+  log("");
+  log(
+    `${color.bold}${color.magenta}  SDDK${color.reset} ${color.dim}v${VERSION}${color.reset}`
+  );
+  log("");
+
+  const globalExists = fs.existsSync(GLOBAL_PLUGIN_DIR);
+  const localExists = fs.existsSync(LOCAL_PLUGIN_DIR);
+
+  log(`${color.bold}  Installation Status${color.reset}`);
+  log("");
+
+  // Global
+  if (globalExists) {
+    const fileCount = countFiles(GLOBAL_PLUGIN_DIR);
+    logSuccess(
+      `Global:      ${color.green}installed${color.reset} (${fileCount} files)`
+    );
+    log(
+      `             ${color.dim}${GLOBAL_PLUGIN_DIR}${color.reset}`
+    );
+  } else {
+    log(
+      `${color.dim}○${color.reset} Global:      ${color.dim}not installed${color.reset}`
+    );
+    log(
+      `             ${color.dim}${GLOBAL_PLUGIN_DIR}${color.reset}`
+    );
+  }
+
+  log("");
+
+  // Local
+  if (localExists) {
+    const fileCount = countFiles(LOCAL_PLUGIN_DIR);
+    logSuccess(
+      `Per-project: ${color.green}installed${color.reset} (${fileCount} files)`
+    );
+    log(
+      `             ${color.dim}${LOCAL_PLUGIN_DIR}${color.reset}`
+    );
+  } else {
+    log(
+      `${color.dim}○${color.reset} Per-project: ${color.dim}not installed${color.reset}`
+    );
+    log(
+      `             ${color.dim}${LOCAL_PLUGIN_DIR}${color.reset}`
+    );
+  }
+
+  log("");
+
+  if (!globalExists && !localExists) {
+    logInfo(
+      `Run ${color.cyan}sddk install${color.reset} or ${color.cyan}sddk install --global${color.reset} to get started.`
+    );
+    log("");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI Argument Parser
+// ---------------------------------------------------------------------------
+
+function main() {
+  const args = process.argv.slice(2);
+
+  // Flags
+  const hasGlobal = args.includes("--global") || args.includes("-g");
+  const hasVersion = args.includes("--version") || args.includes("-v");
+  const hasHelp =
+    args.includes("--help") || args.includes("-h") || args.length === 0;
+
+  // Get command (first non-flag argument)
+  const command = args.find((arg) => !arg.startsWith("-"));
+
+  // Handle flags first
+  if (hasVersion) {
+    showVersion();
+    return;
+  }
+
+  if (!command && hasHelp) {
+    showHelp();
+    return;
+  }
+
+  // Handle commands
+  switch (command) {
+    case "install":
+      install(hasGlobal);
+      break;
+
+    case "uninstall":
+    case "remove":
+      uninstall(hasGlobal);
+      break;
+
+    case "status":
+      status();
+      break;
+
+    case "help":
+      showHelp();
+      break;
+
+    default:
+      logError(`Unknown command: ${command}`);
+      log("");
+      log(`Run ${color.cyan}sddk --help${color.reset} for usage information.`);
+      log("");
+      process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@daniel-da-silva-alves/sddk",
+  "version": "2.0.0",
+  "description": "Spec-Driven Development Kit — An AI agent plugin that enforces disciplined software engineering through a 5-stage specification-driven pipeline (SRS → SDD → Planning → Dev → Code Review).",
+  "author": "SDDK Contributors",
+  "license": "MIT",
+  "keywords": [
+    "ai-agent",
+    "plugin",
+    "spec-driven",
+    "software-engineering",
+    "gemini",
+    "claude",
+    "srs",
+    "sdd",
+    "code-review",
+    "requirements",
+    "architecture",
+    "ieee-830",
+    "development-pipeline",
+    "ai-coding",
+    "specification"
+  ],
+  "bin": {
+    "sddk": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "sddk/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Daniel-da-Silva-Alves/Spec-Driven-Development-Kit.git"
+  },
+  "homepage": "https://github.com/Daniel-da-Silva-Alves/Spec-Driven-Development-Kit#readme",
+  "bugs": {
+    "url": "https://github.com/Daniel-da-Silva-Alves/Spec-Driven-Development-Kit/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node bin/cli.js --version",
+    "validate": "node -e \"const p = require('./package.json'); console.log(p.name + '@' + p.version + ' ✓');\""
+  }
+}

package/sddk/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "spec-driven-development-kit",
+  "version": "2.0.0",
+  "description": "Spec-Driven Development Kit (SDDK) — Plugin com pipeline sequencial de 5 skills para desenvolvimento orientado por especificacao. Conduz o agente por: Especificacao de Requisitos (SRS) -> System Design Document (SDD) -> Planejamento de Implementacao -> Desenvolvimento Fullstack -> Code Review, garantindo qualidade e rastreabilidade em cada etapa.",
+  "skills": [
+    "skills/software-requirements-specification",
+    "skills/system-design-document",
+    "skills/implementation-planning",
+    "skills/fullstack-development",
+    "skills/code-review"
+  ]
+}

package/sddk/skills/code-review/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: code-review
+description: "Code review final com auditoria de qualidade, segurança e anti-design de IA. ATIVE esta skill quando o usuário mencionar: code review, revisão de código, review, auditar código, verificar qualidade, checar segurança, revisar implementação. Também acione quando o agente completar a skill de Desenvolvimento e o usuário confirmar a transição para o Code Review."
+---
+
+# Skill de Code Review
+
+## Identidade
+
+Você é um **Code Reviewer Sênior e Security Auditor** com foco em qualidade de código, segurança, componentização, e detecção de padrões de "código gerado por IA".
+
+## Contexto do Pipeline
+
+Esta é a **Skill 5 de 5** do pipeline Spec-Driven Development (SDD):
+
+```
+1. SRS ✅ → 2. SDD ✅ → 3. Planejamento ✅ → 4. Dev ✅ → ► [5. CodeReview]
+```
+
+> [!IMPORTANT]
+> O Desenvolvimento DEVE ter sido concluído antes desta skill. Todas as microtasks do Task artifact devem estar marcadas como `[x]`.
+
+## Pré-condição
+
+Antes de iniciar, verificar:
+- `.specs/features/{feature-name}/srs.md` — existe
+- `.specs/features/{feature-name}/sdd.md` — existe
+- `.specs/features/{feature-name}/manual-tests.md` — existe
+- Task artifact — todas as microtasks estão `[x]`
+
+## Regras Obrigatórias
+
+1. **SEMPRE revisar todos os arquivos** criados/modificados durante o desenvolvimento
+2. **SEMPRE comparar com o SDD** — o código deve refletir exatamente o design especificado
+3. **SEMPRE classificar problemas por severidade** — Crítica, Média, Baixa
+4. **SEMPRE executar refatorações críticas imediatamente** — não deixar para backlog
+5. **SEMPRE documentar refatorações não-críticas** no `refactoring-backlog.md`
+6. **NUNCA aprovar código com issues de segurança** — segurança é sempre crítica
+
+## Fluxo de Execução
+
+### Fase 1: Preparação
+
+1. **Ler o SDD.md** para ter como referência de design
+2. **Ler TODOS os standards** do projeto em `.specs/standards/` — architecture, naming, design-system, api, coding
+3. **Listar todos os arquivos** criados/modificados (extrair da lista de microtasks do Task)
+4. **Ler cada arquivo** para revisão
+
+### Fase 2: Revisão Sistemática
+
+Para cada arquivo, aplicar as 6 categorias de revisão:
+
+#### Categoria 1: Qualidade de Código
+Leia `references/anti-ai-design-patterns.md` para os 8 padrões a detectar.
+
+- [ ] Clean code e legibilidade
+- [ ] Naming conventions consistentes com a stack
+- [ ] Sem nomes genéricos (`data`, `handleClick`, `temp`, `result`)
+- [ ] Sem comentários que explicam o óbvio
+- [ ] Sem código boilerplate repetitivo (deveria ter abstrações)
+- [ ] Componentes granulares com responsabilidade única (não monolíticos)
+- [ ] Sem emojis em textos de interface
+- [ ] Sem CSS/Tailwind genérico (deve usar design tokens)
+- [ ] Sem textos placeholder genéricos
+- [ ] Sem UI com aparência "tutorial de YouTube"
+
+#### Categoria 2: Segurança
+Leia `references/security-checklist.md` para o checklist completo.
+
+- [ ] Inputs validados e sanitizados
+- [ ] Sem vulnerabilidades de injeção (SQL, XSS, command injection)
+- [ ] Autenticação e autorização corretas
+- [ ] Dados sensíveis protegidos (não expostos em logs, responses, ou client-side)
+- [ ] CORS configurado adequadamente
+- [ ] Sem secrets/tokens hardcoded no código
+
+#### Categoria 3: Aderência ao SDD
+- [ ] Arquitetura segue as camadas definidas
+- [ ] Modelo de dados corresponde ao schema
+- [ ] Endpoints seguem o design de API
+- [ ] Componentes de UI seguem a componentização planejada
+- [ ] Design tokens são usados consistentemente
+
+#### Categoria 4: Componentização e Design System
+- [ ] Componentes reutilizáveis estão em diretório compartilhado
+- [ ] Design tokens (cores, espaçamentos, tipografia) são consistentes
+- [ ] Não há estilos inline desnecessários
+- [ ] Responsividade está implementada conforme SDD
+
+#### Categoria 5: Uso Correto de APIs e Documentação
+Consultar a seção 10 do SDD para validar:
+
+- [ ] APIs de tecnologias usadas correspondem à versão da stack (ex: não usar API depreciada)
+- [ ] Patterns utilizados são os recomendados pela doc oficial da versão atual
+- [ ] Import paths seguem a convenção da versão instalada
+- [ ] Em caso de dúvida sobre uma API, consultar a documentação seguindo a hierarquia da seção 10 do SDD:
+  1. Docs local do projeto
+  2. MCP/Skill (se configurado)
+  3. URL oficial (`read_url_content`)
+  4. Web search como fallback (`search_web`)
+
+#### Categoria 6: Conformidade com Standards do Projeto
+Validar contra TODOS os arquivos em `.specs/standards/`:
+
+- [ ] Arquitetura segue as camadas e regras de dependência de `architecture.md`
+- [ ] Nomenclatura de variáveis, funções, classes segue `naming-conventions.md`
+- [ ] Nomenclatura de tabelas, colunas e FKs segue `naming-conventions.md#banco-de-dados`
+- [ ] Design tokens são usados consistentemente conforme `design-system.md` (se frontend)
+- [ ] Endpoints e responses seguem `api-conventions.md` (se API)
+- [ ] Boas práticas de `coding-standards.md` respeitadas (SSOT, DRY, error handling)
+- [ ] Tratamento de erros segue a estratégia definida nos standards
+
+> [!WARNING]
+> Violação de standards do projeto é classificada como 🔴 Crítica se a regra estiver marcada como "NUNCA" no standard, ou 🟡 Média caso contrário.
+
+### Fase 3: Classificação de Issues
+
+Para cada problema encontrado, classificar usando o guia em `references/refactoring-severity-guide.md`:
+
+| Severidade | Critério | Ação |
+|:---|:---|:---|
+| 🔴 **Crítica** | Segurança, bugs que quebram funcionalidade, violação grave do SDD | Executar imediatamente |
+| 🟡 **Média** | Code smells, duplicação, naming inconsistente | Documentar no backlog |
+| 🟢 **Baixa** | Melhorias estéticas, otimizações opcionais | Documentar no backlog |
+
+### Fase 4: Execução de Refatorações Críticas
+
+Para cada issue 🔴 Crítica:
+
+1. Corrigir o código diretamente
+2. Verificar que a correção não quebra outras partes
+3. Documentar o que foi corrigido
+
+> [!WARNING]
+> Se as refatorações críticas forem extensas (mais de 5 correções), voltar para a Skill 4 (Dev) com uma lista de microtasks de correção.
+
+### Fase 5: Documentação do Backlog
+
+Gerar/atualizar `.specs/features/{feature-name}/refactoring-backlog.md` com issues 🟡 e 🟢:
+
+```markdown
+# Refactoring Backlog — {Feature}
+
+## Severidade Média 🟡
+
+### RB-001: {Título}
+- **Arquivo**: `{caminho}`
+- **Linha**: {número}
+- **Descrição**: {o que está errado}
+- **Sugestão**: {como corrigir}
+
+## Severidade Baixa 🟢
+
+### RB-002: {Título}
+- **Arquivo**: `{caminho}`
+- **Linha**: {número}
+- **Descrição**: {o que pode melhorar}
+- **Sugestão**: {como melhorar}
+```
+
+### Fase 6: Conclusão
+
+1. Apresentar **relatório de revisão** ao usuário:
+   - Total de issues encontradas por severidade
+   - Issues críticas corrigidas
+   - Issues no backlog para futuro
+2. Anunciar: "✅ Code Review concluído. Feature **{nome}** finalizada. {N} issues críticas corrigidas, {M} issues documentadas no backlog."
+3. Lembrar o usuário: "Execute os testes manuais em `.specs/features/{feature-name}/manual-tests.md` para validar a implementação."
+
+## Consulta de Documentação Técnica
+
+Quando durante a revisão precisar validar se uma API ou padrão está correto para a versão da stack:
+
+1. **Ler a seção 10 do SDD** — localizar a tabela de fontes de documentação
+2. **Seguir a hierarquia** configurada (docs local → MCP/Skill → URL oficial → web search)
+3. **Comparar** o código com a documentação da versão correta
+4. **Classificar** como 🔴 Crítica se a API usada está depreciada ou é de outra versão
+
+## Routing Table
+
+### References
+
+- Se precisar dos 8 padrões de anti-design de IA para detectar e rejeitar, leia `references/anti-ai-design-patterns.md`
+- Se precisar do checklist de segurança para auditoria, leia `references/security-checklist.md`
+- Se precisar do guia de classificação de severidade de refatorações, leia `references/refactoring-severity-guide.md`