@xelth/eck-snapshot 4.0.0 → 4.2.0

package/src/cli/commands/doctor.js

@@ -0,0 +1,60 @@
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+
+/**
+ * Scans .eck directory for files containing [STUB] markers
+ */
+export async function runDoctor(repoPath = process.cwd()) {
+  const eckDir = path.join(repoPath, '.eck');
+  console.log(chalk.blue('🏥 Checking project health and manifest integrity...'));
+
+  try {
+    await fs.access(eckDir);
+  } catch {
+    console.log(chalk.yellow('⚠️  .eck directory not found. Nothing to check.'));
+    return;
+  }
+
+  const stubFiles = [];
+  const scannedFiles = [];
+
+  async function scan(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await scan(fullPath);
+      } else if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.json'))) {
+        scannedFiles.push(fullPath);
+        const content = await fs.readFile(fullPath, 'utf-8');
+        if (content.includes('[STUB:')) {
+          stubFiles.push({
+            path: path.relative(repoPath, fullPath),
+            type: 'STUB'
+          });
+        }
+      }
+    }
+  }
+
+  await scan(eckDir);
+
+  if (stubFiles.length === 0) {
+    console.log(chalk.green(`\n✅ All clear! Found ${scannedFiles.length} manifest files and no stubs.`));
+  } else {
+    console.log(chalk.red(`\n❌ Found ${stubFiles.length} files that need attention:`));
+    stubFiles.forEach(file => {
+      console.log(chalk.yellow(`   - ${file.path} `) + chalk.gray('(contains [STUB] marker)'));
+    });
+    console.log(chalk.cyan('\n💡 Tip: Instruct your Coder agent to "Finalize these stubs by analyzing the code".'));
+  }
+
+  // Cross-platform tree-sitter check
+  try {
+    const ts = await import('tree-sitter');
+    console.log(chalk.green('✅ tree-sitter: Installed and loadable.'));
+  } catch (e) {
+    console.log(chalk.yellow('ℹ️  tree-sitter: Not available (Skeleton mode will be limited for non-JS files).'));
+  }
+}

package/src/cli/commands/setupGemini.js

@@ -134,7 +134,7 @@ args = ["${indexJsPath}", "ask-claude"]
 # gemini-cli claude "Generate a project overview"
 
 [claude.metadata]
-version = "4.0.0"
+version = "4.1.0"
 author = "eck-snapshot"
 generated_at = "${new Date().toISOString()}"
 platform = "${process.platform}"

package/src/cli/commands/setupGemini.test.js

@@ -39,7 +39,7 @@ command = "node"
 args = ["${indexJsPath}", "ask-claude"]
 
 [claude.metadata]
-version = "4.0.0"
+version = "4.1.0"
 author = "eck-snapshot"
 platform = "${process.platform}"
 working_directory = "${indexJsPath.replace('/index.js', '')}"`;

package/src/cli/commands/showFile.js

@@ -0,0 +1,39 @@
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+
+/**
+ * Show the full content of specific files
+ * Used for AI lazy loading when skeleton mode is active
+ * @param {string[]} filePaths - Array of paths to the files to display
+ */
+export async function showFile(filePaths) {
+    // Ensure input is array (commander passes array for variadic args)
+    const files = Array.isArray(filePaths) ? filePaths : [filePaths];
+
+    if (files.length === 0) {
+        console.error(chalk.yellow('No files specified. Usage: eck-snapshot show <file1> [file2] ...'));
+        return;
+    }
+
+    for (const filePath of files) {
+        try {
+            const fullPath = path.resolve(process.cwd(), filePath);
+            const content = await fs.readFile(fullPath, 'utf-8');
+
+            console.log(chalk.green(`\n--- FULL CONTENT: ${filePath} ---\n`));
+
+            // Detect file extension for syntax highlighting hint
+            const ext = path.extname(filePath).slice(1);
+            console.log('```' + ext);
+            console.log(content);
+            console.log('```');
+
+            console.log(chalk.green(`\n--- END OF FILE: ${filePath} ---\n`));
+
+        } catch (error) {
+            console.error(chalk.red(`Failed to read file ${filePath}: ${error.message}`));
+            // Continue to next file even if one fails
+        }
+    }
+}

package/src/cli/commands/updateSnapshot.js

@@ -0,0 +1,75 @@
+import fs from 'fs/promises';
+import path from 'path';
+import ora from 'ora';
+import { getGitAnchor, getChangedFiles, getGitDiffOutput } from '../../utils/gitUtils.js';
+import { loadSetupConfig } from '../../config.js';
+import { readFileWithSizeCheck, parseSize, formatSize, matchesPattern, loadGitignore, generateTimestamp } from '../../utils/fileUtils.js';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export async function updateSnapshot(repoPath, options) {
+  const spinner = ora('Generating update snapshot...').start();
+  try {
+    const anchor = await getGitAnchor(repoPath);
+    if (!anchor) {
+      throw new Error('No snapshot anchor found. Run a full snapshot first: eck-snapshot snapshot');
+    }
+
+    const changedFiles = await getChangedFiles(repoPath, anchor);
+    if (changedFiles.length === 0) {
+      spinner.succeed('No changes detected since last full snapshot.');
+      return;
+    }
+
+    // Load configs for filtering logic
+    const setupConfig = await loadSetupConfig();
+    const config = { ...setupConfig.fileFiltering, ...setupConfig.performance, ...options };
+    const gitignore = await loadGitignore(repoPath);
+
+    let contentOutput = '';
+    let includedCount = 0;
+    const fileList = [];
+
+    for (const filePath of changedFiles) {
+      // Basic filtering (reuse logic roughly)
+      if (config.dirsToIgnore.some(d => filePath.startsWith(d))) continue;
+      if (gitignore.ignores(filePath)) continue;
+
+      try {
+        const fullPath = path.join(repoPath, filePath);
+        const content = await readFileWithSizeCheck(fullPath, parseSize(config.maxFileSize));
+
+        contentOutput += `--- File: /${filePath} ---\n\n${content}\n\n`;
+        fileList.push(`- ${filePath}`);
+        includedCount++;
+      } catch (e) {
+        // Skip deleted files or read errors
+      }
+    }
+
+    // Load Template
+    const templatePath = path.join(__dirname, '../../templates/update-prompt.template.md');
+    let header = await fs.readFile(templatePath, 'utf-8');
+    header = header.replace('{{anchor}}', anchor.substring(0, 7))
+      .replace('{{timestamp}}', new Date().toLocaleString())
+      .replace('{{fileList}}', fileList.join('\n'));
+
+    // Add Git Diff at the end for context
+    const diffOutput = await getGitDiffOutput(repoPath, anchor);
+    const diffSection = `\n--- GIT DIFF (For Context) ---\n\n\`\`\`diff\n${diffOutput}\n\`\`\``;
+
+    const outputFilename = `update_${generateTimestamp()}.md`;
+    const outputPath = path.join(repoPath, '.eck', 'snapshots', outputFilename);
+
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, header + contentOutput + diffSection);
+
+    spinner.succeed(`Update snapshot created: .eck/snapshots/${outputFilename}`);
+    console.log(`📦 Included ${includedCount} changed files.`);
+
+  } catch (error) {
+    spinner.fail(`Update failed: ${error.message}`);
+  }
+}

package/src/config.js

@@ -16,6 +16,10 @@ export async function loadSetupConfig() {
     const setupPath = path.join(__dirname, '..', 'setup.json');
     const setupContent = await fs.readFile(setupPath, 'utf-8');
     cachedConfig = JSON.parse(setupContent);
+
+    // Basic schema validation for critical fields
+    validateConfigSchema(cachedConfig);
+
     return cachedConfig;
   } catch (error) {
     console.error('Error loading setup.json:', error.message);
@@ -23,6 +27,46 @@ export async function loadSetupConfig() {
   }
 }
 
+/**
+ * Validates critical config fields and warns if missing or invalid
+ */
+function validateConfigSchema(config) {
+  const warnings = [];
+
+  // Validate fileFiltering section
+  if (!config.fileFiltering) {
+    warnings.push('Missing "fileFiltering" section');
+  } else {
+    if (!Array.isArray(config.fileFiltering.filesToIgnore)) {
+      warnings.push('"fileFiltering.filesToIgnore" must be an array');
+    }
+    if (!Array.isArray(config.fileFiltering.dirsToIgnore)) {
+      warnings.push('"fileFiltering.dirsToIgnore" must be an array');
+    }
+  }
+
+  // Validate aiInstructions section
+  if (!config.aiInstructions) {
+    warnings.push('Missing "aiInstructions" section');
+  }
+
+  // Legacy support
+  if (!config.filesToIgnore || !Array.isArray(config.filesToIgnore)) {
+    warnings.push('filesToIgnore missing or not an array - using defaults');
+    config.filesToIgnore = DEFAULT_CONFIG.filesToIgnore;
+  }
+  if (!config.dirsToIgnore || !Array.isArray(config.dirsToIgnore)) {
+    warnings.push('dirsToIgnore missing or not an array - using defaults');
+    config.dirsToIgnore = DEFAULT_CONFIG.dirsToIgnore;
+  }
+
+  if (warnings.length > 0) {
+    console.warn('\n⚠️ Config Validation Warnings:');
+    warnings.forEach(w => console.warn(`   - ${w}`));
+    console.warn('   (Falling back to defaults for missing values where possible)\n');
+  }
+}
+
 /**
  * Loads and merges all profiles (local-first).
  */

package/src/core/skeletonizer.js

@@ -0,0 +1,201 @@
+import { parse } from '@babel/parser';
+import _traverse from '@babel/traverse';
+const traverse = _traverse.default || _traverse;
+import _generate from '@babel/generator';
+const generate = _generate.default || _generate;
+
+// Lazy-load tree-sitter to avoid breaking when native bindings are unavailable
+let Parser = null;
+let Python = null;
+let Java = null;
+let Kotlin = null;
+let C = null;
+let Rust = null;
+let Go = null;
+
+async function loadTreeSitter() {
+    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;
+    }
+}
+
+// Initialize parsers map (will be populated lazily)
+const languages = {
+    '.py': () => Python,
+    '.java': () => Java,
+    '.kt': () => Kotlin,
+    '.c': () => C,
+    '.h': () => C,
+    '.cpp': () => C,
+    '.hpp': () => C,
+    '.rs': () => Rust,
+    '.go': () => Go
+};
+
+/**
+ * Strips implementation details from code.
+ * @param {string} content - Full file content
+ * @param {string} filePath - File path to determine language
+ * @returns {Promise<string>} - Skeletonized code
+ */
+export async function skeletonize(content, filePath) {
+    if (!content) return content;
+
+    // 1. JS/TS Strategy (Babel is better for JS ecosystem)
+    if (/\.(js|jsx|ts|tsx|mjs|cjs)$/.test(filePath)) {
+        return skeletonizeJs(content);
+    }
+
+    // 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();
+        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 content; // Fallback: return original content if tree-sitter unavailable
+    }
+
+    // 3. Fallback (Return as is)
+    return content;
+}
+
+function skeletonizeJs(content) {
+    try {
+        const ast = parse(content, {
+            sourceType: 'module',
+            plugins: ['typescript', 'jsx', 'decorators-legacy'],
+            errorRecovery: true
+        });
+
+        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 = [];
+                    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 = leadingComments.length > 0
+                        ? leadingComments
+                        : [{ type: 'CommentBlock', value: ' ... ' }];
+                }
+            }
+        });
+
+        const output = generate(ast, {}, content);
+        return output.code;
+    } catch (e) {
+        return content + '\n// [Skeleton parse error]';
+    }
+}
+
+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
+        const bodyTypes = ['block', 'function_body', 'compound_statement'];
+        const replacements = [];
+
+        const visit = (node) => {
+            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) {
+                let bodyNode = null;
+                for (let i = 0; i < node.childCount; i++) {
+                    const child = node.child(i);
+                    if (bodyTypes.includes(child.type)) {
+                        bodyNode = child;
+                        break;
+                    }
+                }
+
+                if (bodyNode) {
+                    replacements.push({
+                        start: bodyNode.startIndex,
+                        end: bodyNode.endIndex,
+                        text: replacementText
+                    });
+                    return;
+                }
+            }
+
+            for (let i = 0; i < node.childCount; i++) {
+                visit(node.child(i));
+            }
+        };
+
+        visit(tree.rootNode);
+        replacements.sort((a, b) => b.start - a.start);
+
+        let currentContent = content;
+        for (const rep of replacements) {
+            currentContent = currentContent.substring(0, rep.start) + rep.text + currentContent.substring(rep.end);
+        }
+
+        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.