vtasks-automate-cli 0.10.0 → 1.0.0

package/README.md

@@ -1,94 +1,108 @@
-# vtasks-automate-cli
-
-Automatizá el flujo de trabajo de tus tareas en **vTasks** con un solo comando.
-
----
-
-## 🚀 ¿Qué hace este CLI?
-
-`vtasks-automate-cli` es una herramienta diseñada para integrarse fácilmente en tu proyecto con frontend (Next.js o create-react-app) y backend (Node.js), y así automatizar el movimiento de tarjetas en **vTasks** mientras trabajás con ramas vinculadas a tareas.
-
-Con solo ejecutar el comando en la raíz del proyecto:
-
-```bash
-npx vtasks-automate-cli
-```
-
-La herramienta hará lo siguiente:
-
-1. 📦 **Instalará automáticamente la dependencia de automatización** en el frontend y el backend del proyecto.
-2. 🔧 **Modificarán los scripts de ejecución**:
-   - En el backend: actualiza `npm start`
-   - En el frontend (Next.js): actualiza `npm run dev` (o si el proyecto aun utiliza create-react-app actaualiza `npm start`)
-3. 🛠️ Agrega un githook para detectar los cambios de ramas y notificar que cambiaste la tarea en la que estas trabajando
-4. ⚙️ Al quedar configurado, **las tarjetas de vTasks se moverán automáticamente** a medida que que estés trabajando en las distintas ramas.
-
----
-
-## 📦 Instalación
-
-Solo ejecutá:
-
-```bash
-npx vtasks-automate-cli
-```
-
-Te pedira una confirmación para instalar los paquetes necesarios. Basta con aceptar.
-
-Este comando detectará automáticamente tus carpetas de frontend y backend, instalará lo necesario, y actualizará los scripts.
-
----
-
-## 🧠 ¿Cómo funciona?
-
-El paquete se integra en el ciclo de desarrollo de tu equipo. Cuando ejecutás los scripts habituales (`npm start` o `npm run dev`), se activa el sistema de automatización, que:
-
-- Detecta la rama en la que estás trabajando.
-- Detecta el usuario y el nombre del proyecto desde la configuración de git.
-- Se comunica con la API de **vTasks**.
-- Mueve la tarjeta correspondiente al estado "En Progreso".
-
----
-
-## 🛠️ Requisitos
-
-- Un proyecto con:
-  - Backend con Node.js y script `npm start` o
-  - Backend de React y script `npm start` o
-  - Frontend con Next.js y script `npm run dev`
-- Tener ramas creadas a través de **vTasks**, siguiendo el formato sugerido por la plataforma.
-
-## 🔄 Actualizar versión
-
-Para actualizar la versión del paquete **vtasks-automate-cli** en los proyectos, seguí estos pasos:
-
-1. Ir a las carpetas donde se ejecutan los programas, por ejemplo:
-
-   - `server`
-   - `client`
-   - `client-nextjs`
-     (según correspondan o existan en tu entorno)
-
-2. En **cada una** de esas carpetas, ejecutar el siguiente comando para instalar la última versión del paquete:
-
-   ```bash
-   npm i vtasks-automate-cli@latest
-
-   ```
-
-3. Verificar que la instalación se haya completado correctamente y que el paquete se haya actualizado en el package.json de cada proyecto.
-
-⚠️ **Importante:**  
-**No ejecutar** este comando en la raíz del proyecto.  
-Por ejemplo, **no** correrlo en:
-
-```
-/Venturing-Fullstack-Boilerplate
-```
-
-Sino en las rutas específicas:
-
-```
-/Venturing-Fullstack-Boilerplate/server
-/Venturing-Fullstack-Boilerplate/client
-```
+# vtasks-automate-cli
+
+Automatizá el flujo de trabajo de tus tareas en **vTasks** con un solo comando.
+
+---
+
+## ¿Qué hace este CLI?
+
+`vtasks-automate-cli` se integra en proyectos con una carpeta `/client` (frontend) y `/server` (backend), y automatiza el movimiento de tarjetas en **vTasks** mientras trabajás con ramas vinculadas a tareas.
+
+Con solo ejecutar el comando en la raíz del proyecto:
+
+```bash
+npx vtasks-automate-cli
+```
+
+La herramienta hará lo siguiente:
+
+1. **Se auto-actualiza**: si el paquete ya estaba instalado en el root con una versión anterior, se actualiza a la más reciente y re-ejecuta el setup con el nuevo código.
+2. **Instala o actualiza la dependencia** en `/client` y `/server`. Si ya está instalada y es la última versión, no hace nada.
+3. **Parchea el script `dev`** en el `package.json` de cada carpeta para que `vtasks-automate-cli` se ejecute automáticamente antes de iniciar la app. Solo lo agrega si no estaba ya — es idempotente.
+4. **Sincroniza los git hooks** en `.githooks/` con los últimos disponibles.
+
+---
+
+## Requisitos
+
+- Un proyecto con las carpetas `/client` y/o `/server` en la raíz (solo estas dos son soportadas).
+- Cada carpeta debe tener un script `"dev"` en su `package.json`. Es el único script que se modifica.
+- Ramas con el formato `{número}_{descripción}` para que el número de issue sea detectado automáticamente (ej: `12_fix-login`).
+
+---
+
+## Cómo funciona en el día a día
+
+Una vez configurado, el sistema actúa en dos momentos:
+
+### Al correr `npm run dev`
+Antes de iniciar el servidor o el frontend, el script:
+- Verifica si hay una nueva versión del paquete. Si la hay, se actualiza y sincroniza los git hooks.
+- Lee la rama actual y extrae el número de issue.
+- Si la rama es `qa`, `dev`, `master`, o no sigue el formato de issue, omite la notificación y continúa.
+- Llama a la API de **vTasks** para mover la tarjeta correspondiente a "En Progreso".
+
+### Al cambiar de rama (`git checkout` / `git switch`)
+El hook `post-checkout` detecta el cambio y también notifica a vTasks sobre la nueva tarea activa.
+
+---
+
+## Git hooks instalados
+
+El setup crea y mantiene actualizados los siguientes archivos en `.githooks/`:
+
+| Hook | Cuándo corre | Qué hace |
+|---|---|---|
+| `post-checkout` | Al cambiar de rama | Notifica a vTasks qué tarea está activa |
+| `commit-msg` | Al hacer commit | Augmenta el mensaje con un resumen generado por Claude CLI; agrega el número de issue en la primera línea y al final del mensaje |
+| `post-commit` | Después de cada commit | Refresca el índice de git (`git update-index -g`) |
+| `pre-commit` | Antes de cada commit | Valida archivos `.dist` y aplica prettier a los archivos staged |
+| `pre-push` | Antes de cada push | Compila `/client` y `/server` con `npm run build` para detectar errores antes de subir |
+| `validate-config-dist.js` | Llamado por `pre-commit` | Script auxiliar que verifica que los archivos `.dist` estén sincronizados con sus pares reales |
+
+> Para que los hooks funcionen, git debe estar configurado para usar la carpeta `.githooks`:
+> ```bash
+> git config core.hooksPath .githooks
+> ```
+
+---
+
+## Auto-actualización
+
+El paquete es auto-actualizable una vez instalado:
+
+- **Al correr `npm run dev`** en `/client` o `/server`: verifica la versión instalada contra la última en npm. Si hay una más nueva, la instala y sincroniza los git hooks automáticamente.
+- **Al correr `npx vtasks-automate-cli`**: si el paquete ya estaba instalado en el root con una versión antigua, se actualiza y re-ejecuta el setup completo con el código nuevo.
+
+---
+
+## Actualizar manualmente
+
+Para actualizar todo de una vez — root, `/client`, `/server` y git hooks — correr desde la raíz del proyecto:
+
+```bash
+npx vtasks-automate-cli@latest
+```
+
+Esto fuerza la descarga de la última versión y ejecuta el setup completo con el código nuevo, independientemente de qué versión haya instalada localmente.
+
+---
+
+## Estructura interna del paquete
+
+```
+vtasks-automate-cli/
+  hooks/                  ← contenido fuente de cada git hook
+    post-checkout
+    commit-msg
+    post-commit
+    pre-commit
+    pre-push
+    validate-config-dist.js
+  lib/
+    hooks.js              ← lógica de sincronización de hooks
+    update-hooks.js       ← script standalone para actualizar hooks desde content/index.js
+  content/
+    index.js              ← runtime: notifica a vTasks y maneja auto-update
+  init.js                 ← entry point del npx
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vtasks-automate-cli",
-  "version": "0.10.0",
+  "version": "1.0.0",
   "description": "Automate your vTasks workflow with ease — move tasks between states without opening the app",
   "bin": {
     "vtasks-automate": "init.js"