@saulwade/swl-ses 1.4.1 → 1.5.0

package/scripts/lib/detectar-stack-detallado.js

@@ -1,307 +1,307 @@
-'use strict';
-
-/**
- * detectar-stack-detallado.js
- *
- * Detecta stack del proyecto destino con información rica para generación de
- * CLAUDE.md (no solo presencia, sino también: framework principal, scripts
- * disponibles, package manager, deps clave).
- *
- * Diferencia con `detectar-stack.js`: ese módulo es para FILTRAR reglas de
- * lenguaje (presence/absence). Este módulo es para POBLAR el bloque CLAUDE.md
- * inyectado por el installer con info accionable del proyecto destino.
- *
- * Zero-dependencies (solo fs/path nativos). Defensivo: cualquier read failure
- * devuelve null/undefined, nunca lanza.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Lee package.json del proyecto destino.
- * @returns {{ name?: string, version?: string, scripts?: object, dependencies?: object, devDependencies?: object } | null}
- */
-function leerPackageJson(dirProyecto) {
-  return _leerJsonSeguro(path.join(dirProyecto, 'package.json'));
-}
-
-/**
- * Detecta el package manager Node usado (basado en lockfile).
- * @returns {'pnpm' | 'yarn' | 'bun' | 'npm' | null}
- */
-function detectarPackageManagerNode(dirProyecto) {
-  if (fs.existsSync(path.join(dirProyecto, 'pnpm-lock.yaml'))) return 'pnpm';
-  if (fs.existsSync(path.join(dirProyecto, 'yarn.lock'))) return 'yarn';
-  if (fs.existsSync(path.join(dirProyecto, 'bun.lockb'))) return 'bun';
-  if (fs.existsSync(path.join(dirProyecto, 'package-lock.json'))) return 'npm';
-  if (fs.existsSync(path.join(dirProyecto, 'package.json'))) return 'npm';
-  return null;
-}
-
-/**
- * Detecta el package manager Python.
- * @returns {'poetry' | 'uv' | 'pdm' | 'pip' | null}
- */
-function detectarPackageManagerPython(dirProyecto) {
-  const pyproject = path.join(dirProyecto, 'pyproject.toml');
-  if (fs.existsSync(pyproject)) {
-    const contenido = _leerArchivoSeguro(pyproject) || '';
-    if (contenido.includes('[tool.poetry]')) return 'poetry';
-    if (contenido.includes('[tool.uv]')) return 'uv';
-    if (contenido.includes('[tool.pdm]')) return 'pdm';
-    return 'pip'; // pyproject genérico
-  }
-  if (fs.existsSync(path.join(dirProyecto, 'requirements.txt'))) return 'pip';
-  if (fs.existsSync(path.join(dirProyecto, 'Pipfile'))) return 'pip';
-  return null;
-}
-
-/**
- * Detecta framework Node a partir de dependencies.
- * @returns {string | null}
- */
-function detectarFrameworkNode(packageJson) {
-  if (!packageJson) return null;
-  const deps = { ...(packageJson.dependencies || {}), ...(packageJson.devDependencies || {}) };
-
-  if (deps.next) return `Next.js ${_limpiarVersion(deps.next)}`;
-  if (deps['@angular/core']) return `Angular ${_limpiarVersion(deps['@angular/core'])}`;
-  if (deps['@nestjs/core']) return `NestJS ${_limpiarVersion(deps['@nestjs/core'])}`;
-  if (deps.svelte) return `Svelte ${_limpiarVersion(deps.svelte)}`;
-  if (deps.vue) return `Vue ${_limpiarVersion(deps.vue)}`;
-  if (deps.remix || deps['@remix-run/node']) return 'Remix';
-  if (deps.astro) return `Astro ${_limpiarVersion(deps.astro)}`;
-  if (deps.nuxt) return `Nuxt ${_limpiarVersion(deps.nuxt)}`;
-  if (deps.fastify) return `Fastify ${_limpiarVersion(deps.fastify)}`;
-  if (deps.express) return `Express ${_limpiarVersion(deps.express)}`;
-  if (deps.react) return `React ${_limpiarVersion(deps.react)} (sin framework)`;
-
-  return null;
-}
-
-/**
- * Detecta framework Python leyendo deps en pyproject.toml o requirements.txt.
- * @returns {string | null}
- */
-function detectarFrameworkPython(dirProyecto) {
-  const pyproject = _leerArchivoSeguro(path.join(dirProyecto, 'pyproject.toml')) || '';
-  const requirements = _leerArchivoSeguro(path.join(dirProyecto, 'requirements.txt')) || '';
-  const deps = (pyproject + '\n' + requirements).toLowerCase();
-
-  if (deps.includes('fastapi')) return 'FastAPI';
-  if (deps.includes('django')) return 'Django';
-  if (deps.includes('flask')) return 'Flask';
-  if (deps.includes('starlette')) return 'Starlette';
-  if (deps.includes('aiohttp')) return 'aiohttp';
-  return null;
-}
-
-/**
- * Detecta el ORM/driver de BD principal.
- * @returns {string | null}
- */
-function detectarORM(packageJson, dirProyecto) {
-  const depsNode = packageJson
-    ? { ...(packageJson.dependencies || {}), ...(packageJson.devDependencies || {}) }
-    : {};
-
-  if (depsNode.prisma || depsNode['@prisma/client']) return 'Prisma';
-  if (depsNode['drizzle-orm']) return 'Drizzle';
-  if (depsNode.typeorm) return 'TypeORM';
-  if (depsNode.sequelize) return 'Sequelize';
-  if (depsNode.mongoose) return 'Mongoose';
-
-  // Python
-  const pyproject = _leerArchivoSeguro(path.join(dirProyecto, 'pyproject.toml')) || '';
-  const requirements = _leerArchivoSeguro(path.join(dirProyecto, 'requirements.txt')) || '';
-  const depsPy = (pyproject + '\n' + requirements).toLowerCase();
-  if (depsPy.includes('sqlalchemy')) return 'SQLAlchemy';
-  if (depsPy.includes('peewee')) return 'Peewee';
-  if (depsPy.includes('tortoise-orm')) return 'Tortoise ORM';
-
-  return null;
-}
-
-/**
- * Detecta lenguaje principal con confianza (devuelve el más probable).
- * @returns {{ lenguaje: string, runtime?: string } | null}
- */
-function detectarLenguajePrincipal(dirProyecto) {
-  // Node.js / TypeScript
-  if (fs.existsSync(path.join(dirProyecto, 'package.json'))) {
-    if (fs.existsSync(path.join(dirProyecto, 'tsconfig.json'))) {
-      return { lenguaje: 'TypeScript', runtime: 'Node.js' };
-    }
-    return { lenguaje: 'JavaScript', runtime: 'Node.js' };
-  }
-  // Python
-  if (
-    fs.existsSync(path.join(dirProyecto, 'pyproject.toml')) ||
-    fs.existsSync(path.join(dirProyecto, 'requirements.txt')) ||
-    fs.existsSync(path.join(dirProyecto, 'setup.py'))
-  ) {
-    return { lenguaje: 'Python' };
-  }
-  // Go
-  if (fs.existsSync(path.join(dirProyecto, 'go.mod'))) return { lenguaje: 'Go' };
-  // Rust
-  if (fs.existsSync(path.join(dirProyecto, 'Cargo.toml'))) return { lenguaje: 'Rust' };
-  // Java / Kotlin
-  if (fs.existsSync(path.join(dirProyecto, 'pom.xml'))) return { lenguaje: 'Java', runtime: 'Maven' };
-  if (
-    fs.existsSync(path.join(dirProyecto, 'build.gradle')) ||
-    fs.existsSync(path.join(dirProyecto, 'build.gradle.kts'))
-  ) {
-    return { lenguaje: 'Java/Kotlin', runtime: 'Gradle' };
-  }
-  // PHP
-  if (fs.existsSync(path.join(dirProyecto, 'composer.json'))) return { lenguaje: 'PHP' };
-  // Swift
-  if (fs.existsSync(path.join(dirProyecto, 'Package.swift'))) return { lenguaje: 'Swift' };
-  // Ruby
-  if (fs.existsSync(path.join(dirProyecto, 'Gemfile'))) return { lenguaje: 'Ruby' };
-  // C# / .NET
-  if (fs.existsSync(path.join(dirProyecto, 'global.json'))) return { lenguaje: 'C#', runtime: '.NET' };
-
-  return null;
-}
-
-/**
- * Detecta scripts comunes del proyecto (test, dev, build, lint).
- * Devuelve los scripts npm si existen + comandos típicos del lenguaje.
- *
- * @returns {Array<{ comando: string, proposito: string }>}
- */
-function detectarComandos(dirProyecto) {
-  const comandos = [];
-  const pkg = leerPackageJson(dirProyecto);
-  const pm = detectarPackageManagerNode(dirProyecto);
-
-  if (pkg && pkg.scripts) {
-    const interesantes = ['dev', 'start', 'build', 'test', 'lint', 'typecheck', 'format'];
-    for (const script of interesantes) {
-      if (pkg.scripts[script]) {
-        comandos.push({
-          comando: `${pm || 'npm'} run ${script}`,
-          proposito: _propositoScript(script),
-        });
-      }
-    }
-    // Si tiene "test" como entrypoint puro
-    if (pkg.scripts.test && !comandos.some(c => c.comando.includes('test'))) {
-      comandos.push({ comando: `${pm || 'npm'} test`, proposito: 'Tests' });
-    }
-  }
-
-  // Python
-  const pmPy = detectarPackageManagerPython(dirProyecto);
-  if (pmPy === 'poetry') {
-    comandos.push({ comando: 'poetry install', proposito: 'Instalar dependencias' });
-    comandos.push({ comando: 'poetry run pytest', proposito: 'Tests' });
-  } else if (pmPy === 'uv') {
-    comandos.push({ comando: 'uv sync', proposito: 'Instalar dependencias' });
-    comandos.push({ comando: 'uv run pytest', proposito: 'Tests' });
-  } else if (pmPy === 'pip') {
-    comandos.push({ comando: 'pip install -r requirements.txt', proposito: 'Instalar dependencias' });
-    comandos.push({ comando: 'pytest', proposito: 'Tests' });
-  }
-
-  // Go
-  if (fs.existsSync(path.join(dirProyecto, 'go.mod'))) {
-    comandos.push({ comando: 'go test ./...', proposito: 'Tests' });
-    comandos.push({ comando: 'go build ./...', proposito: 'Build' });
-  }
-
-  // Rust
-  if (fs.existsSync(path.join(dirProyecto, 'Cargo.toml'))) {
-    comandos.push({ comando: 'cargo test', proposito: 'Tests' });
-    comandos.push({ comando: 'cargo build', proposito: 'Build' });
-    comandos.push({ comando: 'cargo clippy', proposito: 'Lint' });
-  }
-
-  return comandos;
-}
-
-/**
- * Detección integral: devuelve resumen del stack del proyecto destino.
- *
- * @returns {{
- *   lenguajePrincipal: { lenguaje: string, runtime?: string } | null,
- *   framework: string | null,
- *   orm: string | null,
- *   packageManager: string | null,
- *   comandos: Array<{ comando: string, proposito: string }>,
- *   detectado: boolean
- * }}
- */
-function detectarStackDetallado(dirProyecto) {
-  const lenguajePrincipal = detectarLenguajePrincipal(dirProyecto);
-  const pkg = leerPackageJson(dirProyecto);
-  const framework = detectarFrameworkNode(pkg) || detectarFrameworkPython(dirProyecto);
-  const orm = detectarORM(pkg, dirProyecto);
-  const packageManager =
-    detectarPackageManagerNode(dirProyecto) || detectarPackageManagerPython(dirProyecto);
-  const comandos = detectarComandos(dirProyecto);
-
-  return {
-    lenguajePrincipal,
-    framework,
-    orm,
-    packageManager,
-    comandos,
-    detectado: lenguajePrincipal !== null,
-  };
-}
-
-// ─── Helpers privados ────────────────────────────────────────────────────────
-
-function _leerJsonSeguro(ruta) {
-  try {
-    if (!fs.existsSync(ruta)) return null;
-    return JSON.parse(fs.readFileSync(ruta, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-function _leerArchivoSeguro(ruta) {
-  try {
-    if (!fs.existsSync(ruta)) return null;
-    return fs.readFileSync(ruta, 'utf8');
-  } catch {
-    return null;
-  }
-}
-
-function _limpiarVersion(rango) {
-  // "^15.0.0" → "15", "~3.4.1" → "3"
-  if (typeof rango !== 'string') return '';
-  const m = rango.match(/(\d+)/);
-  return m ? m[1] : '';
-}
-
-function _propositoScript(nombre) {
-  const map = {
-    dev: 'Servidor de desarrollo',
-    start: 'Iniciar app',
-    build: 'Build de producción',
-    test: 'Tests',
-    lint: 'Lint',
-    typecheck: 'Verificar tipos',
-    format: 'Formatear código',
-  };
-  return map[nombre] || nombre;
-}
-
-module.exports = {
-  detectarStackDetallado,
-  detectarLenguajePrincipal,
-  detectarFrameworkNode,
-  detectarFrameworkPython,
-  detectarORM,
-  detectarPackageManagerNode,
-  detectarPackageManagerPython,
-  detectarComandos,
-  leerPackageJson,
-};
+'use strict';
+
+/**
+ * detectar-stack-detallado.js
+ *
+ * Detecta stack del proyecto destino con información rica para generación de
+ * CLAUDE.md (no solo presencia, sino también: framework principal, scripts
+ * disponibles, package manager, deps clave).
+ *
+ * Diferencia con `detectar-stack.js`: ese módulo es para FILTRAR reglas de
+ * lenguaje (presence/absence). Este módulo es para POBLAR el bloque CLAUDE.md
+ * inyectado por el installer con info accionable del proyecto destino.
+ *
+ * Zero-dependencies (solo fs/path nativos). Defensivo: cualquier read failure
+ * devuelve null/undefined, nunca lanza.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Lee package.json del proyecto destino.
+ * @returns {{ name?: string, version?: string, scripts?: object, dependencies?: object, devDependencies?: object } | null}
+ */
+function leerPackageJson(dirProyecto) {
+  return _leerJsonSeguro(path.join(dirProyecto, 'package.json'));
+}
+
+/**
+ * Detecta el package manager Node usado (basado en lockfile).
+ * @returns {'pnpm' | 'yarn' | 'bun' | 'npm' | null}
+ */
+function detectarPackageManagerNode(dirProyecto) {
+  if (fs.existsSync(path.join(dirProyecto, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(dirProyecto, 'yarn.lock'))) return 'yarn';
+  if (fs.existsSync(path.join(dirProyecto, 'bun.lockb'))) return 'bun';
+  if (fs.existsSync(path.join(dirProyecto, 'package-lock.json'))) return 'npm';
+  if (fs.existsSync(path.join(dirProyecto, 'package.json'))) return 'npm';
+  return null;
+}
+
+/**
+ * Detecta el package manager Python.
+ * @returns {'poetry' | 'uv' | 'pdm' | 'pip' | null}
+ */
+function detectarPackageManagerPython(dirProyecto) {
+  const pyproject = path.join(dirProyecto, 'pyproject.toml');
+  if (fs.existsSync(pyproject)) {
+    const contenido = _leerArchivoSeguro(pyproject) || '';
+    if (contenido.includes('[tool.poetry]')) return 'poetry';
+    if (contenido.includes('[tool.uv]')) return 'uv';
+    if (contenido.includes('[tool.pdm]')) return 'pdm';
+    return 'pip'; // pyproject genérico
+  }
+  if (fs.existsSync(path.join(dirProyecto, 'requirements.txt'))) return 'pip';
+  if (fs.existsSync(path.join(dirProyecto, 'Pipfile'))) return 'pip';
+  return null;
+}
+
+/**
+ * Detecta framework Node a partir de dependencies.
+ * @returns {string | null}
+ */
+function detectarFrameworkNode(packageJson) {
+  if (!packageJson) return null;
+  const deps = { ...(packageJson.dependencies || {}), ...(packageJson.devDependencies || {}) };
+
+  if (deps.next) return `Next.js ${_limpiarVersion(deps.next)}`;
+  if (deps['@angular/core']) return `Angular ${_limpiarVersion(deps['@angular/core'])}`;
+  if (deps['@nestjs/core']) return `NestJS ${_limpiarVersion(deps['@nestjs/core'])}`;
+  if (deps.svelte) return `Svelte ${_limpiarVersion(deps.svelte)}`;
+  if (deps.vue) return `Vue ${_limpiarVersion(deps.vue)}`;
+  if (deps.remix || deps['@remix-run/node']) return 'Remix';
+  if (deps.astro) return `Astro ${_limpiarVersion(deps.astro)}`;
+  if (deps.nuxt) return `Nuxt ${_limpiarVersion(deps.nuxt)}`;
+  if (deps.fastify) return `Fastify ${_limpiarVersion(deps.fastify)}`;
+  if (deps.express) return `Express ${_limpiarVersion(deps.express)}`;
+  if (deps.react) return `React ${_limpiarVersion(deps.react)} (sin framework)`;
+
+  return null;
+}
+
+/**
+ * Detecta framework Python leyendo deps en pyproject.toml o requirements.txt.
+ * @returns {string | null}
+ */
+function detectarFrameworkPython(dirProyecto) {
+  const pyproject = _leerArchivoSeguro(path.join(dirProyecto, 'pyproject.toml')) || '';
+  const requirements = _leerArchivoSeguro(path.join(dirProyecto, 'requirements.txt')) || '';
+  const deps = (pyproject + '\n' + requirements).toLowerCase();
+
+  if (deps.includes('fastapi')) return 'FastAPI';
+  if (deps.includes('django')) return 'Django';
+  if (deps.includes('flask')) return 'Flask';
+  if (deps.includes('starlette')) return 'Starlette';
+  if (deps.includes('aiohttp')) return 'aiohttp';
+  return null;
+}
+
+/**
+ * Detecta el ORM/driver de BD principal.
+ * @returns {string | null}
+ */
+function detectarORM(packageJson, dirProyecto) {
+  const depsNode = packageJson
+    ? { ...(packageJson.dependencies || {}), ...(packageJson.devDependencies || {}) }
+    : {};
+
+  if (depsNode.prisma || depsNode['@prisma/client']) return 'Prisma';
+  if (depsNode['drizzle-orm']) return 'Drizzle';
+  if (depsNode.typeorm) return 'TypeORM';
+  if (depsNode.sequelize) return 'Sequelize';
+  if (depsNode.mongoose) return 'Mongoose';
+
+  // Python
+  const pyproject = _leerArchivoSeguro(path.join(dirProyecto, 'pyproject.toml')) || '';
+  const requirements = _leerArchivoSeguro(path.join(dirProyecto, 'requirements.txt')) || '';
+  const depsPy = (pyproject + '\n' + requirements).toLowerCase();
+  if (depsPy.includes('sqlalchemy')) return 'SQLAlchemy';
+  if (depsPy.includes('peewee')) return 'Peewee';
+  if (depsPy.includes('tortoise-orm')) return 'Tortoise ORM';
+
+  return null;
+}
+
+/**
+ * Detecta lenguaje principal con confianza (devuelve el más probable).
+ * @returns {{ lenguaje: string, runtime?: string } | null}
+ */
+function detectarLenguajePrincipal(dirProyecto) {
+  // Node.js / TypeScript
+  if (fs.existsSync(path.join(dirProyecto, 'package.json'))) {
+    if (fs.existsSync(path.join(dirProyecto, 'tsconfig.json'))) {
+      return { lenguaje: 'TypeScript', runtime: 'Node.js' };
+    }
+    return { lenguaje: 'JavaScript', runtime: 'Node.js' };
+  }
+  // Python
+  if (
+    fs.existsSync(path.join(dirProyecto, 'pyproject.toml')) ||
+    fs.existsSync(path.join(dirProyecto, 'requirements.txt')) ||
+    fs.existsSync(path.join(dirProyecto, 'setup.py'))
+  ) {
+    return { lenguaje: 'Python' };
+  }
+  // Go
+  if (fs.existsSync(path.join(dirProyecto, 'go.mod'))) return { lenguaje: 'Go' };
+  // Rust
+  if (fs.existsSync(path.join(dirProyecto, 'Cargo.toml'))) return { lenguaje: 'Rust' };
+  // Java / Kotlin
+  if (fs.existsSync(path.join(dirProyecto, 'pom.xml'))) return { lenguaje: 'Java', runtime: 'Maven' };
+  if (
+    fs.existsSync(path.join(dirProyecto, 'build.gradle')) ||
+    fs.existsSync(path.join(dirProyecto, 'build.gradle.kts'))
+  ) {
+    return { lenguaje: 'Java/Kotlin', runtime: 'Gradle' };
+  }
+  // PHP
+  if (fs.existsSync(path.join(dirProyecto, 'composer.json'))) return { lenguaje: 'PHP' };
+  // Swift
+  if (fs.existsSync(path.join(dirProyecto, 'Package.swift'))) return { lenguaje: 'Swift' };
+  // Ruby
+  if (fs.existsSync(path.join(dirProyecto, 'Gemfile'))) return { lenguaje: 'Ruby' };
+  // C# / .NET
+  if (fs.existsSync(path.join(dirProyecto, 'global.json'))) return { lenguaje: 'C#', runtime: '.NET' };
+
+  return null;
+}
+
+/**
+ * Detecta scripts comunes del proyecto (test, dev, build, lint).
+ * Devuelve los scripts npm si existen + comandos típicos del lenguaje.
+ *
+ * @returns {Array<{ comando: string, proposito: string }>}
+ */
+function detectarComandos(dirProyecto) {
+  const comandos = [];
+  const pkg = leerPackageJson(dirProyecto);
+  const pm = detectarPackageManagerNode(dirProyecto);
+
+  if (pkg && pkg.scripts) {
+    const interesantes = ['dev', 'start', 'build', 'test', 'lint', 'typecheck', 'format'];
+    for (const script of interesantes) {
+      if (pkg.scripts[script]) {
+        comandos.push({
+          comando: `${pm || 'npm'} run ${script}`,
+          proposito: _propositoScript(script),
+        });
+      }
+    }
+    // Si tiene "test" como entrypoint puro
+    if (pkg.scripts.test && !comandos.some(c => c.comando.includes('test'))) {
+      comandos.push({ comando: `${pm || 'npm'} test`, proposito: 'Tests' });
+    }
+  }
+
+  // Python
+  const pmPy = detectarPackageManagerPython(dirProyecto);
+  if (pmPy === 'poetry') {
+    comandos.push({ comando: 'poetry install', proposito: 'Instalar dependencias' });
+    comandos.push({ comando: 'poetry run pytest', proposito: 'Tests' });
+  } else if (pmPy === 'uv') {
+    comandos.push({ comando: 'uv sync', proposito: 'Instalar dependencias' });
+    comandos.push({ comando: 'uv run pytest', proposito: 'Tests' });
+  } else if (pmPy === 'pip') {
+    comandos.push({ comando: 'pip install -r requirements.txt', proposito: 'Instalar dependencias' });
+    comandos.push({ comando: 'pytest', proposito: 'Tests' });
+  }
+
+  // Go
+  if (fs.existsSync(path.join(dirProyecto, 'go.mod'))) {
+    comandos.push({ comando: 'go test ./...', proposito: 'Tests' });
+    comandos.push({ comando: 'go build ./...', proposito: 'Build' });
+  }
+
+  // Rust
+  if (fs.existsSync(path.join(dirProyecto, 'Cargo.toml'))) {
+    comandos.push({ comando: 'cargo test', proposito: 'Tests' });
+    comandos.push({ comando: 'cargo build', proposito: 'Build' });
+    comandos.push({ comando: 'cargo clippy', proposito: 'Lint' });
+  }
+
+  return comandos;
+}
+
+/**
+ * Detección integral: devuelve resumen del stack del proyecto destino.
+ *
+ * @returns {{
+ *   lenguajePrincipal: { lenguaje: string, runtime?: string } | null,
+ *   framework: string | null,
+ *   orm: string | null,
+ *   packageManager: string | null,
+ *   comandos: Array<{ comando: string, proposito: string }>,
+ *   detectado: boolean
+ * }}
+ */
+function detectarStackDetallado(dirProyecto) {
+  const lenguajePrincipal = detectarLenguajePrincipal(dirProyecto);
+  const pkg = leerPackageJson(dirProyecto);
+  const framework = detectarFrameworkNode(pkg) || detectarFrameworkPython(dirProyecto);
+  const orm = detectarORM(pkg, dirProyecto);
+  const packageManager =
+    detectarPackageManagerNode(dirProyecto) || detectarPackageManagerPython(dirProyecto);
+  const comandos = detectarComandos(dirProyecto);
+
+  return {
+    lenguajePrincipal,
+    framework,
+    orm,
+    packageManager,
+    comandos,
+    detectado: lenguajePrincipal !== null,
+  };
+}
+
+// ─── Helpers privados ────────────────────────────────────────────────────────
+
+function _leerJsonSeguro(ruta) {
+  try {
+    if (!fs.existsSync(ruta)) return null;
+    return JSON.parse(fs.readFileSync(ruta, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function _leerArchivoSeguro(ruta) {
+  try {
+    if (!fs.existsSync(ruta)) return null;
+    return fs.readFileSync(ruta, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function _limpiarVersion(rango) {
+  // "^15.0.0" → "15", "~3.4.1" → "3"
+  if (typeof rango !== 'string') return '';
+  const m = rango.match(/(\d+)/);
+  return m ? m[1] : '';
+}
+
+function _propositoScript(nombre) {
+  const map = {
+    dev: 'Servidor de desarrollo',
+    start: 'Iniciar app',
+    build: 'Build de producción',
+    test: 'Tests',
+    lint: 'Lint',
+    typecheck: 'Verificar tipos',
+    format: 'Formatear código',
+  };
+  return map[nombre] || nombre;
+}
+
+module.exports = {
+  detectarStackDetallado,
+  detectarLenguajePrincipal,
+  detectarFrameworkNode,
+  detectarFrameworkPython,
+  detectarORM,
+  detectarPackageManagerNode,
+  detectarPackageManagerPython,
+  detectarComandos,
+  leerPackageJson,
+};