PDF Tracker

PDF Tracker es una aplicación web mínima para registrar PDFs por ruta y guardar metadatos de lectura en SQLite.

Está pensada para correr en Linux o WSL, con una interfaz web simple y un backend en Node.js.

Instalación

La guía de instalación, requisitos, variables de entorno, tests y troubleshooting de entorno está en INSTALL.md.

Qué es

• Un registro de PDFs por ubicación.
• Un tracker de estado de lectura (unread, reading, read).
• Un sitio donde guardar título, keywords y comentarios.
• Una app que puede intentar abrir la carpeta contenedora o mostrar el fichero en el explorador, según el entorno.
• En WSL, una app que puede intentar abrir el selector nativo de PDFs de Windows mediante PowerShell.

Qué no es

• No es un gestor documental.
• No sube PDFs a ningún servidor.
• No copia archivos a una carpeta interna.
• No mueve ni renombra PDFs en disco.
• No indexa ni lee el contenido del PDF.
• No sincroniza bibliotecas ni extrae metadatos académicos.

Arranque rápido

Si ya tienes el entorno preparado:

cd /home/norwi/.openclaw/workspace/projects/pdf-tracker
npm install
PORT=3001 npm start

Después abre en el navegador:

• http://localhost:3001

El backend expone además:

• GET /health

Uso básico

1. Abre la aplicación en el navegador.
2. Rellena la ficha del PDF.
3. Indica al menos la ruta actual del PDF.
4. Opcionalmente añade:
   • título
   • ruta original de referencia
   • estado
   • keywords
   • comentarios
5. Pulsa Registrar PDF.
6. Usa los filtros por estado o keyword para revisar tu lista.
7. Desde cada registro puedes editar datos o borrar el registro.

Cómo registrar PDFs

Campos importantes:

• Ruta actual del PDF: obligatoria. Es la ubicación donde el archivo está ahora mismo.
• Ruta original de referencia: opcional. Si la dejas vacía, la app reutiliza la ruta actual.
• Título: opcional. Si lo dejas vacío, la app usa el nombre del fichero sin extensión.
• Estado: unread, reading o read.
• Keywords: puedes separarlas por comas o saltos de línea. El backend limpia espacios y elimina duplicados.
• Comentarios: texto libre.

Ejemplos válidos de ruta:

• Windows: D:\Papers\paper.pdf
• WSL montando Windows: /mnt/d/Papers/paper.pdf
• Linux: /home/usuario/docs/paper.pdf
• URL remota: https://example.com/paper.pdf

Importante: la app acepta rutas remotas para registrar un ítem, pero las acciones de abrir carpeta o localizar fichero solo tienen sentido con rutas locales.

Explicación de rutas

La aplicación maneja varias rutas/campos relacionados:

• currentPath: la ruta actual del PDF.
• originalPath: la ruta original o de referencia.
• filePath: campo serializado por compatibilidad, alineado con la ruta actual guardada.

En la base de datos también se guardan nombres derivados del archivo:

• stored_filename
• original_filename

Si no indicas título, se genera a partir del nombre del archivo.

Selector de PDF en WSL

En la interfaz hay botones Elegir PDF… junto a la ruta actual y la ruta original.

En WSL, el backend intenta este flujo:

1. Convierte la ruta de trabajo si viene en formato /mnt/c/....
2. Ejecuta PowerShell de Windows.
3. Lanza el script scripts/pick-pdf-windows.ps1.
4. Ese script abre System.Windows.Forms.OpenFileDialog en Windows.
5. El resultado se escribe en un JSON temporal compartido.
6. El backend lee ese JSON y devuelve la ruta elegida a la UI.

Esto evita depender solo de stdout entre WSL y Windows.

Si ese flujo falla, siempre puedes pegar la ruta manualmente.

Abrir carpeta y mostrar ubicación

La app expone acciones de sistema para localizar el PDF registrado:

• Abrir carpeta contenedora
• Mostrar/localizar fichero

Comportamiento según entorno:

• WSL: usa explorer.exe; para localizar el fichero intenta explorer.exe /select,....
• Windows: usa explorer.
• macOS: usa open.
• Linux: usa xdg-open para abrir carpeta.

Limitación real: en Linux y algunos entornos no siempre se puede resaltar el fichero concreto. En esos casos, el backend degrada la acción y abre solo la carpeta contenedora.

Si la ruta es remota (http://, https://, file://), estas acciones fallarán porque no apuntan a un fichero local manejable por el lanzador del sistema.

Dónde se guardan los datos

Base de datos SQLite por defecto:

• data/pdf-tracker.sqlite

Tabla principal:

• pdfs

Esquema relevante:

• id
• title
• stored_filename
• original_filename
• file_path
• original_path
• current_path
• status
• keywords_json
• comments
• created_at
• updated_at

La app crea automáticamente el directorio data/ si no existe.

Resumen rápido

• Registra PDFs por ruta.
• Guarda estado, keywords y comentarios en SQLite.
• No mueve ni copia archivos.
• En WSL puede abrir el selector nativo de Windows.
• Puede intentar abrir carpeta o localizar el fichero, con degradación según plataforma.