aiox-core 5.0.4 → 5.0.5

package/pro/squads/squad-creator-pro/scripts/generate-squad-guide.js

@@ -1,558 +0,0 @@
-#!/usr/bin/env node
-/**
- * Squad Guide Generator
- *
- * Generates the complete *guide output dynamically from agent .md files.
- * Single source of truth: the agents themselves define commands.
- *
- * Follows the same pattern as generate-squad-greeting.js:
- * - Extracts YAML blocks from squad agent files
- * - Parses commands, modes, categories
- * - Generates numbered command tables per agent
- *
- * Usage:
- *   node generate-squad-guide.js <squad-name>
- *
- * Example:
- *   node generate-squad-guide.js squad-creator
- *
- * @module generate-squad-guide
- * @version 1.0.0
- * @location squads/squad-creator-pro/scripts/
- */
-
-const fs = require('fs').promises;
-const path = require('path');
-const yaml = require('js-yaml');
-
-const SQUADS_PATH = './squads';
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// YAML EXTRACTION
-// ═══════════════════════════════════════════════════════════════════════════════
-
-/**
- * Extract ALL yaml/yml code blocks from markdown content.
- * @param {string} content - Markdown file content
- * @returns {string[]} Raw YAML block strings
- */
-function extractAllYamlBlocks(content) {
-  const blocks = [];
-  const regex = /```ya?ml\n([\s\S]*?)\n```/g;
-  let match;
-  while ((match = regex.exec(content)) !== null) {
-    blocks.push(match[1]);
-  }
-  return blocks;
-}
-
-/**
- * Preprocess YAML to fix known format issues.
- *
- * pedro-valerio modes have commands like:
- *   - "*eng-map {processo}" - Mapear processo completo
- * which is invalid YAML (content after closing quote).
- * We fix it to:
- *   - "*eng-map {processo} - Mapear processo completo"
- *
- * @param {string} yamlStr - Raw YAML string
- * @returns {string} Preprocessed YAML string
- */
-function preprocessYaml(yamlStr) {
-  // Fix: use [ \t] instead of \s to avoid matching across newlines
-  return yamlStr.replace(
-    /^(\s*-\s*)"([^"]+)"[ \t]+-[ \t]+(.+)$/gm,
-    '$1"$2 - $3"',
-  );
-}
-
-/**
- * Parse YAML blocks safely, returning parsed objects.
- * Applies preprocessing and skips blocks that fail to parse.
- *
- * @param {string[]} rawBlocks - Raw YAML block strings
- * @returns {Object[]} Successfully parsed YAML documents
- */
-function parseYamlBlocks(rawBlocks) {
-  const parsed = [];
-  for (const block of rawBlocks) {
-    try {
-      const preprocessed = preprocessYaml(block);
-      const doc = yaml.load(preprocessed);
-      if (doc && typeof doc === 'object') {
-        parsed.push(doc);
-      }
-    } catch (e) {
-      // Block failed to parse — skip silently
-    }
-  }
-  return parsed;
-}
-
-/**
- * Find a top-level key across multiple parsed YAML blocks.
- * Returns the first match found.
- *
- * @param {Object[]} parsedBlocks - Array of parsed YAML documents
- * @param {string} key - Key to search for
- * @returns {*} Value found, or null
- */
-function findKey(parsedBlocks, key) {
-  for (const block of parsedBlocks) {
-    if (block[key] !== undefined) {
-      return block[key];
-    }
-  }
-  return null;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// AGENT DATA LOADING
-// ═══════════════════════════════════════════════════════════════════════════════
-
-/**
- * Regex-based fallback to extract agent info from raw YAML blocks.
- * Used when YAML parsing fails due to loose formatting (e.g. "text" → more text).
- *
- * @param {string[]} rawBlocks - Raw YAML block strings
- * @returns {Object|null} Agent info {name, id, title, icon} or null
- */
-function extractAgentInfoFromRaw(rawBlocks) {
-  for (const block of rawBlocks) {
-    const agentStart = block.match(/^agent:\s*$/m);
-    if (!agentStart) continue;
-
-    const agentSection = block.substring(agentStart.index);
-    const getName = agentSection.match(/^\s+name:\s*(.+)/m);
-    const getId = agentSection.match(/^\s+id:\s*(.+)/m);
-    const getTitle = agentSection.match(/^\s+title:\s*(.+)/m);
-    const getIcon = agentSection.match(/^\s+icon:\s*(.+)/m);
-
-    if (getName) {
-      const clean = (v) => v.trim().replace(/^["']|["']$/g, '');
-      return {
-        name: clean(getName[1]),
-        id: getId ? clean(getId[1]) : '',
-        title: getTitle ? clean(getTitle[1]) : '',
-        icon: getIcon ? getIcon[1].trim() : '',
-      };
-    }
-  }
-  return null;
-}
-
-/**
- * Load and parse an agent .md file, extracting all YAML blocks
- * and searching for relevant keys across blocks.
- *
- * @param {string} squadName - Squad directory name
- * @param {string} agentName - Agent filename (without .md)
- * @returns {Promise<Object>} Agent data with parsed YAML keys
- */
-async function loadAgentData(squadName, agentName) {
-  const agentPath = path.join(
-    process.cwd(),
-    SQUADS_PATH,
-    squadName,
-    'agents',
-    `${agentName}.md`,
-  );
-  const content = await fs.readFile(agentPath, 'utf8');
-  const rawBlocks = extractAllYamlBlocks(content);
-  const parsedBlocks = parseYamlBlocks(rawBlocks);
-
-  // agent key may fail YAML parsing (loose formatting in core_beliefs etc.)
-  // Use regex fallback if not found via standard parsing.
-  const agent =
-    findKey(parsedBlocks, 'agent') || extractAgentInfoFromRaw(rawBlocks);
-
-  return {
-    agent,
-    commands: findKey(parsedBlocks, 'commands'),
-    modes: findKey(parsedBlocks, 'modes'),
-    command_categories: findKey(parsedBlocks, 'command_categories'),
-    command_aliases_ptbr: findKey(parsedBlocks, 'command_aliases_ptbr'),
-  };
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// COMMAND PARSING
-// ═══════════════════════════════════════════════════════════════════════════════
-
-/**
- * Parse a command string in the format:
- *   "*command {params} - Description"
- *
- * Used for squad-chief commands (string array) and
- * pedro-valerio mode commands (after YAML preprocessing).
- *
- * @param {string} str - Command string
- * @returns {{command: string, description: string}|null}
- */
-function parseCommandString(str) {
-  if (typeof str !== 'string') return null;
-
-  // Match: *command-name {optional params} - Description
-  const match = str.match(/^(\*\S+(?:\s+\{[^}]+\})*)\s+-\s+(.+)$/);
-  if (match) {
-    return { command: match[1].trim(), description: match[2].trim() };
-  }
-
-  // Fallback: just extract the command name
-  const cmdMatch = str.match(/^(\*\S+)/);
-  if (cmdMatch) {
-    return { command: cmdMatch[1], description: '' };
-  }
-
-  return null;
-}
-
-/**
- * Parse object-format commands (from oalanicolas/pedro-valerio visibility blocks).
- * Format: [{name: "*cmd", description: "..."}, ...]
- *
- * @param {Array} arr - Array of command objects
- * @returns {{command: string, description: string}[]}
- */
-function parseObjectCommands(arr) {
-  if (!Array.isArray(arr)) return [];
-  return arr
-    .filter((cmd) => cmd && typeof cmd === 'object' && cmd.name)
-    .map((cmd) => ({
-      command: cmd.name.startsWith('*') ? cmd.name : `*${cmd.name}`,
-      description: cmd.description || '',
-    }));
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// GUIDE GENERATION — Shared Helpers
-// ═══════════════════════════════════════════════════════════════════════════════
-
-/**
- * Generate a markdown table of commands with sequential numbering.
- *
- * @param {{command: string, description: string}[]} commands
- * @param {number} startNumber - First row number
- * @returns {string} Markdown table
- */
-function generateCommandTable(commands, startNumber) {
-  let table = '| # | Comando | Descrição |\n|---|---------|-----------|';
-  commands.forEach((cmd, i) => {
-    table += `\n| ${startNumber + i} | \`${cmd.command}\` | ${cmd.description} |`;
-  });
-  return table;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// GUIDE GENERATION — Conceptual Sections (static template strings)
-// ═══════════════════════════════════════════════════════════════════════════════
-
-function generateConceptualSections() {
-  return `## O que é o Squad Architect?
-
-Sou o arquiteto especializado em criar **squads de agentes** baseados em **elite minds reais** — pessoas com frameworks documentados e skin in the game. Ao invés de criar bots genéricos, eu clono a metodologia de experts reais de qualquer domínio.
-
-> **Filosofia:** "Clone minds > create bots"
-
-## Conceitos Fundamentais
-
-| Conceito | O que é | Detalhes |
-|----------|---------|----------|
-| **Voice DNA** | COMO o expert comunica | Vocabulário, frases assinatura, tom, histórias recorrentes |
-| **Thinking DNA** | COMO o expert decide | Frameworks, heurísticas, arquitetura de decisão |
-| **Tiers** | Organização hierárquica | T0: Diagnóstico → T1: Masters → T2: Sistemáticos → Orchestrator |
-| **Quality Gates** | Validação rigorosa | 3 smoke tests + Voice DNA rastreável + Heuristics com QUANDO |
-
-## Workflow de Criação
-
-| Fase | Ação | Descrição |
-|------|------|-----------|
-| 1 | CONTEXTO | Detecto greenfield/resume/brownfield |
-| 2 | DISCOVERY | Pesquisa paralela (experts, tools, riscos) |
-| 3 | ARQUITETURA | Defino tiers, handoffs e escopo |
-| 4 | CRIAÇÃO | Gero agents/tasks/workflows |
-| 5 | INTEGRAÇÃO | Wiring, handoffs, documentação |
-| 6 | GATES FINAIS | validate-squad + validate-final-artifacts |
-
-## Primeiros Passos
-
-| Ação | Comando | Descrição |
-|------|---------|-----------|
-| Criar squad | \`*create-squad-smart legal\` | Detecto contexto e escolho workflow automaticamente |
-| Upgrade brownfield | \`*brownfield-upgrade legal\` | Valido baseline e aplico upgrade seguro |
-| Clonar expert | \`*clone-mind Gary Halbert\` | Extrair Voice DNA + Thinking DNA completo |
-| Validar squad | \`*validate-squad copy\` | Validação granular component-by-component |
-| Ver analytics | \`*squad-analytics\` | Dashboard detalhado de métricas |`;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// GUIDE GENERATION — Per-Agent Command Sections
-// ═══════════════════════════════════════════════════════════════════════════════
-
-/**
- * Generate squad-chief command section, grouped by command_categories.
- * Falls back to flat table if no categories defined.
- *
- * @param {Object} data - Agent data from loadAgentData
- * @param {number} startNumber - First command number
- * @returns {{output: string, nextNumber: number}}
- */
-function generateSquadChiefCommands(data, startNumber) {
-  const rawCommands = data.commands || [];
-
-  // Parse all commands from string array
-  const allParsed = rawCommands
-    .filter((cmd) => typeof cmd === 'string' && cmd.startsWith('*'))
-    .map(parseCommandString)
-    .filter(Boolean);
-
-  // Build lookup by base command name (without params)
-  const cmdMap = new Map();
-  for (const cmd of allParsed) {
-    const baseName = cmd.command.split(' ')[0];
-    if (!cmdMap.has(baseName)) {
-      cmdMap.set(baseName, cmd);
-    }
-  }
-
-  const categories = data.command_categories;
-  let output = '';
-  let currentNum = startNumber;
-
-  if (categories) {
-    // Group by categories (preserves order from YAML)
-    for (const [, category] of Object.entries(categories)) {
-      const catCommands = (category.commands || [])
-        .map((cmdName) => cmdMap.get(cmdName) || null)
-        .filter(Boolean);
-
-      if (catCommands.length > 0) {
-        output += `\n**${category.display}**\n`;
-        output += generateCommandTable(catCommands, currentNum);
-        output += '\n';
-        currentNum += catCommands.length;
-      }
-    }
-  } else {
-    // No categories — flat table
-    output += generateCommandTable(allParsed, currentNum);
-    currentNum += allParsed.length;
-  }
-
-  return { output, nextNumber: currentNum };
-}
-
-/**
- * Generate oalanicolas command section — flat table (no subcategories).
- *
- * @param {Object} data - Agent data from loadAgentData
- * @param {number} startNumber - First command number
- * @returns {{output: string, nextNumber: number}}
- */
-function generateOalanicolasCommands(data, startNumber) {
-  const commands = parseObjectCommands(data.commands);
-  const table = generateCommandTable(commands, startNumber);
-  return { output: table, nextNumber: startNumber + commands.length };
-}
-
-/**
- * Generate pedro-valerio command section, grouped by modes prefix.
- * Remaining commands (not in any mode) go to "CRIAÇÃO & AUDITORIA".
- *
- * @param {Object} data - Agent data from loadAgentData
- * @param {number} startNumber - First command number
- * @returns {{output: string, nextNumber: number}}
- */
-function generatePedroValerioCommands(data, startNumber) {
-  const { commands: visibilityCommands, modes } = data;
-  const parsedVisibility = parseObjectCommands(visibilityCommands);
-
-  let output = '';
-  let currentNum = startNumber;
-  const usedCommandBases = new Set();
-
-  if (modes) {
-    for (const [, mode] of Object.entries(modes)) {
-      const prefix = mode.prefix || '';
-      const modeCommands = [];
-
-      // Extract commands from mode.commands (strings with params + descriptions)
-      if (Array.isArray(mode.commands)) {
-        for (const cmdStr of mode.commands) {
-          const parsed = parseCommandString(cmdStr);
-          if (parsed) {
-            modeCommands.push(parsed);
-            usedCommandBases.add(parsed.command.split(' ')[0]);
-          }
-        }
-      }
-
-      // Fallback: if no mode commands parsed, match visibility commands by prefix
-      if (modeCommands.length === 0 && prefix) {
-        for (const cmd of parsedVisibility) {
-          if (cmd.command.startsWith(prefix)) {
-            modeCommands.push(cmd);
-            usedCommandBases.add(cmd.command);
-          }
-        }
-      }
-
-      if (modeCommands.length > 0) {
-        const displayName = (mode.name || '').toUpperCase();
-        const prefixDisplay = prefix ? ` (\`${prefix}*\`)` : '';
-        output += `\n**${displayName}${prefixDisplay}**\n`;
-        output += generateCommandTable(modeCommands, currentNum);
-        output += '\n';
-        currentNum += modeCommands.length;
-      }
-    }
-  }
-
-  // Remaining commands not assigned to any mode
-  const remaining = parsedVisibility.filter(
-    (cmd) => !usedCommandBases.has(cmd.command),
-  );
-  if (remaining.length > 0) {
-    output += '\n**CRIAÇÃO & AUDITORIA**\n';
-    output += generateCommandTable(remaining, currentNum);
-    output += '\n';
-    currentNum += remaining.length;
-  }
-
-  return { output, nextNumber: currentNum };
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// GUIDE GENERATION — Aliases Section
-// ═══════════════════════════════════════════════════════════════════════════════
-
-/**
- * Generate aliases table from command_aliases_ptbr array.
- *
- * @param {string[]} aliases - Array of alias strings
- * @returns {string} Markdown table or empty string
- */
-function generateAliasesSection(aliases) {
-  if (!Array.isArray(aliases)) return '';
-
-  const rows = [];
-  let num = 1;
-  for (const alias of aliases) {
-    if (typeof alias !== 'string') continue;
-    const match = alias.match(/^\*(\S+)\s*->\s*\*(\S+)$/);
-    if (match) {
-      rows.push(`| ${num} | \`*${match[1]}\` | → \`*${match[2]}\` |`);
-      num++;
-    }
-  }
-
-  if (rows.length === 0) return '';
-  return '| # | Alias PT-BR | Comando Original |\n|---|-------------|-----------------|' + '\n' + rows.join('\n');
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// MAIN GENERATION
-// ═══════════════════════════════════════════════════════════════════════════════
-
-/**
- * Generate the complete squad guide.
- *
- * @param {string} squadName - Squad directory name (e.g. "squad-creator")
- * @returns {Promise<string>} Complete guide as markdown
- */
-async function generateSquadGuide(squadName) {
-  // Load all 3 agents in parallel
-  const [chiefData, alanData, pedroData] = await Promise.all([
-    loadAgentData(squadName, 'squad-chief'),
-    loadAgentData(squadName, 'oalanicolas'),
-    loadAgentData(squadName, 'pedro-valerio'),
-  ]);
-
-  const parts = [];
-
-  // ── Title ──
-  parts.push('🎨 SQUAD CREATOR — Guia Completo & Menu de Comandos');
-
-  // ── Conceptual Sections ──
-  parts.push(generateConceptualSections());
-
-  // ── Squad Chief Commands ──
-  const chiefAgent = chiefData.agent || {};
-  const chiefLabel = chiefAgent.name || 'Squad Chief';
-  const chiefResult = generateSquadChiefCommands(chiefData, 1);
-  parts.push(
-    `## 100% Comandos — @squad-chief (${chiefLabel})\n${chiefResult.output}`,
-  );
-
-  // ── oalanicolas Commands ──
-  const alanAgent = alanData.agent || {};
-  const alanLabel = alanAgent.name || 'oalanicolas';
-  const alanResult = generateOalanicolasCommands(
-    alanData,
-    chiefResult.nextNumber,
-  );
-  parts.push(
-    `## 100% Comandos — @oalanicolas (${alanLabel})\n${alanResult.output}`,
-  );
-
-  // ── pedro-valerio Commands ──
-  const pedroAgent = pedroData.agent || {};
-  const pedroLabel = pedroAgent.name || 'pedro-valerio';
-  const pedroResult = generatePedroValerioCommands(
-    pedroData,
-    alanResult.nextNumber,
-  );
-  parts.push(
-    `## 100% Comandos — @pedro-valerio (${pedroLabel})\n${pedroResult.output}`,
-  );
-
-  // ── Aliases PT-BR ──
-  const aliasesTable = generateAliasesSection(chiefData.command_aliases_ptbr);
-  if (aliasesTable) {
-    parts.push(`## Aliases PT-BR (Squad Chief)\n${aliasesTable}`);
-  }
-
-  // ── Footer ──
-  const totalCommands = pedroResult.nextNumber - 1;
-  parts.push(
-    `## Resumo & Próximo Passo\n\n| Métrica | Valor |\n|---------|-------|\n| Comandos totais | **${totalCommands}** |\n| Agentes no squad | **3** (@squad-chief, @oalanicolas, @pedro-valerio) |\n| Aliases PT-BR | **${chiefData.command_aliases_ptbr ? chiefData.command_aliases_ptbr.filter(a => a.includes('->')).length : 0}** |\n\nDigite o **número** ou o **comando** para executar. Qual domínio você quer transformar em squad?`,
-  );
-
-  return parts.join('\n\n');
-}
-
-/**
- * Fallback guide when generation fails.
- * @returns {string}
- */
-function generateFallbackGuide() {
-  return '🎨 Squad Architect — Guide\n\nType *help to see available commands.';
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// CLI
-// ═══════════════════════════════════════════════════════════════════════════════
-
-if (require.main === module) {
-  const squadName = process.argv[2];
-
-  if (!squadName) {
-    console.error(
-      'Usage: node generate-squad-guide.js <squad-name>\n\nExample:\n  node generate-squad-guide.js squad-creator',
-    );
-    process.exit(1);
-  }
-
-  generateSquadGuide(squadName)
-    .then((guide) => {
-      console.log(guide);
-      process.exit(0);
-    })
-    .catch((error) => {
-      console.error('Error:', error.message);
-      console.log(generateFallbackGuide());
-      process.exit(1);
-    });
-}
-
-module.exports = { generateSquadGuide, generateFallbackGuide };