@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

# 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

# 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

# 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

# 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

# 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

# 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:

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/:

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:

// 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.