Metadata-Version: 2.4
Name: omni-friday
Version: 0.0.9
Summary: FRIDAY is a console tool developed in Python that allows you to obtain and analyze key information from projects based on Adobe Commerce.
Home-page: https://github.com/omni-pro/friday
Author: Facundo Capua
Author-email: capua.facundo@omni.pro
License: MIT License
Classifier: Programming Language :: Python :: 3.8
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.7
Requires-Dist: click_help_colors==0.9.4
Requires-Dist: PyYAML==6.0.2
Requires-Dist: boto3==1.35.83
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: pyperclip>=1.8.2
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

```

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

```

# 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](https://ddev.readthedocs.io/) (para comandos `ddev:*`)
- [Magento Cloud CLI](https://experienceleague.adobe.com/docs/commerce-cloud-service/user-guide/dev-tools/cloud-cli.html) (para comandos `cloud:*`)
- [Claude Code](https://claude.ai) (para el comando `explain`)

### Instalación

1. **Clonar el repositorio**:
   ```bash
   git clone https://github.com/omni-pro/friday-cli.git
   cd friday-cli
   ```
2. **Crear un entorno virtual (recomendado):**
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   ```
3. **Instalar las dependencias**:
   ```bash
   pip install -r requirements.txt
   ```
4. **Instalar como CLI global (opcional)**:
   ```bash
   pip install -e .
   ```

## Comandos

```bash
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.

```bash
# 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 |

```bash
# 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

```bash
# 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.

```bash
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.

```bash
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.
   ```bash
   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](LICENSE) para más detalles.

## Contacto

- **Autor**: Facundo Capua
- **Empresa**: OMNI.PRO
- **Correo**: capua.facundo@omni.pro
