@followthecode/cli 1.0.0

package/README.md

@@ -0,0 +1,491 @@
+# FTC CLI - Ferramenta de Análise de Repositórios Git
+
+Ferramenta de linha de comando (CLI) para análise de repositórios Git, desenvolvida seguindo a arquitetura Vertical Slice do projeto FTC.
+
+## Funcionalidades
+
+- ✅ Total de commits no repositório
+- ✅ Lista de autores e quantidade de commits por autor
+- ✅ Número total de arquivos alterados
+- ✅ Lista dos arquivos alterados com quantidade de alterações (adições/remoções)
+- ✅ Relatório resumido com datas dos primeiros e últimos commits
+- ✅ **Suporte a repositórios remotos** (clona automaticamente)
+- ✅ Filtros por data (--startDate e --endDate)
+- ✅ Exportação em JSON (--json)
+- ✅ **Exportação em CSV detalhado** (--csv) com informações por commit
+- ✅ **Tratamento robusto de erros** com mensagens claras
+- ✅ **Testes automatizados** para validação de funcionalidades
+- ✅ **Suporte a Docker** para execução em containers
+- ✅ **Uso como ferramenta global (dotnet tool)**
+
+## Simulando/Executando localmente via Docker CLI
+
+Você pode rodar o FTC CLI via Docker em ambiente local, sem scripts auxiliares, seguindo estes passos:
+
+### 1. Build da imagem Docker localmente
+
+No diretório do projeto (onde está o Dockerfile):
+
+```sh
+docker build -t ftc:latest .
+```
+
+### 2. Executar a CLI com repositório local
+
+Supondo que você tenha um repositório local em uma pasta chamada `meu-repo` no seu diretório atual:
+
+#### Linux/macOS
+```sh
+docker run --rm -v "$PWD:/repo" ftc:latest collect code "/repo/meu-repo" --json
+```
+
+#### Windows (cmd/powershell)
+```bat
+docker run --rm -v "%cd%:/repo" ftc:latest collect code "/repo/meu-repo" --json
+```
+
+- O volume `-v "$PWD:/repo"` (ou `%cd%:/repo` no Windows) faz com que a pasta atual do host seja montada como `/repo` dentro do container.
+- O parâmetro `collect code "/repo/meu-repo"` aponta para o caminho do repositório dentro do container.
+
+### 3. Executar a CLI com repositório remoto
+
+Você não precisa mapear volumes para repositórios remotos:
+
+```sh
+docker run --rm ftc:latest collect code "https://github.com/usuario/repositorio.git" --json
+```
+
+### 4. Exemplo com filtros de data
+
+```sh
+docker run --rm -v "$PWD:/repo" ftc:latest collect code "/repo/meu-repo" --startDate 2024-01-01 --endDate 2024-12-31 --json
+```
+
+### 5. Ver ajuda da CLI
+
+```sh
+docker run --rm ftc:latest --help
+```
+
+> **Resumo:**
+> - Sempre use `-v "$PWD:/repo"` (Linux/macOS) ou `-v "%cd%:/repo"` (Windows) para acessar repositórios locais.
+> - O caminho passado para `code` deve ser o caminho dentro do container, por exemplo, `"/repo/meu-repo"`.
+> - Para repositórios remotos, basta passar a URL.
+
+## Uso moderno via Docker CLI
+
+Execute diretamente, sem scripts auxiliares:
+
+### Linux/macOS
+```sh
+docker run --rm -v "$PWD:/repo" ftc:latest collect code "/repo/meu-repo" --json
+```
+
+### Windows (cmd/powershell)
+```bat
+docker run --rm -v "%cd%:/repo" ftc:latest collect code "/repo/meu-repo" --json
+```
+
+### Repositório remoto
+```sh
+docker run --rm ftc:latest collect code "https://github.com/usuario/repositorio.git" --json
+```
+
+### Com filtros de data
+```sh
+docker run --rm -v "$PWD:/repo" ftc:latest collect code "/repo/meu-repo" --startDate 2024-01-01 --endDate 2024-12-31 --json
+```
+
+> **Dica:**
+> - O volume `-v "$PWD:/repo"` (ou `%cd%:/repo` no Windows) permite que o container acesse seu repositório local.
+> - O comando `code "/repo/meu-repo"` deve apontar para o caminho dentro do container.
+
+## Uso como ferramenta global (dotnet tool)
+
+Após instalar:
+
+```sh
+dotnet tool install --global --add-source ./bin/Release ftc.cli
+```
+
+Execute de qualquer lugar:
+
+```sh
+ftc collect code "./caminho/para/meu-repo" --json
+```
+
+Exemplo com repositório remoto e filtros:
+
+```sh
+ftc collect code "https://github.com/usuario/repositorio.git" --startDate 2024-01-01 --endDate 2024-12-31 --json
+```
+
+Para ajuda:
+
+```sh
+ftc --help
+```
+
+## Uso
+
+### Execução Local
+
+#### Análise de repositório local
+```bash
+dotnet run -- collect code /caminho/para/repositorio
+```
+
+#### Análise de repositório remoto
+```bash
+dotnet run -- collect code https://github.com/usuario/repositorio.git
+```
+
+#### Com filtros de data
+```bash
+dotnet run -- collect code /caminho/para/repositorio --startDate 2024-01-01 --endDate 2024-12-31
+```
+
+#### Exportação em JSON
+```bash
+dotnet run -- collect code /caminho/para/repositorio --json
+```
+
+#### Exportação em CSV detalhado
+```bash
+dotnet run -- collect code /caminho/para/repositorio --csv
+```
+
+#### Exportação para S3
+```bash
+dotnet run -- collect code /caminho/para/repositorio --csv --export s3
+```
+
+### Execução com Docker
+
+#### Construir e executar
+```bash
+# Linux/macOS
+./scripts/docker-run.sh collect code /caminho/para/repositorio
+
+# Windows
+scripts\docker-run.bat collect code C:\caminho\para\repositorio
+```
+
+#### Análise de repositório remoto
+```bash
+# Linux/macOS
+./scripts/docker-run.sh collect code https://github.com/usuario/repositorio.git
+
+# Windows
+scripts\docker-run.bat collect code https://github.com/usuario/repositorio.git
+```
+
+#### Com filtros e JSON
+```bash
+# Linux/macOS
+./scripts/docker-run.sh collect code /caminho/para/repositorio --startDate 2024-01-01 --json
+
+# Windows
+scripts\docker-run.bat collect code C:\caminho\para\repositorio --startDate 2024-01-01 --json
+```
+
+#### Opções do Docker Runner
+```bash
+# Mostrar ajuda
+./scripts/docker-run.sh --help
+
+# Reconstruir imagem
+./scripts/docker-run.sh --build collect code /caminho/para/repositorio
+
+# Limpar containers
+./scripts/docker-run.sh --clean
+```
+
+#### Execução direta com Docker
+```bash
+# Construir imagem
+docker-compose build
+
+# Executar CLI
+docker-compose run --rm ftc collect code /caminho/para/repositorio
+
+# Executar com volumes mapeados
+docker run --rm -v $(pwd)/repos:/repos:ro ftc:latest collect code /repos/meu-projeto
+```
+
+## Opções
+
+- `collect`: Comando para coleta de dados
+- `code`: Caminho local ou URL do repositório Git (obrigatório)
+- `--startDate`: Data inicial no formato yyyy-MM-dd (opcional)
+- `--endDate`: Data final no formato yyyy-MM-dd (opcional)
+- `--json`: Exportar resultado em formato JSON (opcional)
+- `--csv`: Exportar resultado em formato CSV detalhado (opcional)
+- `--export`: Destino de exportação: local:/caminho/arquivo.json ou s3 (opcional)
+
+## Repositórios Suportados
+
+### Locais
+- Caminhos absolutos: `C:\caminho\para\repositorio`
+- Caminhos relativos: `./repositorio`, `../repositorio`
+
+### Remotos
+- HTTPS: `https://github.com/usuario/repositorio.git`
+- HTTP: `http://github.com/usuario/repositorio.git`
+- SSH: `git@github.com/usuario/repositorio.git`
+- Git: `git://github.com/usuario/repositorio.git`
+
+## Exemplo de Saída
+
+### Formato padrão
+```
+Analisando repositório: https://github.com/usuario/repositorio.git
+Tipo: Remoto
+Clonando repositório: https://github.com/usuario/repositorio.git
+Pasta temporária: C:\Users\usuario\AppData\Local\Temp\ftc-cli-12345678-1234-1234-1234-123456789abc
+Repositório clonado com sucesso.
+
+📊 Total de commits: 150
+
+👥 Autores:
+  • João Silva <joao@exemplo.com>: 45 commits
+  • Maria Santos <maria@exemplo.com>: 38 commits
+  • Pedro Oliveira <pedro@exemplo.com>: 27 commits
+
+📁 Total de arquivos alterados: 89
+📄 Arquivos alterados:
+  • src/Program.cs: +120 -45
+  • src/Models.cs: +89 -12
+  • README.md: +15 -3
+  ... e mais 86 arquivos
+
+📅 Primeiro commit: 2024-01-15 10:30:00
+📅 Último commit: 2024-12-20 16:45:30
+```
+
+### Formato JSON
+```json
+{
+  "totalCommits": 150,
+  "authors": [
+    {
+      "name": "João Silva",
+      "email": "joao@exemplo.com",
+      "commits": 45
+    }
+  ],
+  "totalFilesChanged": 89,
+  "files": [
+    {
+      "filePath": "src/Program.cs",
+      "additions": 120,
+      "deletions": 45
+    }
+  ],
+  "firstCommitDate": "2024-01-15T10:30:00+00:00",
+  "lastCommitDate": "2024-12-20T16:45:30+00:00"
+}
+```
+
+### Formato CSV
+```csv
+nomeRepositorio;idRepositorio;dataCommit;idCommit;nomeAutor;emailAutor;nomeArquivo;caminhoArquivo;linhasAdicionadas;linhasRemovidas
+meu-repo;abc123;2024-01-15 10:30:00;def456;João Silva;joao@exemplo.com;Program.cs;src/Program.cs;120;45
+meu-repo;abc123;2024-01-15 10:30:00;def456;João Silva;joao@exemplo.com;Models.cs;src/Models.cs;89;12
+meu-repo;abc123;2024-01-16 14:20:00;ghi789;Maria Santos;maria@exemplo.com;README.md;README.md;15;3
+```
+
+O formato CSV inclui:
+- **nomeRepositorio**: Nome do repositório
+- **idRepositorio**: ID do repositório (SHA do HEAD)
+- **dataCommit**: Data e hora do commit
+- **idCommit**: SHA do commit
+- **nomeAutor**: Nome do autor do commit
+- **emailAutor**: Email do autor do commit
+- **nomeArquivo**: Nome do arquivo alterado
+- **caminhoArquivo**: Caminho completo do arquivo
+- **linhasAdicionadas**: Número de linhas adicionadas
+- **linhasRemovidas**: Número de linhas removidas
+
+## Tratamento de Erros
+
+A CLI fornece mensagens de erro claras e específicas:
+
+- **Repositório não encontrado**: Verifica se o caminho existe
+- **Repositório Git inválido**: Valida se é um repositório Git válido
+- **Sem commits**: Verifica se há commits para análise
+- **Período sem commits**: Avisa quando não há commits no período especificado
+- **Datas inválidas**: Valida formato e ordem das datas
+- **Erro de clonagem**: Trata falhas na clonagem de repositórios remotos
+
+## Arquitetura
+
+O projeto segue a arquitetura Vertical Slice do FTC:
+
+```
+Features/
+└── AnalyzeRepository/
+    ├── Models.cs              # Request/Response records
+    └── AnalyzeRepositorySlice.cs  # Lógica de análise
+
+Common/
+└── RepositoryUtils.cs         # Utilitários para repositórios
+
+scripts/
+├── docker-run.sh             # Script Linux/macOS
+└── docker-run.bat            # Script Windows
+```
+
+## Docker
+
+### Estrutura Docker
+```
+Dockerfile                    # Multi-stage build otimizado
+.dockerignore                 # Exclusões para build
+docker-compose.yml            # Configuração do container
+scripts/
+├── docker-run.sh            # Script Linux/macOS
+└── docker-run.bat           # Script Windows
+```
+
+### Características da Imagem
+- **Multi-stage build**: Otimiza tamanho da imagem
+- **Runtime .NET 8**: Imagem base leve
+- **Git instalado**: Suporte a repositórios remotos
+- **Volumes mapeados**: Acesso a repositórios locais
+- **Timezone configurado**: America/Sao_Paulo
+
+### Volumes Docker
+- `./repos:/repos:ro`: Mapeia repositórios locais (somente leitura)
+- `./temp:/tmp/ftc-cli`: Pasta temporária para persistência
+
+## Testes
+
+O projeto inclui testes automatizados para validação de funcionalidades:
+
+```bash
+# Executar todos os testes
+dotnet test ../../ftc.cli.tests
+
+# Executar testes específicos
+dotnet test ../../ftc.cli.tests --filter "IsRemoteRepository"
+```
+
+### Cobertura de Testes
+- ✅ Detecção de repositórios remotos vs locais
+- ✅ Validação de URLs HTTPS, HTTP, SSH, Git
+- ✅ Validação de caminhos locais e relativos
+
+## Dependências
+
+- **System.CommandLine**: Para parsing de argumentos da CLI
+- **LibGit2Sharp**: Para análise de repositórios Git
+- **System.Text.Json**: Para serialização JSON
+- **xUnit**: Para testes automatizados
+- **Docker**: Para containerização
+
+## Desenvolvimento
+
+### Compilar
+```bash
+dotnet build
+```
+
+### Executar Localmente
+```bash
+dotnet run -- [argumentos]
+```
+
+### Executar com Docker
+```bash
+# Linux/macOS
+./scripts/docker-run.sh [argumentos]
+
+# Windows
+scripts\docker-run.bat [argumentos]
+```
+
+### Testar
+```bash
+# Testar com um repositório local
+dotnet run -- C:\caminho\para\repositorio
+
+# Testar com repositório remoto
+dotnet run -- https://github.com/usuario/repositorio.git
+
+# Testar com filtros
+dotnet run -- C:\caminho\para\repositorio --since 2024-01-01 --json
+
+# Executar testes
+dotnet test ../../ftc.cli.tests
+
+# Testar com Docker
+./scripts/docker-run.sh C:\caminho\para\repositorio
+```
+
+## Melhorias Implementadas
+
+### ✅ Suporte a Repositórios Remotos
+- Detecção automática de URLs vs caminhos locais
+- Clonagem automática para pasta temporária
+- Limpeza automática após análise
+- Suporte a múltiplos protocolos (HTTPS, HTTP, SSH, Git)
+
+### ✅ Testes Automatizados
+- Testes unitários para detecção de repositórios
+- Cobertura de diferentes tipos de URLs
+- Validação de caminhos locais e relativos
+- Integração com xUnit
+
+### ✅ Tratamento Robusto de Erros
+- Mensagens de erro específicas e úteis
+- Validação de argumentos de entrada
+- Verificação de repositórios válidos
+- Tratamento de exceções com contexto
+- Interface melhorada com emojis e formatação
+
+### ✅ Suporte a Docker
+- Multi-stage build otimizado
+- Scripts para Linux/macOS e Windows
+- Volumes mapeados para repositórios locais
+- Configuração de timezone
+- Docker Compose para facilitar uso 
+
+## Exportação de resultados (local e S3)
+
+A CLI permite exportar o resultado da análise para um arquivo local ou diretamente para um bucket S3.
+
+### Exportar JSON localmente
+```sh
+ftc code "./meu-repo" --json --export local:./resultado.json
+```
+
+### Exportar CSV localmente
+```sh
+ftc code "./meu-repo" --csv --export local:./resultado.csv
+```
+
+### Exportar para S3 (JSON)
+```sh
+ftc code "./meu-repo" --json --export s3
+```
+
+### Exportar para S3 (CSV)
+```sh
+ftc code "./meu-repo" --csv --export s3
+```
+
+### Exportar para S3 (bucket e key customizados)
+```sh
+ftc code "./meu-repo" --csv --export s3: --s3-bucket "meu-bucket"
+```
+
+### Exportar para S3 (bucket/key no próprio parâmetro)
+```sh
+ftc code "./meu-repo" --csv --export s3://meu-bucket/analises/resultado.csv
+```
+
+- Se `--s3-bucket` não for informado, será usado o bucket padrão `ftc-analyzer`.
+- Para JSON: Se `--s3-key` não for informado, será usado o padrão `analises/<nome_repositorio>-ano-mes-dia.json`.
+- Para CSV: Se `--s3-key` não for informado, será usado o padrão `analises/<nome_repositorio>-ano-mes-dia.csv`.
+- O parâmetro `--s3-region` pode ser usado para especificar a região AWS. 

package/bin/ftc.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Detecta a plataforma e arquitetura
+const platform = process.platform;
+const arch = process.arch;
+
+// Mapeia a plataforma para o diretório correto
+const platformMap = {
+    'win32': 'win-x64',
+    'darwin': 'osx-x64', // macOS
+    'linux': 'linux-x64'
+};
+
+// Obtém o diretório da plataforma
+const platformDir = platformMap[platform];
+if (!platformDir) {
+    console.error('❌ Plataforma não suportada:', platform);
+    console.error('💡 Plataformas suportadas: Windows, macOS, Linux');
+    process.exit(1);
+}
+
+// Define o nome do executável baseado na plataforma
+const executableName = platform === 'win32' ? 'ftc.cli.exe' : 'ftc.cli';
+const executablePath = path.join(__dirname, platformDir, executableName);
+
+// Argumentos passados para o comando
+const args = process.argv.slice(2);
+
+// Se não há argumentos ou é --help, mostra o help customizado
+if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.log(`
+🚀 Follow The Code CLI - Ferramenta de Análise de Repositórios Git
+
+📋 USO:
+    ftc <comando> [opções]
+
+📝 COMANDOS:
+    collect code <repo>    Analisa um repositório Git e coleta dados
+
+📊 OPÇÕES DE EXPORTAÇÃO:
+    --csv                 Exporta resultados em formato CSV
+    --json                Exporta resultados em formato JSON
+    --export <destino>    Define o destino da exportação
+
+🎯 DESTINOS DE EXPORTAÇÃO:
+    local:<caminho>       Salva arquivo local (ex: local:./output.csv)
+    s3:<bucket>/<key>     Envia para AWS S3 (ex: s3:meu-bucket/resultado.csv)
+
+📖 EXEMPLOS:
+    ftc collect code https://github.com/user/repo --csv --export local:./resultado.csv
+    ftc collect code https://github.com/user/repo --json --export s3:meu-bucket/analise.json
+    ftc collect code https://github.com/user/repo --csv
+
+🔧 OPÇÕES GLOBAIS:
+    --help, -h            Mostra esta ajuda
+    --version, -v         Mostra a versão
+
+🌍 PLATAFORMAS SUPORTADAS:
+    Windows (x64), macOS (x64), Linux (x64)
+
+📚 MAIS INFORMAÇÕES:
+    Visite: https://github.com/your-org/follow-the-code
+    `);
+    process.exit(0);
+}
+
+// Verifica se o executável existe
+if (!fs.existsSync(executablePath)) {
+    console.error('❌ Erro: Executável .NET não encontrado para', platform, 'em:', executablePath);
+    console.error('💡 Certifique-se de que o projeto foi compilado para todas as plataformas.');
+    process.exit(1);
+}
+
+// Executa o binário .NET
+const executableDir = path.dirname(executablePath);
+const child = spawn(executablePath, args, {
+    stdio: 'inherit',
+    cwd: executableDir
+});
+
+// Aguarda o processo terminar
+child.on('close', (code) => {
+    process.exit(code);
+});
+
+// Trata erros
+child.on('error', (error) => {
+    console.error('❌ Erro ao executar o CLI:', error.message);
+    process.exit(1);
+}); 

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@followthecode/cli",
+  "version": "1.0.0",
+  "description": "CLI tool for Git repository analysis and data collection",
+  "main": "index.js",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "bin": {
+    "ftc": "./bin/ftc.js"
+  },
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "build": "npm run build:win && npm run build:mac && npm run build:linux",
+    "build:win": "dotnet publish ftc.cli.csproj -c Release -r win-x64 --self-contained true /p:PublishSingleFile=true -o ./bin/win-x64",
+    "build:mac": "dotnet publish ftc.cli.csproj -c Release -r osx-x64 --self-contained true /p:PublishSingleFile=true -o ./bin/osx-x64",
+    "build:linux": "dotnet publish ftc.cli.csproj -c Release -r linux-x64 --self-contained true /p:PublishSingleFile=true -o ./bin/linux-x64",
+    "test": "dotnet test",
+    "clean": "dotnet clean",
+    "publish:patch": "node scripts/publish.js --patch",
+    "publish:minor": "node scripts/publish.js --minor",
+    "publish:major": "node scripts/publish.js --major",
+    "publish:manual": "node scripts/publish.js"
+  },
+  "keywords": [
+    "git",
+    "analysis",
+    "repository",
+    "cli",
+    "follow-the-code",
+    "metrics",
+    "csv",
+    "json",
+    "s3"
+  ],
+  "author": "Follow The Code Team",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/follow-the-code.git"
+  },
+  "bugs": {
+    "url": "https://github.com/your-org/follow-the-code/issues"
+  },
+  "homepage": "https://github.com/your-org/follow-the-code#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "files": [
+    "bin/ftc.js",
+    "bin/win-x64/ftc.cli.exe",
+    "bin/osx-x64/ftc.cli",
+    "bin/linux-x64/ftc.cli",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@followthecode/cli": "^1.0.1",
+    "node-fetch": "^3.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.0.0"
+  }
+}