# Generador de Scaffolds Python (ca-scaffold-py)

Una herramienta CLI diseñada para generar y modificar proyectos de Python que implementan patrones de Arquitectura Limpia.

Este proyecto proporciona un comando de línea (scaffold-py) que permite crear nuevas bases de proyecto desde cero e inyectar componentes en proyectos existentes. Administra automáticamente la creación de archivos, la inyección de dependencias y las plantillas de código para acelerar el desarrollo.

Actualmente, su funcionalidad está optimizada para generar proyectos MCP (Model Context Protocol), pero su arquitectura es extensible para otros tipos de proyectos como agentes y microservicios.

---

## 1. Características Principales

### 1.1. Generación de Proyectos

Crea una base completa de proyecto con Arquitectura Limpia: dominio, infraestructura y aplicación.

### 1.2. Modificación de Proyectos (Inyección)

Permite añadir nuevos componentes (Tools, Prompts, Resources) mediante un solo comando:

```
scaffold-py add
```

### 1.3. Inyección de Código Dinámica

Genera automáticamente el boilerplate necesario en múltiples capas:

* Modelos Pydantic
* Gateways (interfaces) y casos de uso
* Adaptadores de infraestructura
* Registro en el contenedor de inyección de dependencias
* Registro en los entrypoints (tools.py, prompts.py, resources.py)

### 1.4. CLI Intuitiva

Tres modos de creación:

* `interactive`: guiado por preguntas
* `create`: mediante argumentos
* `from-file`: usando un archivo JSON de configuración

### 1.5. Backups y Restauración

Antes de cada operación `add`, se crea un backup automático de `src/`, con posibilidad de restaurar estados anteriores.

---

## 2. Instalación (Como Paquete CLI)

Este generador está diseñado para construirse como un paquete wheel de Python e instalarse localmente.

### 2.1. Construir el Paquete

Desde la raíz del proyecto:

```bash
python -m pip install build
python -m build
```

Esto generará un archivo `.whl` en la carpeta `dist/`.

### 2.2. Instalar el Paquete

```bash
uv pip install dist/ca_scaffold_py-1.0.3-py3-none-any.whl
```

(Reemplazar la versión según corresponda.)

### 2.3. Verificar la Instalación

```bash
scaffold-py --help
```

---

## 3. Uso de la CLI

El entrypoint principal es:

```
scaffold-py
```

### 3.1. Crear un Nuevo Proyecto

#### Opción 1: Creación Directa (Argumentos)

El nombre del proyecto debe estar en snake_case y terminar en `_smcp`.

```bash
scaffold-py create "mi_proyecto_mcp_smcp" \
  --tool "search_products|Busca productos por categoría|category: str, in_stock: bool = True|List[dict]" \
  --prompt "ecommerce_assistant_prompt|Define el comportamiento del asistente para e-commerce" \
  --resource "get_shipping_info|shipping://{order_id}|Obtiene información de envío|order_id: str|Dict[str, Any]" \
  --output-dir ./
```

#### Opción 2: Desde Archivo JSON

```bash
scaffold-py from-file --config project_config.json --output-dir ./
```

Ejemplo de `project_config.json`:

```json
{
  "project_name": "e_commerce_mcp_smcp",
  "dynamic_tools": [
    {
      "name": "search_products",
      "description": "Search products by category",
      "params": "category: str, in_stock: bool = True",
      "return_type": "List[dict]"
    }
  ],
  "dynamic_prompts": [
    {
      "name": "assistant_prompt",
      "description": "System prompt for the assistant"
    }
  ],
  "dynamic_resources": [
    {
      "name": "get_policy",
      "uri": "policy://{policy_name}",
      "description": "Retrieves company policies",
      "params": "policy_name: str",
      "return_type": "Dict[str, Any]"
    }
  ]
}
```

#### Opción 3: Modo Interactivo

```bash
scaffold-py interactive --output-dir ./
```

---

## 3.2. Modificación de un Proyecto Existente (add)

El comando `add` analiza el proyecto, valida colisiones e inyecta código en todos los archivos necesarios.

### Añadir un Tool

```bash
scaffold-py add --tool "calculate_discount|Calcula descuentos|total_amount: float, tier: str = 'standard'|Dict"
```

### Añadir un Prompt

```bash
scaffold-py add --prompt "product_recommendation_prompt|Prompt para recomendar productos"
```

### Añadir un Resource

```bash
scaffold-py add --resource "get_shipping_policy|shipping://policy/{region}|Obtiene política de envío|region: str|Dict"
```

### Añadir Múltiples Componentes

```bash
scaffold-py add \
  --tool "get_order_status|Obtiene estado de orden|order_id: str|Dict" \
  --prompt "support_prompt|Prompt de atención al cliente" \
  --resource "get_faq|faq://{category}|Obtiene FAQs|category: str|List[Dict]"
```

---

## 3.3. Restauración de Backups

Cada operación `add` crea un backup automático en `.mcp_backups/` (máximo 5).

### Listar Backups

```bash
scaffold-py restore-backup
```

### Restaurar un Backup Específico

```bash
scaffold-py restore-backup backup_20251114_134500
```

---

## 4. Formato de Componentes

El formato utiliza cadenas separadas por `|`.

### 4.1. Formato de Tool

```
name|description|params|return_type
```

Ejemplo:

```
search_books|Busca libros por autor|author: str, genre: str = None|List[Dict[str, Any]]
```

### 4.2. Formato de Prompt

```
name|description
```

Ejemplo:

```
system_prompt|Prompt principal del sistema para el asistente
```

### 4.3. Formato de Resource

```
name|uri|description|params|return_type
```

Ejemplo:

```
get_policy|policy://company/{policy_name}|Obtiene política de la compañía|policy_name: str|Dict[str, Any]
```

---

## 5. Desarrollo (Para Contribuidores)

A continuación, los pasos para contribuir al desarrollo de ca-scaffold-py.

### 5.1. Crear Entorno Virtual

```bash
uv venv
```

### 5.2. Activar el Entorno

macOS/Linux:

```bash
source .venv/bin/activate
```

Windows (PowerShell):

```bash
.venv\Scripts\activate
```

### 5.3. Instalar Dependencias

```bash
uv sync
```

### 5.4. Ejecutar Pruebas

```bash
uv run pytest
```

Con cobertura:

```bash
uv run pytest --cov=project_generator --cov-config=.coveragerc tests/unit
```

