171 lines
3.9 KiB
Markdown
171 lines
3.9 KiB
Markdown
# Personal Tracker
|
|
|
|
Herramienta CLI para seguimiento de proyectos personales con foco en continuidad entre sesiones.
|
|
|
|
## Características
|
|
|
|
- **Persistencia simple**: Archivos Markdown y YAML legibles
|
|
- **Sin dependencias cloud**: Todo funciona offline
|
|
- **Kanban liviano**: TASKS.md con estados (Inbox, Next, Active, Blocked, Waiting, Done)
|
|
- **Bitácora por sesiones**: LOG.md y archivos de sesión detallados
|
|
- **Changelog**: Registro de cambios relevantes
|
|
- **CLI intuitiva**: Comandos para iniciar, pausar y documentar trabajo
|
|
|
|
## Stack
|
|
|
|
- Python 3.11+
|
|
- [Typer](https://typer.tiangolo.com/) - CLI
|
|
- [PyYAML](https://pyyaml.org/) - Metadatos
|
|
- [Jinja2](https://jinja.palletsprojects.com/) - Plantillas
|
|
- [Pydantic](https://docs.pydantic.dev/) - Modelos
|
|
|
|
## Instalación
|
|
|
|
### Requisitos Previos
|
|
|
|
- Python 3.11 o superior
|
|
- pip (gestor de paquetes Python)
|
|
|
|
### Método 1: Instalación con pip
|
|
|
|
```bash
|
|
# Clonar el repositorio
|
|
git clone <url-del-repositorio>
|
|
cd tracker
|
|
|
|
# Instalar en modo desarrollo
|
|
pip install -e .
|
|
|
|
# Verificar instalación
|
|
tracker --help
|
|
```
|
|
|
|
### Método 2: Usando uv (recomendado)
|
|
|
|
```bash
|
|
# Instalar con uv
|
|
uv pip install -e .
|
|
|
|
# O desde el código fuente
|
|
uv pip install -e .
|
|
```
|
|
|
|
### Verificar Instalación
|
|
|
|
```bash
|
|
tracker --help
|
|
```
|
|
|
|
Deberías ver la lista de comandos disponibles.
|
|
|
|
### Desinstalación
|
|
|
|
```bash
|
|
pip uninstall tracker
|
|
```
|
|
|
|
## Comandos
|
|
|
|
| Comando | Descripción |
|
|
|---------|-------------|
|
|
| `tracker init-project <slug>` | Crear nuevo proyecto |
|
|
| `tracker list` | Listar todos los proyectos |
|
|
| `tracker show <slug>` | Ver detalles de un proyecto |
|
|
| `tracker start <slug>` | Iniciar sesión de trabajo |
|
|
| `tracker note <text>` | Agregar nota a la sesión activa |
|
|
| `tracker stop <slug>` | Finalizar sesión y generar resumen |
|
|
| `tracker change <slug>` | Agregar entrada al changelog |
|
|
| `tracker next <slug>` | Sugerir próximos pasos |
|
|
| `tracker review` | Vista general de todos los proyectos |
|
|
|
|
## Estructura de un Proyecto
|
|
|
|
```
|
|
projects/<slug>/
|
|
├── README.md # Documentación principal
|
|
├── LOG.md # Bitácora de sesiones (append-only)
|
|
├── CHANGELOG.md # Registro de cambios
|
|
├── TASKS.md # Kanban liviano
|
|
├── sessions/ # Sesiones detalladas
|
|
├── docs/ # Documentación técnica
|
|
├── assets/ # Recursos
|
|
└── meta/
|
|
└── project.yaml # Metadatos
|
|
```
|
|
|
|
## Flujo de Uso
|
|
|
|
```bash
|
|
# 1. Crear proyecto
|
|
tracker init-project mi-proyecto --name "Mi Proyecto" --type code
|
|
|
|
# 2. Iniciar sesión
|
|
tracker start mi-proyecto --objective "Implementar feature X"
|
|
|
|
# 3. Agregar notas durante el trabajo
|
|
tracker note "Implementé la función base" --type work
|
|
tracker note "Decidí usar PostgreSQL en vez de SQLite" --type decision
|
|
|
|
# 4. Finalizar sesión
|
|
tracker stop mi-proyecto
|
|
|
|
# 5. Ver estado
|
|
tracker show mi-proyecto
|
|
tracker list
|
|
```
|
|
|
|
## Tipos de Nota
|
|
|
|
- `work` - Trabajo realizado
|
|
- `change` - Cambio realizado
|
|
- `blocker` - Bloqueo encontrado
|
|
- `decision` - Decisión tomada
|
|
- `idea` - Idea o pensamiento
|
|
- `reference` - Referencia o link
|
|
|
|
## Estados de Proyecto
|
|
|
|
- `inbox` - Recibido/revisar
|
|
- `next` - Próximo a trabajar
|
|
- `active` - En desarrollo activo
|
|
- `blocked` - Bloqueado
|
|
- `waiting` - En espera
|
|
- `done` - Completado
|
|
- `archived` - Archivado
|
|
|
|
## Tipos de Proyecto
|
|
|
|
- `code` - Desarrollo de software
|
|
- `homelab` - Infraestructura personal
|
|
- `automation` - Automatización
|
|
- `agent` - Agentes/IA
|
|
- `research` - Investigación
|
|
- `misc` - Misceláneo
|
|
|
|
## Proyecto Demo
|
|
|
|
Ver `examples/demo-project/` para un proyecto de ejemplo completo.
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
pytest tests/ -v
|
|
```
|
|
|
|
## Desarrollo
|
|
|
|
```bash
|
|
# Estructura del paquete
|
|
tracker/
|
|
├── cli/ # Comandos CLI
|
|
├── models/ # Modelos de datos
|
|
├── services/ # Lógica de negocio
|
|
├── storage/ # Persistencia archivos
|
|
├── utils/ # Utilidades
|
|
└── templates/ # Plantillas
|
|
```
|
|
|
|
## Licencia
|
|
|
|
MIT
|