omni-friday 0.0.9

FRIDAY is a console tool developed in Python that allows you to obtain and analyze key information from projects based on Adobe Commerce.

███████ ██████  ██ ██████   █████  ██    ██ 
██      ██   ██ ██ ██   ██ ██   ██  ██  ██  
█████   ██████  ██ ██   ██ ███████   ████   
██      ██   ██ ██ ██   ██ ██   ██    ██    
██      ██   ██ ██ ██████  ██   ██    ██    

F.R.I.D.A.Y. - Adobe Commerce Project Tool

FRIDAY es una herramienta de consola desarrollada en Python que permite obtener, analizar y documentar información clave de proyectos basados en Adobe Commerce (Magento). Incluye generación de documentación asistida por IA, gestión de logs en la nube, diagnóstico de entornos locales y troubleshooting de órdenes.

Características

• Documentación con IA: Extrae la lógica de negocio de módulos custom y genera documentación lista para equipos de soporte, usando Claude como asistente.
• Análisis de configuración: Extrae y muestra configuraciones clave del proyecto.
• Logs en la nube: Descarga, busca y monitorea logs de Magento Commerce Cloud en paralelo.
• Diagnóstico local: Verifica el estado del entorno ddev y ejecuta resets automatizados.
• Troubleshooting: Reconstruye timelines de órdenes a partir de logs locales.
• Exploración con IA: Carga contexto de un módulo y lanza Claude Code para exploración asistida.

Requisitos

• Python 3.8 o superior
• Acceso al proyecto Adobe Commerce
• ddev (para comandos ddev:*)
• Magento Cloud CLI (para comandos cloud:*)
• Claude Code (para el comando explain)

Instalación

1. Clonar el repositorio:

   git clone https://github.com/omni-pro/friday-cli.git
   cd friday-cli
   

2. Crear un entorno virtual (recomendado):

   python3 -m venv venv
   source venv/bin/activate
   

3. Instalar las dependencias:

   pip install -r requirements.txt
   

4. Instalar como CLI global (opcional):

   pip install -e .
   

Comandos

friday --help

📋 Proyecto

Comando	Descripción
friday project:info	Muestra información general del proyecto y envía metadata a SQS

📖 Documentación (docs:*)

Generación de documentación de módulos Magento asistida por IA.

Comando	Descripción
friday docs:extract <module_path>	Extrae archivos de lógica de negocio de un módulo y copia el resultado al clipboard
friday docs:update	Detecta módulos modificados en el último commit y extrae su contexto

docs:extract analiza un módulo Magento y extrae únicamente los archivos relevantes para entender la lógica de negocio:

• Siempre extrae: registration.php, module.xml, di.xml (global y por área), events.xml, firmas de clases en Observer/ y Plugin/
• Extrae si existen: webapi.xml, schema.graphqls, system.xml, crontab.xml, archivos de colas (communication, queue_topology, queue_consumer), db_schema.xml, data patches (solo nombre de clase), interfaces y constructores de modelos
• Nunca extrae: view/, Test/, i18n/, implementaciones completas de PHP

Cada extracción incluye un score de complejidad (T1/T2/T3) basado en la cantidad de observers, plugins, dependencias externas, consumers de colas, endpoints de API, cron jobs, data patches y tablas de BD.

# Extraer un módulo específico (resultado copiado al clipboard)
friday docs:extract app/code/Vendor/ModuleName

# Detectar y extraer módulos cambiados en el último commit
friday docs:update

El output se diseñó para ser pegado directamente en claude.ai junto con el prompt template incluido en app/templates/module_doc_prompt.md.

☁️ Cloud Logs (cloud:*)

Wrappers para Magento Commerce Cloud CLI con ejecución paralela entre environments.

Comando	Descripción
friday cloud:logs:fetch	Descarga logs de los 3 environments simultáneamente
friday cloud:logs:grep <string>	Busca un string en paralelo en integration/staging/production
friday cloud:logs:tail --env=ENV	Tail de logs en tiempo real de un environment específico

# Descargar logs de todos los environments
friday cloud:logs:fetch

# Buscar errores de pago en todos los environments
friday cloud:logs:grep "payment failed"

# Buscar solo en producción
friday cloud:logs:grep "payment failed" --env=production

# Tail de logs en staging
friday cloud:logs:tail --env=staging

🔧 ddev (ddev:*)

Gestión del entorno local de desarrollo.

Comando	Descripción
friday ddev:reset	Reset completo del entorno local en la secuencia correcta
friday ddev:doctor	Diagnóstico del entorno: servicios, indexers, caché, cron, RabbitMQ

ddev:reset ejecuta en orden:

1. ddev stop → ddev start
2. setup:upgrade → di:compile → static-content:deploy
3. cache:flush → indexer:reindex

Si algún paso falla, se detiene y muestra el error.

ddev:doctor verifica:

• ✓/✗ Servicios ddev corriendo
• ✓/✗ Indexers válidos
• ✓/✗ Caché habilitada
• ✓/✗ Cron ejecutándose
• ✓/✗ Conexión a RabbitMQ

# Reset completo del entorno
friday ddev:reset

# Diagnóstico rápido
friday ddev:doctor

🔍 Troubleshooting

Comando	Descripción
friday troubleshoot:order <increment_id>	Reconstruye un timeline de una orden desde los logs locales

Busca el increment ID en todos los archivos de log (system.log, exception.log, payment.log, debug.log y cualquier log custom en var/log/), extrae timestamps y presenta una línea de tiempo ordenada cronológicamente.

friday troubleshoot:order 000000123

🤖 Exploración con IA

Comando	Descripción
friday explain <module_name>	Carga documentación del módulo y lanza Claude Code con contexto

Carga el archivo de documentación del módulo (docs/modules/Vendor_ModuleName.md) y cualquier skill file relacionado (docs/skills/), genera un archivo de contexto en .claude/contexts/, y lanza Claude Code con ese contexto pre-cargado.

friday explain Vendor_ModuleName

🎯 Claude Code Slash Command

El proyecto incluye un slash command para Claude Code en .claude/commands/gen-docs.md:

/project:gen-docs                      # Genera docs para módulos cambiados en el último commit
/project:gen-docs Vendor_ModuleName    # Genera doc para un módulo específico
/project:gen-docs app/code/Vendor/Mod  # Genera doc desde un path específico

El slash command es diff-aware: ignora módulos donde solo cambiaron archivos de view/, Test/ o i18n/.

Estructura de Documentación

docs/
├── modules/                    # Documentación generada por módulo
│   └── Vendor_ModuleName.md    # Un archivo por módulo
└── skills/                     # Runbooks para procesos de negocio complejos
    └── payment_azul_rd.md      # Ejemplo: gateway de pago Azul RD

Templates

Archivo	Propósito
app/templates/module_doc_prompt.md	Prompt reutilizable para generar docs con claude.ai
app/templates/skill_template.md	Plantilla para skill files (decision trees, symptom maps)

Skill Files

Los skills son documentos verticales para procesos de negocio complejos que cruzan múltiples módulos. Están optimizados para consumo por IA, no para lectura humana:

• Decision trees en formato ASCII para diagnóstico
• Mapas Symptom → Cause → Action en tabla
• Data flows con boundaries de sistema marcados
• Referencia de configuración con impacto de valores incorrectos
• Modos de fallo conocidos con pasos de recuperación

Configuración

El proyecto usa project.settings.yml para configuración general y variables de entorno (.env) para credenciales AWS:

AWS_REGION=us-east-1
AWS_SQS_URL=https://sqs.us-east-1.amazonaws.com/...
AWS_SQS_MESSAGE_GROUP_ID=friday

Contribución

¡Las contribuciones son bienvenidas! Para colaborar:

1. Realiza un fork del repositorio.
2. Crea una rama con la nueva funcionalidad o corrección de errores.

   git checkout -b feature/nueva-funcionalidad
   

3. Envía un Pull Request.

Licencia

Este proyecto está licenciado bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.

Contacto

• Autor: Facundo Capua
• Empresa: OMNI.PRO
• Correo: [e-mail]