# Anatomía de una Pieza USEE ## Especificación Estructural para Piezas del Protocolo **Versión 1.0** --- ## Visión General Una pieza USEE es una unidad atómica de software que: - Hace una sola cosa - Se comunica mediante texto estructurado - Funciona de forma independiente - Puede combinarse con otras piezas Este documento define la estructura obligatoria que toda pieza debe seguir para ser considerada compatible con el protocolo USEE. --- ## Estructura de Archivos Toda pieza USEE debe contener como mínimo: ``` nombre-de-pieza/ ├── PIEZA.usee # Manifiesto de la pieza (obligatorio) ├── LEEME.md # Documentación para humanos (obligatorio) ├── ENTRADA.ejemplo # Ejemplo de entrada válida (obligatorio) ├── SALIDA.ejemplo # Ejemplo de salida esperada (obligatorio) ├── ejecutar # Punto de entrada principal (obligatorio) ├── pruebas/ # Directorio de pruebas (obligatorio) │ ├── caso-basico.entrada │ ├── caso-basico.salida │ └── ... └── codigo/ # Implementación (estructura libre) └── ... ``` ### Archivos Obligatorios | Archivo | Propósito | |---------|-----------| | `PIEZA.usee` | Metadatos estructurados de la pieza | | `LEEME.md` | Documentación legible por humanos | | `ENTRADA.ejemplo` | Muestra qué recibe la pieza | | `SALIDA.ejemplo` | Muestra qué produce la pieza | | `ejecutar` | Comando o script que ejecuta la pieza | | `pruebas/` | Casos de prueba para validación automática | ### Archivos Opcionales | Archivo | Propósito | |---------|-----------| | `CAMBIOS.md` | Historial de versiones | | `CONFIG.ejemplo` | Ejemplo de configuración | | `ejecutar-json` | Adaptador JSON (Nivel 3) | | `ejecutar-http` | Adaptador HTTP (Nivel 4) | | `licencia.txt` | Términos de uso | --- ## El Archivo PIEZA.usee Este archivo contiene los metadatos de la pieza en Formato de Texto USEE. ### Campos Obligatorios ``` # Identidad nombre: login version: 1.0.0 creador: nombre@correo.com fecha_creacion: 2025-01-15 # Descripción descripcion_corta: Autentica un usuario con correo y contraseña descripcion_larga: | Recibe credenciales de usuario (correo y contraseña) y verifica si coinciden con un registro existente. Devuelve un identificador de sesión si la autenticación es exitosa, o un error descriptivo si falla. # Clasificación categoria: autenticacion etiquetas: usuario, sesion, seguridad # Capacidad accion: autenticar usuario entrada_descripcion: Credenciales del usuario salida_descripcion: Resultado de autenticación con sesión o error # Requisitos lenguaje: python version_lenguaje_minima: 3.6 dependencias_externas: ninguna dependencias_usee: ninguna # Comercial costo_por_uso: 0.001 moneda: usd modelo_cobro: por_llamada ``` ### Campos Opcionales ``` # Configuración opciones_configuracion: tiempo_expiracion, intentos_maximos, bloqueo_temporal configuracion_requerida: no # Rendimiento tiempo_respuesta_promedio_ms: 50 memoria_maxima_mb: 64 # Compatibilidad sistemas_operativos: linux, macos, windows arquitecturas: x64, arm64 # Servicios requiere_red: no requiere_almacenamiento: si base_datos_compatible: sqlite, postgres, mysql # Adaptadores disponibles adaptador_json: si adaptador_http: si puerto_http_default: 8080 # Soporte documentacion_url: https://ejemplo.com/docs/login codigo_url: https://github.com/ejemplo/usee-login soporte_contacto: soporte@ejemplo.com ``` --- ## El Archivo LEEME.md Documentación legible por humanos. Debe seguir esta estructura: ```markdown # [Nombre de la Pieza] [Una oración que describe qué hace] ## Qué Hace [Párrafo explicando el propósito en lenguaje simple] ## Qué No Hace [Lista de cosas que esta pieza NO hace, para evitar confusión] ## Uso Rápido [El ejemplo más simple posible para usar la pieza] ## Entrada [Descripción de todos los campos de entrada] ### Campos Obligatorios | Campo | Tipo | Descripción | |-------|------|-------------| | ... | ... | ... | ### Campos Opcionales | Campo | Tipo | Default | Descripción | |-------|------|---------|-------------| | ... | ... | ... | ... | ## Salida [Descripción de todos los campos de salida] ### Salida Exitosa | Campo | Tipo | Descripción | |-------|------|-------------| | ... | ... | ... | ### Salida con Error | Campo | Tipo | Descripción | |-------|------|-------------| | ... | ... | ... | ## Ejemplos ### [Nombre del caso de uso] [Ejemplo completo con entrada y salida] ## Configuración [Opciones de configuración disponibles] ## Errores Comunes | Código | Significado | Solución | |--------|-------------|----------| | ... | ... | ... | ## Dependencias [Lista de dependencias y por qué son necesarias] ## Historial de Versiones [Resumen de cambios por versión] ``` --- ## Ejemplos de Entrada y Salida ### ENTRADA.ejemplo Debe mostrar el caso de uso más común: ``` # Ejemplo de entrada para la pieza Login # Este es el caso más básico de uso usuario: ejemplo@correo.com clave: mi_contraseña_segura ``` ### SALIDA.ejemplo Debe mostrar la salida correspondiente a la entrada de ejemplo: ``` # Salida exitosa para el ejemplo de entrada estado: ok sesion_id: usr_abc123xyz789 expira: 2025-01-16T10:30:00Z usuario_id: usr_001 ``` --- ## El Archivo Ejecutar El punto de entrada principal de la pieza. ### Requisitos 1. Debe ser ejecutable directamente desde terminal 2. Debe leer de stdin 3. Debe escribir resultados a stdout 4. Debe escribir errores a stderr 5. Debe retornar código de salida 0 si éxito, distinto de 0 si error ### Comportamiento Estándar ```bash # Uso básico (stdin/stdout) echo "usuario: juan@ejemplo.com clave: secreto123" | ./ejecutar # Con archivo de entrada ./ejecutar < entrada.txt # Con archivo de salida ./ejecutar < entrada.txt > salida.txt # Ver ayuda ./ejecutar --ayuda # Ver versión ./ejecutar --version ``` ### Argumentos Obligatorios | Argumento | Descripción | |-----------|-------------| | `--ayuda` | Muestra instrucciones de uso | | `--version` | Muestra la versión de la pieza | ### Argumentos Opcionales Estándar | Argumento | Descripción | |-----------|-------------| | `--config [archivo]` | Usa archivo de configuración | | `--json` | Entrada/salida en formato JSON | | `--silencioso` | Solo muestra errores | | `--verbose` | Muestra información de debug | --- ## Directorio de Pruebas Las pruebas son obligatorias y deben ser automáticamente verificables. ### Estructura ``` pruebas/ ├── caso-basico.entrada # Entrada del caso ├── caso-basico.salida # Salida esperada ├── caso-basico.descripcion # (Opcional) Descripción del caso ├── error-clave-vacia.entrada ├── error-clave-vacia.salida ├── error-clave-vacia.codigo # Código de salida esperado (ej: 1) └── ... ``` ### Convención de Nombres - `caso-[nombre].entrada` - Datos de entrada - `caso-[nombre].salida` - Salida esperada - `error-[nombre].entrada` - Caso que debe producir error - `error-[nombre].salida` - Mensaje de error esperado - `error-[nombre].codigo` - Código de salida esperado ### Casos Obligatorios Toda pieza debe incluir al menos: 1. **caso-basico**: El uso más simple y común 2. **caso-completo**: Uso con todos los campos opcionales 3. **error-entrada-vacia**: Comportamiento sin entrada 4. **error-campo-faltante**: Comportamiento sin campos obligatorios ### Verificación Automática Las pruebas se ejecutan con: ```bash # Pseudocódigo del verificador para cada archivo *.entrada en pruebas/: nombre = extraer_nombre(archivo) entrada = leer(nombre.entrada) salida_esperada = leer(nombre.salida) codigo_esperado = leer(nombre.codigo) o 0 salida_real, codigo_real = ejecutar(pieza, entrada) verificar(salida_real == salida_esperada) verificar(codigo_real == codigo_esperado) ``` --- ## Códigos de Salida Las piezas USEE deben usar códigos de salida consistentes: | Código | Significado | |--------|-------------| | 0 | Éxito - la operación se completó correctamente | | 1 | Error general - algo salió mal | | 2 | Error de entrada - los datos de entrada son inválidos | | 3 | Error de configuración - la configuración es inválida | | 4 | Error de dependencia - una dependencia no está disponible | | 5 | Error de conexión - no se pudo conectar a un servicio requerido | | 10-99 | Errores específicos de la pieza (documentar en LEEME.md) | --- ## Formato de Errores Cuando una pieza falla, debe producir salida estructurada en stderr: ``` estado: error codigo: identificador_del_error mensaje: Descripción legible del error detalle: Información adicional para debugging sugerencia: Qué puede hacer el usuario para resolverlo ``` ### Campos de Error | Campo | Obligatorio | Descripción | |-------|-------------|-------------| | `estado` | Sí | Siempre "error" | | `codigo` | Sí | Identificador único del error (snake_case) | | `mensaje` | Sí | Descripción corta legible por humanos | | `detalle` | No | Información técnica adicional | | `sugerencia` | No | Acción recomendada para el usuario | ### Ejemplo de Error ``` estado: error codigo: credenciales_invalidas mensaje: El correo o la contraseña son incorrectos detalle: No se encontró coincidencia para el correo proporcionado sugerencia: Verifique que el correo esté escrito correctamente ``` --- ## Configuración Las piezas pueden aceptar configuración de múltiples formas, en orden de prioridad: ### 1. Argumentos de línea de comandos (máxima prioridad) ```bash ./ejecutar --tiempo-expiracion=3600 ``` ### 2. Variables de entorno ```bash USEE_LOGIN_TIEMPO_EXPIRACION=3600 ./ejecutar ``` Convención: `USEE_[NOMBRE_PIEZA]_[OPCION]` ### 3. Archivo de configuración ```bash ./ejecutar --config=mi-config.usee ``` Contenido del archivo: ``` tiempo_expiracion: 3600 intentos_maximos: 5 bloqueo_temporal: si ``` ### 4. Valores por defecto (mínima prioridad) Definidos en el código de la pieza. ### Regla de Configuración USEE > Una pieza debe funcionar sin ninguna configuración para su caso de uso más común. La configuración existe para personalizar, no para habilitar. --- ## Versionado Las piezas USEE siguen versionado semántico adaptado: ``` MAYOR.MENOR.PARCHE Ejemplo: 1.4.2 ``` ### Cuándo Incrementar | Componente | Cuándo incrementar | |------------|-------------------| | **MAYOR** | Nunca (una pieza USEE no rompe compatibilidad) | | **MENOR** | Nuevos campos opcionales de entrada/salida, nuevas funcionalidades | | **PARCHE** | Corrección de errores, mejoras de rendimiento | ### La Regla de Oro del Versionado USEE > Si un cambio rompería una entrada que funcionaba antes, no es una actualización. Es una pieza nueva. ### Ejemplo - `login 1.0.0` - Versión inicial - `login 1.1.0` - Agrega campo opcional `recordar_sesion` - `login 1.1.1` - Corrige error en validación de correo - `login 1.2.0` - Agrega campo de salida `ultimo_acceso` - `login2 1.0.0` - Nueva pieza que cambia el formato de sesión (incompatible con login 1.x) --- ## Adaptadores ### Adaptador JSON (Nivel 3) Archivo: `ejecutar-json` Traduce entrada/salida entre JSON y Formato de Texto USEE. **Entrada JSON:** ```json { "usuario": "juan@ejemplo.com", "clave": "secreto123" } ``` **Equivalente FTU:** ``` usuario: juan@ejemplo.com clave: secreto123 ``` ### Adaptador HTTP (Nivel 4) Archivo: `ejecutar-http` Expone la pieza como servicio HTTP. ```bash ./ejecutar-http --puerto=8080 ``` **Endpoints estándar:** | Método | Ruta | Descripción | |--------|------|-------------| | POST | `/` | Ejecuta la pieza | | GET | `/salud` | Verifica que la pieza está funcionando | | GET | `/version` | Retorna versión de la pieza | | GET | `/ayuda` | Retorna documentación | **Ejemplo de uso:** ```bash curl -X POST http://localhost:8080/ \ -H "Content-Type: text/plain" \ -d "usuario: juan@ejemplo.com clave: secreto123" ``` --- ## Lista de Verificación para Publicar Antes de publicar una pieza USEE, verificar: ### Estructura - [ ] Existe `PIEZA.usee` con todos los campos obligatorios - [ ] Existe `LEEME.md` con la estructura requerida - [ ] Existe `ENTRADA.ejemplo` con un caso válido - [ ] Existe `SALIDA.ejemplo` correspondiente - [ ] Existe `ejecutar` y es ejecutable - [ ] Existe directorio `pruebas/` con casos obligatorios ### Funcionalidad - [ ] `./ejecutar --ayuda` muestra instrucciones - [ ] `./ejecutar --version` muestra versión - [ ] Todas las pruebas pasan - [ ] La pieza funciona sin configuración ### Documentación - [ ] `LEEME.md` explica qué hace Y qué no hace - [ ] Todos los campos de entrada están documentados - [ ] Todos los campos de salida están documentados - [ ] Todos los errores posibles están documentados ### Calidad - [ ] La descripción cabe en una oración - [ ] La pieza hace una sola cosa - [ ] No hay dependencias innecesarias - [ ] Los errores son descriptivos y útiles --- ## Ejemplo Completo: Pieza "Login" ### Estructura de Archivos ``` login/ ├── PIEZA.usee ├── LEEME.md ├── ENTRADA.ejemplo ├── SALIDA.ejemplo ├── ejecutar ├── ejecutar-json ├── ejecutar-http ├── pruebas/ │ ├── caso-basico.entrada │ ├── caso-basico.salida │ ├── caso-recordar.entrada │ ├── caso-recordar.salida │ ├── error-entrada-vacia.entrada │ ├── error-entrada-vacia.salida │ ├── error-entrada-vacia.codigo │ ├── error-campo-faltante.entrada │ ├── error-campo-faltante.salida │ ├── error-campo-faltante.codigo │ ├── error-credenciales.entrada │ ├── error-credenciales.salida │ └── error-credenciales.codigo └── codigo/ ├── main.py ├── validar.py └── sesion.py ``` ### PIEZA.usee ``` nombre: login version: 1.0.0 creador: equipo@entio.com fecha_creacion: 2025-01-15 descripcion_corta: Autentica un usuario con correo y contraseña descripcion_larga: | Recibe credenciales de usuario (correo y contraseña) y verifica si coinciden con un registro existente. Devuelve un identificador de sesión si la autenticación es exitosa. categoria: autenticacion etiquetas: usuario, sesion, seguridad accion: autenticar usuario entrada_descripcion: Correo y contraseña del usuario salida_descripcion: Sesión activa o error de autenticación lenguaje: python version_lenguaje_minima: 3.6 dependencias_externas: ninguna dependencias_usee: ninguna costo_por_uso: 0.001 moneda: usd modelo_cobro: por_llamada opciones_configuracion: tiempo_expiracion, intentos_maximos configuracion_requerida: no tiempo_respuesta_promedio_ms: 45 adaptador_json: si adaptador_http: si ``` ### ENTRADA.ejemplo ``` # Autenticación básica usuario: maria@ejemplo.com clave: contraseña_segura_123 ``` ### SALIDA.ejemplo ``` estado: ok sesion_id: ses_7f8a9b2c3d4e5f6g expira: 2025-01-16T15:30:00Z usuario_id: usr_maria_001 ``` ### Caso de prueba: caso-basico.entrada ``` usuario: test@ejemplo.com clave: test123 ``` ### Caso de prueba: caso-basico.salida ``` estado: ok sesion_id: ses_test_session expira: 2025-01-16T00:00:00Z usuario_id: usr_test_001 ``` ### Caso de prueba: error-credenciales.entrada ``` usuario: test@ejemplo.com clave: clave_incorrecta ``` ### Caso de prueba: error-credenciales.salida ``` estado: error codigo: credenciales_invalidas mensaje: El correo o la contraseña son incorrectos sugerencia: Verifique sus credenciales e intente nuevamente ``` ### Caso de prueba: error-credenciales.codigo ``` 1 ``` --- ## Resumen Una pieza USEE es predecible porque su estructura es predecible. Todo creador sabe qué debe incluir. Todo usuario sabe qué esperar. Todo sistema sabe cómo verificar. Esta uniformidad es lo que permite que piezas creadas por diferentes personas, en diferentes momentos, en diferentes lenguajes, funcionen juntas como si fueran creadas por la misma mano. --- **USEE**: Estructura que libera, no que restringe.