leganux-commit-describer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Angel Erick Cruz Olivera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# lnxcommit — Leganux Commit Describer
+
+> CLI que analiza los cambios de tus commits de Git y genera una descripción legible en español usando IA (DeepSeek).
+
+---
+
+## Requisitos
+
+- Node.js >= 18
+- Una API key de [DeepSeek](https://platform.deepseek.com/)
+- El directorio donde lo uses debe ser un repositorio Git
+
+---
+
+## Instalación
+
+### Opción A — Global desde npm
+
+```bash
+npm install -g leganux-commit-describer
+```
+
+### Opción B — Clonar y enlazar localmente
+
+```bash
+git clone https://github.com/leganux/leganux-commit-describer.git
+cd leganux-commit-describer
+npm install
+npm link
+```
+
+Tras la instalación el binario `lnxcommit` quedará disponible en tu `PATH`.
+
+---
+
+## Comandos
+
+### `lnxcommit configure`
+
+Guarda tu API key de DeepSeek en `~/.lnx_commit_describer/config.json`.
+Solo necesitas ejecutarlo **una vez** (o cuando quieras cambiar la key).
+
+```bash
+lnxcommit configure
+```
+
+**Flujo interactivo:**
+
+```
+🔧  Configuración de lnxcommit
+
+API key actual: (no configurada)
+
+? Ingresa tu API key de DeepSeek: ****************************
+
+✅  API key guardada en: /Users/<tu-usuario>/.lnx_commit_describer/config.json
+```
+
+---
+
+### `lnxcommit describe`
+
+Analiza el repositorio Git del directorio actual (o del indicado con `--path`) y
+muestra la descripción de cambios directamente en la consola.
+
+```bash
+# En el directorio del repo
+lnxcommit describe
+
+# Apuntando a otro repositorio
+lnxcommit describe --path /ruta/al/repo
+```
+
+**Salida de ejemplo:**
+
+```
+🔍  Analizando cambios en: /Users/leganux/mi-proyecto
+
+:sparkles: Título: Migración de script a librería npm con CLI interactivo
+
+- :sparkles: Se agrega el archivo `bin/lnxcommit.js` que expone el CLI con commander
+- :recycle: Se refactoriza `describe-changes.js` separando la lógica en `lib/core.js`
+- :memo: Se actualiza `README.md` con instrucciones completas de uso
+- :package: Se crea `package.json` definiendo el binario `lnxcommit`
+
+Resumen: Se convirtió el script original en una herramienta de línea de comandos instalable...
+```
+
+#### Opciones
+
+| Opción | Descripción |
+|--------|-------------|
+| `--path <ruta>` | Ruta al repositorio git (por defecto: directorio actual) |
+
+---
+
+### `lnxcommit describeandexport`
+
+Igual que `describe`, pero además exporta el resultado a un archivo `.txt`.
+
+```bash
+# Exporta a commit-description.txt en el directorio actual
+lnxcommit describeandexport
+
+# Con ruta y nombre de archivo personalizado
+lnxcommit describeandexport --path /ruta/al/repo --output ./changelog/cambios.txt
+```
+
+**Salida de ejemplo:**
+
+```
+🔍  Analizando cambios en: /Users/leganux/mi-proyecto
+
+- :sparkles: ...
+- :bug: ...
+
+📄  Descripción exportada a: /Users/leganux/mi-proyecto/commit-description.txt
+```
+
+El archivo generado tiene el siguiente formato:
+
+```
+# Descripción de cambios
+Generado: 2026-05-06 14:00:00
+Directorio: /Users/leganux/mi-proyecto
+
+- :sparkles: Título: ...
+- :recycle: ...
+...
+```
+
+#### Opciones
+
+| Opción | Descripción |
+|--------|-------------|
+| `--path <ruta>` | Ruta al repositorio git (por defecto: directorio actual) |
+| `--output <archivo>` | Archivo de salida (por defecto: `commit-description.txt` en el repo) |
+
+---
+
+## Configuración almacenada
+
+La API key se guarda de forma local en tu máquina en:
+
+```
+~/.lnx_commit_describer/config.json
+```
+
+Ejemplo del contenido:
+
+```json
+{
+  "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+}
+```
+
+Este archivo es **solo tuyo** y nunca se sube al repositorio (está en `.gitignore`).
+
+---
+
+## Cómo funciona internamente
+
+1. Detecta la rama base de comparación (`origin/main`, `origin/master` o `HEAD~1`).
+2. Obtiene `git diff --name-status` y el patch unificado contra esa base.
+3. Construye un prompt en español y lo envía a la API de DeepSeek (`deepseek-chat`).
+4. Formatea la respuesta como viñetas con gitmoji y la muestra / guarda.
+
+---
+
+## Estructura del proyecto
+
+```
+leganux-commit-describer/
+├── bin/
+│   └── lnxcommit.js        # Punto de entrada del CLI (commander)
+├── lib/
+│   └── core.js             # Lógica reutilizable (git, AI, config)
+├── describe-changes.js     # Script original (standalone)
+├── package.json
+└── README.md
+```
+
+---
+
+## Licencia
+
+MIT © [leganux](https://github.com/leganux)

package/bin/lnxcommit.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { program } = require('commander');
+const readline = require('readline');
+const fs = require('fs');
+const path = require('path');
+
+const {
+  readConfig,
+  writeConfig,
+  CONFIG_FILE,
+  CONFIG_DIR,
+  isGitRepo,
+  describeChanges,
+} = require('../lib/core');
+
+const { version } = require('../package.json');
+
+// ─── Helper: leer input oculto desde terminal ─────────────────────────────────
+function askSecret(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    // Silencia la salida para ocultar lo que se escribe
+    process.stdout.write(prompt);
+    let input = '';
+
+    // Desactivar echo en terminales que lo soporten
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.setEncoding('utf8');
+
+      process.stdin.on('data', function handler(char) {
+        if (char === '\n' || char === '\r' || char === '\u0004') {
+          process.stdin.setRawMode(false);
+          process.stdin.removeListener('data', handler);
+          process.stdout.write('\n');
+          rl.close();
+          resolve(input);
+        } else if (char === '\u0003') {
+          // Ctrl+C
+          process.stdout.write('\n');
+          process.exit(0);
+        } else if (char === '\u007f') {
+          // Backspace
+          input = input.slice(0, -1);
+        } else {
+          input += char;
+        }
+      });
+    } else {
+      // Sin TTY (p.ej. pipe): leer directamente
+      rl.question('', (answer) => {
+        rl.close();
+        resolve(answer);
+      });
+    }
+  });
+}
+
+program
+  .name('lnxcommit')
+  .description('CLI para describir cambios de commits con IA (DeepSeek)')
+  .version(version);
+
+// ─── configure ────────────────────────────────────────────────────────────────
+program
+  .command('configure')
+  .description('Configura la API key de DeepSeek y la guarda en ~/.lnx_commit_describer/config.json')
+  .action(async () => {
+    console.log('🔧  Configuración de lnxcommit\n');
+
+    const existing = readConfig();
+    const maskedKey = existing.apiKey
+      ? `${existing.apiKey.slice(0, 6)}${'*'.repeat(Math.max(0, existing.apiKey.length - 10))}${existing.apiKey.slice(-4)}`
+      : '(no configurada)';
+
+    console.log(`API key actual: ${maskedKey}\n`);
+
+    const apiKey = await askSecret('Ingresa tu API key de DeepSeek: ');
+    if (!apiKey || !apiKey.trim()) {
+      console.error('❌  La API key no puede estar vacía.');
+      process.exit(1);
+    }
+
+    const newConfig = { ...existing, apiKey: apiKey.trim() };
+    writeConfig(newConfig);
+
+    console.log(`\n✅  API key guardada en: ${CONFIG_FILE}`);
+  });
+
+// ─── describe ─────────────────────────────────────────────────────────────────
+program
+  .command('describe')
+  .description('Analiza los cambios del repositorio git en el directorio actual y muestra la descripción en consola')
+  .option('--path <ruta>', 'Ruta del repositorio git (por defecto: directorio actual)')
+  .action(async (opts) => {
+    const cwd = opts.path ? path.resolve(opts.path) : process.cwd();
+
+    console.log(`🔍  Analizando cambios en: ${cwd}\n`);
+
+    try {
+      const output = await describeChanges(cwd);
+      console.log(output);
+    } catch (err) {
+      const detail = err?.response?.data || err.message;
+      console.error('❌  Error:', detail);
+      process.exit(1);
+    }
+  });
+
+// ─── describeandexport ────────────────────────────────────────────────────────
+program
+  .command('describeandexport')
+  .description('Analiza los cambios del repositorio git y exporta la descripción a un archivo .txt')
+  .option('--path <ruta>', 'Ruta del repositorio git (por defecto: directorio actual)')
+  .option('--output <archivo>', 'Nombre del archivo de salida (por defecto: commit-description.txt)')
+  .action(async (opts) => {
+    const cwd = opts.path ? path.resolve(opts.path) : process.cwd();
+    const outputFile = opts.output
+      ? path.resolve(opts.output)
+      : path.join(cwd, 'commit-description.txt');
+
+    console.log(`🔍  Analizando cambios en: ${cwd}\n`);
+
+    try {
+      const output = await describeChanges(cwd);
+
+      const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
+      const fileContent = `# Descripción de cambios\nGenerado: ${timestamp}\nDirectorio: ${cwd}\n\n${output}\n`;
+
+      fs.writeFileSync(outputFile, fileContent, 'utf8');
+
+      console.log(output);
+      console.log(`\n📄  Descripción exportada a: ${outputFile}`);
+    } catch (err) {
+      const detail = err?.response?.data || err.message;
+      console.error('❌  Error:', detail);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/describe-changes.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+
+require('dotenv').config();
+
+const axios = require('axios');
+const { execSync } = require('child_process');
+
+function run(command) {
+  return execSync(command, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+
+function runSafe(command) {
+  try {
+    return run(command);
+  } catch (error) {
+    return '';
+  }
+}
+
+function getBaseRef() {
+  const checkMain = runSafe('git show-ref --verify --quiet refs/remotes/origin/main; echo $?');
+  if (checkMain.endsWith('0')) return 'origin/main';
+
+  const checkMaster = runSafe('git show-ref --verify --quiet refs/remotes/origin/master; echo $?');
+  if (checkMaster.endsWith('0')) return 'origin/master';
+
+  const hasPreviousCommit = runSafe('git rev-parse --verify HEAD~1');
+  if (hasPreviousCommit) return 'HEAD~1';
+
+  return 'HEAD';
+}
+
+function getGitChanges(baseRef) {
+  const branch = runSafe('git rev-parse --abbrev-ref HEAD') || 'unknown-branch';
+  const changedFiles = runSafe(`git diff --name-status ${baseRef}...HEAD`);
+  const patch = runSafe(`git diff --unified=1 ${baseRef}...HEAD`);
+  const status = runSafe('git status --short');
+
+  return {
+    branch,
+    baseRef,
+    changedFiles,
+    patch: patch.slice(0, 20000),
+    status,
+  };
+}
+
+function buildPrompt({ branch, baseRef, changedFiles, patch, status }) {
+  return `Analiza estos cambios de Git y crea una descripción humana en español.
+
+Reglas de salida:
+0) aniade un titulo para todos los cambios
+1) Responde SOLO con viñetas, un renglón por cada cambio relevante.
+2) Cada viñeta debe iniciar con gitmoji (ejemplo: :sparkles:, :bug:, :recycle:, :art:, :zap:).
+3) Formato exacto: "- :gitmoji: descripción corta".
+4) Máximo 1 línea por punto, sin párrafos, sin encabezados, sin texto extra.
+5) Si hay varios fixes, sepáralos en puntos distintos.
+6) Si no hay cambios relevantes, responde: "- :white_check_mark: No se detectaron cambios relevantes".
+7) Haz referencia detallada a los botones, Ids, funciones, clases, rutas de archivos, ramas; describiendo con base a sus nombres de esas clases o funciones que hacen internamente o que funcionalidad resuelven.
+8) Y al final pon un resumen corto de 4 o 5 renglones en lenguaje no tecnico de lo que implico esos cambios.
+9) Dame el titulo del commit en una sola frase con gitmoji al inicio.
+
+Contexto:
+- Rama: ${branch}
+- Base de comparación: ${baseRef}
+
+Archivos cambiados:
+${changedFiles || '(sin archivos en diff commit)'}
+
+Estado de working tree:
+${status || '(limpio)'}
+
+Patch (resumido):
+${patch || '(sin patch disponible)'}
+`;
+}
+
+async function requestDeepseek(prompt, apiKey) {
+  const response = await axios.post(
+    'https://api.deepseek.com/v1/chat/completions',
+    {
+      model: 'deepseek-chat',
+      temperature: 0.2,
+      max_tokens: 700,
+      messages: [
+        {
+          role: 'system',
+          content:
+            'Eres un generador de changelogs técnicos cortos. Cumple formato solicitado exactamente.',
+        },
+        {
+          role: 'user',
+          content: prompt,
+        },
+      ],
+    },
+    {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      timeout: 60000,
+    }
+  );
+
+  return response?.data?.choices?.[0]?.message?.content?.trim() || '';
+}
+
+function normalizeOutput(text) {
+  if (!text) return '- :white_check_mark: No se detectaron cambios relevantes';
+
+  const lines = text
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const clean = line.replace(/^[-*]\s*/, '').trim();
+      return clean.startsWith(':') ? `- ${clean}` : `- :wrench: ${clean}`;
+    });
+
+  return lines.length
+    ? lines.join('\n')
+    : '- :white_check_mark: No se detectaron cambios relevantes';
+}
+
+async function main() {
+  const isDryRun = process.argv.includes('--dry-run');
+  const apiKey = process.env.AI_API_KEY;
+  if (!apiKey && !isDryRun) {
+    console.error('Error: falta AI_API_KEY en el .env');
+    process.exit(1);
+  }
+
+  const baseRef = getBaseRef();
+  const changes = getGitChanges(baseRef);
+  const prompt = buildPrompt(changes);
+
+  if (isDryRun) {
+    console.log('DRY RUN - Resumen local de cambios detectados');
+    console.log(`Base: ${baseRef}`);
+    console.log(changes.changedFiles || 'Sin cambios detectados en diff contra base');
+    return;
+  }
+
+  try {
+    const aiText = await requestDeepseek(prompt, apiKey);
+    const output = normalizeOutput(aiText);
+    console.log(output);
+  } catch (error) {
+    const detail = error?.response?.data || error.message;
+    console.error('Error al generar descripción con IA:', detail);
+    process.exit(1);
+  }
+}
+
+main();

package/lib/core.js

@@ -0,0 +1,204 @@
+'use strict';
+
+const axios = require('axios');
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ─── Config helpers ───────────────────────────────────────────────────────────
+
+const CONFIG_DIR = path.join(os.homedir(), '.lnx_commit_describer');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+function readConfig() {
+  if (!fs.existsSync(CONFIG_FILE)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(data) {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2), 'utf8');
+}
+
+function getApiKey() {
+  const config = readConfig();
+  return config.apiKey || null;
+}
+
+// ─── Git helpers ──────────────────────────────────────────────────────────────
+
+function run(command, cwd) {
+  return execSync(command, {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    cwd: cwd || process.cwd(),
+  }).trim();
+}
+
+function runSafe(command, cwd) {
+  try {
+    return run(command, cwd);
+  } catch {
+    return '';
+  }
+}
+
+function isGitRepo(cwd) {
+  const result = runSafe('git rev-parse --is-inside-work-tree', cwd);
+  return result === 'true';
+}
+
+function getBaseRef(cwd) {
+  const checkMain = runSafe(
+    'git show-ref --verify --quiet refs/remotes/origin/main; echo $?',
+    cwd
+  );
+  if (checkMain.endsWith('0')) return 'origin/main';
+
+  const checkMaster = runSafe(
+    'git show-ref --verify --quiet refs/remotes/origin/master; echo $?',
+    cwd
+  );
+  if (checkMaster.endsWith('0')) return 'origin/master';
+
+  const hasPreviousCommit = runSafe('git rev-parse --verify HEAD~1', cwd);
+  if (hasPreviousCommit) return 'HEAD~1';
+
+  return 'HEAD';
+}
+
+function getGitChanges(baseRef, cwd) {
+  const branch =
+    runSafe('git rev-parse --abbrev-ref HEAD', cwd) || 'unknown-branch';
+  const changedFiles = runSafe(`git diff --name-status ${baseRef}...HEAD`, cwd);
+  const patch = runSafe(`git diff --unified=1 ${baseRef}...HEAD`, cwd);
+  const status = runSafe('git status --short', cwd);
+
+  return {
+    branch,
+    baseRef,
+    changedFiles,
+    patch: patch.slice(0, 20000),
+    status,
+  };
+}
+
+// ─── AI helpers ───────────────────────────────────────────────────────────────
+
+function buildPrompt({ branch, baseRef, changedFiles, patch, status }) {
+  return `Analiza estos cambios de Git y crea una descripción humana en español.
+
+Reglas de salida:
+0) aniade un titulo para todos los cambios
+1) Responde SOLO con viñetas, un renglón por cada cambio relevante.
+2) Cada viñeta debe iniciar con gitmoji (ejemplo: :sparkles:, :bug:, :recycle:, :art:, :zap:).
+3) Formato exacto: "- :gitmoji: descripción corta".
+4) Máximo 1 línea por punto, sin párrafos, sin encabezados, sin texto extra.
+5) Si hay varios fixes, sepáralos en puntos distintos.
+6) Si no hay cambios relevantes, responde: "- :white_check_mark: No se detectaron cambios relevantes".
+7) Haz referencia detallada a los botones, Ids, funciones, clases, rutas de archivos, ramas; describiendo con base a sus nombres de esas clases o funciones que hacen internamente o que funcionalidad resuelven.
+8) Y al final pon un resumen corto de 4 o 5 renglones en lenguaje no tecnico de lo que implico esos cambios.
+9) Dame el titulo del commit en una sola frase con gitmoji al inicio.
+
+Contexto:
+- Rama: ${branch}
+- Base de comparación: ${baseRef}
+
+Archivos cambiados:
+${changedFiles || '(sin archivos en diff commit)'}
+
+Estado de working tree:
+${status || '(limpio)'}
+
+Patch (resumido):
+${patch || '(sin patch disponible)'}
+`;
+}
+
+async function requestDeepseek(prompt, apiKey) {
+  const response = await axios.post(
+    'https://api.deepseek.com/v1/chat/completions',
+    {
+      model: 'deepseek-chat',
+      temperature: 0.2,
+      max_tokens: 700,
+      messages: [
+        {
+          role: 'system',
+          content:
+            'Eres un generador de changelogs técnicos cortos. Cumple formato solicitado exactamente.',
+        },
+        {
+          role: 'user',
+          content: prompt,
+        },
+      ],
+    },
+    {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      timeout: 60000,
+    }
+  );
+
+  return response?.data?.choices?.[0]?.message?.content?.trim() || '';
+}
+
+function normalizeOutput(text) {
+  if (!text) return '- :white_check_mark: No se detectaron cambios relevantes';
+
+  const lines = text
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const clean = line.replace(/^[-*]\s*/, '').trim();
+      return clean.startsWith(':') ? `- ${clean}` : `- :wrench: ${clean}`;
+    });
+
+  return lines.length
+    ? lines.join('\n')
+    : '- :white_check_mark: No se detectaron cambios relevantes';
+}
+
+// ─── Main describe logic ──────────────────────────────────────────────────────
+
+async function describeChanges(cwd) {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw new Error(
+      'No se encontró la API key. Ejecuta primero: lnxcommit configure'
+    );
+  }
+
+  if (!isGitRepo(cwd)) {
+    throw new Error(
+      `El directorio "${cwd}" no es un repositorio git válido.`
+    );
+  }
+
+  const baseRef = getBaseRef(cwd);
+  const changes = getGitChanges(baseRef, cwd);
+  const prompt = buildPrompt(changes);
+  const aiText = await requestDeepseek(prompt, apiKey);
+  return normalizeOutput(aiText);
+}
+
+module.exports = {
+  readConfig,
+  writeConfig,
+  getApiKey,
+  CONFIG_FILE,
+  CONFIG_DIR,
+  isGitRepo,
+  describeChanges,
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "leganux-commit-describer",
+  "version": "1.0.0",
+  "description": "CLI tool to describe git commit changes using DeepSeek AI",
+  "main": "lib/core.js",
+  "bin": {
+    "lnxcommit": "./bin/lnxcommit.js"
+  },
+  "scripts": {
+    "start": "node bin/lnxcommit.js"
+  },
+  "keywords": [
+    "git",
+    "commit",
+    "changelog",
+    "ai",
+    "deepseek",
+    "cli"
+  ],
+  "author": "leganux",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0",
+    "commander": "^12.0.0"
+  }
+}