🎓 PradoOS (prado-os)

El motor de sincronización y flujo académico inteligente para PRADO UGR (pradogrado, pradoposgrado, prado.ugr.es) y Moodle.
Disponible para macOS, Linux Desktop y Windows.

🌐 Idiomas / Languages / Lingue / Langues: 🇪🇸 Español (Principal) | 🇬🇧 English | 🇮🇹 Italiano | 🇫🇷 Français

📸 Ver galería completa de interfaces (Menú TUI, Asistente de Onboarding, Lector de Correo UGR, Sincronización Incremental y Doctor)

1. Menú Interactivo Principal (prado)

2. Asistente de Configuración Guiado en 2 Fases (prado onboard)

3. Lector TUI de Correo UGR y Auto-Reenvío Selectivo (prado mail)

4. Sincronización Incremental con Protección Anti-Sobrescritura y DASHBOARD.md (prado sync --adopt)

5. Diagnóstico Integral de Salud y Daemon Multiplataforma (prado doctor / prado daemon)

---

👥 Autoría y AI Disclosure

🇮🇹 De una Necesidad Real en Granada a un Proyecto Open-Source

PradoOS fue desarrollado por Lorenzo Vasile, estudiante de Ingeniería Informática de la Università degli Studi di Palermo (UniPa) durante su estancia Erasmus+ en la Universidad de Granada (UGR, ETSIIT) (Curso 2026/2027).
Al compaginar múltiples asignaturas de distintos departamentos (Estructura de Datos, Modelos de Computación, Visión por Computador, Teoría de la Información y Sistemas Operativos), surgió la necesidad de optimizar el tiempo de estudio y eliminar por completo las pérdidas de tiempo manuales: descargar PDFs uno a uno, revisar foros repetitivamente, reorganizar carpetas y vigilar fechas de entrega dispersas.

🤖 AI Disclosure & Proceso de Desarrollo

Este proyecto fue diseñado e implementado mediante pair programming asistido por inteligencia artificial con Google Antigravity:

• Lorenzo Vasile: concepción del proyecto, definición de requisitos funcionales y de seguridad (aislamiento de credenciales en el Llavero nativo, flujo SAML/MFA sin contraseñas en texto plano, protección anti-sobrescritura) y validación en entornos reales (macOS, Linux y Windows).
• Stack de IA (Google Antigravity): se utilizó Gemini 4 Argon para el diseño de la arquitectura modular, análisis de seguridad y verificación, y Gemini 3.8 Flash para la generación ágil de código, la suite de tests automatizados (714 tests + suite E2E real sin mocks) y los pipelines de CI multiplataforma.

---

🇪🇸 Documentación en Español

💡 ¿Qué hace PradoOS por ti? (Sencillo, Claro e Impactante)

Si estudias en la Universidad de Granada, PradoOS resuelve en segundo plano todo lo que antes hacías a mano:

1. 📥 Tus asignaturas siempre al día en tu ordenador, sin mover un dedo:
   PradoOS detecta automáticamente todas las asignaturas en las que estás matriculado en PRADO (pradogrado, pradoposgrado o ceprud) y descarga transparencias, apuntes y guiones de prácticas a tu carpeta local.
2. 🛡️ Jamás pierdes ni se sobrescribe tu trabajo:
   Si resuelves una práctica, modificas un notebook .ipynb o compilas código .cpp y más tarde el profesor sube una corrección a PRADO, tu archivo nunca se borra ni se sobreescribe. PradoOS detecta tu modificación mediante hash SHA-256 y guarda la versión del profesor al lado como {archivo}_server_{fecha}.ext.
3. 📅 Tus entregas y exámenes directos a Google Calendar:
   Olvídate de revisar PRADO para ver cuándo vence una tarea. PradoOS envía tus fechas límite directamente a tu Google Calendar universitario (ETSIIT Granada o calendario principal) con alarmas popup inteligentes: 3 días, 1 día y 2 horas antes para exámenes; 2 días, 1 día y 3 horas antes para prácticas.
4. 🔑 Sin pedirte la contraseña todos los días:
   Gracias a su soporte del token de dispositivo de confianza (MFA_TOKEN), solo introduces tu segundo factor una vez cada 30 días. Tu contraseña se guarda en el Llavero nativo de tu sistema operativo (macOS Keychain, Windows Credential Manager o Linux SecretService), jamás en texto plano.
5. 📂 Organización natural y selector gráfico nativo (Finder / Explorador de Archivos):
   • Por defecto (mirror): mantiene los nombres oficiales de tus asignaturas en PRADO y replica exactamente las secciones creadas por cada profesor.
   • Modo IA (smart): separa automáticamente Teoria/, Practicas/P1..Pn/ y General/ (ideal si utilizas un agente de IA).
   • Sin escribir rutas a mano: detecta automáticamente tu Escritorio/Inicio localizado (en español, italiano o inglés) y te permite pulsar G durante la configuración para elegir dónde guardar tu carpeta mediante la ventana gráfica nativa de tu sistema (Finder en macOS, Explorador de Archivos en Windows, Zenity/KDialog en Linux).
6. 📬 Lector TUI de Correo UGR (@correo.ugr.es) y Reenvío Automático a tu Correo Personal (prado mail):
   • Lee tu buzón institucional directamente en terminal (correo.ugr.es:993 vía IMAP4_SSL) reutilizando tus credenciales ya guardadas: muestra por defecto todo tu buzón igual que Webmail, te permite aplicar filtros rápidos por profesor o palabra clave ([F]), no marca tus correos como leídos en segundo plano (BODY.PEEK[], solo los marca como leídos cuando tú abres un correo concreto), y al descargar archivos adjuntos (📎) abre siempre la ventana gráfica nativa de carpetas para que elijas dónde guardarlos.
   • Reenvío selectivo automático ([R]): configura qué profesores o asignaturas te interesan y PradoOS reenviará automáticamente sus correos (con adjuntos incluidos) a tu cuenta personal (@gmail.com, @icloud.com, @outlook.com) a través de correo.ugr.es:465 (SMTP_SSL).

---

🚀 Inicio Rápido

Opción A: Mediante Asistente de IA (Antigravity, Claude Code, Cursor, Codex)

Pega este mensaje en tu asistente de programación con IA:

Instala y configura https://github.com/LorSt4r/prado-os siguiendo BOOTSTRAP.md

El agente leerá BOOTSTRAP.md, te hablará en tu idioma preferido (español o inglés) y completará la configuración inicial en menos de 60 segundos.

Opción B: Instalación en 1 Clic por Terminal (100% Determinista, sin IA)

💡 Cero configuración previa: No necesitas tener Python ni Git instalados previamente. El instalador detecta tu entorno, descarga un runtime aislado en espacio de usuario (sin permisos de administrador) y lanza automáticamente el asistente en Español (o Inglés) junto con la primera descarga de tus asignaturas.

macOS y Linux Desktop:

curl -fsSL https://raw.githubusercontent.com/LorSt4r/prado-os/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/LorSt4r/prado-os/main/install.ps1 | iex

(Si ejecutas prado sin argumentos en tu terminal, se abrirá un menú interactivo con opciones numeradas del 1 al 7).

---

🛠️ Comandos Principales de la CLI

Todos los comandos admiten --help y formato estructurado --json:

Comando	Qué hace
prado onboard	Asistente de configuración inicial interactivo en 2 fases.
prado sync --adopt	Sincroniza materiales, revisa tu correo UGR (y aplica reglas de reenvío), y actualiza DASHBOARD.md.
prado mail	Abre el lector interactivo de correo UGR (@correo.ugr.es), filtros manuales ([F]) y reglas de auto-reenvío ([R]).
prado gcalendar	Sincroniza directamente las entregas y exámenes con Google Calendar API.
prado sync --gcalendar	Descarga materiales nuevos y empuja las fechas al calendario en un único paso.
prado auth login --gui	Abre la ventana emergente nativa del sistema operativo para iniciar sesión.
prado auth status	Comprueba la validez de la sesión y el estado del token de confianza a 30 días.
prado discover	Lista todas las asignaturas matriculadas detectadas en PRADO.
prado doctor --json	Diagnóstico de salud: comprueba red UGR, credenciales, permisos y dependencias.
prado notify (on/off)	Activa o desactiva las notificaciones de escritorio nativas (opt-in deshabilitado por defecto).
prado daemon install	Instala un servicio en segundo plano para sincronizar cada 4 horas (launchd/systemd/schtasks).
prado star	Deja una estrella al repositorio en GitHub si la herramienta te ha sido útil.

---

🔬 Especificaciones Técnicas y Arquitectura Interna (Deep Dive)

Para desarrolladores, administradores de sistemas o estudiantes que deseen conocer las tripas técnicas del motor:

┌─────────────────────────────────────────────────────────────────────────┐
│                           ARQUITECTURA PRADOOS                          │
└─────────────────────────────────────────────────────────────────────────┘
   [ Usuario / Agente IA ]
              │
              ▼
   [ CLI Engine: prado ]  (Click/Argparse, protocol --json universal, menús TUI)
              ├───► [ Auth & 3-Tier SAML Engine ]
              │       ├── UgrSamlDriver: Redirección HTTP headless con IdP SimpleSAMLphp
              │       ├── Tier 1: Persistencia de cookie MFA_TOKEN (Trust 30 días)
              │       ├── Tier 2: Extracción automática de código 2FA vía IMAP SSL (imap.ugr.es)
              │       └── Tier 3: Diálogo nativo GUI (prompt_gui_input) o TTY interactivo
              │
              ├───► [ Security & Isolation Layer ]
              │       ├── CredentialStore: Keyring nativo (Security / CredMgr / SecretService)
              │       ├── Bóveda AES-256 fallback con permisos estrictos 0600
              │       └── Separación total: config en ~/.config/prado, NUNCA en la carpeta de apuntes
              │
              ├───► [ Safe Downloader & 4-Quadrant Overwrite Protection ]
              │       ├── Streaming en chunks de 64 KB con hash SHA-256 sobre archivos temporales
              │       ├── Reemplazo atómico con backoff ante bloqueos NTFS de Windows
              │       └── Matriz de Colisiones:
              │             • Q1 (Local = Server): Sin acción.
              │             • Q2 (Local nuevo, Server nuevo): Descarga y registra hash.
              │             • Q3 (Estudiante modificó, Server igual): Protege trabajo local.
              │             • Q4 (Estudiante modificó, Server modificó): Conserva trabajo local y
              │               guarda actualización como {nombre}_server_{AAAAMMDD_HHMMSS}.{ext}
              │
              ├───► [ Exporters & Calendar Sync Engine ]
              │       ├── GoogleCalendarSync: REST API v3 con OAuth2 auto-refresh (stdlib urllib puro)
              │       ├── CalendarExporter: deadlines.ics estándar RFC-5545 con VALARMs a scaglioni
              │       ├── DashboardExporter: DASHBOARD.md con cuenta regresiva en vivo
              │       └── ChangelogExporter: Historial cronológico con hash SHA-256 en CHANGELOG.md
              │
              └───► [ Diagnostics & Background Daemons ]
                      ├── Doctor: 9 sondas de verificación (idp.ugr.es, pradogrado, permisos 0700/0600)
                      └── DaemonManager: macOS launchd, Linux systemd --user / cron, Windows schtasks

• Manejo Seguro del Sistema Operativo: Las carpetas y archivos sensibles (config.yaml, session.json, state.db) se crean forzando permisos POSIX 0700 y 0600 incluso bajo umasks permisivas (0000). En Windows NTFS, las operaciones de reemplazo atómico cuentan con un bucle de reintento con backoff exponencial para absorber cerrojos transitorios de lectura.
• Sin Dependencias de Red Pesadas para Calendario: La sincronización con Google Calendar no requiere librerías externas de Google de cientos de megabytes; se comunica directamente con la API REST v3 mediante urllib.request y gestiona el flujo de refresh_token de forma nativa.
• Suite de Pruebas Opaque-Box, Adversarial y E2E Real sin Mocks: Cuenta con 714 tests automatizados en pytest más una suite de verificación E2E en vivo (tests/e2e/test_live_real.py) que validan desde ataques de path traversal en nombres de secciones hasta descargas reales en PRADO UGR, correo institucional (correo.ugr.es) y daemons nativos en macOS, Linux y Windows.

---

🇬🇧 English Documentation

👥 Authorship & AI Disclosure

🇮🇹 From a Real Need in Granada to an Open-Source Project

PradoOS was created by Lorenzo Vasile, a Computer Engineering student from the Università degli Studi di Palermo (UniPa) during his Erasmus+ exchange at the Universidad de Granada (UGR, ETSIIT) (2026/2027 academic year).
While juggling five core Computer Engineering courses across different departments (Data Structures, Models of Computation, Computer Vision, Information Theory & Coding, and Operating Systems), the need arose to optimize study time and completely eliminate repetitive manual busywork: downloading PDFs one by one, checking scattered forum announcements, organizing local folders, and tracking shifting submission deadlines.

🤖 AI Disclosure & Development Process

This project was designed and built through AI-assisted pair programming using Google Antigravity:

• Lorenzo Vasile: project conception, functional and security requirements specification (OS Keychain credential isolation, zero-plaintext SAML/MFA authentication flow, 4-quadrant student overwrite protection, real correo.ugr.es IMAP/SMTP integration), and live E2E validation across macOS, Linux, and Windows.
• AI Stack (Google Antigravity): Gemini 4 Argon was used for modular systems architecture, security auditing, and formal verification, while Gemini 3.8 Flash powered rapid implementation, the 714-test automated suite (including zero-mock live E2E tests), and cross-platform CI pipelines.

---

💡 What Does PradoOS Do for You?

PradoOS turns your university Moodle / PRADO UGR portal into an automated, self-updating local workspace on macOS, Linux Desktop, and Windows:

1. 📥 Zero Manual Downloads: Auto-discovers all your enrolled courses and synchronizes slides, lecture notes, code templates, and assignment briefs directly to your machine.
2. 🛡️ Zero Overwrites Guarantee: Your work is sacred. If you edit a Jupyter Notebook (.ipynb), write code (.cpp, .py), or modify a report (.docx), PradoOS tracks original SHA-256 hashes and never overwrites your local edits. Professor updates are stored side-by-side as {name}_server_{timestamp}.{ext}.
3. 📅 Direct Google Calendar Integration: Pushes deadlines and exam milestones directly to your Google Calendar with tiered popup reminders (3d/1d/2h for exams, 2d/1d/3h for assignments).
4. 🔑 30-Day Device Trust: Enter your 2FA verification code once a month. Passwords live strictly in your operating system's Keychain—never in plaintext.
5. 📂 Native GUI Folder Picker & Official PRADO Course Names:
   • Default (mirror): preserves official PRADO course names and exact professor section structure.
   • AI Mode (smart): separates Teoria/, Practicas/P1..Pn/, and General/ for AI-assisted workflows.
   • No manual path typing: auto-detects your OS-localized Desktop/Home folder and lets you press G during setup to pick your destination folder via a native graphical window (macOS Finder, Windows File Explorer, Linux File Manager).
6. 📬 Built-in UGR Mail TUI Reader & Selective Auto-Forwarding (prado mail):
   • Connects directly to correo.ugr.es:993 (IMAP4_SSL) and correo.ugr.es:465 (SMTP_SSL) reusing your stored UGR credentials. Opens your full unfiltered inbox by default (like Webmail) with top-level manual filters ([F]) and auto-forwarding rules ([R]) to forward emails from specific professors or course keywords straight to your personal email (@gmail.com, @icloud.com, etc.). Preserves unread status (BODY.PEEK[]) during background syncs and opens a native GUI folder picker whenever you save an email attachment (📎).

---

🚀 Quick Start (English)

Option A: Via AI Assistant (Antigravity, Claude Code, Cursor, Codex)

Send this prompt to your AI assistant:

Install and configure https://github.com/LorSt4r/prado-os for me following BOOTSTRAP.md

Option B: 1-Click Standalone Terminal Installation

💡 Zero prerequisites needed: You do not need Python or Git pre-installed. The installer automatically sets up an isolated user-space runtime and launches the interactive setup wizard (Spanish default or English) and initial course sync.

# macOS & Linux Desktop:
curl -fsSL https://raw.githubusercontent.com/LorSt4r/prado-os/main/install.sh | bash

# Windows (PowerShell):
irm https://raw.githubusercontent.com/LorSt4r/prado-os/main/install.ps1 | iex

---

⭐ Support & License

Si PradoOS te ayuda a ahorrar tiempo durante el cuatrimestre, apoya el repositorio con una estrella en GitHub (prado star)!
If PradoOS saves you time during your university semester, please consider starring the repository on GitHub (prado star)!

Distribuido bajo la Licencia GNU AGPLv3 (AGPL-3.0) — Desarrollado por Lorenzo Vasile.
Distributed under the GNU Affero General Public License v3.0 (AGPL-3.0) — Created by Lorenzo Vasile.