kaven-cli 0.1.0-alpha.1 → 0.3.5

package/README.md

@@ -1,93 +1,332 @@
-# Kaven CLI 🚀
+# Kaven CLI
 
+> 📖 Versão em Português: [README.pt-BR.md](./README.pt-BR.md)
+
+[![npm version](https://img.shields.io/npm/v/kaven-cli/alpha.svg)](https://www.npmjs.com/package/kaven-cli)
+[![npm downloads](https://img.shields.io/npm/dm/kaven-cli.svg)](https://www.npmjs.com/package/kaven-cli)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Version](https://img.shields.io/badge/version-0.1.0--alpha.1-orange.svg)](https://semver.org)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+[![CI](https://github.com/kaven-co/kaven-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/kaven-co/kaven-cli/actions/workflows/ci.yml)
 
-A ferramenta de linha de comando oficial para o ecossistema **Kaven**. Projetada para ser robusta, idempotente e extensível.
+The official command-line tool for the [Kaven](https://kaven.site) SaaS boilerplate framework.
+Bootstrap projects, manage modules, and interact with the Kaven Marketplace — all from your terminal.
 
-> **Note**: Este projeto está em fase **Alpha**. APIs e comandos estão sujeitos a alterações.
+> **Alpha:** APIs and commands may change before v1.0.0.
 
 ---
 
-## 📦 Instalação
-
-A CLI pode ser instalada globalmente via npm ou pnpm:
+## Installation
 
 ```bash
 npm install -g kaven-cli@alpha
-# ou
+# or
 pnpm add -g kaven-cli@alpha
 ```
 
-## 🚀 Início Rápido
+**Requirements:** Node.js >= 20, pnpm (required by `kaven init`)
+
+---
 
-Consiga o seu projeto rodando em segundos:
+## Quick Start
 
 ```bash
-# 1. Autenticação
+# 1. Bootstrap a new Kaven project
+kaven init my-saas-app
+
+# 2. Authenticate with the marketplace
 kaven auth login
 
-# 2. Explorar Módulos
-kaven marketplace list
+# 3. Browse available modules
+kaven marketplace browse
 
-# 3. Instalar um Módulo
+# 4. Install a module
 kaven marketplace install payments
 
-# 4. Verificar Saúde do Projeto
+# 5. Check project health
 kaven module doctor
+```
+
+---
+
+## Command Reference
+
+### `kaven init [project-name]`
+
+Bootstrap a new Kaven project from the official template.
+
+```
+Options:
+  --defaults       Skip interactive prompts, use defaults
+  --skip-install   Skip pnpm install after setup
+  --skip-git       Skip git init and initial commit
+  --force          Overwrite existing directory
+  --with-squad     Initialize AIOX squad in the project
+
+Examples:
+  kaven init my-app
+  kaven init my-app --defaults
+  kaven init my-app --skip-git --skip-install
+```
+
+---
+
+### `kaven auth`
+
+Manage authentication with the Kaven Marketplace.
+
+```
+Commands:
+  login    Start device code flow (RFC 8628) — opens browser to confirm
+  logout   Clear the local session
+  whoami   Display the authenticated user info
+```
+
+---
+
+### `kaven marketplace`
+
+Explore and install modules from the Kaven Marketplace.
+
+```
+Commands:
+  list      List available modules
+  install   Download and apply a module to the current project
+  browse    Interactive TUI browser
+
+Options (list):
+  --category <cat>   Filter by category
+  --sort <field>     newest (default) | popular | name
+  --page <n>         Page number
+  --limit <n>        Results per page (max 100)
+  --json             Raw JSON output
+
+Options (install):
+  --version <ver>    Install a specific version
+  --force            Skip overwrite confirmation
+  --skip-env         Skip .env injection
+  --env-file <path>  Target .env file path
+```
+
+---
+
+### `kaven module`
+
+Manage modules installed in the current project.
+
+```
+Commands:
+  doctor    Run health checks on the project and installed modules
+  add       Install a module from a local manifest
+  remove    Uninstall an installed module
+  publish   Publish a module to the marketplace
+
+Options (doctor):
+  --fix    Auto-fix detected issues (runs pnpm install, prisma generate, patches env)
+  --json   Machine-readable JSON output
+
+Exit codes (doctor):
+  0   All checks passed
+  1   One or more errors
+  2   Warnings only
+
+Options (publish):
+  --dry-run          Validate and package without uploading
+  --changelog <msg>  Release notes for this version
+```
+
+> `kaven doctor` is an alias for `kaven module doctor`.
+
+---
+
+### `kaven upgrade`
+
+Upgrade your license tier via Paddle checkout.
+
+```
+Options:
+  --no-browser   Print checkout URL instead of opening browser
+
+Behavior:
+  Opens Paddle checkout in browser → polls for payment (every 5s, max 10 min)
+  → updates local license on success
+```
+
+---
+
+### `kaven license`
+
+```
+Commands:
+  status   Show current license tier and expiry
+```
+
+---
+
+### `kaven cache`
+
+Manage the local API response cache (`~/.kaven/cache`, max 50 MB).
 
-# 5. Ver Telemetria Local
-kaven telemetry view
 ```
+Commands:
+  status   Show cache stats (size, entries, age)
+  clear    Delete all cached data
+
+Cache TTLs:
+  Module listings    24 hours
+  Module manifests   7 days
+  License status     1 hour
+```
+
+---
+
+### `kaven telemetry`
+
+```
+Commands:
+  view   Show recent local telemetry events
+         -l, --limit <n>   Number of events (default: 10)
+```
+
+---
+
+### `kaven config`
+
+```
+Commands:
+  set <key> <value>   Set a configuration value
+  get <key>           Get a configuration value
+```
+
+---
+
+### `kaven init-ci`
+
+Initialize CI/CD configuration in the current project. Generates GitHub Actions workflows tailored for Kaven projects.
+
+---
+
+## Configuration
+
+All configuration lives in `~/.kaven/`:
+
+```
+~/.kaven/
+  auth.json         Authentication tokens         (chmod 600)
+  config.json       CLI configuration
+  license.json      License key and tier
+  signing-key.json  Module Ed25519 signing key    (chmod 600)
+  cache/            API response cache            (max 50 MB)
+  telemetry.log     Local telemetry events
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `KAVEN_API_URL` | Override the marketplace API URL |
+| `KAVEN_DEBUG=1` | Enable verbose debug output |
+| `KAVEN_OFFLINE=1` | Use cached data only, no network requests |
+| `KAVEN_TELEMETRY=0` | Disable telemetry entirely |
+
+### API URL Override (config file)
 
-## 🛠️ Comandos Principais
+```json
+// ~/.kaven/config.json
+{
+  "apiUrl": "https://api.your-kaven-instance.com"
+}
+```
 
-A Kaven CLI organiza suas funcionalidades em grupos lógicos para uma melhor experiência:
+### Debug Mode
 
-### 📦 Módulos (`module`, `m`)
+```bash
+KAVEN_DEBUG=1 kaven marketplace list
+```
 
-Gerenciamento local de módulos e integridade do projeto.
+### Offline Mode
 
-- `kaven module add <path>`: Adiciona um módulo localmente via arquivo de manifest.
-- `kaven module remove <name>`: Remove um módulo e limpa as injeções de código.
-- `kaven module doctor`: Verifica a integridade dos markers, âncoras e dependências.
+```bash
+KAVEN_OFFLINE=1 kaven marketplace list
+```
 
-### 🔑 Autenticação (`auth`)
+---
 
-Gerenciamento de sessão e tokens.
+## Troubleshooting
 
-- `kaven auth login`: Inicia o fluxo de autenticação (Device Flow).
-- `kaven auth logout`: Remove as credenciais locais.
-- `kaven auth whoami`: Exibe informações do usuário atual.
+**"Not authenticated" error**
+```bash
+kaven auth login
+```
 
-### 🏬 Marketplace (`marketplace`, `mkt`)
+**"module.json not found" on publish**
 
-Descoberta e instalação de módulos oficiais.
+Run `kaven module publish` from inside the module directory (the one containing `module.json`).
 
-- `kaven marketplace list`: Lista todos os módulos disponíveis na nuvem Kaven.
-- `kaven marketplace install <id>`: Baixa e instala um módulo automaticamente.
+**pnpm install fails on `kaven init`**
+```bash
+npm install -g pnpm          # install pnpm globally
+# or skip it and install later:
+kaven init my-app --skip-install
+cd my-app && pnpm install
+```
 
-### 📊 Telemetria (`telemetry`)
+**Prisma client out of sync**
+```bash
+kaven module doctor --fix
+# or manually:
+npx prisma generate
+```
 
-Observabilidade e auditoria local.
+**Cache issues**
+```bash
+kaven cache clear
+```
 
-- `kaven telemetry view`: Exibe os últimos eventos registrados localmente.
+**Permission denied on `~/.kaven/`**
+```bash
+chmod 700 ~/.kaven
+chmod 600 ~/.kaven/auth.json ~/.kaven/signing-key.json
+```
 
 ---
 
-## 🧪 Desenvolvimento
+## Contributing
 
-Nós valorizamos contribuições! Antes de começar, por favor leia nosso guia de contribuição:
+```bash
+git clone https://github.com/kaven-co/kaven-cli
+cd kaven-cli
+pnpm install
+pnpm test           # 310 tests
+pnpm run typecheck
+pnpm run lint
+```
+
+**Commit convention:** this repo uses [Conventional Commits](https://www.conventionalcommits.org/).
 
-- [CONTRIBUTING.md](./CONTRIBUTING.md) - Guia de setup e padrões.
-- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) - Nosso compromisso com a comunidade.
+```bash
+feat: add --with-squad flag to kaven init
+fix: resolve cache corruption on concurrent writes
+docs: update troubleshooting section
+```
+
+**Release flow:**
+1. Open a PR against `main`
+2. PR requires CI green (lint + typecheck + tests + build)
+3. Merge → Semantic Release automatically bumps version and publishes to npm (`@alpha` tag)
+
+Types that trigger a release: `feat` (minor), `fix` / `perf` / `refactor` (patch), `BREAKING CHANGE` (major).
+Types that do **not** trigger a release: `chore`, `docs`, `test`, `style`, `ci`.
+
+See [`docs/releasing.md`](./docs/releasing.md) for the full release pipeline documentation.
+
+---
 
-## 📄 Licença
+## License
 
-Este projeto é licenciado sob a **Apache-2.0 License** - veja o arquivo [LICENSE](LICENSE) para detalhes.
+Apache 2.0 — see [LICENSE](LICENSE)
 
 ---
 
-<p align="center">
-  Feito com ❤️ pela equipe Kaven
-</p>
+Documentation: https://docs.kaven.site/cli
+GitHub: https://github.com/kaven-co/kaven-cli
+npm: https://www.npmjs.com/package/kaven-cli

package/README.pt-BR.md

@@ -0,0 +1,334 @@
+# Kaven CLI
+
+> 📖 English version: [README.md](./README.md)
+
+[![npm version](https://img.shields.io/npm/v/kaven-cli/alpha.svg)](https://www.npmjs.com/package/kaven-cli)
+[![npm downloads](https://img.shields.io/npm/dm/kaven-cli.svg)](https://www.npmjs.com/package/kaven-cli)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+[![CI](https://github.com/kaven-co/kaven-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/kaven-co/kaven-cli/actions/workflows/ci.yml)
+
+A CLI oficial do [Kaven](https://kaven.site) — boilerplate enterprise-grade para SaaS.
+Bootstrap de projetos, gerenciamento de módulos e integração com o Kaven Marketplace diretamente pelo terminal.
+
+O Kaven é um projeto brasileiro. O boilerplate comprime de 3-6 meses para dias o trabalho de infraestrutura base de um SaaS (auth, multi-tenancy, pagamentos, design system).
+
+> **Alpha:** APIs e comandos podem mudar antes da v1.0.0.
+
+---
+
+## Instalação
+
+```bash
+npm install -g kaven-cli@alpha
+# ou
+pnpm add -g kaven-cli@alpha
+```
+
+**Requisitos:** Node.js >= 20, pnpm (necessário para o `kaven init`)
+
+---
+
+## Início Rápido
+
+```bash
+# 1. Bootstrap de um novo projeto
+kaven init meu-saas
+
+# 2. Autenticar com o marketplace
+kaven auth login
+
+# 3. Explorar módulos disponíveis
+kaven marketplace browse
+
+# 4. Instalar um módulo
+kaven marketplace install payments
+
+# 5. Verificar saúde do projeto
+kaven module doctor
+```
+
+---
+
+## Referência de Comandos
+
+### `kaven init [nome-do-projeto]`
+
+Cria um novo projeto Kaven a partir do template oficial.
+
+```
+Opções:
+  --defaults       Pular prompts interativos, usar valores padrão
+  --skip-install   Pular o pnpm install após o setup
+  --skip-git       Pular git init e commit inicial
+  --force          Sobrescrever diretório existente
+  --with-squad     Inicializar squad AIOX no projeto
+
+Exemplos:
+  kaven init meu-app
+  kaven init meu-app --defaults
+  kaven init meu-app --skip-git --skip-install
+```
+
+---
+
+### `kaven auth`
+
+Gerenciar autenticação com o Kaven Marketplace.
+
+```
+Subcomandos:
+  login    Iniciar fluxo de device code (RFC 8628) — abre o navegador para confirmar
+  logout   Encerrar a sessão local
+  whoami   Exibir informações do usuário autenticado
+```
+
+---
+
+### `kaven marketplace`
+
+Explorar e instalar módulos do Kaven Marketplace.
+
+```
+Subcomandos:
+  list      Listar módulos disponíveis
+  install   Baixar e aplicar um módulo no projeto atual
+  browse    Navegador interativo (TUI)
+
+Opções (list):
+  --category <cat>   Filtrar por categoria
+  --sort <campo>     newest (padrão) | popular | name
+  --page <n>         Número da página
+  --limit <n>        Resultados por página (máx 100)
+  --json             Saída em JSON bruto
+
+Opções (install):
+  --version <ver>    Instalar uma versão específica
+  --force            Pular confirmação de sobrescrita
+  --skip-env         Pular injeção no .env
+  --env-file <path>  Caminho do .env alvo
+```
+
+---
+
+### `kaven module`
+
+Gerenciar módulos instalados no projeto atual.
+
+```
+Subcomandos:
+  doctor    Executar health checks no projeto e nos módulos instalados
+  add       Instalar um módulo a partir de um manifest local
+  remove    Desinstalar um módulo instalado
+  publish   Publicar um módulo no marketplace
+
+Opções (doctor):
+  --fix    Corrigir problemas automaticamente (pnpm install, prisma generate, env vars)
+  --json   Saída em JSON legível por máquina
+
+Exit codes (doctor):
+  0   Todos os checks passaram
+  1   Um ou mais erros encontrados
+  2   Apenas avisos (sem erros)
+
+Opções (publish):
+  --dry-run          Validar e empacotar sem fazer upload
+  --changelog <msg>  Notas de release para esta versão
+```
+
+> `kaven doctor` é um alias para `kaven module doctor`.
+
+---
+
+### `kaven upgrade`
+
+Fazer upgrade da licença via checkout Paddle.
+
+```
+Opções:
+  --no-browser   Imprimir URL do checkout em vez de abrir o navegador
+
+Comportamento:
+  Abre o checkout Paddle no navegador → aguarda confirmação de pagamento (a cada 5s, máx 10 min)
+  → atualiza a licença local em caso de sucesso
+```
+
+---
+
+### `kaven license`
+
+```
+Subcomandos:
+  status   Exibir tier e validade da licença atual
+```
+
+---
+
+### `kaven cache`
+
+Gerenciar o cache local de respostas da API (`~/.kaven/cache`, máx 50 MB).
+
+```
+Subcomandos:
+  status   Exibir estatísticas do cache (tamanho, entradas, idade)
+  clear    Apagar todos os dados em cache
+
+TTLs do cache:
+  Listagem de módulos    24 horas
+  Manifests de módulos   7 dias
+  Status da licença      1 hora
+```
+
+---
+
+### `kaven telemetry`
+
+```
+Subcomandos:
+  view   Exibir eventos de telemetria locais recentes
+         -l, --limit <n>   Número de eventos (padrão: 10)
+```
+
+---
+
+### `kaven config`
+
+```
+Subcomandos:
+  set <chave> <valor>   Definir um valor de configuração
+  get <chave>           Ler um valor de configuração
+```
+
+---
+
+### `kaven init-ci`
+
+Inicializa configuração de CI/CD no projeto atual. Gera workflows do GitHub Actions configurados para projetos Kaven.
+
+---
+
+## Configuração
+
+Toda a configuração fica em `~/.kaven/`:
+
+```
+~/.kaven/
+  auth.json         Tokens de autenticação        (chmod 600)
+  config.json       Configuração da CLI
+  license.json      Chave e tier da licença
+  signing-key.json  Chave Ed25519 para módulos    (chmod 600)
+  cache/            Cache de respostas da API      (máx 50 MB)
+  telemetry.log     Eventos de telemetria locais
+```
+
+### Variáveis de Ambiente
+
+| Variável | Descrição |
+|----------|-----------|
+| `KAVEN_API_URL` | Sobrescrever a URL da API do marketplace |
+| `KAVEN_DEBUG=1` | Ativar saída de debug detalhada |
+| `KAVEN_OFFLINE=1` | Usar apenas dados em cache, sem requisições de rede |
+| `KAVEN_TELEMETRY=0` | Desativar telemetria completamente |
+
+### Sobrescrever a URL da API (config file)
+
+```json
+// ~/.kaven/config.json
+{
+  "apiUrl": "https://api.seu-kaven.com"
+}
+```
+
+### Modo Debug
+
+```bash
+KAVEN_DEBUG=1 kaven marketplace list
+```
+
+### Modo Offline
+
+```bash
+KAVEN_OFFLINE=1 kaven marketplace list
+```
+
+---
+
+## Troubleshooting
+
+**Erro "Not authenticated"**
+```bash
+kaven auth login
+```
+
+**"module.json not found" ao publicar**
+
+Execute `kaven module publish` de dentro do diretório do módulo (o que contém o `module.json`).
+
+**pnpm install falha no `kaven init`**
+```bash
+npm install -g pnpm          # instalar pnpm globalmente
+# ou pular e instalar depois:
+kaven init meu-app --skip-install
+cd meu-app && pnpm install
+```
+
+**Prisma client desatualizado**
+```bash
+kaven module doctor --fix
+# ou manualmente:
+npx prisma generate
+```
+
+**Problemas de cache**
+```bash
+kaven cache clear
+```
+
+**Permission denied em `~/.kaven/`**
+```bash
+chmod 700 ~/.kaven
+chmod 600 ~/.kaven/auth.json ~/.kaven/signing-key.json
+```
+
+---
+
+## Contribuindo
+
+```bash
+git clone https://github.com/kaven-co/kaven-cli
+cd kaven-cli
+pnpm install
+pnpm test           # 310 testes
+pnpm run typecheck
+pnpm run lint
+```
+
+**Convenção de commits:** este repositório usa [Conventional Commits](https://www.conventionalcommits.org/).
+
+```bash
+feat: adicionar flag --with-squad ao kaven init
+fix: corrigir corrupção de cache em escritas concorrentes
+docs: atualizar seção de troubleshooting
+```
+
+**Fluxo de release:**
+1. Abrir um PR contra `main`
+2. CI deve estar verde (lint + typecheck + testes + build)
+3. Merge → Semantic Release faz o bump de versão automaticamente e publica no npm (tag `@alpha`)
+
+Tipos que disparam release: `feat` (minor), `fix` / `perf` / `refactor` (patch), `BREAKING CHANGE` (major).
+Tipos que **não** disparam release: `chore`, `docs`, `test`, `style`, `ci`.
+
+Consulte [`docs/releasing.md`](./docs/releasing.md) para a documentação completa do pipeline de release.
+
+---
+
+## Licença
+
+Apache 2.0 — veja [LICENSE](LICENSE)
+
+---
+
+Documentação: https://docs.kaven.site/cli
+GitHub: https://github.com/kaven-co/kaven-cli
+npm: https://www.npmjs.com/package/kaven-cli