kaven-cli 0.3.0 → 0.3.5

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

package/dist/core/ModuleDoctor.js

@@ -28,9 +28,9 @@ class ModuleDoctor {
     async checkAnchors() {
         const results = [];
         const expectedAnchors = [
-            { file: "apps/api/src/index.ts", anchor: "// [ANCHOR:ROUTES]" },
-            { file: "apps/api/src/index.ts", anchor: "// [ANCHOR:MIDDLEWARE]" },
-            { file: "apps/admin/app/layout.tsx", anchor: "// [ANCHOR:NAV_ITEMS]" },
+            { file: "apps/api/src/app.ts", anchor: "// [KAVEN_MODULE_IMPORTS]" },
+            { file: "apps/api/src/app.ts", anchor: "// [KAVEN_MODULE_HOOKS]" },
+            { file: "apps/api/src/app.ts", anchor: "// [KAVEN_MODULE_REGISTRATION]" },
         ];
         for (const { file, anchor } of expectedAnchors) {
             const filePath = path_1.default.join(this.projectRoot, file);
@@ -433,7 +433,7 @@ class ModuleDoctor {
         return results;
     }
     async readKavenConfig() {
-        const configPath = path_1.default.join(this.projectRoot, "kaven.config.json");
+        const configPath = path_1.default.join(this.projectRoot, "kaven.json");
         if (!(await fs_extra_1.default.pathExists(configPath))) {
             return { modules: [] };
         }

package/dist/core/ProjectInitializer.js

@@ -8,6 +8,7 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const TEMPLATE_REPO = "https://github.com/kaven-co/kaven-template.git";
+const KAVEN_SQUAD_REPO = "https://github.com/bychrisr/kaven-squad";
 /** Run a shell command via spawn, returning exit code. */
 function runCommand(cmd, args, cwd, onData) {
     return new Promise((resolve, reject) => {
@@ -64,7 +65,7 @@ class ProjectInitializer {
         const filesToProcess = [
             "package.json",
             ".env.example",
-            "prisma/schema.prisma",
+            "packages/database/prisma/schema.prisma",
             "apps/api/package.json",
             "apps/admin/package.json",
             "apps/tenant/package.json",
@@ -79,6 +80,15 @@ class ProjectInitializer {
             }
             await fs_extra_1.default.writeFile(filePath, content, "utf-8");
         }
+        // Safety net: directly update root package.json name field regardless of placeholder
+        const pkgPath = path_1.default.join(targetDir, "package.json");
+        if (await fs_extra_1.default.pathExists(pkgPath)) {
+            const pkg = await fs_extra_1.default.readJson(pkgPath);
+            if (pkg.name !== values.projectName) {
+                pkg.name = values.projectName;
+                await fs_extra_1.default.writeJson(pkgPath, pkg, { spaces: 2 });
+            }
+        }
     }
     /** Run pnpm install in the target directory. */
     async runInstall(targetDir) {
@@ -93,11 +103,38 @@ class ProjectInitializer {
         await runCommand("git", ["add", "."], targetDir);
         await runCommand("git", ["commit", "-m", "chore: initial kaven setup"], targetDir);
     }
+    /**
+     * Clone kaven-squad into squads/kaven-squad/ inside the project.
+     * Returns { installed: true } on success, { installed: false, reason } on failure.
+     * Never throws — squad installation is non-fatal.
+     */
+    async installSquad(targetDir) {
+        const squadsDir = path_1.default.join(targetDir, "squads");
+        const squadDir = path_1.default.join(squadsDir, "kaven-squad");
+        // Squad already present — skip
+        if (await fs_extra_1.default.pathExists(squadDir)) {
+            return { installed: false, reason: "already-exists" };
+        }
+        await fs_extra_1.default.ensureDir(squadsDir);
+        const exitCode = await runCommand("git", ["clone", "--depth", "1", KAVEN_SQUAD_REPO, squadDir], process.cwd());
+        if (exitCode !== 0) {
+            return {
+                installed: false,
+                reason: `git clone exited with code ${exitCode}`,
+            };
+        }
+        // Remove .git — squad history not needed in user project
+        const squadGitDir = path_1.default.join(squadDir, ".git");
+        if (await fs_extra_1.default.pathExists(squadGitDir)) {
+            await fs_extra_1.default.remove(squadGitDir);
+        }
+        return { installed: true };
+    }
     /** Health check after project initialization. */
     async healthCheck(targetDir) {
         const issues = [];
         // Check key files exist
-        const requiredFiles = ["package.json", ".env.example", "prisma/schema.prisma"];
+        const requiredFiles = ["package.json", ".env.example", "packages/database/prisma/schema.prisma"];
         for (const file of requiredFiles) {
             if (!(await fs_extra_1.default.pathExists(path_1.default.join(targetDir, file)))) {
                 issues.push(`Missing required file: ${file}`);

package/dist/core/SignatureVerifier.js

@@ -33,9 +33,8 @@ function decodeSignature(encoded) {
  * Verify Ed25519 signature against a SHA-256 checksum.
  *
  * Accepts signature in either hex or base64 encoding.
- * The publisher signs the hex-encoded checksum with their
- * Ed25519 private key. We verify using the public key stored
- * in the release metadata.
+ * Tolerates signatures made over checksum with trailing newline
+ * (common when signing via `echo checksum > file && openssl sign`).
  */
 function verifyEd25519Signature(checksum, signature, publicKeyBase64) {
     try {
@@ -45,7 +44,11 @@ function verifyEd25519Signature(checksum, signature, publicKeyBase64) {
             format: "der",
         });
         const sigBuffer = decodeSignature(signature);
-        return crypto_1.default.verify(null, Buffer.from(checksum), publicKey, sigBuffer);
+        if (crypto_1.default.verify(null, Buffer.from(checksum), publicKey, sigBuffer)) {
+            return true;
+        }
+        // Tolerate trailing newline from shell-based signing
+        return crypto_1.default.verify(null, Buffer.from(checksum + "\n"), publicKey, sigBuffer);
     }
     catch {
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaven-cli",
-  "version": "0.3.0",
+  "version": "0.3.5",
   "description": "Kaven CLI - The official command line tool for Kaven",
   "main": "dist/index.js",
   "bin": {
@@ -12,7 +12,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "pnpm run build && pnpm run quality",
+    "prepublishOnly": "pnpm run build",
     "lint": "eslint 'src/**/*.{ts,tsx}' --max-warnings 0",
     "lint:fix": "eslint 'src/**/*.{ts,tsx}' --fix",
     "test": "vitest run",
@@ -39,9 +39,14 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/KavenCompany/kaven-cli"
+    "url": "https://github.com/kaven-co/kaven-cli"
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^20.0.0",
     "@types/tar": "^6.1.13",
@@ -49,6 +54,7 @@
     "@typescript-eslint/parser": "^8.53.1",
     "eslint": "^8.0.0",
     "msw": "^2.12.10",
+    "semantic-release": "^25.0.3",
     "typescript": "^5.0.0",
     "vitest": "^1.0.0"
   },

package/dist/commands/modules/add.js

@@ -1,53 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.addCommand = void 0;
-const commander_1 = require("commander");
-const path_1 = __importDefault(require("path"));
-const fs_extra_1 = __importDefault(require("fs-extra"));
-const ModuleManager_1 = require("../../core/modules/ModuleManager");
-const ModuleInstaller_1 = require("../../core/modules/ModuleInstaller");
-const logger_1 = require("../../lib/logger");
-exports.addCommand = new commander_1.Command('add')
-    .description('Install a module')
-    .argument('<slug>', 'Module slug to install')
-    .action(async (slug) => {
-    try {
-        const projectRoot = process.cwd();
-        // Locate modules source: 
-        // In dev: ./modules
-        // In prod (installed): ../modules relative to dist
-        // For now, assume we run from CLI root or use logic to find 'modules' folder.
-        // Ideally CLI should be installed in a way that 'modules' folder is known.
-        // Fallback logic for finding modules source:
-        // 1. Env var KAVEN_MODULES_PATH
-        // 2. Local ./modules
-        // 3. Resolve relative to __dirname (dist) -> ../modules
-        let modulesSource = process.env.KAVEN_MODULES_PATH;
-        if (!modulesSource) {
-            if (await fs_extra_1.default.pathExists(path_1.default.resolve('modules'))) {
-                modulesSource = path_1.default.resolve('modules');
-            }
-            else {
-                modulesSource = path_1.default.resolve(__dirname, '../../modules');
-            }
-        }
-        if (!await fs_extra_1.default.pathExists(modulesSource)) {
-            logger_1.Logger.error(`Module source not found at ${modulesSource}`);
-            return;
-        }
-        const manifestPath = path_1.default.join(modulesSource, slug, 'module.json');
-        if (!await fs_extra_1.default.pathExists(manifestPath)) {
-            logger_1.Logger.error(`Module ${slug} not found in catalog.`);
-            return;
-        }
-        const manifest = await ModuleManager_1.ModuleManager.loadManifest(manifestPath);
-        await ModuleInstaller_1.ModuleInstaller.install(manifest, projectRoot, modulesSource);
-    }
-    catch (error) {
-        logger_1.Logger.error('Failed to add module', error);
-        process.exit(1);
-    }
-});

package/dist/commands/modules/list.js

@@ -1,40 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.listCommand = void 0;
-const commander_1 = require("commander");
-const path_1 = __importDefault(require("path"));
-const ModuleManager_1 = require("../../core/modules/ModuleManager");
-const logger_1 = require("../../lib/logger");
-const chalk_1 = __importDefault(require("chalk"));
-exports.listCommand = new commander_1.Command('list')
-    .description('List available modules')
-    .action(async () => {
-    try {
-        logger_1.Logger.startSpinner('Loading modules...');
-        // By default, Kaven CLI looks for modules in the current project's ./kaven-cli/modules
-        // OR internal modules directory. For dev/bootstrap, we use the local 'modules' dir relative to CWD or __dirname.
-        // Strategy: 
-        // 1. Check local repo structure (dev mode): ./modules
-        // 2. Check installed structure (production): ../modules
-        const modulesPath = path_1.default.resolve('modules');
-        const modules = await ModuleManager_1.ModuleManager.listAvailableModules(modulesPath);
-        logger_1.Logger.stopSpinner();
-        if (modules.length === 0) {
-            logger_1.Logger.warn('No modules found in ' + modulesPath);
-            return;
-        }
-        logger_1.Logger.info(`Found ${modules.length} modules:`);
-        modules.forEach(mod => {
-            console.log('');
-            console.log(chalk_1.default.bold.cyan(mod.displayName) + ' ' + chalk_1.default.dim(`(${mod.slug})`));
-            console.log(chalk_1.default.white(mod.description));
-            console.log(chalk_1.default.dim(`Version: ${mod.version}`));
-        });
-    }
-    catch (error) {
-        logger_1.Logger.error('Failed to list modules', error);
-    }
-});

package/dist/commands/modules/remove.js

@@ -1,54 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.removeCommand = void 0;
-const commander_1 = require("commander");
-const path_1 = __importDefault(require("path"));
-const fs_extra_1 = __importDefault(require("fs-extra"));
-const ModuleManager_1 = require("../../core/modules/ModuleManager");
-const ModuleRemover_1 = require("../../core/modules/ModuleRemover");
-const logger_1 = require("../../lib/logger");
-exports.removeCommand = new commander_1.Command('remove')
-    .description('Remove a module')
-    .argument('<slug>', 'Module slug to remove')
-    .action(async (slug) => {
-    try {
-        const projectRoot = process.cwd();
-        // For removal, we need the manifest to know what to eject.
-        // We look for the installed module first?
-        // Doc 3: "The engine behaves as if it’s 'playing back' the manifest in reverse."
-        // We need the manifest. Where do we get it?
-        // Option A: From the installed module directory (if we copied the manifest there).
-        // Option B: From the store (but what if version changed?).
-        // Best practice: We should have copied module.json to the installed location.
-        // Current Installer (Phase 2) does NOT copy module.json to installed location explicitly (it copies `api` folder content).
-        // Let's check `ModuleInstaller.ts`:
-        // if (manifest.slug) -> copy `api` to `modules/slug`.
-        // Does `api` contain `module.json`? No, `module.json` is at root of module source.
-        // FIX REQUIRED: We should probably look up the manifest from the *store* (catalog) matching the installed version,
-        // OR we should store the manifest upon installation.
-        // For MVP (Phase 3), let's assume we can find the manifest in the same Store logic as `add`.
-        let modulesSource = process.env.KAVEN_MODULES_PATH;
-        if (!modulesSource) {
-            if (await fs_extra_1.default.pathExists(path_1.default.resolve('modules'))) {
-                modulesSource = path_1.default.resolve('modules');
-            }
-            else {
-                modulesSource = path_1.default.resolve(__dirname, '../../modules');
-            }
-        }
-        const manifestPath = path_1.default.join(modulesSource, slug, 'module.json');
-        if (!await fs_extra_1.default.pathExists(manifestPath)) {
-            logger_1.Logger.error(`Module manifest not found in store for ${slug}. Cannot safely remove.`);
-            return;
-        }
-        const manifest = await ModuleManager_1.ModuleManager.loadManifest(manifestPath);
-        await ModuleRemover_1.ModuleRemover.remove(manifest, projectRoot);
-    }
-    catch (error) {
-        logger_1.Logger.error('Failed to remove module', error);
-        process.exit(1);
-    }
-});