convoke-agents 3.1.0 → 3.2.1

package/_bmad/bme/_team-factory/lib/writers/csv-creator.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const { deriveWorkflowNames, toKebab } = require('./config-creator');
+
+/** @typedef {import('../types/factory-types')} Types */
+
+/**
+ * Standard module-help.csv header — matches BMB and BMM exactly.
+ * Trailing comma is intentional (existing pattern).
+ */
+const CSV_HEADER = 'module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,';
+
+/**
+ * Create a per-module module-help.csv for a new team.
+ * One row per workflow, matching the BMB/BMM column format.
+ *
+ * Safety: Simple (write → verify header match). Additive-only (NFR17).
+ *
+ * @param {Object} specData - Parsed team spec file content
+ * @param {string} outputPath - Full path to write module-help.csv
+ * @returns {Promise<import('../types/factory-types').CreatorResult>}
+ */
+async function createCsv(specData, outputPath) {
+  // --- Additive-only check (NFR17) ---
+  if (await fs.pathExists(outputPath)) {
+    return { success: false, filePath: outputPath, rowCount: 0, errors: ['module-help.csv already exists at target path — additive-only, will not overwrite'] };
+  }
+
+  // --- Build CSV rows ---
+  const rows = buildCsvRows(specData);
+
+  // --- Write CSV ---
+  try {
+    await fs.ensureDir(path.dirname(outputPath));
+    const content = CSV_HEADER + '\n' + rows.map(formatCsvRow).join('\n') + '\n';
+    await fs.writeFile(outputPath, content, 'utf8');
+  } catch (err) {
+    return { success: false, filePath: outputPath, rowCount: 0, errors: [`Write failed: ${err.message}`] };
+  }
+
+  // --- Verify header match (Simple safety) ---
+  try {
+    const readBack = await fs.readFile(outputPath, 'utf8');
+    const firstLine = readBack.split('\n')[0];
+    if (firstLine !== CSV_HEADER) {
+      return { success: false, filePath: outputPath, rowCount: rows.length, errors: ['Verification failed: header mismatch after write'] };
+    }
+  } catch (err) {
+    return { success: false, filePath: outputPath, rowCount: 0, errors: [`Verification failed: ${err.message}`] };
+  }
+
+  return { success: true, filePath: outputPath, rowCount: rows.length, errors: [] };
+}
+
+/**
+ * Build CSV row data from spec.
+ * One row per workflow (one workflow per agent).
+ * @param {Object} specData
+ * @returns {import('../types/factory-types').CsvRow[]}
+ */
+function buildCsvRows(specData) {
+  const modulePath = `bme/_${specData.team_name_kebab}`;
+  const outputLocation = specData.integration.output_directory;
+  const workflows = deriveWorkflowNames(specData);
+  const rows = [];
+
+  for (let i = 0; i < (specData.agents || []).length; i++) {
+    const agent = specData.agents[i];
+    const workflowName = workflows[i];
+    const displayName = toTitleCase(workflowName);
+    const code = deriveCode(workflowName);
+    const sequence = (i + 1) * 10;
+
+    rows.push({
+      module: modulePath,
+      phase: 'anytime',
+      name: displayName,
+      code,
+      sequence,
+      workflow_file: `_bmad/bme/_${specData.team_name_kebab}/workflows/${workflowName}/workflow.md`,
+      command: `bmad-${specData.team_name_kebab}-${workflowName}`,
+      required: 'false',
+      agent: agent.id,
+      options: 'Create Mode',
+      description: agent.role,
+      output_location: outputLocation,
+      outputs: workflowName
+    });
+  }
+
+  return rows;
+}
+
+/**
+ * Format a CsvRow into a CSV line string.
+ * Matches BMB/BMM format: values with commas/spaces are quoted.
+ * Trailing comma included.
+ * @param {import('../types/factory-types').CsvRow} row
+ * @returns {string}
+ */
+function formatCsvRow(row) {
+  const values = [
+    row.module,
+    row.phase,
+    row.name,
+    row.code,
+    row.sequence,
+    row.workflow_file,
+    row.command,
+    row.required,
+    row.agent,
+    row.options,
+    csvQuote(row.description),
+    row.output_location,
+    csvQuote(row.outputs)
+  ];
+  return values.join(',') + ',';
+}
+
+/**
+ * Quote a CSV value if it contains commas, quotes, or newlines.
+ * @param {string} val
+ * @returns {string}
+ */
+function csvQuote(val) {
+  if (val == null || val === '') return '';
+  if (val.includes(',') || val.includes('"') || val.includes('\n')) {
+    return `"${val.replace(/"/g, '""')}"`;
+  }
+  return val;
+}
+
+/**
+ * Derive a 2-letter uppercase code from a workflow name.
+ * Takes first letter of first two words (e.g., "stack-detection" → "SD").
+ * @param {string} name - kebab-case workflow name
+ * @returns {string}
+ */
+function deriveCode(name) {
+  const words = name.split('-').filter(Boolean);
+  if (words.length >= 2) {
+    return (words[0][0] + words[1][0]).toUpperCase();
+  }
+  return (words[0] || 'XX').substring(0, 2).toUpperCase();
+}
+
+/**
+ * Convert kebab-case to Title Case.
+ * @param {string} str
+ * @returns {string}
+ */
+function toTitleCase(str) {
+  return str
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+// --- CLI entry point ---
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const specFileIdx = args.indexOf('--spec-file');
+
+  if (specFileIdx === -1 || !args[specFileIdx + 1]) {
+    console.error('Usage: node csv-creator.js --spec-file <path>');
+    process.exit(1);
+  }
+
+  const specFilePath = args[specFileIdx + 1];
+
+  (async () => {
+    try {
+      const specContent = await fs.readFile(specFilePath, 'utf8');
+      const specData = yaml.load(specContent);
+      const bmeRoot = path.resolve(__dirname, '../../../../');
+      const outputPath = path.join(bmeRoot, `_${specData.team_name_kebab}`, 'module-help.csv');
+      const result = await createCsv(specData, outputPath);
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.success ? 0 : 1);
+    } catch (err) {
+      console.log(JSON.stringify({ success: false, errors: [err.message] }, null, 2));
+      process.exit(1);
+    }
+  })();
+}
+
+module.exports = { createCsv, buildCsvRows, formatCsvRow, csvQuote, deriveCode, toTitleCase, CSV_HEADER };

package/_bmad/bme/_team-factory/lib/writers/registry-appender.js

@@ -0,0 +1,372 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const {
+  derivePrefix,
+  buildAgentEntry,
+  escapeSingleQuotes,
+  verifyRequire,
+  checkDirtyTree,
+} = require('./registry-writer');
+
+/** @typedef {import('../types/factory-types').RegistryResult} RegistryResult */
+
+/**
+ * Append a new agent to an existing team's module block in agent-registry.js.
+ * Uses Full Write Safety Protocol: stage → validate → check → apply → verify → rollback.
+ *
+ * @param {string} teamNameKebab - Existing team (e.g., "gyre")
+ * @param {Object} newAgentData - Agent spec with id, name, icon, role, persona fields
+ * @param {string} registryPath - Absolute path to agent-registry.js
+ * @param {Object} [options]
+ * @param {boolean} [options.skipDirtyCheck] - Skip git dirty-tree detection (for tests)
+ * @returns {Promise<RegistryResult>}
+ */
+async function appendAgentToBlock(teamNameKebab, newAgentData, registryPath, options = {}) {
+  if (!teamNameKebab || !teamNameKebab.trim()) {
+    return fail(['teamNameKebab is required and must not be empty']);
+  }
+  if (!newAgentData || !newAgentData.id) {
+    return fail(['newAgentData with id is required']);
+  }
+
+  const prefix = derivePrefix(teamNameKebab);
+
+  // --- Read current content ---
+  let currentContent;
+  try {
+    currentContent = await fs.readFile(registryPath, 'utf8');
+  } catch (err) {
+    return fail([`Cannot read registry file: ${err.message}`]);
+  }
+
+  // --- 1. STAGE: Locate existing block and build new entry ---
+  const agentsVarName = `${prefix}_AGENTS`;
+  if (!currentContent.includes(`const ${agentsVarName}`)) {
+    return fail([`Team block not found: const ${agentsVarName} does not exist in registry`]);
+  }
+
+  // Check duplicate agent ID
+  const agentIdLiteral = `id: '${escapeSingleQuotes(newAgentData.id)}'`;
+  if (currentContent.includes(agentIdLiteral)) {
+    return { success: true, written: [], skipped: ['agent already exists in block'], errors: [], rollbackApplied: false };
+  }
+
+  // Build the new agent entry as JS text
+  const entry = buildAgentEntry(newAgentData, teamNameKebab);
+  const entryLines = formatAgentEntry(entry);
+
+  // --- 2. VALIDATE: Structural checks ---
+  // Find the closing ]; of the AGENTS array
+  const arrayStart = currentContent.indexOf(`const ${agentsVarName} = [`);
+  if (arrayStart === -1) {
+    return fail([`Cannot parse ${agentsVarName} array start`]);
+  }
+
+  const closingBracket = findArrayClose(currentContent, arrayStart);
+  if (closingBracket === -1) {
+    return fail([`Cannot find closing ]; for ${agentsVarName}`]);
+  }
+
+  // --- 3. CHECK: Dirty-tree detection ---
+  if (!options.skipDirtyCheck) {
+    const dirtyResult = checkDirtyTree(registryPath);
+    if (dirtyResult.dirty) {
+      return { success: false, written: [], skipped: [], errors: [], rollbackApplied: false, dirty: true, diff: dirtyResult.diff };
+    }
+  }
+
+  // --- 4. APPLY: Insert new entry before closing ]; ---
+  const bakPath = `${registryPath}.bak`;
+  if (await fs.pathExists(bakPath)) {
+    return fail(['Stale .bak file exists — a previous run may have crashed. Remove it manually before retrying.']);
+  }
+
+  try {
+    await fs.writeFile(bakPath, currentContent, 'utf8');
+  } catch (err) {
+    return fail([`Failed to create backup: ${err.message}`]);
+  }
+
+  // Insert the new entry before the closing ];
+  const before = currentContent.slice(0, closingBracket);
+  const after = currentContent.slice(closingBracket);
+  const modified = before + entryLines + '\n' + after;
+
+  try {
+    await fs.writeFile(registryPath, modified, 'utf8');
+  } catch (err) {
+    await fs.writeFile(registryPath, currentContent, 'utf8');
+    await fs.remove(bakPath);
+    return { success: false, written: [], skipped: [], errors: [`Write failed: ${err.message}`], rollbackApplied: true };
+  }
+
+  // --- 5. VERIFY: Re-read + node require() ---
+  const verifyError = verifyRequire(registryPath);
+  if (verifyError) {
+    await fs.writeFile(registryPath, currentContent, 'utf8');
+    await fs.remove(bakPath);
+    return { success: false, written: [], skipped: [], errors: [verifyError], rollbackApplied: true };
+  }
+
+  // Verify new agent appears in the file
+  const verifyContent = await fs.readFile(registryPath, 'utf8');
+  if (!verifyContent.includes(agentIdLiteral)) {
+    await fs.writeFile(registryPath, currentContent, 'utf8');
+    await fs.remove(bakPath);
+    return { success: false, written: [], skipped: [], errors: ['Post-write verification: new agent entry not found'], rollbackApplied: true };
+  }
+
+  // --- Cleanup ---
+  await fs.remove(bakPath);
+
+  return {
+    success: true,
+    written: [newAgentData.id],
+    skipped: [],
+    errors: [],
+    rollbackApplied: false,
+  };
+}
+
+/**
+ * Format an agent entry object as JS source text for insertion into AGENTS array.
+ * @param {Object} entry - From buildAgentEntry
+ * @returns {string}
+ */
+function formatAgentEntry(entry) {
+  const lines = [];
+  lines.push('  {');
+  lines.push(`    id: '${escapeSingleQuotes(entry.id)}', name: '${escapeSingleQuotes(entry.name)}', icon: '${entry.icon}',`);
+  lines.push(`    title: '${escapeSingleQuotes(entry.title)}', stream: '${escapeSingleQuotes(entry.stream)}',`);
+  lines.push('    persona: {');
+  lines.push(`      role: '${escapeSingleQuotes(entry.persona.role)}',`);
+  lines.push(`      identity: '${escapeSingleQuotes(entry.persona.identity)}',`);
+  lines.push(`      communication_style: '${escapeSingleQuotes(entry.persona.communication_style)}',`);
+  lines.push(`      expertise: '${escapeSingleQuotes(entry.persona.expertise)}',`);
+  lines.push('    },');
+  lines.push('  },');
+  return lines.join('\n');
+}
+
+/**
+ * Find the closing ]; of an array that starts with `const NAME = [`.
+ * Counts bracket depth to handle nested objects.
+ * @param {string} content
+ * @param {number} startIdx - Index of `const NAME = [`
+ * @returns {number} Index of the `]` in `];`, or -1
+ */
+function findArrayClose(content, startIdx) {
+  const bracketOpen = content.indexOf('[', startIdx);
+  if (bracketOpen === -1) return -1;
+
+  let depth = 0;
+  let inString = false;
+  let stringChar = '';
+  let escaped = false;
+
+  for (let i = bracketOpen; i < content.length; i++) {
+    const ch = content[i];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+
+    if (ch === '\\') {
+      escaped = true;
+      continue;
+    }
+
+    if (inString) {
+      if (ch === stringChar) {
+        inString = false;
+      }
+      continue;
+    }
+
+    // Skip line comments
+    if (ch === '/' && content[i + 1] === '/') {
+      const eol = content.indexOf('\n', i);
+      i = eol === -1 ? content.length : eol;
+      continue;
+    }
+
+    // Skip block comments
+    if (ch === '/' && content[i + 1] === '*') {
+      const end = content.indexOf('*/', i + 2);
+      i = end === -1 ? content.length : end + 1;
+      continue;
+    }
+
+    if (ch === "'" || ch === '"' || ch === '`') {
+      inString = true;
+      stringChar = ch;
+      continue;
+    }
+
+    if (ch === '[') depth++;
+    if (ch === ']') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+
+  return -1;
+}
+
+/**
+ * Create a failure result.
+ * @param {string[]} errors
+ * @returns {RegistryResult}
+ */
+function fail(errors) {
+  return { success: false, written: [], skipped: [], errors, rollbackApplied: false };
+}
+
+/**
+ * Append a new workflow entry to an existing team's WORKFLOWS array in agent-registry.js.
+ * Uses Full Write Safety Protocol: stage → validate → check → apply → verify → rollback.
+ *
+ * @param {string} teamNameKebab - Existing team (e.g., "gyre")
+ * @param {string} workflowName - Workflow name (kebab-case, e.g., "data-analysis")
+ * @param {string} agentId - Agent ID this workflow belongs to (e.g., "stack-detective")
+ * @param {string} registryPath - Absolute path to agent-registry.js
+ * @param {Object} [options]
+ * @param {boolean} [options.skipDirtyCheck] - Skip git dirty-tree detection (for tests)
+ * @returns {Promise<RegistryResult>}
+ */
+async function appendWorkflowToBlock(teamNameKebab, workflowName, agentId, registryPath, options = {}) {
+  if (!teamNameKebab || !teamNameKebab.trim()) {
+    return fail(['teamNameKebab is required and must not be empty']);
+  }
+  if (!workflowName || !workflowName.trim()) {
+    return fail(['workflowName is required and must not be empty']);
+  }
+  if (!agentId || !agentId.trim()) {
+    return fail(['agentId is required and must not be empty']);
+  }
+
+  // Normalize inputs — trim whitespace to prevent phantom entries
+  teamNameKebab = teamNameKebab.trim();
+  workflowName = workflowName.trim();
+  agentId = agentId.trim();
+
+  const prefix = derivePrefix(teamNameKebab);
+
+  // --- Read current content ---
+  let currentContent;
+  try {
+    currentContent = await fs.readFile(registryPath, 'utf8');
+  } catch (err) {
+    return fail([`Cannot read registry file: ${err.message}`]);
+  }
+
+  // --- 1. STAGE: Locate existing block and build new entry ---
+  const workflowsVarName = `${prefix}_WORKFLOWS`;
+  if (!currentContent.includes(`const ${workflowsVarName}`)) {
+    return fail([`Team block not found: const ${workflowsVarName} does not exist in registry`]);
+  }
+
+  // --- 2. VALIDATE: Structural checks ---
+  const arrayStart = currentContent.indexOf(`const ${workflowsVarName} = [`);
+  if (arrayStart === -1) {
+    return fail([`Cannot parse ${workflowsVarName} array start`]);
+  }
+
+  const closingBracket = findArrayClose(currentContent, arrayStart);
+  if (closingBracket === -1) {
+    return fail([`Cannot find closing ]; for ${workflowsVarName}`]);
+  }
+
+  // Check duplicate workflow entry — scoped to THIS team's WORKFLOWS block only
+  const nameLiteral = `name: '${escapeSingleQuotes(workflowName)}'`;
+  const blockContent = currentContent.slice(arrayStart, closingBracket + 1);
+  if (blockContent.includes(nameLiteral)) {
+    return { success: true, written: [], skipped: ['workflow already exists in block'], errors: [], rollbackApplied: false };
+  }
+
+  // --- 3. CHECK: Dirty-tree detection ---
+  if (!options.skipDirtyCheck) {
+    const dirtyResult = checkDirtyTree(registryPath);
+    if (dirtyResult.dirty) {
+      return { success: false, written: [], skipped: [], errors: [], rollbackApplied: false, dirty: true, diff: dirtyResult.diff };
+    }
+  }
+
+  // --- 4. APPLY: Insert new entry before closing ]; ---
+  const bakPath = `${registryPath}.bak`;
+  if (await fs.pathExists(bakPath)) {
+    return fail(['Stale .bak file exists — a previous run may have crashed. Remove it manually before retrying.']);
+  }
+
+  try {
+    await fs.writeFile(bakPath, currentContent, 'utf8');
+  } catch (err) {
+    return fail([`Failed to create backup: ${err.message}`]);
+  }
+
+  // Build workflow entry line
+  const entryLine = `  { name: '${escapeSingleQuotes(workflowName)}', agent: '${escapeSingleQuotes(agentId)}' },`;
+
+  const before = currentContent.slice(0, closingBracket);
+  const after = currentContent.slice(closingBracket);
+  const modified = before + entryLine + '\n' + after;
+
+  try {
+    await fs.writeFile(registryPath, modified, 'utf8');
+  } catch (err) {
+    let rollbackApplied = false;
+    try {
+      await fs.writeFile(registryPath, currentContent, 'utf8');
+      rollbackApplied = true;
+    } catch (rollbackErr) {
+      return { success: false, written: [], skipped: [], errors: [`Write failed: ${err.message}`, `Rollback also failed: ${rollbackErr.message}`], rollbackApplied: false };
+    }
+    await fs.remove(bakPath).catch(() => {});
+    return { success: false, written: [], skipped: [], errors: [`Write failed: ${err.message}`], rollbackApplied };
+  }
+
+  // --- 5. VERIFY: Re-read + node require() ---
+  const verifyError = verifyRequire(registryPath);
+  if (verifyError) {
+    try {
+      await fs.writeFile(registryPath, currentContent, 'utf8');
+      await fs.remove(bakPath);
+    } catch (rollbackErr) {
+      return { success: false, written: [], skipped: [], errors: [verifyError, `Rollback failed: ${rollbackErr.message}`], rollbackApplied: false };
+    }
+    return { success: false, written: [], skipped: [], errors: [verifyError], rollbackApplied: true };
+  }
+
+  // Verify new workflow appears in the file
+  const verifyContent = await fs.readFile(registryPath, 'utf8');
+  if (!verifyContent.includes(nameLiteral)) {
+    try {
+      await fs.writeFile(registryPath, currentContent, 'utf8');
+      await fs.remove(bakPath);
+    } catch (rollbackErr) {
+      return { success: false, written: [], skipped: [], errors: ['Post-write verification: new workflow entry not found', `Rollback failed: ${rollbackErr.message}`], rollbackApplied: false };
+    }
+    return { success: false, written: [], skipped: [], errors: ['Post-write verification: new workflow entry not found'], rollbackApplied: true };
+  }
+
+  // --- Cleanup ---
+  await fs.remove(bakPath);
+
+  return {
+    success: true,
+    written: [workflowName],
+    skipped: [],
+    errors: [],
+    rollbackApplied: false,
+  };
+}
+
+module.exports = {
+  appendAgentToBlock,
+  appendWorkflowToBlock,
+  formatAgentEntry,
+  findArrayClose,
+};