convoke-agents 3.0.4 → 3.2.0

package/_bmad/bme/_team-factory/lib/spec-writer.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/** @typedef {import('./types/factory-types').TeamSpec} TeamSpec */
+
+/**
+ * Write a team spec to a YAML file with atomic write safety.
+ * Protocol: write to .tmp → validate parse → rename to target.
+ *
+ * @param {TeamSpec} spec - The team spec object to write
+ * @param {string} targetPath - Absolute path to the output YAML file
+ * @returns {Promise<{ success: boolean, errors: string[] }>}
+ */
+async function writeSpec(spec, targetPath) {
+  if (!spec || typeof spec !== 'object') {
+    return { success: false, errors: ['spec must be a non-null object'] };
+  }
+  if (!targetPath || !path.isAbsolute(targetPath)) {
+    return { success: false, errors: ['targetPath must be an absolute path'] };
+  }
+
+  // Serialize to YAML
+  let yamlContent;
+  try {
+    yamlContent = yaml.dump(spec, {
+      indent: 2,
+      lineWidth: 120,
+      noRefs: true,
+      sortKeys: false,
+      quotingType: '"',
+    });
+  } catch (err) {
+    return { success: false, errors: [`YAML serialization failed: ${err.message}`] };
+  }
+
+  // Atomic write: .tmp → validate → rename
+  const tmpPath = targetPath + '.tmp';
+
+  try {
+    await fs.ensureDir(path.dirname(targetPath));
+    await fs.writeFile(tmpPath, yamlContent, 'utf8');
+  } catch (err) {
+    return { success: false, errors: [`Failed to write temp file: ${err.message}`] };
+  }
+
+  // Validate: re-read and parse to confirm round-trip integrity
+  try {
+    const reRead = await fs.readFile(tmpPath, 'utf8');
+    const parsed = yaml.load(reRead);
+    if (!parsed || typeof parsed !== 'object') {
+      await fs.remove(tmpPath);
+      return { success: false, errors: ['Round-trip validation failed: parsed result is empty or not an object'] };
+    }
+    // Verify key fields survived serialization
+    const checks = [
+      ['team_name_kebab', parsed.team_name_kebab, spec.team_name_kebab],
+      ['composition_pattern', parsed.composition_pattern, spec.composition_pattern],
+      ['agents.length', (parsed.agents || []).length, (spec.agents || []).length],
+    ];
+    for (const [field, actual, expected] of checks) {
+      if (actual !== expected) {
+        await fs.remove(tmpPath);
+        return { success: false, errors: [`Round-trip validation failed: ${field} mismatch ("${actual}" vs "${expected}")`] };
+      }
+    }
+  } catch (err) {
+    await fs.remove(tmpPath).catch(() => {});
+    return { success: false, errors: [`Round-trip validation failed: ${err.message}`] };
+  }
+
+  // Rename .tmp → target
+  try {
+    await fs.rename(tmpPath, targetPath);
+  } catch (err) {
+    await fs.remove(tmpPath).catch(() => {});
+    return { success: false, errors: [`Failed to rename temp file to target: ${err.message}`] };
+  }
+
+  return { success: true, errors: [] };
+}
+
+/**
+ * Update specific fields in an existing spec file.
+ * Loads current spec, merges updates, writes back atomically.
+ *
+ * @param {string} specPath - Absolute path to existing spec file
+ * @param {Object} updates - Fields to update (shallow merge at top level, deep merge for nested objects)
+ * @returns {Promise<{ success: boolean, errors: string[] }>}
+ */
+async function updateSpec(specPath, updates) {
+  let raw;
+  try {
+    raw = await fs.readFile(specPath, 'utf8');
+  } catch (err) {
+    return { success: false, errors: [`Cannot read spec file: ${err.message}`] };
+  }
+
+  let current;
+  try {
+    current = yaml.load(raw);
+  } catch (err) {
+    return { success: false, errors: [`Invalid YAML in existing spec: ${err.message}`] };
+  }
+
+  // Shallow merge with deep merge for known nested objects
+  const merged = { ...current };
+  for (const [key, value] of Object.entries(updates)) {
+    if (key === 'progress' && typeof value === 'object' && typeof merged.progress === 'object') {
+      merged.progress = { ...merged.progress, ...value };
+    } else if (key === 'integration' && typeof value === 'object' && typeof merged.integration === 'object') {
+      merged.integration = { ...merged.integration, ...value };
+    } else if (key === 'metrics' && typeof value === 'object' && typeof merged.metrics === 'object') {
+      merged.metrics = { ...merged.metrics, ...value };
+    } else {
+      merged[key] = value;
+    }
+  }
+
+  return writeSpec(merged, specPath);
+}
+
+module.exports = {
+  writeSpec,
+  updateSpec,
+};

package/_bmad/bme/_team-factory/lib/types/factory-types.js

@@ -0,0 +1,193 @@
+'use strict';
+
+/**
+ * JSDoc type definitions for Team Factory integration wiring modules.
+ * Canonical source for all factory shapes — no runtime code.
+ */
+
+/**
+ * Parsed team spec file shape.
+ * @typedef {Object} TeamSpec
+ * @property {string} schema_version
+ * @property {string} team_name
+ * @property {string} team_name_kebab
+ * @property {string} [description] - Optional team description for config.yaml
+ * @property {string} composition_pattern - "Sequential" or "Independent"
+ * @property {string} created - ISO date string
+ * @property {string} factory_version
+ * @property {AgentSpec[]} agents
+ * @property {ContractSpec[]} contracts
+ * @property {ContractSpec[]} feedback_contracts
+ * @property {IntegrationSpec} integration
+ * @property {Object} progress
+ */
+
+/**
+ * Agent specification from spec file.
+ * @typedef {Object} AgentSpec
+ * @property {string} id
+ * @property {string} role
+ * @property {string[]} capabilities
+ * @property {number} [pipeline_position] - Sequential only
+ * @property {string[]} overlap_acknowledgments
+ */
+
+/**
+ * Contract specification from spec file.
+ * @typedef {Object} ContractSpec
+ * @property {string} id
+ * @property {string} source_agent
+ * @property {string[]} target_agents
+ * @property {string} artifact_title
+ * @property {string} artifact_description
+ * @property {string[]} key_sections
+ * @property {string} file_name
+ * @property {string[]} input_artifacts
+ * @property {boolean} optional
+ */
+
+/**
+ * Integration decisions from spec file.
+ * @typedef {Object} IntegrationSpec
+ * @property {string} output_directory
+ * @property {string} compass_routing - "optional", "per-agent", "required", or "shared-reference"
+ * @property {string} [contract_prefix]
+ */
+
+/**
+ * Config.yaml data shape (matches Gyre/Vortex schema).
+ * @typedef {Object} ConfigData
+ * @property {string} submodule_name
+ * @property {string} description
+ * @property {string} module
+ * @property {string} output_folder
+ * @property {string[]} agents
+ * @property {string[]} workflows
+ * @property {string} version
+ * @property {string} user_name
+ * @property {string} communication_language
+ * @property {boolean} party_mode_enabled
+ * @property {string} core_module
+ */
+
+/**
+ * Module-help.csv row shape.
+ * @typedef {Object} CsvRow
+ * @property {string} module
+ * @property {string} phase
+ * @property {string} name
+ * @property {string} code
+ * @property {number} sequence
+ * @property {string} workflow_file
+ * @property {string} command
+ * @property {string} required
+ * @property {string} agent
+ * @property {string} options
+ * @property {string} description
+ * @property {string} output_location
+ * @property {string} outputs
+ */
+
+/**
+ * Activation validation result per agent.
+ * @typedef {Object} ActivationResult
+ * @property {string} agentFile
+ * @property {ActivationCheck[]} checks
+ * @property {string[]} errors
+ */
+
+/**
+ * Individual activation check.
+ * @typedef {Object} ActivationCheck
+ * @property {string} check - Description of what was checked
+ * @property {boolean} passed
+ * @property {string} [detail] - Additional info if failed
+ */
+
+/**
+ * Collision detection result.
+ * @typedef {Object} Collision
+ * @property {string} field - "submodule_name", "agent", or "workflow"
+ * @property {string} value - The colliding value
+ * @property {string} existingModule - Module that already has this value
+ */
+
+/**
+ * Creator result shape (shared by config-creator and csv-creator).
+ * @typedef {Object} CreatorResult
+ * @property {boolean} success
+ * @property {string} [filePath]
+ * @property {string[]} errors
+ * @property {number} [rowCount] - csv-creator only
+ * @property {Collision[]} [collisions] - config-creator only
+ */
+
+/**
+ * Activation validator result shape.
+ * @typedef {Object} ValidationResult
+ * @property {boolean} valid
+ * @property {ActivationResult[]} results
+ */
+
+/**
+ * Registry writer result shape (Full Write Safety Protocol).
+ * Differs from CreatorResult intentionally — writers return written[]/skipped[] per architecture rule 2.
+ * @typedef {Object} RegistryResult
+ * @property {boolean} success
+ * @property {string[]} written - Const names added to module.exports
+ * @property {string[]} skipped - Reasons for skipping (e.g., 'block already exists')
+ * @property {string[]} errors
+ * @property {boolean} rollbackApplied - True if .bak was restored after verify failure
+ * @property {boolean} [dirty] - True if dirty-tree detection found uncommitted changes
+ * @property {string} [diff] - Git diff output when dirty
+ */
+
+/**
+ * Agent entry in agent-registry.js.
+ * @typedef {Object} RegistryAgentEntry
+ * @property {string} id
+ * @property {string} name - Display name (first name or derived)
+ * @property {string} icon - Unicode emoji character
+ * @property {string} title - Role-based title
+ * @property {string} stream - Team name kebab
+ * @property {RegistryPersona} persona
+ */
+
+/**
+ * Persona sub-object within a registry agent entry.
+ * @typedef {Object} RegistryPersona
+ * @property {string} role
+ * @property {string} identity
+ * @property {string} communication_style
+ * @property {string} expertise
+ */
+
+/**
+ * File manifest entry tracking a created or modified file.
+ * @typedef {Object} ManifestEntry
+ * @property {string} path - File path (relative to project root)
+ * @property {'created' | 'modified'} operation - Whether the file was created or modified
+ * @property {string} module - Team name kebab identifying the owning module
+ */
+
+/**
+ * End-to-end validation result.
+ * @typedef {Object} E2EValidationResult
+ * @property {boolean} valid - True if all checks passed
+ * @property {E2ECheck[]} checks - Individual check results
+ * @property {string[]} errors - Human-readable error messages for failed checks
+ */
+
+/**
+ * Individual end-to-end validation check.
+ * Name uses {PROP}-{SEMANTIC-NAME} format per architecture (line 590).
+ * @typedef {Object} E2ECheck
+ * @property {string} name - Check ID in {PROP}-{SEMANTIC-NAME} format (e.g., CONFIG-EXISTS)
+ * @property {string} stepName - Step that produced the check (e.g., 'structural', 'regression', 'wiring')
+ * @property {boolean} passed - Whether the check passed
+ * @property {string} [expected] - Expected value (included on failure per TF-NFR11)
+ * @property {string} [actual] - Actual value found (included on failure per TF-NFR11)
+ * @property {string} [detail] - Additional context (e.g., file path)
+ */
+
+module.exports = {};

package/_bmad/bme/_team-factory/lib/utils/csv-utils.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * RFC 4180-aware CSV row parser for team factory validation.
+ * Handles quoted fields containing commas and escaped quotes ("").
+ */
+
+/**
+ * Parse a single CSV row into an array of field values.
+ * Handles double-quoted fields per RFC 4180:
+ * - Fields containing commas, quotes, or newlines are enclosed in double quotes
+ * - Double quotes inside quoted fields are escaped as ""
+ *
+ * @param {string} line - A single CSV row string
+ * @returns {string[]} Array of field values
+ */
+function parseCsvRow(line) {
+  const fields = [];
+  let current = '';
+  let inQuotes = false;
+  let i = 0;
+
+  while (i < line.length) {
+    const ch = line[i];
+
+    if (inQuotes) {
+      if (ch === '"') {
+        // Check for escaped quote ""
+        if (i + 1 < line.length && line[i + 1] === '"') {
+          current += '"';
+          i += 2;
+        } else {
+          // End of quoted field
+          inQuotes = false;
+          i++;
+        }
+      } else {
+        current += ch;
+        i++;
+      }
+    } else {
+      if (ch === '"') {
+        inQuotes = true;
+        i++;
+      } else if (ch === ',') {
+        fields.push(current);
+        current = '';
+        i++;
+      } else {
+        current += ch;
+        i++;
+      }
+    }
+  }
+
+  // Push the last field
+  fields.push(current);
+
+  return fields;
+}
+
+module.exports = { parseCsvRow };

package/_bmad/bme/_team-factory/lib/utils/naming-utils.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * Shared naming utilities for team factory modules.
+ * Canonical source for toKebab() and deriveWorkflowName() — no duplication.
+ */
+
+/**
+ * Convert a string to kebab-case.
+ * @param {string} str
+ * @returns {string}
+ */
+function toKebab(str) {
+  if (!str) return '';
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Derive a workflow name for a single agent from spec data.
+ * Uses workflow_names map if present, otherwise derives from first capability.
+ * Falls back to role > agent.id when capabilities are absent.
+ *
+ * @param {Object} agent - Agent spec object with id, role, capabilities
+ * @param {Object} [specData] - Full spec data (checked for workflow_names map)
+ * @returns {string} kebab-case workflow name
+ */
+function deriveWorkflowName(agent, specData) {
+  if (specData && specData.workflow_names && specData.workflow_names[agent.id]) {
+    return specData.workflow_names[agent.id];
+  }
+  if (agent.capabilities && agent.capabilities.length > 0) {
+    const cap = agent.capabilities[0];
+    const wordCount = cap.trim().split(/\s+/).length;
+    if (wordCount > 4 && agent.role) {
+      return toKebab(agent.role);
+    }
+    return toKebab(cap);
+  }
+  return toKebab(agent.role || agent.id);
+}
+
+module.exports = { toKebab, deriveWorkflowName };