Global use and change proyects

CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.2] - 2026-04-24
+
+### Fixed
+- **NameError in Migration**: Fixed missing `migrate_from_json` function reported in code review.
+- **SQLite Connection Leaks**: Implemented a robust context manager in `DatabaseManager` to ensure all database connections are properly closed after use.
+- **Redundant Schema Alterations**: Integrated `total_balance` directly into the initial table creation for cleaner database initialization.
+- **Smooth Exit Flow**: Improved `KeyboardInterrupt` handling to exit immediately without requiring extra prompts.
+
+### Changed
+- **Higher-Level Storage API**: Refactored CLI code to use `DatabaseManager` methods instead of raw SQL queries for better separation of concerns.
+
+## [0.4.1] - 2026-04-24
+
+### Added
+- **High-Performance Balance Cache**: Added `total_balance` column to projects table to avoid $O(N)$ calculations.
+- **Atomic Balance Updates**: Balance is now updated incrementally on each record creation, modification, or deletion.
+- **Balance Audit Tool**: New internal methods to recalculate and validate the total balance.
+- **Automated Balance Tests**: Added comprehensive test suite for the balance cache engine.
+
+### Changed
+- **Optimized CLI Performance**: The status command and main menu now display the balance instantly.
+- **Clean Test Output**: Silenced CLI print statements during automated testing for professional output.
+
+## [0.3.0] - 2026-04-24
+### Added
+- **Global Installation**: The app now stores data in standard system paths (XDG compliant), making it truly global.
+- **SQLite Backend**: Replaced JSON storage with SQLite for improved performance and data integrity.
+- **Multi-project Support**: New project management menu allows creating, switching, and editing multiple work contexts.
+- **Migration Tool**: New `--migrate <file.json>` command to import legacy history files into the new system.
+- **Active Project Context**: The application now remembers the last used project globally.
+
+### Changed
+- Refactored `storage.py` to use `DatabaseManager`.
+- Updated `cli.py` to support project management submenus.
+- Decoupled `io.py` from storage logic for better testability.
+
 ## [0.2.0] - 2026-04-20
 ### Added
 - **Globalization (i18n)**: Fully translated UI with automatic language detection (English and Spanish supported).

README.es.md

@@ -1,6 +1,6 @@
 # time-balance 🕒
 
-> Una herramienta de terminal ligera y profesional para registrar tus jornadas laborales y controlar tu saldo acumulado de horas.
+> Una herramienta de terminal profesional y global para gestionar múltiples proyectos, registrar jornadas laborales y controlar tu saldo de horas.
 
 [Read in English 🇺🇸](README.md)
 
@@ -9,85 +9,75 @@
 
 ## Descripción
 
-`time-balance` es una aplicación de consola diseñada para personas que necesitan llevar un control riguroso de su tiempo trabajado. Calcula automáticamente la diferencia diaria respecto a una jornada base (7h 45m por defecto) y mantiene un saldo acumulado para que siempre sepas si "debes" horas o tienes saldo a favor.
+`time-balance` es una aplicación de consola **global**. Ya no depende de dónde la ejecutes; tus proyectos y registros se almacenan en una base de datos SQLite centralizada en tu sistema. Calcula automáticamente la diferencia diaria respecto a una jornada base y mantiene un saldo acumulado por cada proyecto de forma independiente.
 
 ---
 
-## Instalación rápida
+## Instalación Global
+
+Para instalar la aplicación de forma que esté disponible en cualquier terminal:
 
 ```bash
 # Clonar y entrar al directorio
 git clone <url-del-repo>
 cd time-balance
 
-# Instalar la aplicación
-python3 -m pip install .
+# Instalar de forma global en tu usuario
+pip install .
 ```
 
 ---
 
 ## Uso de la aplicación
 
-### 1. Menú Interactivo (Recomendado)
-Simplemente ejecuta el comando para abrir el centro de control:
+### 1. Centro de Control (Menú Interactivo)
+Ejecuta el comando desde cualquier carpeta para abrir el gestor:
 
 ```bash
 time-balance
 ```
 
-La interfaz detecta automáticamente el idioma de tu sistema (soporta inglés y español). Puedes registrar nuevas jornadas, ver tu historial reciente o importar/exportar tus datos.
+### 2. Navegación Intuitiva
+La interfaz utiliza un estándar claro:
+- **Números (1-5)** para seleccionar acciones.
+- **Letras** para navegación: `V` para volver, `N`/`P` para navegar por las páginas del historial.
+
+### 3. Gestión de Proyectos y Configuración
+- **Opción 3 (Configuración)**: Ajusta el nombre, la jornada base o el idioma del proyecto activo. También permite importar/exportar datos.
+- **Opción 4 (Cambiar Proyecto)**: Cambia entre tus diferentes contextos de trabajo o crea uno nuevo.
 
-### 2. Comandos Rápidos (Modo Directo)
+### 4. Consultas Rápidas
 Consulta tu estado sin entrar al menú:
 
 ```bash
-# Ver solo tu saldo acumulado actual
+# Ver el saldo del proyecto activo
 time-balance --status
 
-# Listar los últimos 10 días registrados
+# Listar los últimos 10 registros del proyecto activo
 time-balance --list 10
 
-# Forzar un idioma específico
-time-balance --lang es
-
-# Consultar la versión instalada
-time-balance --version
+# Migrar un historial antiguo en formato JSON
+time-balance --migrate ./ruta/al/archivo.json
 ```
 
 ---
 
 ## Características Principales
 
-- ✅ **Registro ágil**: Introduce horas y minutos de forma sencilla.
-- ✅ **Seguridad ante todo**: Escritura atómica de datos y backups automáticos en operaciones críticas.
-- ✅ **Multi-idioma**: Cambia sin problemas entre inglés y español.
-- ✅ **Importación flexible**: Combina historiales de diferentes dispositivos (merge) o restaura copias completas.
-- ✅ **Sin dependencias**: 100% Python estándar. Funciona en Windows, macOS y Linux.
-- ✅ **Privacidad absoluta**: Todo se guarda localmente en un archivo JSON legible.
+- ✅ **Caché de Alto Rendimiento**: Actualizaciones atómicas del saldo para resultados instantáneos, incluso con años de datos.
+- ✅ **Historial Paginado**: Navega cómodamente por tus registros, sin importar cuántos tengas.
+- ✅ **Almacenamiento SQLite**: Persistencia robusta y profesional en rutas estándar (XDG).
+- ✅ **Multi-proyecto**: Gestiona diferentes contextos de trabajo de forma independiente.
+- ✅ **Navegación Estandarizada**: Uso consistente de teclas para una mejor experiencia de usuario.
+- ✅ **Privacidad**: Todo sigue siendo 100% local en tu equipo.
 
 ---
 
-## Configuración Avanzada
-
-### Ubicación del historial
-Por defecto, la aplicación crea `historial_hours.json` en la carpeta actual. Si prefieres centralizarlo, define la variable de entorno:
-
-```bash
-export HISTORIAL_PATH="~/.config/mi_historial.json"
-```
-
-### Jornada Base
-La aplicación usa por defecto **7h 45m**. Puedes modificarla a través del menú interactivo en la configuración del proyecto.
-
----
-
-## Próximos Pasos (Roadmap) 🚀
-
-Estamos trabajando para llevar `time-balance` al siguiente nivel:
-
-- 🗄️ **Migración a SQLite**: Evolucionar el almacenamiento interno a una base de datos robusta para mejorar la integridad y velocidad, manteniendo JSON como estándar de importación/exportación.
-- 📂 **Gestión Multiproyecto**: Permitir el cambio rápido entre diferentes contextos de trabajo desde una instalación centralizada.
-- ☁️ **Sincronización Inteligente**: Ubicación configurable para facilitar el uso en carpetas compartidas (Dropbox, Drive) y backups automáticos.
+## Ubicación de los datos
+La base de datos se guarda automáticamente en:
+- **macOS**: `~/Library/Application Support/time-balance/time_balance.db`
+- **Linux**: `~/.local/share/time-balance/time_balance.db`
+- **Windows**: `%APPDATA%/time-balance/time_balance.db`
 
 ---
 

README.md

@@ -1,6 +1,6 @@
 # time-balance 🕒
 
-> A lightweight, professional command-line tool to track your working hours and manage your accumulated balance.
+> A professional, global terminal tool to manage multiple projects, track workdays, and manage your hour balance.
 
 [Leer en español 🇪🇸](README.es.md)
 
@@ -9,86 +9,72 @@
 
 ## Description
 
-`time-balance` is a CLI application designed for people who need rigorous control over their worked time. It automatically calculates the daily difference against a base workday (7h 45m by default) and maintains an accumulated balance so you always know if you "owe" hours or have a surplus.
+`time-balance` is a **global** console application. It no longer depends on where you run it; your projects and records are stored in a centralized SQLite database on your machine. It automatically calculates the daily difference against a base workday and maintains an accumulated balance for each project independently.
 
 ---
 
-## Quick Installation
+## Global Installation
+
+To install the application so it's available in any terminal:
 
 ```bash
 # Clone and enter directory
 git clone <repo-url>
 cd time-balance
 
-# Install the application
-python3 -m pip install .
+# Install globally for your user
+pip install .
 ```
 
 ---
 
 ## Usage
 
-### 1. Interactive Menu (Recommended)
-Simply run the command to open the control center:
+### 1. Control Center (Interactive Menu)
+Simply run the command from any folder to open the manager:
 
 ```bash
 time-balance
 ```
 
-The interface automatically detects your system language (supports English and Spanish). You can register new days, view recent history, or import/export your data.
+### 2. Intuitive Navigation
+The interface uses a clear standard:
+- **Numbers (1-5)** to select actions.
+- **Letters** for navigation: `V` to go back, `N`/`P` to navigate history pages.
+
+### 3. Project Management and Configuration
+- **Option 3 (Configuration)**: Adjust the name, base workday, or language of the active project. Also allows data import/export.
+- **Option 4 (Change Project)**: Switch between different work contexts or create a new one.
 
-### 2. Quick Commands (Direct Mode)
-Consult your status without entering the menu:
+### 4. Quick Commands
+Check your status without entering the menu:
 
 ```bash
-# Show current accumulated balance only
+# Show balance for the active project
 time-balance --status
 
-# List last 10 recorded days
+# List last 10 records for the active project
 time-balance --list 10
-
-# Force a specific language
-time-balance --lang en
-
-# Check installed version
-time-balance --version
 ```
 
 ---
 
-## Key Features
-
-- ✅ **Agile Registration**: Input hours and minutes easily.
-- ✅ **Safety First**: Atomic data writing and automatic backups for critical operations.
-- ✅ **Multi-language**: Seamlessly switch between English and Spanish.
-- ✅ **Flexible Import**: Merge histories from different devices or restore full copies.
-- ✅ **Zero Dependencies**: 100% Standard Python. Works on Windows, macOS, and Linux.
-- ✅ **Privacy-Focused**: All data is stored locally in a readable JSON file.
-
----
-
-## Advanced Configuration
-
-### History Location
-By default, the app creates `historial_hours.json` in the current folder. To centralize it, define the environment variable:
+## Main Features
 
-```bash
-export HISTORIAL_PATH="~/.config/time-balance/my_history.json"
-```
-
-### Base Workday
-The app defaults to **7h 45m**. If your workday is different, you can modify the constants in `time_balance/constants.py` and reinstall, or configure it via the interactive menu.
+- ✅ **High-Performance Caching**: Atomic balance updates for instant results, even with years of data.
+- ✅ **Paginated History**: Comfortably browse your records, no matter how many you have.
+- ✅ **SQLite Backend**: Robust and professional persistence in standard paths (XDG).
+- ✅ **Multi-project**: Manage different work contexts independently.
+- ✅ **Standardized Navigation**: Consistent use of keys for a better user experience.
+- ✅ **Privacy-Focused**: All data remains 100% local on your machine.
 
 ---
 
-## Future Steps (Roadmap) 🚀
-
-We are working to take `time-balance` to the next level:
-
-- 🗄️ **SQLite Migration**: Evolving internal storage to a robust database for better integrity and speed, keeping JSON as the standard for import/export.
-- 📂 **Multi-project Management**: Switch between different work contexts from a single centralized installation.
-- ☁️ **Smart Sync**: Simplified data location settings for cloud folders (Dropbox, iCloud, Drive) and automatic backups.
-- 🎨 **Rich UI**: Enhanced terminal experience using modern libraries for clearer tables, colors, and better usability.
+## Data Location
+The database is automatically saved in:
+- **macOS**: `~/Library/Application Support/time-balance/time_balance.db`
+- **Linux**: `~/.local/share/time-balance/time_balance.db`
+- **Windows**: `%APPDATA%/time-balance/time_balance.db`
 
 ---