@xelth/eck-snapshot 4.1.0 → 4.2.0

package/src/core/skeletonizer.js

@@ -10,22 +10,41 @@ let Python = null;
 let Java = null;
 let Kotlin = null;
 let C = null;
+let Rust = null;
+let Go = null;
 
 async function loadTreeSitter() {
-    if (!Parser) {
-        try {
-            const treeSitterModule = await import('tree-sitter');
-            Parser = treeSitterModule.default;
-            Python = (await import('tree-sitter-python')).default;
-            Java = (await import('tree-sitter-java')).default;
-            Kotlin = (await import('tree-sitter-kotlin')).default;
-            C = (await import('tree-sitter-c')).default;
-        } catch (error) {
-            console.warn('Tree-sitter not available:', error.message);
-            return false;
-        }
+    if (Parser) return true; // Already loaded
+
+    try {
+        // We use dynamic imports and check for basic sanity to handle broken native builds (common on Windows)
+        const treeSitterModule = await import('tree-sitter').catch(() => null);
+        if (!treeSitterModule || !treeSitterModule.default) return false;
+
+        Parser = treeSitterModule.default;
+
+        // Load language packs with Promise.allSettled to handle individual failures
+        const langs = await Promise.allSettled([
+            import('tree-sitter-python'),
+            import('tree-sitter-java'),
+            import('tree-sitter-kotlin'),
+            import('tree-sitter-c'),
+            import('tree-sitter-rust'),
+            import('tree-sitter-go')
+        ]);
+
+        Python = langs[0].status === 'fulfilled' ? langs[0].value.default : null;
+        Java = langs[1].status === 'fulfilled' ? langs[1].value.default : null;
+        Kotlin = langs[2].status === 'fulfilled' ? langs[2].value.default : null;
+        C = langs[3].status === 'fulfilled' ? langs[3].value.default : null;
+        Rust = langs[4].status === 'fulfilled' ? langs[4].value.default : null;
+        Go = langs[5].status === 'fulfilled' ? langs[5].value.default : null;
+
+        return true;
+    } catch (error) {
+        // Silently fail, skeletonize will fallback to original content
+        return false;
     }
-    return true;
 }
 
 // Initialize parsers map (will be populated lazily)
@@ -35,8 +54,10 @@ const languages = {
     '.kt': () => Kotlin,
     '.c': () => C,
     '.h': () => C,
-    '.cpp': () => C, // C parser often handles C++ basics well enough for skeletons
-    '.hpp': () => C
+    '.cpp': () => C,
+    '.hpp': () => C,
+    '.rs': () => Rust,
+    '.go': () => Go
 };
 
 /**
@@ -53,15 +74,18 @@ export async function skeletonize(content, filePath) {
         return skeletonizeJs(content);
     }
 
-    // 2. Tree-sitter Strategy (Python, Java, Kotlin, C)
+    // 2. Tree-sitter Strategy (Python, Java, Kotlin, C, Rust, Go)
     const ext = filePath.substring(filePath.lastIndexOf('.'));
     if (languages[ext]) {
         // Lazy-load tree-sitter
         const available = await loadTreeSitter();
-        if (!available) {
-            return content; // Fallback: return original content if tree-sitter unavailable
+        const langModule = languages[ext]();
+
+        // Only attempt tree-sitter if both the parser and the specific language module are ready
+        if (available && Parser && langModule) {
+            return skeletonizeTreeSitter(content, langModule, ext);
         }
-        return skeletonizeTreeSitter(content, languages[ext]());
+        return content; // Fallback: return original content if tree-sitter unavailable
     }
 
     // 3. Fallback (Return as is)
@@ -79,15 +103,22 @@ function skeletonizeJs(content) {
         traverse(ast, {
             Function(path) {
                 if (path.node.body && path.node.body.type === 'BlockStatement') {
+                    // Preserve leading comments (JSDoc) before emptying body
+                    const leadingComments = path.node.leadingComments || [];
                     path.node.body.body = [];
-                    // Minimal comment to save tokens
-                    path.node.body.innerComments = [{ type: 'CommentBlock', value: ' ... ' }];
+                    path.node.body.innerComments = leadingComments.length > 0
+                        ? leadingComments
+                        : [{ type: 'CommentBlock', value: ' ... ' }];
                 }
             },
             ClassMethod(path) {
                 if (path.node.body && path.node.body.type === 'BlockStatement') {
+                    // Preserve leading comments (JSDoc) before emptying body
+                    const leadingComments = path.node.leadingComments || [];
                     path.node.body.body = [];
-                    path.node.body.innerComments = [{ type: 'CommentBlock', value: ' ... ' }];
+                    path.node.body.innerComments = leadingComments.length > 0
+                        ? leadingComments
+                        : [{ type: 'CommentBlock', value: ' ... ' }];
                 }
             }
         });
@@ -99,28 +130,38 @@ function skeletonizeJs(content) {
     }
 }
 
-function skeletonizeTreeSitter(content, language) {
+function skeletonizeTreeSitter(content, language, ext) {
     try {
         const parser = new Parser();
         parser.setLanguage(language);
         const tree = parser.parse(content);
 
-        // Define node types that represent function bodies for different languages
+        // Define node types that represent function bodies
         const bodyTypes = ['block', 'function_body', 'compound_statement'];
-
         const replacements = [];
 
         const visit = (node) => {
-            // Check for function definitions
-            const isFunction = [
-                'function_definition', // Python, C
-                'method_declaration',  // Java
-                'function_declaration', // Kotlin
-                'class_declaration',   // Kotlin/Java/Python (to clean init blocks if needed, but risky)
-            ].includes(node.type);
+            const type = node.type;
+            let isFunction = false;
+            let replacementText = '{ /* ... */ }';
+
+            // Language specific detection
+            if (ext === '.rs') {
+                isFunction = ['function_item', 'method_declaration'].includes(type);
+            } else if (ext === '.go') {
+                isFunction = ['function_declaration', 'method_declaration'].includes(type);
+            } else if (ext === '.py') {
+                isFunction = type === 'function_definition';
+                replacementText = '...';
+            } else {
+                isFunction = [
+                    'function_definition',
+                    'method_declaration',
+                    'function_declaration'
+                ].includes(type);
+            }
 
             if (isFunction) {
-                // Find the body node
                 let bodyNode = null;
                 for (let i = 0; i < node.childCount; i++) {
                     const child = node.child(i);
@@ -131,23 +172,10 @@ function skeletonizeTreeSitter(content, language) {
                 }
 
                 if (bodyNode) {
-                    const start = bodyNode.startIndex;
-                    const end = bodyNode.endIndex;
-                    // Use minimal replacement to save tokens
-                    replacements.push({ start, end, text: '{ /* ... */ }' });
-                    return; // Don't traverse inside the body we just stripped
-                }
-            }
-
-            // Python uses colons and indentation, distinct from {} blocks
-            // Use Python's Ellipsis literal for maximum brevity
-            if (node.type === 'function_definition' && language === Python) {
-                const body = node.lastChild;
-                if (body && body.type === 'block') {
                     replacements.push({
-                        start: body.startIndex,
-                        end: body.endIndex,
-                        text: '...'  // Python Ellipsis literal - minimal tokens
+                        start: bodyNode.startIndex,
+                        end: bodyNode.endIndex,
+                        text: replacementText
                     });
                     return;
                 }
@@ -159,8 +187,6 @@ function skeletonizeTreeSitter(content, language) {
         };
 
         visit(tree.rootNode);
-
-        // Sort replacements reversed to apply without messing up indices
         replacements.sort((a, b) => b.start - a.start);
 
         let currentContent = content;
@@ -169,7 +195,6 @@ function skeletonizeTreeSitter(content, language) {
         }
 
         return currentContent;
-
     } catch (e) {
         return content + `\n// [Skeleton error: ${e.message}]`;
     }

package/src/services/claudeCliService.js

@@ -1,6 +1,7 @@
 import { execa } from 'execa';
 import { spawn } from 'child_process';
 import pRetry from 'p-retry';
+import { parseWithFallback } from '../utils/eckProtocolParser.js';
 
 /**
  * Executes a prompt using the claude-code CLI in non-interactive print mode.
@@ -145,8 +146,12 @@ async function attemptClaudeExecution(prompt, sessionId = null, options = {}) {
       throw new Error('No result JSON found in claude-code output.');
     }
 
+    // Parse the result using Eck-Protocol v2 parser
+    const parsed = parseWithFallback(resultJson.result || '');
+
     return {
       result: resultJson.result,
+      parsed: parsed,  // Structured data from Eck-Protocol v2
       cost: resultJson.total_cost_usd,
       usage: resultJson.usage,
       duration_ms: resultJson.duration_ms

package/src/templates/agent-prompt.template.md

@@ -12,18 +12,115 @@ You are the **Junior Architect** agent (`gemini_wsl`). Your primary goal is to e
 - **You (Junior Architect / `gemini_wsl`)** analyze the task, break it down, and use your tools.
 - The **Coder (`claude`)** is your primary tool for *writing code*.
 
-## CRITICAL WORKFLOW: Using the Coder (`/claude`)
+## CRITICAL WORKFLOW: Eck-Protocol v2 (Hybrid Format)
 
-The `claude` agent (who you command via `/claude`) is a **specialized Coder**. It is highly trained for code generation.
+When you need to write or modify code, you **MUST** use the `/claude` command with the **Eck-Protocol v2** format. This format uses Markdown for readability, XML tags for file boundaries, and JSON for metadata.
 
-When you need to write or modify code, you **MUST** use the `/claude` command and provide it with a **JSON payload** (as a single-line JSON string) in the `apply_code_changes` format.
+### Response Format
 
-**DO NOT** ask `claude` to "write a function" in natural language. You *must* command it with this precise JSON structure:
+**CRITICAL DISPLAY RULE:**
+You MUST wrap your ENTIRE response in a `text` block using **QUADRUPLE BACKTICKS** (` ```` `). This prevents internal code blocks from breaking the container.
 
-**IMPORTANT:** The JSON payload must be passed as a **single-line string wrapped in SINGLE QUOTES (`'`)**. This is the simplest and safest way to pass the complete JSON (which uses double quotes) through the shell without it breaking.
+````text
+# Analysis
 
+[Your thinking and analysis of the task goes here.
+Explain what you're going to do and why.]
+
+## Changes
+
+<file path="src/path/to/file.js" action="replace">
+```javascript
+// Your code here - no escaping needed!
+async function example() {
+    console.log("Clean code with quotes!");
+    return { success: true };
+}
 ```
-/claude '{"target_agent":"local_dev","command_for_agent":"apply_code_changes","task_id":"ja-subtask-123","payload":{"objective":"Write the `doSomething` function","context":"This function is for the `UserService`...","files_to_modify":[{"path":"src/services/UserService.js","action":"add","location":"After the `getUser` function","details":"...new function code..."}],"new_files":[],"validation_steps":[]},"post_execution_steps":{"journal_entry":{"type":"feat","scope":"api","summary":"Implement `doSomething` function","details":"Delegated from JA"}}}'
+</file>
+
+<file path="src/another/file.js" action="create">
+```javascript
+export const helper = () => true;
 ```
+</file>
+
+## Metadata
+
+```json
+{
+  "journal": {
+    "type": "feat",
+    "scope": "api",
+    "summary": "Add example function"
+  }
+}
+```
+````
+
+### File Actions
+
+| Action | Description |
+|--------|-------------|
+| `create` | Create a new file |
+| `replace` | Replace entire file content |
+| `modify` | Partial modification (include context) |
+| `delete` | Delete the file (no content needed) |
+
+### Example Command
+
+```
+/claude
+````text
+# Analysis
+
+I need to fix the null check in auth.js and add a helper function.
+
+## Changes
+
+<file path="src/auth.js" action="replace">
+```javascript
+async function login(user) {
+    if (!user) throw new Error("No user provided");
+    return await db.authenticate(user);
+}
+```
+</file>
+
+<file path="src/utils/validate.js" action="create">
+```javascript
+export const validateUser = (user) => {
+    return user && typeof user.id === 'string';
+};
+```
+</file>
+
+## Metadata
+
+```json
+{
+  "journal": {
+    "type": "fix",
+    "scope": "auth",
+    "summary": "Add null check and validation helper"
+  }
+}
+```
+````
+```
+
+### Why This Format?
+
+1. **No escaping hell** - Code is written in standard markdown fences, no `\"` or `\n`
+2. **Readable** - Both humans and AI can easily read and write this format
+3. **Parseable** - XML tags provide clear boundaries for automated processing
+4. **Flexible** - Markdown sections allow for thinking and context
+
+### Important Rules
+
+- Always wrap code in markdown fences (` ``` `) inside `<file>` tags
+- Always include the `path` and `action` attributes on `<file>` tags
+- Use the `## Metadata` section for journal entries and other structured data
+- The `# Analysis` section is optional but recommended for complex tasks
 
-Your other tools (like `bash`) can be used for analysis and validation.
+Your other tools (like `bash`) can be used for analysis and validation.

package/src/templates/architect-prompt.template.md

@@ -7,44 +7,133 @@ You are an autonomous AI Architect. Your primary goal is to develop and evolve a
 Your entire operational process follows a strict loop:
 1.  **Thought:** Analyze the user's request, the current state of the project, and previous observations. Formulate a plan and decide on the next immediate action. You must explain your reasoning and your chosen action in plain text.
 2.  **Tool:** Immediately after your thought process, you MUST issue a command to either the local `eck-snapshot` environment or the `claude_code_agent`.
-3.  **Observation:** After issuing a command, you MUST STOP and wait for an `Observation:` message from the system, which will contain the result of your command. Do not proceed until you receive it.
+3.  **Observation:** After issuing a command, you MUST STOP and wait for an `Observation:` message from the system, which will contain the result of your command.
 
-## Commanding the Execution Agent (Claude)
+## Commanding the Execution Agent: Eck-Protocol v2
 
-To delegate any coding task (writing, editing, testing, refactoring), you MUST generate a JSON command block for the `claude_code_agent`. This is your primary method of modifying the codebase.
+To delegate any coding task (writing, editing, testing, refactoring), you MUST generate a command using the **Eck-Protocol v2** format. This hybrid Markdown/XML format eliminates JSON escaping issues and is both human-readable and machine-parseable.
+
+**CRITICAL DISPLAY RULE:**
+You MUST wrap your ENTIRE response (Analysis + Changes + Metadata) in a single `text` code block using **QUADRUPLE BACKTICKS** (` ```` `). This prevents internal code blocks from breaking the container.
+
+### Command Format (Wrapped)
+
+````text
+# Analysis
+
+[Explain your reasoning: what you're doing and why.
+This helps the Coder understand context.]
+
+## Changes
+
+<file path="exact/path/to/file.js" action="replace">
+```javascript
+// Code is written naturally inside markdown fences
+// No escaping of quotes or newlines needed!
+async function example() {
+    console.log("This just works!");
+    return { success: true };
+}
+```
+</file>
+
+## Metadata
 
-**JSON Command Format:**
 ```json
 {
-  "target_agent": "claude_code_agent",
-  "command_for_agent": "apply_code_changes",
-  "payload": {
-    "objective": "A brief, clear task description for Claude.",
-    "context": "Explain why this change is needed and any relevant architectural context.",
-    "files_to_modify": [
-      {
-        "path": "exact/path/to/file.js",
-        "action": "add | modify | replace | delete",
-        "location": "line numbers, function name, or a unique search pattern",
-        "details": "Precise, step-by-step instructions for Claude to implement."
-      }
-    ]
+  "journal": {
+    "type": "feat",
+    "scope": "api",
+    "summary": "Brief description of the change"
   }
 }
 ```
+````
+
+### File Actions Reference
+
+| Action | Use Case | Content Required |
+|--------|----------|------------------|
+| `create` | New file | Yes - full file content |
+| `replace` | Overwrite entire file | Yes - full file content |
+| `modify` | Change part of file | Yes - include surrounding context |
+| `delete` | Remove file | No |
+
+### Complete Example
+
+````text
+# Analysis
+
+The authentication module needs a null check to prevent crashes when
+no user object is provided. I'll also add a validation helper.
+
+## Changes
+
+<file path="src/auth/login.js" action="replace">
+```javascript
+import { validateUser } from '../utils/validate.js';
+
+export async function login(user) {
+    if (!validateUser(user)) {
+        throw new Error("Invalid user object");
+    }
+
+    const session = await db.authenticate(user);
+    return {
+        token: session.token,
+        expiresAt: session.expiresAt
+    };
+}
+```
+</file>
+
+<file path="src/utils/validate.js" action="create">
+```javascript
+export function validateUser(user) {
+    return user &&
+           typeof user.email === 'string' &&
+           typeof user.password === 'string';
+}
+```
+</file>
+
+<file path="src/legacy/oldAuth.js" action="delete">
+</file>
+
+## Metadata
+
+```json
+{
+  "journal": {
+    "type": "fix",
+    "scope": "auth",
+    "summary": "Add user validation to prevent null crashes"
+  }
+}
+```
+````
+
+### Why Eck-Protocol v2?
+
+| Problem with JSON | Solution in v2 |
+|-------------------|----------------|
+| `"code": "console.log(\"hello\")"` - escaping hell | Code in markdown fences - no escaping |
+| Single-line strings break on newlines | Multi-line content is natural |
+| Hard to read for humans | Markdown sections are readable |
+| Fragile parsing | XML tags provide clear boundaries |
 
 ## Interacting with the Local Environment
 
-To understand the project state, you can command the `eck-snapshot` tool directly. Use this for discovery, analysis, and managing project context.
+To understand the project state, you can command the `eck-snapshot` tool directly:
 
 **Tool Command Format:** `[tool_code: eck-snapshot <command> <options>]`
 
 **Available Commands:**
-- `eck-snapshot snapshot`: To create a new snapshot of the current state.
-- `eck-snapshot query "<question>"`: To search the codebase.
-- `eck-snapshot detect`: To analyze the project structure.
-- `eck-snapshot restore <snapshot_file> --include ...`: To view specific files from a snapshot.
+- `eck-snapshot snapshot`: Create a new snapshot of the current state
+- `eck-snapshot query "<question>"`: Search the codebase
+- `eck-snapshot detect`: Analyze the project structure
+- `eck-snapshot restore <snapshot_file> --include ...`: View specific files
 
 ## Final Mandate
 
-Your existence is defined by this loop. Think, act by issuing a tool command, and then wait for the observation. This is the only way you can make progress.
+Your existence is defined by this loop. Think, act by issuing a command using Eck-Protocol v2, and then wait for the observation. This is the only way you can make progress.

package/src/templates/multiAgent.md

@@ -21,6 +21,15 @@ You are the Project Manager and Solution Architect AI. Your primary goal is to t
 
 {{eckManifestSection}}
 
+### 🛠 MANIFEST MAINTENANCE PROTOCOL (CRITICAL)
+
+The `.eck/` directory files are your "Source of Knowledge".
+1. **Stub Detection:** If a file starts with `# [STUB: ...]`, it means the system failed to auto-generate meaningful content.
+2. **Architect's Duty:** You **MUST NOT** ignore stubs. Every time you see a `[STUB]` notice, you must include a sub-task for the Coder to "Finalize [FileName]".
+3. **Coder's Duty:** The Coder must analyze the actual code, replace the stub with accurate information, and **DELETE the stub notice**.
+
+**Documentation is part of the "Definition of Done". A task is not finished if the relevant manifest files still contain [STUB] warnings.**
+
 ### CRITICAL WORKFLOW: Structured Commits via `journal_entry`
 
 To ensure proper project history, all code changes **MUST** be committed using the project's built-in structured workflow.