@xelth/eck-snapshot 4.1.0 → 4.2.0

package/src/utils/aiHeader.js

@@ -39,39 +39,109 @@ function buildAgentDefinitions(executionAgents) {
   return definitions;
 }
 
-function buildEckManifestSection(eckManifest) {
-  if (!eckManifest) {
-    return '';
+/**
+ * Parse journal entries from JOURNAL.md content
+ * @param {string} journalContent - Raw content of JOURNAL.md
+ * @returns {Array} Array of parsed journal entries
+ */
+function parseJournalEntries(journalContent) {
+  if (!journalContent || typeof journalContent !== 'string') {
+    return [];
   }
 
-  let section = '\n## Project-Specific Manifest (.eck Directory)\n\n';
-  section += 'This project includes a `.eck` directory with specific context and configuration:\n\n';
-
-  if (eckManifest.context) {
-    section += '### Project Context\n\n';
-    section += eckManifest.context + '\n\n';
+  // Split by --- separators, filter empty blocks
+  const blocks = journalContent.split(/^---$/m).filter(b => b.trim());
+  const entries = [];
+
+  for (let i = 0; i < blocks.length; i += 2) {
+    const frontmatter = blocks[i];
+    const body = blocks[i + 1] || '';
+
+    // Parse frontmatter
+    const typeMatch = frontmatter.match(/^type:\s*(.+)$/m);
+    const scopeMatch = frontmatter.match(/^scope:\s*(.+)$/m);
+    const summaryMatch = frontmatter.match(/^summary:\s*(.+)$/m);
+    const dateMatch = frontmatter.match(/^(?:date|timestamp):\s*(.+)$/m);
+    const taskIdMatch = frontmatter.match(/^task_id:\s*(.+)$/m);
+
+    // Extract title from body (first # heading)
+    const titleMatch = body.match(/^#\s+(.+)$/m);
+
+    entries.push({
+      type: typeMatch ? typeMatch[1].trim() : 'unknown',
+      scope: scopeMatch ? scopeMatch[1].trim() : '',
+      summary: summaryMatch ? summaryMatch[1].trim() : (titleMatch ? titleMatch[1].trim() : ''),
+      date: dateMatch ? dateMatch[1].trim() : '',
+      taskId: taskIdMatch ? taskIdMatch[1].trim() : '',
+      body: body.trim()
+    });
   }
 
-  if (eckManifest.operations) {
-    section += '### Operations Guide\n\n';
-    section += eckManifest.operations + '\n\n';
+  return entries;
+}
+
+/**
+ * Build a compact journal summary for the architect
+ * Shows: last entry (full) + 5 previous (headers only) + total count
+ */
+function buildJournalSummary(journalContent) {
+  const entries = parseJournalEntries(journalContent);
+
+  if (entries.length === 0) {
+    return 'No journal entries found.';
   }
 
-  if (eckManifest.journal) {
-    section += '### Development Journal\n\n';
-    section += eckManifest.journal + '\n\n';
+  let summary = '';
+
+  // Last entry - show full details
+  const lastEntry = entries[0];
+  summary += `**Latest Entry** (${lastEntry.date || 'no date'}):\n`;
+  summary += `- Type: \`${lastEntry.type}\` | Scope: \`${lastEntry.scope}\`\n`;
+  summary += `- ${lastEntry.summary}\n`;
+  if (lastEntry.body) {
+    // Include body but limit to first 3 lines
+    const bodyLines = lastEntry.body.split('\n').filter(l => l.trim()).slice(0, 4);
+    summary += bodyLines.map(l => `  ${l}`).join('\n') + '\n';
   }
 
-  if (Object.keys(eckManifest.environment).length > 0) {
-    section += '### Environment Overrides\n\n';
-    section += 'The following environment settings override auto-detected values:\n\n';
-    for (const [key, value] of Object.entries(eckManifest.environment)) {
-      section += `- **${key}**: ${value}\n`;
+  // Previous 5 entries - headers only
+  if (entries.length > 1) {
+    summary += '\n**Previous entries:**\n';
+    const previousEntries = entries.slice(1, 6);
+    for (const entry of previousEntries) {
+      summary += `- \`${entry.type}(${entry.scope})\`: ${entry.summary}\n`;
     }
-    section += '\n';
   }
 
-  section += '**Important**: Use this manifest information when formulating technical plans and briefing execution agents. The context, operations guide, and journal provide crucial project-specific knowledge that should inform your decisions.\n\n';
+  // Total count
+  if (entries.length > 6) {
+    summary += `\n*...and ${entries.length - 6} more entries in .eck/JOURNAL.md*\n`;
+  }
+
+  return summary;
+}
+
+function buildEckManifestSection(eckManifest) {
+  if (!eckManifest) {
+    return '';
+  }
+
+  let section = '\n## Project Context (.eck Directory)\n\n';
+  section += 'This project has a `.eck/` directory with project-specific context files.\n';
+  section += 'The coder agent can read these files when needed. Available files:\n\n';
+  section += '- `CONTEXT.md` - Project overview and architecture\n';
+  section += '- `OPERATIONS.md` - Common commands and workflows\n';
+  section += '- `JOURNAL.md` - Development history\n';
+  section += '- `ROADMAP.md` - Planned features\n';
+  section += '- `TECH_DEBT.md` - Known issues and refactoring needs\n';
+  section += '- `ENVIRONMENT.md` - Environment-specific settings\n\n';
+
+  // Add journal summary (compact view for architect)
+  if (eckManifest.journal) {
+    section += '### Recent Development Activity\n\n';
+    section += buildJournalSummary(eckManifest.journal) + '\n';
+  }
+
   section += '---\n\n';
 
   return section;
@@ -255,7 +325,7 @@ Your primary role is **Senior Architect**. You formulate high-level strategy. Fo
 
   - **Senior Architect (You):** Sets strategy, defines high-level tasks.
   - **Junior Architect (\`gemini_wsl\`):** Receives strategic tasks, analyzes the \`_ja.md\` snapshot, breaks the task down, and commands the Coder.
-  - **Coder (\`claude\`):** Receives small, precise coding tasks from the Junior Architect. **Claude is highly trained for code generation and should be used for all primary code-writing tasks**, while \`gemini_wsl\` can use its own tools for analysis, validation, and running shell commands.`;
+  - **Coder (\`claude\`):** Receives small, precise coding tasks from the Junior Architect. **Claude is responsible for keeping the .eck/ manifest files accurate and synchronized with the code.**`;
 
       commandFormats = `### COMMAND FORMATS
 
@@ -339,92 +409,74 @@ Use \`execute_strategic_task\` for complex features. The JA will use its own sna
     } else {
       hierarchicalWorkflow = `### AGENT WORKFLOW
 
-Your role is **Architect**. You formulate technical plans and delegate code implementation tasks directly to the **Coder** agents (e.g., \`local_dev\`).
+Your role is **Architect**. You formulate technical plans and delegate code implementation tasks directly to the **Coder** agents.
 
-  - **Architect (You):** Sets strategy, defines tasks.
-  - **Coder (e.g., \`local_dev\`):** Receives precise coding tasks and executes them.`;
+**Your secondary duty is DOCUMENTATION INTEGRITY.** You must ensure the Coder updates .eck/ files whenever the project structure, roadmap, or debt changes.
 
-      commandFormats = `### COMMAND FORMATS
+  - **Architect (You):** Sets strategy, defines tasks, enforces manifest maintenance.
+  - **Coder (e.g., \`local_dev\`):** Receives precise coding tasks and executes them, including manifest updates.`;
 
-You MUST use the following JSON command format for Coders:
+      commandFormats = `### COMMAND FORMATS (Eck-Protocol v2)
 
-**For Coders (\`local_dev\`, \`production_server\`, \`android_wsl_dev\`, \`gemini_windows\`):**
-Use \`apply_code_changes\` for direct tasks where you provide all details.
+You MUST use the **Eck-Protocol v2** format for all code execution tasks. This format combines Markdown for analysis, XML tags for file operations, and JSON for routing metadata.
 
-\`\`\`json
-{
-  "target_agent": "local_dev",
-  "agent_environment": "Development environment with full GUI support and development tools",
-  "command_for_agent": "apply_code_changes",
-  "task_id": "unique-task-id",
-  "payload": {
-    "objective": "Brief, clear task description",
-    "context": "Why this change is needed - include relevant .eck manifest context",
-    "files_to_modify": [
-      {
-        "path": "exact/file/path.js",
-        "action": "specific action (add, modify, replace, delete)",
-        "location": "line numbers, function name, or search pattern",
-        "details": "precise description of the change"
-      }
-    ],
-    "new_files": [
-      {
-        "path": "path/to/new/file.js",
-        "content_type": "javascript/json/markdown/config",
-        "purpose": "why this file is needed"
-      }
-    ],
-    "dependencies": {
-      "install": ["package-name@version"],
-      "remove": ["old-package-name"]
-    },
-    "validation_steps": [
-      "npm run test",
-      "node index.js --help",
-      "specific command to verify functionality"
-    ],
-    "expected_outcome": "what should work after changes",
-    "post_execution_steps": {
-      "journal_entry": {
-        "type": "feat",
-        "scope": "authentication",
-        "summary": "Brief description of what was accomplished",
-        "details": "Detailed explanation of changes, impacts, and technical notes"
-      },
-      "mcp_feedback": {
-        "success": true,
-        "errors": [],
-        "mcp_version": "1.0"
-      }
-    }
-  }
-}
-\`\`\``;
+**CRITICAL DISPLAY RULE (THE 4-BACKTICK WRAPPER):**
+To ensure your command is copy-pasteable without breaking UI rendering, you **MUST** wrap the ENTIRE protocol output in a \`text\` block using **QUADRUPLE BACKTICKS** (\` \`\`\`\` \`).
+
+**Why?** Your command contains internal code blocks with 3 backticks. To escape them, the outer container needs 4.
+
+**Required Output Format:**
+
+\`\`\`\`text
+# Analysis
+[Your reasoning...]
+
+## Changes
+<file path="example.js" action="replace">
+\\\`\\\`\\\`javascript
+// Internal code block uses 3 backticks
+const x = 1;
+\\\`\\\`\\\`
+</file>
+
+## Metadata
+\\\`\\\`\\\`json
+{ ... }
+\\\`\\\`\\\`
+\`\`\`\`
+
+**File Actions:**
+- \`create\`: Create a new file (requires full content)
+- \`replace\`: Overwrite existing file (requires full content)
+- \`modify\`: Replace specific sections (provide context)
+- \`delete\`: Delete the file
+`;
     }
 
     // --- This is the main/Senior Architect prompt logic ---
     let template;
-    if (context.mode === 'vector') {
-      template = await loadTemplate(promptTemplates.vectorMode);
-      // Inject context for vector mode
-      template = template.replace('{{multiAgentSection}}', `
-${projectOverview}
-${eckManifestSection}
-`);
-    } else {
-      template = await loadTemplate(promptTemplates.multiAgent);
-      // --- INJECT DYNAMIC CONTEXT ---
-      template = template.replace('{{projectOverview}}', projectOverview);
-      template = template.replace('{{eckManifestSection}}', eckManifestSection);
-      // --- END INJECT ---
+    template = await loadTemplate(promptTemplates.multiAgent);
+    // --- INJECT DYNAMIC CONTEXT ---
+    template = template.replace('{{projectOverview}}', projectOverview);
+    template = template.replace('{{eckManifestSection}}', eckManifestSection);
+    // --- END INJECT ---
+
+    // Filter out gemini agents if not in JA mode
+    const filteredExecutionAgents = {};
+    for (const [key, agent] of Object.entries(executionAgents)) {
+      const isGeminiAgent = key.includes('gemini') || (agent.name && agent.name.toLowerCase().includes('gemini'));
+      if (isGeminiAgent) {
+        if (withJa && agent.active) filteredExecutionAgents[key] = agent;
+      } else {
+        if (agent.active) filteredExecutionAgents[key] = agent;
+      }
     }
 
-    const agentDefinitions = buildAgentDefinitions(executionAgents);
+    const agentDefinitions = buildAgentDefinitions(filteredExecutionAgents);
 
     const data = {
       ...context,
-      timestamp: new Date().toISOString(),
+      timestamp: new Date().toLocaleString(),
       architectPersona,
       agentDefinitions,
       hierarchicalWorkflow,

package/src/utils/eckProtocolParser.js

@@ -0,0 +1,221 @@
+/**
+ * Eck-Protocol v2 Parser
+ *
+ * Parses hybrid Markdown/XML/JSON format for agent communication.
+ * This is a pure text parser - no shell commands are involved.
+ *
+ * Format specification:
+ * - Markdown for human-readable analysis/thinking
+ * - XML-like <file> tags for code changes (with code in standard fences)
+ * - JSON in fenced blocks for structured metadata
+ */
+
+/**
+ * Parses Eck-Protocol v2 response from an agent.
+ * @param {string} text - Raw text response from the agent
+ * @returns {object} Parsed structure with thought, files, and metadata
+ */
+export function parseEckResponse(text) {
+  const result = {
+    thought: '',
+    files: [],
+    metadata: {},
+    raw: text
+  };
+
+  if (!text || typeof text !== 'string') {
+    return result;
+  }
+
+  result.files = extractFiles(text);
+  result.metadata = extractMetadata(text);
+  result.thought = extractThought(text);
+
+  return result;
+}
+
+/**
+ * Extracts file changes from <file> tags.
+ * @param {string} text - Raw text
+ * @returns {Array<{path: string, action: string, content: string}>}
+ */
+function extractFiles(text) {
+  const files = [];
+
+  // Pattern: <file path="..." action="..."> content </file>
+  const fileRegex = /<file\s+path=["']([^"']+)["']\s+action=["']([^"']+)["']>\s*([\s\S]*?)\s*<\/file>/gi;
+
+  let match;
+  while ((match = fileRegex.exec(text)) !== null) {
+    const path = match[1];
+    const action = match[2];
+    let content = match[3].trim();
+
+    // Strip markdown code fences if present
+    const fenceMatch = content.match(/^```[\w]*\s*\n?([\s\S]*?)\n?\s*```$/);
+    if (fenceMatch) {
+      content = fenceMatch[1];
+    }
+
+    content = content.replace(/\r\n/g, '\n');
+    files.push({ path, action, content });
+  }
+
+  return files;
+}
+
+/**
+ * Extracts metadata from JSON fenced blocks.
+ * @param {string} text - Raw text
+ * @returns {object} Parsed metadata object
+ */
+function extractMetadata(text) {
+  let metadata = {};
+
+  // Try: ## Metadata section with JSON block
+  const metadataSectionMatch = text.match(/##\s*Metadata\s*\n+```json\s*\n([\s\S]*?)\n```/i);
+  if (metadataSectionMatch) {
+    try {
+      metadata = JSON.parse(metadataSectionMatch[1].trim());
+      return metadata;
+    } catch (e) {
+      console.warn('Failed to parse Metadata JSON:', e.message);
+    }
+  }
+
+  // Try: <journal> tag with JSON
+  const journalMatch = text.match(/<journal>\s*```json\s*\n?([\s\S]*?)\n?\s*```\s*<\/journal>/i);
+  if (journalMatch) {
+    try {
+      metadata.journal = JSON.parse(journalMatch[1].trim());
+      return metadata;
+    } catch (e) {
+      console.warn('Failed to parse journal JSON:', e.message);
+    }
+  }
+
+  // Try: simple <journal type="..." scope="...">summary</journal>
+  const simpleJournalMatch = text.match(/<journal\s+type=["']([^"']+)["']\s+scope=["']([^"']+)["']>([^<]+)<\/journal>/i);
+  if (simpleJournalMatch) {
+    metadata.journal = {
+      type: simpleJournalMatch[1],
+      scope: simpleJournalMatch[2],
+      summary: simpleJournalMatch[3].trim()
+    };
+  }
+
+  return metadata;
+}
+
+/**
+ * Extracts the thought/analysis section.
+ * @param {string} text - Raw text
+ * @returns {string} The thought/analysis content
+ */
+function extractThought(text) {
+  const changesIndex = text.search(/##\s*Changes/i);
+  const fileIndex = text.search(/<file\s+path=/i);
+
+  let endIndex = text.length;
+  if (changesIndex !== -1 && fileIndex !== -1) {
+    endIndex = Math.min(changesIndex, fileIndex);
+  } else if (changesIndex !== -1) {
+    endIndex = changesIndex;
+  } else if (fileIndex !== -1) {
+    endIndex = fileIndex;
+  }
+
+  let thought = text.substring(0, endIndex).trim();
+  thought = thought.replace(/^#\s*(Analysis|Thinking|Plan)\s*\n*/i, '').trim();
+  return thought;
+}
+
+/**
+ * Validates if a response contains valid Eck-Protocol v2 structure.
+ * @param {string} text - Raw text to validate
+ * @returns {{valid: boolean, hasFiles: boolean, hasMetadata: boolean, errors: string[]}}
+ */
+export function validateEckResponse(text) {
+  const result = {
+    valid: true,
+    hasFiles: false,
+    hasMetadata: false,
+    errors: []
+  };
+
+  if (!text || typeof text !== 'string') {
+    result.valid = false;
+    result.errors.push('Response is empty or not a string');
+    return result;
+  }
+
+  const hasFileTags = /<file\s+path=/.test(text);
+  if (hasFileTags) {
+    result.hasFiles = true;
+    const openTags = (text.match(/<file\s+/g) || []).length;
+    const closeTags = (text.match(/<\/file>/g) || []).length;
+    if (openTags !== closeTags) {
+      result.valid = false;
+      result.errors.push(`Mismatched file tags: ${openTags} opening, ${closeTags} closing`);
+    }
+  }
+
+  const hasMetadata = /##\s*Metadata|<journal/i.test(text);
+  if (hasMetadata) {
+    result.hasMetadata = true;
+  }
+
+  return result;
+}
+
+/**
+ * Parses response with fallback to legacy JSON format.
+ * @param {string} text - Raw response text
+ * @returns {object} Parsed result with format indicator
+ */
+export function parseWithFallback(text) {
+  const validation = validateEckResponse(text);
+
+  if (validation.hasFiles || validation.hasMetadata) {
+    const parsed = parseEckResponse(text);
+    return { format: 'eck-v2', ...parsed };
+  }
+
+  // Fallback: try to parse as JSON
+  try {
+    const jsonMatch = text.match(/```json\s*\n([\s\S]*?)\n```/);
+    if (jsonMatch) {
+      const jsonData = JSON.parse(jsonMatch[1]);
+      return {
+        format: 'legacy-json',
+        thought: text.split('```json')[0].trim(),
+        data: jsonData,
+        files: [],
+        metadata: {}
+      };
+    }
+
+    const jsonData = JSON.parse(text.trim());
+    return {
+      format: 'pure-json',
+      thought: '',
+      data: jsonData,
+      files: [],
+      metadata: {}
+    };
+  } catch (e) {
+    return {
+      format: 'plain-text',
+      thought: text,
+      files: [],
+      metadata: {},
+      raw: text
+    };
+  }
+}
+
+export default {
+  parseEckResponse,
+  validateEckResponse,
+  parseWithFallback
+};