# Kasy CLI — Referência de Comandos

## Visão Geral

O Kasy CLI é uma ferramenta para criar e gerenciar projetos Flutter com arquitetura padronizada, múltiplos backends e features opcionais.

---

## Comandos

### `kasy new [directory]`

Cria um novo projeto Kasy.

```bash
kasy new                        # interativo — pergunta tudo
kasy new meu-app               # cria na pasta meu-app
kasy new --yes                 # modo rápido, preset Starter
kasy new --backend supabase    # define backend sem perguntar
kasy new --with llm_chat,sentry  # pré-seleciona features
```

**Opções:**
| Flag | Descrição |
|------|-----------|
| `[directory]` | Pasta de destino (padrão: pergunta durante setup) |
| `-b, --backend <id>` | Backend: `firebase`, `supabase` ou `api` |
| `--with <modules>` | Features separados por vírgula |
| `--yes` | Modo não-interativo com preset Starter |
| `-p, --project <id>` | Firebase Project ID (usado com `--yes`) |

---

### `kasy add <feature>`

Adiciona uma feature a um projeto Kasy existente.

```bash
kasy add llm_chat
kasy add sentry
kasy add revenuecat
kasy add --list               # lista features disponíveis e status
kasy add --yes llm_chat       # sem perguntas interativas
kasy add -d ./outro-app llm_chat
```

**Features disponíveis:**
| feature | Descrição |
|--------|-----------|
| `sentry` | Monitoramento de erros em produção |
| `analytics` | Analytics com Mixpanel |
| `facebook` | Login social e Facebook Pixel |
| `revenuecat` | Assinaturas e monetização |
| `onboarding` | Fluxo de onboarding customizável |
| `web` | Suporte a Flutter Web |
| `widget` | Home widgets para iOS e Android |
| `llm_chat` | Chat com IA via Cloud/Edge Functions |
| `feedback` | Sistema de feedback e feature requests |
| `ci` | CI/CD com GitHub Actions / Codemagic |

---

### `kasy doctor`

Verifica o ambiente de desenvolvimento.

```bash
kasy doctor
```

Verifica: Node.js, Flutter SDK (≥3.24.0), Dart SDK (≥3.5.0), CocoaPods (macOS), Firebase CLI, FlutterFire CLI, gcloud CLI.

Quando executado dentro de um projeto Kasy, também exibe: nome do app, backend, bundle ID, features ativos.

---

### `kasy run [directory]`

Executa o app Flutter com as configurações do projeto.

```bash
kasy run                  # detecta dispositivo automaticamente
kasy run --ios            # iOS simulator/device
kasy run --android        # Android emulator/device
kasy run --web            # Chrome
kasy run -d <device-id>   # dispositivo específico
kasy run --prod           # usa configurações de produção
kasy run --no-defines     # sem dart-defines do launch.json
```

Prioriza valores de `.env` (gerado a partir de `.env.example`) e mantém compatibilidade com `--dart-define` do `.vscode/launch.json`.

---

### `kasy deploy [directory]`

Faz deploy do projeto (Firebase: Functions + Firestore rules).

```bash
kasy deploy
kasy deploy -p meu-projeto-firebase
kasy deploy ./outro-app
```

---

### `kasy ios` — Release iOS (Mac)

Publicação na App Store a partir do Mac (sem Transporter).

```bash
kasy ios configure    # uma vez — credenciais Apple API
kasy ios release      # incrementa build, gera IPA e envia
kasy ios build        # só gera IPA
kasy ios clean        # limpa cache Flutter/Xcode (após erro DerivedData/disco)
```

Documentação no projeto: `docs/ios-release.md` (idioma da CLI)

Atalho: `make release-ios`

---

### `kasy codemagic` — Release iOS (nuvem)

Dispara build iOS no Codemagic (ideal sem Mac).

```bash
kasy add ci                  # cria codemagic.yaml (se necessário)
kasy codemagic configure     # token API + app/workflow ID
kasy codemagic release       # inicia build na nuvem
kasy codemagic status <id>   # status do build
```

Documentação: `docs/codemagic-release.md` (idioma da CLI)

---

### `kasy update ios-release`

Atualiza scripts e docs de release iOS em projetos criados antes desta feature.

```bash
kasy update ios-release
```

---

### `kasy features`

Lista todas as features disponíveis e uma breve descrição.

```bash
kasy features
```

---

### `kasy validate`

Valida a estrutura e configuração do projeto atual.

```bash
kasy validate
kasy validate --analyze-only   # apenas análise, sem sugestões
```

---

### `kasy docs`

Abre a documentação no navegador.

```bash
kasy docs
```

---

## Backends

| Backend | Descrição |
|---------|-----------|
| `firebase` | Firebase (Auth, Firestore, Storage, FCM, Remote Config) |
| `supabase` | Supabase (Auth, PostgreSQL, Storage, Edge Functions) |
| `api` | REST API própria (Auth customizada, endpoints próprios) |

---

## Arquitetura do Projeto Gerado

```
lib/
  core/
    config/         # features.dart — flags das features ativos
    data/           # APIs, modelos, repositórios
    guards/         # guards de navegação
    theme/          # design system (cores, tipografia, espaçamento)
  features/
    authentication/ # login, cadastro, recuperação de senha
    home/           # tela principal
    notifications/  # notificações locais e push
    settings/       # configurações do app
    llm_chat/       # [feature] chat com IA
    feedbacks/      # [feature] feedback e feature requests
    onboarding/     # [feature] onboarding
    subscription/   # [feature] assinaturas (RevenueCat)
  router.dart       # gerado automaticamente baseado nas features
  main.dart         # ponto de entrada
kit_setup.json      # configuração do projeto (backend, features, IDs)
```

---

## kit_setup.json

Arquivo gerado na raiz do projeto com os metadados da configuração:

```json
{
  "appName": "Meu App",
  "bundleId": "com.empresa.meuapp",
  "backendProvider": "firebase",
  "templateVersion": "1.0.0",
  "subscriptionModule": true,
  "feedbackModule": true,
  "useSentry": true,
  "withOnboarding": true,
  "analyticsProvider": "mixpanel",
  "withFacebookPixel": false
}
```

---

## Variáveis de Ambiente

No desenvolvimento local, ficam em `.env` (copiado de `.env.example`). `--dart-define` no `.vscode/launch.json` segue suportado para CI/release e compatibilidade:

| Variável | feature | Descrição |
|----------|--------|-----------|
| `ENV` | sempre | `dev` ou `prod` |
| `SENTRY_DSN` | sentry | DSN do Sentry (só em prod) |
| `MIXPANEL_TOKEN` | analytics | Token do Mixpanel |
| `RC_ANDROID_API_KEY` | revenuecat | Chave Android do RevenueCat |
| `RC_IOS_API_KEY` | revenuecat | Chave iOS do RevenueCat |
| `LLM_CHAT_ENDPOINT` | llm_chat | URL da Cloud/Edge Function |
| `BACKEND_URL` | supabase/api | URL do backend |
| `SUPABASE_TOKEN` | supabase | Anon key do Supabase |
