npm package: @perma-tools/cli
Description: 🚀 CLI moderna e interativa para geração rápida de projetos frontend e backend com configurações personalizadas
Latest version: 0.0.2

# @perma-tools/cli

🚀 CLI moderna e interativa para geração rápida de projetos frontend e backend com configurações personalizadas.

## 📦 Instalação

### Uso com npx (Recomendado - sem instalação)

```bash
npx @perma-tools/cli@latest
```

### Instalação Global

```bash
npm install -g @perma-tools/cli
# ou
pnpm add -g @perma-tools/cli
# ou
yarn global add @perma-tools/cli
```

## 🚀 Uso Rápido

### Modo Interativo

```bash
npx @perma-tools/cli@latest
```

A CLI irá guiá-lo através de perguntas interativas para configurar seu projeto.

### Modo CLI com Flags

```bash
npx @perma-tools/cli@latest \
  --name meu-app \
  --type frontend \
  --framework nextjs-15 \
  --http-client ky \
  --linter biome \
  --libs tanstack-query,zod,react-hook-form \
  --with-shadcn \
  --shadcn-color slate \
  --install
```

## ✨ Características

- ✅ Suporte completo para **Frontend** (NextJS 15) e **Backend** (em desenvolvimento)
- ✅ Escolha entre **ky**, **axios** ou **fetch** nativo como cliente HTTP
- ✅ Configuração automática de **Biome** ou **ESLint + Prettier**
- ✅ Instalação e configuração de bibliotecas populares com **versões específicas testadas**
- ✅ Integração completa com **shadcn/ui**
- ✅ Sistema de **providers** com injeção automática robusta
- ✅ **Criação automática de repositório no GitHub** com GitHub CLI
- ✅ **Deploy automático na Vercel** para projetos frontend
- ✅ Instalação automática de dependências
- ✅ Validação completa de nomes de projetos (seguindo regras do npm)
- ✅ Verificação de projetos existentes para evitar sobrescritas
- ✅ Compatibilidade total com Windows, Linux e macOS

## 🚀 Git & Deploy Automático

A CLI oferece configuração automática de repositório e deploy, adaptando-se automaticamente às ferramentas disponíveis no seu sistema:

### Pré-requisitos

- **GitHub CLI** (`gh`): [Instalar e autenticar](https://cli.github.com/)
  - **Obrigatório** para criação de repositórios
  - Se não estiver instalado, a opção de Git setup será ocultada
- **Vercel CLI** (opcional): `npm i -g vercel && vercel login`
  - **Necessário** apenas para deploy automático
  - Se não estiver instalado, apenas a opção "criar repo" será mostrada

### Detecção Automática de Ferramentas

A CLI detecta automaticamente quais ferramentas estão instaladas e **ajusta as opções disponíveis**:

| GitHub CLI | Vercel CLI | Opções Mostradas |
|------------|------------|------------------|
| ✅ Instalado | ✅ Instalado | Repo + Deploy, Repo only, Nenhum |
| ✅ Instalado | ❌ Não instalado | Repo only, Nenhum |
| ❌ Não instalado | ✅/❌ Qualquer | Nenhum (pula essa etapa) |

**Comportamento inteligente:**
- Se você **não tem GitHub CLI**, a CLI pula completamente a configuração de Git
- Se você **só tem GitHub CLI**, mostra apenas a opção de criar repositório
- Se você **tem ambas** e é um projeto **frontend**, mostra todas as opções

### Opções Disponíveis

1. **Criar repo e deploy na Vercel**: Cria repositório no GitHub e configura deploy automático (frontend apenas, requer ambas CLIs)
2. **Apenas criar repo**: Cria repositório no GitHub sem deploy (requer apenas GitHub CLI)
3. **Não configurar agora**: Pula a configuração (pode fazer manualmente depois)

### Criação em Organizações

A CLI detecta automaticamente suas organizações do GitHub e permite escolher onde criar o repositório:

- **Perfil Pessoal**: `github.com/seu-usuario/repo`
- **Organização**: `github.com/sua-org/repo`

Se você tiver acesso a múltiplas organizações, poderá selecioná-las interativamente.

### Como Funciona

Após criar o projeto, a CLI:
- 🔧 Inicializa o repositório Git local
- 📍 Pergunta onde criar (perfil pessoal ou organização)
- 🏢 Lista suas organizações do GitHub (se aplicável)
- 📦 Cria repositório no GitHub (público ou privado)
- 🚀 Faz push do código inicial
- ⏳ Aguarda o GitHub processar o repositório (3 segundos)
- ⚡ Configura deploy na Vercel (se selecionado)

```bash
# A CLI faz tudo isso automaticamente:
git init
git add .
git commit -m "chore: initial commit from @perma-tools/cli"
gh repo create my-org/my-repo --public --source . --push  # Com org
# ou
gh repo create my-repo --public --source . --push  # Perfil pessoal
vercel --prod --yes  # Se deploy estiver habilitado
```

## 🏗️ Estrutura do Projeto Gerado

### Providers e Client Components

Quando você seleciona bibliotecas que usam Context API (TanStack Query, nuqs, etc.), a CLI:

1. Cria um arquivo `src/app/providers.tsx` com a diretiva `'use client'`
2. Injeta automaticamente os providers necessários
3. Mantém a estrutura aninhada corretamente

```tsx
'use client';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <>
      <QueryClientProvider>
        <NuqsAdapter>
          {children}
        </NuqsAdapter>
      </QueryClientProvider>
    </>
  );
}
```

**Por que 'use client'?**  
Providers que usam hooks do React (useState, useContext, etc.) precisam ser Client Components no Next.js 15.

## 📄 Licença

MIT