kaven-cli 0.1.0-alpha.1 → 0.3.0

package/README.md

@@ -1,93 +1,269 @@
-# Kaven CLI 🚀
+# 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)
+[![Version](https://img.shields.io/badge/version-0.2.0--alpha.1-orange.svg)](https://semver.org)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
 
-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** SaaS boilerplate ecosystem.
+Bootstrap projects, manage modules, and interact with the Kaven Marketplace.
 
-> **Note**: Este projeto está em fase **Alpha**. APIs e comandos estão sujeitos a alterações.
+> **Alpha**: APIs and commands are subject to 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 (for `kaven init`)
+
+---
 
-Consiga o seu projeto rodando em segundos:
+## Quick Start
+
+Five commands to get productive with Kaven:
 
 ```bash
-# 1. Autenticação
+# 1. Bootstrap a new 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]`
 
-# 5. Ver Telemetria Local
-kaven telemetry view
+Bootstrap a new Kaven project from the official template.
+
+```
+Options:
+  --defaults       Skip interactive prompts and use default values
+  --skip-install   Skip running pnpm install after setup
+  --skip-git       Skip git init and initial commit
+  --force          Overwrite existing directory
+
+Examples:
+  kaven init my-app
+  kaven init my-app --defaults
+  kaven init my-app --skip-git --skip-install
 ```
 
-## 🛠️ Comandos Principais
+### `kaven auth`
 
-A Kaven CLI organiza suas funcionalidades em grupos lógicos para uma melhor experiência:
+Manage authentication and session tokens.
 
-### 📦 Módulos (`module`, `m`)
+```
+Commands:
+  login    Start device code authentication flow (RFC 8628)
+  logout   Clear the local authentication session
+  whoami   Display info about the authenticated user
+```
 
-Gerenciamento local de módulos e integridade do projeto.
+### `kaven marketplace`
 
-- `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.
+Explore and install modules from the Kaven Marketplace.
 
-### 🔑 Autenticação (`auth`)
+```
+Commands:
+  list      List available modules
+  install   Install a module
+  browse    Interactive TUI module browser
+
+Options for list:
+  --category <cat>   Filter by category
+  --sort <field>     Sort: newest (default), popular, name
+  --page <n>         Page number
+  --limit <n>        Results per page (max: 100)
+  --json             Output raw JSON
+
+Options for install:
+  --version <ver>    Install specific version
+  --force            Skip overwrite confirmation
+  --skip-env         Skip .env injection
+  --env-file <path>  Target .env file
+```
 
-Gerenciamento de sessão e tokens.
+### `kaven module`
 
-- `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.
+Manage installed modules.
 
-### 🏬 Marketplace (`marketplace`, `mkt`)
+```
+Commands:
+  doctor    Run health checks on the project and modules
+  add       Install a module from a local manifest
+  remove    Remove an installed module
+  publish   Publish a module to the marketplace
+
+Options for doctor:
+  --fix    Auto-fix detected issues (pnpm install, prisma generate, env vars)
+  --json   Output machine-readable JSON
+
+Exit codes for doctor:
+  0   All checks passed
+  1   One or more errors found
+  2   Warnings only (no errors)
+
+Options for publish:
+  --dry-run          Validate and package without uploading
+  --changelog <text> Release notes for this version
+```
 
-Descoberta e instalação de módulos oficiais.
+### `kaven upgrade`
 
-- `kaven marketplace list`: Lista todos os módulos disponíveis na nuvem Kaven.
-- `kaven marketplace install <id>`: Baixa e instala um módulo automaticamente.
+Upgrade your Kaven license tier via Paddle checkout.
 
-### 📊 Telemetria (`telemetry`)
+```
+Options:
+  --no-browser   Print checkout URL instead of opening browser
 
-Observabilidade e auditoria local.
+Behavior:
+  - Opens a Paddle checkout in your browser
+  - Polls for payment confirmation (every 5s, max 10 min)
+  - Updates local license on success
+```
+
+### `kaven license`
+
+Manage your Kaven license.
+
+```
+Commands:
+  status   Show current license status and tier
+```
+
+### `kaven cache`
+
+Manage the local API response cache (~/.kaven/cache, max 50 MB).
+
+```
+Commands:
+  status   Show cache statistics (size, entries, age)
+  clear    Delete all cached data
+
+Cache TTLs:
+  Module listings:   24 hours
+  Module manifests:  7 days
+  License status:    1 hour
+```
+
+### `kaven telemetry`
 
-- `kaven telemetry view`: Exibe os últimos eventos registrados localmente.
+View observability and audit logs.
+
+```
+Commands:
+  view   Display the most recent local telemetry events
+         -l, --limit <n>   Number of events to show (default: 10)
+```
 
 ---
 
-## 🧪 Desenvolvimento
+## Configuration
+
+Kaven CLI stores configuration in `~/.kaven/`:
 
-Nós valorizamos contribuições! Antes de começar, por favor leia nosso guia de contribuição:
+```
+~/.kaven/
+  auth.json        Authentication tokens (chmod 600)
+  config.json      CLI configuration (apiUrl override)
+  license.json     License key and tier
+  signing-key.json Module signing key pair (chmod 600)
+  cache/           API response cache (max 50 MB)
+  telemetry.log    Local telemetry events
+```
 
-- [CONTRIBUTING.md](./CONTRIBUTING.md) - Guia de setup e padrões.
-- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) - Nosso compromisso com a comunidade.
+### Overriding the API URL
+
+Set `KAVEN_API_URL` environment variable or add to `~/.kaven/config.json`:
+
+```json
+{
+  "apiUrl": "https://api.your-kaven-instance.com"
+}
+```
+
+### Debug Mode
+
+```bash
+KAVEN_DEBUG=1 kaven marketplace list
+```
+
+### Offline Mode
+
+```bash
+KAVEN_OFFLINE=1 kaven marketplace list   # Uses cached data only
+```
+
+---
+
+## Troubleshooting
+
+### "Not authenticated" error
+
+Run `kaven auth login` and complete the device code flow in your browser.
+
+### "module.json not found" on publish
+
+Run `kaven module publish` from inside the module directory
+(the directory containing `module.json`).
+
+### pnpm install fails on kaven init
+
+Install pnpm globally: `npm install -g pnpm`
+Or use `kaven init --skip-install` and run `pnpm install` manually.
+
+### Prisma client out of sync
+
+Run `kaven module doctor --fix` or manually: `npx prisma generate`
+
+### Cache issues
+
+Clear the cache: `kaven cache clear`
+
+### Permission denied on ~/.kaven/
+
+```bash
+chmod 700 ~/.kaven
+chmod 600 ~/.kaven/auth.json
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/kaven-co/kaven-cli
+cd kaven-cli
+pnpm install          # or: npm install (with legacy-peer-deps)
+pnpm test             # Run test suite
+pnpm run typecheck    # TypeScript check
+pnpm run lint         # ESLint
+```
+
+---
 
-## 📄 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.sh/cli
+GitHub: https://github.com/kaven-co/kaven-cli

package/dist/commands/auth/login.js

@@ -6,39 +6,117 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.authLogin = authLogin;
 const chalk_1 = __importDefault(require("chalk"));
 const ora_1 = __importDefault(require("ora"));
+const open_1 = __importDefault(require("open"));
 const AuthService_1 = require("../../core/AuthService");
+const MarketplaceClient_1 = require("../../infrastructure/MarketplaceClient");
 const TelemetryBuffer_1 = require("../../infrastructure/TelemetryBuffer");
+/**
+ * Sleep helper for polling delays
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Poll for access token with exponential backoff
+ */
+async function pollForToken(client, deviceCode, expiresIn, initialInterval, spinner) {
+    const deadline = Date.now() + expiresIn * 1000;
+    const backoffIntervals = [5, 10, 15, 20]; // seconds - exponential backoff
+    let backoffIndex = 0;
+    let interval = initialInterval;
+    while (Date.now() < deadline) {
+        // Update countdown spinner
+        const remaining = Math.ceil((deadline - Date.now()) / 1000);
+        const mm = Math.floor(remaining / 60);
+        const ss = String(remaining % 60).padStart(2, '0');
+        spinner.text = `Waiting for authorization... (expires in ${mm}:${ss})`;
+        // Wait for next poll
+        await sleep(interval * 1000);
+        try {
+            const result = await client.pollDeviceToken(deviceCode);
+            // Success - return tokens
+            if (result.status === 'success' && result.tokens) {
+                return result.tokens;
+            }
+            // Handle different status codes
+            switch (result.status) {
+                case 'slow_down':
+                    // Increase interval by 5s as requested by server
+                    interval += 5;
+                    break;
+                case 'access_denied':
+                    throw new Error('Authorization denied by user. Try again with \'kaven auth login\'.');
+                case 'expired_token':
+                    throw new Error('Device code expired. Run \'kaven auth login\' again.');
+                case 'authorization_pending':
+                    // Continue polling - apply exponential backoff
+                    if (backoffIndex < backoffIntervals.length - 1) {
+                        backoffIndex++;
+                        interval = backoffIntervals[backoffIndex];
+                    }
+                    break;
+            }
+        }
+        catch (error) {
+            // Re-throw our custom errors
+            if (error.message.includes('denied') ||
+                error.message.includes('expired')) {
+                throw error;
+            }
+            // Network errors
+            const nodeError = error;
+            if (nodeError.code === 'ECONNREFUSED' || nodeError.code === 'ENOTFOUND') {
+                throw new Error('Network error. Check your connection and try again.');
+            }
+            // Unknown error
+            throw error;
+        }
+    }
+    // Timeout - device code expired
+    throw new Error('Device code expired. Run \'kaven auth login\' again.');
+}
+/**
+ * Main login command - OAuth 2.0 Device Authorization Grant (RFC 8628)
+ */
 async function authLogin() {
     const telemetry = TelemetryBuffer_1.TelemetryBuffer.getInstance();
     const startTime = Date.now();
     telemetry.capture("cli.auth.login.start");
+    const client = new MarketplaceClient_1.MarketplaceClient();
     const authService = new AuthService_1.AuthService();
-    console.log(chalk_1.default.blue("🔐 Iniciando fluxo de autenticação...\n"));
-    const spinner = (0, ora_1.default)("Gerando código de dispositivo...").start();
+    console.log(chalk_1.default.blue("🔐 Starting authentication flow...\n"));
+    const spinner = (0, ora_1.default)("Requesting device code from marketplace...").start();
     try {
-        // Simulando atraso da rede
-        await new Promise((resolve) => setTimeout(resolve, 1000));
-        const deviceCode = "KAVEN-777-BINGO";
-        const verificationUrl = "https://kaven.sh/device";
+        // Step 1: Request device code
+        const { device_code, user_code, verification_uri, expires_in, interval } = await client.requestDeviceCode();
         spinner.stop();
-        console.log(chalk_1.default.yellow("Para continuar o login, acesse a URL abaixo e insira o código:"));
-        console.log(chalk_1.default.bold(`\n   URL:    ${verificationUrl}`));
-        console.log(chalk_1.default.bold(`   Código: ${deviceCode}\n`));
-        const pollSpinner = (0, ora_1.default)("Aguardando autorização no navegador...").start();
-        // Simular polling bem-sucedido após 3 segundos
-        await new Promise((resolve) => setTimeout(resolve, 3000));
-        const mockToken = "jwt-mock-token-for-kaven-explorador";
-        await authService.storeToken(mockToken);
-        pollSpinner.succeed(chalk_1.default.green("Autenticação realizada com sucesso!"));
-        console.log(chalk_1.default.gray("\nSeu token foi salvo com segurança em ~/.kaven/auth.json"));
-        telemetry.capture("cli.auth.login.success", {}, Date.now() - startTime);
+        // Step 2: Display code and open browser
+        console.log(chalk_1.default.yellow("To complete login, follow these steps:\n"));
+        console.log(chalk_1.default.bold(`  Your verification code: ${chalk_1.default.cyan(user_code)}\n`));
+        try {
+            await (0, open_1.default)(verification_uri);
+            console.log(chalk_1.default.dim("  ✓ Browser opened automatically"));
+        }
+        catch {
+            console.log(chalk_1.default.yellow(`  Open this URL in your browser:`));
+            console.log(chalk_1.default.underline(`  ${verification_uri}\n`));
+        }
+        // Step 3: Poll for token with exponential backoff
+        const pollSpinner = (0, ora_1.default)('Waiting for authorization...').start();
+        const tokens = await pollForToken(client, device_code, expires_in, interval, pollSpinner);
+        // Step 4: Store tokens securely
+        await authService.saveTokens(tokens);
+        pollSpinner.succeed(chalk_1.default.green(`Logged in as ${chalk_1.default.bold(tokens.user.email)}`));
+        console.log(chalk_1.default.dim(`  Tier: ${tokens.user.tier}`));
+        console.log(chalk_1.default.gray("\n  Your credentials were saved securely in ~/.kaven/auth.json\n"));
+        telemetry.capture("cli.auth.login.success", { tier: tokens.user.tier }, Date.now() - startTime);
         await telemetry.flush();
     }
     catch (error) {
         telemetry.capture("cli.auth.login.error", { error: error.message }, Date.now() - startTime);
         await telemetry.flush();
-        spinner.fail(chalk_1.default.red("Erro ao realizar login."));
-        console.error(error);
+        spinner.fail(chalk_1.default.red("Authentication failed"));
+        console.error(chalk_1.default.red(`\n  Error: ${error.message}\n`));
         process.exit(1);
     }
 }

package/dist/commands/auth/logout.js

@@ -5,21 +5,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.authLogout = authLogout;
 const chalk_1 = __importDefault(require("chalk"));
-const ora_1 = __importDefault(require("ora"));
 const AuthService_1 = require("../../core/AuthService");
 async function authLogout() {
     const authService = new AuthService_1.AuthService();
-    const spinner = (0, ora_1.default)("Encerrando sessão...").start();
     try {
         if (!(await authService.isAuthenticated())) {
-            spinner.info(chalk_1.default.yellow("Você não está autenticado."));
+            console.log(chalk_1.default.yellow("You are not authenticated."));
             return;
         }
-        await authService.clearToken();
-        spinner.succeed(chalk_1.default.green("Sessão encerrada com sucesso!"));
+        await authService.logout();
+        console.log(chalk_1.default.green("Logged out successfully."));
     }
     catch {
-        spinner.fail(chalk_1.default.red("Erro ao realizar logout."));
+        console.error(chalk_1.default.red("Error during logout."));
         process.exit(1);
     }
 }

package/dist/commands/auth/whoami.js

@@ -12,24 +12,25 @@ async function authWhoami() {
     telemetry.capture("cli.auth.whoami.start");
     const authService = new AuthService_1.AuthService();
     try {
-        const userInfo = await authService.getUserInfo();
-        if (!userInfo) {
-            console.log(chalk_1.default.yellow("Você não está autenticado."));
-            console.log(chalk_1.default.gray("Use 'kaven auth login' para entrar."));
+        const info = await authService.getWhoamiInfo();
+        if (!info) {
+            console.log(chalk_1.default.yellow("You are not authenticated."));
+            console.log(chalk_1.default.gray("Use 'kaven auth login' to sign in."));
             telemetry.capture("cli.auth.whoami.not_authenticated");
             await telemetry.flush();
             return;
         }
         telemetry.capture("cli.auth.whoami.authenticated");
-        console.log(chalk_1.default.blue("👤 Usuário logado:"));
-        console.log(`${chalk_1.default.bold("ID:")}    ${userInfo.id}`);
-        console.log(`${chalk_1.default.bold("E-mail:")} ${userInfo.email}`);
-        if (userInfo.name) {
-            console.log(`${chalk_1.default.bold("Nome:")}   ${userInfo.name}`);
-        }
+        console.log();
+        console.log(`  ${chalk_1.default.bold("Email:")}    ${info.email}`);
+        console.log(`  ${chalk_1.default.bold("GitHub:")}   ${info.githubId}`);
+        console.log(`  ${chalk_1.default.bold("Tier:")}     ${info.tier}`);
+        console.log(`  ${chalk_1.default.bold("Session:")}  ${info.sessionExpiry}`);
+        console.log();
     }
     catch {
-        console.error(chalk_1.default.red("Erro ao verificar status de autenticação."));
+        console.error(chalk_1.default.red("Error checking authentication status."));
         process.exit(1);
     }
+    await telemetry.flush();
 }

package/dist/commands/cache/index.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheStatus = cacheStatus;
+exports.cacheClear = cacheClear;
+const chalk_1 = __importDefault(require("chalk"));
+const CacheManager_1 = require("../../core/CacheManager");
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return "0 B";
+    const k = 1024;
+    const sizes = ["B", "KB", "MB", "GB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}
+async function cacheStatus() {
+    const manager = (0, CacheManager_1.getCacheManager)();
+    const stats = await manager.stats();
+    console.log(chalk_1.default.bold("\nKaven CLI Cache Status\n"));
+    console.log(`  Cache directory:  ${chalk_1.default.cyan(manager.cacheDir)}`);
+    console.log(`  Total size:       ${chalk_1.default.cyan(formatBytes(stats.totalSize))}`);
+    console.log(`  Cached entries:   ${chalk_1.default.cyan(stats.entries.toString())}`);
+    if (stats.oldest) {
+        console.log(`  Oldest entry:     ${chalk_1.default.gray(stats.oldest.toLocaleString())}`);
+    }
+    if (stats.newest) {
+        console.log(`  Newest entry:     ${chalk_1.default.gray(stats.newest.toLocaleString())}`);
+    }
+    console.log();
+    console.log(chalk_1.default.gray("Run 'kaven cache clear' to remove all cached data."));
+}
+async function cacheClear() {
+    const manager = (0, CacheManager_1.getCacheManager)();
+    const stats = await manager.stats();
+    if (stats.entries === 0) {
+        console.log(chalk_1.default.gray("Cache is already empty."));
+        return;
+    }
+    await manager.clear();
+    console.log(chalk_1.default.green(`Cache cleared: ${stats.entries} entries (${formatBytes(stats.totalSize)}) removed.`));
+}