kaven-cli 0.1.0-alpha.1 → 0.3.5

package/dist/core/RegistryResolver.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistryResolver = void 0;
+const ConfigManager_1 = require("./ConfigManager");
+const MarketplaceClient_1 = require("../infrastructure/MarketplaceClient");
+const AuthService_1 = require("./AuthService");
+/**
+ * C2.5: Registry resolver — handles both official and custom registries
+ */
+class RegistryResolver {
+    constructor(authService) {
+        this.authService = authService || new AuthService_1.AuthService();
+    }
+    /**
+     * Get the active registry URL (custom or default)
+     */
+    async getActiveRegistry() {
+        await ConfigManager_1.configManager.initialize();
+        return ConfigManager_1.configManager.getRegistry();
+    }
+    /**
+     * Get marketplace client for active registry
+     */
+    async getMarketplaceClient() {
+        const registry = await this.getActiveRegistry();
+        const client = new MarketplaceClient_1.MarketplaceClient(this.authService);
+        // Set custom registry if configured
+        if (registry !== "https://marketplace.kaven.sh") {
+            client.baseUrl = registry;
+        }
+        return client;
+    }
+    /**
+     * Validate registry URL is accessible
+     */
+    async validateRegistry(url) {
+        try {
+            const response = await fetch(`${url}/health`);
+            if (!response.ok) {
+                return {
+                    valid: false,
+                    error: `Registry returned ${response.status} ${response.statusText}`,
+                };
+            }
+            return { valid: true };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: `Failed to connect: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    /**
+     * Set custom registry
+     */
+    async setCustomRegistry(url) {
+        // Validate URL format
+        try {
+            new URL(url);
+        }
+        catch {
+            throw new Error(`Invalid URL format: ${url}`);
+        }
+        // Validate registry is accessible
+        const validation = await this.validateRegistry(url);
+        if (!validation.valid) {
+            throw new Error(`Registry validation failed: ${validation.error}`);
+        }
+        // Save to config
+        await ConfigManager_1.configManager.initialize();
+        await ConfigManager_1.configManager.set("customRegistry", url);
+    }
+    /**
+     * Reset to default registry
+     */
+    async resetToDefaultRegistry() {
+        await ConfigManager_1.configManager.initialize();
+        await ConfigManager_1.configManager.set("customRegistry", undefined);
+    }
+    /**
+     * List all available registries (default + custom)
+     */
+    async listRegistries() {
+        await ConfigManager_1.configManager.initialize();
+        const config = ConfigManager_1.configManager.getAll();
+        return {
+            default: config.registry || "https://marketplace.kaven.sh",
+            custom: config.customRegistry,
+            active: await this.getActiveRegistry(),
+        };
+    }
+}
+exports.RegistryResolver = RegistryResolver;

package/dist/core/ScriptRunner.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScriptRunner = void 0;
+const child_process_1 = require("child_process");
+const readline_1 = __importDefault(require("readline"));
+const chalk_1 = __importDefault(require("chalk"));
+class ScriptRunner {
+    constructor(timeoutMs = 60000) {
+        this.timeoutMs = timeoutMs;
+    }
+    async runScript(script, label, skipConfirmation = false) {
+        if (!skipConfirmation) {
+            const confirmed = await this.confirm(`Run ${label} script: ${script.command} ${(script.args ?? []).join(' ')}?`);
+            if (!confirmed) {
+                console.log(chalk_1.default.dim(`  Skipping ${label} script.`));
+                return;
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const child = (0, child_process_1.spawn)(script.command, script.args ?? [], {
+                cwd: script.cwd,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                shell: true,
+            });
+            const prefix = chalk_1.default.dim(`[${label}] `);
+            child.stdout?.on('data', (data) => {
+                process.stdout.write(prefix + data.toString());
+            });
+            child.stderr?.on('data', (data) => {
+                process.stderr.write(prefix + chalk_1.default.yellow(data.toString()));
+            });
+            const timer = setTimeout(() => {
+                console.warn(chalk_1.default.yellow(`\n  ⚠ ${label} script timed out after ${this.timeoutMs / 1000}s, sending SIGTERM...`));
+                child.kill('SIGTERM');
+                setTimeout(() => {
+                    child.kill('SIGKILL');
+                }, 5000);
+            }, this.timeoutMs);
+            child.on('close', (code) => {
+                clearTimeout(timer);
+                if (code === 0 || code === null) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`${label} script exited with code ${code}`));
+                }
+            });
+            child.on('error', (err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+    async runScripts(scripts, label, skipConfirmation = false) {
+        for (const script of scripts) {
+            await this.runScript(script, label, skipConfirmation);
+        }
+    }
+    confirm(message) {
+        return new Promise((resolve) => {
+            const rl = readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
+            rl.question(`\n  ${message} [y/N] `, (answer) => {
+                rl.close();
+                resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+            });
+        });
+    }
+}
+exports.ScriptRunner = ScriptRunner;

package/dist/core/SignatureVerifier.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeFileChecksum = computeFileChecksum;
+exports.verifyEd25519Signature = verifyEd25519Signature;
+exports.verifyDownload = verifyDownload;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const errors_1 = require("../infrastructure/errors");
+/**
+ * Compute SHA-256 hex checksum of a file.
+ */
+async function computeFileChecksum(filePath) {
+    const data = await fs_extra_1.default.readFile(filePath);
+    return crypto_1.default.createHash("sha256").update(data).digest("hex");
+}
+const HEX_PATTERN = /^[0-9a-fA-F]+$/;
+/**
+ * Decode a signature string that may be hex or base64 encoded.
+ * Ed25519 signatures are always 64 bytes:
+ *   - hex: 128 chars, only [0-9a-fA-F]
+ *   - base64: 88 chars, may contain +/=
+ */
+function decodeSignature(encoded) {
+    if (HEX_PATTERN.test(encoded) && encoded.length === 128) {
+        return Buffer.from(encoded, "hex");
+    }
+    return Buffer.from(encoded, "base64");
+}
+/**
+ * Verify Ed25519 signature against a SHA-256 checksum.
+ *
+ * Accepts signature in either hex or base64 encoding.
+ * Tolerates signatures made over checksum with trailing newline
+ * (common when signing via `echo checksum > file && openssl sign`).
+ */
+function verifyEd25519Signature(checksum, signature, publicKeyBase64) {
+    try {
+        const publicKey = crypto_1.default.createPublicKey({
+            key: Buffer.from(publicKeyBase64, "base64"),
+            type: "spki",
+            format: "der",
+        });
+        const sigBuffer = decodeSignature(signature);
+        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;
+    }
+}
+/**
+ * Verify a downloaded module tarball:
+ * 1. Compute SHA-256 checksum and compare to expected
+ * 2. Verify Ed25519 signature of checksum with publisher key
+ *
+ * Throws SignatureVerificationError on failure.
+ */
+async function verifyDownload(opts) {
+    const actualChecksum = await computeFileChecksum(opts.filePath);
+    if (actualChecksum !== opts.expectedChecksum) {
+        throw new errors_1.SignatureVerificationError(`Checksum mismatch: expected ${opts.expectedChecksum.substring(0, 16)}..., ` +
+            `got ${actualChecksum.substring(0, 16)}...`);
+    }
+    const valid = verifyEd25519Signature(opts.expectedChecksum, opts.signature, opts.publicKeyBase64);
+    if (!valid) {
+        throw new errors_1.SignatureVerificationError("Ed25519 signature verification failed. " +
+            "The package may have been tampered with.");
+    }
+}

package/dist/index.js

@@ -6,55 +6,152 @@ const commander_1 = require("commander");
 const doctor_1 = require("./commands/module/doctor");
 const add_1 = require("./commands/module/add");
 const remove_1 = require("./commands/module/remove");
+const publish_1 = require("./commands/module/publish");
 const login_1 = require("./commands/auth/login");
 const logout_1 = require("./commands/auth/logout");
 const whoami_1 = require("./commands/auth/whoami");
 const list_1 = require("./commands/marketplace/list");
 const install_1 = require("./commands/marketplace/install");
+const browse_1 = require("./commands/marketplace/browse");
 const view_1 = require("./commands/telemetry/view");
+const index_js_1 = require("./commands/license/index.js");
+const index_1 = require("./commands/init/index");
+const index_2 = require("./commands/upgrade/index");
+const index_3 = require("./commands/cache/index");
+const index_4 = require("./commands/config/index");
+const index_5 = require("./commands/init-ci/index");
 const main = () => {
     const program = new commander_1.Command();
     program
         .name("kaven")
-        .description("CLI oficial para o ecossistema Kaven")
-        .version("0.1.0-alpha.1");
+        .description("The official CLI for the Kaven SaaS boilerplate ecosystem")
+        .version("0.2.0-alpha.1")
+        .addHelpText("after", `
+Examples:
+  $ kaven init my-saas-app          Bootstrap a new Kaven project
+  $ kaven auth login                Authenticate with Kaven Marketplace
+  $ kaven marketplace list          Browse available modules
+  $ kaven marketplace install auth  Install the auth module
+  $ kaven upgrade                   Upgrade your license tier
+  $ kaven module doctor             Check project health
+
+Documentation: https://docs.kaven.sh/cli
+Support:       https://github.com/kaven-co/kaven-cli/issues
+`);
+    /**
+     * Init command — Bootstrap a new Kaven project
+     */
+    program
+        .command("init [project-name]")
+        .description("Bootstrap a new Kaven project from the official template")
+        .option("--defaults", "Skip interactive prompts and use default values")
+        .option("--skip-install", "Skip running pnpm install after setup")
+        .option("--skip-git", "Skip git init and initial commit")
+        .option("--force", "Overwrite existing directory if it exists")
+        .addHelpText("after", `
+Examples:
+  $ kaven init my-app               Interactive setup
+  $ kaven init my-app --defaults    Use defaults (no prompts)
+  $ kaven init my-app --skip-git   Skip git initialization
+`)
+        .action((name, opts) => (0, index_1.initProject)(name, {
+        defaults: opts.defaults,
+        skipInstall: opts.skipInstall,
+        skipGit: opts.skipGit,
+        force: opts.force,
+    }));
     /**
      * Modules Group
      */
     const moduleCommand = program
         .command("module")
         .alias("m")
-        .description("Gerenciamento de módulos e integridade");
+        .description("Manage Kaven modules: install, remove, publish, and diagnose")
+        .addHelpText("after", `
+Examples:
+  $ kaven module doctor             Check module integrity
+  $ kaven module doctor --fix       Auto-fix detected issues
+  $ kaven module add ./my-module    Install a local module
+  $ kaven module remove payments    Remove a module
+  $ kaven module publish            Publish module to marketplace
+`);
     moduleCommand
         .command("doctor")
-        .description("Verifica integridade do projeto e dos módulos instalados")
-        .option("--fix", "Attempt to fix issues")
-        .action((options) => (0, doctor_1.moduleDoctor)(options));
+        .description("Run comprehensive project and module health checks")
+        .option("--fix", "Attempt to auto-fix detected issues (pnpm install, prisma generate, env vars)")
+        .option("--json", "Output results as machine-readable JSON")
+        .addHelpText("after", `
+Exit codes:
+  0  All checks passed
+  1  One or more errors found
+  2  Warnings only (no errors)
+
+Examples:
+  $ kaven module doctor
+  $ kaven module doctor --fix
+  $ kaven module doctor --json
+`)
+        .action((options) => (0, doctor_1.moduleDoctor)({ fix: options.fix, json: options.json }));
     moduleCommand
         .command("add <path>")
-        .description("Instala um módulo a partir de um manifest local")
+        .description("Install a module from a local manifest file")
+        .addHelpText("after", `
+Examples:
+  $ kaven module add ./modules/payments/module.json
+  $ kaven module add /absolute/path/to/module.json
+`)
         .action((path) => (0, add_1.moduleAdd)(path));
     moduleCommand
         .command("remove <name>")
-        .description("Remove um módulo e limpa injeções de código")
+        .description("Remove an installed module and clean up injected code")
+        .addHelpText("after", `
+Examples:
+  $ kaven module remove payments
+  $ kaven module remove notifications
+`)
         .action((name) => (0, remove_1.moduleRemove)(name));
+    moduleCommand
+        .command("publish")
+        .description("Publish the current directory as a module to Kaven Marketplace")
+        .option("--dry-run", "Validate and package the module without uploading")
+        .option("--changelog <text>", "Release notes for this version")
+        .addHelpText("after", `
+Requirements:
+  - module.json must exist in the current directory
+  - Must be authenticated: run 'kaven auth login' first
+
+Examples:
+  $ kaven module publish
+  $ kaven module publish --dry-run
+  $ kaven module publish --changelog "Added dark mode support"
+`)
+        .action((opts) => (0, publish_1.modulePublish)({
+        dryRun: opts.dryRun,
+        changelog: opts.changelog,
+    }));
     /**
      * Auth Group
      */
     const authCommand = program
         .command("auth")
-        .description("Autenticação e gerenciamento de sessão");
+        .description("Manage authentication and session tokens")
+        .addHelpText("after", `
+Examples:
+  $ kaven auth login    Start device code authentication flow
+  $ kaven auth whoami   Show current user info
+  $ kaven auth logout   End the local session
+`);
     authCommand
         .command("login")
-        .description("Inicia o fluxo de login interativo")
+        .description("Start the interactive device code authentication flow (RFC 8628)")
         .action(() => (0, login_1.authLogin)());
     authCommand
         .command("logout")
-        .description("Encerra a sessão local")
+        .description("Clear the local authentication session")
         .action(() => (0, logout_1.authLogout)());
     authCommand
         .command("whoami")
-        .description("Exibe informações do usuário autenticado")
+        .description("Display information about the currently authenticated user")
         .action(() => (0, whoami_1.authWhoami)());
     /**
      * Marketplace Group
@@ -63,26 +160,174 @@ const main = () => {
         .command("marketplace")
         .alias("mkt")
         .alias("market")
-        .description("Explorar e instalar módulos do Marketplace oficial");
+        .description("Explore, browse, and install modules from the Kaven Marketplace")
+        .addHelpText("after", `
+Examples:
+  $ kaven marketplace list
+  $ kaven marketplace list --category auth --sort popular
+  $ kaven marketplace install payments
+  $ kaven marketplace browse
+`);
     marketplaceCommand
         .command("list")
-        .description("Lista todos os módulos disponíveis no marketplace")
-        .action(() => (0, list_1.marketplaceList)());
+        .description("List all modules available in the marketplace")
+        .option("--category <category>", "Filter modules by category")
+        .option("--sort <field>", "Sort order: newest (default), popular, name", "newest")
+        .option("--page <n>", "Page number (default: 1)", "1")
+        .option("--limit <n>", "Results per page (default: 20, max: 100)", "20")
+        .option("--json", "Output raw JSON instead of formatted table")
+        .action((options) => (0, list_1.marketplaceList)({
+        category: options.category,
+        sort: options.sort,
+        page: parseInt(options.page, 10),
+        limit: parseInt(options.limit, 10),
+        json: options.json ?? false,
+    }));
     marketplaceCommand
         .command("install <moduleId>")
-        .description("Baixa e instala um módulo via Marketplace")
-        .action((moduleId) => (0, install_1.marketplaceInstall)(moduleId));
+        .description("Download and install a module from the Kaven Marketplace")
+        .option("--version <ver>", "Install a specific version (default: latest)")
+        .option("--force", "Skip overwrite confirmation")
+        .option("--skip-env", "Skip environment variable injection")
+        .option("--skip-verify", "Skip Ed25519 signature verification (dev only)")
+        .option("--env-file <path>", "Target .env file (default: .env)")
+        .addHelpText("after", `
+Examples:
+  $ kaven marketplace install payments
+  $ kaven marketplace install payments --version 1.2.0
+  $ kaven marketplace install auth --skip-env
+  $ kaven marketplace install my-module --skip-verify
+`)
+        .action((moduleId, options) => (0, install_1.marketplaceInstall)(moduleId, {
+        version: options.version,
+        force: options.force ?? false,
+        skipEnv: options.skipEnv ?? false,
+        skipVerify: options.skipVerify ?? false,
+        envFile: options.envFile,
+    }));
+    marketplaceCommand
+        .command("browse")
+        .description("Interactive TUI module browser — explore modules by category")
+        .addHelpText("after", `
+Navigate with arrow keys, press Enter to select.
+Supports category filtering and pagination.
+`)
+        .action(() => (0, browse_1.marketplaceBrowse)());
+    /**
+     * Upgrade Group — License tier upgrades and CLI updates
+     */
+    const upgradeCommandGroup = program
+        .command("upgrade")
+        .description("Upgrade your license tier or CLI version")
+        .addHelpText("after", `
+Examples:
+  $ kaven upgrade                  Upgrade license tier
+  $ kaven upgrade check            Check for CLI updates
+  $ kaven upgrade install          Install latest CLI version
+`);
+    upgradeCommandGroup
+        .command("tier")
+        .description("Upgrade your Kaven license to a higher tier (default)")
+        .option("--no-browser", "Print the checkout URL instead of opening the browser")
+        .action((opts) => (0, index_2.upgradeCommand)({
+        browser: opts.browser !== false,
+    }));
+    upgradeCommandGroup
+        .command("check")
+        .description("Check for Kaven CLI updates")
+        .action(() => (0, index_2.upgradeCheck)());
+    upgradeCommandGroup
+        .command("install")
+        .description("Install the latest Kaven CLI version")
+        .action(() => (0, index_2.upgradeInstall)());
     /**
      * Telemetry Group
      */
     const telemetryCommand = program
         .command("telemetry")
-        .description("Observabilidade e auditoria de comandos");
+        .description("View observability and command audit logs");
     telemetryCommand
         .command("view")
-        .description("Visualiza os últimos eventos de telemetria locais")
-        .option("-l, --limit <number>", "Número de eventos a exibir", "10")
+        .description("Display the most recent local telemetry events")
+        .option("-l, --limit <number>", "Number of events to display", "10")
         .action((options) => (0, view_1.telemetryView)(parseInt(options.limit)));
+    /**
+     * License Group
+     */
+    program.addCommand((0, index_js_1.buildLicenseCommand)());
+    /**
+     * Cache Group
+     */
+    const cacheCommand = program
+        .command("cache")
+        .description("Manage the local API response cache")
+        .addHelpText("after", `
+Cache directory: ~/.kaven/cache (max 50 MB)
+Cached data: module listings (24h TTL), manifests (7d), license status (1h)
+
+Examples:
+  $ kaven cache status
+  $ kaven cache clear
+`);
+    cacheCommand
+        .command("status")
+        .description("Show cache statistics (size, entry count, age)")
+        .action(() => (0, index_3.cacheStatus)());
+    cacheCommand
+        .command("clear")
+        .description("Delete all locally cached API responses")
+        .action(() => (0, index_3.cacheClear)());
+    /**
+     * Config Group — Manage Kaven CLI configuration
+     */
+    const configCommand = program
+        .command("config")
+        .description("Manage Kaven CLI configuration")
+        .addHelpText("after", `
+Config file: ~/.kaven/config.json
+
+Examples:
+  $ kaven config set registry https://custom.registry.sh
+  $ kaven config get registry
+  $ kaven config view
+  $ kaven config reset
+`);
+    configCommand
+        .command("set <key> <value>")
+        .description("Set a configuration value")
+        .action((key, value) => (0, index_4.configSet)(key, value));
+    configCommand
+        .command("get <key>")
+        .description("Get a configuration value")
+        .option("--json", "Output as JSON")
+        .action((key, opts) => (0, index_4.configGet)(key, { json: opts.json }));
+    configCommand
+        .command("view")
+        .description("Display all configuration")
+        .option("--json", "Output as JSON")
+        .action((opts) => (0, index_4.configView)({ json: opts.json }));
+    configCommand
+        .command("reset")
+        .description("Reset configuration to defaults")
+        .action(() => (0, index_4.configReset)());
+    /**
+     * Init CI — Initialize CI/CD workflows
+     */
+    program
+        .command("init-ci")
+        .description("Initialize GitHub Actions CI/CD workflows")
+        .option("--dry-run", "Show what would be created without writing files")
+        .addHelpText("after", `
+Creates:
+  - .github/workflows/test.yml       Run tests on push/PR
+  - .github/workflows/publish.yml    Publish modules on git tags
+  - .husky/pre-commit                Local pre-commit validation
+
+Examples:
+  $ kaven init-ci                  Interactive setup
+  $ kaven init-ci --dry-run        Show what would be created
+`)
+        .action((opts) => (0, index_5.initCi)({ dryRun: opts.dryRun }));
     program.parse();
 };
 exports.main = main;