@icarusmx/creta 1.4.18 → 1.5.1

package/README.md

@@ -0,0 +1,395 @@
+# 🏛️ Creta CLI
+
+**Creta** es el compañero CLI que evoluciona contigo - desde tus primeros comandos hasta tu carrera profesional.
+
+> "Salgamos de este laberinto" 🏛️
+
+## 🌱 Un CLI que crece con el desarrollador
+
+Creta no es una herramienta que "terminas" y dejas atrás. Se adapta a tu nivel:
+
+```
+🎓 Aprendiz          →  💻 Desarrollador      →  🏗️ Constructor
+Learn interactively     Quick references        Professional workflow
+creta sintaxis          creta ls               creta requirement
+```
+
+**Versión actual:** 1.4.16 (Phase 1 - Aprendiz)
+**Próxima:** 1.5.0 (Phase 2 - Desarrollador)
+
+---
+
+## Instalación
+
+```bash
+# Instalación global (recomendado)
+npm install -g @icarusmx/creta
+
+# Uso directo con npx (sin instalar)
+npx @icarusmx/creta
+```
+
+---
+
+## 🎓 Phase 1: Aprendiz (LIVE)
+
+**Para estudiantes aprendiendo desde cero**
+
+### El Flujo de Aprendizaje
+
+Creta es parte de un ecosistema educativo que combina **Discord**, **CLI** y **videos**:
+
+```
+Discord Server
+    ↓ Aprende tus primeros comandos
+    ↓ Instala Node.js
+    ↓
+npx @icarusmx/creta
+    ↓ Practica comandos interactivos
+    ↓ Completa lecciones
+    ↓ Obtén un hash especial
+    ↓
+Discord: /redeem <hash>
+    ↓ Recibe link de YouTube oculto
+    ↓
+Videos educativos
+    ↓ Aprende conceptos
+    ↓ Regresa al CLI para practicar
+    ↓
+🔁 Ciclo continuo de aprendizaje
+```
+
+### Comandos de Aprendizaje
+
+```bash
+# Menú principal (empieza aquí)
+creta
+
+# Lecciones de sintaxis con práctica interactiva
+creta sintaxis
+
+# Explorar los 7 enunciados fundamentales (OOP)
+creta enunciados
+
+# Ver proyectos disponibles
+creta proyectos
+```
+
+### 💻 Sistema de Práctica Interactiva
+
+**Ejecuta comandos reales en sandboxes aislados:**
+
+```bash
+creta sintaxis
+# → Selecciona "Primeros comandos"
+# → Ejecuta ls, mkdir, cd en entorno seguro
+# → Validación estricta de sintaxis
+# → Los cambios persisten entre pasos
+```
+
+**Características:**
+- 🔒 **Seguro:** Todo ocurre en `/tmp/`, nunca toca tus archivos reales
+- ✅ **Validación estricta:** Aprende la sintaxis exacta, sin atajos
+- 🔁 **Estado persistente:** Los cambios se mantienen entre pasos
+- 🧹 **Auto-limpieza:** Sandboxes se limpian automáticamente
+
+### 📚 Curriculum Completo
+
+**4 Lecciones de Sintaxis (con práctica interactiva):**
+1. **Primeros comandos** - `ls`, `mkdir`, `cd` en sandbox real
+2. **Git** - Control de versiones con definiciones rigurosas
+3. **Combina comandos** - Standard streams (stdin/stdout/stderr) + piping
+4. **Escribe scripts** - Automatización desde `echo` hasta scripts de deployment
+
+**7 Enunciados Fundamentales (Conceptos OOP):**
+1. Sistema - Descomposición de bibliotecas digitales
+2. Solicitudes - Chat system object requests
+3. Única forma - Cajas fuertes digitales
+4. Firmas - Calculadora financiera
+5. Conjunto - Music player interfaces
+6. Énfasis - Banking system design
+7. Objeto - Datos + procedimientos que operan sobre datos
+
+### 🚀 Generación de Portafolios
+
+```bash
+# Crear portafolio personal (reto completo con instrucciones)
+creta portafolio
+
+# Nivel 1: Navbar completado
+creta portafolio-1
+
+# Nivel 2: Navbar + Hero completados
+creta portafolio-2
+
+# Nivel 3: Solución completa
+creta portafolio-3
+```
+
+**Stack del portafolio:** SvelteKit 5 + Tailwind CSS 4
+
+---
+
+## 💻 Phase 2: Desarrollador (COMING SOON - v1.5.0)
+
+**Para junior devs que necesitan referencias rápidas**
+
+### Reemplaza `man` con ayuda en español
+
+```bash
+# En lugar de: man ls
+creta ls
+# → Quick reference en español
+# → Solo lo esencial (no 500 líneas)
+# → Ejemplos prácticos reales
+# → Link a lecciones relacionadas
+
+# Funciona con cualquier comando
+creta git status
+creta mkdir
+creta wc
+creta grep
+```
+
+### Por qué mejor que `man`:
+
+- 🇪🇸 **Documentación nativa en español** - Sin traducción mental
+- 🎯 **Solo lo esencial** - No más walls of text de 500 líneas
+- 💡 **Ejemplos prácticos** - Casos reales de tu contexto de estudiante
+- 🔗 **Conectado a tu aprendizaje** - Links a lecciones si necesitas profundizar
+- 🚀 **Sin context-switching** - No Google, no browser, solo terminal
+
+**Status:** 🚧 En desarrollo - Ships en v1.5.0
+
+---
+
+## 🏗️ Phase 3: Constructor (VISION - v2.0.0+)
+
+**Para profesionales trabajando en proyectos de Icarus**
+
+### Asistente personalizado de workflow
+
+```bash
+# Autenticación (desbloquea features personalizados)
+creta login
+
+# Ver tu ticket actual (Jira-like en terminal)
+creta requirement
+# →
+# 📋 Current Ticket: CRETA-142
+# 🏷️  Add dark mode toggle to dashboard
+# 👤 Assigned to: Guillermo
+# ⏱️  Due: 2 days
+# 📝 Description: Implement dark mode...
+# 💡 Related docs: creta tailwind, creta svelte
+
+# Revisar progreso y asignaciones
+creta status
+
+# Enviar trabajo completado
+creta submit
+```
+
+**Features:**
+- 🔐 Authentication con cuenta de Icarus
+- 📋 Ticket management (agile workflow)
+- 👥 Team workspace sync
+- 📊 Progress tracking personalizado
+
+**Status:** 🔮 Vision - Requiere infraestructura de autenticación
+
+---
+
+## 🛠️ Utilidades Actuales
+
+```bash
+# Sesión interactiva de programación con Claude
+creta code
+
+# Personalizar terminal con tema de Icarus
+creta icarus-terminal
+
+# Revertir personalización de terminal
+creta revert-terminal
+
+# Mostrar ayuda
+creta help
+creta ayuda
+
+# Reiniciar estado de usuario (nombre, progreso, estadísticas)
+creta reset
+```
+
+---
+
+## 💾 Datos Locales
+
+Creta almacena estos datos en tu sistema:
+
+| Ubicación | Contenido | Limpieza |
+|-----------|-----------|----------|
+| `~/.creta/user.json` | Nombre, lecciones completadas, proyectos, estadísticas | `creta reset` |
+| `/tmp/creta-practice-*` | Sesiones de práctica interactiva (sandboxes temporales) | Auto-limpieza al iniciar CLI |
+| `{nombre}-portafolio/` | Proyectos generados por ti | Manual (son tus proyectos) |
+
+**Nota:** Los sandboxes de práctica se limpian automáticamente cada vez que ejecutas Creta.
+
+---
+
+## 🎯 Filosofía Creta
+
+> **"Partir de enunciados que generan 'ruido' para construir comprensión real, no solo sintaxis."**
+
+### Principios
+
+**Evolution Over Replacement:**
+- No abandonamos features a medida que creces
+- Agregamos capas de funcionalidad
+- Misma herramienta, diferentes modos
+- Progresión sin fisuras
+
+**Always Relevant:**
+- Estudiantes la usan para aprender
+- Juniors la usan para referencias
+- Profesionales la usan para workflow
+- Nunca te quedas sin tu compañero
+
+**Spanish-First:**
+- Aprendizaje en tu idioma nativo
+- Sin barrera de traducción
+- Contexto cultural importa
+- Comunidad LATAM de desarrolladores
+
+**CLI-Native:**
+- Rápido, keyboard-driven
+- Sin cambio de contexto
+- La terminal es tu hogar
+- Funciona donde los devs trabajan
+
+### Valores
+
+- 🎯 **Aprender construyendo** - Learn by doing
+- 🧠 **Conceptos antes que sintaxis** - Fundamentos sólidos
+- 💪 **Progresión por niveles** - Salta adelante o obtén soluciones
+- 🔁 **Aprendizaje cíclico** - Discord → CLI → Videos → Repite
+- 🎮 **Gamificación** - Hashes, recompensas, desbloqueos
+- 🇪🇸 **Todo en español** - Educación accesible en tu idioma
+
+---
+
+## 🔧 Desarrollo
+
+### Estructura del Proyecto
+
+```
+cli/
+├── bin/creta.js              # Punto de entrada
+├── lib/
+│   ├── cli/index.js          # Lógica principal del CLI
+│   ├── builders/             # MenuBuilder, LessonBuilder
+│   ├── data/                 # Lecciones, menús, mensajes
+│   ├── executors/            # Ejecutores de sintaxis, enunciados, proyectos
+│   ├── sandbox/              # Sistema de práctica interactiva
+│   │   ├── SandboxManager.js
+│   │   ├── CommandValidator.js
+│   │   └── CommandExecutor.js
+│   └── utils/                # User state, greeting, etc.
+└── templates/
+    └── sveltekit-portfolio/  # Template de portafolio
+```
+
+### Comandos de Desarrollo
+
+```bash
+# Probar CLI localmente
+node bin/creta.js
+
+# Probar comando específico
+node bin/creta.js sintaxis
+node bin/creta.js portafolio
+
+# Publicar a npm (incrementar versión primero)
+npm publish
+
+# O usar el script de deployment
+./deploy-patch.sh
+```
+
+### Tecnologías
+
+- **Runtime:** Node.js (ES modules, no TypeScript)
+- **CLI Framework:** Vanilla Node.js con readline
+- **Template Engine:** SvelteKit 5 + Tailwind CSS 4
+- **Package Manager:** npm
+- **Publicado como:** `@icarusmx/creta` (acceso público)
+
+---
+
+## 🗺️ Roadmap
+
+### ✅ Ahora: Phase 1 Complete (v1.4.16)
+- Core curriculum (7 enunciados + 4 sintaxis)
+- Interactive practice system
+- Portfolio generation
+- User state tracking
+
+### 🚀 Próximo: Phase 2 Launch (v1.5.0)
+- Command reference system (`creta ls`)
+- Reemplazar `man` para estudiantes
+- Polish existing content
+- Neovim curriculum
+
+### 📈 3-6 meses: Phase 2 Expansion
+- Advanced command references
+- Hash/YouTube loop completado
+- Scythe integration (tokens)
+- 500+ monthly active users
+
+### 🏗️ 6-12 meses: Phase 3 Vision
+- Authentication system
+- Requirement management (`creta requirement`)
+- Team workspace features
+- Constructor tools live
+
+Ver **[ROADMAP.md](./ROADMAP.md)** para detalles completos.
+
+---
+
+## 📊 Métricas de Éxito
+
+**Phase 1 (Aprendiz):**
+- Monthly active learners
+- Lessons completed per user
+- Hash redemption rate
+
+**Phase 2 (Desarrollador):**
+- `creta [command]` usage vs `man [command]`
+- Command reference engagement
+- Time saved vs Google/man
+
+**Phase 3 (Constructor):**
+- Authenticated users
+- Daily active professionals
+- Tickets managed through Creta
+
+---
+
+## 🤝 Contribuir
+
+Este proyecto es parte de [Icarus](https://icarus.mx), una escuela de software enfocada en formar desarrolladores mediante la construcción de proyectos reales.
+
+**Queremos contribuciones que:**
+- Agreguen nuevas lecciones de sintaxis
+- Mejoren la experiencia de aprendizaje
+- Expandan el sistema de ayuda de comandos
+- Compartan feedback de estudiantes
+
+---
+
+## 📄 Licencia
+
+ISC
+
+---
+
+🏛️ **Hecho con <3 por [icarus.mx](https://icarus.mx)** - Salgamos de este laberinto