🏛️ Creta CLI

El compañero CLI que evoluciona contigo - desde tus primeros comandos hasta tu carrera profesional.

"Salgamos de este laberinto" 🏛️

📖 Tabla de Contenidos

• ¿Qué es Creta?
• Instalación
• Arquitectura
• Phase 1: Aprendiz (✅ LIVE)
• Phase 2: Desarrollador (🚧 v1.5.0)
• Phase 3: Constructor (🔮 v2.0.0+)
• Utilidades
• Filosofía
• Desarrollo
• Roadmap
• Contribuir

🌱 ¿Qué es Creta?

Creta no es una herramienta que "terminas" y dejas atrás. Es un compañero que se adapta a tu nivel, evolucionando contigo desde estudiante hasta profesional:

🎓 Aprendiz          →  💻 Desarrollador      →  🏗️ Constructor
Learn interactively     Quick references        Professional workflow
creta sintaxis          creta ls               creta requirement

Versión actual: 1.5.14 (Phase 1 - Aprendiz completado) Próxima: 1.5.15 (Phase 2 - Sistema de ayuda)

¿Por qué Creta?

• 🇪🇸 Spanish-First: Aprende en tu idioma nativo, sin barrera de traducción
• 🔁 Aprendizaje Cíclico: Integrado con Discord + YouTube para experiencia completa
• 🔒 Práctica Segura: Ejecuta comandos reales en sandboxes aislados
• 📈 Evoluciona Contigo: Nunca te quedas sin tu compañero a medida que creces

📦 Instalación

# Instalación global (recomendado)
npm install -g @icarusmx/creta

# Uso directo con npx (sin instalar)
npx @icarusmx/creta

# Verificar instalación
creta --version

Requisitos:

• Node.js ≥ 18.0.0
• Sistema operativo: macOS, Linux, Windows (WSL)

🏗️ Arquitectura

Creta está diseñado como un sistema modular de 3 fases que evoluciona con las necesidades del desarrollador.

Vista General del Sistema

graph TB
    subgraph "🏛️ Creta CLI - Arquitectura de 3 Fases"
        subgraph "Phase 1: Aprendiz (v1.4.16) ✅ LIVE"
            A1[CLI Principal]
            A2[Sistema de Menús]
            A3[Ejecutores]
            A4[Sistema Sandbox]
            A5[Generador de Portafolios]

            A1 --> A2
            A2 --> A3
            A3 --> A4
            A3 --> A5
        end

        subgraph "Phase 2: Desarrollador (v1.5.0) 🚧 EN DEV"
            B1[Sistema de Ayuda]
            B2[Formateador de Comandos]
            B3[Contenido de Referencia]

            B1 --> B2
            B2 --> B3
        end

        subgraph "Phase 3: Constructor (v2.0+) 🔮 VISION"
            C1[Sistema de Auth]
            C2[API Client]
            C3[Gestor de Workflow]

            C1 --> C2
            C2 --> C3
        end
    end

    subgraph "Componentes Clave"
        D1[MenuBuilder]
        D2[LessonBuilder]
        D3[SandboxManager]
        D4[CommandValidator]
        D5[CommandExecutor]
        D6[UserState]

        A2 -.utiliza.-> D1
        A3 -.utiliza.-> D2
        A4 -.utiliza.-> D3
        A4 -.utiliza.-> D4
        A4 -.utiliza.-> D5
        A1 -.mantiene.-> D6
    end

    subgraph "Datos"
        E1[(Lecciones<br/>Enunciados + Sintaxis)]
        E2[(Menús<br/>Configuración)]
        E3[(Estado Usuario<br/>~/.creta/user.json)]
        E4[(Sandboxes<br/>/tmp/creta-*)]

        D2 --> E1
        D1 --> E2
        D6 --> E3
        D3 --> E4
    end

    subgraph "Ecosistema Externo"
        F1[Discord Server]
        F2[YouTube Videos]
        F3[npm Registry]

        A1 <-.hash redemption.-> F1
        F1 <-.unlock videos.-> F2
        F3 <-.npx @icarusmx/creta.-> A1
    end

    style A1 fill:#4CAF50
    style B1 fill:#FF9800
    style C1 fill:#9C27B0
    style D3 fill:#2196F3
    style D6 fill:#F44336

Ver diagrama completo →

Flujo de Comandos

graph LR
    Start([Usuario ejecuta comando]) --> Entry[bin/creta.js<br/>Entry Point]

    Entry --> Router{Detectar<br/>patrón de comando}

    Router -->|creta| MainMenu[Menú Principal]
    Router -->|creta sintaxis| SintaxisExec[SintaxisExecutor]
    Router -->|creta enunciados| EnunciadosExec[EnunciadosExecutor]
    Router -->|creta proyectos| ProyectosExec[ProyectosExecutor]
    Router -->|creta portafolio| PortfolioExec[PortfolioExecutor]
    Router -->|creta exercises| ExercisesExec[ExercisesExecutor]
    Router -->|creta papers| PapersExec[PapersExecutor]
    Router -->|creta help| HelpCmd[help.js]
    Router -->|creta ls<br/>creta git status| CmdHelp[CommandHelpExecutor<br/>Phase 2 🚧]

    SintaxisExec --> LessonBuilder[LessonBuilder]
    EnunciadosExec --> LessonBuilder
    ProyectosExec --> ProjectBuilder[ProjectBuilder]

    LessonBuilder --> Interactive{¿Lección<br/>interactiva?}
    Interactive -->|Sí| Sandbox[SandboxManager<br/>Práctica real]
    Interactive -->|No| Display[Mostrar contenido]

    Sandbox --> Validator[CommandValidator]
    Validator --> Executor[CommandExecutor]
    Executor --> TmpDir[/tmp/creta-practice-*]

    PortfolioExec --> LevelMod[LevelModifier]
    LevelMod --> SvelteTemplate[Template SvelteKit 5]

    MainMenu --> MenuBuilder[MenuBuilder]
    MenuBuilder --> UserState[(UserState<br/>~/.creta/user.json)]

    CmdHelp --> HelpData[(command-help/<br/>Contenido de ayuda)]
    HelpData --> Formatter[CommandHelpFormatter]

    style Entry fill:#4CAF50
    style Router fill:#FF9800
    style Sandbox fill:#2196F3
    style CmdHelp fill:#9C27B0
    style UserState fill:#F44336

Ver diagrama de routing →

Estructura del Proyecto

cli/
├── bin/creta.js              # Punto de entrada principal
├── lib/
│   ├── cli/index.js          # Lógica core del CLI
│   ├── builders/             # MenuBuilder, LessonBuilder, ProjectBuilder
│   ├── data/                 # Contenido de lecciones y ayuda
│   │   ├── lessons/
│   │   │   ├── enunciados/  # 7 conceptos OOP fundamentales
│   │   │   └── sintaxis/    # 5 lecciones de sintaxis
│   │   └── command-help/    # Phase 2: Sistema de ayuda
│   ├── executors/            # Ejecutores de comandos
│   ├── sandbox/              # Sistema de práctica interactiva
│   │   ├── SandboxManager.js
│   │   ├── CommandValidator.js
│   │   └── CommandExecutor.js
│   └── utils/                # UserState, greeting, input/output
├── templates/
│   └── sveltekit-portfolio/  # Template de portafolio
└── docs/                     # Diagramas Mermaid

🎓 Phase 1: Aprendiz (LIVE)

Para estudiantes aprendiendo desde cero

El Flujo de Aprendizaje

Creta es parte de un ecosistema educativo completo que combina Discord, CLI y videos educativos:

sequenceDiagram
    participant Student as 🎓 Estudiante
    participant Discord as 💬 Discord Server
    participant CLI as 🏛️ Creta CLI
    participant Sandbox as 🔒 Sandbox /tmp
    participant YouTube as 📺 YouTube

    Note over Student,YouTube: Ciclo de Aprendizaje Interactivo

    Student->>Discord: 1. Únete al server
    Discord->>Student: "Aprende tus primeros comandos"
    Discord->>Student: "Instala Node.js"

    Student->>CLI: 2. npx @icarusmx/creta
    CLI->>Student: Menú principal interactivo

    Student->>CLI: 3. creta sintaxis
    CLI->>Student: Lista de lecciones disponibles

    Student->>CLI: 4. Seleccionar "Primeros comandos"
    CLI->>Sandbox: Crear sandbox en /tmp/creta-practice-*
    Sandbox-->>CLI: Sandbox listo
    CLI->>Student: Prompt interactivo (práctica real)

    Student->>CLI: 5. Ejecutar: ls
    CLI->>Sandbox: Validar y ejecutar comando
    Sandbox-->>CLI: Resultado real del comando
    CLI->>Student: ✅ Correcto! + Explicación

    Student->>CLI: 6. Ejecutar: mkdir proyectos
    CLI->>Sandbox: Validar y ejecutar
    Sandbox-->>CLI: Directorio creado
    CLI->>Student: ✅ Estado persiste entre pasos

    Student->>CLI: 7. Completar todos los pasos
    CLI->>CLI: Generar hash único
    CLI->>Student: 🎉 Hash: abc123xyz

    Student->>Discord: 8. /redeem abc123xyz
    Discord->>Discord: Validar hash
    Discord->>Student: 🔓 Link YouTube oculto

    Student->>YouTube: 9. Ver video educativo
    YouTube->>Student: Conceptos OOP, Git, etc.

    Note over Student,CLI: 10. Regresa al CLI para practicar más

    Student->>CLI: creta enunciados
    CLI->>Student: 7 conceptos OOP para explorar

    Note over Student,YouTube: 🔁 El ciclo continúa...

Ver flujo completo →

Comandos de Aprendizaje

# 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:

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

¿Cómo funciona internamente?

sequenceDiagram
    participant Student as 🎓 Estudiante
    participant SM as SandboxManager
    participant CV as CommandValidator
    participant CE as CommandExecutor
    participant FS as 💾 Sistema de Archivos

    Note over Student,FS: Sistema de Práctica Interactiva Segura

    Student->>SM: Iniciar lección interactiva
    SM->>SM: Limpiar sandboxes antiguos
    SM->>FS: Crear /tmp/creta-practice-{timestamp}
    FS-->>SM: Sandbox creado
    SM->>Student: Prompt: "Ejecuta: ls"

    Student->>SM: Ingresa: ls
    SM->>CV: Validar comando

    alt Comando válido
        CV-->>SM: ✅ Válido
        SM->>CE: Ejecutar en sandbox
        CE->>FS: chdir(/tmp/creta-practice-*)
        CE->>FS: exec('ls')
        FS-->>CE: Resultado
        CE-->>SM: stdout + stderr
        SM->>Student: ✅ Correcto!<br/>Resultado: [archivos]
        SM->>Student: Explicación del comando
    else Comando inválido
        CV-->>SM: ❌ Inválido
        SM->>Student: ❌ Incorrecto<br/>Esperaba: ls<br/>Hint: lista archivos
    end

    Student->>SM: Siguiente paso: "mkdir proyectos"
    SM->>CV: Validar
    CV-->>SM: ✅ Válido
    SM->>CE: Ejecutar
    CE->>FS: exec('mkdir proyectos')
    FS-->>CE: Directorio creado
    CE-->>SM: Éxito
    SM->>Student: ✅ Carpeta creada

    Note over SM,FS: Estado persiste entre pasos

    Student->>SM: "ls" (verificar)
    SM->>CE: Ejecutar
    CE->>FS: exec('ls')
    FS-->>CE: proyectos/ <- ¡Persiste!
    SM->>Student: ✅ proyectos/

    Student->>SM: Completar lección
    SM->>SM: Generar hash
    SM->>Student: 🎉 Hash: abc123xyz
    SM->>FS: Cleanup al salir del CLI
    FS-->>SM: Sandbox eliminado

    Note over Student,FS: Seguro: Todo en /tmp/, nunca toca archivos reales

Ver diagrama del sandbox →

📚 Curriculum Completo

5 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
5. curl y pipes - HTTP requests y procesamiento de datos

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

# 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)

Para junior devs que necesitan referencias rápidas

Reemplaza man con ayuda en español

# 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
creta curl

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.15

🏗️ Phase 3: Constructor (VISION)

Para profesionales trabajando en proyectos de Icarus

Asistente personalizado de workflow

# 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

# 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

# Tutorial para configurar Neovim
creta vim

# Tutorial para crear Pull Requests
creta pr

# Ver guías de AWS
creta aws

# Acceder a papers académicos
creta papers

# Generar ejercicios en PDF
creta exercises

# 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

Comandos de Desarrollo

# Probar CLI localmente
node bin/creta.js

# Probar comando específico
node bin/creta.js sintaxis
node bin/creta.js portafolio
node bin/creta.js ls  # Phase 2 command help

# Publicar a npm (incrementar versión primero en package.json)
npm publish

# O usar el script de deployment rápido
./deploy-patch.sh

Tecnologías

• Runtime: Node.js ≥ 18.0.0 (ES modules, no TypeScript)
• CLI Framework: Vanilla Node.js con readline
• Formatting: chalk v5
• Template Engine: SvelteKit 5 + Tailwind CSS 4
• Package Manager: npm
• Publicado como: @icarusmx/creta (acceso público)

Arquitectura de Componentes

classDiagram
    class SandboxManager {
        +createSandbox() string
        +executeStep(command, expected) Result
        +cleanup() void
        +validateCommand(input, expected) boolean
    }

    class CommandValidator {
        +validate(input, expected) ValidationResult
        +isExactMatch(input, expected) boolean
        +provideHint(expected) string
    }

    class CommandExecutor {
        +execute(command, workingDir) ExecutionResult
        +captureOutput(command) Output
        +handleError(error) ErrorInfo
    }

    class LessonBuilder {
        +buildLesson(lessonData) Lesson
        +renderContent(lesson) string
        +handleInteractive(lesson) void
        +generateHash(completion) string
    }

    class MenuBuilder {
        +buildMenu(menuConfig) Menu
        +displayOptions(menu) void
        +handleSelection(choice) void
        +navigate(path) void
    }

    class UserState {
        +load() UserData
        +save(data) void
        +updateProgress(lesson) void
        +getCompletedLessons() string[]
        +resetState() void
    }

    class PortfolioExecutor {
        +generatePortfolio(level) void
        +applyLevel(template, level) Project
        +copyTemplate(source, dest) void
    }

    class CommandHelpExecutor {
        +showHelp(command) void
        +findHelpContent(command) HelpData
        +formatHelp(content) string
        +linkToLesson(lesson) string
    }

    SandboxManager --> CommandValidator : usa
    SandboxManager --> CommandExecutor : usa
    LessonBuilder --> SandboxManager : interactivo
    MenuBuilder --> UserState : lee/escribe
    PortfolioExecutor --> LevelModifier : modifica
    CommandHelpExecutor --> HelpFormatter : formatea

    note for SandboxManager "Core del sistema de práctica\nAísla ejecución en /tmp/"
    note for CommandHelpExecutor "Phase 2 - Sistema de ayuda\nReemplaza 'man' en español"
    note for UserState "Persiste en ~/.creta/user.json\nNo requiere autenticación"

Ver diagrama de interfaces →

🗺️ Roadmap

✅ Ahora: Phase 1 Complete (v1.5.14)

• Core curriculum (7 enunciados + 5 sintaxis)
• Interactive practice system
• Portfolio generation
• User state tracking
• Exercises and papers system

🚀 Próximo: Phase 2 Launch (v1.5.15)

• Command reference system (creta ls, creta git status)
• Reemplazar man para estudiantes
• 10 comandos esenciales documentados
• Polish existing content
• Enhanced command help with examples

📈 3-6 meses: Phase 2 Expansion

• Advanced command references (30+ commands)
• Hash/YouTube loop completado
• Scythe integration (tokens)
• 500+ monthly active users
• Community-contributed help content

🏗️ 6-12 meses: Phase 3 Vision

• Authentication system (JWT/OAuth)
• Requirement management (creta requirement)
• Team workspace features
• Ticket tracking y workflow
• Constructor tools live
• Professional developer features

Ver ROADMAP.md para detalles completos.

📊 Métricas de Éxito

Phase 1 (Aprendiz):

• Monthly active learners
• Lessons completed per user
• Hash redemption rate
• Discord ↔ CLI ↔ YouTube loop completion

Phase 2 (Desarrollador):

• creta [command] usage vs man [command]
• Command reference engagement
• Student preference surveys
• Time saved vs Google/man

Phase 3 (Constructor):

• Authenticated daily active users
• Tickets managed through Creta
• Team adoption rate
• Professional workflow efficiency

🤝 Contribuir

Este proyecto es parte de Icarus, 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
• ✅ Mejoren la documentación
• ✅ Reporten bugs o issues

Cómo contribuir

1. Fork el repositorio
2. Crea una rama para tu feature: git checkout -b feature/nueva-leccion
3. Commit tus cambios: git commit -m "Add new lesson: grep basics"
4. Push a tu fork: git push origin feature/nueva-leccion
5. Abre un Pull Request describiendo tus cambios

Guías de contribución

• Lecciones: Deben ser interactivas, en español, con ejemplos claros
• Command help: Formato consistente, ejemplos prácticos, links a lecciones
• Código: ES modules, sin TypeScript, archivos < 300 líneas
• Commits: Mensajes descriptivos en español o inglés

📄 Licencia

MIT © Guillermo Rodríguez López

🔗 Enlaces

• npm: @icarusmx/creta
• Icarus: icarus.mx
• Discord: Únete al server de Icarus

🏛️ Hecho con ❤️ por icarus.mx - Salgamos de este laberinto