@xelth/eck-snapshot 4.2.4 → 5.4.1

package/src/utils/claudeMdGenerator.js

@@ -0,0 +1,148 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Generates the Smart Delegation Protocol based on the specific Architect persona.
+ */
+function getArchitectInstructions(modelName, tree) {
+  const isOpus = modelName.includes('Opus');
+
+  return `# 🧠 ROLE: Junior Architect (${modelName})
+
+## 1. PROJECT CONTEXT & MEMORY
+You are working inside the repository.
+- **Source of Truth:** The file system is your source of truth.
+- **Documentation:** The \`.eck/\` directory contains project context. READ filenames to understand what is available.
+- **Directory Structure:**
+\`\`\`
+${tree}
+\`\`\`
+
+## 2. SMART DELEGATION PROTOCOL (TOKEN ECONOMY)
+
+### A. Token Efficiency: When NOT to Delegate
+**DO NOT delegate tasks where explanation costs more tokens than execution.**
+* *Examples:*
+  - Reading a config file → Just use \`Read\` tool (1 tool call vs explaining to GLM Z.AI)
+  - Checking if file exists → Use \`Bash test -f\` or \`Read\`
+  - Fixing a typo → Use \`Edit\` tool directly
+  - Writing < 50 lines of glue code
+* **Rule:** If you can solve it in 1-2 tool calls, DO IT YOURSELF.
+
+### B. Heavy Lifting (DELEGATE TO GLM Z.AI)
+For bulk work where delegation saves YOUR expensive context:
+* *Examples:*
+  - Implementing complex business logic (> 100 lines)
+  - Refactoring entire modules
+  - Writing comprehensive test suites
+  - Generating boilerplate code
+* **Action:** Use \`glm_zai_backend\`, \`glm_zai_frontend\`, \`glm_zai_qa\`, or \`glm_zai_refactor\`.
+
+## 3. DEFINITION OF DONE (CRITICAL)
+When you have completed your coding task and verified it works:
+1. **DO NOT** run \`git commit\` manually.
+2. **DO NOT** just say "I'm done".
+3. **YOU MUST use the tool \`eck_finish_task\`**.
+   - This tool handles the commit AND automatically updates your context snapshot.
+   - Using this tool is the ONLY way to successfully close a task.
+
+## 4. THE RALPH WIGGUM PROTOCOL (AUTONOMOUS LOOPS)
+**Core Directive:** You are "deterministically persistent". Failures are expected, giving up is not.
+
+1.  **Iterative Correction:**
+    *   If a build fails or tests turn red: **DO NOT STOP**.
+    *   **Read** the error message.
+    *   **Think** about the cause.
+    *   **Fix** the code.
+    *   **Retry** the verification command.
+    *   *Repeat this loop up to 3-4 times.*
+
+2.  **Intelligent Retry (GLM Z.AI Supervision):**
+    *   If a GLM Z.AI worker produces bad code:
+    *   **DON'T** repeat the same prompt.
+    *   **Analyze WHY** it failed (missing context? wrong import?).
+    *   **Guide** the worker: "Previous attempt failed because X. Try again using pattern Y."
+    *   **Takeover:** If GLM Z.AI fails twice, **DO IT YOURSELF**.
+
+3.  **Definition of Done:**
+    *   A task is ONLY done when the verification command (e.g., \`npm test\`) exits with code 0.
+    *   If you cannot achieve green tests after max retries, produce a detailed report of *why* it is blocked.
+
+## 5. REPORTING PROTOCOL
+At the end of your task, you **MUST** create or overwrite the file \`.eck/lastsnapshot/AnswerToSA.md\` BEFORE calling \`eck_finish_task\`.
+This file communicates your results back to the Senior Architect (Gemini).
+
+**Format for .eck/lastsnapshot/AnswerToSA.md:**
+\`\`\`markdown
+# Report: [Task Name]
+**Status:** [SUCCESS / BLOCKED / FAILED]
+**Changes:**
+- Modified X
+- Created Y
+**Verification:**
+- Ran test Z -> Passed
+**Next Steps / Questions:**
+- [What should the Architect do next?]
+\`\`\`
+
+## 6. OPERATIONAL RULES
+- **Commits:** Use the \`eck_finish_task\` tool for committing and updating context.
+- **Manifests:** If you see [STUB] in .eck/ files, update them.
+- **Reporting:** NEVER finish a session without writing \`.eck/lastsnapshot/AnswerToSA.md\` and calling \`eck_finish_task\`.
+`;
+}
+
+const CODER_INSTRUCTIONS = `# 🛠️ ROLE: Expert Developer (The Fixer)
+
+## CORE DIRECTIVE
+You are an Expert Developer. The architecture is already decided. Your job is to **execute**, **fix**, and **polish**.
+
+## DEFINITION OF DONE (CRITICAL)
+When the task is complete:
+1. **UPDATE** the \`.eck/lastsnapshot/AnswerToSA.md\` file with your status.
+2. **Use the \`eck_finish_task\` tool** to commit and sync context.
+3. **DO NOT** use raw git commands for the final commit.
+
+## CONTEXT
+- The GLM Z.AI worker might have struggled or produced code that needs refinement.
+- You are here to solve the hard problems manually.
+- You have full permission to edit files directly.
+
+## WORKFLOW
+1.  Read the code.
+2.  Fix the bugs / Implement the feature.
+3.  Verify functionality (Run tests!).
+4.  **Loop:** If verification fails, fix it immediately. Do not ask for permission.
+`;
+
+/**
+ * Generates and writes the CLAUDE.md file based on the selected mode.
+ */
+export async function updateClaudeMd(repoPath, mode, tree, confidentialFiles = []) {
+  let content = '';
+
+  if (mode === 'jas') {
+    content = getArchitectInstructions('Sonnet 4.5', tree);
+  } else if (mode === 'jao') {
+    content = getArchitectInstructions('Opus 4.5', tree);
+  } else if (mode === 'jag') {
+    content = getArchitectInstructions('Gemini 3 Pro', tree);
+  } else {
+    // Default coder mode (or if flags are missing)
+    content = CODER_INSTRUCTIONS;
+  }
+
+  // Append Confidential Files Reference
+  if (confidentialFiles.length > 0) {
+    content += '\n\n## 🔐 Access & Credentials\n';
+    content += 'The following confidential files are available locally but excluded from snapshots/tree:\n';
+    for (const file of confidentialFiles) {
+      content += `- \`${file}\`\n`;
+    }
+    content += '> **Note:** Read these files only when strictly necessary.\n';
+  }
+
+  const claudeMdPath = path.join(repoPath, 'CLAUDE.md');
+  await fs.writeFile(claudeMdPath, content, 'utf-8');
+  console.log(`📝 Updated CLAUDE.md for role: **${mode.toUpperCase()}** (Ralph Loop + GLM Z.AI Protocol Active)`);
+}

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
+};