npm package: @jamx-framework/cli
Description: JAMX Framework â€” CLI
Author: Stiven-21
Latest version: 1.1.0

# @jamx-framework/cli

## Descripción
Interfaz de línea de comandos (CLI) de JAMX Framework. Proporciona comandos para crear, desarrollar, construir, desplegar y gestionar aplicaciones JAMX. Es la herramienta principal que los desarrolladores usan para interactuar con el framework desde la terminal, ofreciendo una experiencia de desarrollo integrada y productiva.

## Cómo funciona
El CLI está construido con Commander.js y organizado en comandos jerárquicos:

- **Comandos globales**: `build`, `dev`, `create`, `generate`, `type-check`
- **Comandos de base de datos**: `db:migrate`, `db:rollback`, `db:status`, `db:generate-migration`
- **Comandos de deployment**: `deploy` (a Vercel, Cloudflare, AWS, etc.)

Cada comando tiene su propio módulo en `src/commands/` y puede tener subcomandos. El CLI detecta automáticamente la estructura del proyecto, carga la configuración desde `jamx.config.ts`, y ejecuta las acciones apropiadas utilizando los demás paquetes de JAMX (compiler, db, server, etc.).

## Componentes principales
- **src/bin/jamx.js**: Punto de entrada que inicia la CLI
- **src/index.ts**: Exporta todos los comandos y utilidades
- **src/commands/build.ts**: Compila la aplicación para producción
- **src/commands/dev.ts**: Inicia servidor de desarrollo con HMR
- **src/commands/create.ts**: Crea nuevos proyectos, módulos, componentes
- **src/commands/generate.ts**: Genera código (auth, migraciones, etc.)
- **src/commands/type-check.ts**: Verifica tipos TypeScript
- **src/commands/db/**: Comandos para migraciones y gestión de BD
- **src/ui/formatter.ts**: Formatea output para consola (colores, tablas)
- **src/utils/project-detector.ts**: Detecta estructura y configuración del proyecto
- **src/utils/scaffolding.ts**: Genera archivos desde plantillas

## Uso básico
```bash
# Crear un nuevo proyecto JAMX
jamx create app mi-proyecto

# Iniciar servidor de desarrollo
jamx dev

# Compilar para producción
jamx build

# Verificar tipos
jamx type-check

# Generar migración de base de datos
jamx db:generate-migration --name add_users_table

# Aplicar migraciones
jamx db:migrate

# Generar módulo de autenticación
jamx generate auth
```

## Ejemplos
### Crear un proyecto completo
```bash
# Interactivo: pregunta nombre, adaptador, etc.
jamx create app .

# No interactivo con opciones
jamx create app mi-app --adapter vercel --typescript strict
```

### Desarrollo con hot reload
```bash
# Iniciar dev server en puerto 3000
jamx dev --port 3000 --host 0.0.0.0

# Con recarga automática de archivos
jamx dev --watch src,packages
```

### Build con optimizaciones
```bash
# Build estándar
jamx build

# Build con minificación y sourcemaps
jamx build --minify --sourcemap

# Build solo de tipos (sin compilar)
jamx build --types-only
```

### Generar código
```bash
# Generar migración a partir de cambios en esquema
jamx db:generate-migration --name add_posts_table

# Generar módulo de autenticación completo
jamx generate auth --module AuthModule

# Generar componente UI
jamx generate component Button --path src/components
```

### Gestión de base de datos
```bash
# Ver estado de migraciones
jamx db:status

# Aplicar todas las migraciones pendientes
jamx db:migrate

# Revertir última migración
jamx db:rollback --steps 1

# Resetear base de datos (cuidado!)
jamx db:reset
```

## Flujo interno
1. **Inicialización**: El CLI carga configuración desde `jamx.config.ts` y detecta el tipo de proyecto.
2. **Parseo de argumentos**: Commander.js procesa los argumentos de la línea de comandos.
3. **Ejecución de comando**: Se ejecuta la función correspondiente al comando.
4. **Orquestación**: El comando puede usar otros paquetes (compiler, db, server) para realizar su trabajo.
5. **Formateo de salida**: `formatter.ts` pinta la salida con colores y formato.
6. **Manejo de errores**: Los errores se capturan y se muestran de forma amigable.

## API Reference (Resumen)
### Comandos principales
- `jamx create app <name>`: Crea un nuevo proyecto
- `jamx dev [options]`: Inicia servidor de desarrollo
- `jamx build [options]`: Compila para producción
- `jamx type-check`: Ejecuta TypeScript compiler
- `jamx generate <type> [options]`: Genera código (auth, component, module, etc.)
- `jamx db:*`: Comandos de base de datos

### Opciones comunes
- `--config <file>`: Ruta a archivo de configuración alternativo
- `--env <environment>`: Entorno (development, production, test)
- `--verbose`: Output detallado
- `--dry-run`: Simula sin hacer cambios
- `--force`: Sobrescribe archivos existentes

## Performance Considerations
- **Parallel builds**: El compilador puede procesar múltiples archivos en paralelo.
- **Incremental compilation**: Solo recompila archivos modificados en modo dev.
- **Caching**: Los resultados de compilación se cachean para builds subsiguientes.
- **Tree-shaking**: Elimina código no usado en el bundle final.

## Configuration
El CLI lee `jamx.config.ts` en la raíz del proyecto:

```typescript
import { defineConfig } from '@jamx-framework/core';

export default defineConfig({
  name: 'mi-app',
  version: '1.0.0',
  server: { port: 3000, host: 'localhost' },
  compiler: { sourcemap: true, minify: false },
  db: { driver: 'sqlite', url: './data.db' },
  adapters: { web: true, api: true },
});
```

## Testing
Tests en `packages/cli/tests/unit/`:

```bash
pnpm test
```

Cubre:
- Parseo de argumentos
- Generación de proyectos
- Comandos de build y dev
- Generación de migraciones
- Detección de estructura de proyecto

## Compatibility
- Compatible con Node.js 18+
- Funciona en Windows, macOS, Linux
- Requiere TypeScript 5.x
- Integra con Git para commits automáticos (opcional)

## Plugin System
El CLI soporta plugins personalizados:

```typescript
// jamx.plugin.ts
export default {
  name: 'mi-plugin',
  commands: [
    {
      name: 'mi-comando',
      description: 'Descripción',
      action: async (options) => {
        // Lógica personalizada
      },
    },
  ],
};
```

## Troubleshooting
### Error: "No JAMX project found"
Asegúrate de estar en un directorio con `jamx.config.ts` o ejecuta `jamx init`.

### Error: "Port already in use"
Usa `--port <numero>` para cambiar el puerto o detén el proceso que lo usa.

### Build lento
Habilita caching: `jamx build --cache` o configura `compiler.cache` en `jamx.config.ts`.

## CLI Integration
Este paquete es la entrada principal para desarrolladores:

- `jamx`: Comando global instalado via `npm i -g @jamx-framework/cli`
- `npx jamx`: Ejecuta sin instalar globalmente
- Integra con todos los adaptadores y paquetes de JAMX

This CLI provides a comprehensive, developer-friendly interface to the JAMX Framework, enabling rapid application development, testing, and deployment with a consistent command-line experience across all platforms and adapters.