📮 ACHE CEP CLI

🇧🇷 Português

CLI simples e poderoso para consulta de CEP (Código de Endereçamento Postal) brasileiro usando a API ViaCEP.

✨ Funcionalidades

• 🚀 Consulta rápida de CEP diretamente do terminal
• 📍 Retorna informações completas: logradouro, bairro, cidade e estado
• 🎨 Interface colorida e amigável usando Chalk
• ⚡ Leve e rápido
• 🧪 100% de cobertura de testes
• 📦 Zero configuração necessária

📦 Instalação

Uso com NPX (Recomendado)

Sem necessidade de instalação! Execute diretamente:

npx ache-cep-cli <cep>

Instalação Global

npm install -g ache-cep-cli

Instalação como Dependência

npm install ache-cep-cli --save-dev

🚀 Como Usar

Exemplo Básico

npx ache-cep-cli 01310-100

Saída Esperada

📍 CEP: 01310-100
Endereço: Avenida Paulista
Bairro: Bela Vista
Cidade: São Paulo
Estado: SP

Formatos Aceitos

O CLI aceita CEP com ou sem formatação:

# Com hífen
npx ache-cep-cli 01310-100

# Sem formatação
npx ache-cep-cli 01310100

🛠️ Desenvolvimento

Pré-requisitos

• Node.js 18+
• npm ou yarn

Clonar o Repositório

git clone https://github.com/mayconbalves/ache-cep-cli.git
cd ache-cep-cli
npm install

Scripts Disponíveis

# Executar em modo de desenvolvimento
npm run dev -- <cep>

# Rodar testes
npm test

# Rodar testes em modo watch
npm run test:watch

# Verificar cobertura de testes
npm run test:coverage

# Rodar linter
npm run lint

# Corrigir problemas de lint automaticamente
npm run lint:fix

# Formatar código
npm run format

# Verificar formatação
npm run format:check

# Build do projeto
npm run build

🧪 Testes

Este projeto possui 100% de cobertura de testes usando Jest.

# Rodar todos os testes
npm test

# Rodar testes com cobertura
npm run test:coverage

# Modo watch para desenvolvimento
npm run test:watch

🏗️ Estrutura do Projeto

ache-cep-cli/
├── .github/
│   └── workflows/          # GitHub Actions CI/CD
│       ├── ci.yml          # Pipeline de integração contínua
│       ├── publish.yml     # Pipeline de publicação no NPM
│       └── codeql.yml      # Análise de segurança
├── .husky/                 # Git hooks
│   ├── pre-commit          # Hook de pre-commit (lint-staged)
│   └── pre-push            # Hook de pre-push (testes)
├── src/
│   ├── __tests__/
│   │   └── cep.test.js     # Testes unitários
│   ├── cep.js              # Lógica de consulta de CEP
│   └── index.js            # Entry point do CLI
├── dist/                   # Build output
├── eslint.config.js        # Configuração do ESLint
├── jest.config.js          # Configuração do Jest
├── .prettierrc             # Configuração do Prettier
└── package.json            # Dependências e scripts

🔄 CI/CD

Este projeto usa GitHub Actions para CI/CD:

Pipeline de CI

• ✅ Lint (ESLint + Prettier)
• ✅ Testes em múltiplas versões do Node.js (18, 20, 22)
• ✅ Cobertura de código (Codecov)
• ✅ Build do projeto
• ✅ Análise de segurança (CodeQL)

Pipeline de Publicação

• 📦 Publicação automática no NPM
• 🏷️ Criação de releases no GitHub
• 🔒 Assinatura de pacotes com provenance

🤝 Como Contribuir

Contribuições são muito bem-vindas! Siga os passos abaixo:

1. Fork o projeto

2. Clone seu fork

   git clone https://github.com/seu-usuario/ache-cep-cli.git
   cd ache-cep-cli

3. Crie uma branch para sua feature

   git checkout -b feature/minha-feature

4. Instale as dependências

   npm install

5. Faça suas alterações e adicione testes

   • Mantenha a cobertura de testes em 100%
   • Siga os padrões de código (ESLint + Prettier)

6. Execute os testes

   npm test
   npm run lint

7. Commit suas alterações

   git add .
   git commit -m "feat: adiciona nova funcionalidade"

   Seguimos o padrão de Conventional Commits:

   • feat: Nova funcionalidade
   • fix: Correção de bug
   • docs: Documentação
   • style: Formatação
   • refactor: Refatoração
   • test: Testes
   • chore: Manutenção

8. Push para seu fork

   git push origin feature/minha-feature

9. Abra um Pull Request

   • Descreva suas alterações
   • Referencie issues relacionadas
   • Aguarde review

📋 Checklist para PRs

• [ ] Código segue os padrões do projeto (ESLint + Prettier)
• [ ] Testes foram adicionados/atualizados
• [ ] Todos os testes estão passando
• [ ] Cobertura de testes mantida em 100%
• [ ] Documentação foi atualizada (se necessário)
• [ ] Commit messages seguem o padrão Conventional Commits

🐛 Reportar Bugs

Encontrou um bug? Abra uma issue com:

• Descrição do problema
• Passos para reproduzir
• Comportamento esperado
• Comportamento atual
• Versão do Node.js e do sistema operacional

💡 Sugerir Funcionalidades

Tem uma ideia? Abra uma issue com:

• Descrição da funcionalidade
• Por que ela é útil
• Exemplos de uso

📝 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

• ViaCEP - API gratuita de consulta de CEP
• Chalk - Terminal string styling
• Axios - HTTP client

📞 Contato

• Issues: GitHub Issues
• Email: crie uma issue

🇺🇸 English

Simple and powerful CLI for querying Brazilian postal codes (CEP - Código de Endereçamento Postal) using the ViaCEP API.

✨ Features

• 🚀 Fast CEP lookup directly from the terminal
• 📍 Returns complete information: street, neighborhood, city, and state
• 🎨 Colorful and friendly interface using Chalk
• ⚡ Lightweight and fast
• 🧪 100% test coverage
• 📦 Zero configuration required

📦 Installation

Use with NPX (Recommended)

No installation needed! Run directly:

npx ache-cep-cli <cep>

Global Installation

npm install -g ache-cep-cli

Install as Dependency

npm install ache-cep-cli --save-dev

🚀 Usage

Basic Example

npx ache-cep-cli 01310-100

Expected Output

📍 CEP: 01310-100
Endereço: Avenida Paulista
Bairro: Bela Vista
Cidade: São Paulo
Estado: SP

Accepted Formats

The CLI accepts CEP with or without formatting:

# With hyphen
npx ache-cep-cli 01310-100

# Without formatting
npx ache-cep-cli 01310100

🛠️ Development

Prerequisites

• Node.js 18+
• npm or yarn

Clone the Repository

git clone https://github.com/mayconbalves/ache-cep-cli.git
cd ache-cep-cli
npm install

Available Scripts

# Run in development mode
npm run dev -- <cep>

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Check test coverage
npm run test:coverage

# Run linter
npm run lint

# Fix lint issues automatically
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

# Build the project
npm run build

🧪 Tests

This project has 100% test coverage using Jest.

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

🏗️ Project Structure

ache-cep-cli/
├── .github/
│   └── workflows/          # GitHub Actions CI/CD
│       ├── ci.yml          # Continuous integration pipeline
│       ├── publish.yml     # NPM publish pipeline
│       └── codeql.yml      # Security analysis
├── .husky/                 # Git hooks
│   ├── pre-commit          # Pre-commit hook (lint-staged)
│   └── pre-push            # Pre-push hook (tests)
├── src/
│   ├── __tests__/
│   │   └── cep.test.js     # Unit tests
│   ├── cep.js              # CEP query logic
│   └── index.js            # CLI entry point
├── dist/                   # Build output
├── eslint.config.js        # ESLint configuration
├── jest.config.js          # Jest configuration
├── .prettierrc             # Prettier configuration
└── package.json            # Dependencies and scripts

🔄 CI/CD

This project uses GitHub Actions for CI/CD:

CI Pipeline

• ✅ Lint (ESLint + Prettier)
• ✅ Tests on multiple Node.js versions (18, 20, 22)
• ✅ Code coverage (Codecov)
• ✅ Project build
• ✅ Security analysis (CodeQL)

Publishing Pipeline

• 📦 Automatic NPM publishing
• 🏷️ GitHub releases creation
• 🔒 Package signing with provenance

🤝 How to Contribute

Contributions are very welcome! Follow these steps:

1. Fork the project

2. Clone your fork

   git clone https://github.com/your-username/ache-cep-cli.git
   cd ache-cep-cli

3. Create a branch for your feature

   git checkout -b feature/my-feature

4. Install dependencies

   npm install

5. Make your changes and add tests

   • Maintain 100% test coverage
   • Follow code standards (ESLint + Prettier)

6. Run tests

   npm test
   npm run lint

7. Commit your changes

   git add .
   git commit -m "feat: add new feature"

   We follow the Conventional Commits standard:

   • feat: New feature
   • fix: Bug fix
   • docs: Documentation
   • style: Formatting
   • refactor: Refactoring
   • test: Tests
   • chore: Maintenance

8. Push to your fork

   git push origin feature/my-feature

9. Open a Pull Request

   • Describe your changes
   • Reference related issues
   • Wait for review

📋 PR Checklist

• [ ] Code follows project standards (ESLint + Prettier)
• [ ] Tests were added/updated
• [ ] All tests are passing
• [ ] Test coverage maintained at 100%
• [ ] Documentation was updated (if necessary)
• [ ] Commit messages follow Conventional Commits standard

🐛 Report Bugs

Found a bug? Open an issue with:

• Problem description
• Steps to reproduce
• Expected behavior
• Current behavior
• Node.js version and operating system

💡 Suggest Features

Have an idea? Open an issue with:

• Feature description
• Why it's useful
• Usage examples

📝 License

This project is under the MIT license. See the LICENSE file for more details.

🙏 Acknowledgments

• ViaCEP - Free CEP lookup API
• Chalk - Terminal string styling
• Axios - HTTP client

📞 Contact

• Issues: GitHub Issues
• Email: create an issue

Made with ❤️ by Maycon Alves