kcreate-scaffolding-gcp-script 0.0.0-stage → 0.2.0

package/bin/cli.js

@@ -0,0 +1,441 @@
+#!/usr/bin/env node
+/**
+ * kcreate-scaffolding-gcp-script — instalador tipo npx del skill.
+ *
+ *   npx --yes kcreate-scaffolding-gcp-script --target-repo /ruta/al/repo
+ *   npx --yes kcreate-scaffolding-gcp-script uninstall --target-repo /ruta/al/repo
+ *   npx --yes kcreate-scaffolding-gcp-script doctor
+ *
+ * Comandos: install (por defecto) · uninstall · doctor
+ * Flags:    --target-repo RUTA · --skip-tracking · --force
+ *           --with-tracking · --clean-gitignore · -h/--help · -v/--version
+ *
+ * Sin dependencias npm (Node >= 18). Replica exactamente el contrato de
+ * install.sh/uninstall.sh de este repo:
+ *   - destino: <target-repo>/.claude/skills/<skill>/
+ *   - copia atómica (stage + swap), nunca deja el destino a medias
+ *   - exit 0 solo si el skill quedó instalado/actualizado (o desinstalado)
+ *   - exit 1 si no se instaló nada (ya existía sin --force), destino inválido
+ *   - exit 2 si los argumentos son inválidos (igual que el CLI hermano)
+ */
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const SKILL_NAME = 'kcreate-scaffolding-gcp-script';
+const TRACKING_SKILL_NAME = 'github-proyect-tracking';
+const VERSION = require('../package.json').version;
+const SKILL_SRC = path.join(__dirname, '..', 'skill'); // copia empaquetada
+// Dependencia vendorizada, empaquetada por bin/build.js en prepack (viene de
+// vendor/github-proyect-tracking/ en la raíz del repo).
+const TRACKING_SRC = path.join(__dirname, '..', 'vendor', TRACKING_SKILL_NAME);
+
+// ---------------------------------------------------------------------------
+// utilidades
+// ---------------------------------------------------------------------------
+
+const log = (m = '') => console.log(m);
+const ok = (m) => log(`\x1b[32m[OK]\x1b[0m ${m}`);
+const info = (m) => log(`[INFO] ${m}`);
+const warn = (m) => console.log(`\x1b[33m[WARN]\x1b[0m ${m}`);
+const err = (m) => console.error(`\x1b[31m[ERROR]\x1b[0m ${m}`);
+const die = (msg, code = 1) => { err(msg); process.exit(code); };
+
+const COMMANDS = new Set(['install', 'uninstall', 'doctor']);
+// Flags que exigen un valor no vacío.
+const VALUE_FLAGS = new Set(['--target-repo']);
+// Flags booleanos por comando.
+const BOOL_FLAGS = {
+  install: new Set(['--skip-tracking', '--force']),
+  uninstall: new Set(['--with-tracking', '--clean-gitignore']),
+  doctor: new Set([]),
+};
+
+function parseArgs(argv) {
+  const out = { command: null, flags: {}, rest: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') out.flags.help = true;
+    else if (a === '-v' || a === '--version') out.flags.version = true;
+    else if (VALUE_FLAGS.has(a)) {
+      const v = argv[i + 1];
+      if (v === undefined || !v.trim() || v.startsWith('-')) {
+        die(`el flag ${a} requiere un valor no vacío (ej. ${a} /ruta/al/repo)`, 2);
+      }
+      out.flags.targetRepo = v;
+      i++;
+    } else if (a.startsWith('-')) {
+      out.rest.push(a);
+    } else if (out.command === null) {
+      out.command = a;
+    } else {
+      out.rest.push(a);
+    }
+  }
+  if (out.command === null) out.command = 'install';
+  return out;
+}
+
+// validateFlags <command> <flags> -> DETENTE con exit 2 si un flag no
+// corresponde al comando (mismo criterio que el CLI hermano, que rechaza
+// --purge-state fuera de uninstall).
+function validateFlags(command, flags) {
+  const allowed = BOOL_FLAGS[command] || new Set();
+  const known = new Set([...Object.values(BOOL_FLAGS).flatMap((s) => [...s])]);
+  for (const a of flags.rest) {
+    if (!known.has(a)) die(`flag desconocido: ${a} (usa --help)`, 2);
+    if (!allowed.has(a)) die(`${a} no es válido con '${command}' (usa --help)`, 2);
+    const key = a.replace(/^--/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    flags[key] = true;
+  }
+}
+
+function requireGitRepo(p) {
+  if (!fs.existsSync(p) || !fs.statSync(p).isDirectory()) {
+    die(`no existe el directorio: ${p}`, 1);
+  }
+  if (!fs.existsSync(path.join(p, '.git'))) {
+    die(`${p} no es la raíz de un repo git (no tiene .git/). Verifica la ruta.`, 1);
+  }
+}
+
+function resolveTargetRepo(flags) {
+  if (!flags.targetRepo) {
+    die('falta --target-repo /ruta/al/repo (raíz del repo donde instalar el skill)', 2);
+  }
+  const p = path.resolve(flags.targetRepo);
+  requireGitRepo(p);
+  return p;
+}
+
+// cleanCaches <dir> — mismo criterio que install.sh (ksc_copy_skill): nunca
+// copiar __pycache__ ni bytecode al destino.
+function cleanCaches(dir) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === '__pycache__') fs.rmSync(p, { recursive: true, force: true });
+      else cleanCaches(p);
+    } else if (/\.py[co]$/.test(e.name)) {
+      fs.rmSync(p, { force: true });
+    }
+  }
+}
+
+function validateFrontmatter(skillDir, expectedName) {
+  const mdPath = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(mdPath)) throw new Error(`falta ${mdPath}`);
+  const md = fs.readFileSync(mdPath, 'utf8');
+  if (!md.startsWith('---')) throw new Error(`${mdPath}: falta "---" inicial`);
+  const rel = md.slice(3).search(/\n---\s*\n/);
+  if (rel < 0) throw new Error(`${mdPath}: falta cierre "---"`);
+  const fm = md.slice(3, 3 + rel);
+  const name = (fm.match(/^name:\s*(.+?)\s*$/m) || [])[1];
+  if (name !== expectedName) {
+    throw new Error(`${mdPath}: name=${name} (esperado ${expectedName})`);
+  }
+}
+
+// verifySkill <skillDir> — verificación OBLIGATORIA (no un aviso): si el
+// skill está empaquetado a medias, es mejor fallar aquí que instalarlo.
+function verifySkill(skillDir) {
+  validateFrontmatter(skillDir, SKILL_NAME);
+  const required = [
+    'scripts/01_init_config.sh',
+    'scripts/02_print_config.sh',
+    'scripts/10_build_components.sh',
+    'scripts/20_validate_file_parity.sh',
+    'scripts/21_validate_project_pinning.sh',
+    'scripts/run_tracking.sh',
+    'scripts/lib/common.sh',
+    'templates/scaffolding.config.template',
+  ];
+  const missing = required.filter((f) => !fs.existsSync(path.join(skillDir, f)));
+  if (missing.length) {
+    throw new Error(`paquete corrupto, faltan: ${missing.join(', ')}`);
+  }
+}
+
+// verifyTracking <skillDir> — la dependencia es un requisito del skill, pero
+// install.sh permite --skip-tracking: se valida solo si se va a instalar.
+function verifyTracking(skillDir) {
+  validateFrontmatter(skillDir, TRACKING_SKILL_NAME);
+  if (!fs.existsSync(path.join(skillDir, 'scripts', 'tracking.py'))) {
+    throw new Error(`paquete corrupto: falta ${skillDir}/scripts/tracking.py`);
+  }
+}
+
+// copyModes <src> <dest> — replica los permisos de los hijos del origen, como
+// hace `cp -R` (que install.sh usa): node copia con 644/755 por defecto y eso
+// dejaría los scripts sin los bits que tienen en el repo. El directorio raíz
+// del stage NO se toca: install.sh lo hereda de `mktemp -d` (0700) y aquí se
+// replica igual para que el resultado sea idéntico con los dos instaladores.
+function copyModes(src, dest) {
+  let st;
+  try {
+    st = fs.lstatSync(src);
+  } catch { return; }
+  try { fs.chmodSync(dest, st.mode & 0o7777); } catch { /* noop */ }
+  if (!st.isDirectory()) return;
+  for (const name of fs.readdirSync(src)) {
+    copyModes(path.join(src, name), path.join(dest, name));
+  }
+}
+
+// copyAtomic <src> <dest> <label> — stage + swap, como ksc_copy_skill.
+function copyAtomic(src, dest, label) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const stage = fs.mkdtempSync(path.join(path.dirname(dest), '.ksc-install.'));
+  try {
+    fs.cpSync(src, stage, { recursive: true });
+    cleanCaches(stage);
+    // Permisos: los hijos según el origen; el stage conserva el 0700 de
+    // mkdtemp (igual que install.sh) y ese modo pasa a ser el del destino.
+    for (const name of fs.readdirSync(src)) {
+      copyModes(path.join(src, name), path.join(stage, name));
+    }
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.renameSync(stage, dest);
+    ok(`${label} instalado en ${dest}`);
+  } catch (e) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    throw e;
+  }
+}
+
+// addExecBits <file> — replica exactamente `chmod +x` de install.sh (suma
+// los bits de ejecución a los que ya tenía, sin normalizar a 755), para que
+// los permisos del destino sean idénticos con los dos instaladores.
+function addExecBits(file) {
+  try {
+    const mode = fs.statSync(file).mode & 0o7777;
+    fs.chmodSync(file, mode | 0o111);
+  } catch { /* noop */ }
+}
+
+function chmodScripts(skillDir) {
+  const dirs = [path.join(skillDir, 'scripts'), path.join(skillDir, 'scripts', 'lib')];
+  for (const d of dirs) {
+    if (!fs.existsSync(d)) continue;
+    for (const f of fs.readdirSync(d)) {
+      if (f.endsWith('.sh')) addExecBits(path.join(d, f));
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// comandos
+// ---------------------------------------------------------------------------
+
+function install(flags) {
+  const target = resolveTargetRepo(flags);
+  if (!fs.existsSync(path.join(target, 'live'))) {
+    warn(`${target} no tiene un directorio live/ — este skill asume la convención ` +
+         'live/<entorno>/<componente>/terragrunt.hcl. Puede fallar.');
+  }
+
+  const skillsDir = path.join(target, '.claude', 'skills');
+  const destMain = path.join(skillsDir, SKILL_NAME);
+  const destTracking = path.join(skillsDir, TRACKING_SKILL_NAME);
+
+  // El skill y su dependencia se validan ANTES de tocar el destino: si el
+  // paquete está roto, no se deja una instalación parcial.
+  try {
+    verifySkill(SKILL_SRC);
+  } catch (e) {
+    die(e.message, 2);
+  }
+  if (!flags.skipTracking) {
+    try {
+      verifyTracking(TRACKING_SRC);
+    } catch (e) {
+      die(`no se puede instalar ${TRACKING_SKILL_NAME}: ${e.message} ` +
+          '(usa --skip-tracking solo si el repo destino ya lo gestiona por su cuenta)', 2);
+    }
+  }
+
+  let mainInstalled = false;
+  if (fs.existsSync(destMain) && !flags.force) {
+    err(`${SKILL_NAME} ya existe en ${destMain} — usa --force para sobreescribir.`);
+  } else {
+    copyAtomic(SKILL_SRC, destMain, SKILL_NAME);
+    chmodScripts(destMain);
+    mainInstalled = true;
+  }
+
+  let trackingInstalled = false;
+  if (flags.skipTracking) {
+    info(`--skip-tracking: no se tocó ${TRACKING_SKILL_NAME}`);
+  } else if (fs.existsSync(destTracking) && !flags.force) {
+    info(`${TRACKING_SKILL_NAME} ya existe en el destino — no se sobreescribe (usa --force).`);
+  } else {
+    copyAtomic(TRACKING_SRC, destTracking, TRACKING_SKILL_NAME);
+    addExecBits(path.join(destTracking, 'scripts', 'tracking.py'));
+    trackingInstalled = true;
+  }
+
+  log();
+  // Mismo contrato que install.sh: exit 0 ⇔ el skill quedó instalado.
+  if (!mainInstalled) {
+    die('No se instaló nada. Vuelve a correr con --force para sobreescribir ' +
+        'la instalación existente.', 1);
+  }
+
+  ok(`Instalación completa en ${target}`);
+  if (!trackingInstalled) info(`${TRACKING_SKILL_NAME} no fue (re)instalado en esta corrida.`);
+  log('Siguiente paso: desde una sesión de Claude Code abierta en ese repo,');
+  log('invoca el skill con:');
+  log();
+  log(`  /${SKILL_NAME} <SOURCE_ENV> <NEW_ENV>`);
+  log();
+  log(`Ejemplo: /${SKILL_NAME} boletera-qa xoloshop-prod`);
+}
+
+function uninstall(flags) {
+  const target = resolveTargetRepo(flags);
+  const skillsDir = path.join(target, '.claude', 'skills');
+  const destMain = path.join(skillsDir, SKILL_NAME);
+  const destTracking = path.join(skillsDir, TRACKING_SKILL_NAME);
+
+  if (fs.existsSync(destMain)) {
+    fs.rmSync(destMain, { recursive: true, force: true });
+    ok(`eliminado ${destMain}`);
+  } else {
+    info(`${SKILL_NAME} no estaba instalado en ${target}`);
+  }
+
+  if (flags.withTracking) {
+    if (fs.existsSync(destTracking)) {
+      fs.rmSync(destTracking, { recursive: true, force: true });
+      ok(`eliminado ${destTracking}`);
+    } else {
+      info(`${TRACKING_SKILL_NAME} no estaba instalado en ${target}`);
+    }
+  }
+
+  if (flags.cleanGitignore) {
+    const gitignore = path.join(target, '.gitignore');
+    const markers = [
+      '.kcreate-scaffolding/',
+      '# kcreate-scaffolding-gcp-script: configuracion de ejecucion, no comitear',
+    ];
+    if (fs.existsSync(gitignore)) {
+      const text = fs.readFileSync(gitignore, 'utf8');
+      const endsWithNewline = text.endsWith('\n');
+      const lines = endsWithNewline ? text.slice(0, -1).split('\n') : text.split('\n');
+      const kept = [];
+      for (const line of lines) {
+        if (markers.includes(line)) continue;
+        // colapsar líneas en blanco consecutivas, igual que `cat -s` en
+        // uninstall.sh (que es la implementación de referencia).
+        if (line === '' && kept.length && kept[kept.length - 1] === '') continue;
+        kept.push(line);
+      }
+      fs.writeFileSync(
+        gitignore,
+        kept.join('\n') + (endsWithNewline && kept.length ? '\n' : '')
+      );
+      ok(`quitada la línea .kcreate-scaffolding/ de ${gitignore}`);
+    }
+    const stateDir = path.join(target, '.kcreate-scaffolding');
+    if (fs.existsSync(stateDir)) {
+      fs.rmSync(stateDir, { recursive: true, force: true });
+      ok(`eliminado ${stateDir}/`);
+    }
+  }
+  log('Listo.');
+}
+
+// doctor — diagnóstico SIN tocar nada: qué hay instalado en el repo destino y
+// si sus dependencias (bash/python3/terragrunt/git) están disponibles.
+function doctor(flags) {
+  const target = resolveTargetRepo(flags);
+  const destMain = path.join(target, '.claude', 'skills', SKILL_NAME);
+  const destTracking = path.join(target, '.claude', 'skills', TRACKING_SKILL_NAME);
+
+  log(`kcreate-scaffolding-gcp-script/${VERSION} (instalador npx)`);
+  log(`repo destino : ${target}`);
+  log(`live/        : ${fs.existsSync(path.join(target, 'live')) ? 'sí' : 'NO (el skill asumirá live/<env>/...)'}`);
+  log(`skill        : ${fs.existsSync(destMain) ? destMain : 'no instalado'}`);
+  log(`tracking     : ${fs.existsSync(destTracking) ? destTracking : 'no instalado'}`);
+  log();
+
+  const checks = [
+    ['bash', ['--version']],
+    ['git', ['--version']],
+    ['python3', ['-c', 'import ipaddress; print("ipaddress OK")']],
+    ['curl', ['--version']],
+    ['terragrunt', ['--version']],
+  ];
+  let blocking = 0;
+  for (const [cmd, args] of checks) {
+    const r = spawnSync(cmd, args, { encoding: 'utf8' });
+    const available = !r.error;
+    const optional = cmd === 'terragrunt';
+    if (available) {
+      const first = (r.stdout || '').trim().split('\n')[0];
+      ok(`${cmd}: ${first}`);
+    } else if (optional) {
+      warn(`${cmd}: no disponible (opcional — omite hcl fmt/validate al construir)`);
+    } else {
+      err(`${cmd}: NO disponible (requerido por los scripts del skill)`);
+      blocking++;
+    }
+  }
+  log();
+  if (blocking) {
+    err(`${blocking} requisito(s) faltante(s) — el skill fallará sin ellos.`);
+    process.exit(1);
+  }
+  ok('Entorno listo para usar el skill.');
+}
+
+// ---------------------------------------------------------------------------
+// ayuda y main
+// ---------------------------------------------------------------------------
+
+function help() {
+  log(`${SKILL_NAME} v${VERSION} — instalador npx del skill`);
+  log();
+  log('Uso:');
+  log(`  npx --yes ${SKILL_NAME} --target-repo /ruta/al/repo        instalar (o actualizar)`);
+  log(`  npx --yes ${SKILL_NAME} uninstall --target-repo /ruta     desinstalar`);
+  log(`  npx --yes ${SKILL_NAME} doctor --target-repo /ruta        diagnóstico sin cambios`);
+  log();
+  log('Flags de install:');
+  log('  --target-repo RUTA   raíz del repo destino (debe ser un repo git)  [obligatorio]');
+  log('  --skip-tracking      no instala/actualiza github-proyect-tracking');
+  log('  --force              sobreescribe una instalación existente');
+  log();
+  log('Flags de uninstall:');
+  log('  --with-tracking      elimina también github-proyect-tracking');
+  log('  --clean-gitignore    quita .kcreate-scaffolding/ del .gitignore y borra la carpeta');
+  log();
+  log('  -h, --help           esta ayuda');
+  log('  -v, --version        versión del paquete');
+  log();
+  log('Destino: <repo>/.claude/skills/kcreate-scaffolding-gcp-script/ (+ github-proyect-tracking/).');
+  log('Requisitos: Node >= 18 para este instalador; bash, git, python3 3.8+, curl y');
+  log('GNU sed para los scripts; terragrunt opcional. Instalar el skill NO crea nada');
+  log('en GCP: solo prepara la herramienta.');
+}
+
+function main() {
+  const { command, flags, rest } = parseArgs(process.argv.slice(2));
+  if (flags.version) { log(`${SKILL_NAME}/${VERSION} (instalador npx)`); return; }
+  if (flags.help) { help(); return; }
+  if (!COMMANDS.has(command)) die(`comando desconocido: ${command} (usa --help)`, 2);
+  flags.rest = rest;
+  validateFlags(command, flags);
+
+  switch (command) {
+    case 'install': install(flags); break;
+    case 'uninstall': uninstall(flags); break;
+    case 'doctor': doctor(flags); break;
+  }
+}
+
+main();

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "kcreate-scaffolding-gcp-script",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Instalador npx del skill kcreate-scaffolding-gcp-script: genera el scaffolding de Terragrunt para un entorno GCP nuevo a partir de uno existente.",
+  "bin": {
+    "kcreate-scaffolding-gcp-script": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skill/",
+    "vendor/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node bin/build.js",
+    "prepack": "node bin/build.js"
+  },
+  "keywords": [
+    "terragrunt",
+    "terraform",
+    "gcp",
+    "scaffolding",
+    "skill",
+    "claude-code",
+    "instalador"
+  ],
+  "author": "Rommel (https://github.com/rommelmg)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kronops/KCreateScaffoldingGCPScripts.git"
+  },
+  "private": false
+}