siesa-agents 2.1.83 → 2.1.84

package/bin/folder-mappings.js

@@ -0,0 +1,79 @@
+// folder-mappings.js — Single source of truth for the source→target mapping used by the
+// installer (install.js) and the publish helpers (prepare-publish.js / restore-folders.js).
+//
+// Background — the dual-mirror pattern this repo uses:
+//   Every folder that ships with the npm package exists twice in the dev tree:
+//     - The "dotted/underscored" version used by the dev workflow:
+//         `.claude/`, `.github/`, `.gemini/`, `.resources/`, `.mcp.json`, `.vscode/`,
+//         `_bmad/`, `_siesa-agents/`
+//     - The "flat" version that is what npm publish actually packages and ships:
+//         `claude/`, `github/`, `gemini/`, `resources/`, `mcp.json`, `vscode/`,
+//         `bmad/`, `siesa-agents/`
+//   When you edit anything under `.claude/skills/`, you must mirror the change into
+//   `claude/skills/`. The installer reads from the flat (tarball) names and writes to the
+//   dotted (user project) names.
+//
+// Why both? npm's `files` array historically had quirks with dot-prefixed entries
+// (`.github/` would sometimes ship, sometimes not, depending on npm version and registry
+// rules). Keeping a flat copy guarantees the file ships, while keeping the dotted copy
+// keeps the dev workflow honest (`.claude/` is what Claude Code reads, `.github/` is what
+// GitHub Actions reads).
+//
+// Three views of the same data:
+//   - installerMappings()   used by bin/install.js: { source = tarball name,
+//                           target = user project name }
+//   - publishRenames()      used by bin/prepare-publish.js. Currently empty — see comment
+//                           on the FOLDERS array.
+//   - restoreRenames()      used by bin/restore-folders.js. Currently empty — see comment.
+//
+// Add new folders here and the rest of the pipeline picks them up. If a new folder needs
+// pre-publish renaming (only when there's no flat mirror in dev), add a `devSource`.
+
+'use strict';
+
+// Each entry describes one shipping unit:
+//   - tarball:     name inside the published npm tarball (no leading `.` or `_`)
+//   - userProject: name in the user's project after `npx siesa-agents`
+//   - devSource:   optional — pre-publish rename source. Leave it `null` when the dev tree
+//                  already maintains both the dotted AND the flat copy (current strategy
+//                  for every folder shipped today). Only set it if you want the publish
+//                  pipeline to physically rename the dev folder before `npm publish`.
+const FOLDERS = [
+  { tarball: 'bmad',          userProject: '_bmad',          devSource: null },
+  { tarball: 'siesa-agents',  userProject: '_siesa-agents',  devSource: null },
+  { tarball: 'vscode',        userProject: '.vscode',        devSource: null },
+  { tarball: 'github',        userProject: '.github',        devSource: null },
+  { tarball: 'claude',        userProject: '.claude',        devSource: null },
+  { tarball: 'gemini',        userProject: '.gemini',        devSource: null },
+  { tarball: 'resources',     userProject: '.resources',     devSource: null },
+  { tarball: 'mcp.json',      userProject: '.mcp.json',      devSource: null },
+];
+
+// Shape expected by install.js: { source, target } where source is the tarball name and
+// target is what to call it in the user's project.
+function installerMappings() {
+  return FOLDERS.map(f => ({ source: f.tarball, target: f.userProject }));
+}
+
+// Shape expected by prepare-publish.js: { from, to } where from is the dev name and to is
+// the tarball name. Empty when the dev tree already maintains dual-mirror copies.
+function publishRenames() {
+  return FOLDERS
+    .filter(f => f.devSource && f.devSource !== f.tarball)
+    .map(f => ({ from: f.devSource, to: f.tarball }));
+}
+
+// Inverse of publishRenames: restore tarball names back to dev names. Empty in the
+// dual-mirror strategy.
+function restoreRenames() {
+  return FOLDERS
+    .filter(f => f.devSource && f.devSource !== f.tarball)
+    .map(f => ({ from: f.tarball, to: f.devSource }));
+}
+
+module.exports = {
+  FOLDERS,
+  installerMappings,
+  publishRenames,
+  restoreRenames,
+};

package/bin/install.js

@@ -2,27 +2,91 @@
 
 const fs = require('fs-extra');
 const path = require('path');
-const { sourceMapsEnabled } = require('process');
-const readline = require('readline');
 const { execSync } = require('child_process');
+const { installerMappings } = require('./folder-mappings');
+
+// @clack/prompts es ESM-only, así que desde este install.js CJS lo cargamos con
+// dynamic `import()`. Cachéamos la promesa para que la primera carga pague el
+// costo de resolución y las siguientes sean instantáneas.
+let _clackPromise = null;
+function loadClack() {
+  if (!_clackPromise) {
+    _clackPromise = import('@clack/prompts');
+  }
+  return _clackPromise;
+}
+
+// En Windows oculta/des-oculta una carpeta o archivo (atributo +h/-h). Sirve para
+// que las carpetas de staging `.sa-new`/`.sa-old` no aparezcan en el explorador
+// durante el breve lapso en que existen — verlas crearse y borrarse se ve raro.
+// Best-effort: si `attrib` falla no pasa nada (es puramente cosmético). No-op
+// fuera de Windows (en Unix el prefijo `.` ya las oculta en la mayoría de FMs).
+function setHidden(targetPath, hidden) {
+  if (process.platform !== 'win32') return;
+  try {
+    execSync(`attrib ${hidden ? '+h' : '-h'} "${targetPath}"`, { stdio: 'ignore' });
+  } catch (_) { /* cosmético: ignorar */ }
+}
+
+// Maneja la cancelación de un prompt clack (Ctrl+C / Esc). Sale limpio con
+// código 0 — no es un error, el usuario explícitamente abortó.
+async function bailIfCancel(value) {
+  const clack = await loadClack();
+  if (clack.isCancel(value)) {
+    clack.cancel('Instalación cancelada por el usuario.');
+    process.exit(0);
+  }
+  return value;
+}
+
+// Parse argumentos CLI básicos. Soporta:
+//   --yes / -y           Modo no-interactivo: usa defaults sensatos en cualquier prompt
+//                        en vez de leer de stdin. Defaults: "hacer backup de modificados"
+//                        (opción 2) y "no hay repo remoto" (opción 2). También se activa
+//                        automáticamente cuando stdin no es un TTY (CI, pipes).
+//   --version            Imprime la versión del paquete y sale.
+//   --help / -h          Imprime ayuda breve y sale.
+function parseCliArgs(argv) {
+  const out = { yes: false, version: false, help: false };
+  for (const a of argv) {
+    if (a === '--yes' || a === '-y') out.yes = true;
+    else if (a === '--version') out.version = true;
+    else if (a === '--help' || a === '-h') out.help = true;
+  }
+  return out;
+}
+
+// Deep-merge de dos objetos JSON. Source gana en conflictos; los arrays se
+// reemplazan completos (no se hace merge elemento-a-elemento). Pensado para
+// `.mcp.json`: los MCPs que el usuario agregó (no existen en el paquete) sobreviven
+// al update mientras los nativos se actualizan a la versión del paquete.
+function deepMergeJson(target, source) {
+  if (source === null || typeof source !== 'object') return source;
+  if (target === null || typeof target !== 'object') return source;
+  if (Array.isArray(source) || Array.isArray(target)) return source;
+  const out = { ...target };
+  for (const key of Object.keys(source)) {
+    out[key] = deepMergeJson(target[key], source[key]);
+  }
+  return out;
+}
 
 class SiesaBmadInstaller {
-  constructor() {
-    // Definir las carpetas primero (nombres en el paquete vs nombres finales)
-    this.folderMappings = [
-      { source: 'bmad', target: '_bmad' },
-      { source: 'siesa-agents', target: '_siesa-agents' },
-      { source: 'vscode', target: '.vscode' },
-      { source: 'github', target: '.github' },
-      { source: 'claude', target: '.claude' },
-      { source: 'gemini', target: '.gemini' },
-      { source: 'resources', target: '.resources' },
-      { source: 'mcp.json', target: '.mcp.json' }
-    ];
-    
-    // Lista de archivos que se preservan automáticamente (no se crean backups)
+  constructor(cliArgs = {}) {
+    // Definir las carpetas primero (nombres en el paquete vs nombres finales).
+    // Source of truth: bin/folder-mappings.js
+    this.folderMappings = installerMappings();
+
+    // Archivos que el instalador PRESERVA: no se sobrescriben si ya existen, no se
+    // reportan como "modificados" y no se les hace backup. El usuario los personaliza
+    // localmente y son suyos.
+    //   - data/technical-preferences.md → preferencias del usuario.
+    //   - settings.json → `.vscode/settings.json` (la única carpeta del paquete con
+    //     un settings.json en su raíz es `.vscode`, así que el match es inequívoco).
+    //     El usuario ajusta su editor; el instalador no debe pisarlo ni molestar.
     this.ignoredFiles = [
-      'data/technical-preferences.md'
+      'data/technical-preferences.md',
+      'settings.json'
     ];
 
     // Directorios base que se deben crear siempre durante la instalación
@@ -33,9 +97,14 @@ class SiesaBmadInstaller {
     this.targetDir = process.cwd();
     // Intentar múltiples ubicaciones posibles para el paquete
     this.packageDir = this.findPackageDir();
-    
+
     // Almacenamiento temporal para contenido de archivos ignorados
     this.preservedContent = new Map();
+
+    // Flag no-interactivo: opt-in via --yes/-y o auto-detectado cuando stdin no es TTY
+    // (típicamente CI, npx detrás de pipes, scripts automatizados). Si está activo, los
+    // prompts usan defaults en vez de bloquearse esperando input.
+    this.nonInteractive = Boolean(cliArgs.yes) || !process.stdin.isTTY;
   }
   
 
@@ -121,27 +190,39 @@ class SiesaBmadInstaller {
   }
 
   async promptHasRepository() {
-    console.log('\n¿Tienes un repositorio remoto?');
-    console.log('1. Sí');
-    console.log('2. No, parametrizar manual después');
-
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-      rl.question('\nElige una opción (1 o 2): ', (answer) => {
-        rl.close();
-        resolve(answer.trim());
-      });
+    if (this.nonInteractive) {
+      console.log('\n  (modo no-interactivo: sin repositorio remoto)');
+      return '2';
+    }
+
+    const clack = await loadClack();
+    const answer = await clack.select({
+      message: '¿Tienes un repositorio remoto que quieras vincular ahora?',
+      options: [
+        { value: '2', label: 'No, lo configuraré después', hint: 'recomendado si todavía no creaste el repo' },
+        { value: '1', label: 'Sí, tengo URL del repo remoto' },
+      ],
+      initialValue: '2',
     });
+    return bailIfCancel(answer);
   }
 
   async promptRepositoryUrl() {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-      rl.question('Ingresa la URL del repositorio: ', (answer) => {
-        rl.close();
-        resolve(answer.trim());
-      });
+    if (this.nonInteractive) {
+      // En modo no-interactivo nunca deberíamos llegar aquí (promptHasRepository
+      // devuelve '2'), pero por defensa devolvemos cadena vacía.
+      return '';
+    }
+    const clack = await loadClack();
+    const answer = await clack.text({
+      message: 'URL del repositorio',
+      placeholder: 'https://github.com/<org>/<repo>.git',
+      validate: (value) => {
+        if (!value || value.trim() === '') return 'La URL no puede estar vacía';
+      },
     });
+    const checked = await bailIfCancel(answer);
+    return checked.trim();
   }
 
   async installGitignore() {
@@ -149,7 +230,9 @@ class SiesaBmadInstaller {
     const entries = [
       'node_modules/',
       '.claude/commands/get-features/oauth-config.json',
-      '.claude/commands/get-features/tokens.json'
+      '.claude/commands/get-features/tokens.json',
+      '.vscode/settings.json',
+      '.claude.json'
     ];
 
     let content = entries.join('\n') + '\n';
@@ -268,6 +351,13 @@ class SiesaBmadInstaller {
     const modifiedFiles = [];
 
     for (const mapping of this.folderMappings) {
+      // .mcp.json no entra en la detección de modificaciones: se gestiona con
+      // deep-merge JSON en performAtomicUpdate / copyWithBackupPreservation, que
+      // preserva los MCPs personalizados del usuario y actualiza los nativos.
+      // Marcarlo como "modificado" forzaría el flujo backup-y-reemplaza y
+      // destruiría los MCPs custom.
+      if (mapping.target === '.mcp.json') continue;
+
       const sourcePath = path.join(this.packageDir, mapping.source);
       const targetPath = path.join(this.targetDir, mapping.target);
 
@@ -284,9 +374,13 @@ class SiesaBmadInstaller {
 
         if (fs.existsSync(targetFile)) {
           try {
-            // Comparar contenido de archivos
-            const sourceContent = await fs.readFile(sourceFile, 'utf8');
-            const targetContent = await fs.readFile(targetFile, 'utf8');
+            // Comparar contenido normalizando CRLF→LF. Sin esta normalización, en Windows
+            // con `core.autocrlf=true` cualquier archivo de texto cuya copia local fue
+            // checkout con CRLF aparece como "modificado" frente al paquete (que tiene LF),
+            // y el instalador pide backup en cada corrida aunque el usuario no haya tocado
+            // nada.
+            const sourceContent = (await fs.readFile(sourceFile, 'utf8')).replace(/\r\n/g, '\n');
+            const targetContent = (await fs.readFile(targetFile, 'utf8')).replace(/\r\n/g, '\n');
 
             if (sourceContent !== targetContent) {
               modifiedFiles.push({
@@ -297,7 +391,8 @@ class SiesaBmadInstaller {
               });
             }
           } catch (error) {
-            // Si no se puede leer como texto, comparar como buffer (archivos binarios)
+            // Si no se puede leer como texto, comparar como buffer (archivos binarios).
+            // Para binarios la normalización CRLF no aplica.
             const sourceBuffer = await fs.readFile(sourceFile);
             const targetBuffer = await fs.readFile(targetFile);
 
@@ -341,22 +436,26 @@ class SiesaBmadInstaller {
   }
 
   async promptUser(modifiedFiles) {
+    // modifiedFiles solo contiene archivos QUE EXISTEN EN EL PAQUETE y cuyo
+    // contenido difiere del target. Es decir: archivos del paquete (skills nativas,
+    // configs nativas, etc.) que el usuario modificó localmente. Los archivos que
+    // el usuario AGREGÓ y no están en el paquete (skills custom, flows propios,
+    // MCPs adicionales) NO aparecen aquí — se preservan automáticamente en
+    // performAtomicUpdate / copyWithBackupPreservation sin pedir permiso.
+    const nonIgnoredFiles = modifiedFiles.filter(f => !f.is_ignored);
+    if (nonIgnoredFiles.length === 0) return '2';
 
-    const hasNonIgnoredFiles = modifiedFiles.some(file => file.is_ignored == false)
-    if (!hasNonIgnoredFiles) return '2'
-
-    console.log('\n⚠️  Se detectaron archivos modificados:');
+    console.log(`\n⚠️  Detecté ${nonIgnoredFiles.length} archivo(s) del paquete Siesa-Agents que modificaste localmente:`);
 
     // Agrupar por carpeta
     const filesByFolder = {};
-    modifiedFiles.forEach(item => {
+    nonIgnoredFiles.forEach(item => {
       if (!filesByFolder[item.folder]) {
         filesByFolder[item.folder] = [];
       }
       filesByFolder[item.folder].push(item.file);
     });
 
-    // Mostrar archivos modificados por carpeta
     Object.keys(filesByFolder).forEach(folder => {
       console.log(`\n📁 ${folder}:`);
       filesByFolder[folder].forEach(file => {
@@ -364,21 +463,24 @@ class SiesaBmadInstaller {
       });
     });
 
-    console.log('\n¿Qué deseas hacer?');
-    console.log('1. Reemplazar todos los archivos (se perderán las modificaciones)');
-    console.log('2. Hacer backup de archivos modificados (se agregarán con sufijo _bk)');
+    console.log('\nℹ️  Tus skills/flows/MCPs propios (los que NO vienen en el paquete) se');
+    console.log('   preservan automáticamente — no aparecen en la lista de arriba.');
 
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout
-    });
+    if (this.nonInteractive) {
+      console.log('\n  (modo no-interactivo: backup de tus cambios)');
+      return '2';
+    }
 
-    return new Promise((resolve) => {
-      rl.question('\nElige una opción (1 o 2): ', (answer) => {
-        rl.close();
-        resolve(answer.trim());
-      });
+    const clack = await loadClack();
+    const answer = await clack.select({
+      message: '¿Qué hago con TUS cambios sobre los archivos del paquete?',
+      options: [
+        { value: '2', label: 'Backup y actualizar', hint: 'guarda tus cambios con sufijo _bk + trae la versión del paquete (recomendado)' },
+        { value: '1', label: 'Reemplazar', hint: 'pierdes tus modificaciones — sin backup' },
+      ],
+      initialValue: '2',
     });
+    return bailIfCancel(answer);
   }
 
   async backupModifiedFiles(modifiedFiles) {
@@ -419,22 +521,31 @@ class SiesaBmadInstaller {
 
     // Primer intento: archivo_bk.ext
     const basicBackupPath = path.join(dir, `${name}_bk${ext}`);
-
-    // Si no existe, usar el nombre básico
     if (!fs.existsSync(basicBackupPath)) {
       return basicBackupPath;
     }
 
-    // Si ya existe _bk, crear versión con timestamp
+    // Si ya existe _bk, crear versión con timestamp. Incluimos milisegundos para
+    // evitar colisiones cuando dos backups del mismo archivo ocurren en el mismo
+    // segundo (p.ej. instalador corriendo en bucle / tests). Y por si dos backups
+    // caen en el mismo ms (esencialmente imposible pero defensivo), agregamos un
+    // contador incremental.
     const now = new Date();
     const timestamp = now.getFullYear().toString() +
       (now.getMonth() + 1).toString().padStart(2, '0') +
       now.getDate().toString().padStart(2, '0') + '_' +
       now.getHours().toString().padStart(2, '0') +
       now.getMinutes().toString().padStart(2, '0') +
-      now.getSeconds().toString().padStart(2, '0');
-
-    return path.join(dir, `${name}_bk_${timestamp}${ext}`);
+      now.getSeconds().toString().padStart(2, '0') +
+      now.getMilliseconds().toString().padStart(3, '0');
+
+    let candidate = path.join(dir, `${name}_bk_${timestamp}${ext}`);
+    let counter = 1;
+    while (fs.existsSync(candidate)) {
+      candidate = path.join(dir, `${name}_bk_${timestamp}_${counter}${ext}`);
+      counter++;
+    }
+    return candidate;
   }
 
   async performUpdateWithBackups() {
@@ -454,21 +565,33 @@ class SiesaBmadInstaller {
   async copyWithBackupPreservation(sourcePath, targetPath) {
     // Obtener todos los archivos backup existentes
     const backupFiles = await this.findBackupFiles(targetPath);
-    
-    // Copiar la carpeta preservando technical-preferences.md
-    await fs.copy(sourcePath, targetPath, {
-      overwrite: true,
-      recursive: true,
-      filter: (src) => {
-        const relativePath = path.relative(sourcePath, src);
-        // No sobrescribir archivos ignorados si ya existen
-        if (this.ignoredFiles.includes(relativePath)) {
-          const targetFile = path.join(targetPath, relativePath);
-          return !fs.existsSync(targetFile);
+
+    const sourceIsFile = (await fs.stat(sourcePath)).isFile();
+
+    if (sourceIsFile) {
+      // File mapping (.mcp.json u otros). Para .mcp.json hacemos deep-merge JSON
+      // para preservar MCPs personalizados; para cualquier otro archivo,
+      // copia directa (source-wins).
+      await this.applyFileMapping(sourcePath, targetPath, targetPath);
+    } else {
+      // Folder mapping. fs.copy con overwrite=true sobre el target es un merge:
+      // actualiza archivos que ya existían y agrega los nuevos, dejando intactos
+      // los archivos del target que no aparecen en el source (skills custom,
+      // flujos agregados por el ingeniero, etc.).
+      await fs.copy(sourcePath, targetPath, {
+        overwrite: true,
+        recursive: true,
+        filter: (src) => {
+          const relativePath = path.relative(sourcePath, src);
+          // No sobrescribir archivos ignorados si ya existen
+          if (this.ignoredFiles.includes(relativePath)) {
+            const targetFile = path.join(targetPath, relativePath);
+            return !fs.existsSync(targetFile);
+          }
+          return true;
         }
-        return true;
-      }
-    });
+      });
+    }
 
     // Restaurar los archivos backup
     for (const backupFile of backupFiles) {
@@ -485,6 +608,30 @@ class SiesaBmadInstaller {
     }
   }
 
+  // Aplica un mapping de archivo (no carpeta). Para `.mcp.json` hace deep-merge
+  // JSON con source-wins: actualiza los servidores MCP nativos a la versión del
+  // paquete pero conserva los MCPs adicionales que el usuario haya configurado.
+  // Para cualquier otro archivo, copia directa del source.
+  // El parámetro `outputPath` permite usar este método tanto en el camino atómico
+  // (escribiendo a `<target>.sa-new`) como en el camino con backups (escribiendo
+  // directamente al target).
+  async applyFileMapping(sourcePath, targetPath, outputPath) {
+    const isMcpJson = path.basename(targetPath) === '.mcp.json';
+    if (isMcpJson && fs.existsSync(targetPath)) {
+      try {
+        const sourceJson = JSON.parse(await fs.readFile(sourcePath, 'utf8'));
+        const targetJson = JSON.parse(await fs.readFile(targetPath, 'utf8'));
+        const merged = deepMergeJson(targetJson, sourceJson);
+        await fs.writeFile(outputPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+        console.log('🔀 .mcp.json: merge — MCPs nativos actualizados, MCPs personalizados preservados');
+        return;
+      } catch (err) {
+        console.warn(`⚠️  No se pudo hacer merge de .mcp.json (${err.message}). Se usará la versión del paquete.`);
+      }
+    }
+    await fs.copy(sourcePath, outputPath, { overwrite: true });
+  }
+
   async findBackupFiles(targetPath) {
     if (!fs.existsSync(targetPath)) {
       return [];
@@ -566,23 +713,121 @@ class SiesaBmadInstaller {
     if (hasBackups) {
       await this.performUpdateWithBackups();
     } else {
-      // Si no hay backups, hacer actualización normal (remover y copiar)
-      // Pero primero preservar archivos ignorados
+      // Update atómico con merge:
+      //   1. Staging arranca como CLON del target actual — preserva skills custom
+      //      en .claude/skills/, flujos agregados por el ingeniero, y cualquier
+      //      archivo no nativo que el usuario haya puesto dentro de las carpetas
+      //      del paquete.
+      //   2. Source se sobrepone al staging (actualiza archivos nativos).
+      //   3. Para .mcp.json: deep-merge JSON con source-wins — los MCPs nativos
+      //      se actualizan, los MCPs adicionales del usuario sobreviven.
+      //   4. Swap atómico: target → .sa-old, .sa-new → target, borrar .sa-old.
+      //
+      // El flujo anterior borraba el destino antes de copiar — si el proceso moría
+      // a mitad (Ctrl+C, OOM, crash), el usuario se quedaba sin instalación. Con
+      // el staging, una interrupción deja el target intacto y solo basura en
+      // .sa-new que se limpia en la próxima corrida.
+      //
+      // Trade-off conocido: archivos nativos que el paquete eliminó en una versión
+      // nueva permanecen en el target tras el update — no podemos distinguir
+      // entre "nativo removido en upstream" y "custom del usuario". El usuario
+      // limpia artefactos obsoletos a mano si los detecta.
       await this.preserveIgnoredFiles();
-      
+      await this.performAtomicUpdate();
+      await this.restoreIgnoredFiles();
+    }
+  }
+
+  async performAtomicUpdate() {
+    const STAGING_SUFFIX = '.sa-new';
+    const OLD_SUFFIX = '.sa-old';
+
+    // Phase 1: limpiar restos de runs anteriores que murieron mid-update.
+    for (const mapping of this.folderMappings) {
+      const target = path.join(this.targetDir, mapping.target);
+      for (const suffix of [STAGING_SUFFIX, OLD_SUFFIX]) {
+        const stale = target + suffix;
+        if (fs.existsSync(stale)) {
+          try { await fs.remove(stale); } catch (_) {}
+        }
+      }
+    }
+
+    // Phase 2: stage cada mapping en `<target>.sa-new`.
+    //   - Folder mapping: clonar target actual al staging y después overlay del
+    //     source. fs.copy con overwrite=true es un merge — el clon preserva los
+    //     archivos del usuario (skills custom, MCPs, etc.) y el overlay del
+    //     source actualiza los archivos nativos del paquete.
+    //   - File mapping `.mcp.json`: deep-merge JSON con source-wins (preserva
+    //     MCPs personalizados, actualiza nativos). Otros file mappings: copia
+    //     directa del source.
+    // Si falla cualquier mapping, rollback antes de tocar los targets reales.
+    const staged = [];
+    try {
       for (const mapping of this.folderMappings) {
+        const sourcePath = path.join(this.packageDir, mapping.source);
         const targetPath = path.join(this.targetDir, mapping.target);
+        const stagingPath = targetPath + STAGING_SUFFIX;
 
-        if (fs.existsSync(targetPath)) {
-          await fs.remove(targetPath);
+        if (!fs.existsSync(sourcePath)) {
+          console.warn(`⚠️  ${mapping.source} no encontrado en el paquete`);
+          continue;
         }
+
+        const sourceIsFile = (await fs.stat(sourcePath)).isFile();
+
+        if (sourceIsFile) {
+          await this.applyFileMapping(sourcePath, targetPath, stagingPath);
+        } else {
+          // Clonar target al staging primero (preserva customs), después overlay
+          // del source (actualiza nativos).
+          if (fs.existsSync(targetPath)) {
+            await fs.copy(targetPath, stagingPath, { overwrite: true, recursive: true });
+          }
+          await fs.copy(sourcePath, stagingPath, {
+            overwrite: true,
+            recursive: true,
+            filter: (src) => {
+              const relativePath = path.relative(sourcePath, src);
+              // No sobrescribir archivos ignorados si ya existen en el target real.
+              if (this.ignoredFiles.includes(relativePath)) {
+                const realTargetFile = path.join(targetPath, relativePath);
+                return !fs.existsSync(realTargetFile);
+              }
+              return true;
+            }
+          });
+        }
+        // Ocultar el staging mientras existe (cosmético, solo Windows).
+        setHidden(stagingPath, true);
+        staged.push({ targetPath, stagingPath });
+      }
+    } catch (err) {
+      // Rollback: borrar lo que sí alcanzó a copiarse al staging.
+      for (const { stagingPath } of staged) {
+        try { await fs.remove(stagingPath); } catch (_) {}
       }
+      throw err;
+    }
 
-      // Realizar instalación nueva
-      await this.performInstallation();
-      
-      // Restaurar archivos ignorados
-      await this.restoreIgnoredFiles();
+    // Phase 3: swap atómico. Por cada mapping ya staged, rename target → `.sa-old`,
+    // rename `.sa-new` → target, borrar `.sa-old`. fs.move es rename donde es posible.
+    for (const { targetPath, stagingPath } of staged) {
+      const oldPath = targetPath + OLD_SUFFIX;
+
+      if (fs.existsSync(targetPath)) {
+        await fs.move(targetPath, oldPath, { overwrite: true });
+        setHidden(oldPath, true); // ocultar el viejo mientras se borra
+      }
+      await fs.move(stagingPath, targetPath, { overwrite: true });
+      // El rename hereda el atributo oculto del staging — limpiarlo para que el
+      // target final sea visible.
+      setHidden(targetPath, false);
+      if (fs.existsSync(oldPath)) {
+        try { await fs.remove(oldPath); } catch (e) {
+          console.warn(`⚠️  No se pudo borrar ${oldPath} (se limpiará en la próxima corrida): ${e.message}`);
+        }
+      }
     }
   }
 
@@ -660,9 +905,34 @@ class SiesaBmadInstaller {
   }
 }
 
+function printHelp() {
+  console.log('Usage: npx siesa-agents [options]\n');
+  console.log('Options:');
+  console.log('  -y, --yes        Modo no-interactivo. Usa defaults sensatos en cualquier prompt');
+  console.log('                   (no preguntar por repo remoto, hacer backup de modificados).');
+  console.log('                   Se activa automáticamente cuando stdin no es un TTY.');
+  console.log('  --version        Imprime la versión del paquete y sale.');
+  console.log('  -h, --help       Muestra esta ayuda.\n');
+  console.log('Environment:');
+  console.log('  SIESA_DEBUG=1    Muestra información de diagnóstico para el descubrimiento');
+  console.log('                   del directorio del paquete.');
+}
+
 // Ejecutar instalación si el script es llamado directamente
 if (require.main === module) {
-  const installer = new SiesaBmadInstaller();
+  const cliArgs = parseCliArgs(process.argv.slice(2));
+
+  if (cliArgs.help) {
+    printHelp();
+    process.exit(0);
+  }
+  if (cliArgs.version) {
+    const pkg = require('../package.json');
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  const installer = new SiesaBmadInstaller(cliArgs);
   installer.install();
 }
 

package/bin/prepare-publish.js

@@ -2,26 +2,33 @@
 
 const fs = require('fs-extra');
 const path = require('path');
+const { publishRenames } = require('./folder-mappings');
 
 const rootDir = path.dirname(__dirname);
 
-// Renombrar carpetas que empiezan con punto para que npm las incluya
-const folderMappings = [
-  { from: '.bmad-core', to: 'bmad-core' },
-  { from: '.vscode', to: 'vscode' },
-  { from: '.github', to: 'github' }
-];
+// Renombrar carpetas dev-side a sus nombres "flat" antes de `npm publish`. Cuáles se
+// renombran lo decide bin/folder-mappings.js (un solo source of truth compartido con
+// install.js y restore-folders.js).
+const folderMappings = publishRenames();
 
 console.log('📦 Preparando carpetas para publicación (siesa-agents)...');
 
-for (const mapping of folderMappings) {
-  const fromPath = path.join(rootDir, mapping.from);
-  const toPath = path.join(rootDir, mapping.to);
+if (folderMappings.length === 0) {
+  console.log('ℹ️  El repo mantiene un mirror flat de cada carpeta (claude/, github/, bmad/, …)');
+  console.log('   junto al dotted/underscored (.claude/, .github/, _bmad/, …). No hace falta');
+  console.log('   renombrar nada antes de `npm publish` — los archivos flat ya están listos.');
+  console.log('   Si en el futuro se elimina algún mirror, declara su devSource en');
+  console.log('   bin/folder-mappings.js y este script lo renombrará automáticamente.');
+} else {
+  for (const mapping of folderMappings) {
+    const fromPath = path.join(rootDir, mapping.from);
+    const toPath = path.join(rootDir, mapping.to);
 
-  if (fs.existsSync(fromPath)) {
-    console.log(`📁 Renombrando ${mapping.from} -> ${mapping.to}`);
-    fs.moveSync(fromPath, toPath);
+    if (fs.existsSync(fromPath)) {
+      console.log(`📁 Renombrando ${mapping.from} -> ${mapping.to}`);
+      fs.moveSync(fromPath, toPath);
+    }
   }
 }
 
-console.log('✅ Carpetas preparadas para publicación');
+console.log('✅ Carpetas preparadas para publicación');

package/bin/restore-folders.js

@@ -2,26 +2,29 @@
 
 const fs = require('fs-extra');
 const path = require('path');
+const { restoreRenames } = require('./folder-mappings');
 
 const rootDir = path.dirname(__dirname);
 
-// Restaurar nombres originales de las carpetas
-const folderMappings = [
-  { from: 'bmad-core', to: '.bmad-core' },
-  { from: 'vscode', to: '.vscode' },
-  { from: 'github', to: '.github' }
-];
+// Restaurar nombres originales de las carpetas dev tras `npm publish`. Cuáles se
+// restauran lo decide bin/folder-mappings.js (compartido con install.js y prepare-publish.js).
+const folderMappings = restoreRenames();
 
 console.log('🔄 Restaurando nombres originales de carpetas...');
 
-for (const mapping of folderMappings) {
-  const fromPath = path.join(rootDir, mapping.from);
-  const toPath = path.join(rootDir, mapping.to);
+if (folderMappings.length === 0) {
+  console.log('ℹ️  Nada que restaurar — prepare-publish.js no renombró nada porque el repo');
+  console.log('   mantiene mirrors flat junto a los dotted/underscored. Ver bin/folder-mappings.js.');
+} else {
+  for (const mapping of folderMappings) {
+    const fromPath = path.join(rootDir, mapping.from);
+    const toPath = path.join(rootDir, mapping.to);
 
-  if (fs.existsSync(fromPath)) {
-    console.log(`📁 Restaurando ${mapping.from} -> ${mapping.to}`);
-    fs.moveSync(fromPath, toPath);
+    if (fs.existsSync(fromPath)) {
+      console.log(`📁 Restaurando ${mapping.from} -> ${mapping.to}`);
+      fs.moveSync(fromPath, toPath);
+    }
   }
 }
 
-console.log('✅ Carpetas restauradas');
+console.log('✅ Carpetas restauradas');

package/claude/agents/sa-code-review.md

@@ -20,6 +20,7 @@ NO modifiques ningún archivo dentro de `.claude/agent-memory/` — es de SOLO L
 - Sé directo, funcional y breve.
 - Si encuentras issues que puedes auto-corregir, corrígelos directamente sin pedir confirmación.
 - Valida compliance contra los estándares cargados: folder structure correcta, naming conventions, uso de DateTimeOffset (no DateTime), UUID PKs, FluentValidation, patrones DDD, etc.
+- **Git — NO auto-gitflow:** Cuando este agente es invocado desde `sa-quick-dev`, está **prohibido** crear ramas, hacer commits, push, pull requests, worktrees ni cualquier operación git automática. Todos los cambios (incluidas las auto-correcciones) se aplican directamente sobre la rama activa del repositorio al momento de la invocación. El versionamiento es responsabilidad exclusiva del usuario.
 
 ## Ejecución
 

package/claude/agents/sa-dev-story.md

@@ -20,6 +20,7 @@ NO modifiques ningún archivo dentro de `.claude/agent-memory/` — es de SOLO L
 - Sé directo, funcional y breve.
 - Implementa SOLO lo que los acceptance criteria y las tareas de la historia requieren. Nada más.
 - Todo código DEBE seguir los estándares cargados: folder structure, naming conventions, tech stack, patterns (DDD entities, value objects, CQRS, FluentValidation, DateTimeOffset, UUID PKs, etc.).
+- **Git — NO auto-gitflow:** Cuando este agente es invocado desde `sa-quick-dev`, está **prohibido** crear ramas, hacer commits, push, pull requests, worktrees ni cualquier operación git automática. Todos los cambios se aplican directamente sobre la rama activa del repositorio al momento de la invocación. El versionamiento es responsabilidad exclusiva del usuario.
 
 ## Ejecución
 

package/claude/commands/sa-quick-dev.md

@@ -99,6 +99,64 @@ Modo: epic-level
 
 ---
 
+## Reglas generales del pipeline
+
+### Regla 1 — Observabilidad obligatoria en cada sub-agente
+
+Cada sub-agente que ejecuta un workflow BMAD (`sa-create-story`, `sa-dev-story`, `sa-code-review`) **DEBE honrar las instrucciones de observabilidad** definidas en su respectivo `workflow_ext.md`. Estas instrucciones emiten eventos de telemetría (`sa-emit.js`) a GCP en momentos específicos del flujo y son la fuente de todos los reportes de métricas del equipo.
+
+**Workflows instrumentados y eventos que se deben emitir:**
+
+| Sub-agente | `workflow_ext.md` | Eventos emitidos |
+|---|---|---|
+| `sa-create-story` | `_siesa-agents/bmm/workflows/4-implementation/create-story/workflow_ext.md` | `workflow.started`, `status.changed` (backlog → ready-for-dev), `workflow.finished` |
+| `sa-dev-story` | `_siesa-agents/bmm/workflows/4-implementation/dev-story/workflow_ext.md` | `workflow.started`, `status.changed` (in-progress → review), `workflow.finished` |
+| `sa-code-review` | `_siesa-agents/bmm/workflows/4-implementation/code-review/workflow_ext.md` | `workflow.started`, `fix.started`/`fix.finished` (cuando el usuario acepta auto_fix / action_items / show_details), `status.changed` (review → done o → in-progress), `workflow.finished` |
+
+**Prohibido a cualquier sub-agente bajo este orquestador:**
+
+- ❌ Saltarse, comentar, condicionar u omitir cualquier comando `node ... sa-emit.js ...` del `workflow_ext.md` correspondiente.
+- ❌ Diferir la emisión al "final del pipeline" o agruparla en batch. Los eventos son **lifecycle markers** y solo tienen sentido en el instante exacto que el `workflow_ext.md` indica (`workflow.finished` mide `duration_ms` desde el `workflow.started` correspondiente; si lo retrasas, la métrica queda corrompida).
+
+**Manejo de errores de `sa-emit.js`:**
+
+Si la llamada a `sa-emit.js` falla (gateway caído, credenciales mal configuradas, etc.), el sub-agente debe:
+
+1. Registrar el fallo como advertencia **no-bloqueante**.
+2. **Continuar el workflow normalmente** (regla universal documentada en cada `workflow_ext.md`: *"observability must never block the workflow"*).
+3. NUNCA reemplazar la llamada por su omisión deliberada — el evento queda buffereado localmente en `~/.claude/observability/buffer/events.jsonl` y se reenvía automáticamente cuando el transporte se recupera.
+
+---
+
+## Reglas generales del pipeline
+
+### Regla 1 — Observabilidad obligatoria en cada sub-agente
+
+Cada sub-agente que ejecuta un workflow BMAD (`sa-create-story`, `sa-dev-story`, `sa-code-review`) **DEBE honrar las instrucciones de observabilidad** definidas en su respectivo `workflow_ext.md`. Estas instrucciones emiten eventos de telemetría (`sa-emit.js`) a GCP en momentos específicos del flujo y son la fuente de todos los reportes de métricas del equipo.
+
+**Workflows instrumentados y eventos que se deben emitir:**
+
+| Sub-agente | `workflow_ext.md` | Eventos emitidos |
+|---|---|---|
+| `sa-create-story` | `_siesa-agents/bmm/workflows/4-implementation/create-story/workflow_ext.md` | `workflow.started`, `status.changed` (backlog → ready-for-dev), `workflow.finished` |
+| `sa-dev-story` | `_siesa-agents/bmm/workflows/4-implementation/dev-story/workflow_ext.md` | `workflow.started`, `status.changed` (in-progress → review), `workflow.finished` |
+| `sa-code-review` | `_siesa-agents/bmm/workflows/4-implementation/code-review/workflow_ext.md` | `workflow.started`, `fix.started`/`fix.finished` (cuando el usuario acepta auto_fix / action_items / show_details), `status.changed` (review → done o → in-progress), `workflow.finished` |
+
+**Prohibido a cualquier sub-agente bajo este orquestador:**
+
+- ❌ Saltarse, comentar, condicionar u omitir cualquier comando `node ... sa-emit.js ...` del `workflow_ext.md` correspondiente.
+- ❌ Diferir la emisión al "final del pipeline" o agruparla en batch. Los eventos son **lifecycle markers** y solo tienen sentido en el instante exacto que el `workflow_ext.md` indica (`workflow.finished` mide `duration_ms` desde el `workflow.started` correspondiente; si lo retrasas, la métrica queda corrompida).
+
+**Manejo de errores de `sa-emit.js`:**
+
+Si la llamada a `sa-emit.js` falla (gateway caído, credenciales mal configuradas, etc.), el sub-agente debe:
+
+1. Registrar el fallo como advertencia **no-bloqueante**.
+2. **Continuar el workflow normalmente** (regla universal documentada en cada `workflow_ext.md`: *"observability must never block the workflow"*).
+3. NUNCA reemplazar la llamada por su omisión deliberada — el evento queda buffereado localmente en `~/.claude/observability/buffer/events.jsonl` y se reenvía automáticamente cuando el transporte se recupera.
+
+---
+
 ## PASO 1 — Loop de procesamiento por historia
 
 Para CADA historia pendiente de la épica seleccionada, ejecuta secuencialmente los sub-agentes dedicados. Cada historia completa su ciclo completo antes de pasar a la siguiente.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.83",
+  "version": "2.1.84",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {
@@ -26,7 +26,6 @@
     "github/**/*",
     "claude/**/*",
     "gemini/**/*",
-    "kiro/**/*",
     "bin/**/*",
     "resources/**/*",
     "README.md",
@@ -36,7 +35,7 @@
     "node": ">=14.0.0"
   },
   "dependencies": {
-    "fs-extra": "^11.1.1",
-    "path": "^0.12.7"
+    "@clack/prompts": "^0.11.0",
+    "fs-extra": "^11.1.1"
   }
 }

package/vscode/settings.json

@@ -9,5 +9,9 @@
     "cursor-workspace": true
   },
   "github.copilot.chat.agent.autoFix": true,
-  "chat.tools.autoApprove": false
+  "chat.tools.autoApprove": false,
+  "files.exclude": {
+    "**/*.sa-new": true,
+    "**/*.sa-old": true
+  }
 }