ZCLI

Herramienta de línea de comandos con utilidades para la creación, desarrollo y mantenimiento de proyectos con el Framework Zorraquino.

🚀 Instalación

npm install -g @zorraquino/zcli

Requisitos:

• Bun >= 1.0.0 (se instalará automáticamente si no está presente)
• Node.js >= 22.13
• Git

📖 Uso

zcli [command] [options]

Para ver la lista completa de comandos:

zcli --help

🎯 Comandos Principales

Todos los comandos detectan el framework del proyecto en el directorio actual (server/main.php + vite.config.ts → z-cms; src/index.php + webpack.config.js → cms-zorraquino) y usan sus herramientas: Vite/Bun/oxlint/Prettier/Vitest en z-cms, webpack/npm en cms-zorraquino (test, lint, format, check, create-block y create-template solo existen en z-cms).

Creación de Proyectos

• create-app: Clonar e inicializar un nuevo proyecto. Pregunta qué framework/front usar (o --framework):

  • z-cms — front en React (Vite, Tailwind 4) + API JSON. Instala Composer y Bun, crea app/, config/, .env/.htaccess, build inicial.
  • cms-zorraquino — front en Smarty + API headless. Instala Composer y npm, .env, carpetas/permisos y overrides/ (bin/service.sh), build con webpack.

  En ambos casos termina con el wizard opcional de bases de datos y zcli doctor.

  zcli create-app
  zcli create-app --framework cms-zorraquino

• init-app: Inicializar un directorio que ya contiene el código del framework (se detecta automáticamente; --framework lo fuerza)

  zcli init-app

• db:setup: Crear las bases de datos del proyecto (principal y logs), inicializarlas y guardar la conexión en .env. En z-cms la inicialización son las migraciones de Phinx más los datos iniciales (idempotente); en cms-zorraquino, la importación de los dumps de database/. Interactivo, o sin preguntas con opciones:

  zcli db:setup
  zcli db:setup --yes --user root --password '' --database mi_web --logs-database mi_web_logs
  zcli db:setup --demo               # además carga una web de muestra (home, sección, blog, menú e imágenes)

  Requiere el cliente mysql/mariadb (se busca en el PATH y en rutas de MAMP/XAMPP/Homebrew; o indícalo con --mysql-bin). Si no está disponible, muestra los comandos para hacerlo a mano. Sin Phinx (composer install pendiente) importa database/schema/*.sql; los dumps no se sobrescriben en una base con tablas salvo con --force

• ext:add <slug>, ext:update <slug>, ext:list: Extensiones de z-cms (componentes de contenido y, más adelante, módulos) desde el catálogo z-cms-extensions: se copian a extensions/<slug>/ del proyecto, se registran como componente de página, se añaden a los tipos de bloque que indiques, se aplican sus migraciones y se añaden vacías al .env las claves que declare la extensión (env del manifiesto, p. ej. MAILCHIMP_*, HUBSPOT_*, SALESFORCE_* de forms; zcli doctor avisa de las que falten según las integraciones configuradas en config/forms.json). Solo z-cms

  zcli ext:list
  zcli ext:add news --blocks hero,text
  zcli ext:add news --from ../z-cms-extensions   # catálogo local (desarrollo)
  zcli ext:update news

• front:set <slug>, front:list (y create-app --front react|vue|smarty): Fronts alternativos de z-cms desde el catálogo z-cms-fronts: sustituyen app/ y vite.config.ts (conservando app/build), aplican sus dependencias al package.json (retirando las de React), reinstalan y compilan. react es el front incluido en z-cms. Solo z-cms

  zcli create-app --front vue
  zcli front:list
  zcli front:set vue                 # exige --force si app/src/components/blocks tiene bloques propios

• theme:export <slug>, theme:set <origen>, theme:info (y create-app --theme <origen>): Themes de z-cms, creados a partir de webs en desarrollo. theme:export genera en ../z-cms-theme-<slug> (o --to) un theme con el front del proyecto (app/, public/, vite.config.ts, tsconfig.json), la config de bloques y textos (config/*.json, config/langs/), las extensiones instaladas como requisito, las dependencias propias, una guía del sistema de diseño para personas y asistentes de IA (app/THEME.md + theme.blocks.json: bloques y variantes con qué datos pintan, componentes y parámetros, formularios, tokens y recetas de composición sacadas de la web de origen) y, con --with-content, el contenido (niveles, páginas, bloques, menús e imágenes) como seeder ContenidoTheme. theme:set lo instala en un proyecto: front base del catálogo si hace falta, código y config del theme, extensiones que requiera, dependencias, migraciones, contenido (si la base está vacía) y build. Un theme es de un front concreto (theme.json → front). Solo z-cms

  zcli theme:export corporativo --name "Corporativo" --with-content   # desde la web en desarrollo
  zcli theme:set https://github.com/Zorraquino/z-cms-theme-corporativo.git
  zcli theme:set ../z-cms-theme-corporativo --no-content                # directorio local, sin contenido
  zcli create-app --theme ../z-cms-theme-corporativo

• db:migrate: Aplicar las migraciones pendientes a las dos bases de datos (tras actualizar el proyecto o instalar una extensión) y cargar los datos iniciales si la principal está vacía. Con --status solo informa (código 1 si hay pendientes). Solo z-cms

  zcli db:migrate
  zcli db:migrate --status

• doctor: Comprobar que todo está conectado: PHP ≥ 8.2 con mysqli, Composer, Bun, vendor/ y node_modules/ instalados, .env con las claves DB_*, conexión real a las dos bases de datos (con mysqli, como la app), estado de las migraciones y build. Sale con código 1 si hay problemas; se ejecuta también como resumen al final de create-app/init-app

  zcli doctor

• create-block: Crear un nuevo bloque/componente React

  zcli create-block

• create-template: Crear una nueva plantilla/layout

  zcli create-template

Desarrollo

• dev: Iniciar servidor de desarrollo Vite

  zcli dev

• dev:host: Iniciar servidores de desarrollo (PHP + Vite) con acceso desde red local. El servidor PHP usa el router de zcli, que emula las reglas del .htaccess y activa el modo desarrollo (assets desde Vite con HMR)

  zcli dev:host

• serve: Servir el build de producción con PHP (sin Vite): la plantilla carga los assets compilados de app/build. Requiere haber ejecutado zcli build

  zcli build && zcli serve --port 8000

Compilación

• build: Compilar proyecto para producción

  zcli build

• build:dev: Compilar proyecto en modo desarrollo

  zcli build:dev

• watch: Compilar y observar cambios (producción)

  zcli watch

• watch:dev: Compilar y observar cambios (desarrollo)

  zcli watch:dev

Calidad de Código

• test: Ejecutar tests con Vitest

  zcli test

• lint: Ejecutar linter en el proyecto

  zcli lint

• format: Formatear código con Prettier

  zcli format

• check: Verificar formateo sin modificar archivos

  zcli check

• react-scan: Analizar performance de aplicación React

  zcli react-scan

Mantenimiento

• backup: Crear backup en ./backup/ con los medios (imágenes, documentos, vídeos), los adjuntos de formularios (server/storage/formularios) y el volcado de las dos bases de datos. Se restaura con zcli restore <fichero>

  zcli backup

• cleanup: Limpiar archivos temporales y configurar permisos

  zcli cleanup

• update: Actualizar el core del proyecto a la última versión publicada de z-cms (tags vX.Y.Z) sin tocar lo que es del proyecto (app/, config/, extensions/, .env…). Si el proyecto es un repositorio git (lo es por defecto: create-app conserva el historial del core como remoto zcms), hace un merge a tres bandas que respeta tus cambios y señala conflictos; si no, sustituye solo las rutas del core (core.json) conservando los ficheros que hayas modificado. Después: composer install, migraciones, dependencias del core en package.json, instalación JS y build

  zcli update --check        # instalado vs último publicado
  zcli update                # última versión
  zcli update --to v4.1.0    # una versión concreta
  zcli update --finish       # tras resolver un merge con conflictos a mano
  zcli update --force        # sin git: sobrescribir los ficheros del core modificados

• upgrade: Actualizar ZCLI a la última versión

  zcli upgrade

📚 Documentación Completa

Para documentación detallada, consulta:

• Documentación de Usuario y Desarrollador: Índice completo de documentación
• Guía del Desarrollador: Cómo contribuir y extender ZCLI
• Arquitectura: Detalles técnicos de la arquitectura
• Reglas de Contexto para AI: Contexto para Cursor AI y asistentes similares

🔧 Workflow Típico

Crear un Nuevo Proyecto

# 1. Crear proyecto (instala dependencias, ofrece crear las bases de datos y termina con zcli doctor)
zcli create-app

# 2. Navegar al directorio
cd mi-proyecto

# 3. Iniciar desarrollo
zcli dev:host

# 4. En otra terminal, observar cambios
zcli watch:dev

Añadir un Nuevo Bloque

# 1. Crear bloque
zcli create-block

# 2. El proyecto se compila automáticamente

# 3. El bloque ya está disponible en el CMS

Antes de Deploy

# 1. Formatear código
zcli format

# 2. Verificar linting
zcli lint

# 3. Ejecutar tests
zcli test

# 4. Compilar para producción
zcli build

# 5. Verificar build localmente
zcli serve

🐛 Troubleshooting

Bun no está instalado

El CLI lo detecta y muestra el comando oficial de instalación (no lo ejecuta por ti):

curl -fsSL https://bun.sh/install | bash

Puerto ya en uso

# Encontrar proceso usando el puerto
lsof -i :5173

# Matar proceso
kill -9 <PID>

Build falla

# Ejecutar Vite directamente para ver error completo
bunx --bun vite build --mode=development

Para más soluciones, consulta la Guía de Troubleshooting

🤝 Contribuir

Las contribuciones son bienvenidas! Por favor:

1. Fork del repositorio
2. Crea una rama para tu feature: git checkout -b feature/mi-feature
3. Commit tus cambios: git commit -m "feat: descripción"
4. Push a la rama: git push origin feature/mi-feature
5. Crea un Pull Request

Ver la Guía del Desarrollador para más detalles.

📦 Releases

Para publicar una nueva versión:

# Asegúrate de estar en master y tener todos los cambios commiteados
npm run release [patch|minor|major]

El script automáticamente:

• Incrementa la versión en package.json
• Actualiza el CHANGELOG.md con los commits desde el último release
• Crea un tag de git
• Hace push a GitHub
• GitHub Actions se encarga de publicar en npm y crear el release

📜 Licencia

MIT © Zorraquino Comunicación SLU

🔗 Enlaces

• GitHub: https://github.com/Zorraquino/zcli
• npm: https://www.npmjs.com/package/@zorraquino/zcli
• Framework Zorraquino: https://github.com/Zorraquino/z-cms (si está disponible) o https://gitlab.com/zorraquino-dev/cms/z-cms
• Documentación: ./docs/README.md

Última actualización: Noviembre 2025