agileflow 2.92.1 → 2.94.0

package/tools/cli/lib/content-injector.js

@@ -12,6 +12,11 @@
  *   <!-- {{AGENT_LIST}} -->   - Full formatted agent list
  *   <!-- {{COMMAND_LIST}} --> - Full formatted command list
  *
+ * TEMPLATES:
+ *   <!-- {{SESSION_HARNESS}} -->       - Session harness protocol (generic)
+ *   <!-- {{SESSION_HARNESS:AG-API}} --> - Session harness protocol (with agent ID)
+ *   <!-- {{QUALITY_GATE_PRIORITIES}} --> - Quality gate priorities (CRITICAL/HIGH/MEDIUM)
+ *
  * METADATA:
  *   {{VERSION}}        - AgileFlow version from package.json
  *   {{INSTALL_DATE}}   - Date of installation (YYYY-MM-DD)
@@ -225,6 +230,239 @@ function generateCommandList(commandsDir) {
   return output;
 }
 
+// =============================================================================
+// Template Generation Functions
+// =============================================================================
+
+/**
+ * Session harness template cache
+ * @type {string|null}
+ */
+let sessionHarnessTemplateCache = null;
+
+/**
+ * Quality gate priorities template cache
+ * @type {string|null}
+ */
+let qualityGatePrioritiesCache = null;
+
+/**
+ * Load session harness template from templates directory
+ * @param {string} coreDir - Path to core directory
+ * @returns {string} Template content or empty string if not found
+ */
+function loadSessionHarnessTemplate(coreDir) {
+  // Return cached template if available
+  if (sessionHarnessTemplateCache !== null) {
+    return sessionHarnessTemplateCache;
+  }
+
+  const templatePath = path.join(coreDir, 'templates', 'session-harness-protocol.md');
+
+  if (!fs.existsSync(templatePath)) {
+    // Template not found, return empty string
+    sessionHarnessTemplateCache = '';
+    return sessionHarnessTemplateCache;
+  }
+
+  // Validate path is within core directory (security)
+  if (!isPathSafe(templatePath, coreDir)) {
+    sessionHarnessTemplateCache = '';
+    return sessionHarnessTemplateCache;
+  }
+
+  try {
+    sessionHarnessTemplateCache = fs.readFileSync(templatePath, 'utf8');
+    return sessionHarnessTemplateCache;
+  } catch (err) {
+    sessionHarnessTemplateCache = '';
+    return sessionHarnessTemplateCache;
+  }
+}
+
+/**
+ * Generate session harness protocol content for a specific agent
+ * @param {string} coreDir - Path to core directory
+ * @param {string} agentId - Agent ID (e.g., "AG-API", "AG-UI")
+ * @returns {string} Session harness content with agent ID substituted
+ */
+function generateSessionHarnessContent(coreDir, agentId = 'AGENT') {
+  const template = loadSessionHarnessTemplate(coreDir);
+
+  if (!template) {
+    return '';
+  }
+
+  // Substitute agent ID in the template
+  // The template uses {AGENT_ID} as placeholder
+  return template.replace(/\{AGENT_ID\}/g, agentId);
+}
+
+/**
+ * Clear the session harness template cache
+ * Useful for testing or when template file changes
+ */
+function clearSessionHarnessCache() {
+  sessionHarnessTemplateCache = null;
+}
+
+/**
+ * Load quality gate priorities template from templates directory
+ * @param {string} coreDir - Path to core directory
+ * @returns {string} Template content or empty string if not found
+ */
+function loadQualityGatePrioritiesTemplate(coreDir) {
+  // Return cached template if available
+  if (qualityGatePrioritiesCache !== null) {
+    return qualityGatePrioritiesCache;
+  }
+
+  const templatePath = path.join(coreDir, 'templates', 'quality-gate-priorities.md');
+
+  if (!fs.existsSync(templatePath)) {
+    qualityGatePrioritiesCache = '';
+    return qualityGatePrioritiesCache;
+  }
+
+  // Validate path is within core directory (security)
+  if (!isPathSafe(templatePath, coreDir)) {
+    qualityGatePrioritiesCache = '';
+    return qualityGatePrioritiesCache;
+  }
+
+  try {
+    qualityGatePrioritiesCache = fs.readFileSync(templatePath, 'utf8');
+    return qualityGatePrioritiesCache;
+  } catch (err) {
+    qualityGatePrioritiesCache = '';
+    return qualityGatePrioritiesCache;
+  }
+}
+
+/**
+ * Generate quality gate priorities content for a specific agent
+ * @param {string} coreDir - Path to core directory
+ * @param {string} agentId - Agent ID (e.g., "AG-API", "AG-UI")
+ * @returns {string} Quality gate priorities content with agent ID substituted
+ */
+function generateQualityGatePrioritiesContent(coreDir, agentId = 'AGENT') {
+  const template = loadQualityGatePrioritiesTemplate(coreDir);
+
+  if (!template) {
+    return '';
+  }
+
+  // Substitute placeholders in the template
+  return template
+    .replace(/\{AGENT_ID\}/g, agentId)
+    .replace(/\{TIMESTAMP\}/g, new Date().toISOString())
+    .replace(/\{STORY_ID\}/g, 'US-XXXX');
+}
+
+/**
+ * Clear the quality gate priorities template cache
+ * Useful for testing or when template file changes
+ */
+function clearQualityGatePrioritiesCache() {
+  qualityGatePrioritiesCache = null;
+}
+
+// =============================================================================
+// Preserve Rules Expansion Functions
+// =============================================================================
+
+/**
+ * Preserve rules template cache
+ * @type {Object|null}
+ */
+let preserveRulesCache = null;
+
+/**
+ * Load preserve rules definitions from templates directory
+ * @param {string} coreDir - Path to core directory
+ * @returns {Object} Rules object with category keys and rule arrays
+ */
+function loadPreserveRules(coreDir) {
+  // Return cached rules if available
+  if (preserveRulesCache !== null) {
+    return preserveRulesCache;
+  }
+
+  const rulesPath = path.join(coreDir, 'templates', 'preserve-rules.json');
+
+  if (!fs.existsSync(rulesPath)) {
+    preserveRulesCache = {};
+    return preserveRulesCache;
+  }
+
+  // Validate path is within core directory (security)
+  if (!isPathSafe(rulesPath, coreDir)) {
+    preserveRulesCache = {};
+    return preserveRulesCache;
+  }
+
+  try {
+    const content = fs.readFileSync(rulesPath, 'utf8');
+    preserveRulesCache = JSON.parse(content);
+    return preserveRulesCache;
+  } catch (err) {
+    preserveRulesCache = {};
+    return preserveRulesCache;
+  }
+}
+
+/**
+ * Expand preserve rules placeholders in content
+ * Replaces "{{RULES:category}}" with actual rule strings from the template
+ *
+ * @param {string} content - Content with preserve rules placeholders
+ * @param {string} coreDir - Path to core directory
+ * @returns {string} Content with rules expanded
+ */
+function expandPreserveRules(content, coreDir) {
+  const rules = loadPreserveRules(coreDir);
+
+  if (!rules || Object.keys(rules).length === 0) {
+    return content;
+  }
+
+  // Pattern matches: - "{{RULES:category}}" in YAML preserve_rules arrays
+  // We need to handle the YAML list context carefully
+  const pattern = /- "\{\{RULES:(\w+)\}\}"/g;
+
+  return content.replace(pattern, (match, category) => {
+    const ruleList = rules[category];
+
+    if (!ruleList || !Array.isArray(ruleList) || ruleList.length === 0) {
+      // Unknown category or empty, keep original placeholder as warning
+      return match;
+    }
+
+    // Sanitize rules before injecting
+    const sanitizedRules = ruleList.map(rule => {
+      // Escape double quotes in rule text
+      const escaped = String(rule).replace(/"/g, '\\"');
+      // Validate it's a reasonable rule string
+      if (escaped.length > 500) {
+        return escaped.substring(0, 500);
+      }
+      return escaped;
+    });
+
+    // Return expanded rules as YAML list items with proper indentation
+    // Each rule becomes: - "rule text"
+    return sanitizedRules.map(rule => `- "${rule}"`).join('\n    ');
+  });
+}
+
+/**
+ * Clear the preserve rules template cache
+ * Useful for testing or when template file changes
+ */
+function clearPreserveRulesCache() {
+  preserveRulesCache = null;
+}
+
 // =============================================================================
 // Main Injection Function
 // =============================================================================
@@ -243,6 +481,11 @@ function injectContent(content, context = {}) {
 
   let result = content;
 
+  // Expand preserve rules placeholders first (YAML frontmatter processing)
+  if (coreDir && fs.existsSync(coreDir) && result.includes('{{RULES:')) {
+    result = expandPreserveRules(result, coreDir);
+  }
+
   // Get counts if core directory is available
   let counts = { commands: 0, agents: 0, skills: 0 };
   if (coreDir && fs.existsSync(coreDir)) {
@@ -283,6 +526,69 @@ function injectContent(content, context = {}) {
       result = result.replace(/<!-- \{\{COMMAND_LIST\}\} -->/g, commandList);
       result = result.replace(/\{\{COMMAND_LIST\}\}/g, commandList);
     }
+
+    // Replace session harness template placeholder
+    // Supports two formats:
+    //   <!-- {{SESSION_HARNESS}} -->        - Uses default agent ID
+    //   <!-- {{SESSION_HARNESS:AG-API}} --> - Uses specified agent ID
+    if (result.includes('SESSION_HARNESS')) {
+      // First, handle agent-specific format: <!-- {{SESSION_HARNESS:AG-XXX}} -->
+      const agentSpecificPattern = /<!-- \{\{SESSION_HARNESS:(AG-[A-Z]+)\}\} -->/g;
+      result = result.replace(agentSpecificPattern, (match, agentId) => {
+        return generateSessionHarnessContent(coreDir, agentId);
+      });
+
+      // Then, handle generic format: <!-- {{SESSION_HARNESS}} -->
+      // Try to extract agent ID from frontmatter name field if available
+      const genericPattern = /<!-- \{\{SESSION_HARNESS\}\} -->/g;
+      result = result.replace(genericPattern, () => {
+        // Try to get agent ID from frontmatter 'name' field
+        // Look for "name: agileflow-xxx" pattern in the content
+        const frontmatterMatch = result.match(/^---[\s\S]*?name:\s*(agileflow-)?(\w+)[\s\S]*?---/m);
+        let agentId = 'AGENT';
+        if (frontmatterMatch && frontmatterMatch[2]) {
+          // Convert agent name to uppercase agent ID format
+          // e.g., "api" -> "AG-API", "ui" -> "AG-UI"
+          agentId = `AG-${frontmatterMatch[2].toUpperCase()}`;
+        }
+        return generateSessionHarnessContent(coreDir, agentId);
+      });
+
+      // Also handle non-comment format: {{SESSION_HARNESS}}
+      result = result.replace(/\{\{SESSION_HARNESS\}\}/g, () => {
+        const frontmatterMatch = result.match(/^---[\s\S]*?name:\s*(agileflow-)?(\w+)[\s\S]*?---/m);
+        let agentId = 'AGENT';
+        if (frontmatterMatch && frontmatterMatch[2]) {
+          agentId = `AG-${frontmatterMatch[2].toUpperCase()}`;
+        }
+        return generateSessionHarnessContent(coreDir, agentId);
+      });
+    }
+
+    // Replace quality gate priorities template placeholder
+    // Supports: <!-- {{QUALITY_GATE_PRIORITIES}} -->
+    if (result.includes('QUALITY_GATE_PRIORITIES')) {
+      // Handle comment format: <!-- {{QUALITY_GATE_PRIORITIES}} -->
+      const qualityGatePattern = /<!-- \{\{QUALITY_GATE_PRIORITIES\}\} -->/g;
+      result = result.replace(qualityGatePattern, () => {
+        const frontmatterMatch = result.match(/^---[\s\S]*?name:\s*(agileflow-)?(\w+)[\s\S]*?---/m);
+        let agentId = 'AGENT';
+        if (frontmatterMatch && frontmatterMatch[2]) {
+          agentId = `AG-${frontmatterMatch[2].toUpperCase()}`;
+        }
+        return generateQualityGatePrioritiesContent(coreDir, agentId);
+      });
+
+      // Also handle non-comment format: {{QUALITY_GATE_PRIORITIES}}
+      result = result.replace(/\{\{QUALITY_GATE_PRIORITIES\}\}/g, () => {
+        const frontmatterMatch = result.match(/^---[\s\S]*?name:\s*(agileflow-)?(\w+)[\s\S]*?---/m);
+        let agentId = 'AGENT';
+        if (frontmatterMatch && frontmatterMatch[2]) {
+          agentId = `AG-${frontmatterMatch[2].toUpperCase()}`;
+        }
+        return generateQualityGatePrioritiesContent(coreDir, agentId);
+      });
+    }
   }
 
   // Replace folder placeholders with sanitized values
@@ -380,6 +686,9 @@ function hasPlaceholders(content) {
     /\{\{INSTALL_DATE\}\}/,
     /\{\{AGENT_LIST\}\}/,
     /\{\{COMMAND_LIST\}\}/,
+    /\{\{SESSION_HARNESS\}\}/,
+    /\{\{QUALITY_GATE_PRIORITIES\}\}/,
+    /\{\{RULES:\w+\}\}/,
     /\{agileflow_folder\}/,
   ];
 
@@ -401,6 +710,25 @@ function getPlaceholderDocs() {
       '<!-- {{AGENT_LIST}} -->': 'Full formatted agent list with details',
       '<!-- {{COMMAND_LIST}} -->': 'Full formatted command list',
     },
+    templates: {
+      '<!-- {{SESSION_HARNESS}} -->':
+        'Session harness protocol (auto-detects agent ID from frontmatter)',
+      '<!-- {{SESSION_HARNESS:AG-API}} -->': 'Session harness protocol with explicit agent ID',
+      '<!-- {{QUALITY_GATE_PRIORITIES}} -->':
+        'Quality gate priorities with CRITICAL/HIGH/MEDIUM levels',
+    },
+    preserve_rules: {
+      '{{RULES:json_operations}}': 'Rules for safe JSON file modifications',
+      '{{RULES:file_preview}}': 'Rules for showing previews before writing',
+      '{{RULES:user_confirmation}}': 'Rules for using AskUserQuestion tool',
+      '{{RULES:todo_tracking}}': 'Rules for using TodoWrite tool',
+      '{{RULES:bus_messaging}}': 'Rules for bus message logging',
+      '{{RULES:plan_mode}}': 'Rules for using EnterPlanMode',
+      '{{RULES:commit_approval}}': 'Rules about git commits',
+      '{{RULES:delegation}}': 'Rules for expert delegation',
+      '{{RULES:research_first}}': 'Rules for checking research before starting',
+      '{{RULES:status_updates}}': 'Rules for updating status.json',
+    },
     metadata: {
       '{{VERSION}}': 'AgileFlow version from package.json',
       '{{INSTALL_DATE}}': 'Installation date (YYYY-MM-DD)',
@@ -423,6 +751,16 @@ module.exports = {
   generateAgentList,
   generateCommandList,
 
+  // Template generation
+  generateSessionHarnessContent,
+  clearSessionHarnessCache,
+  generateQualityGatePrioritiesContent,
+  clearQualityGatePrioritiesCache,
+
+  // Preserve rules expansion
+  expandPreserveRules,
+  clearPreserveRulesCache,
+
   // Main injection
   injectContent,
   hasPlaceholders,