sincron-plan 1.0.0

package/bin/install.js

@@ -0,0 +1,423 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+// Colors
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+// Get version from package.json
+const pkg = require('../package.json');
+
+// Parse args
+const args = process.argv.slice(2);
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasLocal = args.includes('--local') || args.includes('-l');
+const hasUninstall = args.includes('--uninstall') || args.includes('-u');
+const hasHelp = args.includes('--help') || args.includes('-h');
+
+// Parse --config-dir argument
+function parseConfigDirArg() {
+  const configDirIndex = args.findIndex(arg => arg === '--config-dir' || arg === '-c');
+  if (configDirIndex !== -1) {
+    const nextArg = args[configDirIndex + 1];
+    if (!nextArg || nextArg.startsWith('-')) {
+      console.error(`  ${yellow}--config-dir requires a path argument${reset}`);
+      process.exit(1);
+    }
+    return nextArg;
+  }
+  const configDirArg = args.find(arg => arg.startsWith('--config-dir=') || arg.startsWith('-c='));
+  if (configDirArg) {
+    const value = configDirArg.split('=')[1];
+    if (!value) {
+      console.error(`  ${yellow}--config-dir requires a non-empty path${reset}`);
+      process.exit(1);
+    }
+    return value;
+  }
+  return null;
+}
+const explicitConfigDir = parseConfigDirArg();
+
+const banner = `
+${cyan} ███████╗ ██╗ ███╗   ██╗  ██████╗ ██████╗   ██████╗  ███╗   ██╗
+ ██╔════╝ ██║ ████╗  ██║ ██╔════╝ ██╔══██╗ ██╔═══██╗ ████╗  ██║
+ ███████╗ ██║ ██╔██╗ ██║ ██║      ██████╔╝ ██║   ██║ ██╔██╗ ██║
+ ╚════██║ ██║ ██║╚██╗██║ ██║      ██╔══██╗ ██║   ██║ ██║╚██╗██║
+ ███████║ ██║ ██║ ╚████║ ╚██████╗ ██║  ██║ ╚██████╔╝ ██║ ╚████║
+ ╚══════╝ ╚═╝ ╚═╝  ╚═══╝  ╚═════╝ ╚═╝  ╚═╝  ╚═════╝  ╚═╝  ╚═══╝${reset}
+
+  ${green}Sincron-Plan${reset} ${dim}v${pkg.version}${reset}
+  Plugin de planejamento estruturado para Claude Code.
+  Do requisito ao PRD, com questionamento inteligente.
+`;
+
+console.log(banner);
+
+// Show help if requested
+if (hasHelp) {
+  console.log(`  ${yellow}Uso:${reset} npx sincron-plan [opções]
+
+  ${yellow}Opções:${reset}
+    ${cyan}-g, --global${reset}              Instalar globalmente (~/.claude)
+    ${cyan}-l, --local${reset}               Instalar localmente (./.claude)
+    ${cyan}-u, --uninstall${reset}           Desinstalar Sincron-Plan
+    ${cyan}-c, --config-dir <path>${reset}   Especificar diretório de config
+    ${cyan}-h, --help${reset}                Mostrar esta ajuda
+
+  ${yellow}Exemplos:${reset}
+    ${dim}# Instalação interativa${reset}
+    npx sincron-plan
+
+    ${dim}# Instalar globalmente${reset}
+    npx sincron-plan --global
+
+    ${dim}# Instalar apenas no projeto atual${reset}
+    npx sincron-plan --local
+
+    ${dim}# Desinstalar globalmente${reset}
+    npx sincron-plan --global --uninstall
+
+  ${yellow}Comandos disponíveis após instalação:${reset}
+    ${cyan}/sincron-plan${reset} [descrição]  - Planejamento estruturado com PRD
+    ${cyan}/sincron-map${reset}               - Mapear codebase existente
+`);
+  process.exit(0);
+}
+
+/**
+ * Expand ~ to home directory
+ */
+function expandTilde(filePath) {
+  if (filePath && filePath.startsWith('~/')) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}
+
+/**
+ * Get the global config directory for Claude Code
+ */
+function getGlobalDir(explicitDir = null) {
+  if (explicitDir) {
+    return expandTilde(explicitDir);
+  }
+  if (process.env.CLAUDE_CONFIG_DIR) {
+    return expandTilde(process.env.CLAUDE_CONFIG_DIR);
+  }
+  return path.join(os.homedir(), '.claude');
+}
+
+/**
+ * Read and parse settings.json
+ */
+function readSettings(settingsPath) {
+  if (fs.existsSync(settingsPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch (e) {
+      return {};
+    }
+  }
+  return {};
+}
+
+/**
+ * Write settings.json with proper formatting
+ */
+function writeSettings(settingsPath, settings) {
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+
+/**
+ * Recursively copy directory, replacing paths in .md files
+ */
+function copyWithPathReplacement(srcDir, destDir, pathPrefix) {
+  if (fs.existsSync(destDir)) {
+    fs.rmSync(destDir, { recursive: true });
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyWithPathReplacement(srcPath, destPath, pathPrefix);
+    } else if (entry.name.endsWith('.md')) {
+      let content = fs.readFileSync(srcPath, 'utf8');
+      content = content.replace(/~\/\.claude\//g, pathPrefix);
+      fs.writeFileSync(destPath, content);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Verify a directory exists and contains files
+ */
+function verifyInstalled(dirPath, description) {
+  if (!fs.existsSync(dirPath)) {
+    console.error(`  ${yellow}✗${reset} Falha ao instalar ${description}: diretório não criado`);
+    return false;
+  }
+  try {
+    const entries = fs.readdirSync(dirPath);
+    if (entries.length === 0) {
+      console.error(`  ${yellow}✗${reset} Falha ao instalar ${description}: diretório vazio`);
+      return false;
+    }
+  } catch (e) {
+    console.error(`  ${yellow}✗${reset} Falha ao instalar ${description}: ${e.message}`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Uninstall Sincron-Plan from the specified directory
+ */
+function uninstall(isGlobal) {
+  const targetDir = isGlobal
+    ? getGlobalDir(explicitConfigDir)
+    : path.join(process.cwd(), '.claude');
+
+  const locationLabel = isGlobal
+    ? targetDir.replace(os.homedir(), '~')
+    : targetDir.replace(process.cwd(), '.');
+
+  console.log(`  Desinstalando Sincron-Plan de ${cyan}${locationLabel}${reset}\n`);
+
+  if (!fs.existsSync(targetDir)) {
+    console.log(`  ${yellow}⚠${reset} Diretório não existe: ${locationLabel}`);
+    console.log(`  Nada para desinstalar.\n`);
+    return;
+  }
+
+  let removedCount = 0;
+
+  // 1. Remove sincron-plan commands
+  const commandsToRemove = ['sincron-plan.md', 'sincron-map.md'];
+  const commandsDir = path.join(targetDir, 'commands');
+  if (fs.existsSync(commandsDir)) {
+    for (const cmd of commandsToRemove) {
+      const cmdPath = path.join(commandsDir, cmd);
+      if (fs.existsSync(cmdPath)) {
+        fs.unlinkSync(cmdPath);
+        removedCount++;
+      }
+    }
+    if (removedCount > 0) {
+      console.log(`  ${green}✓${reset} Removidos ${removedCount} comandos`);
+    }
+  }
+
+  // 2. Remove sincron-plan agents
+  const agentsDir = path.join(targetDir, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    const agentsToRemove = ['questionador.md', 'pesquisador.md', 'mapeador.md', 'planejador.md'];
+    let agentCount = 0;
+    for (const agent of agentsToRemove) {
+      const agentPath = path.join(agentsDir, agent);
+      if (fs.existsSync(agentPath)) {
+        fs.unlinkSync(agentPath);
+        agentCount++;
+      }
+    }
+    if (agentCount > 0) {
+      removedCount++;
+      console.log(`  ${green}✓${reset} Removidos ${agentCount} agentes`);
+    }
+  }
+
+  // 3. Remove sincron-plan templates
+  const templatesDir = path.join(targetDir, 'sincron-plan');
+  if (fs.existsSync(templatesDir)) {
+    fs.rmSync(templatesDir, { recursive: true });
+    removedCount++;
+    console.log(`  ${green}✓${reset} Removido sincron-plan/`);
+  }
+
+  if (removedCount === 0) {
+    console.log(`  ${yellow}⚠${reset} Nenhum arquivo do Sincron-Plan encontrado.`);
+  }
+
+  console.log(`
+  ${green}Pronto!${reset} Sincron-Plan foi desinstalado.
+  Seus outros arquivos e configurações foram preservados.
+`);
+}
+
+/**
+ * Install Sincron-Plan to the specified directory
+ */
+function install(isGlobal) {
+  const src = path.join(__dirname, '..');
+  const targetDir = isGlobal
+    ? getGlobalDir(explicitConfigDir)
+    : path.join(process.cwd(), '.claude');
+
+  const locationLabel = isGlobal
+    ? targetDir.replace(os.homedir(), '~')
+    : targetDir.replace(process.cwd(), '.');
+
+  const pathPrefix = isGlobal
+    ? `${targetDir}/`
+    : './.claude/';
+
+  console.log(`  Instalando em ${cyan}${locationLabel}${reset}\n`);
+
+  const failures = [];
+
+  // 1. Create directories
+  fs.mkdirSync(path.join(targetDir, 'commands'), { recursive: true });
+  fs.mkdirSync(path.join(targetDir, 'agents'), { recursive: true });
+
+  // 2. Copy commands
+  const commandsSrc = path.join(src, 'commands');
+  if (fs.existsSync(commandsSrc)) {
+    const commandFiles = fs.readdirSync(commandsSrc).filter(f => f.endsWith('.md'));
+    for (const file of commandFiles) {
+      let content = fs.readFileSync(path.join(commandsSrc, file), 'utf8');
+      content = content.replace(/~\/\.claude\//g, pathPrefix);
+      fs.writeFileSync(path.join(targetDir, 'commands', file), content);
+    }
+    console.log(`  ${green}✓${reset} Instalados ${commandFiles.length} comandos`);
+  } else {
+    failures.push('commands');
+  }
+
+  // 3. Copy agents
+  const agentsSrc = path.join(src, 'agents');
+  if (fs.existsSync(agentsSrc)) {
+    const agentFiles = fs.readdirSync(agentsSrc).filter(f => f.endsWith('.md'));
+    for (const file of agentFiles) {
+      let content = fs.readFileSync(path.join(agentsSrc, file), 'utf8');
+      content = content.replace(/~\/\.claude\//g, pathPrefix);
+      fs.writeFileSync(path.join(targetDir, 'agents', file), content);
+    }
+    console.log(`  ${green}✓${reset} Instalados ${agentFiles.length} agentes`);
+  } else {
+    failures.push('agents');
+  }
+
+  // 4. Copy templates to sincron-plan directory
+  const templatesSrc = path.join(src, 'templates');
+  const templatesDest = path.join(targetDir, 'sincron-plan', 'templates');
+  if (fs.existsSync(templatesSrc)) {
+    copyWithPathReplacement(templatesSrc, templatesDest, pathPrefix);
+    if (verifyInstalled(templatesDest, 'templates')) {
+      console.log(`  ${green}✓${reset} Instalados templates`);
+    } else {
+      failures.push('templates');
+    }
+  }
+
+  // 5. Copy docs
+  const docsSrc = path.join(src, 'docs');
+  const docsDest = path.join(targetDir, 'sincron-plan', 'docs');
+  if (fs.existsSync(docsSrc)) {
+    copyWithPathReplacement(docsSrc, docsDest, pathPrefix);
+    if (verifyInstalled(docsDest, 'docs')) {
+      console.log(`  ${green}✓${reset} Instalada documentação`);
+    } else {
+      failures.push('docs');
+    }
+  }
+
+  // 6. Write VERSION file
+  const versionDest = path.join(targetDir, 'sincron-plan', 'VERSION');
+  fs.mkdirSync(path.dirname(versionDest), { recursive: true });
+  fs.writeFileSync(versionDest, pkg.version);
+  console.log(`  ${green}✓${reset} Escrito VERSION (${pkg.version})`);
+
+  if (failures.length > 0) {
+    console.error(`\n  ${yellow}Instalação incompleta!${reset} Falhou: ${failures.join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(`
+  ${green}Pronto!${reset} Abra o Claude Code e execute ${cyan}/sincron-plan${reset} ou ${cyan}/sincron-map${reset}.
+
+  ${cyan}Comandos disponíveis:${reset}
+    /sincron-plan [descrição]  - Planejamento estruturado com PRD
+    /sincron-map               - Mapear codebase existente
+
+  ${cyan}Dica:${reset} Sincron-Plan funciona junto com Sincron-Auto!
+  Use /sincron-plan para planejar e /sincron-auto para executar.
+
+  ${cyan}Documentação:${reset} https://github.com/MLTCorp/sincron-auto/tree/sincron-plan
+`);
+}
+
+/**
+ * Prompt for install location
+ */
+function promptLocation() {
+  if (!process.stdin.isTTY) {
+    console.log(`  ${yellow}Terminal não-interativo detectado, usando instalação global${reset}\n`);
+    install(true);
+    return;
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  let answered = false;
+
+  rl.on('close', () => {
+    if (!answered) {
+      answered = true;
+      console.log(`\n  ${yellow}Instalação cancelada${reset}\n`);
+      process.exit(0);
+    }
+  });
+
+  const globalPath = getGlobalDir(explicitConfigDir).replace(os.homedir(), '~');
+
+  console.log(`  ${yellow}Onde você quer instalar?${reset}
+
+  ${cyan}1${reset}) Global ${dim}(${globalPath})${reset} - disponível em todos os projetos
+  ${cyan}2${reset}) Local  ${dim}(./.claude)${reset} - apenas neste projeto
+`);
+
+  rl.question(`  Escolha ${dim}[1]${reset}: `, (answer) => {
+    answered = true;
+    rl.close();
+    const choice = answer.trim() || '1';
+    const isGlobal = choice !== '2';
+    install(isGlobal);
+  });
+}
+
+// Main
+if (hasGlobal && hasLocal) {
+  console.error(`  ${yellow}Não é possível especificar --global e --local juntos${reset}`);
+  process.exit(1);
+} else if (explicitConfigDir && hasLocal) {
+  console.error(`  ${yellow}Não é possível usar --config-dir com --local${reset}`);
+  process.exit(1);
+} else if (hasUninstall) {
+  if (!hasGlobal && !hasLocal) {
+    console.error(`  ${yellow}--uninstall requer --global ou --local${reset}`);
+    console.error(`  Exemplo: npx sincron-plan --global --uninstall`);
+    process.exit(1);
+  }
+  uninstall(hasGlobal);
+} else if (hasGlobal || hasLocal) {
+  install(hasGlobal);
+} else {
+  promptLocation();
+}

package/commands/sincron-map.md

@@ -0,0 +1,190 @@
+---
+name: sincron-map
+description: Mapeia codebase existente gerando documentação estruturada
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - Task
+---
+
+# /sincron-map - Mapeamento de Codebase
+
+## Propósito
+Analisar codebase existente e gerar documentação estruturada em `.sincron-plan/codebase/`.
+
+## Quando Usar
+- Projetos brownfield (código existente)
+- Antes de planejar trabalho em código desconhecido
+- Onboarding em projeto novo
+
+## Instruções de Execução
+
+### FASE 1: Verificar Mapeamento Existente
+
+Verificar se `.sincron-plan/codebase/` existe e contém os 4 documentos.
+
+**SE existe mapeamento completo:**
+Perguntar ao usuário usando AskUserQuestion:
+```
+"Encontrei mapeamento existente em .sincron-plan/codebase/. O que deseja fazer?"
+Opções:
+- "Atualizar" - Refazer o mapeamento
+- "Usar existente" - Manter o atual
+- "Ignorar" - Começar do zero
+```
+
+**SE não existe ou está incompleto:**
+Continuar para Fase 2.
+
+### FASE 2: Criar Diretório de Output
+
+```bash
+mkdir -p .sincron-plan/codebase
+```
+
+### FASE 3: Spawnar Agentes Mapeadores em Paralelo
+
+**IMPORTANTE**: Spawnar exatamente 2 agentes em paralelo para arquitetura anti-OOM.
+
+**Agente 1 - Tech/Arch:**
+```
+Task(
+  subagent_type: "general-purpose",
+  prompt: "Você é o Mapeador (Instância Tech/Arch).
+
+Sua missão: Analisar o codebase neste diretório e gerar 2 documentos:
+1. .sincron-plan/codebase/STACK.md
+2. .sincron-plan/codebase/ARCHITECTURE.md
+
+Siga as instruções detalhadas em sincron-plan/agents/mapeador.md.
+Use os templates em sincron-plan/templates/codebase/.
+
+Processo:
+1. Glob para encontrar arquivos de configuração (package.json, tsconfig.json, etc)
+2. Read arquivos de configuração para identificar stack
+3. Glob para mapear estrutura de diretórios
+4. Grep para identificar patterns de arquitetura
+5. Escrever STACK.md com tecnologias e dependências
+6. Escrever ARCHITECTURE.md com padrões e fluxos
+
+Retorne APENAS:
+mapping_complete
+Files:
+- .sincron-plan/codebase/STACK.md ([N] lines)
+- .sincron-plan/codebase/ARCHITECTURE.md ([N] lines)"
+)
+```
+
+**Agente 2 - Quality/Risk:**
+```
+Task(
+  subagent_type: "general-purpose",
+  prompt: "Você é o Mapeador (Instância Quality/Risk).
+
+Sua missão: Analisar o codebase neste diretório e gerar 2 documentos:
+1. .sincron-plan/codebase/STRUCTURE.md
+2. .sincron-plan/codebase/CONCERNS.md
+
+Siga as instruções detalhadas em sincron-plan/agents/mapeador.md.
+Use os templates em sincron-plan/templates/codebase/.
+
+Processo:
+1. Glob/Bash para mapear estrutura de diretórios
+2. Read arquivos índice e principais
+3. Grep para TODO, FIXME, HACK, @deprecated
+4. Identificar convenções de nomenclatura
+5. Escrever STRUCTURE.md com organização e guias
+6. Escrever CONCERNS.md com débitos e riscos
+
+Retorne APENAS:
+mapping_complete
+Files:
+- .sincron-plan/codebase/STRUCTURE.md ([N] lines)
+- .sincron-plan/codebase/CONCERNS.md ([N] lines)"
+)
+```
+
+### FASE 4: Aguardar e Verificar
+
+Aguardar ambos agentes retornarem.
+
+**Verificação de qualidade:**
+- Todos 4 documentos existem em `.sincron-plan/codebase/`
+- Cada documento tem >20 linhas
+- Nenhum documento tem placeholders `[TBD]` ou `[TODO]`
+
+**SE verificação falhar:**
+Informar qual documento está incompleto e oferecer re-executar.
+
+### FASE 5: Atualizar State
+
+Criar ou atualizar `.sincron-plan/state.json`:
+```json
+{
+  "status": "mapped",
+  "project_name": "[detectar do package.json ou diretório]",
+  "has_codebase_map": true,
+  "mapping_date": "[YYYY-MM-DD]",
+  "files": {
+    "STACK.md": "[N] lines",
+    "ARCHITECTURE.md": "[N] lines",
+    "STRUCTURE.md": "[N] lines",
+    "CONCERNS.md": "[N] lines"
+  }
+}
+```
+
+### FASE 6: Exibir Resumo
+
+```markdown
+## ✅ Mapeamento Completo
+
+Documentação gerada em `.sincron-plan/codebase/`:
+
+| Documento | Linhas | Conteúdo |
+|-----------|--------|----------|
+| STACK.md | [N] | Tecnologias e dependências |
+| ARCHITECTURE.md | [N] | Padrões e fluxos de dados |
+| STRUCTURE.md | [N] | Organização e convenções |
+| CONCERNS.md | [N] | Débitos técnicos e riscos |
+
+### Próximo Passo
+Execute `/sincron-plan` para iniciar o planejamento estruturado.
+```
+
+## Tratamento de Erros
+
+### Diretório Vazio
+```
+"Este diretório parece estar vazio ou não contém código fonte.
+O mapeamento requer um projeto existente.
+
+Para projetos novos (greenfield), use diretamente /sincron-plan."
+```
+
+### Linguagem Não Identificada
+```
+"Não consegui identificar a linguagem/stack principal.
+Arquivos encontrados: [lista]
+
+Deseja continuar mesmo assim? O mapeamento pode estar incompleto."
+```
+
+### Agente Falhou
+```
+"O mapeamento de [STACK/ARCHITECTURE/STRUCTURE/CONCERNS] falhou.
+Erro: [mensagem]
+
+Deseja tentar novamente apenas este documento?"
+```
+
+## Output Final
+
+Diretório `.sincron-plan/codebase/` com:
+- `STACK.md` - Stack tecnológico
+- `ARCHITECTURE.md` - Padrões arquiteturais
+- `STRUCTURE.md` - Organização do código
+- `CONCERNS.md` - Débitos e riscos