@eltonssouza/development-utility-kit 1.0.0

package/bin/lib/backup.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Move targetDir/.claude/ to targetDir/.claude.bak/ (overwrites prior backup).
+ * No-op if .claude/ does not exist.
+ *
+ * NOTE: this is the legacy single-slot backup used by `duk install`. The
+ * timestamped backup folders described in ADR-032 are still future work.
+ *
+ * @param {string} targetDir
+ * @param {boolean} dryRun
+ */
+function backupClaudeDir(targetDir, dryRun) {
+  const src = path.join(targetDir, '.claude');
+  const dest = path.join(targetDir, '.claude.bak');
+
+  if (!fs.existsSync(src)) return;
+
+  if (dryRun) {
+    process.stdout.write('  [dry-run] would backup .claude/ -> .claude.bak/\n');
+    return;
+  }
+
+  if (fs.existsSync(dest)) {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+  fs.renameSync(src, dest);
+  process.stdout.write('Note: existing .claude/ backed up to .claude.bak/ (previous backup replaced)\n');
+}
+
+/**
+ * Recursively copy src directory into dest.
+ * Uses fs.cpSync when available (Node 16.7+), falls back to manual walk.
+ * @param {string} src
+ * @param {string} dest
+ */
+function copyDir(src, dest) {
+  if (typeof fs.cpSync === 'function') {
+    fs.cpSync(src, dest, { recursive: true, force: true });
+    return;
+  }
+
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+module.exports = {
+  backupClaudeDir,
+  copyDir,
+};

package/bin/lib/detect-stack.js

@@ -0,0 +1,476 @@
+'use strict';
+
+/**
+ * detect-stack.js — Auto-detect project stack from filesystem signals.
+ *
+ * Reads pom.xml, package.json, pyproject.toml, requirements.txt, go.mod,
+ * and docker-compose.yml from root + 1 level of subdirs. Returns a
+ * normalized stack descriptor. Zero deps; pure fs + regex + JSON.parse.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @typedef {{
+ *   type: 'backend'|'frontend'|'fullstack'|'mobile'|'library'|'cli'|'unknown',
+ *   language: 'java'|'typescript'|'javascript'|'python'|'go'|'node'|'unknown',
+ *   framework: string,
+ *   version: string|null,
+ *   java_version: string|null,
+ *   node_version: string|null,
+ *   python_version: string|null,
+ *   go_version: string|null,
+ *   database: string[],
+ *   ui_lib: string|null,
+ *   detected_from: string[]
+ * }} StackDescriptor
+ */
+
+/**
+ * Read a file as utf8 safely; returns null on any error.
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+function readFileSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse a file as JSON safely.
+ * @param {string} filePath
+ * @returns {object|null}
+ */
+function readJsonSafe(filePath) {
+  const raw = readFileSafe(filePath);
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract a tag value from a snippet of XML using a permissive regex.
+ * Returns null if not found.
+ * @param {string} xml
+ * @param {string} tag
+ * @returns {string|null}
+ */
+function extractXmlTag(xml, tag) {
+  const re = new RegExp(`<${tag}>\\s*([^<\\s]+)\\s*</${tag}>`, 'i');
+  const m = xml.match(re);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Detect Spring Boot version + Java version from a pom.xml string.
+ * @param {string} xml
+ * @returns {{ framework: string, version: string|null, java_version: string|null }|null}
+ */
+function parsePom(xml) {
+  if (!xml) return null;
+  // Java version (multiple common property names)
+  const javaVersion =
+    extractXmlTag(xml, 'java\\.version') ||
+    extractXmlTag(xml, 'maven\\.compiler\\.release') ||
+    extractXmlTag(xml, 'maven\\.compiler\\.source') ||
+    null;
+
+  // Spring Boot detection: <parent> with spring-boot-starter-parent OR explicit dependency
+  const isSpringBoot =
+    /<artifactId>\s*spring-boot-starter-parent\s*<\/artifactId>/i.test(xml) ||
+    /<artifactId>\s*spring-boot-dependencies\s*<\/artifactId>/i.test(xml) ||
+    /org\.springframework\.boot/i.test(xml);
+
+  let version = null;
+  if (isSpringBoot) {
+    // Try parent block first (most reliable)
+    const parentMatch = xml.match(
+      /<parent>[\s\S]*?<artifactId>\s*spring-boot-starter-parent\s*<\/artifactId>[\s\S]*?<version>\s*([^<\s]+)\s*<\/version>[\s\S]*?<\/parent>/i
+    );
+    if (parentMatch) {
+      version = parentMatch[1].trim();
+    } else {
+      version = extractXmlTag(xml, 'spring-boot\\.version') || null;
+    }
+  }
+
+  return {
+    framework: isSpringBoot ? 'spring-boot' : 'java',
+    version,
+    java_version: javaVersion,
+  };
+}
+
+/**
+ * Detect language/framework from a package.json object.
+ * @param {object} pkg
+ * @returns {{
+ *   language: string, framework: string, version: string|null,
+ *   ui_lib: string|null, isMobile: boolean
+ * }|null}
+ */
+function parsePackageJson(pkg) {
+  if (!pkg || typeof pkg !== 'object') return null;
+  const deps = Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
+
+  let framework = 'unknown';
+  let version = null;
+  let ui_lib = null;
+  let isMobile = false;
+  let language = 'javascript';
+
+  if (deps['typescript']) language = 'typescript';
+
+  if (deps['react-native']) {
+    framework = 'react-native';
+    version = stripSemverPrefix(deps['react-native']);
+    isMobile = true;
+  } else if (deps['@angular/core']) {
+    framework = 'angular';
+    version = stripSemverPrefix(deps['@angular/core']);
+    if (deps['@ng-bootstrap/ng-bootstrap']) ui_lib = 'ng-bootstrap';
+    else if (deps['@angular/material']) ui_lib = 'material';
+    else if (deps['tailwindcss']) ui_lib = 'tailwind';
+  } else if (deps['@nestjs/core']) {
+    framework = 'nest';
+    version = stripSemverPrefix(deps['@nestjs/core']);
+  } else if (deps['next']) {
+    framework = 'next';
+    version = stripSemverPrefix(deps['next']);
+    if (deps['tailwindcss']) ui_lib = 'tailwind';
+  } else if (deps['nuxt'] || deps['nuxt3']) {
+    framework = 'nuxt';
+    version = stripSemverPrefix(deps['nuxt'] || deps['nuxt3']);
+  } else if (deps['vue']) {
+    framework = 'vue';
+    version = stripSemverPrefix(deps['vue']);
+  } else if (deps['react']) {
+    framework = 'react';
+    version = stripSemverPrefix(deps['react']);
+    if (deps['@mui/material']) ui_lib = 'material';
+    else if (deps['tailwindcss']) ui_lib = 'tailwind';
+  } else if (deps['express'] || deps['fastify'] || deps['koa']) {
+    framework = deps['fastify'] ? 'fastify' : deps['koa'] ? 'koa' : 'express';
+    version = stripSemverPrefix(deps[framework]);
+    language = deps['typescript'] ? 'typescript' : 'node';
+  }
+
+  // Node engine pin if present
+  return { language, framework, version, ui_lib, isMobile };
+}
+
+/**
+ * Remove leading ^, ~, >=, < from a semver range to extract a usable version.
+ * @param {string} s
+ * @returns {string|null}
+ */
+function stripSemverPrefix(s) {
+  if (!s || typeof s !== 'string') return null;
+  const m = s.match(/(\d+\.\d+(?:\.\d+)?(?:[-+][\w.]+)?)/);
+  return m ? m[1] : null;
+}
+
+/**
+ * Detect Python framework from pyproject.toml or requirements.txt text.
+ * @param {string} text
+ * @returns {{ framework: string, version: string|null, python_version: string|null }|null}
+ */
+function parsePythonDeps(text) {
+  if (!text) return null;
+  const lower = text.toLowerCase();
+
+  // python_requires in pyproject ([project] requires-python = ">=3.12")
+  let python_version = null;
+  const pyReq = text.match(/requires-python\s*=\s*"([^"]+)"/i);
+  if (pyReq) {
+    const m = pyReq[1].match(/(\d+\.\d+)/);
+    python_version = m ? m[1] : null;
+  }
+
+  let framework = 'unknown';
+  let version = null;
+
+  const findPkg = (name) => {
+    // requirements.txt style: "django==5.1.0" or "django>=5"
+    // pyproject style: '"django>=5.1"' or 'django = "5.1"'
+    const re = new RegExp(`["\\s]${name}[\\s=<>~!]+["\\s]*([\\d.]+)`, 'i');
+    const m = text.match(re);
+    return m ? m[1] : null;
+  };
+
+  if (lower.includes('django')) {
+    framework = 'django';
+    version = findPkg('django');
+  } else if (lower.includes('fastapi')) {
+    framework = 'fastapi';
+    version = findPkg('fastapi');
+  } else if (lower.includes('flask')) {
+    framework = 'flask';
+    version = findPkg('flask');
+  } else if (lower.match(/^\s*pyramid\s*[=<>~!]/im)) {
+    framework = 'pyramid';
+    version = findPkg('pyramid');
+  }
+
+  return { framework, version, python_version };
+}
+
+/**
+ * Detect Go framework + version from go.mod text.
+ * @param {string} text
+ * @returns {{ framework: string, version: string|null, go_version: string|null }|null}
+ */
+function parseGoMod(text) {
+  if (!text) return null;
+
+  let go_version = null;
+  const goLine = text.match(/^\s*go\s+(\d+\.\d+(?:\.\d+)?)/m);
+  if (goLine) go_version = goLine[1];
+
+  let framework = 'unknown';
+  let version = null;
+
+  const requirePkg = (pkgPart) => {
+    const re = new RegExp(
+      `${pkgPart.replace(/[/.]/g, '\\$&')}[^\\n]*\\s+v([\\d.]+)`,
+      'i'
+    );
+    const m = text.match(re);
+    return m ? m[1] : null;
+  };
+
+  if (/github\.com\/gin-gonic\/gin/.test(text)) {
+    framework = 'gin';
+    version = requirePkg('github.com/gin-gonic/gin');
+  } else if (/github\.com\/labstack\/echo/.test(text)) {
+    framework = 'echo';
+    version = requirePkg('github.com/labstack/echo');
+  } else if (/github\.com\/gofiber\/fiber/.test(text)) {
+    framework = 'fiber';
+    version = requirePkg('github.com/gofiber/fiber');
+  } else if (/google\.golang\.org\/grpc/.test(text)) {
+    framework = 'grpc';
+    version = requirePkg('google.golang.org/grpc');
+  }
+
+  return { framework, version, go_version };
+}
+
+/**
+ * Detect databases referenced in a docker-compose YAML text.
+ * @param {string} yaml
+ * @returns {string[]}
+ */
+function parseDockerCompose(yaml) {
+  if (!yaml) return [];
+  const dbs = [];
+  const lower = yaml.toLowerCase();
+  if (/\bpostgres(ql)?\b/.test(lower) || /image:\s*postgres/i.test(yaml)) dbs.push('postgres');
+  if (/\bmysql\b/.test(lower) || /image:\s*mysql/i.test(yaml)) dbs.push('mysql');
+  if (/\bmariadb\b/.test(lower)) dbs.push('mariadb');
+  if (/\bmongo(db)?\b/.test(lower) || /image:\s*mongo/i.test(yaml)) dbs.push('mongodb');
+  if (/\bredis\b/.test(lower) || /image:\s*redis/i.test(yaml)) dbs.push('redis');
+  if (/\bcockroach(db)?\b/.test(lower)) dbs.push('cockroachdb');
+  if (/\belasticsearch\b/.test(lower)) dbs.push('elasticsearch');
+  if (/\bkafka\b/.test(lower)) dbs.push('kafka');
+  return Array.from(new Set(dbs));
+}
+
+/**
+ * List files at root + 1 level deep (skip dot-dirs, node_modules, dist, build).
+ * @param {string} cwd
+ * @returns {string[]} absolute paths
+ */
+function listFilesShallow(cwd) {
+  const out = [];
+  const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'target', 'out', '.idea', '.vscode']);
+
+  let rootEntries;
+  try {
+    rootEntries = fs.readdirSync(cwd, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+
+  for (const ent of rootEntries) {
+    const full = path.join(cwd, ent.name);
+    if (ent.isFile()) {
+      out.push(full);
+    } else if (ent.isDirectory() && !ent.name.startsWith('.') && !SKIP_DIRS.has(ent.name)) {
+      try {
+        const subEntries = fs.readdirSync(full, { withFileTypes: true });
+        for (const sub of subEntries) {
+          if (sub.isFile()) out.push(path.join(full, sub.name));
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Detect the project stack from a directory.
+ * @param {string} cwd
+ * @returns {StackDescriptor}
+ */
+function detectStack(cwd) {
+  /** @type {StackDescriptor} */
+  const result = {
+    type: 'unknown',
+    language: 'unknown',
+    framework: 'unknown',
+    version: null,
+    java_version: null,
+    node_version: null,
+    python_version: null,
+    go_version: null,
+    database: [],
+    ui_lib: null,
+    detected_from: [],
+  };
+
+  const files = listFilesShallow(cwd);
+  const basenames = new Map(files.map((f) => [path.basename(f).toLowerCase(), f]));
+
+  let hasBackend = false;
+  let hasFrontend = false;
+  let hasMobile = false;
+
+  // Java / Spring Boot
+  for (const f of files) {
+    if (path.basename(f).toLowerCase() === 'pom.xml') {
+      const xml = readFileSafe(f);
+      const parsed = parsePom(xml);
+      if (parsed) {
+        result.language = 'java';
+        result.framework = parsed.framework;
+        result.version = parsed.version;
+        result.java_version = parsed.java_version;
+        result.detected_from.push(path.relative(cwd, f) || 'pom.xml');
+        hasBackend = true;
+        break; // first pom wins
+      }
+    }
+  }
+
+  // package.json (can coexist with pom.xml → fullstack)
+  for (const f of files) {
+    if (path.basename(f).toLowerCase() === 'package.json') {
+      const pkg = readJsonSafe(f);
+      const parsed = parsePackageJson(pkg);
+      if (parsed && parsed.framework !== 'unknown') {
+        // Don't overwrite Java-detected language; record JS/TS separately
+        if (result.language === 'unknown' || result.language === 'java') {
+          // first non-java package.json takes the language slot if java not set
+          if (result.language === 'unknown') result.language = parsed.language;
+        }
+        // If we don't have a backend framework yet, this becomes primary
+        if (result.framework === 'unknown') {
+          result.framework = parsed.framework;
+          result.version = parsed.version;
+          result.ui_lib = parsed.ui_lib;
+        } else if (result.ui_lib === null && parsed.ui_lib) {
+          result.ui_lib = parsed.ui_lib;
+        }
+
+        // engines.node
+        if (pkg && pkg.engines && pkg.engines.node) {
+          result.node_version = stripSemverPrefix(pkg.engines.node);
+        }
+
+        result.detected_from.push(path.relative(cwd, f) || 'package.json');
+
+        if (parsed.isMobile) hasMobile = true;
+        else if (['angular', 'react', 'vue', 'next', 'nuxt'].includes(parsed.framework)) hasFrontend = true;
+        else if (['nest', 'express', 'fastify', 'koa'].includes(parsed.framework)) hasBackend = true;
+      }
+    }
+  }
+
+  // Python
+  for (const f of files) {
+    const base = path.basename(f).toLowerCase();
+    if (base === 'pyproject.toml' || base === 'requirements.txt' || base === 'setup.py') {
+      const text = readFileSafe(f);
+      const parsed = parsePythonDeps(text);
+      if (parsed) {
+        if (result.language === 'unknown') result.language = 'python';
+        if (result.framework === 'unknown' && parsed.framework !== 'unknown') {
+          result.framework = parsed.framework;
+          result.version = parsed.version;
+        }
+        if (parsed.python_version && !result.python_version) {
+          result.python_version = parsed.python_version;
+        }
+        result.detected_from.push(path.relative(cwd, f) || base);
+        hasBackend = true;
+      }
+    }
+  }
+
+  // Go
+  if (basenames.has('go.mod')) {
+    const goModPath = basenames.get('go.mod');
+    const text = readFileSafe(goModPath);
+    const parsed = parseGoMod(text);
+    if (parsed) {
+      if (result.language === 'unknown') result.language = 'go';
+      if (result.framework === 'unknown') {
+        result.framework = parsed.framework;
+        result.version = parsed.version;
+      }
+      result.go_version = parsed.go_version;
+      result.detected_from.push(path.relative(cwd, goModPath) || 'go.mod');
+      hasBackend = true;
+    }
+  }
+
+  // docker-compose for DB detection
+  for (const f of files) {
+    if (/^docker-compose.*\.ya?ml$/i.test(path.basename(f))) {
+      const yaml = readFileSafe(f);
+      const dbs = parseDockerCompose(yaml);
+      if (dbs.length > 0) {
+        result.database = Array.from(new Set([...result.database, ...dbs]));
+        result.detected_from.push(path.relative(cwd, f) || path.basename(f));
+      }
+    }
+  }
+
+  // Compute type
+  if (hasMobile && !hasBackend && !hasFrontend) {
+    result.type = 'mobile';
+  } else if (hasBackend && hasFrontend) {
+    result.type = 'fullstack';
+  } else if (hasBackend) {
+    result.type = 'backend';
+  } else if (hasFrontend) {
+    result.type = 'frontend';
+  } else if (result.framework !== 'unknown' || result.language !== 'unknown') {
+    // Detected something but couldn't categorize → library / cli fallback
+    result.type = 'library';
+  }
+
+  return result;
+}
+
+module.exports = {
+  detectStack,
+  // Exported for unit-test surface
+  parsePom,
+  parsePackageJson,
+  parsePythonDeps,
+  parseGoMod,
+  parseDockerCompose,
+  stripSemverPrefix,
+};